GlueGen Proudly Beating Panama

Thought I pitch in with this humble claim as some say it is pride month (chuckles)
and GlueGen got neglected in the latest overlord's endeavors.
(regardless, open for contracting and cooperation in this regard as well)

Blog post concluding our GlueGen updates.

Where are we with GlueGen?
- Still all offline, compile time, produced code for any Java VM >= 8
  - Verifiable and human readable
  - No runtime risks or 'production costs'
- Map native foreign function and native data structures to Java
- OO-Style API mapping as used in JOGL's incremental OpenGL Profile API levels
- Struct mapping reworked
  - No native code required for mappings w/o function pointer
  - Supporting most, if not all types including pointer-pointer and function-pointer
- Easy to use (produced) function and data mappings w/o obfuscating
  runtime code data and type arrangements.
- Java callback methods to receive asynchronous and off-thread native toolkit events
- Can produces JNI_OnLoad*(..) for dynamic and static libraries to resolve JNIEnv* handling via generated JVMUtil_GetJNIEnv(..)
- GlueGen also provides a comprehensive runtime library (see API doc)

Previous posts:
-  GlueGen/JNI versus Panama
   https://forum.jogamp.org/GlueGen-JNI-versus-Panama-td4042047.html

-  GlueGen Struct Generator Update *API Change* .. etc
   https://forum.jogamp.org/GlueGen-Struct-Generator-Update-API-Change-etc-td4042685.html#a4042709

Then we have talked about adding an XML frontend
next to our existing C-Header front producing the IR
(Intermediate Representation, or simply object tree/AST making up the structure
and used to produce the code -> backend).
Naturally, a Khronos XML API description is a first target,
planned to be tested with OpenGL and later with Vulkan perhaps.

Project web page
https://jogamp.org/gluegen/www/

A new document describing details (next to the older manual)
https://jogamp.org/gluegen/doc/GlueGen_Mapping.html

Git repo
https://jogamp.org/cgit/gluegen.git/about/

Git log
https://jogamp.org/cgit/gluegen.git/log/

API doc
https://jogamp.org/deployment/jogamp-next/javadoc/gluegen/javadoc/overview-summary.html

+++

The JogAmp project needs funding and we offer commercial support!
<https://jogamp.org/wiki/index.php?title=Maintainer_and_Contacts#Commercial_Support>

Please contact Göthel Software (Jausoft).
<https://jausoft.com/>

+++

Changes
- Added JavaCallback to supported features
- Aligned features w/ GlueGen intro (README, www, ..)

Preliminary JavaCallback documentation
  https://jogamp.org/gluegen/doc/GlueGen_Mapping.html#java-callback-from-native-c-api-support

Code checkin incomplete, generated implementation missing,
but interfaces properly produced.

First JavaCallback working draft pushed w/ docs, see git logs and perhaps

- Updated JavaCallback
  https://jogamp.org/gluegen/doc/GlueGen_Mapping.html#java-callback-from-native-c-api-support

- Updated Overview, covering (hopefully) all big bullets - beating Panama ;-)
  https://jogamp.org/gluegen/doc/GlueGen_Mapping.html#overview

Discussion:

Now we have to thing about the practical 'resource mapping',
as mentioned in the remark (*TODO: Refine ownership + release*) in
https://jogamp.org/cgit/gluegen.git/commit/?id=6591f1fef419841660311bbb554aeda7b267c9a7

Here the ownership or mapping of java userParam -> our little native
glue struct-instance.

Questions:
- Some want ThreadLocal?
- Some want a special key like a context?
  - Example: glDebugMessageCallback(..)
- Just some other argument passed to Callback-SetFunc?
  - Example: OpenAL AL_SOFT_callback_buffer extension
- ... you get the idea.

Right now it is sort of global to the binding instance.

Proposal:
One idea is to produce a CallbackFuncTypeUsrKey class,
which gets all Callback-SetFunc arguments funneled via its ctor.
This class may use any of these arguments as its key criteria
plus also use other external criteria like Thread.currentThread().
(Not performance critical here, since Callback-SetFunc gets called rarely).

Key criteria implies implementing the equals() and hashCode() functions
based on said criteria.

Of course, we would produce this class by default and only use the userParam
as key -> no default change.

The user can configure using its own CallbackFuncTypeUsrKey class definition,
where only the ctor must be same, i.e. fed with all Callback-SetFunc arguments.
User would have all freedoms to implement the actual key for the mapping.

JavaCallback key/resource management resolved

https://jogamp.org/gluegen/doc/GlueGen_Mapping.html#java-callback-from-native-c-api-support

Pushed, tested .. and well, guess API complete now.

commit a73c992290930e617c78241bae9fe20cb18a01a9

    GlueGen JavaCallback: Resolve key mapping of callback and associated resources via 'JavaCallbackKey' config and custom `SetCallback-KeyClass`
   
    Updated unit test and doc accordingly.
    Unit tests handle OpenAL's AL_SOFT_callback_buffer and AL_SOFT_events.
   
    Tested global scope (no key, default) and 1 key (default) and 1 key (custom class).
   
    Added more query functions, which all only take the `SetCallbackFunction` key arguments as specified.
   
    Cleaned up JavaCallback* config class field naminig scheme.
   
    Added 'synchronized (..Map) { }' block in crucial `SetCallbackFunction`,
    rendering implementation thread safe.

I am currently revising the 'UserParam' mapping Java <-> Native, simplifying, removing the native memory heap and allowing more options. Stay tuned ... :)

Sven Gothel wrote

I am currently revising the 'UserParam' mapping Java <-> Native, simplifying, removing the native memory heap and allowing more options. Stay tuned ... :)

I just pushed ..

https://jogamp.org/cgit/gluegen.git/commit/?id=a599b852a041ba3d80b43981589ac1390979dac2

Updated docs:
- https://jogamp.org/gluegen/doc/GlueGen_Mapping.html#java-callback

Added use-cases for 'Struct Type User Param' ...
- https://jogamp.org/gluegen/doc/GlueGen_Mapping.html#struct-type-user-param-homogeneous
- https://jogamp.org/gluegen/doc/GlueGen_Mapping.html#javacallback-example-11a-homogeneous-struct-type

covered and passed in Test4JavaCallback

Brief implementation details (more safe now)
- https://jogamp.org/gluegen/doc/GlueGen_Mapping.html#implementation-details

Added a few fixes & features while testing with AL_SOFT_events (JOAL/OpenAL)
- Added 'ArgumentIsPascalString'
- Allow 'UserParam' to be (part of) key
- Added ReleaseJNIEnv() for GetJNIEnv() .. etc

AL_SOFT_events callbacks essentially working,
will add this feature for ALAudioSink to replace polling if extension is available.

AL_SOFT_events is now exposed in JOAL and used in ALAudioSink.

The latter uses the off-thread buffer consumed count to avoid active polling via AL,
simply using the count or waiting until expected free buffers are available.
This path removes an AL context switch and reading the processed buffers from source,
i.e. should allow a slightly more sleepy and responsive behavior.

GlueGen: Add optional custom 'Callback-UserParamClass` for non-compound `UserParam` types to have more clarity in resulting API

JOAL: AL_SOFT_events: Define 'ALCcontext` as `UserParam` type for more clarity

Conclusion .. https://jausoft.com/blog/2023/08/14/gluegen-compiler-updates/