GlueGen JavaCallback: Remove ambiguity: Config JavaCallbackDef/JavaCallbackKey: Always define both parameter indices; emitJavaStaticCallback(): Use cbFuncBinding and cbFuncKeyIndices from callback parameter to build key

1 files changed, 60 insertions, 41 deletions

diff --git a/doc/GlueGen_Mapping.html b/doc/GlueGen_Mapping.html
index 7bec555..d484ff8 100644
--- a/doc/GlueGen_Mapping.html
+++ b/doc/GlueGen_Mapping.html
@@ -463,8 +463,10 @@
   <li><a href="#javacallback-example-1">JavaCallback Example 1</a></li>
   <li><a href="#javacallback-example-2a-default-keyclass">JavaCallback
   Example 2a (Default <em>KeyClass</em>)</a></li>
-  <li><a href="#javacallback-example-2b-custom-keyclass">JavaCallback
-  Example 2b (Custom <em>KeyClass</em>)</a></li>
+  <li><a
+  href="#javacallback-example-2b-custom-keyclass-different-key-parameter-order">JavaCallback
+  Example 2b (Custom <em>KeyClass</em>, different key-parameter
+  order)</a></li>
   <li><a
   href="#javacallback-example-11a-homogeneous-struct-type">JavaCallback
   Example 11a (<em>Homogeneous Struct Type</em>)</a></li>
@@ -2027,27 +2029,29 @@ Object</em> to be passed to the users'
 <h3 id="javacallback-configuration"><em>JavaCallback</em>
 Configuration</h3>
 <p>Configuration directives are as follows:</p>
-<pre><code>JavaCallbackDef  &lt;SetCallbackFunctionName&gt; [&lt;SetCallback-UserParamIndex&gt;] &lt;CallbackFunctionType&gt; &lt;CallbackFunction-UserParamIndex&gt; [&lt;SetCallback-KeyClassName&gt;]    
-JavaCallbackKey  &lt;SetCallbackFunctionName&gt; (SetCallback-ParamIdx)*</code></pre>
+<pre><code>JavaCallbackDef  &lt;SetCallbackFunctionName&gt; &lt;SetCallback-UserParamIndex&gt; &lt;CallbackFunctionType&gt; &lt;CallbackFunction-UserParamIndex&gt; [&lt;SetCallback-KeyClassName&gt;]    
+JavaCallbackKey  &lt;SetCallbackFunctionName&gt; &lt;SetCallback-ParamIndex&gt;* &lt;CallbackFunctionType&gt; &lt;CallbackFunction-ParamIndex&gt;*</code></pre>
 <p><code>JavaCallbackDef</code> and <code>JavaCallbackKey</code> use the
 name of the <code>SetCallbackFunction</code> as its first attribute, as
-it is core to the semantic mapping of all resources.</p>
+it is core to the semantic mapping of all resources. They also have to
+use the same <code>CallbackFunctionType</code>.</p>
 <p><code>JavaCallbackDef</code> attributes:</p>
 <ul>
 <li><code>SetCallbackFunction</code>: <code>SetCallbackFunction</code>
 name of the native toolkit API responsible to set the callback</li>
-<li><code>SetCallback-UserParamIndex</code>: Optional
-<code>UserParam</code> parameter-index of the
-<code>SetCallbackFunction</code>, allowing to <a
-href="#struct-type-user-param-heterogeneous">indicate a heterogeneous
-<code>UserParam</code></a></li>
+<li><code>SetCallback-UserParamIndex</code>: <code>UserParam</code>
+parameter-index of the <code>SetCallbackFunction</code></li>
 <li><code>CallbackFunctionType</code>: The native toolkit API
 typedef-name of the function-pointer-type, aka the callback type
 name</li>
 <li><code>CallbackFunction-UserParamIndex</code>: The
 <code>userParam</code> parameter-index of the
-<code>CallbackFunctionType</code></li>
-<li><code>SetCallback-KeyClassName</code>: Name of an optional
+<code>CallbackFunctionType</code>, allowing to accommodate a potential
+parameter-type collision between <code>SetCallbackFunction</code> and
+<code>CallbackFunction</code>. It also allows to <a
+href="#struct-type-user-param-heterogeneous">indicate a heterogeneous
+<code>UserParam</code></a></li>
+<li><code>SetCallback-KeyClassName</code>: Optional name of a
 user-implemented <code>SetCallback-KeyClass</code>, providing the
 hash-map-key - see below</li>
 </ul>
@@ -2056,7 +2060,7 @@ hash-map-key - see below</li>
 <code>null</code> for the <code>CallbackFunction</code>.</p>
 <p>If mapping the <code>CallbackFunction</code> to keys, the user must
 specify the same key arguments when setting and removing the
-``CallbackFunction`.</p>
+<code>CallbackFunction</code>.</p>
 <h4 id="javacallback-key-definition"><em>JavaCallback</em> Key
 Definition</h4>
 <p>If no keys are defined via <code>JavaCallbackKey</code> or not
@@ -2068,17 +2072,27 @@ public <code>SetCallback-KeyClass</code> is being generated covering the
 defined keys.</p>
 <p>Keys allow to limit the scope, i.e. map multiple
 <code>CallbackFunction</code> to the different keys.</p>
-<p>Key arguments must match in <code>SetCallbackFunction</code> to
-remove a previously set <code>CallbackFunction</code>.</p>
+<p>To remove a previously set <code>CallbackFunction</code> via
+<code>SetCallbackFunction</code>, the key arguments must match.</p>
 <p><code>JavaCallbackKey</code> attributes</p>
 <ul>
 <li><code>SetCallbackFunction</code>: <code>SetCallbackFunction</code>
 name of the native toolkit API responsible to set the callback</li>
-<li><code>SetCallback-ParamIdx</code>: List of parameter indices of the
-<code>SetCallbackFunction</code>, denoting the key(s) limiting the
+<li><code>SetCallback-ParamIndex</code>: List of parameter indices of
+the <code>SetCallbackFunction</code>, denoting the key(s) limiting the
 callback scope, i.e. the callback and all resources will be mapped to
 this key. The optional <code>SetCallback-KeyClass</code> may override
 this semantic.</li>
+<li><code>CallbackFunctionType</code>: The native toolkit API
+typedef-name of the function-pointer-type, the same callback type name
+as defined in <code>JavaCallbackDef</code></li>
+<li><code>CallbackFunction-ParamIndex</code>: List of parameter indices
+of the <code>CallbackFunctionType</code>, matching the semantic
+parameter of <code>SetCallback-ParamIndex</code> to accommodate
+potential different parameter order or argument names between
+<code>SetCallbackFunction</code> and <code>CallbackFunction</code>. The
+indexed parameters must be semantical equivalent as specified by the
+<code>SetCallback-ParamIndex</code> list.</li>
 </ul>
 <h4 id="custom-setcallback-keyclass">Custom
 <code>SetCallback-KeyClass</code></h4>
@@ -2196,7 +2210,7 @@ and the native callback dispatcher <strong>are thread-safe</strong></li>
 <li>...</li>
 </ul>
 <h3 id="javacallback-example-1">JavaCallback Example 1</h3>
-<p>This examples demonstrates a <a
+<p>This example demonstrates a <a
 href="#pure-java-object-user-type-default">homogeneous <em>Java
 Object</em> <code>UserParam</code> mapping</a> with a <a
 href="#javacallback-key-definition">globally scoped</a>
@@ -2230,7 +2244,7 @@ ArgumentIsString InjectMessageCallback01 1
 #   - `T2_CallbackFunc01 getMessageCallback01()` returns the global T2_CallbackFunc01, null if not mapped
 #   - `Object getMessageCallback01UserParam()` returns the global `usrParam` object, null if not mapped
 #   - `void releaseMessageCallback01()` releases callback data skipping toolkit API. Favor passing `null` callback ref to `MessageCallback01(..)`
-JavaCallbackDef  MessageCallback01 T2_CallbackFunc01 2</code></pre>
+JavaCallbackDef  MessageCallback01 1 T2_CallbackFunc01 2</code></pre>
 <p>Note that <a
 href="#libraryonload-librarybasename-for-jni_onload-"><code>LibraryOnLoad Bindingtest2</code></a>
 must be specified in exactly one native code-unit within the library. It
@@ -2269,18 +2283,18 @@ the current thread to the <code>JavaVM*</code> generating a new
   public void InjectMessageCallback01(long id, String msg);</code></pre>
 <h3 id="javacallback-example-2a-default-keyclass">JavaCallback Example
 2a (Default <em>KeyClass</em>)</h3>
-<p>This examples demonstrates a <a
+<p>This example demonstrates a <a
 href="#pure-java-object-user-type-default">homogeneous <em>Java
 Object</em> <code>UserParam</code> mapping</a> with a <a
 href="#javacallback-key-definition">key-mapped</a>
 <code>CallbackFunction</code> and <code>UserParam</code>.</p>
-<p>This examples is derived from OpenAL's
+<p>This example is derived from OpenAL's
 <code>AL_SOFT_callback_buffer</code> extension.</p>
 <p>The callback <code>ALBUFFERCALLBACKTYPESOFT</code> is mapped to
 <code>buffer</code> name, i.e. one callback can be set for each
 buffer.</p>
 <p>C-API Header snipped</p>
-<pre><code>  typedef void ( * ALBUFFERCALLBACKTYPESOFT)(int buffer, void *userptr, int sampledata, int numbytes);
+<pre><code>  typedef void ( * ALBUFFERCALLBACKTYPESOFT)(int buffer /* key */, void *userptr, int sampledata, int numbytes);
   
   void alBufferCallback0(int buffer /* key */, int format, int freq, ALBUFFERCALLBACKTYPESOFT callback, void *userptr);
   
@@ -2302,8 +2316,8 @@ buffer.</p>
   #   - `Object getAlBufferCallback0UserParam(AlBufferCallback0Key)` returns the `buffer` mapped `userptr` object, null if not mapped
   #   - `void releaseAllAlBufferCallback0()` releases all callback data mapped via Key { int buffer } skipping toolkit API. Favor passing `null` callback ref to `alBufferCallback0(..)`
   #   - `void releaseAlBufferCallback0(AlBufferCallback0Key)` releases callback data mapped to Key { int buffer } skipping toolkit API. Favor passing `null` callback ref to `alBufferCallback0(..)`
-  JavaCallbackDef  alBufferCallback0 ALBUFFERCALLBACKTYPESOFT 1
-  JavaCallbackKey  alBufferCallback0 0</code></pre>
+  JavaCallbackDef  alBufferCallback0 4 ALBUFFERCALLBACKTYPESOFT 1
+  JavaCallbackKey  alBufferCallback0 0 ALBUFFERCALLBACKTYPESOFT 0</code></pre>
 <p>leading to the following interface</p>
 <pre><code>  /** JavaCallback interface: ALBUFFERCALLBACKTYPESOFT -&gt; void (*ALBUFFERCALLBACKTYPESOFT)(int buffer, void *  userptr, int sampledata, int numbytes) */
   public static interface ALBUFFERCALLBACKTYPESOFT {
@@ -2363,22 +2377,27 @@ buffer.</p>
 
   /** Entry point (through function pointer) to C language function: &lt;br&gt; &lt;code&gt;void alEventCallbackInject(int eventType, int object, int param, const char *  msg)&lt;/code&gt;&lt;br&gt;   */
   public void alEventCallbackInject(int eventType, int object, int param, String msg);  </code></pre>
-<h3 id="javacallback-example-2b-custom-keyclass">JavaCallback Example 2b
-(Custom <em>KeyClass</em>)</h3>
-<p>This examples demonstrates a <a
-href="#pure-java-object-user-type-default">homogeneous <em>Java
-Object</em> <code>UserParam</code> mapping</a> with a <a
+<h3
+id="javacallback-example-2b-custom-keyclass-different-key-parameter-order">JavaCallback
+Example 2b (Custom <em>KeyClass</em>, different key-parameter
+order)</h3>
+<p>Similar example as example 2a, but using a <a
 href="#custom-setcallback-keyclass">custom <em>KeyClass</em></a> to map
-<code>CallbackFunction</code> and <code>UserParam</code>.</p>
-<p>Same as example 2a, but implementing a custom
-<code>SetCallback-KeyClass</code>.</p>
-<p>Instead of <code>Callback0</code>, the unit <code>test2.*</code> uses
-<code>Callback1</code> to differentiate this case.</p>
+<code>CallbackFunction</code> and <code>UserParam</code> and also
+accommodating a different key-parameter order between
+<code>SetCallbackFunction</code> and <code>CallbackFunction</code>.</p>
+<p>C-API Header snipped</p>
+<pre><code>  typedef void ( * ALBUFFERCALLBACKTYPESOFT)(int buffer /* key */, void *userptr, int sampledata, int numbytes);
+  
+  void alBufferCallback1(void *user_ptr, int buffer_key /* key */, int format, int freq, ALBUFFERCALLBACKTYPESOFT callback);
+  
+  void alBufferCallback1Inject(int buffer, int sampledata, int numbytes);</code></pre>
 <p>GlueGen configuration snippet with the added option attribute for the
 <code>SetCallback-KeyClass</code> in directive
 <code>JavaCallbackDef</code>.</p>
-<pre><code>JavaCallbackDef  alBufferCallback1 ALBUFFERCALLBACKTYPESOFT 1 com.jogamp.gluegen.test.junit.generation.Test4JavaCallback.CustomAlBufferCallback1Key
-JavaCallbackKey  alBufferCallback1 0</code></pre>
+<pre><code>JavaCallbackDef  alBufferCallback1 0 ALBUFFERCALLBACKTYPESOFT 1 com.jogamp.gluegen.test.junit.generation.Test4JavaCallback.CustomAlBufferCallback1Key
+JavaCallbackKey  alBufferCallback1 1 ALBUFFERCALLBACKTYPESOFT 0
+</code></pre>
 <p>Implementation utilizes a custom <code>SetCallback-KeyClass</code>
 implementation for
 <code>void alBufferCallback1(int buffer, int format, int freq, ALBUFFERCALLBACKTYPESOFT callback, Object userptr)</code>,
@@ -2410,7 +2429,7 @@ which uses one key, i.e. <code>buffer</code>.</p>
     }</code></pre>
 <h3 id="javacallback-example-11a-homogeneous-struct-type">JavaCallback
 Example 11a (<em>Homogeneous Struct Type</em>)</h3>
-<p>This examples demonstrates a <a
+<p>This example demonstrates a <a
 href="#struct-type-user-param-homogeneous">homogeneous <em>Struct</em>
 <code>UserParam</code> mapping</a> with a <a
 href="#javacallback-key-definition">key-mapped</a>
@@ -2432,8 +2451,8 @@ method <code>MessageCallback11b(..)</code>.</p>
   void MessageCallback11a(size_t id /* key */, T2_CallbackFunc11 cbFunc, const T2_Callback11UserType* usrParam);
   void MessageCallback11aInject(size_t id, long val);  </code></pre>
 <p>and the following GlueGen configuration</p>
-<pre><code>  JavaCallbackDef  MessageCallback11a T2_CallbackFunc11 1
-  JavaCallbackKey  MessageCallback11a 0</code></pre>
+<pre><code>  JavaCallbackDef  MessageCallback11a 2 T2_CallbackFunc11 1
+  JavaCallbackKey  MessageCallback11a 0 T2_CallbackFunc11 0</code></pre>
 <p>leading to the following interface</p>
 <pre><code>  /** JavaCallback interface: T2_CallbackFunc11 -&gt; void (*T2_CallbackFunc11)(size_t id, const T2_Callback11UserType *  usrParam, long val) */
   public static interface T2_CallbackFunc11 {
@@ -2473,7 +2492,7 @@ method <code>MessageCallback11b(..)</code>.</p>
 <h3
 id="javacallback-example-11b-heterogeneous-pointerstruct-type">JavaCallback
 Example 11b (<em>Heterogeneous Pointer/Struct Type</em>)</h3>
-<p>This examples demonstrates a <a
+<p>This example demonstrates a <a
 href="#struct-type-user-param-heterogeneous">heterogeneous
 <em>Struct</em> <code>UserParam</code> mapping</a> with a <a
 href="#javacallback-key-definition">key-mapped</a>
@@ -2499,7 +2518,7 @@ users' <code>void*</code> pointer with the
   void MessageCallback11bInject(size_t id, long val);</code></pre>
 <p>and the following GlueGen configuration</p>
 <pre><code>  JavaCallbackDef  MessageCallback11b 2 T2_CallbackFunc11 1
-  JavaCallbackKey  MessageCallback11b 0</code></pre>
+  JavaCallbackKey  MessageCallback11b 0 T2_CallbackFunc11 0</code></pre>
 <p>leading to the following interface</p>
 <pre><code>  /** JavaCallback interface: T2_CallbackFunc11 -&gt; void (*T2_CallbackFunc11)(size_t id, const T2_Callback11UserType *  usrParam, long val) */
   public static interface T2_CallbackFunc11 {