diff options
Diffstat (limited to 'doc/GlueGen_Mapping.html')
| -rw-r--r-- | doc/GlueGen_Mapping.html | 302 |
1 files changed, 260 insertions, 42 deletions
diff --git a/doc/GlueGen_Mapping.html b/doc/GlueGen_Mapping.html index 706eda4..d1b5b04 100644 --- a/doc/GlueGen_Mapping.html +++ b/doc/GlueGen_Mapping.html @@ -449,19 +449,28 @@ <li><a href="#struct-function-pointer-support">Struct Function-Pointer Support</a></li> </ul></li> - <li><a href="#java-callback-from-native-c-api-support">Java Callback - from Native C-API Support</a> + <li><a href="#java-callback">Java Callback</a> <ul> - <li><a href="#required-libraryonload">Required - <em>LibraryOnLoad</em></a></li> + <li><a href="#implementation-details">Implementation Details</a></li> + <li><a href="#javacallback-userparam-mapping"><em>JavaCallback</em> + <em>UserParam</em> Mapping</a></li> <li><a href="#javacallback-configuration"><em>JavaCallback</em> Configuration</a></li> + <li><a + href="#javacallback-generated-interfaces-classes-and-methods"><em>JavaCallback</em> + Generated Interfaces, Classes and Methods</a></li> <li><a href="#javacallback-notes"><em>JavaCallback</em> Notes</a></li> <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-11a-homogeneous-struct-type">JavaCallback + Example 11a (<em>Homogeneous Struct Type</em>)</a></li> + <li><a + href="#javacallback-example-11b-heterogeneous-pointerstruct-type">JavaCallback + Example 11b (<em>Heterogeneous Pointer/Struct Type</em>)</a></li> </ul></li> <li><a href="#misc-configurations">Misc Configurations</a> <ul> @@ -531,11 +540,10 @@ as <a href="#struct-mapping">map native data structures</a> to be fully accessible from Java™ including potential calls to <a href="#struct-function-pointer-support">embedded function pointer</a>.</p> -<p>GlueGen supports <a -href="#java-callback-from-native-c-api-support">registering Java™ -callback methods</a> to receive asynchronous and off-thread native -toolkit events, where a generated native callback function dispatches -the events to Java™.</p> +<p>GlueGen supports <a href="#java-callback">registering Java™ callback +methods</a> to receive asynchronous and off-thread native toolkit +events, where a generated native callback function dispatches the events +to Java™.</p> <p>GlueGen also supports <a href="#oo-style-api-interface-mapping">producing an OO-Style API mapping</a> like <a href="../../jogl/doc/uml/html/index.html">JOGL's @@ -1076,7 +1084,7 @@ variable</li> function pointer, see <a href="#struct-function-pointer-support">Struct Function-Pointer Support</a> below.</li> <li><em>Java Callback from Native Code</em>, see <a -href="#java-callback-from-native-c-api-support">section below</a></li> +href="#java-callback">section below</a></li> </ul> <p>A field may be a direct aggregation, i.e. instance, within the struct including an array or a reference to a single element or array via a @@ -1947,24 +1955,79 @@ StructPackage T2_InitializeOptions com.jogamp.gluegen.test.junit.generation</cod /** Interface to C language function: <br> <code>int32_t CustomFuncB1(T2_UserData * pUserData)</code><br> */ public final int CustomFuncB1(T2_UserData pUserData) { .. } </code></pre> -<h2 id="java-callback-from-native-c-api-support">Java Callback from -Native C-API Support</h2> +<h2 id="java-callback">Java Callback</h2> <p>GlueGen supports registering Java callback methods to receive asynchronous and off-thread native toolkit events, where a generated native callback function dispatches the events to Java.</p> -<h3 id="required-libraryonload">Required <em>LibraryOnLoad</em></h3> -<p>Note that <a -href="#libraryonload-librarybasename-for-jni_onload-"><code>LibraryOnLoad Bindingtest2</code></a> -must be specified in exactly one native code-unit. It provides code to -allow the generated native callback-function to attach the current -thread to the <code>JavaVM*</code> generating a new -<code>JNIEnv*</code>in daemon mode - or just to retrieve the thread's -<code>JNIEnv*</code>, if already attached to the -<code>JavaVM*</code>.</p> +<h3 id="implementation-details">Implementation Details</h3> +<p>Implementation generates a static Java callback dispatcher for each +defined <code>SetCallbackFunction</code>, which gets invoked by the +generated native static counterpart with all arguments required.</p> +<p>The <em>static callback</em> utilizes its own synchronization for +thread-safety and fetches the required data set stored at +<code>SetCallbackFunction</code> to dispatch the call to the users' +<code>CallbackFunction</code>.<br /> +In case the callback has been removed already, the <em>static +callback</em> simply bails out quietly.</p> +<p>The native code does not create, release or manage heap memory and +therefore is considered safe.</p> +<h3 id="javacallback-userparam-mapping"><em>JavaCallback</em> +<em>UserParam</em> Mapping</h3> +<p>Usually the same <code>UserParam</code> type is used in both items +(or hooks), <code>SetCallbackFunctionName</code> and +<code>CallbackFunctionType</code>, which we call a homogeneous +<code>UserParam</code> mapping.</p> +<p>Even in a homogeneous <code>UserParam</code> mapping, handling of the +<code>UserParam</code> value might differ in the native binding +code.</p> +<p>To specify a non homogeneous <code>UserParam</code> mapping, i.e. +heterogeneous <code>UserParam</code> mapping, the <code>UserParam</code> +index of the <code>SetCallbackFunction</code> must be <a +href="#javacallback-configuration">set in the configuration</a>.</p> +<p>The following mappings are supported.</p> +<h4 id="pure-java-object-user-type-default">Pure Java Object User Type +(default)</h4> +<p>A pure Java <em>Object type</em> is used for both, +<code>SetCallbackFunctionName</code> and +<code>CallbackFunctionType</code>.</p> +<p>It's a homogeneous <code>UserParam</code> mapping, where the native +side receives a simple unique ID and shall not dereference the +<em>pointer</em>.</p> +<p>The static Java callback dispatcher fetches the Java +<code>UserParam</code> <em>Object</em> from the key-mapped data +value.</p> +<h4 id="struct-type-user-param-homogeneous">Struct Type User Param +(Homogeneous)</h4> +<p>A <a href="#struct-mapping">GlueGen generated <em>Struct +type</em></a> is used for both, <code>SetCallbackFunctionName</code> and +<code>CallbackFunctionType</code>.</p> +<p>It's a homogeneous <code>UserParam</code> mapping, where the native +side receives the actual native struct address.</p> +<p>The static Java callback dispatcher dereferences the received native +struct address (<em>long</em>), i.e. rebuilding the <em>struct +Object</em> to be passed to the users' +<code>CallbackFunction</code>.</p> +<h4 id="struct-type-user-param-heterogeneous">Struct Type User Param +(Heterogeneous)</h4> +<p>An anonymous pointer (<em>long</em>) for +<code>SetCallbackFunctionName</code> and a <a +href="#struct-mapping">GlueGen generated <em>struct type</em></a> for +<code>CallbackFunctionType</code> is being used.</p> +<p>It's a heterogeneous <code>UserParam</code> mapping, where the +toolkit is expected to place the given anonymous pointer inside the +defined <em>struct type</em> passed to the +<code>CallbackFunction</code>.</p> +<p>The <code>SetCallback-UserParamIndex</code> for the different +parameter-type is <a href="#javacallback-configuration">set in the +configuration</a>.</p> +<p>The static Java callback dispatcher dereferences the received native +struct address (<em>long</em>), i.e. rebuilding the <em>struct +Object</em> to be passed to the users' +<code>CallbackFunction</code>.</p> <h3 id="javacallback-configuration"><em>JavaCallback</em> Configuration</h3> <p>Configuration directives are as follows:</p> -<pre><code>JavaCallbackDef <SetCallbackFunctionName> <CallbackFunctionType> <CallbackFunction-UserParamIndex> [<SetCallback-KeyClassName>] +<pre><code>JavaCallbackDef <SetCallbackFunctionName> [<SetCallback-UserParamIndex>] <CallbackFunctionType> <CallbackFunction-UserParamIndex> [<SetCallback-KeyClassName>] JavaCallbackKey <SetCallbackFunctionName> (SetCallback-ParamIdx)*</code></pre> <p><code>JavaCallbackDef</code> and <code>JavaCallbackKey</code> use the name of the <code>SetCallbackFunction</code> as its first attribute, as @@ -1973,6 +2036,11 @@ it is core to the semantic mapping of all resources.</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>CallbackFunctionType</code>: The native toolkit API typedef-name of the function-pointer-type, aka the callback type name</li> @@ -2012,9 +2080,35 @@ 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> </ul> -<h4 +<h4 id="custom-setcallback-keyclass">Custom +<code>SetCallback-KeyClass</code></h4> +<p>The <code>SetCallback-KeyClass</code> is the optional user-written +hash-map-key definition and shall handle all key parameter of the +<code>SetCallbackFunction</code> as defined via +<code>JavaCallbackKey</code>, see above.</p> +<p><code>SetCallback-KeyClass</code> may be used to add external +key-components, e.g. current-thread or a toolkit dependent context.</p> +<p>The <code>SetCallback-KeyClass</code> shall implement the following +hash-map-key standard methods</p> +<ul> +<li><code>boolean equals(Object)</code></li> +<li><code>int hashCode()</code></li> +<li><code>SetCallback-KeyClassName(...)</code> constructor receiving all +key parameter of <code>SetCallbackFunction</code> as defined via +<code>JavaCallbackKey</code>, see above.</li> +</ul> +<h4 id="required-libraryonload">Required <em>LibraryOnLoad</em></h4> +<p>Note that <a +href="#libraryonload-librarybasename-for-jni_onload-"><code>LibraryOnLoad Bindingtest2</code></a> +must be specified in exactly one native code-unit. It provides code to +allow the generated native callback-function to attach the current +thread to the <code>JavaVM*</code> generating a new +<code>JNIEnv*</code>in daemon mode - or just to retrieve the thread's +<code>JNIEnv*</code>, if already attached to the +<code>JavaVM*</code>.</p> +<h3 id="javacallback-generated-interfaces-classes-and-methods"><em>JavaCallback</em> -Generated Interfaces, Classes and Methods</h4> +Generated Interfaces, Classes and Methods</h3> <p>The public <code>CallbackFunction</code> interface is generated.</p> <p>The default public <code>SetCallback-KeyClass</code> is generated if keys are used and no custom class is specified, see above.</p> @@ -2068,23 +2162,6 @@ and <em>releaseAll<code>SetCallbackFunctionName</code>()</em> methods are not the <em>proper toolkit API way</em> to remove the callback, try to use original <code>SetCallbackFunctionName</code> API method instead using a <code>null</code> <code>CallbackFunction</code> reference.</p> -<h4 id="custom-setcallback-keyclass">Custom -<code>SetCallback-KeyClass</code></h4> -<p>The <code>SetCallback-KeyClass</code> is the optional user-written -hash-map-key definition and shall handle all key parameter of the -<code>SetCallbackFunction</code> as defined via -<code>JavaCallbackKey</code>, see above.</p> -<p><code>SetCallback-KeyClass</code> may be used to add external -key-components, e.g. current-thread or a toolkit dependent context.</p> -<p>The <code>SetCallback-KeyClass</code> shall implement the following -hash-map-key standard methods</p> -<ul> -<li><code>boolean equals(Object)</code></li> -<li><code>int hashCode()</code></li> -<li><code>SetCallback-KeyClassName(...)</code> constructor receiving all -key parameter of <code>SetCallbackFunction</code> as defined via -<code>JavaCallbackKey</code>, see above.</li> -</ul> <h3 id="javacallback-notes"><em>JavaCallback</em> Notes</h3> <p>Please consider the following <em>currently enabled</em> constraints using JavaCallback</p> @@ -2118,7 +2195,11 @@ 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 is a generic example.</p> +<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 +href="#javacallback-key-definition">globally scoped</a> +<code>CallbackFunction</code> and <code>UserParam</code>.</p> <p>The callback <code>T2_CallbackFunc01</code> has global scope, i.e. is not mapped to any key and can be only set globally.</p> <p>C-API header snippet:</p> @@ -2187,6 +2268,11 @@ 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 +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 <code>AL_SOFT_callback_buffer</code> extension.</p> <p>The callback <code>ALBUFFERCALLBACKTYPESOFT</code> is mapped to @@ -2278,6 +2364,11 @@ buffer.</p> 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 +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 @@ -2316,6 +2407,133 @@ which uses one key, i.e. <code>buffer</code>.</p> return "CustomALKey[this "+toHexString(System.identityHashCode(this))+", buffer "+buffer+"]"; } }</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 +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> +<code>CallbackFunction</code> and <code>UserParam</code>.</p> +<p>The callback <code>T2_CallbackFunc11</code> is passed by the toolkit +to the <code>CallbackFunction</code> and by the user to the registration +method <code>MessageCallback11b(..)</code>.</p> +<p>C-API Header snipped</p> +<pre><code> typedef struct { + int32_t ApiVersion; + void* Data; + long i; + long r; + size_t id; + } T2_Callback11UserType; + + typedef void ( * T2_CallbackFunc11)(size_t id, const T2_Callback11UserType* usrParam, long val); + + 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> +<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 { + /** Interface to C language function: <br> <code>void callback(size_t id, const T2_Callback11UserType * usrParam, long val)</code><br>Alias for: <code>T2_CallbackFunc11</code> */ + public void callback(long id, T2_Callback11UserType usrParam, long val); + } + + ... + + public static class MessageCallback11aKey { ... } + + ... + + /** Returns set of Key { long id } for <br> <code> void MessageCallback11a(long id, T2_CallbackFunc11 cbFunc, T2_Callback11UserType usrParam)</code> */ + public Set<MessageCallback11aKey> getMessageCallback11aKeys(); + + /** Returns whether callback Key { long id } is mapped for <br> <code> void MessageCallback11a(long id, T2_CallbackFunc11 cbFunc, T2_Callback11UserType usrParam)</code> */ + public boolean isMessageCallback11aMapped(MessageCallback11aKey key); + + /** Returns T2_CallbackFunc11 callback mapped to Key { long id } for <br> <code> void MessageCallback11a(long id, T2_CallbackFunc11 cbFunc, T2_Callback11UserType usrParam)</code> */ + public T2_CallbackFunc11 getMessageCallback11a(MessageCallback11aKey key); + + /** Returns user-param mapped to Key { long id } for <br> <code> void MessageCallback11a(long id, T2_CallbackFunc11 cbFunc, T2_Callback11UserType usrParam)</code> */ + public Object getMessageCallback11aUserParam(MessageCallback11aKey key); + + /** Releases all callback data mapped via Key { long id } skipping toolkit API. Favor passing `null` callback ref to <br> <code> void MessageCallback11a(long id, T2_CallbackFunc11 cbFunc, T2_Callback11UserType usrParam)</code> */ + public int releaseAllMessageCallback11a(); + + /** Releases callback data mapped to Key { long id } skipping toolkit API. Favor passing `null` callback ref to <br> <code> void MessageCallback11a(long id, T2_CallbackFunc11 cbFunc, T2_Callback11UserType usrParam)</code> */ + public void releaseMessageCallback11a(MessageCallback11aKey key); + + /** Entry point (through function pointer) to C language function: <br> <code>void MessageCallback11a(size_t id, T2_CallbackFunc11 cbFunc, const T2_Callback11UserType * usrParam)</code><br> */ + public void MessageCallback11a(long id, T2_CallbackFunc11 cbFunc, T2_Callback11UserType usrParam); + + /** Entry point (through function pointer) to C language function: <br> <code>void MessageCallback11aInject(size_t id, long val)</code><br> */ + public void MessageCallback11aInject(long id, long val); </code></pre> +<h3 +id="javacallback-example-11b-heterogeneous-pointerstruct-type">JavaCallback +Example 11b (<em>Heterogeneous Pointer/Struct Type</em>)</h3> +<p>This examples 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> +<code>CallbackFunction</code> and <code>UserParam</code>.</p> +<p>The callback <code>T2_CallbackFunc11</code> is managed by the toolkit +and passed to the callback function, while user passes a <em>void</em> +with the registration method <code>MessageCallback11b(..)</code>. The +toolkit associates the users' <code>void*</code> pointer with the +<code>T2_CallbackFunc11</code>.</p> +<p>C-API Header snipped</p> +<pre><code> typedef struct { + int32_t ApiVersion; + void* Data; + long i; + long r; + size_t id; + } T2_Callback11UserType; + + typedef void ( * T2_CallbackFunc11)(size_t id, const T2_Callback11UserType* usrParam, long val); + + void MessageCallback11b(size_t id /* key */, T2_CallbackFunc11 cbFunc, void* Data); + 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> +<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 { + /** Interface to C language function: <br> <code>void callback(size_t id, const T2_Callback11UserType * usrParam, long val)</code><br>Alias for: <code>T2_CallbackFunc11</code> */ + public void callback(long id, T2_Callback11UserType usrParam, long val); + } + + ... + + public static class MessageCallback11bKey { ... } + + ... + + /** Returns set of Key { long id } for <br> <code> void MessageCallback11b(long id, T2_CallbackFunc11 cbFunc, long Data)</code> */ + public Set<MessageCallback11bKey> getMessageCallback11bKeys(); + + /** Returns whether callback Key { long id } is mapped for <br> <code> void MessageCallback11b(long id, T2_CallbackFunc11 cbFunc, long Data)</code> */ + public boolean isMessageCallback11bMapped(MessageCallback11bKey key); + + /** Returns T2_CallbackFunc11 callback mapped to Key { long id } for <br> <code> void MessageCallback11b(long id, T2_CallbackFunc11 cbFunc, long Data)</code> */ + public T2_CallbackFunc11 getMessageCallback11b(MessageCallback11bKey key); + + /** Returns user-param mapped to Key { long id } for <br> <code> void MessageCallback11b(long id, T2_CallbackFunc11 cbFunc, long Data)</code> */ + public Object getMessageCallback11bUserParam(MessageCallback11bKey key); + + /** Releases all callback data mapped via Key { long id } skipping toolkit API. Favor passing `null` callback ref to <br> <code> void MessageCallback11b(long id, T2_CallbackFunc11 cbFunc, long Data)</code> */ + public int releaseAllMessageCallback11b(); + + /** Releases callback data mapped to Key { long id } skipping toolkit API. Favor passing `null` callback ref to <br> <code> void MessageCallback11b(long id, T2_CallbackFunc11 cbFunc, long Data)</code> */ + public void releaseMessageCallback11b(MessageCallback11bKey key); + + /** Entry point (through function pointer) to C language function: <br> <code>void MessageCallback11b(size_t id, T2_CallbackFunc11 cbFunc, void * Data)</code><br> */ + public void MessageCallback11b(long id, T2_CallbackFunc11 cbFunc, long Data); + + /** Entry point (through function pointer) to C language function: <br> <code>void MessageCallback11bInject(size_t id, long val)</code><br> */ + public void MessageCallback11bInject(long id, long val); </code></pre> <p><em>TODO: Enhance documentation</em></p> <h2 id="misc-configurations">Misc Configurations</h2> <h3 |