diff options
| author | Sven Gothel <[email protected]> | 2023-06-17 07:07:52 +0200 |
|---|---|---|
| committer | Sven Gothel <[email protected]> | 2023-06-17 07:07:52 +0200 |
| commit | 42bd110d9ec63594cc028f3ee8a459424b1d2ae0 (patch) | |
| tree | 531692b8d1c29f0323767ca9386c31c6ea383ea3 /doc/GlueGen_Mapping.html | |
| parent | f364dd017e548d1b61b0b01ecd4ab2dbe4924d76 (diff) | |
Drop .md -> .html generated docs (ugly), use our cgit md -> html via refined pandoc styles
Would need to fix my standalone pandoc setup to produce proper standalone docs.
Diffstat (limited to 'doc/GlueGen_Mapping.html')
| -rw-r--r-- | doc/GlueGen_Mapping.html | 1054 |
1 files changed, 0 insertions, 1054 deletions
diff --git a/doc/GlueGen_Mapping.html b/doc/GlueGen_Mapping.html deleted file mode 100644 index 28e1e62..0000000 --- a/doc/GlueGen_Mapping.html +++ /dev/null @@ -1,1054 +0,0 @@ -<!DOCTYPE html> -<html xmlns="http://www.w3.org/1999/xhtml" lang="" xml:lang=""> -<head> - <meta charset="utf-8" /> - <meta name="generator" content="pandoc" /> - <meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes" /> - <title>GlueGen_Mapping.md</title> - <style> - code{white-space: pre-wrap;} - span.smallcaps{font-variant: small-caps;} - span.underline{text-decoration: underline;} - div.column{display: inline-block; vertical-align: top; width: 50%;} - div.hanging-indent{margin-left: 1.5em; text-indent: -1.5em;} - ul.task-list{list-style: none;} - .display.math{display: block; text-align: center; margin: 0.5rem auto;} - </style> - <link rel="stylesheet" href="/usr/local/projects/Text_Processing/pandoc-buttondown-cgit/pandoc-data/css/cgit-buttondown.css" /> -</head> -<body> -<nav id="TOC" role="doc-toc"> - <strong>Contents</strong><label for="contents">⊕</label> - <input type="checkbox" id="contents"> - <ul> - <li><a href="#gluegen-native-data--function-mapping-for-java">GlueGen - Native Data & Function Mapping for Java™</a> - <ul> - <li><a href="#references">References</a></li> - <li><a href="#overview">Overview</a></li> - <li><a href="#primitive-mapping">Primitive Mapping</a> - <ul> - <li><a href="#string-mapping">String Mapping</a></li> - <li><a href="#alignment-for-compound-data">Alignment for Compound - Data</a></li> - </ul></li> - <li><a href="#struct-mapping">Struct Mapping</a> - <ul> - <li><a href="#gluegen-struct-settings">GlueGen Struct - Settings</a></li> - <li><a href="#struct-mapping-notes">Struct Mapping Notes</a></li> - <li><a href="#struct-java-signature-table">Struct Java Signature - Table</a></li> - <li><a href="#struct-setter-pseudo-code">Struct Setter - Pseudo-Code</a></li> - </ul></li> - <li><a href="#platform-header-files">Platform Header Files</a></li> - <li><a href="#pre-defined-macros">Pre-Defined Macros</a></li> - </ul></li> - </ul> -</nav> -<style> -table, th, td { - border: 1px solid black; -} -</style> - -<h1 id="gluegen-native-data--function-mapping-for-java">GlueGen Native -Data & Function Mapping for Java™</h1> -<h2 id="references">References</h2> -<ul> -<li><a href="https://jogamp.org/cgit/gluegen.git/about/">GlueGen Git -Repo</a></li> -<li><a -href="https://jogamp.org/deployment/jogamp-next/javadoc/gluegen/javadoc/">GlueGen -Java™ API-Doc</a></li> -<li><a href="https://jogamp.org/gluegen/doc/manual/">GlueGen -Manual</a></li> -<li><a href="https://jogamp.org/gluegen/www/">GlueGen Project -Page</a></li> -<li><a href="https://jogamp.org/gluegen/doc/HowToBuild.html">How To -Build</a></li> -</ul> -<h2 id="overview">Overview</h2> -<p><a href="https://jogamp.org/gluegen/www/">GlueGen</a> 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 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.</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 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 <a href="https://jogamp.org">JogAmp</a> -projects <a href="https://jogamp.org/cgit/joal.git/about/">JOAL</a>, <a -href="https://jogamp.org/cgit/jogl.git/about/">JOGL</a> and <a -href="https://jogamp.org/cgit/jocl.git/">JOCL</a>.</p> -<p>GlueGen is part of <a href="https://jogamp.org">the JogAmp -project</a>.</p> -<h2 id="primitive-mapping">Primitive Mapping</h2> -<p>Gluegen has build-in types (terminal symbols) for:</p> -<table> -<thead> -<tr class="header"> -<th style="text-align: left;">type</th> -<th style="text-align: left;">java-bits</th> -<th style="text-align: left;">native-bits <br> x32</th> -<th style="text-align: left;">native bits <br> x64</th> -<th style="text-align: left;">type</th> -<th style="text-align: left;">signed</th> -<th style="text-align: left;">origin</th> -</tr> -</thead> -<tbody> -<tr class="odd"> -<td style="text-align: left;">void</td> -<td style="text-align: left;">0</td> -<td style="text-align: left;">0</td> -<td style="text-align: left;">0</td> -<td style="text-align: left;">void</td> -<td style="text-align: left;">void</td> -<td style="text-align: left;">ANSI-C</td> -</tr> -<tr class="even"> -<td style="text-align: left;">char</td> -<td style="text-align: left;">8</td> -<td style="text-align: left;">8</td> -<td style="text-align: left;">8</td> -<td style="text-align: left;">integer</td> -<td style="text-align: left;">any</td> -<td style="text-align: left;">ANSI-C</td> -</tr> -<tr class="odd"> -<td style="text-align: left;">short</td> -<td style="text-align: left;">16</td> -<td style="text-align: left;">16</td> -<td style="text-align: left;">16</td> -<td style="text-align: left;">integer</td> -<td style="text-align: left;">any</td> -<td style="text-align: left;">ANSI-C</td> -</tr> -<tr class="even"> -<td style="text-align: left;">int</td> -<td style="text-align: left;">32</td> -<td style="text-align: left;">32</td> -<td style="text-align: left;">32</td> -<td style="text-align: left;">integer</td> -<td style="text-align: left;">any</td> -<td style="text-align: left;">ANSI-C</td> -</tr> -<tr class="odd"> -<td style="text-align: left;">long</td> -<td style="text-align: left;">64</td> -<td style="text-align: left;">32</td> -<td style="text-align: left;"><strong>32</strong>†</td> -<td style="text-align: left;">integer</td> -<td style="text-align: left;">any</td> -<td style="text-align: left;">ANSI-C - Windows</td> -</tr> -<tr class="even"> -<td style="text-align: left;">long</td> -<td style="text-align: left;">64</td> -<td style="text-align: left;">32</td> -<td style="text-align: left;"><strong>64</strong></td> -<td style="text-align: left;">integer</td> -<td style="text-align: left;">any</td> -<td style="text-align: left;">ANSI-C - Unix</td> -</tr> -<tr class="odd"> -<td style="text-align: left;">float</td> -<td style="text-align: left;">32</td> -<td style="text-align: left;">32</td> -<td style="text-align: left;">32</td> -<td style="text-align: left;">float</td> -<td style="text-align: left;">signed</td> -<td style="text-align: left;">ANSI-C</td> -</tr> -<tr class="even"> -<td style="text-align: left;">double</td> -<td style="text-align: left;">64</td> -<td style="text-align: left;">64</td> -<td style="text-align: left;">64</td> -<td style="text-align: left;">double</td> -<td style="text-align: left;">signed</td> -<td style="text-align: left;">ANSI-C</td> -</tr> -<tr class="odd"> -<td style="text-align: left;">__int32</td> -<td style="text-align: left;">32</td> -<td style="text-align: left;">32</td> -<td style="text-align: left;">32</td> -<td style="text-align: left;">integer</td> -<td style="text-align: left;">any</td> -<td style="text-align: left;">windows</td> -</tr> -<tr class="even"> -<td style="text-align: left;">__int64</td> -<td style="text-align: left;">64</td> -<td style="text-align: left;">64</td> -<td style="text-align: left;">64</td> -<td style="text-align: left;">integer</td> -<td style="text-align: left;">any</td> -<td style="text-align: left;">windows</td> -</tr> -<tr class="odd"> -<td style="text-align: left;">int8_t</td> -<td style="text-align: left;">8</td> -<td style="text-align: left;">8</td> -<td style="text-align: left;">8</td> -<td style="text-align: left;">integer</td> -<td style="text-align: left;">signed</td> -<td style="text-align: left;">stdint.h</td> -</tr> -<tr class="even"> -<td style="text-align: left;">uint8_t</td> -<td style="text-align: left;">8</td> -<td style="text-align: left;">8</td> -<td style="text-align: left;">8</td> -<td style="text-align: left;">integer</td> -<td style="text-align: left;">unsigned</td> -<td style="text-align: left;">stdint.h</td> -</tr> -<tr class="odd"> -<td style="text-align: left;">int16_t</td> -<td style="text-align: left;">16</td> -<td style="text-align: left;">16</td> -<td style="text-align: left;">16</td> -<td style="text-align: left;">integer</td> -<td style="text-align: left;">signed</td> -<td style="text-align: left;">stdint.h</td> -</tr> -<tr class="even"> -<td style="text-align: left;">uint16_t</td> -<td style="text-align: left;">16</td> -<td style="text-align: left;">16</td> -<td style="text-align: left;">16</td> -<td style="text-align: left;">integer</td> -<td style="text-align: left;">unsigned</td> -<td style="text-align: left;">stdint.h</td> -</tr> -<tr class="odd"> -<td style="text-align: left;">int32_t</td> -<td style="text-align: left;">32</td> -<td style="text-align: left;">32</td> -<td style="text-align: left;">32</td> -<td style="text-align: left;">integer</td> -<td style="text-align: left;">signed</td> -<td style="text-align: left;">stdint.h</td> -</tr> -<tr class="even"> -<td style="text-align: left;">uint32_t</td> -<td style="text-align: left;">32</td> -<td style="text-align: left;">32</td> -<td style="text-align: left;">32</td> -<td style="text-align: left;">integer</td> -<td style="text-align: left;">unsigned</td> -<td style="text-align: left;">stdint.h</td> -</tr> -<tr class="odd"> -<td style="text-align: left;">int64_t</td> -<td style="text-align: left;">64</td> -<td style="text-align: left;">64</td> -<td style="text-align: left;">64</td> -<td style="text-align: left;">integer</td> -<td style="text-align: left;">signed</td> -<td style="text-align: left;">stdint.h</td> -</tr> -<tr class="even"> -<td style="text-align: left;">uint64_t</td> -<td style="text-align: left;">64</td> -<td style="text-align: left;">64</td> -<td style="text-align: left;">64</td> -<td style="text-align: left;">integer</td> -<td style="text-align: left;">unsigned</td> -<td style="text-align: left;">stdint.h</td> -</tr> -<tr class="odd"> -<td style="text-align: left;">intptr_t</td> -<td style="text-align: left;">64</td> -<td style="text-align: left;">32</td> -<td style="text-align: left;">64</td> -<td style="text-align: left;">integer</td> -<td style="text-align: left;">signed</td> -<td style="text-align: left;">stdint.h</td> -</tr> -<tr class="even"> -<td style="text-align: left;">uintptr_t</td> -<td style="text-align: left;">64</td> -<td style="text-align: left;">32</td> -<td style="text-align: left;">64</td> -<td style="text-align: left;">integer</td> -<td style="text-align: left;">unsigned</td> -<td style="text-align: left;">stdint.h</td> -</tr> -<tr class="odd"> -<td style="text-align: left;">ptrdiff_t</td> -<td style="text-align: left;">64</td> -<td style="text-align: left;">32</td> -<td style="text-align: left;">64</td> -<td style="text-align: left;">integer</td> -<td style="text-align: left;">signed</td> -<td style="text-align: left;">stddef.h</td> -</tr> -<tr class="even"> -<td style="text-align: left;">size_t</td> -<td style="text-align: left;">64</td> -<td style="text-align: left;">32</td> -<td style="text-align: left;">64</td> -<td style="text-align: left;">integer</td> -<td style="text-align: left;">unsigned</td> -<td style="text-align: left;">stddef.h</td> -</tr> -<tr class="odd"> -<td style="text-align: left;">wchar_t</td> -<td style="text-align: left;">32</td> -<td style="text-align: left;">32</td> -<td style="text-align: left;">32</td> -<td style="text-align: left;">integer</td> -<td style="text-align: left;">signed</td> -<td style="text-align: left;">stddef.h</td> -</tr> -</tbody> -</table> -<p><strong>Warning:</strong> Try to avoid unspecified bit sized types, -especially <strong>long</strong>, since it differs on Unix and -Windows!<br /> -<strong>Notes:</strong></p> -<ul> -<li>† Type <strong>long</strong> will result in broken code on Windows, -since we don't differentiate the OS and it's bit size is ambiguous.</li> -<li>Anonymous void-pointer <em>void*</em> are mapped to NIO -<em>Buffer</em>.</li> -<li>Pointers to pointer-size types like <em>intptr_t*</em>, -<em>uintptr_t*</em>, <em>ptrdiff_t*</em> and <em>size_t*</em> are mapped -to <em>PointerBuffer</em>, to reflect the architecture depending storage -size.</li> -</ul> -<h3 id="string-mapping">String Mapping</h3> -<h4 id="function-return-string-values">Function return String -values</h4> -<p>Function return values are currently mapped from <code>char*</code> -to Java String using <em>UTF-8</em> via JNI function</p> -<blockquote> -<p><code>jstring NewStringUTF(JNIEnv *env, const char *bytes)</code></p> -</blockquote> -<p><em>FIXME</em>: This might need more flexibility in case UTF-8 is not -suitable for 8-bit wide <code>char</code> mappings or wide characters, -e.g. for UTF-16 needs to be supported.</p> -<h4 id="function-argument-string-values">Function argument String -values</h4> -<p>Function argument values are either mapped from <code>char*</code> to -Java String using <em>UTF-8</em> via JNI function</p> -<blockquote> -<p><code>const char * GetStringUTFChars(JNIEnv *env, jstring string, jboolean *isCopy)</code>.</p> -</blockquote> -<p>Alternatively, if a 16-bit wide <em>character</em> type has been -detected, i.e. <em>short</em>, the native <em>character</em> are mapped -to Java using <em>UTF-16</em> via JNI function</p> -<blockquote> -<p><code>void GetStringRegion(JNIEnv *env, jstring str, jsize start, jsize len, jchar *buf)</code>.</p> -</blockquote> -<h4 id="struct-string-mapping">Struct String mapping</h4> -<p>String value mapping for <code>Struct</code> fields is performed -solely from the Java side using <em>Charset</em> and is hence most -flexible.</p> -<p>By default, <em>UTF-8</em> is being used for getter and setter of -String values.<br /> -The <em>Struct</em> class provides two methods to get and set the used -<em>Charset</em> for conversion</p> -<pre><code> /** Returns the Charset for this class's String mapping, default is StandardCharsets.UTF_8. */ - public static Charset getCharset() { return _charset; }; - - /** Sets the Charset for this class's String mapping, default is StandardCharsets.UTF_8. */ - public static void setCharset(Charset cs) { _charset = cs; } -</code></pre> -<p>In case the String length has not been configured via -<code>ReturnedArrayLength</code>, it will be dynamically calculated via -<code>strnlen(aptr, max_len)</code>.<br /> -The maximum length default for the <code>strnlen(..)</code> operation is -8192 bytes and can be get and set using:</p> -<pre><code> /** Returns the maximum number of bytes to read to determine native string length using `strnlen(..)`, default is 8192. */ - public static int getMaxStrnlen() { return _max_strnlen; }; - - /** Sets the maximum number of bytes to read to determine native string length using `strnlen(..)`, default is 8192. */ - public static void setMaxStrnlen(int v) { _max_strnlen = v; }</code></pre> -<p><em>FIXME</em>: This only works reliable using an 8-bit Charset -encoding, e.g. the default <em>UTF-8</em>.</p> -<h3 id="alignment-for-compound-data">Alignment for Compound Data</h3> -<p>In general, depending on CPU and it's configuration (OS), alignment -is set up for each type (char, short, int, long, ..).</p> -<p>Compounds (structures) are aligned naturally, i.e. their inner -components are aligned<br /> -and are itself aligned to it's largest element.</p> -<p>See:</p> -<ul> -<li><a -href="http://en.wikipedia.org/wiki/Data_structure_alignment">Wikipedia -Data Structure Alignment</a></li> -<li><a -href="http://en.wikipedia.org/wiki/Data_structure_alignment#Data_structure_padding">Wikipedia -Data Structure Alignment - Padding</a></li> -<li><a href="http://www.viva64.com/en/l/0021/">Viva64 Data -Alignment</a></li> -<li><a -href="http://developer.apple.com/library/mac/#documentation/Darwin/Conceptual/64bitPorting/transition/transition.html#//apple_ref/doc/uid/TP40001064-CH207-SW1">Apple: -Darwin 64bit Porting - Data Type Size & Alignment</a></li> -</ul> -<h4 id="simple-alignment-arithmetic">Simple alignment arithmetic</h4> -<p>Modulo operation, where the 2nd handles the case offset == -alignment:</p> -<blockquote> -<p>padding = ( alignment - ( offset % alignment ) ) % alignment ;<br /> -aligned_offset = offset + padding ;</p> -</blockquote> -<p>Optimization utilizing alignment as a multiple of 2 -<code>-> x % 2n == x & ( 2n - 1 )</code></p> -<blockquote> -<p>remainder = offset & ( alignment - 1 ) ;<br /> -padding = ( remainder > 0 ) ? alignment - remainder : 0 ;<br /> -aligned_offset = offset + padding ;</p> -</blockquote> -<p>Without branching, using the 2nd modulo operation for the case offset -== alignment:</p> -<blockquote> -<p>padding = ( alignment - ( offset & ( alignment - 1 ) ) ) & ( -alignment - 1 ) ;<br /> -aligned_offset = offset + padding ;</p> -</blockquote> -<p>See -<code>com.jogamp.gluegen.cgram.types.SizeThunk.align(..)</code>.</p> -<h4 -id="type-size--alignment-for-x86-x86_64-armv6l-32bit-eabi-and-windowmingwmingw64">Type -Size & Alignment for x86, x86_64, armv6l-32bit-eabi and -Window(mingw/mingw64)</h4> -<p>Runtime query is implemented as follows:</p> -<pre><code> typedef struct { - char fill; // nibble one byte - // padding to align s1: padding_0 - type_t s1; // - } test_struct_type_t; - - padding_0 = sizeof(test_struct_type_t) - sizeof(type_t) - sizeof(char) ; - alignmentOf(type_t) = sizeof(test_struct_type_t) - sizeof(type_t) ;</code></pre> -<table> -<thead> -<tr class="header"> -<th style="text-align: left;">type</th> -<th style="text-align: left;">size <br> <em>32 bit</em></th> -<th style="text-align: left;">alignment <br> <em>32 bit</em></th> -<th style="text-align: left;">size <br> <em>64 bit</em></th> -<th style="text-align: left;">alignment <br> <em>64 bit</em></th> -</tr> -</thead> -<tbody> -<tr class="odd"> -<td style="text-align: left;">char</td> -<td style="text-align: left;">1</td> -<td style="text-align: left;">1</td> -<td style="text-align: left;">1</td> -<td style="text-align: left;">1</td> -</tr> -<tr class="even"> -<td style="text-align: left;">short</td> -<td style="text-align: left;">2</td> -<td style="text-align: left;">2</td> -<td style="text-align: left;">2</td> -<td style="text-align: left;">2</td> -</tr> -<tr class="odd"> -<td style="text-align: left;">int</td> -<td style="text-align: left;">4</td> -<td style="text-align: left;">4</td> -<td style="text-align: left;">4</td> -<td style="text-align: left;">4</td> -</tr> -<tr class="even"> -<td style="text-align: left;">float</td> -<td style="text-align: left;">4</td> -<td style="text-align: left;">4</td> -<td style="text-align: left;">4</td> -<td style="text-align: left;">4</td> -</tr> -<tr class="odd"> -<td style="text-align: left;">long</td> -<td style="text-align: left;">4</td> -<td style="text-align: left;">4</td> -<td style="text-align: left;">8†,4∗</td> -<td style="text-align: left;">8†,4∗</td> -</tr> -<tr class="even"> -<td style="text-align: left;">pointer</td> -<td style="text-align: left;">4</td> -<td style="text-align: left;">4</td> -<td style="text-align: left;">8</td> -<td style="text-align: left;">8</td> -</tr> -<tr class="odd"> -<td style="text-align: left;">long long</td> -<td style="text-align: left;">8</td> -<td style="text-align: left;">4†,8∗+</td> -<td style="text-align: left;">8</td> -<td style="text-align: left;">8</td> -</tr> -<tr class="even"> -<td style="text-align: left;">double</td> -<td style="text-align: left;">8</td> -<td style="text-align: left;">4†,8∗+</td> -<td style="text-align: left;">8</td> -<td style="text-align: left;">8</td> -</tr> -<tr class="odd"> -<td style="text-align: left;">long double</td> -<td style="text-align: left;">12†∗,8+,16-</td> -<td style="text-align: left;">4†∗,8+,16-</td> -<td style="text-align: left;">16</td> -<td style="text-align: left;">16</td> -</tr> -</tbody> -</table> -<p>† Linux, Darwin<br /> -+armv7l-eabi<br /> -- MacOsX-32bit-gcc4<br /> -∗ Windows</p> -<h2 id="struct-mapping">Struct Mapping</h2> -<p>A <em>Struct</em> is a C compound type declaration, which can be -mapped to a Java class.</p> -<p>A <em>Struct</em> may utilize the following data types for its -fields</p> -<ul> -<li><em>Primitive</em>, i.e. <em>char</em>, <em>int32_t</em>, ... -<ul> -<li>See <a href="#primitive-mapping"><em>Primitive Mapping</em></a> -above.</li> -<li>See <a href="#string-mapping"><em>String Mapping</em></a> -above.</li> -</ul></li> -<li><em>Struct</em>, i.e. another compound variable</li> -<li><em>Function Pointer</em>, a <em>typedef</em>'ed and set callable -function pointer</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 -pointer.</p> -<p>Both, <em>primitive</em> and <em>struct</em> field type mappings only -produce pure Java code, utilizing the <em>GlueGen Runtime</em>. Hence no -additional native code must be compiled nor a resulting additional -library loaded to use the mapping.</p> -<p>Only when mapping <em>function-pointer</em> within <em>structs</em>, -additional native glue-code is produced to call the underlying native -function which has to be compiled and its library loaded.</p> -<p>The generated method -<code>public static boolean usesNativeCode()</code> can be used to -validate whether the produced Java class requires a corresponding -library for additional native code.</p> -<h3 id="gluegen-struct-settings">GlueGen Struct Settings</h3> -<h4 id="immutableaccess-symbol"><strong>ImmutableAccess</strong> -<em>symbol</em></h4> -<p>Immutable access can be set for a whole struct or a single field of a -struct.</p> -<p>Immutable access will simply suppress generating setters in the Java -code and hence also reduces the footprint of the generated Java class -for such struct.</p> -<ul> -<li><p><code>ImmutableAccess TK_Struct</code></p> -<p>Immutable access for the whole struct `TK_Struct</p> -<p>Sets pseudo-code flag <em>ImmutableAccess</em>, see below.</p></li> -<li><p><code>ImmutableAccess TK_Struct.val</code></p> -<p>Immutable access for the single field <code>val</code> within struct -<code>TK_Struct</code></p> -<p>Sets pseudo-code flag <em>ImmutableAccess</em>, see below.</p></li> -</ul> -<h4 id="maxoneelement-symbol"><strong>MaxOneElement</strong> -<em>symbol</em></h4> -<ul> -<li><p><code>MaxOneElement TK_Struct.val</code></p> -<p>Sets field pointer <code>val</code> to point to a array with a -maximum of one element and unset initial value (zero elements).</p> -<p>Sets pseudo-code flag <em>MaxOneElement</em>, see below.</p></li> -</ul> -<h4 -id="returnedarraylength-symbol-expression"><strong>ReturnedArrayLength</strong> -<em>symbol</em> <em>expression</em></h4> -<ul> -<li><p><code>ReturnedArrayLength TK_Struct.val 3</code></p> -<p>Sets field pointer <code>val</code> to point to a array with three -elements.</p> -<p>Sets pseudo-code flag <em>ConstElemCount</em>, see below.</p> -<p>Having set <em>ConstElemCount</em> also implies <em>native -ownership</em> for a <em>Pointer</em> referenced <em>native</em> -memory.</p></li> -<li><p><code>ReturnedArrayLength TK_Struct.val 1</code></p> -<p>Sets field pointer <code>val</code> to point to a array with one -element.</p> -<p>Sets pseudo-code flags <em>ConstElemCount</em> and -<em>MaxOneElement</em>, see below.</p> -<p>Having set <em>ConstElemCount</em> also implies <em>native -ownership</em> for a <em>Pointer</em> referenced <em>native</em> -memory.</p></li> -<li><p><code>ReturnedArrayLength TK_Struct.val getValElements()</code></p> -<p>Sets field pointer <code>val</code> to point to a array with a -variable length as described by the field <code>valElements</code> -retrievable via its getter <code>getValElements()</code>.</p> -<p>Sets pseudo-code flag <em>VariaElemCount</em>, see below.</p></li> -</ul> -<h4 id="returnsstring-symbol"><strong>ReturnsString</strong> -<em>symbol</em></h4> -<p>A direct C code <code>char</code> array or indirect array via pointer -can be interpreted as a Java <code>String</code>.</p> -<ul> -<li><p><code>ReturnsString TK_Struct.name</code></p> -<p>Sets field char-array or char-pointer <code>name</code> to be -additionally interpreted as a Java <code>String</code>. Besides the -<code>byte[]</code> and <code>ByteBuffer</code> getter and setter -variants, a <code>String</code> variant will be added.</p> -<p>Sets pseudo-code flags <em>String</em>, see below.</p> -<p>See <a href="#string-mapping"><em>String Mapping</em></a> -above.</p></li> -</ul> -<h4 id="returnsstringonly-symbol"><strong>ReturnsStringOnly</strong> -<em>symbol</em></h4> -<ul> -<li><p><code>ReturnsStringOnly TK_Struct.name</code></p> -<p>Sets field char-array or char-pointer <code>name</code> to be -exclusively interpreted as a Java <code>String</code>. Instead of the -<code>byte[]</code> and <code>ByteBuffer</code> getter and setter -variants, a <code>String</code> variant will be produced.</p> -<p>Sets pseudo-code flags <em>StringOnly</em>, see below.</p> -<p>See <a href="#string-mapping"><em>String Mapping</em></a> -above.</p></li> -</ul> -<h3 id="struct-mapping-notes">Struct Mapping Notes</h3> -<ul> -<li><p><em>ConstElemCount</em> via <strong>ReturnedArrayLength -<int></strong> implies <em>native ownership</em> for a -<em>Pointer</em> referenced <em>native</em> memory if the expression is -constant. Otherwise the <em>native</em> memory has <em>java -ownership</em>. See <a -href="#returnedarraylength-symbol-expression">ReturnedArrayLength -Setting</a> above.</p></li> -<li><p>To release native memory with <em>java ownership</em>, i.e. a -native ByteBuffer, <code>releaseVal()</code> can be used.</p></li> -</ul> -<h3 id="struct-java-signature-table">Struct Java Signature Table</h3> -<p>Please find below signature table as generated by the <em>C -Declaration</em> including its <em>C Modifier</em>, e.g. -<code>const</code> for constant, <code>[const]</code> for const and -non-const and <code>empty</code> for non-const (variable).</p> -<p>Further, the <em>GlueGen Setting</em> (see above) impacts the code -generation as well.</p> -<p>Below table demonstrates <em>primitive</em> types being mapped within -a <code>struct</code> named <code>TK_Struct</code>. A similar mapping is -produced for <code>struct</code> types, i.e. <em>compounds</em>.</p> -<table> -<thead> -<tr class="header"> -<th style="text-align: left;">C Mod</th> -<th style="text-align: left;">C Declaration</th> -<th style="text-align: left;">Java Setter</th> -<th style="text-align: left;">Java Getter</th> -<th style="text-align: left;">GlueGen Setting</th> -<th style="text-align: left;">Ownership</th> -<th style="text-align: left;">Remarks</th> -</tr> -</thead> -<tbody> -<tr class="odd"> -<td style="text-align: left;"></td> -<td style="text-align: left;"></td> -<td style="text-align: left;"></td> -<td style="text-align: left;">static boolean usesNativeCode()</td> -<td style="text-align: left;"></td> -<td style="text-align: left;"></td> -<td style="text-align: left;">Java, static, <br> <em>true</em> if using -native code</td> -</tr> -<tr class="even"> -<td style="text-align: left;"></td> -<td style="text-align: left;"></td> -<td style="text-align: left;"></td> -<td style="text-align: left;">static int size()</td> -<td style="text-align: left;"></td> -<td style="text-align: left;"></td> -<td style="text-align: left;">Java, static, <br> native size in -bytes</td> -</tr> -<tr class="odd"> -<td style="text-align: left;"></td> -<td style="text-align: left;"></td> -<td style="text-align: left;"></td> -<td style="text-align: left;">static TK_Struct create()</td> -<td style="text-align: left;"></td> -<td style="text-align: left;"></td> -<td style="text-align: left;">Java, static ctor</td> -</tr> -<tr class="even"> -<td style="text-align: left;"></td> -<td style="text-align: left;"></td> -<td style="text-align: left;"></td> -<td style="text-align: left;">static TK_Struct create(ByteBuffer)</td> -<td style="text-align: left;"></td> -<td style="text-align: left;"></td> -<td style="text-align: left;">Java, static ctor <br> w/ existing -ByteBuffer</td> -</tr> -<tr class="odd"> -<td style="text-align: left;"></td> -<td style="text-align: left;"></td> -<td style="text-align: left;"></td> -<td style="text-align: left;">static TK_Struct derefPointer(long -addr)</td> -<td style="text-align: left;"></td> -<td style="text-align: left;"></td> -<td style="text-align: left;">Java, static ctor <br> dereferencing -ByteBuffer <br> at native address of size()</td> -</tr> -<tr class="even"> -<td style="text-align: left;"></td> -<td style="text-align: left;"></td> -<td style="text-align: left;"></td> -<td style="text-align: left;">ByteBuffer getBuffer()</td> -<td style="text-align: left;"></td> -<td style="text-align: left;"></td> -<td style="text-align: left;">Java, <br> underlying ByteBuffer</td> -</tr> -<tr class="odd"> -<td style="text-align: left;"></td> -<td style="text-align: left;"></td> -<td style="text-align: left;"></td> -<td style="text-align: left;">long getDirectBufferAddress()</td> -<td style="text-align: left;"></td> -<td style="text-align: left;"></td> -<td style="text-align: left;">Java, native address <br> of underlying -getBuffer()</td> -</tr> -<tr class="even"> -<td style="text-align: left;"></td> -<td style="text-align: left;">int32_t val</td> -<td style="text-align: left;">setVal(int v)</td> -<td style="text-align: left;">int getVal()</td> -<td style="text-align: left;"></td> -<td style="text-align: left;">Static</td> -<td style="text-align: left;"></td> -</tr> -<tr class="odd"> -<td style="text-align: left;">const</td> -<td style="text-align: left;">int32_t val</td> -<td style="text-align: left;"><em>none</em></td> -<td style="text-align: left;">int getVal()</td> -<td style="text-align: left;"></td> -<td style="text-align: left;">Static</td> -<td style="text-align: left;">Read only</td> -</tr> -<tr class="even"> -<td style="text-align: left;"></td> -<td style="text-align: left;">int32_t val</td> -<td style="text-align: left;"><em>none</em></td> -<td style="text-align: left;">int getVal()</td> -<td style="text-align: left;"><strong>ImmutableAccess</strong></td> -<td style="text-align: left;">Static</td> -<td style="text-align: left;">Read only</td> -</tr> -<tr class="odd"> -<td style="text-align: left;">[const]</td> -<td style="text-align: left;">int32_t* val</td> -<td style="text-align: left;">setVal(int v) [<a -href="#signature-int32_t--maxoneelement-java-owned">1</a>][<a -href="#signature-const-int32_t--maxoneelement-java-owned">2</a>] <br> -releaseVal()</td> -<td style="text-align: left;">int getVal() <br> boolean isValNull() <br> -int getValElemCount()</td> -<td style="text-align: left;"><strong>MaxOneElement</strong></td> -<td style="text-align: left;">Java</td> -<td style="text-align: left;">Starts w/ null elements,<br>max 1 -element</td> -</tr> -<tr class="even"> -<td style="text-align: left;">const</td> -<td style="text-align: left;">int32_t* val</td> -<td style="text-align: left;"><em>none</em></td> -<td style="text-align: left;">int getVal() <br> boolean isValNull() <br> -static int getValElemCount()</td> -<td style="text-align: left;"><strong>ReturnedArrayLength -1</strong></td> -<td style="text-align: left;">Native</td> -<td style="text-align: left;">Const element count 1</td> -</tr> -<tr class="odd"> -<td style="text-align: left;"></td> -<td style="text-align: left;">int32_t* val</td> -<td style="text-align: left;">setVal(int v)</td> -<td style="text-align: left;">int getVal() <br> boolean isValNull() <br> -static int getValElemCount()</td> -<td style="text-align: left;"><strong>ReturnedArrayLength -1</strong></td> -<td style="text-align: left;">Native</td> -<td style="text-align: left;">Const element count 1</td> -</tr> -<tr class="even"> -<td style="text-align: left;"></td> -<td style="text-align: left;">int32_t val[3]</td> -<td style="text-align: left;">setVal(int[] src, int srcPos, int destPos, -int len)</td> -<td style="text-align: left;">IntBuffer getVal() <br> int[] getVal(int -srcPos, int[] dest, int destPos, int len)</td> -<td style="text-align: left;"></td> -<td style="text-align: left;">Static</td> -<td style="text-align: left;"></td> -</tr> -<tr class="odd"> -<td style="text-align: left;">const</td> -<td style="text-align: left;">int32_t val[3]</td> -<td style="text-align: left;"><em>none</em></td> -<td style="text-align: left;">IntBuffer getVal() <br> int[] getVal(int -srcPos, int[] dest, int destPos, int len)</td> -<td style="text-align: left;"></td> -<td style="text-align: left;">Static</td> -<td style="text-align: left;">Read only</td> -</tr> -<tr class="even"> -<td style="text-align: left;">const</td> -<td style="text-align: left;">int32_t* val</td> -<td style="text-align: left;"><em>none</em></td> -<td style="text-align: left;">IntBuffer getVal() <br> int[] getVal(int -srcPos, int[] dest, int destPos, int len) <br> boolean isValNull() <br> -static int getValElemCount()</td> -<td style="text-align: left;"><strong>ReturnedArrayLength -3</strong></td> -<td style="text-align: left;">Native</td> -<td style="text-align: left;">Read only <br> Const element count 3</td> -</tr> -<tr class="odd"> -<td style="text-align: left;"></td> -<td style="text-align: left;">int32_t* val</td> -<td style="text-align: left;">setVal(int[] src, int srcPos, int destPos, -int len)</td> -<td style="text-align: left;">IntBuffer getVal() <br> int[] getVal(int -srcPos, int[] dest, int destPos, int len) <br> boolean isValNull() <br> -static int getValElemCount()</td> -<td style="text-align: left;"><strong>ReturnedArrayLength -3</strong></td> -<td style="text-align: left;">Native</td> -<td style="text-align: left;">Const element count 3</td> -</tr> -<tr class="even"> -<td style="text-align: left;"></td> -<td style="text-align: left;">int32_t* val</td> -<td style="text-align: left;">setVal(boolean subset, int[] src, int -srcPos, int destPos, int len) <br> releaseVal()</td> -<td style="text-align: left;">IntBuffer getVal() <br> int[] getVal(int -srcPos, int[] dest, int destPos, int len) <br> boolean isValNull() <br> -int getValElemCount()</td> -<td style="text-align: left;"></td> -<td style="text-align: left;">Java</td> -<td style="text-align: left;">Starts w/ null elements</td> -</tr> -<tr class="odd"> -<td style="text-align: left;">const</td> -<td style="text-align: left;">int32_t* val</td> -<td style="text-align: left;">setVal(int[] src, int srcPos, int destPos, -int len) <br> releaseVal()</td> -<td style="text-align: left;">IntBuffer getVal() <br> int[] getVal(int -srcPos, int[] dest, int destPos, int len) <br> boolean isValNull() <br> -int getValElemCount()</td> -<td style="text-align: left;"></td> -<td style="text-align: left;">Java</td> -<td style="text-align: left;">Starts w/ null elements</td> -</tr> -<tr class="even"> -<td style="text-align: left;">[const]</td> -<td style="text-align: left;">int32_t* val</td> -<td style="text-align: left;">setVal(int[] src, int srcPos, int destPos, -int len) <br> releaseVal()</td> -<td style="text-align: left;">IntBuffer getVal() <br> int[] getVal(int -srcPos, int[] dest, int destPos, int len) <br> boolean isValNull()</td> -<td style="text-align: left;"><strong>ReturnedArrayLength -getValCount()</strong></td> -<td style="text-align: left;"><em>Ambiguous</em></td> -<td style="text-align: left;">Variable element count<br>using field -<em>valCount</em>,<br>which has getter and setter</td> -</tr> -<tr class="odd"> -<td style="text-align: left;">[const]</td> -<td style="text-align: left;">char* name</td> -<td style="text-align: left;">setName(String srcVal) <br> -releaseVal()</td> -<td style="text-align: left;">String getName() <br> boolean isNameNull() -<br> int getNameElemCount()</td> -<td style="text-align: left;"><strong>ReturnsStringOnly</strong></td> -<td style="text-align: left;">Java</td> -<td style="text-align: left;">String only, w/ EOS</td> -</tr> -<tr class="even"> -<td style="text-align: left;">[const]</td> -<td style="text-align: left;">char* name</td> -<td style="text-align: left;">setName(String srcVal) <br> setName(byte[] -src, int srcPos, int destPos, int len) <br> releaseVal()</td> -<td style="text-align: left;">String getNameAsString() <br> ByteBuffer -getName() <br> boolean isNameNull() <br> int getNameElemCount()</td> -<td style="text-align: left;"><strong>ReturnsString</strong></td> -<td style="text-align: left;">Java</td> -<td style="text-align: left;">String and byte access, w/ EOS</td> -</tr> -</tbody> -</table> -<h4 id="signature-int32_t--maxoneelement-java-owned">Signature -<code>int32_t *</code> MaxOneElement, Java owned</h4> -<pre><code> /** - * Setter for native field <code>variaInt32PointerMaxOneElem</code>, referencing an array with initial element count of <code>0</code>. Maximum element count is <code>1</code>. - * <p> - * NativeSig <code>(PointerType) 'int32_t *' -> (int32_t) * , size [fixed false, lnx64 8], const[false], pointer*1</code> - * </p> - */ - public final TK_Field setVariaInt32PointerMaxOneElem(int src) { .. }</code></pre> -<p>Will reuse memory if existing, otherwise allocating memory.</p> -<h4 id="signature-const-int32_t--maxoneelement-java-owned">Signature -<code>const int32_t *</code> MaxOneElement, Java owned</h4> -<pre><code> /** - * Setter for native field <code>constInt32PointerMaxOneElem</code>, referencing an array with initial element count of <code>0</code>. Maximum element count is <code>1</code>. - * <p> - * NativeSig <code>(PointerType) 'int32_t *' -> (const int32_t) * , size [fixed false, lnx64 8], const[false], pointer*1</code> - * </p> - */ - public final TK_Field setConstInt32PointerMaxOneElem(int src) { .. } - </code></pre> -<p>Always replaces memory due to <code>const</code> value modifier.</p> -<h4 id="signature-int32_t--constelemcount-3-natively-owned">Signature -<code>int32_t *</code> ConstElemCount 3, Natively owned</h4> -<pre><code> /** - * Setter for native field <code>variaInt32PointerConstLen</code>, referencing a natively owned array with fixed element count of <code>3</code>. - * <p> - * NativeSig <code>(PointerType) 'int32_t *' -> (int32_t) * , size [fixed false, lnx64 8], const[false], pointer*1</code> - * </p> - * <p> - * Copies the given source elements into the respective field's existing memory. - * </p> - * @param src the source array of elements - * @param srcPos starting element position within the source array with 'srcPos >= 0` && `srcPos + length <= src.length`, otherwise an {@link IndexOutOfBoundsException} is thrown - * @param destPos starting element position within the destination with 'destPos >= 0` && `destPos + length <= elemCount`, otherwise an exception is thrown - * @param length the element count to be copied with 'length >= 0` && `srcPos + length <= src.length` && `destPos + length <= elemCount`, otherwise an {@link IndexOutOfBoundsException} is thrown - * @return this instance of chaining - */ - public final TK_Field setVariaInt32PointerConstLen(int[] src, final int srcPos, final int destPos, final int length) { .. }</code></pre> -<h4 id="signature-int32_t--freesize-java-owned">Signature -<code>int32_t *</code> FreeSize, Java owned</h4> -<pre><code> /** - * Setter for native field <code>variaInt32PointerVariaLen</code>, referencing an array with initial element count of <code>0</code>. - * <p> - * NativeSig <code>(PointerType) 'int32_t *' -> (int32_t) * , size [fixed false, lnx64 8], const[false], pointer*1</code> - * </p> - * <p> - * Copies the given source elements into the respective field, either writing into the existing memory or creating a new memory and referencing it. - * </p> - * @param subset if `true` keeps the underlying memory and only allows to set up to `elemCount` elements. Otherwise may replace the underlying memory if `destPos + length != elemCount`. - * @param src the source array of elements - * @param srcPos starting element position within the source array with 'srcPos >= 0` && `srcPos + length <= src.length`, otherwise an {@link IndexOutOfBoundsException} is thrown - * @param destPos starting element position within the destination with 'destPos >= 0`. If `subset == true`, `destPos + length <= elemCount` also must be be `true`. Otherwise an exception is thrown - * @param length the element count to be copied with 'length >= 0` && `srcPos + length <= src.length`, otherwise an {@link IndexOutOfBoundsException} is thrown - * @return this instance of chaining - */ - public final TK_Field setVariaInt32PointerVariaLen(final boolean subset, int[] src, final int srcPos, final int destPos, final int length) { .. } </code></pre> -<h3 id="struct-setter-pseudo-code">Struct Setter Pseudo-Code</h3> -<ul> -<li><em>ImmutableAccess</em>: Drops setter, immutable</li> -<li><em>Pointer</em> & <em>ConstValue</em> & -<em>ConstElemCount</em>: Drops setter, native ownership on -const-value</li> -<li><em>Array</em> & <em>ConstValue</em> : Drops setter, const-value -array</li> -<li><em>Primitive</em> -<ul> -<li>Single aggregated instance -<ul> -<li>Store value within <em>native</em> memory</li> -</ul></li> -<li><em>Array</em> | <em>Pointer</em> -<ul> -<li><em>MaxOneElement</em> -<ul> -<li><em>Pointer</em> -<ul> -<li><em>ConstValue</em>: Allocate new memory and store value</li> -<li><em>VariaValue</em>: -<ul> -<li><em>ConstElemCount</em>: Reuse <em>native</em> memory and store -value with matching <em>elemCount 1</em>, otherwise Exception</li> -<li><em>VariaElemCount</em>: Reuse <em>native</em> memory and store -value with matching <em>elemCount 1</em>, otherwise allocates new memory -(had <em>elemCount 0</em>)</li> -</ul></li> -</ul></li> -<li><em>Array</em> & <em>VariaValue</em>: Reuse <em>native</em> -memory and store value (has const <em>elemCount 1</em>)</li> -<li><em>else</em>: <em>SKIP</em> setter for const single-primitive -array</li> -</ul></li> -<li><em>AnyElementCount</em> -<ul> -<li><em>String</em> & <em>isByteBuffer</em> & <em>Pointer</em> -<ul> -<li><em>ConstElemCount</em>: Reuse <em>native</em> memory and store -UTF-8 bytes with EOS with matching <em>elemCount</em>, otherwise -Exception -<ul> -<li><em>StringOnly</em>: End, no more setter for this field, otherwise -continue</li> -</ul></li> -<li><em>VariaElemCount</em>: Allocate new <em>native</em> memory and -store UTF-8 bytes with EOS -<ul> -<li><em>StringOnly</em>: End, no more setter for this field, otherwise -continue</li> -</ul></li> -</ul></li> -<li><em>ConstValue</em> -<ul> -<li><em>Pointer</em> -<ul> -<li><em>VariaElemCount</em>: Allocates new <em>native</em> memory and -store value</li> -</ul></li> -<li><em>else</em>: <em>SKIP</em> setter for const primitive array</li> -</ul></li> -<li><em>Array</em> | <em>ConstElemCount</em>: Reuse <em>native</em> -memory and store value with <= <em>elemCount</em>, otherwise -Exception</li> -<li><em>Pointer</em> & <em>VariaElemCount</em>: Reuse -<em>native</em> memory and store value with <= <em>elemCount</em>, -otherwise allocate new <em>native</em> memory</li> -</ul></li> -</ul></li> -</ul></li> -<li><em>Struct</em> ...</li> -</ul> -<h2 id="platform-header-files">Platform Header Files</h2> -<p>GlueGen provides convenient platform headers,<br /> -which can be included in your C header files for native compilation and -GlueGen code generation.</p> -<p>Example:</p> -<pre><code> #include <gluegen_stdint.h> - #include <gluegen_stddef.h> - - uint64_t test64; - size_t size1; - ptrdiff_t ptr1;</code></pre> -<p>To compile this file you have to include the following folder to your -compilers system includes, ie <code>-I</code>:</p> -<pre><code> gluegen/make/stub_includes/platform</code></pre> -<p>To generate code for this file you have to include the following -folder to your GlueGen <code>includeRefid</code> element:</p> -<pre><code> gluegen/make/stub_includes/gluegen</code></pre> -<h2 id="pre-defined-macros">Pre-Defined Macros</h2> -<p>To identity a GlueGen code generation run, GlueGen defines the -following macros:</p> -<pre><code> #define __GLUEGEN__ 2</code></pre> -</body> -</html> |