diff options
Diffstat (limited to 'doc/GlueGen_Mapping.html')
-rw-r--r-- | doc/GlueGen_Mapping.html | 285 |
1 files changed, 210 insertions, 75 deletions
diff --git a/doc/GlueGen_Mapping.html b/doc/GlueGen_Mapping.html index b86d294..d3f7aef 100644 --- a/doc/GlueGen_Mapping.html +++ b/doc/GlueGen_Mapping.html @@ -430,12 +430,14 @@ <li><a href="#gluegen-struct-settings">GlueGen Struct Settings</a></li> <li><a href="#struct-mapping-notes">Struct Mapping Notes</a></li> + <li><a href="#struct-setter-pseudo-code">Struct Setter + Pseudo-Code</a></li> <li><a href="#struct-java-signature-table">Struct Java Signature Table</a></li> <li><a href="#struct-java-signature-examples">Struct Java Signature Examples</a></li> - <li><a href="#struct-setter-pseudo-code">Struct Setter - Pseudo-Code</a></li> + <li><a href="#struct-function-pointer-support">Struct Function Pointer + Support</a></li> </ul></li> <li><a href="#platform-header-files">Platform Header Files</a></li> <li><a href="#pre-defined-macros">Pre-Defined Macros</a></li> @@ -1043,6 +1045,121 @@ underlying API shall utilize <code>setVal(..)</code> and <li><p>To release native memory with <em>java ownership</em>, i.e. a native ByteBuffer, <code>releaseVal()</code> can be used.</p></li> </ul> +<h3 id="struct-setter-pseudo-code">Struct Setter Pseudo-Code</h3> +<h4 id="overview-1">Overview</h4> +<p>In general we have the following few cases</p> +<ul> +<li><p>Array owned by parent struct itself</p> +<ul> +<li><code>int32_t val[10]</code> +<ul> +<li>Setter of <code>val</code> within range, keeping memory</li> +</ul></li> +<li><code>const int32_t val[10]</code> +<ul> +<li>No setter allowed due to const value</li> +</ul></li> +</ul></li> +<li><p>Referenced Memory (array) owned by Java</p> +<ul> +<li><code>int32_t* val</code> +<ul> +<li>Setter within range, keeping memory, or replacing memory</li> +</ul></li> +<li><code>const int32_t* val</code> +<ul> +<li>Setter replacing memory, since memory is non-const but value is +const</li> +</ul></li> +</ul></li> +<li><p>Referenced Memory (array) owned by Native Code due to set +<em>ConstElemCount</em></p> +<ul> +<li><code>int32_t* val</code> +<ul> +<li>Setter of <code>val</code> within range, keeping memory owned by +native code</li> +</ul></li> +<li><code>const int32_t* val</code> +<ul> +<li>No setter allowed, since memory is owned by native code and value is +const</li> +</ul></li> +</ul></li> +</ul> +<h4 id="implemented-pseudo-code">Implemented Pseudo Code</h4> +<ul> +<li><em>ImmutableAccess</em>: Drops setter, immutable</li> +<li><em>Pointer</em> & <em>ConstValue</em> & +<em>ConstElemCount</em>: Drops setter, native ownership on +const-value</li> +<li><em>Array</em> & <em>ConstValue</em> : Drops setter, const-value +array</li> +<li><em>Primitive</em> +<ul> +<li>Single aggregated instance +<ul> +<li>Store value within <em>native</em> memory</li> +</ul></li> +<li><em>Array</em> | <em>Pointer</em> +<ul> +<li><em>MaxOneElement</em> +<ul> +<li><em>Pointer</em> +<ul> +<li><em>ConstValue</em>: Allocate new memory and store value</li> +<li><em>VariaValue</em>: +<ul> +<li><em>ConstElemCount</em>: Reuse <em>native</em> memory and store +value with matching <em>elemCount 1</em>, otherwise Exception</li> +<li><em>VariaElemCount</em>: Reuse <em>native</em> memory and store +value with matching <em>elemCount 1</em>, otherwise allocates new memory +(had <em>elemCount 0</em>)</li> +</ul></li> +</ul></li> +<li><em>Array</em> & <em>VariaValue</em>: Reuse <em>native</em> +memory and store value (has const <em>elemCount 1</em>)</li> +<li><em>else</em>: <em>SKIP</em> setter for const single-primitive +array</li> +</ul></li> +<li><em>AnyElementCount</em> +<ul> +<li><em>String</em> & <em>isByteBuffer</em> & <em>Pointer</em> +<ul> +<li><em>ConstElemCount</em>: Reuse <em>native</em> memory and store +UTF-8 bytes with EOS with matching <em>elemCount</em>, otherwise +Exception +<ul> +<li><em>StringOnly</em>: End, no more setter for this field, otherwise +continue</li> +</ul></li> +<li><em>VariaElemCount</em>: Allocate new <em>native</em> memory and +store UTF-8 bytes with EOS +<ul> +<li><em>StringOnly</em>: End, no more setter for this field, otherwise +continue</li> +</ul></li> +</ul></li> +<li><em>ConstValue</em> +<ul> +<li><em>Pointer</em> +<ul> +<li><em>VariaElemCount</em>: Allocates new <em>native</em> memory and +store value</li> +</ul></li> +<li><em>else</em>: <em>SKIP</em> setter for const primitive array</li> +</ul></li> +<li><em>Array</em> | <em>ConstElemCount</em>: Reuse <em>native</em> +memory and store value with <= <em>elemCount</em>, otherwise +Exception</li> +<li><em>Pointer</em> & <em>VariaElemCount</em>: Reuse +<em>native</em> memory and store value with <= <em>elemCount</em>, +otherwise allocate new <em>native</em> memory</li> +</ul></li> +</ul></li> +</ul></li> +<li><em>Struct</em> ...</li> +</ul> <h3 id="struct-java-signature-table">Struct Java Signature Table</h3> <p>Please find below signature table as generated by the <em>C Declaration</em> including its <em>C Modifier</em>, e.g. @@ -1569,79 +1686,97 @@ IndexOutOfBoundsException is thrown</li> <li>this instance of chaining</li> </ul></li> </ul> -<h3 id="struct-setter-pseudo-code">Struct Setter Pseudo-Code</h3> -<ul> -<li><em>ImmutableAccess</em>: Drops setter, immutable</li> -<li><em>Pointer</em> & <em>ConstValue</em> & -<em>ConstElemCount</em>: Drops setter, native ownership on -const-value</li> -<li><em>Array</em> & <em>ConstValue</em> : Drops setter, const-value -array</li> -<li><em>Primitive</em> -<ul> -<li>Single aggregated instance -<ul> -<li>Store value within <em>native</em> memory</li> -</ul></li> -<li><em>Array</em> | <em>Pointer</em> -<ul> -<li><em>MaxOneElement</em> -<ul> -<li><em>Pointer</em> -<ul> -<li><em>ConstValue</em>: Allocate new memory and store value</li> -<li><em>VariaValue</em>: -<ul> -<li><em>ConstElemCount</em>: Reuse <em>native</em> memory and store -value with matching <em>elemCount 1</em>, otherwise Exception</li> -<li><em>VariaElemCount</em>: Reuse <em>native</em> memory and store -value with matching <em>elemCount 1</em>, otherwise allocates new memory -(had <em>elemCount 0</em>)</li> -</ul></li> -</ul></li> -<li><em>Array</em> & <em>VariaValue</em>: Reuse <em>native</em> -memory and store value (has const <em>elemCount 1</em>)</li> -<li><em>else</em>: <em>SKIP</em> setter for const single-primitive -array</li> -</ul></li> -<li><em>AnyElementCount</em> -<ul> -<li><em>String</em> & <em>isByteBuffer</em> & <em>Pointer</em> -<ul> -<li><em>ConstElemCount</em>: Reuse <em>native</em> memory and store -UTF-8 bytes with EOS with matching <em>elemCount</em>, otherwise -Exception -<ul> -<li><em>StringOnly</em>: End, no more setter for this field, otherwise -continue</li> -</ul></li> -<li><em>VariaElemCount</em>: Allocate new <em>native</em> memory and -store UTF-8 bytes with EOS -<ul> -<li><em>StringOnly</em>: End, no more setter for this field, otherwise -continue</li> -</ul></li> -</ul></li> -<li><em>ConstValue</em> -<ul> -<li><em>Pointer</em> -<ul> -<li><em>VariaElemCount</em>: Allocates new <em>native</em> memory and -store value</li> -</ul></li> -<li><em>else</em>: <em>SKIP</em> setter for const primitive array</li> -</ul></li> -<li><em>Array</em> | <em>ConstElemCount</em>: Reuse <em>native</em> -memory and store value with <= <em>elemCount</em>, otherwise -Exception</li> -<li><em>Pointer</em> & <em>VariaElemCount</em>: Reuse -<em>native</em> memory and store value with <= <em>elemCount</em>, -otherwise allocate new <em>native</em> memory</li> -</ul></li> -</ul></li> -</ul></li> -<li><em>Struct</em> ...</li> -</ul> +<h3 id="struct-function-pointer-support">Struct Function Pointer +Support</h3> +<p>GlueGen supports function pointers as struct fields,<br /> +generating function calls as methods as well as +<code>is<FuncName>Null()</code> checks<br /> +and function pointer opaque getter and setter as <code>long</code> +types.</p> +<h4 id="example">Example</h4> +<p>Assume the following C Header file example:</p> +<pre><code>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 CustomFuncA1; + T2_CustomFuncB CustomFuncB1; +} T2_InitializeOptions;</code></pre> +<p>and the following GlueGen <em>no-magic</em> configuration</p> +<pre><code>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</code></pre> +<p>This will lead to the following result for +<code>T2_InitializeOptions.customFuncA1</code></p> +<pre><code> /** Interface to C language function: <br> <code>int32_t CustomFuncA1(void * aptr)</code><br> */ + public final int CustomFuncA1(long aptr) { ... } + + /** + * Returns `true` if native pointer <code>CustomFuncA1</code> is `null`, otherwise `false`. + * <p> + * Corresponds to native field <code>CustomFuncA1</code>, being a <i>struct</i> owned function pointer. + * </p> + * <p> + * Native Field Signature <code>(PointerType) typedef 'T2_CustomFuncA' -> int32_t (*)(void * aptr), size [fixed false, lnx64 8], const[false], pointer*1, funcPointer</code> + * </p> + */ + public final boolean isCustomFuncA1Null() { .. } + + /** + * Setter for native field <code>CustomFuncA1</code>, being a <i>struct</i> owned function pointer. + * <p> + * Native Field Signature <code>(PointerType) typedef 'T2_CustomFuncA' -> int32_t (*)(void * aptr), size [fixed false, lnx64 8], const[false], pointer*1, funcPointer</code> + * </p> + */ + public final T2_InitializeOptions setCustomFuncA1(long src) { .. } + + /** + * Getter for native field <code>CustomFuncA1</code>, being a <i>struct</i> owned function pointer. + * <p> + * Native Field Signature <code>(PointerType) typedef 'T2_CustomFuncA' -> int32_t (*)(void * aptr), size [fixed false, lnx64 8], const[false], pointer*1, funcPointer</code> + * </p> + */ + public final long getCustomFuncA1() { .. } </code></pre> +<p>and similar to <code>T2_InitializeOptions.customFuncB1</code></p> +<pre><code> /** Interface to C language function: <br> <code>int32_t CustomFuncB1(T2_UserData * pUserData)</code><br> */ + public final int CustomFuncB1(T2_UserData pUserData) { .. } + + /** + * Returns `true` if native pointer <code>CustomFuncB1</code> is `null`, otherwise `false`. + * <p> + * Corresponds to native field <code>CustomFuncB1</code>, being a <i>struct</i> owned function pointer. + * </p> + * <p> + * Native Field Signature <code>(PointerType) typedef 'T2_CustomFuncB' -> int32_t (*)(T2_UserData * pUserData), size [fixed false, lnx64 8], const[false], pointer*1, funcPointer</code> + * </p> + */ + public final boolean isCustomFuncB1Null() { .. } + + /** + * Setter for native field <code>CustomFuncB1</code>, being a <i>struct</i> owned function pointer. + * <p> + * Native Field Signature <code>(PointerType) typedef 'T2_CustomFuncB' -> int32_t (*)(T2_UserData * pUserData), size [fixed false, lnx64 8], const[false], pointer*1, funcPointer</code> + * </p> + */ + public final T2_InitializeOptions setCustomFuncB1(long src) { .. } + + /** + * Getter for native field <code>CustomFuncB1</code>, being a <i>struct</i> owned function pointer. + * <p> + * Native Field Signature <code>(PointerType) typedef 'T2_CustomFuncB' -> int32_t (*)(T2_UserData * pUserData), size [fixed false, lnx64 8], const[false], pointer*1, funcPointer</code> + * </p> + */ + public final long getCustomFuncB1() { .. } +</code></pre> <h2 id="platform-header-files">Platform Header Files</h2> <p>GlueGen provides convenient platform headers,<br /> which can be included in your C header files for native compilation and |