T
- Target type of the pointer.public class CPointer<T> extends CFacade
int** pint
is
said to be a pointer on a pointer of type int
.
Thus, the target type is int
and the level of
indirection is 2
.T
.
Thus an object of CPointer<CPointer<Integer>>
is the equivalent representation of int**
.
Objects of CPointer are immutable, that means you cannot change
its address. Thus, CPointer objects behave like String's in Java:
Every 'modification' creates a copy of the object with that modification,
while the original objects stays unmodified. This has disadvantages in
performance, if you heavily depend on pointer arithmetics. Hence, there
is another class called CPointerMutable
which allows in-place
modification of pointers (similar to the relationship between String
and StringBuffer).
To change the value of a pointer, which is stored in a block, you have to use the setter method of the facade, array or pointer associated with the block.
BlenderObject newObject = ..; // instantiated a new object ID id = object.getId(); // get id of previous object // get a pointer on the new object CPointer<BlenderObject> pNewObj = newObject.__io__addressof(); id.setNext(pNewObj); // set id.next to point to new obj
In the last line, the new address was written to the underlying block associated with the previous object.
In case you do not have a facade on the data in the block, you will have either an array of pointers or a pointer of pointer. The following example demonstrates it for an int* stored in a block.
// We have a pointer refering to a pointer stored in a block CPointer<CPointer<Integer>> ppint = ..; // And we have received a new address for that pointer from elsewhere CPointer<Integer> pint = ..; // To assign the new address to the pointer in the block we use the setter. ppint.set(pint);
get()
) and basic algebra
(see #add(int)
). For advanced pointer arithmetics see
CPointerMutable
.
get()
returns that objects (Java) value.
CFacade
. That means, you get
access by reference: all modifications to the objects data will be
reflected in the memory backing the object. This applies also to
CArrayFacade
objects but it applies not to instances of
CPointer
itself (see below).
CPointer
is a reference but treated as a scalar.
That means, if you receive a pointer from a method (e.g. from a facade, array
or another pointer) than it is a copy - disconnected from its own memory location. Any
modification to the pointer is not reflected in its original memory location.
To assign a new address to its original memory location, you have to use the
set method of the object, which provided you the pointer.CPointer next = link.getNext(); // retrieve address Link anotherLink = .. ; // link we received elsewhere link.setNext(anotherLink.__io__addressof()); // assign new address to link.next
See also CPointerMutable
and CFacade#__io__addressof()
.
Typical pointer arithmetics are incrementing and decrementing the address
by the size of the target type. This actually reflects the same
functionality provided by array types. CPointer provides different ways
to achieve this functionality: Conversion to an array (see Section
Array Conversion below) and the method plus(int)
.
Array conversion provides you either a Java array type or an iterable CArrayFacade
which is pretty straight forward to handle. The method plus(int)
increments
the address by the given increment multiplied by the size of the pointer
target type. Thus you can use the pointer like an iterator as in the example below.
// iterating over a null terminated list of materials for (CPointerpmat = .. ; !pmat.isNull(); // null check pmat = pmat.plus(+1)) // inc address by sizeof(Material) { Material mat = pmat.get(); }
Please note, that the result of plus(int)
has to be assigned
to pmat, since CPointer
is immutable and plus(int)
does
not change the address of the pointer itself (see also CPointerMutable
).
This functionality of course requires that the pointer is of the correct
type (same as in C). Pointer arithmetics to a void*
(which is mapped to CPointer<Object>
are permitted.
Thus, you have to cast the pointer to the correct target type first
(see Section Type Casts below).
cast(Class)
and
cast(Class[])
. Both take a parameter which describes the new
target type of the casted pointer. Since template parameters
are not available at runtime, type casts of pointers with multiple
indirections and pointers on arrays require you to provide even the
types of the targeted types. For example, if you have a pointer
on a pointer of type Link, than the first pointer is of type pointer
on pointer and the second pointer is of type pointer on Link.
CPointer<CPointer<Link>> pplink = .. ; CPointer<CPointer<Scene>> ppscene; ppscene = pplink.cast(new Class[]{Pointer.class, Scene.class}; CPointer<Scene> pscene = ppscene.get(); Scene scene = pscene.get();
This can get confusing but you will need to cast pointers with multiple levels of indirection rather rare or never.
The method toArray(int)
returns an array with copies
of the values received from the address the pointer points to.
Since it is not possible to use scalar types (such as int, double etc.)
as template parameter, there are several different flavours of
toArray(byte[], int, int)
and toByteArray(int)
for all scalar types. Please note, that there are two special methods
for int64, since long can refer to integer of 4 or 8 byte depending
on the data received from blender file. Refer to the originating
facade, you received the pointer from, to determine its actual type.
Modifier and Type | Field and Description |
---|---|
protected long |
targetSize |
protected java.lang.Class<?>[] |
targetTypeList
Type of the target the pointer is able to address.
|
__io__address, __io__arch_index, __io__block, __io__blockTable, __io__pointersize
Constructor and Description |
---|
CPointer(CPointer<T> other)
Copy constructor.
|
CPointer(long targetAddress,
java.lang.Class<?>[] targetTypes,
Block block,
BlockTable memory)
Common constructor for pointers.
|
Modifier and Type | Method and Description |
---|---|
protected T |
__get(long address) |
protected void |
__set(long address,
T value)
Copies the given value to the given address.
|
CArrayFacade<T> |
cast(CArrayFacade<T> type)
Type cast a pointer to an array.
|
<U> CPointer<U> |
cast(java.lang.Class<?>[] types)
Type cast for pointers with multiple levels of indirection
(pointer on pointer).
|
<U> CPointer<U> |
cast(java.lang.Class<U> type)
Type cast for pointers with just one indirection.
|
boolean |
equals(java.lang.Object obj)
XXX: test whether the pointer references the same file?
This method provides pointer comparison functionality.
|
void |
fromArray(byte[] data)
Copyies all elements from from the given 'data' array
to the memory referenced by this pointer.
|
void |
fromArray(byte[] data,
int off,
int len)
Copies 'len' elements from from the given 'data' array starting at index 'off'
to the memory referenced by this pointer.
|
void |
fromArray(double[] data)
Copyies all elements from from the given 'data' array
to the memory referenced by this pointer.
|
void |
fromArray(double[] data,
int off,
int len)
Copyies 'len' elements from from the given 'data' array starting at index 'off'
to the memory referenced by this pointer.
|
void |
fromArray(float[] data)
Copyies all elements from from the given 'data' array
to the memory referenced by this pointer.
|
void |
fromArray(float[] data,
int off,
int len)
Copyies 'len' elements from from the given 'data' array starting at index 'off'
to the memory referenced by this pointer.
|
void |
fromArray(int[] data)
Copyies all elements from from the given 'data' array
to the memory referenced by this pointer.
|
void |
fromArray(int[] data,
int off,
int len)
Copyies 'len' elements from from the given 'data' array starting at index 'off'
to the memory referenced by this pointer.
|
void |
fromArray(long[] data)
Copyies all elements from from the given 'data' array
to the memory referenced by this pointer.
|
void |
fromArray(long[] data,
int off,
int len)
Copyies 'len' elements from from the given 'data' array starting at index 'off'
to the memory referenced by this pointer.
|
void |
fromArray(short[] data)
Copyies all elements from from the given 'data' array
to the memory referenced by this pointer.
|
void |
fromArray(short[] data,
int off,
int len)
Copyies 'len' elements from from the given 'data' array starting at index 'off'
to the memory referenced by this pointer.
|
void |
fromInt64Array(long[] data)
Copyies all elements from from the given 'data' array
to the memory referenced by this pointer.
|
void |
fromInt64Array(long[] data,
int off,
int len)
Copyies 'len' elements from from the given 'data' array starting at index 'off'
to the memory referenced by this pointer.
|
T |
get()
This method returns the value, the pointer points to.
|
long |
getAddress()
This returns the address this pointer points to.
|
protected T |
getCFacade(long targetAddress)
Returns a facade or pointer on the given targetAddress, depending on the
type of this pointer.
|
protected T |
getScalar(long address)
Returns a copy of the scalar from memory referenced by the given address.
|
int |
hashCode()
XXX: consider file, which contains the data?
|
boolean |
isNull()
Checks whether the address of the pointer equals null.
|
protected boolean |
isPrimitive(java.lang.Class<?> type)
Determines if the given type is a primitive type (scalar).
|
boolean |
isValid()
Tells whether the pointer points to actual data or in
a region of memory, which does not exist.
|
CPointerMutable<T> |
mutable()
Creates a mutable pointer which allows to change its address in-place.
|
CPointer<T> |
plus(int value)
plus(int) returns new instance with the result
of the addition. |
void |
set(T value)
Sets the value the pointer points to.
|
protected void |
setScalar(long address,
T elem) |
byte[] |
toArray(byte[] data,
int off,
int len)
Copies 'len' bytes from the memory referenced by this pointer
to the given 'data' array starting at index 'off'.
|
double[] |
toArray(double[] data,
int off,
int len)
Copyies 'len' elements from the memory referenced by this pointer
to the given 'data' array starting at index 'off'.
|
float[] |
toArray(float[] data,
int off,
int len)
Copyies 'len' elements from the memory referenced by this pointer
to the given 'data' array starting at index 'off'.
|
T[] |
toArray(int length)
Converts the data referenced by the pointer into a Java array
of the given length.
|
int[] |
toArray(int[] data,
int off,
int len)
Copyies 'len' elements from the memory referenced by this pointer
to the given 'data' array starting at index 'off'.
|
long[] |
toArray(long[] data,
int off,
int len)
Copyies 'len' elements from the memory referenced by this pointer
to the given 'data' array starting at index 'off'.
|
short[] |
toArray(short[] data,
int off,
int len)
Copyies 'len' elements from the memory referenced by this pointer
to the given 'data' array starting at index 'off'.
|
long[] |
toArrayInt64(long[] data,
int off,
int len)
Copyies 'len' elements from the memory referenced by this pointer
to the given 'data' array starting at index 'off'.
|
byte[] |
toByteArray(int len)
Converts the data referenced by the pointer into a Java array
of the given length.
|
CArrayFacade<T> |
toCArrayFacade(int len)
Converts the data referenced by the pointer into an array with
a CArrayFacade of the given length.
|
double[] |
toDoubleArray(int len)
Converts the data referenced by the pointer into a Java array
of the given length.
|
float[] |
toFloatArray(int len)
Converts the data referenced by the pointer into a Java array
of the given length.
|
long[] |
toInt64Array(int len)
Converts the data referenced by the pointer into a Java array
of the given length.
|
int[] |
toIntArray(int len)
Converts the data referenced by the pointer into a Java array
of the given length.
|
long[] |
toLongArray(int len)
Converts the data referenced by the pointer into a Java array
of the given length.
|
short[] |
toShortArray(int len)
Converts the data referenced by the pointer into a Java array
of the given length.
|
__io__addressof, __io__addressof, __io__equals, __io__generic__copy, __io__generic__copy, __io__instanceof, __io__native__copy, __io__newInstance, __io__same__encoding, __io__sizeof, __io__sizeof, __io__subclassof
protected java.lang.Class<?>[] targetTypeList
protected long targetSize
public CPointer(CPointer<T> other)
other
- Pointer to be copied.public CPointer(long targetAddress, java.lang.Class<?>[] targetTypes, Block block, BlockTable memory)
targetAddress
- Address the pointer will point to.targetTypes
- Type of the pointer (please read class documentation)block
- Block, which contains the targetAddress.memory
- Associated block table, which contains memory for the targetAddress.public T get() throws java.io.IOException
isNull()
before calling get()
.
java.io.IOException
protected T __get(long address) throws java.io.IOException
java.io.IOException
public void set(T value) throws java.io.IOException
value
- Value to be copied to the address this pointer points to.java.io.IOException
protected void __set(long address, T value) throws java.io.IOException
set(Object)
.address
- to write the value to.value
- to be copied.java.io.IOException
public long getAddress() throws java.io.IOException
java.io.IOException
- address the pointer points topublic boolean isNull()
public boolean isValid()
isNull()
and it is more expensive performance wise.public <U> CPointer<U> cast(java.lang.Class<U> type)
Pointer<ListBase> p; .. Pointer <Scene> pscene = p.cast(Scene.class);
type
- public <U> CPointer<U> cast(java.lang.Class<?>[] types)
CPointer<CPointer<ListBase>> p; .. CPointer<CPointer<Scene>> pscene = p.cast(new Class>[]{CPointer.class, Scene.class});
cast(Class)
since you can do even more nasty stuff.type
- public CArrayFacade<T> cast(CArrayFacade<T> type) throws java.io.IOException
p instanceof CArrayFacade) == true
)).
The parameter is needed only to differentiate it from other
cast
methods. Thus, you can use it like this:
CPointer<Float> p = null; CArrayFacade<Float> array = null; array = p.cast(array);To create a new array facade for a given pointer you have to use the method
toCArrayFacade(int)
.type
- java.io.IOException
public T[] toArray(int length) throws java.io.IOException
length
- of the new Java array instance.isNull()
).java.io.IOException
public CArrayFacade<T> toCArrayFacade(int len)
length
- java.io.IOException
public byte[] toArray(byte[] data, int off, int len) throws java.io.IOException
data
- Array, to copy the data to.off
- Start index in the data array.len
- Amount of elements to be copied to data.java.io.IOException
public void fromArray(byte[] data, int off, int len) throws java.io.IOException
data
- Array, to copy the data from.off
- Start index in the data array.len
- Amount of elements to be copied from 'data'.java.io.IOException
public byte[] toByteArray(int len) throws java.io.IOException
length
- of the new Java array instance.java.io.IOException
public void fromArray(byte[] data) throws java.io.IOException
data
- Array, to copy the data from.java.io.IOException
public short[] toArray(short[] data, int off, int len) throws java.io.IOException
data
- Array, to copy the data to.off
- Start index in the data array.len
- Amount of elements to be copied to data.java.io.IOException
public void fromArray(short[] data, int off, int len) throws java.io.IOException
data
- Array, to copy the data from.off
- Start index in the data array.len
- Amount of elements to be copied from 'data'.java.io.IOException
public short[] toShortArray(int len) throws java.io.IOException
length
- of the new Java array instance.java.io.IOException
public void fromArray(short[] data) throws java.io.IOException
data
- Array, to copy the data from.java.io.IOException
public int[] toArray(int[] data, int off, int len) throws java.io.IOException
data
- Array, to copy the data to.off
- Start index in the data array.len
- Amount of elements to be copied to data.java.io.IOException
public int[] toIntArray(int len) throws java.io.IOException
length
- of the new Java array instance.java.io.IOException
public void fromArray(int[] data, int off, int len) throws java.io.IOException
data
- Array, to copy the data from.off
- Start index in the data array.len
- Amount of elements to be copied from 'data'.java.io.IOException
public void fromArray(int[] data) throws java.io.IOException
data
- Array, to copy the data from.java.io.IOException
public long[] toArray(long[] data, int off, int len) throws java.io.IOException
data
- Array, to copy the data to.off
- Start index in the data array.len
- Amount of elements to be copied to data.java.io.IOException
public long[] toLongArray(int len) throws java.io.IOException
length
- of the new Java array instance.java.io.IOException
public void fromArray(long[] data, int off, int len) throws java.io.IOException
data
- Array, to copy the data from.off
- Start index in the data array.len
- Amount of elements to be copied from 'data'.java.io.IOException
public void fromArray(long[] data) throws java.io.IOException
data
- Array, to copy the data from.java.io.IOException
public long[] toArrayInt64(long[] data, int off, int len) throws java.io.IOException
data
- Array, to copy the data to.off
- Start index in the data array.len
- Amount of elements to be copied to data.java.io.IOException
public long[] toInt64Array(int len) throws java.io.IOException
length
- of the new Java array instance.java.io.IOException
public void fromInt64Array(long[] data, int off, int len) throws java.io.IOException
data
- Array, to copy the data from.off
- Start index in the data array.len
- Amount of elements to be copied from 'data'.java.io.IOException
public void fromInt64Array(long[] data) throws java.io.IOException
data
- Array, to copy the data from.java.io.IOException
public float[] toArray(float[] data, int off, int len) throws java.io.IOException
data
- Array, to copy the data to.off
- Start index in the data array.len
- Amount of elements to be copied to data.java.io.IOException
public float[] toFloatArray(int len) throws java.io.IOException
length
- of the new Java array instance.java.io.IOException
public void fromArray(float[] data, int off, int len) throws java.io.IOException
data
- Array, to copy the data from.off
- Start index in the data array.len
- Amount of elements to be copied from 'data'.java.io.IOException
public void fromArray(float[] data) throws java.io.IOException
data
- Array, to copy the data from.java.io.IOException
public double[] toArray(double[] data, int off, int len) throws java.io.IOException
data
- Array, to copy the data to.off
- Start index in the data array.len
- Amount of elements to be copied to data.java.io.IOException
public double[] toDoubleArray(int len) throws java.io.IOException
length
- of the new Java array instance.java.io.IOException
public void fromArray(double[] data, int off, int len) throws java.io.IOException
data
- Array, to copy the data from.off
- Start index in the data array.len
- Amount of elements to be copied from 'data'.java.io.IOException
public void fromArray(double[] data) throws java.io.IOException
data
- Array, to copy the data from.java.io.IOException
public CPointerMutable<T> mutable()
CPointerMutable
public CPointer<T> plus(int value) throws java.io.IOException
plus(int)
returns new instance with the result
of the addition.
Allows (almost) equivalent handling as operator.
int *p, *a; a = p = .. ; a = (p+1)+1;same as
CPointerMutablewhere the post conditionp, a; p = a = .. ; p = (p.plus(1)).plus(1);
post condition: (p != a)holds.
value
- java.io.IOException
public boolean equals(java.lang.Object obj)
CFacade
including pointers, arrays and iterators of both.equals
in class java.lang.Object
obj
- public int hashCode()
hashCode
in class java.lang.Object
protected boolean isPrimitive(java.lang.Class<?> type)
type
- protected T getCFacade(long targetAddress) throws java.io.IOException
CFacade
).targetAddress
- Addressjava.io.IOException
protected T getScalar(long address) throws java.io.IOException
address
- java.io.IOException
protected void setScalar(long address, T elem) throws java.io.IOException
java.io.IOException