<!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>
div#header, header
{
border-bottom: 1px solid #aaa;
margin-bottom: 0.5em;
}
.title
{
text-align: center;
}
.author, .date
{
text-align: center;
}
div#TOC, nav#TOC
{
border-bottom: 1px solid #aaa;
margin-bottom: 0.5em;
}
nav#TOC {
margin-bottom: var(--line-height);
padding-bottom: 0.5rem;
}
nav#TOC input {
display: none;
}
nav#TOC label {
color: var(--color-link);
cursor: pointer;
}
nav#TOC > ul {
display: none;
}
nav#TOC > input:checked + ul {
display: block;
}
@media print
{
div#TOC, nav#TOC
{
display: none;
}
}
div.content
{
color: #111111;
font-size: 14px;
line-height: 1.6;
}
div#cgit a
{
color: #1212a0;
}
div#cgit a.sourceLine
{
color: #111111;
}
h1, h2, h3, h4, h5, h6
{
font-family: "Helvetica Neue", Helvetica, "Liberation Sans", Calibri, Arial, sans-serif;
page-break-after: avoid;
margin: 20px 0 10px;
padding: 0;
}
h2 {
border-bottom: 1px solid #ccc;
}
div div
{
}
section section
{
margin-left: 2em;
}
p {}
blockquote
{
font-style: italic;
}
li
{
}
li > p
{
margin-top: 1em;
}
ul
{
}
ul li
{
}
ol
{
}
ol li
{
}
hr {}
sub
{
}
sup
{
}
em
{
}
em > em
{
font-style: normal;
}
strong
{
}
a
{
text-decoration: none;
}
@media screen
{
a:hover
{
text-decoration: underline;
}
}
@media print
{
a {
color: black;
background: transparent;
}
a[href^="http://"]:after, a[href^="https://"]:after
{
content: " (" attr(href) ") ";
font-size: 90%;
}
}
img
{
vertical-align: middle;
}
div.figure
{
margin-left: auto;
margin-right: auto;
text-align: center;
font-style: italic;
}
p.caption
{
}
pre, code
{
background-color: #f8f8f8;
white-space: pre-wrap;
white-space: -moz-pre-wrap !important;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;
}
pre
{
padding: 0.5em;
border-radius: 5px;
background-color: #f8f8f8;
border: 1px solid #ccc;
font-size: 13px;
line-height: 19px;
overflow: auto;
padding: 6px 10px;
margin-left: 0.5em;
margin-right: 0.5em;
}
@media screen
{
pre
{
white-space: pre;
overflow: auto;
border: 1px dotted #777;
}
}
code
{
}
p > code, li > code
{
padding-left: 2px;
padding-right: 2px;
}
li > p code
{
padding: 2px;
}
span.math
{
}
div.math
{
}
span.LaTeX
{
}
eq
{
}
table
{
border-collapse: collapse;
border-spacing: 0;
margin-left: auto;
margin-right: auto;
}
thead
{
border-bottom: 1pt solid #000;
background-color: #eee;
}
tr.header
{
}
tbody
{
}
tr {
}
tr.odd:hover, tr.even:hover
{
background-color: #eee;
}
tr.odd {}
tr.even {}
td, th
{
vertical-align: top;
vertical-align: baseline;
padding-left: 0.5em;
padding-right: 0.5em;
padding-top: 0.2em;
padding-bottom: 0.2em;
}
th
{
font-weight: bold;
}
tfoot
{
}
caption
{
caption-side: top;
border: none;
font-size: 0.9em;
font-style: italic;
text-align: center;
margin-bottom: 0.3em;
padding-bottom: 0.2em;
}
dl
{
border-top: 2pt solid black;
padding-top: 0.5em;
border-bottom: 2pt solid black;
}
dt
{
font-weight: bold;
}
dd+dt
{
border-top: 1pt solid black;
padding-top: 0.5em;
}
dd
{
margin-bottom: 0.5em;
}
dd+dd
{
border-top: 1px solid black;
}
a.footnote, a.footnoteRef {
font-size: small;
vertical-align: text-top;
}
a[href^="#fnref"], a.reversefootnote
{
}
@media print
{
a[href^="#fnref"], a.reversefootnote
{
display: none;
}
}
div.footnotes
{
}
div.footnotes li[id^="fn"]
{
}
@media print
{
.noprint
{
display:none;
}
}
</style>
</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="#pointer-mapping">Pointer Mapping</a></li>
<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-setter-pseudo-code">Struct Setter
Pseudo-Code</a></li>
<li><a href="#struct-java-signature-table">Struct Java Signature
Table</a></li>
<li><a href="#struct-java-signature-examples">Struct Java Signature
Examples</a></li>
<li><a href="#struct-pointer-pointer-support">Struct Pointer-Pointer
Support</a></li>
<li><a href="#struct-function-pointer-support">Struct Function-Pointer
Support</a></li>
<li><a href="#java-callback-from-native-c-api-support">Java Callback
from Native C-API Support</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="pointer-mapping">Pointer Mapping</h3>
<p><em>Pointer</em> values itself are represented as <code>long</code>
values on the Java side while using the native pointer-size, e.g. 32-bit
or 64-bit, on the native end.</p>
<p>They may simply be accessible via <code>long</code> or
<code>long[]</code> primitives in Java, or are exposed via
<code>com.jogamp.common.nio.PointerBuffer</code>.</p>
<p>See <a href="#struct-pointer-pointer-support">Struct Pointer-Pointer
Support</a> below.</p>
<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="#pointer-mapping"><em>Pointer Mapping</em></a> for
<em>pointer-to-pointer</em> values above and <a
href="#struct-pointer-pointer-support">Struct Pointer-Pointer
Support</a> below.</li>
<li>See <a href="#string-mapping"><em>String Mapping</em></a>
above.</li>
</ul></li>
<li><em>Struct</em>, i.e. an aggregated or referenced compound
variable</li>
<li><em>Function Pointer</em>, a <em>typedef</em>'ed and set callable
function pointer, see <a href="#struct-function-pointer-support">Struct
Function-Pointer Support</a> below.</li>
<li><em>Java Callback from Native Code</em>, see <a
href="#java-callback-from-native-c-api-support">section below</a></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>, <em>struct</em> and <em>pointer</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>Utilizing a <em>flexible</em> <em>elemCount</em> via
<strong>ReturnedArrayLength getValElements()</strong> renders us unable
to determine ownership of pointer referenced <em>native</em> memory
segment and hence renders ownership <em>mixed or ambiguous</em>, <a
href="#signature-const-int32_t--customsize-ambiguous-java-owned">see
[5]</a>. This is due to the fact, that native code may allocate memory
and writes its <em>elemCount</em> into the designated field
<em>valElements</em>. In such cases, the user being aware of the
underlying API shall utilize <code>setVal(..)</code> and
<code>releaseVal()</code> with care.</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-setter-pseudo-code">Struct Setter Pseudo-Code</h3>
<h4 id="overview-1">Overview</h4>
<p>In general we have the following few cases</p>
<ul>
<li><p>Array owned by parent struct itself</p>
<ul>
<li><code>int32_t val[10]</code>
<ul>
<li>Setter of <code>val</code> within range, keeping memory</li>
</ul></li>
<li><code>const int32_t val[10]</code>
<ul>
<li>No setter allowed due to const value</li>
</ul></li>
</ul></li>
<li><p>Referenced Memory (array) owned by Java</p>
<ul>
<li><code>int32_t* val</code>
<ul>
<li>Setter within range, keeping memory, or replacing memory</li>
</ul></li>
<li><code>const int32_t* val</code>
<ul>
<li>Setter replacing memory, since memory is non-const but value is
const</li>
</ul></li>
</ul></li>
<li><p>Referenced Memory (array) owned by Native Code due to set
<em>ConstElemCount</em></p>
<ul>
<li><code>int32_t* val</code>
<ul>
<li>Setter of <code>val</code> within range, keeping memory owned by
native code</li>
</ul></li>
<li><code>const int32_t* val</code>
<ul>
<li>No setter allowed, since memory is owned by native code and value is
const</li>
</ul></li>
</ul></li>
</ul>
<h4 id="implemented-pseudo-code">Implemented Pseudo Code</h4>
<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>
<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;">Parent</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;">Parent</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;">Parent</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) [<a
href="#signature-int32_t3-constelemcount-3-parent-owned">3</a>]</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;">Parent</td>
<td style="text-align: left;">Reuses parent memory,<br>fixed size.</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;">Parent</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) [<a
href="#signature-int32_t--constelemcount-3-natively-owned">4</a>]</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.<br>Reuses native
memory,<br>fixed size.</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) [<a
href="#signature-int32_t--freesize-java-owned">5</a>] <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.<br>Reuses or
replaces Java memory,<br>variable size.</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 len) [<a
href="#signature-const-int32_t--freesize-java-owned">6</a>] <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.<br>Replaces Java
memory,<br>variable size.</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) [<a
href="#signature-int32_t--customsize-ambiguous-ownership">7</a>] <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;"><strong>Ambiguous</strong></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;">int32_t* val</td>
<td style="text-align: left;">setVal(int[] src, int srcPos, int len) [<a
href="#signature-const-int32_t--customsize-ambiguous-ownership">8</a>]
<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;"><strong>Ambiguous</strong></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="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>
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="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> 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>
<h3 id="struct-java-signature-examples">Struct Java Signature
Examples</h3>
<h4 id="signature-int32_t--maxoneelement-java-owned">Signature
<code>int32_t *</code> MaxOneElement, Java owned</h4>
<ul>
<li><p><code>void com.jogamp.gluegen.test.junit.generation.TK_Field.setVariaInt32PointerMaxOneElemElemCount(int src)</code></p>
<p>Setter for native field variaInt32PointerMaxOneElem, referencing a
Java owned array with variable element count of 0 initial elements.</p>
<p>Maximum element count is 1.</p>
<p>Native Signature:</p>
<ul>
<li>field-type (PointerType) 'int32_t <em>' -> (int32_t) * , size
[fixed false, lnx64 8], const[false], pointer</em>1</li>
<li>referenced (IntType) typedef 'int32_t', size [fixed true, lnx64 4],
const[false], int</li>
</ul>
<p>Will reuse memory if existing, otherwise allocating memory.</p></li>
</ul>
<h4 id="signature-const-int32_t--maxoneelement-java-owned">Signature
<code>const int32_t *</code> MaxOneElement, Java owned</h4>
<ul>
<li><p><code>TK_Field com.jogamp.gluegen.test.junit.generation.TK_Field.setConstInt32PointerMaxOneElem(int src)</code></p>
<p>Setter for native field variaInt32PointerMaxOneElem, referencing a
Java owned array with variable element count of 0 initial elements.</p>
<p>Maximum element count is 1.</p>
<p>Native Signature:</p>
<ul>
<li>field-type (PointerType) 'int32_t <em>' -> (const int32_t) * ,
size [fixed false, lnx64 8], const[false], pointer</em>1</li>
<li>referenced (IntType) typedef 'int32_t', size [fixed true, lnx64 4],
const[native, true], int</li>
</ul>
<p>Always replaces memory due to <code>const</code> value
modifier.</p></li>
</ul>
<h4 id="signature-int32_t3-constelemcount-3-parent-owned">Signature
<code>int32_t[3]</code> ConstElemCount 3, Parent owned</h4>
<ul>
<li><p><code>TK_Field com.jogamp.gluegen.test.junit.generation.TK_Field.setVariaInt32ArrayConstLen(int[] src, int srcPos, int destPos, int length)</code></p>
<p>Setter for native field variaInt32ArrayConstLen, being an array with
fixed element count of 3 elements.</p>
<p>Native Field Signature (ArrayType) 'int32_t <em>', size [fixed false,
lnx64 12], const[false], array</em>1</p>
<p>Copies the given source elements into the respective field's existing
memory.</p>
<p>Parameters:</p>
<ul>
<li>src the source array of elements</li>
<li>srcPos starting element position within the source array with
'srcPos >= 0<code>&&</code>srcPos + length <= src.length`,
otherwise an IndexOutOfBoundsException is thrown</li>
<li>destPos starting element position within the destination with
'destPos >= 0<code>&&</code>destPos + length <=
elemCount`, otherwise an exception is thrown</li>
<li>length the element count to be copied with 'length >=
0<code>&&</code>srcPos + length <=
src.length<code>&&</code>destPos + length <= elemCount`,
otherwise an IndexOutOfBoundsException is thrown</li>
</ul>
<p>Returns:</p>
<ul>
<li>this instance of chaining</li>
</ul></li>
</ul>
<h4 id="signature-int32_t--constelemcount-3-natively-owned">Signature
<code>int32_t *</code> ConstElemCount 3, Natively owned</h4>
<ul>
<li><p><code>TK_Field com.jogamp.gluegen.test.junit.generation.TK_Field.setVariaInt32PointerConstLen(int[] src, int srcPos, int destPos, int length)</code></p>
<p>Setter for native field variaInt32PointerConstLen, referencing a
natively owned array with fixed element count of 3 elements.</p>
<p>Native Signature:</p>
<ul>
<li>field-type (PointerType) 'int32_t <em>' -> (int32_t) * , size
[fixed false, lnx64 8], const[false], pointer</em>1</li>
<li>referenced (IntType) typedef 'int32_t', size [fixed true, lnx64 4],
const[false], int</li>
</ul>
<p>Copies the given source elements into the respective field's existing
memory.</p>
<p>Parameters:</p>
<ul>
<li>src the source array of elements</li>
<li>srcPos starting element position within the source array with
'srcPos >= 0<code>&&</code>srcPos + length <= src.length`,
otherwise an IndexOutOfBoundsException is thrown</li>
<li>destPos starting element position within the destination with
'destPos >= 0<code>&&</code>destPos + length <=
elemCount`, otherwise an exception is thrown</li>
<li>length the element count to be copied with 'length >=
0<code>&&</code>srcPos + length <=
src.length<code>&&</code>destPos + length <= elemCount`,
otherwise an IndexOutOfBoundsException is thrown</li>
</ul>
<p>Returns:</p>
<ul>
<li>this instance of chaining</li>
</ul></li>
</ul>
<h4 id="signature-int32_t--freesize-java-owned">Signature
<code>int32_t *</code> FreeSize, Java owned</h4>
<ul>
<li><p><code>TK_Field com.jogamp.gluegen.test.junit.generation.TK_Field.setVariaInt32PointerVariaLen(boolean subset, int[] src, int srcPos, int destPos, int length)</code></p>
<p>Setter for native field variaInt32PointerVariaLen, referencing a Java
owned array with variable element count of 0 initial elements.</p>
<p>Native Signature:</p>
<ul>
<li>field-type (PointerType) 'int32_t <em>' -> (int32_t) * , size
[fixed false, lnx64 8], const[false], pointer</em>1</li>
<li>referenced (IntType) typedef 'int32_t', size [fixed true, lnx64 4],
const[false], int</li>
</ul>
<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>
<p>Parameters:</p>
<ul>
<li>subset if <code>true</code> keeps the underlying memory and only
allows to set up to <code>elemCount</code> elements. Otherwise may
replace the underlying memory if
<code>destPos + length != elemCount</code>.</li>
<li>src the source array of elements</li>
<li>srcPos starting element position within the source array with
'srcPos >= 0<code>&&</code>srcPos + length <= src.length`,
otherwise an IndexOutOfBoundsException is thrown</li>
<li>destPos starting element position within the destination with
'destPos >= 0<code>. If </code>subset == true<code>, </code>destPos +
length <= elemCount<code>also must be be</code>true`. Otherwise an
exception is thrown</li>
<li>length the element count to be copied with 'length >=
0<code>&&</code>srcPos + length <= src.length`, otherwise an
IndexOutOfBoundsException is thrown</li>
</ul>
<p>Returns:</p>
<ul>
<li>this instance of chaining</li>
</ul></li>
</ul>
<h4 id="signature-const-int32_t--freesize-java-owned">Signature
<code>const int32_t *</code> FreeSize, Java owned</h4>
<ul>
<li><p><code>TK_Field com.jogamp.gluegen.test.junit.generation.TK_Field.setConstInt32PointerVariaLen(int[] src, int srcPos, int length)</code></p>
<p>Setter for native field constInt32PointerVariaLen, referencing a Java
owned array with variable element count of 0 initial elements.</p>
<p>Native Signature:</p>
<ul>
<li>field-type (PointerType) 'int32_t <em>' -> (const int32_t) * ,
size [fixed false, lnx64 8], const[false], pointer</em>1</li>
<li>referenced (IntType) typedef 'int32_t', size [fixed true, lnx64 4],
const[native, true], int</li>
</ul>
<p>Replaces the respective field's memory with a new memory segment
containing given source elements and referencing it.</p>
<p>Parameters:</p>
<ul>
<li>src the source array of elements</li>
<li>srcPos starting element position within the source array with
'srcPos >= 0<code>&&</code>srcPos + length <= src.length`,
otherwise an IndexOutOfBoundsException is thrown</li>
<li>length the element count to be copied with 'length >=
0<code>&&</code>srcPos + length <= src.length`, otherwise an
IndexOutOfBoundsException is thrown</li>
</ul>
<p>Returns:</p>
<ul>
<li>this instance of chaining</li>
</ul></li>
</ul>
<h4 id="signature-int32_t--customsize-ambiguous-ownership">Signature
<code>int32_t *</code> CustomSize, Ambiguous ownership</h4>
<ul>
<li><p><code>TK_Field com.jogamp.gluegen.test.junit.generation.TK_Field.setVariaInt32PointerCustomLen(boolean subset, int[] src, int srcPos, int destPos, int length)</code></p>
<p>Setter for native field variaInt32PointerCustomLen, referencing a
mixed and ambigously owned (warning) array with variable element count
of getVariaInt32PointerCustomLenElemCount() elements.</p>
<p>Native Signature:</p>
<ul>
<li>field-type (PointerType) 'int32_t <em>' -> (int32_t) * , size
[fixed false, lnx64 8], const[false], pointer</em>1</li>
<li>referenced (IntType) typedef 'int32_t', size [fixed true, lnx64 4],
const[false], int</li>
</ul>
<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>
<p>Parameters:</p>
<ul>
<li>subset if <code>true</code> keeps the underlying memory and only
allows to set up to <code>elemCount</code> elements. Otherwise may
replace the underlying memory if
<code>destPos + length != elemCount</code>.</li>
<li>src the source array of elements</li>
<li>srcPos starting element position within the source array with
'srcPos >= 0<code>&&</code>srcPos + length <= src.length`,
otherwise an IndexOutOfBoundsException is thrown</li>
<li>destPos starting element position within the destination with
'destPos >= 0<code>. If </code>subset == true<code>, </code>destPos +
length <= elemCount<code>also must be be</code>true`. Otherwise an
exception is thrown</li>
<li>length the element count to be copied with 'length >=
0<code>&&</code>srcPos + length <= src.length`, otherwise an
IndexOutOfBoundsException is thrown</li>
</ul>
<p>Returns:</p>
<ul>
<li>this instance of chaining</li>
</ul></li>
</ul>
<h4
id="signature-const-int32_t--customsize-ambiguous-ownership">Signature
<code>const int32_t *</code> CustomSize, Ambiguous ownership</h4>
<ul>
<li><p><code>TK_Field com.jogamp.gluegen.test.junit.generation.TK_Field.setConstInt32PointerCustomLen(int[] src, int srcPos, int length)</code></p>
<p>Setter for native field constIntxxPointerCustomLen, referencing a
mixed and ambigously owned (<strong>warning</strong>) array with
variable element count of getConstIntxxPointerCustomLenElemCount()
elements.</p>
<p>Native Signature:</p>
<ul>
<li>field-type (PointerType) 'int32_t <em>' -> (const int32_t) * ,
size [fixed false, lnx64 8], const[false], pointer</em>1</li>
<li>referenced (IntType) typedef 'int32_t', size [fixed true, lnx64 4],
const[native, true], int</li>
</ul>
<p>Replaces the respective field's memory with a new memory segment
containing given source elements and referencing it.</p>
<p>Parameters:</p>
<ul>
<li>src the source array of elements</li>
<li>srcPos starting element position within the source array with
'srcPos >= 0<code>&&</code>srcPos + length <= src.length`,
otherwise an IndexOutOfBoundsException is thrown</li>
<li>length the element count to be copied with 'length >=
0<code>&&</code>srcPos + length <= src.length`, otherwise an
IndexOutOfBoundsException is thrown</li>
</ul>
<p>Returns:</p>
<ul>
<li>this instance of chaining</li>
</ul></li>
</ul>
<h3 id="struct-pointer-pointer-support">Struct Pointer-Pointer
Support</h3>
<p>See primitive <a href="#pointer-mapping"><em>Pointer Mapping</em></a>
above.</p>
<p><em>Pointer</em> are exposed in the following examples</p>
<pre><code>typedef struct {
int32_t* int32PtrArray[10];
int32_t** int32PtrPtr;
...
} T2_PointerStorage;</code></pre>
<p>or via and undefined forward-declared struct</p>
<pre><code>typedef struct T2_UndefStruct* T2_UndefStructPtr;
typedef struct {
...
T2_UndefStructPtr undefStructPtr;
T2_UndefStructPtr undefStructPtrArray[10];
T2_UndefStructPtr* undefStructPtrPtr;
const T2_UndefStructPtr* constUndefStructPtrPtr;
} T2_PointerStorage;</code></pre>
<p>and the following GlueGen configuration</p>
<pre><code>Opaque long T2_UndefStruct*
Ignore T2_UndefStruct</code></pre>
<p><em>TODO: Enhance documentation</em></p>
<h3 id="struct-function-pointer-support">Struct Function-Pointer
Support</h3>
<p>GlueGen supports function pointers as struct fields,<br />
generating function calls as methods as well function-pointer opaque
getter and setter as <code>long</code> types.<br />
The latter only in case if mutable, i.e. non-const.</p>
<h4 id="example">Example</h4>
<p>Assume the following C Header file example:</p>
<pre><code>typedef struct {
int32_t balance;
} T2_UserData;
typedef int32_t ( * T2_CustomFuncA)(void* aptr);
typedef int32_t ( * T2_CustomFuncB)(T2_UserData* pUserData);
typedef struct {
...
T2_CustomFuncA customFuncAVariantsArray[10];
T2_CustomFuncA* customFuncAVariantsArrayPtr;
T2_CustomFuncB customFuncBVariantsArray[10];
T2_CustomFuncB* customFuncBVariantsArrayPtr;
} T2_PointerStorage;
typedef struct {
...
const T2_CustomFuncA CustomFuncA1;
T2_CustomFuncB CustomFuncB1;
} T2_InitializeOptions;</code></pre>
<p>and the following GlueGen configuration</p>
<pre><code>Opaque long void*
EmitStruct T2_UserData
StructPackage T2_UserData com.jogamp.gluegen.test.junit.generation
EmitStruct T2_InitializeOptions
StructPackage T2_InitializeOptions com.jogamp.gluegen.test.junit.generation</code></pre>
<p>This will lead to the following result for
<code>const T2_CustomFuncA customFuncA1</code></p>
<pre><code> /**
* Getter for native field <code>CustomFuncA1</code>, being a <i>struct</i> owned function pointer.
* <p>
* Native Field Signature <code>(PointerType) typedef 'T2_CustomFuncA' -> int32_t (*)(void * aptr), size [fixed false, lnx64 8], const[false], pointer*1, funcPointer</code>
* </p>
*/
public final long getCustomFuncA1() { .. }
/** Interface to C language function: <br> <code>int32_t CustomFuncA1(void * aptr)</code><br> */
public final int CustomFuncA1(long aptr) { ... } </code></pre>
<p>and similar to <code>T2_CustomFuncB customFuncB1</code></p>
<pre><code> /**
* Setter for native field <code>CustomFuncB1</code>, being a <i>struct</i> owned function pointer.
* <p>
* Native Field Signature <code>(PointerType) typedef 'T2_CustomFuncB' -> int32_t (*)(T2_UserData * pUserData), size [fixed false, lnx64 8], const[false], pointer*1, funcPointer</code>
* </p>
*/
public final T2_InitializeOptions setCustomFuncB1(long src) { .. }
/**
* Getter for native field <code>CustomFuncB1</code>, being a <i>struct</i> owned function pointer.
* <p>
* Native Field Signature <code>(PointerType) typedef 'T2_CustomFuncB' -> int32_t (*)(T2_UserData * pUserData), size [fixed false, lnx64 8], const[false], pointer*1, funcPointer</code>
* </p>
*/
public final long getCustomFuncB1() { .. }
/** Interface to C language function: <br> <code>int32_t CustomFuncB1(T2_UserData * pUserData)</code><br> */
public final int CustomFuncB1(T2_UserData pUserData) { .. } </code></pre>
<h3 id="java-callback-from-native-c-api-support">Java Callback from
Native C-API Support</h3>
<p>GlueGen supports registering Java callback methods to native C-API
functions in the form:</p>
<pre><code>typedef int32_t ( * T_CallbackFunc)(size_t id, size_t msg_len, const char* msg, void* userParam);
void AddMessageCallback(T_CallbackFunc func, void* userParam);
void RemoveMessageCallback(T_CallbackFunc func, void* userParam);
void InjectMessageCallback(size_t id, size_t msg_len, const char* msg);</code></pre>
<p><em>TODO: Work in progress</em></p>
<h4 id="example-1">Example</h4>
<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>