GlueGen Struct [17]: Handle void pointers, i.e. `void*`, within a struct as `Opaque` configured pointer-types

.. includes cross-ref'ed doc and unit test

4 files changed, 80 insertions, 43 deletions

diff --git a/doc/GlueGen_Mapping.html b/doc/GlueGen_Mapping.html
index 96c56c5..9739082 100644
--- a/doc/GlueGen_Mapping.html
+++ b/doc/GlueGen_Mapping.html
@@ -940,6 +940,8 @@ fields</p>
 <ul>
 <li>See <a href="#primitive-mapping"><em>Primitive Mapping</em></a>
 above.</li>
+<li>See <a href="#struct-mapping-notes"><em>Opaque and
+<code>void*</code> notes</em></a> below.</li>
 <li>See <a href="#pointer-mapping"><em>Pointer Mapping</em></a> for
 <em>pointer-to-pointer</em> values above and <a
 href="#struct-pointer-pointer-support">Struct Pointer-Pointer
@@ -969,7 +971,48 @@ function which has to be compiled and its library loaded.</p>
 <code>public static boolean usesNativeCode()</code> can be used to
 validate whether the produced Java class requires a corresponding
 library for additional native code.</p>
+<h3 id="struct-mapping-notes">Struct Mapping Notes</h3>
+<ul>
+<li><p><a href="#opaque-java-primitive-type-symbol"><code>Opaque</code>
+configured pointer-types</a> are treated as <code>long</code> values
+from the Java side<br />
+while maintaining their architecture dependent pointer size within
+native memory.</p></li>
+<li><p>Void pointers, i.e. <code>void*</code>, within a struct are
+handled as <a
+href="#opaque-java-primitive-type-symbol"><code>Opaque</code> configured
+pointer-types</a>.</p></li>
+<li><p><em>ConstElemCount</em> via <strong>ReturnedArrayLength
+&lt;int&gt;</strong> implies <em>native ownership</em> for a
+<em>Pointer</em> referenced <em>native</em> memory if the expression is
+constant. Otherwise the <em>native</em> memory has <em>java
+ownership</em>. See <a
+href="#returnedarraylength-symbol-expression">ReturnedArrayLength
+Setting</a> below.</p></li>
+<li><p>Utilizing a <em>flexible</em> <em>elemCount</em> via
+<strong>ReturnedArrayLength getValElements()</strong> renders us unable
+to determine ownership of pointer referenced <em>native</em> memory
+segment and hence renders ownership <em>mixed or ambiguous</em>, <a
+href="#signature-const-int32_t--customsize-ambiguous-java-owned">see
+[5]</a>. This is due to the fact, that native code may allocate memory
+and writes its <em>elemCount</em> into the designated field
+<em>valElements</em>. In such cases, the user being aware of the
+underlying API shall utilize <code>setVal(..)</code> and
+<code>releaseVal()</code> with care.</p></li>
+<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="gluegen-struct-settings">GlueGen Struct Settings</h3>
+<h4 id="opaque-java-primitive-type-symbol"><strong>Opaque</strong>
+<em>Java-primitive-type</em> <em>symbol</em></h4>
+<p>See also <a href="manual/index.html#SecOpaque">Opaque section in
+manual</a>.</p>
+<ul>
+<li><p><code>Opaque long T2_UndefStruct*</code></p>
+<p>Pointers to <code>T2_UndefStruct</code> will be handled opaque, i.e.
+as <code>long</code> values from the Java side while maintaining their
+architecture dependent pointer size within native memory.</p></li>
+</ul>
 <h4 id="immutableaccess-symbol"><strong>ImmutableAccess</strong>
 <em>symbol</em></h4>
 <p>Immutable access can be set for a whole struct or a single field of a
@@ -1045,28 +1088,6 @@ variants, a <code>String</code> variant will be produced.</p>
 <p>See <a href="#string-mapping"><em>String Mapping</em></a>
 above.</p></li>
 </ul>
-<h3 id="struct-mapping-notes">Struct Mapping Notes</h3>
-<ul>
-<li><p><em>ConstElemCount</em> via <strong>ReturnedArrayLength
-&lt;int&gt;</strong> implies <em>native ownership</em> for a
-<em>Pointer</em> referenced <em>native</em> memory if the expression is
-constant. Otherwise the <em>native</em> memory has <em>java
-ownership</em>. See <a
-href="#returnedarraylength-symbol-expression">ReturnedArrayLength
-Setting</a> above.</p></li>
-<li><p>Utilizing a <em>flexible</em> <em>elemCount</em> via
-<strong>ReturnedArrayLength getValElements()</strong> renders us unable
-to determine ownership of pointer referenced <em>native</em> memory
-segment and hence renders ownership <em>mixed or ambiguous</em>, <a
-href="#signature-const-int32_t--customsize-ambiguous-java-owned">see
-[5]</a>. This is due to the fact, that native code may allocate memory
-and writes its <em>elemCount</em> into the designated field
-<em>valElements</em>. In such cases, the user being aware of the
-underlying API shall utilize <code>setVal(..)</code> and
-<code>releaseVal()</code> with care.</p></li>
-<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>
diff --git a/doc/GlueGen_Mapping.md b/doc/GlueGen_Mapping.md
index 8965dd6..b6a9514 100644
--- a/doc/GlueGen_Mapping.md
+++ b/doc/GlueGen_Mapping.md
@@ -208,6 +208,7 @@ A *Struct* is a C compound type declaration, which can be mapped to a Java class
 A *Struct* may utilize the following data types for its fields
 * *Primitive*, i.e. *char*, *int32_t*, ...
   * See [*Primitive Mapping*](#primitive-mapping) above.
+  * See [*Opaque and `void*` notes*](#struct-mapping-notes) below.
   * See [*Pointer Mapping*](#pointer-mapping) for *pointer-to-pointer* values above and [Struct Pointer-Pointer Support](#struct-pointer-pointer-support) below.
   * See [*String Mapping*](#string-mapping) above.
 * *Struct*, i.e. an aggregated or referenced compound variable
@@ -226,8 +227,33 @@ call the underlying native function which has to be compiled and its library loa
 The generated method `public static boolean usesNativeCode()` can be used to validate
 whether the produced Java class requires a corresponding library for additional native code.
 
+### Struct Mapping Notes
+
+* [`Opaque` configured pointer-types](#opaque-java-primitive-type-symbol) are treated as `long` values from the Java side    
+  while maintaining their architecture dependent pointer size within native memory.
+  
+* Void pointers, i.e. `void*`, within a struct are handled as [`Opaque` configured pointer-types](#opaque-java-primitive-type-symbol).
+
+* *ConstElemCount* via **ReturnedArrayLength \<int\>** 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) below.
+
+* 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.
+
 ### GlueGen Struct Settings
 
+#### **Opaque** *Java-primitive-type* *symbol*
+
+See also [Opaque section in manual](manual/index.html#SecOpaque).
+
+* `Opaque long T2_UndefStruct*`
+
+    Pointers to `T2_UndefStruct` will be handled opaque, 
+    i.e. as `long` values from the Java side while maintaining their architecture dependent pointer size within native memory.
+
 #### **ImmutableAccess** *symbol*
 Immutable access can be set for a whole struct or a single field of a struct.
 
@@ -301,17 +327,6 @@ A direct C code `char` array or indirect array via pointer can be interpreted as
     
     See [*String Mapping*](#string-mapping) above.
 
-### Struct Mapping Notes
-
-* *ConstElemCount* via **ReturnedArrayLength \<int\>** 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
diff --git a/src/java/com/jogamp/gluegen/JavaEmitter.java b/src/java/com/jogamp/gluegen/JavaEmitter.java
index f0bc8c7..3a86239 100644
--- a/src/java/com/jogamp/gluegen/JavaEmitter.java
+++ b/src/java/com/jogamp/gluegen/JavaEmitter.java
@@ -1741,8 +1741,11 @@ public class JavaEmitter implements GlueEmitter {
       final String baseElemSizeDenominator;
       final boolean useGetCStringLength;
       final boolean maxOneElement; // zero or one element
-      if( isOpaque && opaqueTypeInfo.pointerDepth() <= 1 || ( fieldType.isPrimitive() && !baseElemType.isFunctionPointer() ) ) {
-          // Overridden by JavaConfiguration.typeInfo(..), i.e. Opaque!
+      if( isOpaque && opaqueTypeInfo.pointerDepth() <= 1 ||                    // explicit 'Opaque' (config)
+          ( fieldType.isPrimitive() && !baseElemType.isFunctionPointer() ) ||  // a primitive and non-function-ptr
+          ( fieldType.isPointer() && baseElemType.isVoid() )                   // like 'void*' -> 'void'
+        )
+      {
           // Emulating array w/ 1 element
           isPrimitive = true;
           isPointer = false;
@@ -1837,14 +1840,6 @@ public class JavaEmitter implements GlueEmitter {
           if( GlueGen.debug() ) {
               System.err.printf("SE.ac.%02d: ownership %s%n", (i+1), ownership);
           }
-
-          if( !baseElemType.hasSize() ) { // like 'void*' -> 'void'
-              final String msg = "SKIP unsized field in struct: "+fqStructFieldName+": fieldType "+fieldType.getSignature(null).toString()+", baseType "+baseElemType.getSignature(null).toString();
-              unit.emitln("  // "+msg);
-              unit.emitln();
-              LOG.log(WARNING, structCType.getASTLocusTag(), msg);
-              return;
-          }
           baseIsPointer = baseElemType.isPointer();
           isConstValue = baseElemType.isConst();
           if( baseIsPointer ) {
diff --git a/src/junit/com/jogamp/gluegen/test/junit/generation/Test2FuncPtr.java b/src/junit/com/jogamp/gluegen/test/junit/generation/Test2FuncPtr.java
index 3503fa3..cf32eb7 100644
--- a/src/junit/com/jogamp/gluegen/test/junit/generation/Test2FuncPtr.java
+++ b/src/junit/com/jogamp/gluegen/test/junit/generation/Test2FuncPtr.java
@@ -96,6 +96,12 @@ public class Test2FuncPtr extends BaseClass {
         Assert.assertNotEquals(0, options.getCustomFuncB1());
         Assert.assertNotEquals(0, options.getCustomFuncB2());
         Assert.assertEquals(1, options.getApiVersion());
+        Assert.assertEquals(1, T2_InitializeOptions.getReserved1ElemCount());
+        BaseClass.assertAPTR(0x0000CAFFEEBEEFL, options.getReserved1());
+        {
+            options.setReserved1(0xBEEFCAFFEE0DADL);
+            BaseClass.assertAPTR(0xBEEFCAFFEE0DADL, options.getReserved1());
+        }
         Assert.assertEquals("Product Name", options.getProductName());
         Assert.assertEquals("Product Version", options.getProductVersion());
         Assert.assertEquals(0xa001, options.CustomFuncA1(0));