diff options
| author | Sven Gothel <[email protected]> | 2023-06-16 02:16:20 +0200 |
|---|---|---|
| committer | Sven Gothel <[email protected]> | 2023-06-16 02:16:20 +0200 |
| commit | 8b127c4c1dd26fcb1756805ddb83729203161f78 (patch) | |
| tree | f8563a0e39d293bc070ef01e457cfe08ee44096d /www | |
| parent | aeadfab9572e4b441b1bc1f0708cf4c72dfe181e (diff) | |
GlueGen Struct [5]: Revised Struct Mapping + Documentation
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.
Diffstat (limited to 'www')
| -rw-r--r-- | www/index.html | 40 |
1 files changed, 27 insertions, 13 deletions
diff --git a/www/index.html b/www/index.html index 5729d74..7000629 100644 --- a/www/index.html +++ b/www/index.html @@ -10,7 +10,7 @@ <body> <div id="container"> <div id="header"> - <div id="slogan">JNI binding code generator</div> + <div id="slogan">Native Binding Generator for Java™</div> <div id="logo"><a href="http://jogamp.org/">Gluegen</a></div> </div> <div id="menu"> @@ -30,34 +30,48 @@ <div id="sidebar"> <h3>Useful Links</h3> <ul> + <li><a href="https://jogamp.org/cgit/gluegen.git/about/">GlueGen Git Repo</a></li> + <li><a href="../../deployment/jogamp-next/javadoc/gluegen/javadoc/">GlueGen API-Doc</a></li> + <li><a href="../doc/GlueGen_Mapping.html">GlueGen Native Data & Function Mapping</a></li> <li><a href="../doc/manual/">GlueGen Manual</a></li> - <li><a href="../../deployment/jogamp-next/javadoc/gluegen/javadoc/">GlueGen Runtime JavaDoc</a></li> + <li><a href="../doc/HowToBuild.html">How To Build</a></li> + <li><a href="../doc/JogAmpMacOSVersions.html">JogAmp's MacOS Version Support</a></li> </ul> </div> <div id="text" class="fill"> <p> - GlueGen is a tool which automatically generates the Java and JNI code - necessary to call C libraries. + GlueGen is a compiler for function and data-structure declarations, + generating Java™ and JNI C code offline at compile time + and allows using native libraries within your Java™ application. </p> <p> - It reads as input ANSI C header files + It reads ANSI C header files and separate configuration files which provide control over many aspects of the glue code generation. GlueGen uses a complete ANSI C parser and an internal representation (IR) capable of representing all C types to represent the APIs for which it generates interfaces. It has the ability to perform significant transformations on the IR - before glue code emission. GlueGen is currently powerful enough to - bind even low-level APIs such as the Java Native Interface (JNI) and - the AWT Native Interface (JAWT) back up to the Java programming - language. + before glue code emission. + </p> + <p> + GlueGen can produce native foreign function bindings to Java™ as well as + map native data structures to be fully accessible from Java™ including + potential calls to embedded function pointer. + </p> + <p> + GlueGen is also capable to bind even low-level APIs such as the Java™ Native Interface (JNI) and + the AWT Native Interface (JAWT) back up to the Java™ programming language. </p> <p> - GlueGen is currently used for the projects - <a href="../../jogl/www/">JOGL</a>, - <a href="../../jocl/www/">JOCL</a> and - <a href="../../joal/www/">JOAL</a>. + GlueGen utilizes <a href="https://jogamp.org/cgit/jcpp.git/about/">JCPP</a>, migrated C preprocessor written in Java™. + </p> + <p> + GlueGen is used for the JogAmp projects + <a href="../../joal/www/">JOAL</a>, + <a href="../../jogl/www/">JOGL</a> and + <a href="../../jocl/www/">JOCL</a>. </p> </div> |