public abstract class CFacade
extends java.lang.Object
CFacade
is the base class of all complex types
(structs).
A facade derived from this class, provides a type safe interface to access (get/set) data in native memory (associated block). This class holds the reference on the associated memory region in a block of a blender file and provides methods to access it as well as helper methods to deal with type casts etc..
Since a facade is just a view on data, its life cycle is not
synchronised with the life cycle of the associated data. That means,
if the facade is garbage collected, the associated data in the block
will still remain in the file. To understand how to remove the data
from the file refer to BlenderFile
and BlockTable
.
Derived classes of CFacade which represent actual facades on struct instances in a blender file, provide getter and setter methods to access member variables of the struct in the associated block, but do not contain the member variables itself.
Every CFacade which represents a struct, contains descriptors for
each of its member variables. Member variable descriptors are used
to identify member variables for example in __io__addressof(long[])
and they are used to provide javadoc documentation for the member variable.
Member variable descriptors always start with the prefix __DNA__FIELD__
followed by the name of the member variable.
Modifier and Type | Field and Description |
---|---|
protected long |
__io__address
Address of the data for this instance in an existing block.
|
protected int |
__io__arch_index
The architecure index is used internally to determine the position
of a struct member variable from its descriptor, in respect to the
encoding of the underlying block.
|
protected Block |
__io__block
Block, which contains the data of the instance.
|
protected BlockTable |
__io__blockTable
Block table which contains the block with the data of
the associated instance.
|
protected int |
__io__pointersize
This is the address width used by the encoding of the underlying data.
|
Modifier | Constructor and Description |
---|---|
protected |
CFacade(CFacade other,
long targetAddress)
Copy constructor, which assigns the instantiated facade to a
another address.
|
protected |
CFacade(long __address,
Block block,
BlockTable __blockTable)
Common constructor for a facade on an existing instance of a
DNA struct, a pointer or an array.
|
Modifier and Type | Method and Description |
---|---|
CPointer<java.lang.Object> |
__io__addressof(long[] fieldDescriptor)
This method creates a void pointer on the field identified by
'fieldDescriptor' of the struct represented by the facade
(see static fields __DNA__FIELD__<fieldname> in the facades).
|
static <T extends CFacade> |
__io__addressof(T object)
This method creates a pointer on the given instance (object).
|
protected boolean |
__io__equals(CFacade facade,
long address)
Tests whether the facade, this method was called on, references the given address in the same file as the given facade.
|
protected void |
__io__generic__copy(CFacade source)
This method does a highlevel copy of the given source to this object.
|
protected static void |
__io__generic__copy(CFacade target,
CFacade source)
Does a high-level copy (meber by member) from source to target.
|
static boolean |
__io__instanceof(CFacade object,
java.lang.Class<?> clazz)
Tests whether the given object is an instance of class clazz
or some subclass of class clazz.
|
protected static void |
__io__native__copy(Block targetBlock,
long targetAddress,
CFacade source)
This method performs a low level copy of the given object to
the given target address in the target block.
|
static CFacade |
__io__newInstance(java.lang.Class<? extends CFacade> type,
long address,
Block block,
BlockTable blockTable)
Creates a new facade instance of the given type.
|
protected boolean |
__io__same__encoding(CFacade facadeA,
CFacade facadeB)
Tests whether the underlying data blocks of both facades use the
same encoding (byte order and address length).
|
long |
__io__sizeof(java.lang.Class<?> ctype)
This method returns the size of the C type which corresponds
to the given Java type according to the type mapping of Java Blend.
|
static long |
__io__sizeof(java.lang.Class<?> ctype,
int addressWidth)
This method returns the size of the C type which corresponds
to the given Java type according to the type mapping of Java Blend.
|
static boolean |
__io__subclassof(java.lang.Class<?> type,
java.lang.Class<?> superType)
Tests whether the given type is a subclass of superType.
|
protected long __io__address
protected BlockTable __io__blockTable
protected Block __io__block
protected int __io__arch_index
protected int __io__pointersize
protected CFacade(long __address, Block block, BlockTable __blockTable)
__address
- Start address of the instance.__block
- The block which contains the address.__blockTable
- Block table, which contains the block.protected CFacade(CFacade other, long targetAddress)
other
- Instance to be copied.targetAddress
- Start address of the instance.public long __io__sizeof(java.lang.Class<?> ctype)
ctype
- The type which size is requested. Any kind of type
representing a C data type, such as any of the sub-classes
of CFacade, a CArrayFacade, CPointer or any of the primitive types (long, int, char ...).public static long __io__sizeof(java.lang.Class<?> ctype, int addressWidth)
ctype
- Any kind of type representing a C data type, such as any of the sub-classes of CFacade, a CArrayFacade, CPointer or any of the primitive types (long, int, char ...).addressWidth
- Size of a pointer in bytes, based on architecture specifications (i.e. 4/8 bytes)public static <T extends CFacade> CPointer<T> __io__addressof(T object)
object
- The instance whose pointer is requested.public CPointer<java.lang.Object> __io__addressof(long[] fieldDescriptor)
The returned pointer has to be casted (by means of CPointer.cast(Class)
and similar methods)
in order to use pointer arithmetics on it. We had the choice
here to either carry all type information for every field over
to the runtime model (and waste a lot of performance) or deal
with the risk of having void pointers. Since it is very rare
that pointers on fields are needed, we decided to go with this approach.
This method is highly dangerous because we do not check, whether the field descriptor actually belongs to the facade and it is directly interpreted as offset to the structs base address.
fieldDescriptor
- The __DNA__FIELD__<fieldname> descriptor
of the field, who's address will be determined.public static boolean __io__subclassof(java.lang.Class<?> type, java.lang.Class<?> superType)
type
- type to be tested.superType
- expected base class of the given type.public static boolean __io__instanceof(CFacade object, java.lang.Class<?> clazz)
type
- type to be tested.superType
- expected base class of the given type.public static CFacade __io__newInstance(java.lang.Class<? extends CFacade> type, long address, Block block, BlockTable blockTable) throws java.lang.InstantiationException, java.lang.IllegalAccessException, java.lang.IllegalArgumentException, java.lang.reflect.InvocationTargetException, java.lang.NoSuchMethodException, java.lang.SecurityException
type
- The type of facade to instantiate.address
- The associated address for the instantiated facade.block
- The block, which contains the address.blockTable
- the global block map of the associated file.java.lang.InstantiationException
java.lang.IllegalAccessException
java.lang.IllegalArgumentException
java.lang.reflect.InvocationTargetException
java.lang.NoSuchMethodException
java.lang.SecurityException
protected boolean __io__equals(CFacade facade, long address)
facade
- address
- protected static void __io__native__copy(Block targetBlock, long targetAddress, CFacade source) throws java.io.IOException
This method performs a low level copy of the given object to the given target address in the target block. This requires, that the target
targetBlock
- Block, which will receive the written data.targetAddress
- Target address where the data will be written to. This address has to be
in range of the given target block.source
- facade with the data to be copied to the given address.java.io.IOException
protected void __io__generic__copy(CFacade source) throws java.io.IOException
The method is used in case a lowlevel copy (see __io__native__copy(Block, long, CFacade)
)
is not possible due to different encodings of the underlying blocks
(see __io__same__encoding(CFacade, CFacade)
.
The method is overridden by CArrayFacade.
source
- An object derived from CFacade or CArrayFacade, but not CPointer.nla_tracks
- java.io.IOException
protected static void __io__generic__copy(CFacade target, CFacade source) throws java.io.IOException
target.__io__generic__copy(source)
.target
- Facade, which gets its data overriden with the values of source.source
- Facade, which data gets copied to target.java.io.IOException
#__io__generic__copy(CFacade)}