** implies *native ownership* for a *Pointer* referenced *native* memory
if the expression is constant. Otherwise the *native* memory has *java ownership*.
See [ReturnedArrayLength Setting](#returnedarraylength-symbol-expression) above.
* Utilizing a *flexible* *elemCount* via **ReturnedArrayLength getValElements()** renders us unable to determine ownership
of pointer referenced *native* memory segment and hence renders ownership *mixed or ambiguous*, [see \[5\]](#signature-const-int32_t--customsize-ambiguous-java-owned). This is due to the fact, that native code may allocate memory and writes its *elemCount* into the designated field *valElements*. In such cases, the user being aware of the underlying API shall utilize `setVal(..)` and `releaseVal()` with care.
* To release native memory with *java ownership*, i.e. a native ByteBuffer, `releaseVal()` can be used.
### Struct Setter Pseudo-Code
#### Overview
In general we have the following few cases
* Array owned by parent struct itself
* `int32_t val[10]`
* Setter of `val` within range, keeping memory
* `const int32_t val[10]`
* No setter allowed due to const value
* Referenced Memory (array) owned by Java
* `int32_t* val`
* Setter within range, keeping memory, or replacing memory
* `const int32_t* val`
* Setter replacing memory, since memory is non-const but value is const
* Referenced Memory (array) owned by Native Code due to set *ConstElemCount*
* `int32_t* val`
* Setter of `val` within range, keeping memory owned by native code
* `const int32_t* val`
* No setter allowed, since memory is owned by native code and value is const
#### Implemented Pseudo Code
* *ImmutableAccess*: Drops setter, immutable
* *Pointer* & *ConstValue* & *ConstElemCount*: Drops setter, native ownership on const-value
* *Array* & *ConstValue* : Drops setter, const-value array
* *Primitive*
* Single aggregated instance
* Store value within *native* memory
* *Array* | *Pointer*
* *MaxOneElement*
* *Pointer*
* *ConstValue*: Allocate new memory and store value
* *VariaValue*:
* *ConstElemCount*: Reuse *native* memory and store value with matching *elemCount 1*, otherwise Exception
* *VariaElemCount*: Reuse *native* memory and store value with matching *elemCount 1*, otherwise allocates new memory (had *elemCount 0*)
* *Array* & *VariaValue*: Reuse *native* memory and store value (has const *elemCount 1*)
* *else*: *SKIP* setter for const single-primitive array
* *AnyElementCount*
* *String* & *isByteBuffer* & *Pointer*
* *ConstElemCount*: Reuse *native* memory and store UTF-8 bytes with EOS with matching *elemCount*, otherwise Exception
* *StringOnly*: End, no more setter for this field, otherwise continue
* *VariaElemCount*: Allocate new *native* memory and store UTF-8 bytes with EOS
* *StringOnly*: End, no more setter for this field, otherwise continue
* *ConstValue*
* *Pointer*
* *VariaElemCount*: Allocates new *native* memory and store value
* *else*: *SKIP* setter for const primitive array
* *Array* | *ConstElemCount*: Reuse *native* memory and store value with <= *elemCount*, otherwise Exception
* *Pointer* & *VariaElemCount*: Reuse *native* memory and store value with <= *elemCount*, otherwise allocate new *native* memory
* *Struct* ...
### Struct Java Signature Table
Please find below signature table as generated by the *C Declaration* including its *C Modifier*,
e.g. `const` for constant, `[const]` for const and non-const and `empty` for non-const (variable).
Further, the *GlueGen Setting* (see above) impacts the code generation as well.
Below table demonstrates *primitive* types being mapped within a `struct` named `TK_Struct`.
A similar mapping is produced for `struct` types, i.e. *compounds*.
| C Mod | C Declaration | Java Setter | Java Getter | GlueGen Setting | Ownership | Remarks |
|:--------|:--------------|:-----------------------------------------------------------------|:--------------------------------------|:-----------------------------------------------|:----------|:----------|
| | | | static boolean usesNativeCode() | | | Java, static,
*true* if using native code |
| | | | static int size() | | | Java, static,
native size in bytes |
| | | | static TK_Struct create() | | | Java, static ctor |
| | | | static TK_Struct create(ByteBuffer) | | | Java, static ctor
w/ existing ByteBuffer |
| | | | static TK_Struct derefPointer(long addr) | | | Java, static ctor
dereferencing ByteBuffer
at native address of size() |
| | | | ByteBuffer getBuffer() | | | Java,
underlying ByteBuffer |
| | | | long getDirectBufferAddress() | | | Java, native address
of underlying getBuffer() |
| | int32_t val | setVal(int v) | int getVal() | | Parent | |
| const | int32_t val | *none* | int getVal() | | Parent | Read only |
| | int32_t val | *none* | int getVal() | **ImmutableAccess** | Parent | Read only |
| [const] | int32_t* val | setVal(int v) \[[1](#signature-int32_t--maxoneelement-java-owned)\]\[[2](#signature-const-int32_t--maxoneelement-java-owned)\]
releaseVal() | int getVal()
boolean isValNull()
int getValElemCount() | **MaxOneElement** | Java | Starts w/ null elements,
max 1 element |
| const | int32_t* val | *none* | int getVal()
boolean isValNull()
static int getValElemCount() | **ReturnedArrayLength 1** | Native | Const element count 1 |
| | int32_t* val | setVal(int v) | int getVal()
boolean isValNull()
static int getValElemCount() | **ReturnedArrayLength 1** | Native | Const element count 1 | |
| | int32_t val[3]| setVal(int[] src, int srcPos, int destPos, int len) \[[3](#signature-int32_t3-constelemcount-3-parent-owned)\] | IntBuffer getVal()
int[] getVal(int srcPos, int[] dest, int destPos, int len) | | Parent | Reuses parent memory,
fixed size. |
| const | int32_t val[3]| *none* | IntBuffer getVal()
int[] getVal(int srcPos, int[] dest, int destPos, int len) | | Parent | Read only |
| const | int32_t* val | *none* | IntBuffer getVal()
int[] getVal(int srcPos, int[] dest, int destPos, int len)
boolean isValNull()
static int getValElemCount() | **ReturnedArrayLength 3** | Native | Read only
Const element count 3 |
| | int32_t* val | setVal(int[] src, int srcPos, int destPos, int len) \[[4](#signature-int32_t--constelemcount-3-natively-owned)\] | IntBuffer getVal()
int[] getVal(int srcPos, int[] dest, int destPos, int len)
boolean isValNull()
static int getValElemCount() | **ReturnedArrayLength 3** | Native | Const element count 3.
Reuses native memory,
fixed size. |
| | int32_t* val | setVal(boolean subset, int[] src, int srcPos, int destPos, int len) \[[5](#signature-int32_t--freesize-java-owned)\]
releaseVal() | IntBuffer getVal()
int[] getVal(int srcPos, int[] dest, int destPos, int len)
boolean isValNull()
int getValElemCount() | | Java | Starts w/ null elements.
Reuses or replaces Java memory,
variable size. |
| const | int32_t* val | setVal(int[] src, int srcPos, int len) \[[6](#signature-const-int32_t--freesize-java-owned)\]
releaseVal() | IntBuffer getVal()
int[] getVal(int srcPos, int[] dest, int destPos, int len)
boolean isValNull()
int getValElemCount() | | Java | Starts w/ null elements.
Replaces Java memory,
variable size. |
| | int32_t* val | setVal(boolean subset, int[] src, int srcPos, int destPos, int len) \[[7](#signature-int32_t--customsize-ambiguous-ownership)\]
releaseVal() | IntBuffer getVal()
int[] getVal(int srcPos, int[] dest, int destPos, int len)
boolean isValNull() | **ReturnedArrayLength getValCount()** | **Ambiguous** | Variable element count
using field *valCount*,
which has getter and setter |
| const | int32_t* val | setVal(int[] src, int srcPos, int len) \[[8](#signature-const-int32_t--customsize-ambiguous-ownership)\]
releaseVal() | IntBuffer getVal()
int[] getVal(int srcPos, int[] dest, int destPos, int len)
boolean isValNull() | **ReturnedArrayLength getValCount()** | **Ambiguous** | Variable element count
using field *valCount*,
which has getter and setter |
| [const] | char* name | setName(String srcVal)
releaseVal() | String getName()
boolean isNameNull()
int getNameElemCount() | **ReturnsStringOnly** | Java | String only, w/ EOS |
| [const] | char* name | setName(String srcVal)
setName(byte[] src, int srcPos, int destPos, int len)
releaseVal() | String getNameAsString()
ByteBuffer getName()
boolean isNameNull()
int getNameElemCount() | **ReturnsString** | Java | String and byte access, w/ EOS|
### Struct Java Signature Examples
#### Signature `int32_t *` MaxOneElement, Java owned
* `void com.jogamp.gluegen.test.junit.generation.TK_Field.setVariaInt32PointerMaxOneElemElemCount(int src)`
Setter for native field variaInt32PointerMaxOneElem, referencing a Java owned array with variable element count of 0 initial elements.
Maximum element count is 1.
Native Signature:
* field-type (PointerType) 'int32_t *' -> (int32_t) * , size [fixed false, lnx64 8], const[false], pointer*1
* referenced (IntType) typedef 'int32_t', size [fixed true, lnx64 4], const[false], int
Will reuse memory if existing, otherwise allocating memory.
#### Signature `const int32_t *` MaxOneElement, Java owned
* `TK_Field com.jogamp.gluegen.test.junit.generation.TK_Field.setConstInt32PointerMaxOneElem(int src)`
Setter for native field variaInt32PointerMaxOneElem, referencing a Java owned array with variable element count of 0 initial elements.
Maximum element count is 1.
Native Signature:
* field-type (PointerType) 'int32_t *' -> (const int32_t) * , size [fixed false, lnx64 8], const[false], pointer*1
* referenced (IntType) typedef 'int32_t', size [fixed true, lnx64 4], const[native, true], int
Always replaces memory due to `const` value modifier.
#### Signature `int32_t[3]` ConstElemCount 3, Parent owned
* `TK_Field com.jogamp.gluegen.test.junit.generation.TK_Field.setVariaInt32ArrayConstLen(int[] src, int srcPos, int destPos, int length)`
Setter for native field variaInt32ArrayConstLen, being an array with fixed element count of 3 elements.
Native Field Signature (ArrayType) 'int32_t *', size [fixed false, lnx64 12], const[false], array*1
Copies the given source elements into the respective field's existing memory.
Parameters:
* src the source array of elements
* srcPos starting element position within the source array with 'srcPos >= 0` && `srcPos + length <= src.length`, otherwise an IndexOutOfBoundsException is thrown
* destPos starting element position within the destination with 'destPos >= 0` && `destPos + length <= elemCount`, otherwise an exception is thrown
* length the element count to be copied with 'length >= 0` && `srcPos + length <= src.length` && `destPos + length <= elemCount`, otherwise an IndexOutOfBoundsException is thrown
Returns:
* this instance of chaining
#### Signature `int32_t *` ConstElemCount 3, Natively owned
* `TK_Field com.jogamp.gluegen.test.junit.generation.TK_Field.setVariaInt32PointerConstLen(int[] src, int srcPos, int destPos, int length)`
Setter for native field variaInt32PointerConstLen, referencing a natively owned array with fixed element count of 3 elements.
Native Signature:
* field-type (PointerType) 'int32_t *' -> (int32_t) * , size [fixed false, lnx64 8], const[false], pointer*1
* referenced (IntType) typedef 'int32_t', size [fixed true, lnx64 4], const[false], int
Copies the given source elements into the respective field's existing memory.
Parameters:
* src the source array of elements
* srcPos starting element position within the source array with 'srcPos >= 0` && `srcPos + length <= src.length`, otherwise an IndexOutOfBoundsException is thrown
* destPos starting element position within the destination with 'destPos >= 0` && `destPos + length <= elemCount`, otherwise an exception is thrown
* length the element count to be copied with 'length >= 0` && `srcPos + length <= src.length` && `destPos + length <= elemCount`, otherwise an IndexOutOfBoundsException is thrown
Returns:
* this instance of chaining
#### Signature `int32_t *` FreeSize, Java owned
* `TK_Field com.jogamp.gluegen.test.junit.generation.TK_Field.setVariaInt32PointerVariaLen(boolean subset, int[] src, int srcPos, int destPos, int length)`
Setter for native field variaInt32PointerVariaLen, referencing a Java owned array with variable element count of 0 initial elements.
Native Signature:
* field-type (PointerType) 'int32_t *' -> (int32_t) * , size [fixed false, lnx64 8], const[false], pointer*1
* referenced (IntType) typedef 'int32_t', size [fixed true, lnx64 4], const[false], int
Copies the given source elements into the respective field, either writing into the existing memory or creating a new memory and referencing it.
Parameters:
* subset if `true` keeps the underlying memory and only allows to set up to `elemCount` elements. Otherwise may replace the underlying memory if `destPos + length != elemCount`.
* src the source array of elements
* srcPos starting element position within the source array with 'srcPos >= 0` && `srcPos + length <= src.length`, otherwise an IndexOutOfBoundsException is thrown
* destPos starting element position within the destination with 'destPos >= 0`. If `subset == true`, `destPos + length <= elemCount` also must be be `true`. Otherwise an exception is thrown
* length the element count to be copied with 'length >= 0` && `srcPos + length <= src.length`, otherwise an IndexOutOfBoundsException is thrown
Returns:
* this instance of chaining
#### Signature `const int32_t *` FreeSize, Java owned
* `TK_Field com.jogamp.gluegen.test.junit.generation.TK_Field.setConstInt32PointerVariaLen(int[] src, int srcPos, int length)`
Setter for native field constInt32PointerVariaLen, referencing a Java owned array with variable element count of 0 initial elements.
Native Signature:
* field-type (PointerType) 'int32_t *' -> (const int32_t) * , size [fixed false, lnx64 8], const[false], pointer*1
* referenced (IntType) typedef 'int32_t', size [fixed true, lnx64 4], const[native, true], int
Replaces the respective field's memory with a new memory segment containing given source elements and referencing it.
Parameters:
* src the source array of elements
* srcPos starting element position within the source array with 'srcPos >= 0` && `srcPos + length <= src.length`, otherwise an IndexOutOfBoundsException is thrown
* length the element count to be copied with 'length >= 0` && `srcPos + length <= src.length`, otherwise an IndexOutOfBoundsException is thrown
Returns:
* this instance of chaining
#### Signature `int32_t *` CustomSize, Ambiguous ownership
* `TK_Field com.jogamp.gluegen.test.junit.generation.TK_Field.setVariaInt32PointerCustomLen(boolean subset, int[] src, int srcPos, int destPos, int length)`
Setter for native field variaInt32PointerCustomLen, referencing a mixed and ambigously owned (warning) array with variable element count of getVariaInt32PointerCustomLenElemCount() elements.
Native Signature:
* field-type (PointerType) 'int32_t *' -> (int32_t) * , size [fixed false, lnx64 8], const[false], pointer*1
* referenced (IntType) typedef 'int32_t', size [fixed true, lnx64 4], const[false], int
Copies the given source elements into the respective field, either writing into the existing memory or creating a new memory and referencing it.
Parameters:
* subset if `true` keeps the underlying memory and only allows to set up to `elemCount` elements. Otherwise may replace the underlying memory if `destPos + length != elemCount`.
* src the source array of elements
* srcPos starting element position within the source array with 'srcPos >= 0` && `srcPos + length <= src.length`, otherwise an IndexOutOfBoundsException is thrown
* destPos starting element position within the destination with 'destPos >= 0`. If `subset == true`, `destPos + length <= elemCount` also must be be `true`. Otherwise an exception is thrown
* length the element count to be copied with 'length >= 0` && `srcPos + length <= src.length`, otherwise an IndexOutOfBoundsException is thrown
Returns:
* this instance of chaining
#### Signature `const int32_t *` CustomSize, Ambiguous ownership
* `TK_Field com.jogamp.gluegen.test.junit.generation.TK_Field.setConstInt32PointerCustomLen(int[] src, int srcPos, int length)`
Setter for native field constIntxxPointerCustomLen, referencing a mixed and ambigously owned (**warning**) array with variable element count of getConstIntxxPointerCustomLenElemCount() elements.
Native Signature:
* field-type (PointerType) 'int32_t *' -> (const int32_t) * , size [fixed false, lnx64 8], const[false], pointer*1
* referenced (IntType) typedef 'int32_t', size [fixed true, lnx64 4], const[native, true], int
Replaces the respective field's memory with a new memory segment containing given source elements and referencing it.
Parameters:
* src the source array of elements
* srcPos starting element position within the source array with 'srcPos >= 0` && `srcPos + length <= src.length`, otherwise an IndexOutOfBoundsException is thrown
* length the element count to be copied with 'length >= 0` && `srcPos + length <= src.length`, otherwise an IndexOutOfBoundsException is thrown
Returns:
* this instance of chaining
### Struct Pointer-Pointer Support
See primitive [*Pointer Mapping*](#pointer-mapping) above.
*Pointer* are exposed in the following examples
```
typedef struct {
int32_t* int32PtrArray[10];
int32_t** int32PtrPtr;
...
} T2_PointerStorage;
```
or via and undefined forward-declared struct
```
typedef struct T2_UndefStruct* T2_UndefStructPtr;
typedef struct {
...
T2_UndefStructPtr undefStructPtr;
T2_UndefStructPtr undefStructPtrArray[10];
T2_UndefStructPtr* undefStructPtrPtr;
const T2_UndefStructPtr* constUndefStructPtrPtr;
} T2_PointerStorage;
```
and the following GlueGen configuration
```
Opaque long T2_UndefStruct*
Ignore T2_UndefStruct
```
*TODO: Enhance documentation*
### Struct Function-Pointer Support
GlueGen supports function pointers as struct fields,
generating function calls as methods as well function-pointer opaque getter and setter as `long` types.
The latter only in case if mutable, i.e. non-const.
#### Example
Assume the following C Header file example:
```
typedef struct {
int32_t balance;
} T2_UserData;
typedef int32_t ( * T2_CustomFuncA)(void* aptr);
typedef int32_t ( * T2_CustomFuncB)(T2_UserData* pUserData);
typedef struct {
...
T2_CustomFuncA customFuncAVariantsArray[10];
T2_CustomFuncA* customFuncAVariantsArrayPtr;
T2_CustomFuncB customFuncBVariantsArray[10];
T2_CustomFuncB* customFuncBVariantsArrayPtr;
} T2_PointerStorage;
typedef struct {
...
const T2_CustomFuncA CustomFuncA1;
T2_CustomFuncB CustomFuncB1;
} T2_InitializeOptions;
```
and the following GlueGen configuration
```
Opaque long void*
EmitStruct T2_UserData
StructPackage T2_UserData com.jogamp.gluegen.test.junit.generation
EmitStruct T2_InitializeOptions
StructPackage T2_InitializeOptions com.jogamp.gluegen.test.junit.generation
```
This will lead to the following result for `const T2_CustomFuncA customFuncA1`
```
/**
* Getter for native field CustomFuncA1, being a struct owned function pointer.
*
* Native Field Signature (PointerType) typedef 'T2_CustomFuncA' -> int32_t (*)(void * aptr), size [fixed false, lnx64 8], const[false], pointer*1, funcPointer
*
*/
public final long getCustomFuncA1() { .. }
/** Interface to C language function:
int32_t CustomFuncA1(void * aptr)
*/
public final int CustomFuncA1(long aptr) { ... }
```
and similar to `T2_CustomFuncB customFuncB1`
```
/**
* Setter for native field CustomFuncB1, being a struct owned function pointer.
*
* Native Field Signature (PointerType) typedef 'T2_CustomFuncB' -> int32_t (*)(T2_UserData * pUserData), size [fixed false, lnx64 8], const[false], pointer*1, funcPointer
*
*/
public final T2_InitializeOptions setCustomFuncB1(long src) { .. }
/**
* Getter for native field CustomFuncB1, being a struct owned function pointer.
*
* Native Field Signature (PointerType) typedef 'T2_CustomFuncB' -> int32_t (*)(T2_UserData * pUserData), size [fixed false, lnx64 8], const[false], pointer*1, funcPointer
*
*/
public final long getCustomFuncB1() { .. }
/** Interface to C language function:
int32_t CustomFuncB1(T2_UserData * pUserData)
*/
public final int CustomFuncB1(T2_UserData pUserData) { .. }
```
### Java Callback from Native C-API Support
GlueGen supports registering Java callback methods to native C-API functions in the form:
```
typedef int32_t ( * T_CallbackFunc)(size_t id, size_t msg_len, const char* msg, void* userParam);
void AddMessageCallback(T_CallbackFunc func, void* userParam);
void RemoveMessageCallback(T_CallbackFunc func, void* userParam);
void InjectMessageCallback(size_t id, size_t msg_len, const char* msg);
```
*TODO: Work in progress*
#### Example
## Platform Header Files
GlueGen provides convenient platform headers,
which can be included in your C header files for native compilation and GlueGen code generation.
Example:
```
#include
#include
uint64_t test64;
size_t size1;
ptrdiff_t ptr1;
```
To compile this file you have to include the following folder to your compilers system includes, ie `-I`:
```
gluegen/make/stub_includes/platform
```
To generate code for this file you have to include the following folder to your GlueGen `includeRefid` element:
```
gluegen/make/stub_includes/gluegen
```
## Pre-Defined Macros
To identity a GlueGen code generation run, GlueGen defines the following macros:
```
#define __GLUEGEN__ 2
```