From 3ed3e9887c459169b807165c9df2ae2bc2990a31 Mon Sep 17 00:00:00 2001 From: Sven Gothel Date: Thu, 6 Jul 2023 10:35:30 +0200 Subject: GlueGen JavaCallback: Remove ambiguity: Config JavaCallbackDef/JavaCallbackKey: Always define both parameter indices; emitJavaStaticCallback(): Use cbFuncBinding and cbFuncKeyIndices from callback parameter to build key --- doc/GlueGen_Mapping.html | 101 ++++++++++++++++++++++++++++------------------- 1 file changed, 60 insertions(+), 41 deletions(-) (limited to 'doc/GlueGen_Mapping.html') 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 @@
  • JavaCallback Example 1
  • JavaCallback Example 2a (Default KeyClass)
    • -
  • JavaCallback - Example 2b (Custom KeyClass)
    • +
  • JavaCallback + Example 2b (Custom KeyClass, different key-parameter + order)
  • JavaCallback Example 11a (Homogeneous Struct Type)
    • @@ -2027,27 +2029,29 @@ Object to be passed to the users'

    JavaCallback Configuration

    Configuration directives are as follows:

    -
    JavaCallbackDef  <SetCallbackFunctionName> [<SetCallback-UserParamIndex>] <CallbackFunctionType> <CallbackFunction-UserParamIndex> [<SetCallback-KeyClassName>]    
-JavaCallbackKey  <SetCallbackFunctionName> (SetCallback-ParamIdx)*
    +
    JavaCallbackDef  <SetCallbackFunctionName> <SetCallback-UserParamIndex> <CallbackFunctionType> <CallbackFunction-UserParamIndex> [<SetCallback-KeyClassName>]    
+JavaCallbackKey  <SetCallbackFunctionName> <SetCallback-ParamIndex>* <CallbackFunctionType> <CallbackFunction-ParamIndex>*

    JavaCallbackDef and JavaCallbackKey use the name of the SetCallbackFunction as its first attribute, as -it is core to the semantic mapping of all resources.

    +it is core to the semantic mapping of all resources. They also have to +use the same CallbackFunctionType.

    JavaCallbackDef attributes:

    @@ -2056,7 +2060,7 @@ hash-map-key - see below null for the CallbackFunction.

    If mapping the CallbackFunction to keys, the user must specify the same key arguments when setting and removing the -``CallbackFunction`.

    +CallbackFunction.

    JavaCallback Key Definition

    If no keys are defined via JavaCallbackKey or not @@ -2068,17 +2072,27 @@ public SetCallback-KeyClass is being generated covering the defined keys.

    Keys allow to limit the scope, i.e. map multiple CallbackFunction to the different keys.

    -

    Key arguments must match in SetCallbackFunction to -remove a previously set CallbackFunction.

    +

    To remove a previously set CallbackFunction via +SetCallbackFunction, the key arguments must match.

    JavaCallbackKey attributes

    Custom SetCallback-KeyClass

    @@ -2196,7 +2210,7 @@ and the native callback dispatcher are thread-safe
  • ...

    • JavaCallback Example 1

    -

    This examples demonstrates a This example demonstrates a homogeneous Java Object UserParam mapping with a globally scoped @@ -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 +JavaCallbackDef MessageCallback01 1 T2_CallbackFunc01 2

    Note that LibraryOnLoad Bindingtest2 must be specified in exactly one native code-unit within the library. It @@ -2269,18 +2283,18 @@ the current thread to the JavaVM* generating a new public void InjectMessageCallback01(long id, String msg);

    JavaCallback Example 2a (Default KeyClass)

    -

    This examples demonstrates a This example demonstrates a homogeneous Java Object UserParam mapping with a key-mapped CallbackFunction and UserParam.

    -

    This examples is derived from OpenAL's +

    This example is derived from OpenAL's AL_SOFT_callback_buffer extension.

    The callback ALBUFFERCALLBACKTYPESOFT is mapped to buffer name, i.e. one callback can be set for each buffer.

    C-API Header snipped

    -
      typedef void ( * ALBUFFERCALLBACKTYPESOFT)(int buffer, void *userptr, int sampledata, int numbytes);
+
      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.
    
   #   - `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
    
+  JavaCallbackDef  alBufferCallback0 4 ALBUFFERCALLBACKTYPESOFT 1
+  JavaCallbackKey  alBufferCallback0 0 ALBUFFERCALLBACKTYPESOFT 0

    leading to the following interface

      /** JavaCallback interface: ALBUFFERCALLBACKTYPESOFT -> void (*ALBUFFERCALLBACKTYPESOFT)(int buffer, void *  userptr, int sampledata, int numbytes) */
   public static interface ALBUFFERCALLBACKTYPESOFT {
@@ -2363,22 +2377,27 @@ buffer.
    
 
   /** 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);
    -

    JavaCallback Example 2b -(Custom KeyClass)

    -

    This examples demonstrates a homogeneous Java -Object UserParam mapping with a JavaCallback +Example 2b (Custom KeyClass, different key-parameter +order) +

    Similar example as example 2a, but using a custom KeyClass to map -CallbackFunction and UserParam.

    -

    Same as example 2a, but implementing a custom -SetCallback-KeyClass.

    -

    Instead of Callback0, the unit test2.* uses -Callback1 to differentiate this case.

    +CallbackFunction and UserParam and also +accommodating a different key-parameter order between +SetCallbackFunction and CallbackFunction.

    +

    C-API Header snipped

    +
      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);

    GlueGen configuration snippet with the added option attribute for the SetCallback-KeyClass in directive JavaCallbackDef.

    -
    JavaCallbackDef  alBufferCallback1 ALBUFFERCALLBACKTYPESOFT 1 com.jogamp.gluegen.test.junit.generation.Test4JavaCallback.CustomAlBufferCallback1Key
-JavaCallbackKey  alBufferCallback1 0
    +
    JavaCallbackDef  alBufferCallback1 0 ALBUFFERCALLBACKTYPESOFT 1 com.jogamp.gluegen.test.junit.generation.Test4JavaCallback.CustomAlBufferCallback1Key
+JavaCallbackKey  alBufferCallback1 1 ALBUFFERCALLBACKTYPESOFT 0
+

    Implementation utilizes a custom SetCallback-KeyClass implementation for void alBufferCallback1(int buffer, int format, int freq, ALBUFFERCALLBACKTYPESOFT callback, Object userptr), @@ -2410,7 +2429,7 @@ which uses one key, i.e. buffer.

    }

    JavaCallback Example 11a (Homogeneous Struct Type)

    -

    This examples demonstrates a This example demonstrates a homogeneous Struct UserParam mapping with a key-mapped @@ -2432,8 +2451,8 @@ method MessageCallback11b(..).

    void MessageCallback11a(size_t id /* key */, T2_CallbackFunc11 cbFunc, const T2_Callback11UserType* usrParam); void MessageCallback11aInject(size_t id, long val);

    and the following GlueGen configuration

    -
      JavaCallbackDef  MessageCallback11a T2_CallbackFunc11 1
-  JavaCallbackKey  MessageCallback11a 0
    +
      JavaCallbackDef  MessageCallback11a 2 T2_CallbackFunc11 1
+  JavaCallbackKey  MessageCallback11a 0 T2_CallbackFunc11 0

    leading to the following interface

      /** 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 MessageCallback11b(..).
    
 
    JavaCallback
 Example 11b (Heterogeneous Pointer/Struct Type)
    
-
    This examples demonstrates a This example demonstrates a heterogeneous
 Struct UserParam mapping with a key-mapped
@@ -2499,7 +2518,7 @@ users' void* pointer with the
   void MessageCallback11bInject(size_t id, long val);

    and the following GlueGen configuration

      JavaCallbackDef  MessageCallback11b 2 T2_CallbackFunc11 1
-  JavaCallbackKey  MessageCallback11b 0
    + JavaCallbackKey MessageCallback11b 0 T2_CallbackFunc11 0

    leading to the following interface

      /** JavaCallback interface: T2_CallbackFunc11 -> void (*T2_CallbackFunc11)(size_t id, const T2_Callback11UserType *  usrParam, long val) */
   public static interface T2_CallbackFunc11 {
-- 
cgit v1.2.3