summaryrefslogtreecommitdiffstats
path: root/doc/GlueGen_Mapping.html
diff options
context:
space:
mode:
Diffstat (limited to 'doc/GlueGen_Mapping.html')
-rw-r--r--doc/GlueGen_Mapping.html285
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> &amp; <em>ConstValue</em> &amp;
+<em>ConstElemCount</em>: Drops setter, native ownership on
+const-value</li>
+<li><em>Array</em> &amp; <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> &amp; <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> &amp; <em>isByteBuffer</em> &amp; <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 &lt;= <em>elemCount</em>, otherwise
+Exception</li>
+<li><em>Pointer</em> &amp; <em>VariaElemCount</em>: Reuse
+<em>native</em> memory and store value with &lt;= <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> &amp; <em>ConstValue</em> &amp;
-<em>ConstElemCount</em>: Drops setter, native ownership on
-const-value</li>
-<li><em>Array</em> &amp; <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> &amp; <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> &amp; <em>isByteBuffer</em> &amp; <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 &lt;= <em>elemCount</em>, otherwise
-Exception</li>
-<li><em>Pointer</em> &amp; <em>VariaElemCount</em>: Reuse
-<em>native</em> memory and store value with &lt;= <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&lt;FuncName&gt;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: &lt;br&gt; &lt;code&gt;int32_t CustomFuncA1(void * aptr)&lt;/code&gt;&lt;br&gt; */
+ public final int CustomFuncA1(long aptr) { ... }
+
+ /**
+ * Returns `true` if native pointer &lt;code&gt;CustomFuncA1&lt;/code&gt; is `null`, otherwise `false`.
+ * &lt;p&gt;
+ * Corresponds to native field &lt;code&gt;CustomFuncA1&lt;/code&gt;, being a &lt;i&gt;struct&lt;/i&gt; owned function pointer.
+ * &lt;/p&gt;
+ * &lt;p&gt;
+ * Native Field Signature &lt;code&gt;(PointerType) typedef &#39;T2_CustomFuncA&#39; -&gt; int32_t (*)(void * aptr), size [fixed false, lnx64 8], const[false], pointer*1, funcPointer&lt;/code&gt;
+ * &lt;/p&gt;
+ */
+ public final boolean isCustomFuncA1Null() { .. }
+
+ /**
+ * Setter for native field &lt;code&gt;CustomFuncA1&lt;/code&gt;, being a &lt;i&gt;struct&lt;/i&gt; owned function pointer.
+ * &lt;p&gt;
+ * Native Field Signature &lt;code&gt;(PointerType) typedef &#39;T2_CustomFuncA&#39; -&gt; int32_t (*)(void * aptr), size [fixed false, lnx64 8], const[false], pointer*1, funcPointer&lt;/code&gt;
+ * &lt;/p&gt;
+ */
+ public final T2_InitializeOptions setCustomFuncA1(long src) { .. }
+
+ /**
+ * Getter for native field &lt;code&gt;CustomFuncA1&lt;/code&gt;, being a &lt;i&gt;struct&lt;/i&gt; owned function pointer.
+ * &lt;p&gt;
+ * Native Field Signature &lt;code&gt;(PointerType) typedef &#39;T2_CustomFuncA&#39; -&gt; int32_t (*)(void * aptr), size [fixed false, lnx64 8], const[false], pointer*1, funcPointer&lt;/code&gt;
+ * &lt;/p&gt;
+ */
+ public final long getCustomFuncA1() { .. } </code></pre>
+<p>and similar to <code>T2_InitializeOptions.customFuncB1</code></p>
+<pre><code> /** Interface to C language function: &lt;br&gt; &lt;code&gt;int32_t CustomFuncB1(T2_UserData * pUserData)&lt;/code&gt;&lt;br&gt; */
+ public final int CustomFuncB1(T2_UserData pUserData) { .. }
+
+ /**
+ * Returns `true` if native pointer &lt;code&gt;CustomFuncB1&lt;/code&gt; is `null`, otherwise `false`.
+ * &lt;p&gt;
+ * Corresponds to native field &lt;code&gt;CustomFuncB1&lt;/code&gt;, being a &lt;i&gt;struct&lt;/i&gt; owned function pointer.
+ * &lt;/p&gt;
+ * &lt;p&gt;
+ * Native Field Signature &lt;code&gt;(PointerType) typedef &#39;T2_CustomFuncB&#39; -&gt; int32_t (*)(T2_UserData * pUserData), size [fixed false, lnx64 8], const[false], pointer*1, funcPointer&lt;/code&gt;
+ * &lt;/p&gt;
+ */
+ public final boolean isCustomFuncB1Null() { .. }
+
+ /**
+ * Setter for native field &lt;code&gt;CustomFuncB1&lt;/code&gt;, being a &lt;i&gt;struct&lt;/i&gt; owned function pointer.
+ * &lt;p&gt;
+ * Native Field Signature &lt;code&gt;(PointerType) typedef &#39;T2_CustomFuncB&#39; -&gt; int32_t (*)(T2_UserData * pUserData), size [fixed false, lnx64 8], const[false], pointer*1, funcPointer&lt;/code&gt;
+ * &lt;/p&gt;
+ */
+ public final T2_InitializeOptions setCustomFuncB1(long src) { .. }
+
+ /**
+ * Getter for native field &lt;code&gt;CustomFuncB1&lt;/code&gt;, being a &lt;i&gt;struct&lt;/i&gt; owned function pointer.
+ * &lt;p&gt;
+ * Native Field Signature &lt;code&gt;(PointerType) typedef &#39;T2_CustomFuncB&#39; -&gt; int32_t (*)(T2_UserData * pUserData), size [fixed false, lnx64 8], const[false], pointer*1, funcPointer&lt;/code&gt;
+ * &lt;/p&gt;
+ */
+ 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