GlueGen Struct [15]: Add FunctionPointer getter and setter support w/ documentation

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