diff options
Diffstat (limited to 'doc/GlueGen_Mapping.html')
| -rw-r--r-- | doc/GlueGen_Mapping.html | 101 |
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 <SetCallbackFunctionName> [<SetCallback-UserParamIndex>] <CallbackFunctionType> <CallbackFunction-UserParamIndex> [<SetCallback-KeyClassName>] -JavaCallbackKey <SetCallbackFunctionName> (SetCallback-ParamIdx)*</code></pre> +<pre><code>JavaCallbackDef <SetCallbackFunctionName> <SetCallback-UserParamIndex> <CallbackFunctionType> <CallbackFunction-UserParamIndex> [<SetCallback-KeyClassName>] +JavaCallbackKey <SetCallbackFunctionName> <SetCallback-ParamIndex>* <CallbackFunctionType> <CallbackFunction-ParamIndex>*</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 -> 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: <br> <code>void alEventCallbackInject(int eventType, int object, int param, const char * msg)</code><br> */ 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 -> 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 -> void (*T2_CallbackFunc11)(size_t id, const T2_Callback11UserType * usrParam, long val) */ public static interface T2_CallbackFunc11 { |