Login  Register

GlueGen Struct Generator Update *API Change* .. etc

Posted by Sven Gothel on Jun 16, 2023; 1:45am
URL: https://forum.jogamp.org/GlueGen-Struct-Generator-Update-API-Change-etc-tp4042685.html

I made a detailed overhaul of GlueGen's Struct Code Generator.

(Next desired step: Adding callback-generator C -> Java for C-function callbacks)

Documentation:
- New document covering GlueGen in general
  <https://jogamp.org/cgit/gluegen.git/about/doc/GlueGen_Mapping.md>

- Specifically Struct Mapping (what has changes)
  <https://jogamp.org/cgit/gluegen.git/about/doc/GlueGen_Mapping.md#struct-mapping>

- Actual JavaEmitter commit with details
  <https://jogamp.org/cgit/gluegen.git/commit/?id=8b127c4c1dd26fcb1756805ddb83729203161f78>

- All git changes visible as usual here
  <https://jogamp.org/cgit/gluegen.git/log/>

The JOAL, JOGL and JOCL changes were minimal:
<https://jogamp.org/cgit/joal.git/log/>
<https://jogamp.org/cgit/jogl.git/log/>
<https://jogamp.org/cgit/jocl.git/log/>

Further I updated
- GlueGen git about <https://jogamp.org/cgit/gluegen.git/about/>
- GlueGen web <https://jogamp.org/gluegen/www/>

Please discuss ... below the copy & paste of the
main git commit message of JavaEmitter commit with details
<https://jogamp.org/cgit/gluegen.git/commit/?id=8b127c4c1dd26fcb1756805ddb83729203161f78>

GlueGen Revised Struct Mapping (esp pointer to array or single element), Struct String Charset, .. and Documentation

- Documentation:
    - Added README.md
      Let's have a proper face for the git repo

    - Added doc/GlueGen_Mapping.md (and its html conversion doc/GlueGen_Mapping.html)
      Created a new document covering application and implementation details suitable for users/devs.

    - Added doc/JogAmpMacOSVersions.md conversion to doc/JogAmpMacOSVersions.html

    - Updated www/index.html

- Use *CodeUnit instead of PrintWriter, representing a Java or C code unit covering a set of functions and structs.
    The CCodeUnit also handles common code shared by its unit across functions etc.

- Dropping 'static initializer', as its no more required
    due to simplified `JVMUtil_NewDirectByteBufferCopy()` variant.

- Revised Struct Mapping:
  - Pure Java implementation to map primitive and struct fields within a struct
    by utilizing ElementBuffer.

    Only 'Function Pointer' fields within a struct require native code.

    Exposes `static boolean usesNativeCode()` to query whether native code is used/required.

  - Transparent native memory address API

    Expose `long getDirectBufferAddress()` and `static TK_Struct derefPointer(long addr)`,
    allowing to
    - pass the native struct-pointer with native code
    - reconstruct the struct from a native struct-pointer
    - have a fully functional `TK_Struct.derefPointer(struct.getDirectBufferAddress())` cycle.

  - Add 'boolean is<Val>Null() to query whether a pointer (array) is NULL

  - *Changed* array get/set method for more flexibility alike `System.arraycopy(src, srcPos, dest, destPos, len)`,
    where 'src' is being dropped for the getter and 'dest' is being dropped for the setter
    as both objects are reflected by the struct instance.

  - *Changed* `get<Val>ArrayLength()` -> `get<Val>ElemCount()` for clarity

  - Considering all ConstElemCount values with config 'ReturnedArrayLength <int>'
    to be owned by native code -> NativeOwnership -> Not changing the underlying memory region!
    JavaOwnership is considered for all pointer-arrays not of NativeOwnership.
    Hence any setter on a NativeOwnership pointer-array will fail with non-matching elem-count.

  - Add 'release<Val>()' for JavaOwnership pointer-arrays,
    allowing to release the Java owned native memory incl. null-ing pointer and set<Val>ElemCount(0).

  - Support setter for 'const <type>*' w/ JavaOwnership, i.e. pointer to const value of a primitive or struct,
    setter and getter using pointer to array or single element in general.

  - Added Config `ImmutableAccess symbol` to disable all setter for whole struct or a field

  - Added Config `MaxOneElement symbol` to restrict a pointer to maximum one element and unset
    initial value (zero elements)

  - Added Config `ReturnsStringOnly symbol` to restrict mapping only to a Java String,
    dropping the ByteBuffer variant for 'char'

  - String mapping default is UTF-8 and can be read and set via [get|set]Charset(..) per class.

  - Dynamic string length retrieval in case no `ReturnedArrayLength` has been configured
    has changed from `strlen()` to `strnlen(aptr, max_len)` to be on the safe site.

    The maximum length default is 8192 bytes and can be read and set via [get|set]MaxStrnlen(..) per class.

    FIXME: strnlen(..) using EOS byte non-functional for non 8-bit codecs like UTF-8, US-ASCII.
           This is due to e.g. UTF-16 doesn't use an EOS byte, but interprets it as part of a code point.

  - TODO: Perhaps a few more unit tests

  - TODO: Allow plain 'int' to be mapped in structs IFF their size is same for all MachineDescriptions used.
          Currently this is the case -> 4 bytes like int32_t.