File: GlueGen_Mapping.html

package info (click to toggle)
gluegen2 2.6.0%2Bdfsg-1
links: PTS, VCS
area: main
in suites: forky, sid
size: 9,320 kB
sloc: java: 55,357; ansic: 3,758; xml: 3,328; sh: 1,565; pascal: 591; asm: 162; makefile: 76
file content (2780 lines) | stat: -rw-r--r-- 116,695 bytes
<!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-data-func-mapping">GlueGen Native Data &amp;
  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="#oo-style-api-interface-mapping">OO-Style API Interface
  Mapping</a>
  <ul>
  <li><a href="#oo-style-mapping-settings">OO-Style Mapping
  Settings</a></li>
  <li><a href="#oo-style-example">OO-Style Example</a></li>
  </ul></li>
  <li><a href="#struct-mapping">Struct Mapping</a>
  <ul>
  <li><a href="#struct-mapping-notes">Struct Mapping Notes</a></li>
  <li><a href="#gluegen-struct-settings">GlueGen Struct
  Settings</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>
  </ul></li>
  <li><a href="#java-callback">Java Callback</a>
  <ul>
  <li><a href="#implementation-details">Implementation Details</a></li>
  <li><a href="#javacallback-userparam-mapping"><em>JavaCallback</em>
  <em>UserParam</em> Mapping</a></li>
  <li><a href="#javacallback-configuration"><em>JavaCallback</em>
  Configuration</a></li>
  <li><a
  href="#javacallback-generated-interfaces-classes-and-methods"><em>JavaCallback</em>
  Generated Interfaces, Classes and Methods</a></li>
  <li><a href="#javacallback-notes"><em>JavaCallback</em> Notes</a></li>
  <li><a href="#javacallback-example-1">JavaCallback Example 1</a></li>
  <li><a href="#javacallback-example-2a-default-keyclass">JavaCallback
  Example 2a (Default <em>KeyClass</em>)</a></li>
  <li><a
  href="#javacallback-example-2b-custom-keyclass-different-key-parameter-order">JavaCallback
  Example 2b (Custom <em>KeyClass</em>, different key-parameter
  order)</a></li>
  <li><a
  href="#javacallback-example-5b-userparam-part-of-2-component-key">JavaCallback
  Example 5b (UserParam part of 2 component-key)</a></li>
  <li><a
  href="#javacallback-example-11a-homogeneous-struct-type">JavaCallback
  Example 11a (<em>Homogeneous Struct Type</em>)</a></li>
  <li><a
  href="#javacallback-example-11b-heterogeneous-pointerstruct-type">JavaCallback
  Example 11b (<em>Heterogeneous Pointer/Struct Type</em>)</a></li>
  <li><a href="#javacallback-example-12-without-userparam">JavaCallback
  Example 12 (Without UserParam)</a></li>
  </ul></li>
  <li><a href="#misc-configurations">Misc Configurations</a>
  <ul>
  <li><a
  href="#libraryonload-librarybasename-for-jni_onload-"><code>LibraryOnLoad &lt;LibraryBasename&gt;</code>
  for <code>JNI_OnLoad*(..)</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>
<!---
We convert markdown using pandoc using `markdown+lists_without_preceding_blankline` as source format
and `html5+smart` with a custom template as the target.

Recipe:
```
  ~/pandoc-buttondown-cgit/pandoc_md2html_local.sh GlueGen_Mapping.md > GlueGen_Mapping.html
```

Git repos:
- https://jausoft.com/cgit/users/sgothel/pandoc-buttondown-cgit.git/about/
- https://github.com/sgothel/pandoc-buttondown-cgit
-->
<style>
table, th, td {
   border: 1px solid black;
}
</style>
<h1 id="gluegen-data-func-mapping">GlueGen Native Data &amp; Function
Mapping for Java™</h1>
<p><em>Disclaimer: This documented shall be synchronized with source
code, especially the configuration options.</em></p>
<p>Please also consider reading <a
href="https://jogamp.org/gluegen/doc/manual/">GlueGen Manual</a> for
general usage and configuration options.</p>
<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>
<li><a
href="https://jogamp.org/gluegen/doc/JogAmpPlatforms.html">JogAmp’s
Supported Platforms</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>GlueGen also provides a comprehensive <a
href="https://jogamp.org/deployment/jogamp-next/javadoc/gluegen/javadoc/">runtime
library</a> offering</p>
<ul>
<li>Support for multi-arch and java code fat-jar deployment
<ul>
<li>Native library including JNI bundle handling and Jar file cache</li>
<li>Platform architecture information retrieval, ELF parser, alignment
etc</li>
</ul></li>
<li>Enhanced NIO buffer handling for pointer, arrays, DMA mapping
etc</li>
<li>Network Uri RFC 2396, connection and resource handler to simplify
asset loading</li>
<li>Bitstream, hash maps, ringbuffer, sha cumulator, reflection and
threading utils</li>
<li>Abstract AudioFormat and AudioSink interfaces, concurrent locks ..
and more</li>
</ul>
<p>GlueGen’s compiler 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 <a href="#struct-mapping">map native data structures</a> to be fully
accessible from Java™ including potential calls to <a
href="#struct-function-pointer-support">embedded function
pointer</a>.</p>
<p>GlueGen supports <a href="#java-callback">registering Java™ callback
methods</a> to receive asynchronous and off-thread native toolkit
events, where a generated native callback function dispatches the events
to Java™.</p>
<p>GlueGen also supports <a
href="#oo-style-api-interface-mapping">producing an OO-Style API
mapping</a> like <a
href="https://jogamp.org/jogl/doc/uml/html/index.html">JOGL’s
incremental OpenGL Profile API levels</a>.</p>
<p>GlueGen is capable to bind 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>Further, GlueGen supports <a
href="#libraryonload-librarybasename-for-jni_onload-">generating
<code>JNI_OnLoad*(..)</code> for dynamic and static libraries</a>, also
resolving off-thread <code>JNIEnv*</code> lookup.</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>
<colgroup>
<col style="width: 16%" />
<col style="width: 15%" />
<col style="width: 16%" />
<col style="width: 16%" />
<col style="width: 12%" />
<col style="width: 11%" />
<col style="width: 11%" />
</colgroup>
<thead>
<tr class="header">
<th style="text-align: left;">type</th>
<th style="text-align: right;">java-bits</th>
<th style="text-align: right;">native-x32</th>
<th style="text-align: right;">native-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: right;">0</td>
<td style="text-align: right;">0</td>
<td style="text-align: right;">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: right;">8</td>
<td style="text-align: right;">8</td>
<td style="text-align: right;">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: right;">16</td>
<td style="text-align: right;">16</td>
<td style="text-align: right;">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: right;">32</td>
<td style="text-align: right;">32</td>
<td style="text-align: right;">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: right;">64</td>
<td style="text-align: right;">32</td>
<td style="text-align: right;"><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: right;">64</td>
<td style="text-align: right;">32</td>
<td style="text-align: right;"><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: right;">32</td>
<td style="text-align: right;">32</td>
<td style="text-align: right;">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: right;">64</td>
<td style="text-align: right;">64</td>
<td style="text-align: right;">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: right;">32</td>
<td style="text-align: right;">32</td>
<td style="text-align: right;">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: right;">64</td>
<td style="text-align: right;">64</td>
<td style="text-align: right;">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: right;">8</td>
<td style="text-align: right;">8</td>
<td style="text-align: right;">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: right;">8</td>
<td style="text-align: right;">8</td>
<td style="text-align: right;">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: right;">16</td>
<td style="text-align: right;">16</td>
<td style="text-align: right;">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: right;">16</td>
<td style="text-align: right;">16</td>
<td style="text-align: right;">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: right;">32</td>
<td style="text-align: right;">32</td>
<td style="text-align: right;">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: right;">32</td>
<td style="text-align: right;">32</td>
<td style="text-align: right;">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: right;">64</td>
<td style="text-align: right;">64</td>
<td style="text-align: right;">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: right;">64</td>
<td style="text-align: right;">64</td>
<td style="text-align: right;">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: right;">64</td>
<td style="text-align: right;">32</td>
<td style="text-align: right;">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: right;">64</td>
<td style="text-align: right;">32</td>
<td style="text-align: right;">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: right;">64</td>
<td style="text-align: right;">32</td>
<td style="text-align: right;">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: right;">64</td>
<td style="text-align: right;">32</td>
<td style="text-align: right;">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: right;">32</td>
<td style="text-align: right;">32</td>
<td style="text-align: right;">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!
<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 &gt;
<code>jstring NewStringUTF(JNIEnv *env, const char *bytes)</code></p>
<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 &gt;
<code>const char * GetStringUTFChars(JNIEnv *env, jstring string, jboolean *isCopy)</code>.</p>
<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 &gt;
<code>void GetStringRegion(JNIEnv *env, jstring str, jsize start, jsize len, jchar *buf)</code>.</p>
<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. 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&#39;s String mapping, default is StandardCharsets.UTF_8. */
  public static Charset getCharset() { return _charset; };

  /** Sets the Charset for this class&#39;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>. 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 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 &amp; 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 ;
aligned_offset = offset + padding ;</p>
</blockquote>
<p>Optimization utilizing alignment as a multiple of 2
<code>-&gt; x % 2n == x &amp; ( 2n - 1 )</code></p>
<blockquote>
<p>remainder = offset &amp; ( alignment - 1 ) ; padding = ( remainder
&gt; 0 ) ? alignment - remainder : 0 ; 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 &amp; ( alignment - 1 ) ) ) &amp; (
alignment - 1 ) ; 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 &amp; 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>
<colgroup>
<col style="width: 12%" />
<col style="width: 19%" />
<col style="width: 24%" />
<col style="width: 19%" />
<col style="width: 24%" />
</colgroup>
<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 +armv7l-eabi - MacOsX-32bit-gcc4 ∗ Windows</p>
<h2 id="oo-style-api-interface-mapping">OO-Style API Interface
Mapping</h2>
<p>GlueGen supports producing an OO-Style API mapping like <a
href="https://jogamp.org/jogl/doc/uml/html/index.html">JOGL’s
incremental OpenGL Profile API levels</a>.</p>
<h3 id="oo-style-mapping-settings">OO-Style Mapping Settings</h3>
<ul>
<li><p><code>ExtendedInterfaceSymbolsIgnore ../build-temp/gensrc/classes/com/jogamp/opengl/GL.java</code></p>
<p>Ignore all extended interface symbols from named Java source
file.</p>
<p>The named Java source file is parsed and a list of its symbols
extracted, allowing GlueGen to ignore these in the generated interface
(here GLES3).</p>
<p>This complements <code>Extends</code> setting, see below.</p></li>
<li><p><code>Extends GLES3 GLES2</code></p>
<p>The generated interface GLES3 extends interface GLES2.</p>
<p>This complements <code>ExtendedInterfaceSymbolsIgnore</code> setting,
see above.</p></li>
<li><p><code>Implements GLES3Impl GLES3</code></p>
<p>The generated implementation GLES3Impl implements interface
GLES3.</p></li>
</ul>
<h3 id="oo-style-example">OO-Style Example</h3>
<p>Example snippet from JOGL’s GLES3 interface config
<code>gl-if-es3.cfg</code></p>
<pre><code>...

ExtendedInterfaceSymbolsIgnore ../build-temp/gensrc/classes/com/jogamp/opengl/GL.java
ExtendedInterfaceSymbolsIgnore ../build-temp/gensrc/classes/com/jogamp/opengl/GL2ES2.java
ExtendedInterfaceSymbolsIgnore ../build-temp/gensrc/classes/com/jogamp/opengl/GLES2.java
ExtendedInterfaceSymbolsIgnore ../build-temp/gensrc/classes/com/jogamp/opengl/GL2ES3.java
ExtendedInterfaceSymbolsIgnore ../build-temp/gensrc/classes/com/jogamp/opengl/GL3ES3.java
ExtendedInterfaceSymbolsIgnore ../build-temp/gensrc/classes/com/jogamp/opengl/GL4ES3.java
ExtendedInterfaceSymbolsIgnore ../src/jogl/classes/com/jogamp/opengl/GLBase.java

Package com.jogamp.opengl
Style InterfaceOnly
JavaClass GLES3
Extends GLES3 GLES2
Extends GLES3 GL4ES3
...</code></pre>
<p>Example snippet from JOGL’s GLES3Impl implementation
<code>gl-es3-impl.cfg</code></p>
<pre><code>...
ExtendedInterfaceSymbolsIgnore ../build-temp/gensrc/classes/com/jogamp/opengl/GL.java
ExtendedInterfaceSymbolsIgnore ../build-temp/gensrc/classes/com/jogamp/opengl/GL2ES2.java
ExtendedInterfaceSymbolsIgnore ../build-temp/gensrc/classes/com/jogamp/opengl/GLES2.java
ExtendedInterfaceSymbolsIgnore ../build-temp/gensrc/classes/com/jogamp/opengl/GL2ES3.java
ExtendedInterfaceSymbolsIgnore ../build-temp/gensrc/classes/com/jogamp/opengl/GL3ES3.java
ExtendedInterfaceSymbolsIgnore ../build-temp/gensrc/classes/com/jogamp/opengl/GL4ES3.java
ExtendedInterfaceSymbolsIgnore ../build-temp/gensrc/classes/com/jogamp/opengl/GLES3.java
ExtendedInterfaceSymbolsIgnore ../src/jogl/classes/com/jogamp/opengl/GLBase.java

Style ImplOnly
ImplPackage jogamp.opengl.es3
ImplJavaClass GLES3Impl
Implements GLES3Impl GLES2
Implements GLES3Impl GLES3
...</code></pre>
<p>Above produces the GLES3 interface and its implementation as visible
in JOGL’s UML document <a
href="https://jogamp.org/jogl/doc/uml/html/index.html">about OpenGL
Profiles</a>.</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="#struct-mapping-notes"><em>Opaque and
<code>void*</code> notes</em></a> below.</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">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="struct-mapping-notes">Struct Mapping Notes</h3>
<ul>
<li><p><a href="#opaque-java-primitive-type-symbol"><code>Opaque</code>
configured pointer-types</a> are treated as <code>long</code> values
from the Java side while maintaining their architecture dependent
pointer size within native memory.</p></li>
<li><p>Void pointers, i.e. <code>void*</code>, within a struct are
handled as <a
href="#opaque-java-primitive-type-symbol"><code>Opaque</code> configured
pointer-types</a>.</p></li>
<li><p><em>ConstElemCount</em> via <strong>ReturnedArrayLength
&lt;int&gt;</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> below.</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-ownership">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="gluegen-struct-settings">GlueGen Struct Settings</h3>
<h4 id="opaque-java-primitive-type-symbol"><strong>Opaque</strong>
<em>Java-primitive-type</em> <em>symbol</em></h4>
<p>See also <a
href="https://jogamp.org/gluegen/doc/manual/index.html#SecOpaque">Opaque
section in manual</a>.</p>
<ul>
<li><p><code>Opaque long T2_UndefStruct*</code></p>
<p>Pointers to <code>T2_UndefStruct</code> will be handled opaque,
i.e. as <code>long</code> values from the Java side while maintaining
their architecture dependent pointer size within native memory.</p></li>
</ul>
<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-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>Array owned by parent struct itself
<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>Referenced Memory (array) owned by Java
<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>Referenced Memory (array) owned by Native Code due to set
<em>ConstElemCount</em>
<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> &amp; <em>ConstValue</em> &amp;
<em>ConstElemCount</em>: Drops setter, native ownership on
const-value</li>
<li><em>Array</em> &amp; <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> &amp; <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> &amp; <em>isByteBuffer</em> &amp; <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 &lt;= <em>elemCount</em>, otherwise
Exception</li>
<li><em>Pointer</em> &amp; <em>VariaElemCount</em>: Reuse
<em>native</em> memory and store value with &lt;= <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>
<colgroup>
<col style="width: 4%" />
<col style="width: 7%" />
<col style="width: 33%" />
<col style="width: 19%" />
<col style="width: 24%" />
<col style="width: 5%" />
<col style="width: 5%" />
</colgroup>
<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>’ -&gt; (int32_t) </em> , size
[fixed false, lnx64 8], const[false], pointer*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>’ -&gt; (const int32_t) </em>
, size [fixed false, lnx64 8], const[false], pointer*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 &gt;= 0<code>&amp;&amp;</code>srcPos + length &lt;= src.length`,
otherwise an IndexOutOfBoundsException is thrown</li>
<li>destPos starting element position within the destination with
’destPos &gt;= 0<code>&amp;&amp;</code>destPos + length &lt;=
elemCount`, otherwise an exception is thrown</li>
<li>length the element count to be copied with ’length &gt;=
0<code>&amp;&amp;</code>srcPos + length &lt;=
src.length<code>&amp;&amp;</code>destPos + length &lt;= 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>’ -&gt; (int32_t) </em> , size
[fixed false, lnx64 8], const[false], pointer*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 &gt;= 0<code>&amp;&amp;</code>srcPos + length &lt;= src.length`,
otherwise an IndexOutOfBoundsException is thrown</li>
<li>destPos starting element position within the destination with
’destPos &gt;= 0<code>&amp;&amp;</code>destPos + length &lt;=
elemCount`, otherwise an exception is thrown</li>
<li>length the element count to be copied with ’length &gt;=
0<code>&amp;&amp;</code>srcPos + length &lt;=
src.length<code>&amp;&amp;</code>destPos + length &lt;= 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>’ -&gt; (int32_t) </em> , size
[fixed false, lnx64 8], const[false], pointer*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 &gt;= 0<code>&amp;&amp;</code>srcPos + length &lt;= src.length`,
otherwise an IndexOutOfBoundsException is thrown</li>
<li>destPos starting element position within the destination with
’destPos &gt;= 0<code>. If</code>subset == true<code>,</code>destPos +
length &lt;= elemCount<code>also must be be</code>true`. Otherwise an
exception is thrown</li>
<li>length the element count to be copied with ’length &gt;=
0<code>&amp;&amp;</code>srcPos + length &lt;= 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>’ -&gt; (const int32_t) </em>
, size [fixed false, lnx64 8], const[false], pointer*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 &gt;= 0<code>&amp;&amp;</code>srcPos + length &lt;= src.length`,
otherwise an IndexOutOfBoundsException is thrown</li>
<li>length the element count to be copied with ’length &gt;=
0<code>&amp;&amp;</code>srcPos + length &lt;= 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>’ -&gt; (int32_t) </em> , size
[fixed false, lnx64 8], const[false], pointer*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 &gt;= 0<code>&amp;&amp;</code>srcPos + length &lt;= src.length`,
otherwise an IndexOutOfBoundsException is thrown</li>
<li>destPos starting element position within the destination with
’destPos &gt;= 0<code>. If</code>subset == true<code>,</code>destPos +
length &lt;= elemCount<code>also must be be</code>true`. Otherwise an
exception is thrown</li>
<li>length the element count to be copied with ’length &gt;=
0<code>&amp;&amp;</code>srcPos + length &lt;= 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>’ -&gt; (const int32_t) </em>
, size [fixed false, lnx64 8], const[false], pointer*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 &gt;= 0<code>&amp;&amp;</code>srcPos + length &lt;= src.length`,
otherwise an IndexOutOfBoundsException is thrown</li>
<li>length the element count to be copied with ’length &gt;=
0<code>&amp;&amp;</code>srcPos + length &lt;= 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, generating
function calls as methods as well function-pointer opaque getter and
setter as <code>long</code> types. 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 &lt;code&gt;CustomFuncA1&lt;/code&gt;, being a &lt;i&gt;struct&lt;/i&gt; owned function pointer.
   * &lt;p&gt;
   * Native Field Signature &lt;code&gt;(PointerType) typedef &#39;T2_CustomFuncA&#39; -&gt; int32_t (*)(void *  aptr), size [fixed false, lnx64 8], const[false], pointer*1, funcPointer&lt;/code&gt;
   * &lt;/p&gt;
   */
  public final long getCustomFuncA1() { .. }

  /** Interface to C language function: &lt;br&gt; &lt;code&gt;int32_t CustomFuncA1(void *  aptr)&lt;/code&gt;&lt;br&gt;   */
  public final int CustomFuncA1(long aptr)  { ... }</code></pre>
<p>and similar to <code>T2_CustomFuncB customFuncB1</code></p>
<pre><code>  /**
   * Setter for native field &lt;code&gt;CustomFuncB1&lt;/code&gt;, being a &lt;i&gt;struct&lt;/i&gt; owned function pointer.
   * &lt;p&gt;
   * Native Field Signature &lt;code&gt;(PointerType) typedef &#39;T2_CustomFuncB&#39; -&gt; int32_t (*)(T2_UserData *  pUserData), size [fixed false, lnx64 8], const[false], pointer*1, funcPointer&lt;/code&gt;
   * &lt;/p&gt;
   */
  public final T2_InitializeOptions setCustomFuncB1(long src) { .. }

  /**
   * Getter for native field &lt;code&gt;CustomFuncB1&lt;/code&gt;, being a &lt;i&gt;struct&lt;/i&gt; owned function pointer.
   * &lt;p&gt;
   * Native Field Signature &lt;code&gt;(PointerType) typedef &#39;T2_CustomFuncB&#39; -&gt; int32_t (*)(T2_UserData *  pUserData), size [fixed false, lnx64 8], const[false], pointer*1, funcPointer&lt;/code&gt;
   * &lt;/p&gt;
   */
  public final long getCustomFuncB1() { .. }

  /** Interface to C language function: &lt;br&gt; &lt;code&gt;int32_t CustomFuncB1(T2_UserData *  pUserData)&lt;/code&gt;&lt;br&gt;   */
  public final int CustomFuncB1(T2_UserData pUserData)  { .. }</code></pre>
<h2 id="java-callback">Java Callback</h2>
<p>GlueGen supports registering Java callback methods to receive
asynchronous and off-thread native toolkit events, where a generated
native callback function dispatches the events to Java.</p>
<h3 id="implementation-details">Implementation Details</h3>
<p>Implementation generates a static Java callback dispatcher for each
defined <code>SetCallbackFunction</code>, which gets invoked by the
generated native static counterpart with all arguments required.</p>
<p>The <em>static callback</em> utilizes its own synchronization for
thread-safety and fetches the required data set stored at
<code>SetCallbackFunction</code> to dispatch the call to the users’
<code>CallbackFunction</code>. In case the callback has been removed
already, the <em>static callback</em> simply bails out quietly.</p>
<p>The native code does not create, release or manage heap memory and
therefore is considered safe.</p>
<h3 id="javacallback-userparam-mapping"><em>JavaCallback</em>
<em>UserParam</em> Mapping</h3>
<p>Usually the same <code>UserParam</code> type is used in both items
(or hooks), <code>SetCallbackFunctionName</code> and
<code>CallbackFunctionType</code>, which we call a homogeneous
<code>UserParam</code> mapping.</p>
<p>Even in a homogeneous <code>UserParam</code> mapping, handling of the
<code>UserParam</code> value might differ in the native binding
code.</p>
<p>To specify a non homogeneous <code>UserParam</code> mapping,
i.e. heterogeneous <code>UserParam</code> mapping, the
<code>UserParam</code> index of the <code>SetCallbackFunction</code>
must be <a href="#javacallback-configuration">set in the
configuration</a>.</p>
<p>The following mappings are supported.</p>
<h4 id="pure-java-object-user-type-default">Pure Java Object User Type
(default)</h4>
<p>A pure Java <em>Object type</em> is used for both,
<code>SetCallbackFunctionName</code> and
<code>CallbackFunctionType</code>.</p>
<p>It’s a homogeneous <code>UserParam</code> mapping, where the native
side receives a simple unique ID and shall not dereference the
<em>pointer</em>.</p>
<p>The static Java callback dispatcher fetches the Java
<code>UserParam</code> <em>Object</em> from the key-mapped data
value.</p>
<p>Instead of using the default plain Java <code>Object</code> type, a
<a href="#custom-callback-userparamclass">custom
<em>UserParamClass</em></a> can be specified <a
href="#javacallback-configuration">in the configuration</a>, which is
recommended for more clarity in the resulting API.</p>
<h4 id="struct-type-user-param-homogeneous">Struct Type User Param
(Homogeneous)</h4>
<p>A <a href="#struct-mapping">GlueGen generated <em>Struct
type</em></a> is used for both, <code>SetCallbackFunctionName</code> and
<code>CallbackFunctionType</code>.</p>
<p>It’s a homogeneous <code>UserParam</code> mapping, where the native
side receives the actual native struct address.</p>
<p>The static Java callback dispatcher dereferences the received native
struct address (<em>long</em>), i.e. rebuilding the <em>struct
Object</em> to be passed to the users’
<code>CallbackFunction</code>.</p>
<h4 id="struct-type-user-param-heterogeneous">Struct Type User Param
(Heterogeneous)</h4>
<p>An anonymous pointer (<em>long</em>) for
<code>SetCallbackFunctionName</code> and a <a
href="#struct-mapping">GlueGen generated <em>struct type</em></a> for
<code>CallbackFunctionType</code> is being used.</p>
<p>It’s a heterogeneous <code>UserParam</code> mapping, where the
toolkit is expected to place the given anonymous pointer inside the
defined <em>struct type</em> passed to the
<code>CallbackFunction</code>.</p>
<p>The <code>SetCallback-UserParamIndex</code> for the different
parameter-type is <a href="#javacallback-configuration">set in the
configuration</a>.</p>
<p>The static Java callback dispatcher dereferences the received native
struct address (<em>long</em>), i.e. rebuilding the <em>struct
Object</em> to be passed to the users’
<code>CallbackFunction</code>.</p>
<h3 id="javacallback-configuration"><em>JavaCallback</em>
Configuration</h3>
<p>Configuration directives are as follows:</p>
<pre><code>JavaCallbackDef  &lt;SetCallbackFunctionName&gt; &lt;SetCallback-UserParamIndex&gt; &lt;CallbackFunctionType&gt; &lt;CallbackFunction-UserParamIndex&gt; [&lt;Callback-UserParamClass&gt; [&lt;Callback-KeyClass&gt;]]
JavaCallbackKey  &lt;SetCallbackFunctionName&gt; &lt;SetCallback-ParamIndex&gt;* &lt;CallbackFunctionType&gt; &lt;CallbackFunction-ParamIndex&gt;*</code></pre>
<p><code>JavaCallbackDef</code> and <code>JavaCallbackKey</code> use the
name of the <code>SetCallbackFunction</code> as its first attribute, as
it is core to the semantic mapping of all resources. They also have to
use the same <code>CallbackFunctionType</code>.</p>
<p><code>JavaCallbackDef</code> attributes:</p>
<ul>
<li><code>SetCallbackFunction</code>: <code>SetCallbackFunction</code>
name of the native toolkit API responsible to set the callback</li>
<li><code>SetCallback-UserParamIndex</code>: <code>UserParam</code>
parameter-index of the <code>SetCallbackFunction</code> or
<code>&lt;0</code> to disable <code>UserParam</code></li>
<li><code>CallbackFunctionType</code>: The native toolkit API
typedef-name of the function-pointer-type, aka the callback type
name</li>
<li><code>CallbackFunction-UserParamIndex</code>: The
<code>userParam</code> parameter-index of the
<code>CallbackFunctionType</code>, which allows to <a
href="#struct-type-user-param-heterogeneous">indicate a heterogeneous
<code>UserParam</code></a> or <code>&lt;0</code> to disable
<code>UserParam</code></li>
<li><code>Callback-UserParamClass</code>: Optional <a
href="#custom-callback-userparamclass">custom
<em>UserParamClass</em></a> overriding the default <code>Object</code>
for non-compound <code>UserParam</code> types.</li>
<li><code>Callback-KeyClass</code>: Optional <a
href="#custom-callback-keyclass">custom <em>KeyClass</em></a>, providing
the hash-map-key.</li>
</ul>
<p>The <code>SetCallbackFunction</code> is utilized to set the
<code>CallbackFunction</code> as well as to remove it passing
<code>null</code> for the <code>CallbackFunction</code>.</p>
<p>If mapping the <code>CallbackFunction</code> to keys, the user must
specify the same key arguments when setting and removing the
<code>CallbackFunction</code>.</p>
<h4 id="javacallback-key-definition"><em>JavaCallback</em> Key
Definition</h4>
<p>If no keys are defined via <code>JavaCallbackKey</code> or not
manually injected using a custom <code>Callback-KeyClass</code>, see
below, the <code>CallbackFunction</code> has global scope.</p>
<p>In case keys are defined via <code>JavaCallbackKey</code> and no
manually injected custom <code>Callback-KeyClass</code> used, a public
<code>Callback-KeyClass</code> is being generated covering the defined
keys.</p>
<p>Keys allow to limit the scope, i.e. map multiple
<code>CallbackFunction</code> to the different keys.</p>
<p>To remove a previously set <code>CallbackFunction</code> via
<code>SetCallbackFunction</code>, the key arguments must match.</p>
<p><code>JavaCallbackKey</code> attributes</p>
<ul>
<li><code>SetCallbackFunction</code>: <code>SetCallbackFunction</code>
name of the native toolkit API responsible to set the callback</li>
<li><code>SetCallback-ParamIndex</code>: List of parameter indices of
the <code>SetCallbackFunction</code>, denoting the key(s) limiting the
callback scope, i.e. the callback and all resources will be mapped to
this key. The optional <code>Callback-KeyClass</code> may override this
semantic.</li>
<li><code>CallbackFunctionType</code>: The native toolkit API
typedef-name of the function-pointer-type, the same callback type name
as defined in <code>JavaCallbackDef</code></li>
<li><code>CallbackFunction-ParamIndex</code>: List of parameter indices
of the <code>CallbackFunctionType</code>, matching the semantic
parameter of <code>SetCallback-ParamIndex</code>.</li>
</ul>
<h4 id="custom-callback-userparamclass">Custom
<code>Callback-UserParamClass</code></h4>
<p>Instead of using the default plain Java <code>Object</code> for
non-compound <code>UserParam</code> types, a custom
<code>Callback-UserParamClass</code> can be specified <a
href="#javacallback-configuration">in the configuration</a>, which
produces more clarity in the resulting API.</p>
<h4 id="custom-callback-keyclass">Custom
<code>Callback-KeyClass</code></h4>
<p>The <code>Callback-KeyClass</code> is the optional user-written
hash-map-key definition and shall handle all key parameter of the
<code>SetCallbackFunction</code> as defined via
<code>JavaCallbackKey</code>, see above.</p>
<p><code>Callback-KeyClass</code> may be used to add external
key-components, e.g. current-thread or a toolkit dependent context.</p>
<p>The <code>Callback-KeyClass</code> shall implement the following
hash-map-key standard methods</p>
<ul>
<li><code>boolean equals(Object)</code></li>
<li><code>int hashCode()</code></li>
<li><code>Callback-KeyClassName(...)</code> constructor receiving all
key parameter of <code>SetCallbackFunction</code> as defined via
<code>JavaCallbackKey</code>, see above.</li>
</ul>
<h4 id="required-libraryonload">Required <em>LibraryOnLoad</em></h4>
<p>Note that <a
href="#libraryonload-librarybasename-for-jni_onload-"><code>LibraryOnLoad &lt;LibraryBasename&gt;</code></a>
must be specified in exactly one native code-unit within one native
library.</p>
<p>It provides code to allow the generated native callback-function to
attach the current thread to the <code>JavaVM*</code>, retrieving a
valid <code>JNIEnv*</code>, see <a
href="#libraryonload-librarybasename-for-jni_onload-"><code>LibraryOnLoad &lt;LibraryBasename&gt;</code></a>
for details.</p>
<h3
id="javacallback-generated-interfaces-classes-and-methods"><em>JavaCallback</em>
Generated Interfaces, Classes and Methods</h3>
<p>The public <code>CallbackFunction</code> interface is generated.</p>
<p>The default public <code>Callback-KeyClass</code> is generated if
keys are used and no custom class is specified, see above.</p>
<p>The public toolkit API <code>SetCallbackFunction</code> method is
being generated.</p>
<p>Additional public <em>maintenance</em> methods are generated. In case
keys are being used, they expect <code>Callback-KeyClass</code> as an
argument, otherwise they expect no argument for global scope.</p>
<p>In case a <code>Callback-KeyClass</code> is used, the additional
<em>maintenance</em> methods are:</p>
<ul>
<li><em>Set&lt;<code>Callback-KeyClass</code>&gt;
get<code>SetCallbackFunctionName</code>Keys()</em></li>
<li><em>boolean
is<code>SetCallbackFunctionName</code>Mapped(<code>Callback-KeyClass</code>)</em>
queries whether <code>SetCallbackFunctionName</code> is mapped to
key.</li>
<li><em><code>CallbackFunction</code>
get<code>SetCallbackFunctionName</code>(<code>Callback-KeyClass</code>)</em>
returns the mapped <code>CallbackFunction</code>, null if not
mapped</li>
<li><em><code>Callback-UserParamClass</code>
get<code>SetCallbackFunctionName</code>UserParam(<code>Callback-KeyClass</code>)</em>
returns the mapped <code>userParam</code> object, null if not
mapped</li>
<li><em>void
release<code>SetCallbackFunctionName</code>(<code>Callback-KeyClass</code>)</em>
releases the mapped <code>CallbackFunction</code> data set associated
via <code>SetCallbackFunctionName</code>.</li>
<li><em>int releaseAll<code>SetCallbackFunctionName</code>()</em>
releases complete mapped <code>CallbackFunction</code> data set
associated via <code>SetCallbackFunctionName</code>.</li>
</ul>
<p>If no <code>Callback-KeyClass</code> is used, the additional
<em>maintenance</em> methods are:</p>
<ul>
<li><em>boolean is<code>SetCallbackFunctionName</code>Mapped()</em>
queries whether <code>SetCallbackFunctionName</code> is mapped.</li>
<li><em><code>CallbackFunction</code>
get<code>SetCallbackFunctionName</code>()</em> returns the mapped
<code>CallbackFunction</code>, null if not mapped</li>
<li><em><code>Callback-UserParamClass</code>
get<code>SetCallbackFunctionName</code>UserParam()</em> returns the
mapped <code>userParam</code> object, null if not mapped</li>
<li><em>void release<code>SetCallbackFunctionName</code>()</em> releases
the mapped <code>CallbackFunction</code> data set associated via
<code>SetCallbackFunctionName</code>.</li>
</ul>
<p>Note that the <em>release<code>SetCallbackFunctionName</code>(*)</em>
and <em>releaseAll<code>SetCallbackFunctionName</code>()</em> methods
are not the <em>proper toolkit API way</em> to remove the callback, try
to use original <code>SetCallbackFunctionName</code> API method instead
using a <code>null</code> <code>CallbackFunction</code> reference.</p>
<h3 id="javacallback-notes"><em>JavaCallback</em> Notes</h3>
<p>Please consider the following <em>currently enabled</em> constraints
using JavaCallback</p>
<ul>
<li>Only one interface callback-method binding is allowed for a native
callback function, e.g. <code>T2_CallbackFunc01</code> (see above)
<ul>
<li>Implying that the native single function-pointer typedef must be
mapped to a single Java method within its interface</li>
<li>Hence it must be avoided that multiple method variation are
produced, e.g. due to <code>char*</code> to <code>byte[]</code> and
<code>String</code> mapping etc.</li>
</ul></li>
<li>The native callback function can only return no-value,
i.e. <code>void</code>, or a primitive type. Usually <code>void</code>
is being used in toolkit APIs.</li>
<li>The native callback function argument types must be convertible to
JNI Java types as (previously) supported for function return values,
using the same conversion function
<code>CMethodBindingEmitter.emitBodyMapCToJNIType(..)</code>.</li>
<li>To remove a JavaCallback the <code>SetCallbackFunction</code> must
be called with <code>null</code> for the <code>CallbackFunction</code>
argument but with the same <a
href="#javacallback-key-definition"><em>key arguments</em> (see
<code>JavaCallbackKey</code>)</a> as previously called to set the
callback.</li>
<li>Exactly one native code-unit within the library must specify <a
href="#libraryonload-librarybasename-for-jni_onload-"><code>LibraryOnLoad libraryBasename</code></a></li>
<li><code>SetCallbackFunction</code>, all <em>maintenance</em> methods
and the native callback dispatcher <strong>are thread-safe</strong></li>
<li>…</li>
</ul>
<h3 id="javacallback-example-1">JavaCallback Example 1</h3>
<p>This example demonstrates a <a
href="#pure-java-object-user-type-default">homogeneous <em>Java
Object</em> <code>UserParam</code> mapping</a> with a <a
href="#javacallback-key-definition">globally scoped</a>
<code>CallbackFunction</code> and <code>UserParam</code>.</p>
<p>The callback <code>T2_CallbackFunc01</code> has global scope, i.e. is
not mapped to any key and can be only set globally.</p>
<p>C-API header snippet:</p>
<pre><code>typedef void ( * T2_CallbackFunc01)(size_t id, const char* msg, void* usrParam);

/** Sets the given `cbFunc` and associated `usrParam` as the callback. Passing NULL for `func` _and_ same `usrParam` removes the callback and its associated resources. */
void MessageCallback01(T2_CallbackFunc01 cbFunc, void* usrParam);

void InjectMessageCallback01(size_t id, const char* msg);</code></pre>
<p>and the following GlueGen configuration</p>
<pre><code>
# JavaCallback requires `JNI_OnLoad*(..)` and `JVMUtil_GetJNIEnv(..)`
LibraryOnLoad Bindingtest2

ArgumentIsString T2_CallbackFunc01 1
ArgumentIsString InjectMessageCallback01 1

# Define a JavaCallback.
#   Set JavaCallback via function `MessageCallback01` if `T2_CallbackFunc01` argument is non-null, otherwise removes the mapped callback and associated resources.
#
#   It uses the function-pointer argument `T2_CallbackFunc01` as the callback function type
#   and marks `T2_CallbackFunc01`s 3rd argument (index 2) as the mandatory user-param.
#
#   This callback has no keys defines, rendering it of global scope!
#
#   Explicit maintenance methods are generated, passing the keys as paramters
#   - `boolean isMessageCallback01Mapped()` queries whether `MessageCallback0` is mapped globally
#   - `T2_CallbackFunc01 getMessageCallback01()` returns the global T2_CallbackFunc01, null if not mapped
#   - `Object getMessageCallback01UserParam()` returns the global `usrParam` object, null if not mapped
#   - `void releaseMessageCallback01()` releases callback data skipping toolkit API. Favor passing `null` callback ref to `MessageCallback01(..)`
JavaCallbackDef  MessageCallback01 1 T2_CallbackFunc01 2
</code></pre>
<p>Note that <a
href="#libraryonload-librarybasename-for-jni_onload-"><code>LibraryOnLoad Bindingtest2</code></a>
must be specified in exactly one native code-unit within the library. It
provides code to allow the generated native callback-function to attach
the current thread to the <code>JavaVM*</code> generating a new
<code>JNIEnv*</code>in daemon mode - or just to retrieve the thread’s
<code>JNIEnv*</code>, if already attached to the
<code>JavaVM*</code>.</p>
<p>This will lead to the following interface</p>
<pre><code>public interface Bindingtest2 {

  /** JavaCallback interface: T2_CallbackFunc01 -&gt; void (*T2_CallbackFunc01)(size_t id, const char *  msg, void *  usrParam) */
  public static interface T2_CallbackFunc01 {
    /** Interface to C language function: &lt;br&gt; &lt;code&gt;void callback(size_t id, const char *  msg, void *  usrParam)&lt;/code&gt;&lt;br&gt;Alias for: &lt;code&gt;T2_CallbackFunc01&lt;/code&gt;     */
    public void callback(long id, String msg, Object usrParam);
  }

  ...

  /** Entry point (through function pointer) to C language function: &lt;br&gt; &lt;code&gt;void MessageCallback01(T2_CallbackFunc01 cbFunc, void *  usrParam)&lt;/code&gt;&lt;br&gt;   */
  public void MessageCallback01(T2_CallbackFunc01 cbFunc, Object usrParam);

  /** Returns if callback is mapped for &lt;br&gt; &lt;code&gt;  public void MessageCallback01(T2_CallbackFunc01 cbFunc, Object usrParam)&lt;/code&gt; **/
  public boolean isMessageCallback01Mapped();

  /** Returns T2_CallbackFunc01 callback for &lt;br&gt; &lt;code&gt;  public void MessageCallback01(T2_CallbackFunc01 cbFunc, Object usrParam)&lt;/code&gt; **/
  public T2_CallbackFunc01 getMessageCallback01();

  /** Returns user-param for &lt;br&gt; &lt;code&gt;  public void MessageCallback01(T2_CallbackFunc01 cbFunc, Object usrParam)&lt;/code&gt; **/
  public Object getMessageCallback01UserParam();

  /** Releases callback data skipping toolkit API. Favor passing `null` callback ref to &lt;br&gt; &lt;code&gt;  public void MessageCallback01(T2_CallbackFunc01 cbFunc, Object usrParam)&lt;/code&gt; **/
  public void releaseMessageCallback01();

  /** Entry point (through function pointer) to C language function: &lt;br&gt; &lt;code&gt;void InjectMessageCallback01(size_t id, const char *  msg)&lt;/code&gt;&lt;br&gt;   */
  public void InjectMessageCallback01(long id, String msg);</code></pre>
<h3 id="javacallback-example-2a-default-keyclass">JavaCallback Example
2a (Default <em>KeyClass</em>)</h3>
<p>This example demonstrates a <a
href="#pure-java-object-user-type-default">homogeneous <em>Java
Object</em> <code>UserParam</code> mapping</a> with a <a
href="#javacallback-key-definition">key-mapped</a>
<code>CallbackFunction</code> and <code>UserParam</code>.</p>
<p>Additionally a <a href="#custom-callback-userparamclass">custom
<em>UserParamClass</em></a> <code>ALCcontext</code> is being used for
more clarity in the resulting API.</p>
<p>This example is derived from OpenAL’s
<code>AL_SOFT_callback_buffer</code> extension.</p>
<p>The callback <code>ALBUFFERCALLBACKTYPESOFT</code> is mapped to
<code>buffer</code> name, i.e. one callback can be set for each
buffer.</p>
<p>C-API Header snipped</p>
<pre><code>  typedef void ( * ALBUFFERCALLBACKTYPESOFT)(int buffer /* key */, void *userptr, int sampledata, int numbytes);

  void alBufferCallback0(int buffer /* key */, int format, int freq, ALBUFFERCALLBACKTYPESOFT callback, void *userptr);

  void alBufferCallback0Inject(int buffer, int sampledata, int numbytes);</code></pre>
<p>and the following GlueGen configuration</p>
<pre><code>  # Define a JavaCallback.
  #   Set JavaCallback via function `alBufferCallback0` if `ALBUFFERCALLBACKTYPESOFT` argument is non-null, otherwise removes the mapped callback and associated resources.
  #
  #   It uses the function-pointer argument `ALBUFFERCALLBACKTYPESOFT` as the callback function type
  #   and marks `ALBUFFERCALLBACKTYPESOFT`s 2nd argument (index 1) as the mandatory user-param.
  #
  #   This callback defines one key, `buffer`, index 0 of alBufferCallback0(..) parameter list, limiting it to buffer-name scope!
  #   The `buffer` key allows setting one callback per buffer-name, compatible with the `AL_SOFT_callback_buffer` spec.
  #
  #   Explicit queries are generated, passing the keys as paramters
  #   - `Set&lt;AlBufferCallback0Key&gt; getAlBufferCallback0Keys()` returns set of Key { int buffer }
  #   - `boolean isAlBufferCallback0Mapped(AlBufferCallback0Key)` queries whether `alBufferCallback0` is mapped to `buffer`.
  #   - `ALBUFFERCALLBACKTYPESOFT getAlBufferCallback0(AlBufferCallback0Key)` returns the `buffer` mapped ALEVENTPROCSOFT, null if not mapped
  #   - `ALCcontext getAlBufferCallback0UserParam(AlBufferCallback0Key)` returns the `buffer` mapped `userptr` object, null if not mapped
  #   - `void releaseAllAlBufferCallback0()` releases all callback data mapped via Key { int buffer } skipping toolkit API. Favor passing `null` callback ref to `alBufferCallback0(..)`
  #   - `void releaseAlBufferCallback0(AlBufferCallback0Key)` releases callback data mapped to Key { int buffer } skipping toolkit API. Favor passing `null` callback ref to `alBufferCallback0(..)`
  JavaCallbackDef  alBufferCallback0 4 ALBUFFERCALLBACKTYPESOFT 1 ALCcontext
  JavaCallbackKey  alBufferCallback0 0 ALBUFFERCALLBACKTYPESOFT 0</code></pre>
<p>leading to the following interface</p>
<pre><code>  /** JavaCallback interface: ALBUFFERCALLBACKTYPESOFT -&gt; void (*ALBUFFERCALLBACKTYPESOFT)(int buffer, void *  userptr, int sampledata, int numbytes) */
  public static interface ALBUFFERCALLBACKTYPESOFT {
    /** Interface to C language function: &lt;br&gt; &lt;code&gt;void callback(int buffer, void *  userptr, int sampledata, int numbytes)&lt;/code&gt;&lt;br&gt;Alias for: &lt;code&gt;ALBUFFERCALLBACKTYPESOFT&lt;/code&gt;     */
    public void callback(int buffer, ALCcontext userptr, int sampledata, int numbytes);
  }

  ...

  /** Key { int buffer } for &lt;br&gt; &lt;code&gt;  public void alBufferCallback0(int buffer, int format, int freq, ALBUFFERCALLBACKTYPESOFT callback, Object userptr)&lt;/code&gt; **/
  public static class AlBufferCallback0Key {
    public final int buffer;
    public AlBufferCallback0Key(int buffer) {
      this.buffer = buffer;
    }
    @Override
    public boolean equals(final Object o) {
      if( this == o ) {
        return true;
      }
      if( !(o instanceof AlBufferCallback0Key) ) {
        return false;
      }
      final AlBufferCallback0Key o2 = (AlBufferCallback0Key)o;
      return buffer == o2.buffer;
    }
    @Override
    public int hashCode() {
      // 31 * x == (x &lt;&lt; 5) - x
      int hash = buffer;
      return hash;
    }
  }

  ...

  /** Returns set of Key { int buffer } for &lt;br&gt; &lt;code&gt;  void alBufferCallback0(int buffer, int format, int freq, ALBUFFERCALLBACKTYPESOFT callback, ALCcontext userptr)&lt;/code&gt; */
  public Set&lt;AlBufferCallback0Key&gt; getAlBufferCallback0Keys();

  /** Returns whether callback Key { int buffer } is mapped for &lt;br&gt; &lt;code&gt;  void alBufferCallback0(int buffer, int format, int freq, ALBUFFERCALLBACKTYPESOFT callback, ALCcontext userptr)&lt;/code&gt; */
  public boolean isAlBufferCallback0Mapped(AlBufferCallback0Key key);

  /** Returns ALBUFFERCALLBACKTYPESOFT callback mapped to Key { int buffer } for &lt;br&gt; &lt;code&gt;  void alBufferCallback0(int buffer, int format, int freq, ALBUFFERCALLBACKTYPESOFT callback, ALCcontext userptr)&lt;/code&gt; */
  public ALBUFFERCALLBACKTYPESOFT getAlBufferCallback0(AlBufferCallback0Key key);

  /** Returns user-param mapped to Key { int buffer } for &lt;br&gt; &lt;code&gt;  void alBufferCallback0(int buffer, int format, int freq, ALBUFFERCALLBACKTYPESOFT callback, ALCcontext userptr)&lt;/code&gt; */
  public ALCcontext getAlBufferCallback0UserParam(AlBufferCallback0Key key);

  /** Releases all callback data mapped via Key { int buffer } skipping toolkit API. Favor passing `null` callback ref to &lt;br&gt; &lt;code&gt;  void alBufferCallback0(int buffer, int format, int freq, ALBUFFERCALLBACKTYPESOFT callback, ALCcontext userptr)&lt;/code&gt; */
  public int releaseAllAlBufferCallback0();

  /** Releases callback data mapped to Key { int buffer } skipping toolkit API. Favor passing `null` callback ref to &lt;br&gt; &lt;code&gt;  void alBufferCallback0(int buffer, int format, int freq, ALBUFFERCALLBACKTYPESOFT callback, ALCcontext userptr)&lt;/code&gt; */
  public void releaseAlBufferCallback0(AlBufferCallback0Key key);

  /** Entry point (through function pointer) to C language function: &lt;br&gt; &lt;code&gt;void alBufferCallback0(int buffer, int format, int freq, ALBUFFERCALLBACKTYPESOFT callback, void *  userptr)&lt;/code&gt;&lt;br&gt;   */
  public void alBufferCallback0(int buffer, int format, int freq, ALBUFFERCALLBACKTYPESOFT callback, ALCcontext userptr);

  /** Entry point (through function pointer) to C language function: &lt;br&gt; &lt;code&gt;void alBufferCallback0Inject(int buffer, int sampledata, int numbytes)&lt;/code&gt;&lt;br&gt;   */
  public void alBufferCallback0Inject(int buffer, int sampledata, int numbytes);</code></pre>
<h3
id="javacallback-example-2b-custom-keyclass-different-key-parameter-order">JavaCallback
Example 2b (Custom <em>KeyClass</em>, different key-parameter
order)</h3>
<p>Similar example as example 2a, but using a <a
href="#custom-callback-keyclass">custom <em>KeyClass</em></a> to map
<code>CallbackFunction</code> and <code>UserParam</code> and also
accommodating a different key-parameter order between
<code>SetCallbackFunction</code> and <code>CallbackFunction</code>.</p>
<p>C-API Header snipped</p>
<pre><code>  typedef void ( * ALBUFFERCALLBACKTYPESOFT)(int buffer /* key */, void *userptr, int sampledata, int numbytes);

  void alBufferCallback1(void *user_ptr, int buffer_key /* key */, int format, int freq, ALBUFFERCALLBACKTYPESOFT callback);

  void alBufferCallback1Inject(int buffer, int sampledata, int numbytes);</code></pre>
<p>GlueGen configuration snippet with the added option attribute for the
<code>Callback-KeyClass</code> in directive
<code>JavaCallbackDef</code>.</p>
<pre><code>JavaCallbackDef  alBufferCallback1 0 ALBUFFERCALLBACKTYPESOFT 1 ALCcontext com.jogamp.gluegen.test.junit.generation.BaseClass4JavaCallback.CustomAlBufferCallback1Key
JavaCallbackKey  alBufferCallback1 1 ALBUFFERCALLBACKTYPESOFT 0
</code></pre>
<p>Implementation utilizes a custom <code>Callback-KeyClass</code>
implementation for
<code>void alBufferCallback1(int buffer, int format, int freq, ALBUFFERCALLBACKTYPESOFT callback, ALCcontext userptr)</code>,
which uses one key, i.e. <code>buffer</code>.</p>
<pre><code>    public static class CustomAlBufferCallback1Key {
        private final int buffer;
        public CustomAlBufferCallback1Key(final int buffer) {
            this.buffer = buffer;
        }
        @Override
        public boolean equals(final Object o) {
            if( this == o ) {
                return true;
            }
            if( !(o instanceof CustomAlBufferCallback1Key) ) {
                return false;
            }
            final CustomAlBufferCallback1Key o2 = (CustomAlBufferCallback1Key)o;
            return buffer == o2.buffer;
        }
        @Override
        public int hashCode() {
            return buffer;
        }
        @Override
        public String toString() {
            return &quot;CustomALKey[this &quot;+toHexString(System.identityHashCode(this))+&quot;, buffer &quot;+buffer+&quot;]&quot;;
        }
    }</code></pre>
<h3
id="javacallback-example-5b-userparam-part-of-2-component-key">JavaCallback
Example 5b (UserParam part of 2 component-key)</h3>
<p>Similar example as example 2a, but having the <code>UserParam</code>
as part of the 2 component-key <em>and</em> defining
<code>Callback-UserParamClass</code> class as
<code>ALCcontext</code>.</p>
<p>C-API Header snipped</p>
<pre><code>  typedef void ( * ALEVENTPROCSOFT)(int eventType, int object, int param, int length, const char *message, void *userParam /* key */);

  void alEventCallback1(int object /* key */, ALEVENTPROCSOFT callback, void *userParam /* key */);</code></pre>
<p>GlueGen configuration snippet with the added option attribute for the
<code>Callback-UserParamClass</code> in directive
<code>JavaCallbackDef</code>.</p>
<pre><code>ArgumentIsPascalString ALEVENTPROCSOFT 3 4

JavaCallbackDef  alEventCallback1 2 ALEVENTPROCSOFT 5 ALCcontext
JavaCallbackKey  alEventCallback1 0 2 ALEVENTPROCSOFT 1 5</code></pre>
<p>Resulting to the default <code>KeyClass</code></p>
<pre><code>  /** Key { int object, ALCcontext userParam } for &lt;br&gt; &lt;code&gt;  void alEventCallback1(int object, ALEVENTPROCSOFT callback, ALCcontext userParam)&lt;/code&gt; */
  public static class AlEventCallback1Key {
    public final int object;
    public final ALCcontext userParam;
    public AlEventCallback1Key(int object, ALCcontext userParam) {
      this.object = object;
      this.userParam = userParam;
    }
    @Override
    public boolean equals(final Object o) {
      if( this == o ) {
        return true;
      }
      if( !(o instanceof AlEventCallback1Key) ) {
        return false;
      }
      final AlEventCallback1Key o2 = (AlEventCallback1Key)o;
      return object == o2.object &amp;&amp;
             userParam == o2.userParam;
    }
    @Override
    public int hashCode() {
      // 31 * x == (x &lt;&lt; 5) - x
      int hash = object;
      hash = ((hash &lt;&lt; 5) - hash) + System.identityHashCode( userParam );
      return hash;
    }
  }</code></pre>
<h3 id="javacallback-example-11a-homogeneous-struct-type">JavaCallback
Example 11a (<em>Homogeneous Struct Type</em>)</h3>
<p>This example demonstrates a <a
href="#struct-type-user-param-homogeneous">homogeneous <em>Struct</em>
<code>UserParam</code> mapping</a> with a <a
href="#javacallback-key-definition">key-mapped</a>
<code>CallbackFunction</code> and <code>UserParam</code>.</p>
<p>The callback <code>T2_CallbackFunc11</code> is passed by the toolkit
to the <code>CallbackFunction</code> and by the user to the registration
method <code>MessageCallback11b(..)</code>.</p>
<p>C-API Header snipped</p>
<pre><code>  typedef struct {
    int32_t ApiVersion;
    void* Data;
    long i;
    long r;
    size_t id;
  } T2_Callback11UserType;

  typedef void ( * T2_CallbackFunc11)(size_t id, const T2_Callback11UserType* usrParam, long val);

  void MessageCallback11a(size_t id /* key */, T2_CallbackFunc11 cbFunc, const T2_Callback11UserType* usrParam);
  void MessageCallback11aInject(size_t id, long val);</code></pre>
<p>and the following GlueGen configuration</p>
<pre><code>  JavaCallbackDef  MessageCallback11a 2 T2_CallbackFunc11 1
  JavaCallbackKey  MessageCallback11a 0 T2_CallbackFunc11 0</code></pre>
<p>leading to the following interface</p>
<pre><code>  /** JavaCallback interface: T2_CallbackFunc11 -&gt; void (*T2_CallbackFunc11)(size_t id, const T2_Callback11UserType *  usrParam, long val) */
  public static interface T2_CallbackFunc11 {
    /** Interface to C language function: &lt;br&gt; &lt;code&gt;void callback(size_t id, const T2_Callback11UserType *  usrParam, long val)&lt;/code&gt;&lt;br&gt;Alias for: &lt;code&gt;T2_CallbackFunc11&lt;/code&gt;     */
    public void callback(long id, T2_Callback11UserType usrParam, long val);
  }

  ...

  public static class MessageCallback11aKey { ... }

  ...

  /** Returns set of Key { long id } for &lt;br&gt; &lt;code&gt;  void MessageCallback11a(long id, T2_CallbackFunc11 cbFunc, T2_Callback11UserType usrParam)&lt;/code&gt; */
  public Set&lt;MessageCallback11aKey&gt; getMessageCallback11aKeys();

  /** Returns whether callback Key { long id } is mapped for &lt;br&gt; &lt;code&gt;  void MessageCallback11a(long id, T2_CallbackFunc11 cbFunc, T2_Callback11UserType usrParam)&lt;/code&gt; */
  public boolean isMessageCallback11aMapped(MessageCallback11aKey key);

  /** Returns T2_CallbackFunc11 callback mapped to Key { long id } for &lt;br&gt; &lt;code&gt;  void MessageCallback11a(long id, T2_CallbackFunc11 cbFunc, T2_Callback11UserType usrParam)&lt;/code&gt; */
  public T2_CallbackFunc11 getMessageCallback11a(MessageCallback11aKey key);

  /** Returns user-param mapped to Key { long id } for &lt;br&gt; &lt;code&gt;  void MessageCallback11a(long id, T2_CallbackFunc11 cbFunc, T2_Callback11UserType usrParam)&lt;/code&gt; */
  public T2_Callback11UserType getMessageCallback11aUserParam(MessageCallback11aKey key);

  /** Releases all callback data mapped via Key { long id } skipping toolkit API. Favor passing `null` callback ref to &lt;br&gt; &lt;code&gt;  void MessageCallback11a(long id, T2_CallbackFunc11 cbFunc, T2_Callback11UserType usrParam)&lt;/code&gt; */
  public int releaseAllMessageCallback11a();

  /** Releases callback data mapped to Key { long id } skipping toolkit API. Favor passing `null` callback ref to &lt;br&gt; &lt;code&gt;  void MessageCallback11a(long id, T2_CallbackFunc11 cbFunc, T2_Callback11UserType usrParam)&lt;/code&gt; */
  public void releaseMessageCallback11a(MessageCallback11aKey key);

  /** Entry point (through function pointer) to C language function: &lt;br&gt; &lt;code&gt;void MessageCallback11a(size_t id, T2_CallbackFunc11 cbFunc, const T2_Callback11UserType *  usrParam)&lt;/code&gt;&lt;br&gt;   */
  public void MessageCallback11a(long id, T2_CallbackFunc11 cbFunc, T2_Callback11UserType usrParam);

  /** Entry point (through function pointer) to C language function: &lt;br&gt; &lt;code&gt;void MessageCallback11aInject(size_t id, long val)&lt;/code&gt;&lt;br&gt;   */
  public void MessageCallback11aInject(long id, long val);</code></pre>
<h3
id="javacallback-example-11b-heterogeneous-pointerstruct-type">JavaCallback
Example 11b (<em>Heterogeneous Pointer/Struct Type</em>)</h3>
<p>This example demonstrates a <a
href="#struct-type-user-param-heterogeneous">heterogeneous
<em>Struct</em> <code>UserParam</code> mapping</a> with a <a
href="#javacallback-key-definition">key-mapped</a>
<code>CallbackFunction</code> and <code>UserParam</code>.</p>
<p>The callback <code>T2_CallbackFunc11</code> is managed by the toolkit
and passed to the callback function, while user passes a
<code>void*</code> as a <code>long</code> value to the registration
method <code>MessageCallback11b(..)</code>. The toolkit associates the
users’ <code>void*</code> pointer with the
<code>T2_CallbackFunc11</code>.</p>
<p>C-API Header snipped</p>
<pre><code>  typedef struct {
    int32_t ApiVersion;
    void* Data;
    long i;
    long r;
    size_t id;
  } T2_Callback11UserType;

  typedef void ( * T2_CallbackFunc11)(size_t id, const T2_Callback11UserType* usrParam, long val);

  void MessageCallback11b(size_t id /* key */, T2_CallbackFunc11 cbFunc, void* Data);
  void MessageCallback11bInject(size_t id, long val);</code></pre>
<p>and the following GlueGen configuration</p>
<pre><code>  JavaCallbackDef  MessageCallback11b 2 T2_CallbackFunc11 1
  JavaCallbackKey  MessageCallback11b 0 T2_CallbackFunc11 0</code></pre>
<p>leading to the following interface</p>
<pre><code>  /** JavaCallback interface: T2_CallbackFunc11 -&gt; void (*T2_CallbackFunc11)(size_t id, const T2_Callback11UserType *  usrParam, long val) */
  public static interface T2_CallbackFunc11 {
    /** Interface to C language function: &lt;br&gt; &lt;code&gt;void callback(size_t id, const T2_Callback11UserType *  usrParam, long val)&lt;/code&gt;&lt;br&gt;Alias for: &lt;code&gt;T2_CallbackFunc11&lt;/code&gt;     */
    public void callback(long id, T2_Callback11UserType usrParam, long val);
  }

  ...

  public static class MessageCallback11bKey { ... }

  ...

  /** Returns set of Key { long id } for &lt;br&gt; &lt;code&gt;  void MessageCallback11b(long id, T2_CallbackFunc11 cbFunc, long Data)&lt;/code&gt; */
  public Set&lt;MessageCallback11bKey&gt; getMessageCallback11bKeys();

  /** Returns whether callback Key { long id } is mapped for &lt;br&gt; &lt;code&gt;  void MessageCallback11b(long id, T2_CallbackFunc11 cbFunc, long Data)&lt;/code&gt; */
  public boolean isMessageCallback11bMapped(MessageCallback11bKey key);

  /** Returns T2_CallbackFunc11 callback mapped to Key { long id } for &lt;br&gt; &lt;code&gt;  void MessageCallback11b(long id, T2_CallbackFunc11 cbFunc, long Data)&lt;/code&gt; */
  public T2_CallbackFunc11 getMessageCallback11b(MessageCallback11bKey key);

  /** Returns user-param mapped to Key { long id } for &lt;br&gt; &lt;code&gt;  void MessageCallback11b(long id, T2_CallbackFunc11 cbFunc, long Data)&lt;/code&gt; */
  public Object getMessageCallback11bUserParam(MessageCallback11bKey key);

  /** Releases all callback data mapped via Key { long id } skipping toolkit API. Favor passing `null` callback ref to &lt;br&gt; &lt;code&gt;  void MessageCallback11b(long id, T2_CallbackFunc11 cbFunc, long Data)&lt;/code&gt; */
  public int releaseAllMessageCallback11b();

  /** Releases callback data mapped to Key { long id } skipping toolkit API. Favor passing `null` callback ref to &lt;br&gt; &lt;code&gt;  void MessageCallback11b(long id, T2_CallbackFunc11 cbFunc, long Data)&lt;/code&gt; */
  public void releaseMessageCallback11b(MessageCallback11bKey key);

  /** Entry point (through function pointer) to C language function: &lt;br&gt; &lt;code&gt;void MessageCallback11b(size_t id, T2_CallbackFunc11 cbFunc, void *  Data)&lt;/code&gt;&lt;br&gt;   */
  public void MessageCallback11b(long id, T2_CallbackFunc11 cbFunc, long Data);

  /** Entry point (through function pointer) to C language function: &lt;br&gt; &lt;code&gt;void MessageCallback11bInject(size_t id, long val)&lt;/code&gt;&lt;br&gt;   */
  public void MessageCallback11bInject(long id, long val);</code></pre>
<h3 id="javacallback-example-12-without-userparam">JavaCallback Example
12 (Without UserParam)</h3>
<p>This example demonstrates a JavaCallBack without user param and only
a global key.</p>
<p>The callback <code>T2_CallbackFunc12</code> is managed by the toolkit
and passed to the callback function, while user passes JavaCallback to
the registration method <code>SetLogCallBack(..)</code>.</p>
<p>C-API Header snipped</p>
<pre><code>  typedef enum {
    LOG_Off = 0,
    LOG_Fatal = 100,
    LOG_Error = 200,
    LOG_Warning = 300,
    LOG_Info = 400,
    LOG_Verbose = 500,
    LOG_VeryVerbose = 600
  } LogLevel;

  typedef struct {
    const char* Category;
    const char* Message;
    LogLevel Level;
  } LogMessage;

  typedef void ( * T2_CallbackFunc12)(const LogMessage* usrParam);

  void SetLogCallBack(T2_CallbackFunc12 cbFunc);
  void LogCallBackInject(const LogMessage* message);</code></pre>
<p>and the following GlueGen configuration</p>
<pre><code>  ReturnsStringOnly LogMessage.Category
  ReturnsStringOnly LogMessage.Message

  JavaCallbackDef SetLogCallBack -1 T2_CallbackFunc12 -1</code></pre>
<p>leading to the following interface</p>
<pre><code>
  /** JavaCallback interface: T2_CallbackFunc12 -&gt; void (*T2_CallbackFunc12)(const LogMessage *  usrParam) */
  public static interface T2_CallbackFunc12 {
    /** Interface to C language function: &lt;br&gt; &lt;code&gt;void callback(const LogMessage *  usrParam)&lt;/code&gt;&lt;br&gt;Alias for: &lt;code&gt;T2_CallbackFunc12&lt;/code&gt;     */
    public void callback(LogMessage usrParam);
  }

  ...

  /** Returns if callback is mapped for &lt;br&gt; &lt;code&gt;  void SetLogCallBack(T2_CallbackFunc12 cbFunc)&lt;/code&gt; */
  public boolean isSetLogCallBackMapped();

  /** Returns T2_CallbackFunc12 callback for &lt;br&gt; &lt;code&gt;  void SetLogCallBack(T2_CallbackFunc12 cbFunc)&lt;/code&gt; */
  public T2_CallbackFunc12 getSetLogCallBack();

  /** Releases callback data skipping toolkit API. Favor passing `null` callback ref to &lt;br&gt; &lt;code&gt;  void SetLogCallBack(T2_CallbackFunc12 cbFunc)&lt;/code&gt; */
  public void releaseSetLogCallBack();

  /** Entry point (through function pointer) to C language function: &lt;br&gt; &lt;code&gt;void SetLogCallBack(T2_CallbackFunc12 cbFunc)&lt;/code&gt;&lt;br&gt;   */
  public void SetLogCallBack(T2_CallbackFunc12 cbFunc);

  /** Entry point (through function pointer) to C language function: &lt;br&gt; &lt;code&gt;void LogCallBackInject(const LogMessage *  message)&lt;/code&gt;&lt;br&gt;   */
  public void LogCallBackInject(LogMessage message);</code></pre>
<p><em>TODO: Enhance documentation</em></p>
<h2 id="misc-configurations">Misc Configurations</h2>
<h3
id="libraryonload-librarybasename-for-jni_onload-"><code>LibraryOnLoad &lt;LibraryBasename&gt;</code>
for <code>JNI_OnLoad*(..)</code> …</h3>
<p><code>LibraryOnLoad &lt;LibraryBasename&gt;</code> <em>can</em> be
specified in one native code-unit within one native library maximum,
otherwise multiple function definitions would occur.</p>
<p>In case <a href="#java-callback">Java™ callback methods are used</a>,
it is required to have
<code>LibraryOnLoad &lt;LibraryBasename&gt;</code> specified in exactly
one native code-unit within one native library.</p>
<p><code>LibraryOnLoad &lt;LibraryBasename&gt;</code> generates native
JNI code to handle the <code>JavaVM*</code> instance</p>
<ul>
<li><code>JavaVM* JVMUtil_GetJavaVM()</code> returning the static
<code>JavaVM*</code> instance for <code>LibraryBasename</code> set by
<code>JNI_OnLoad*()</code></li>
<li><code>JNI_OnLoad(..)</code> setting the static <code>JavaVM*</code>
instance for <code>LibraryBasename</code>, used for dynamic
libraries,</li>
<li><code>JNI_OnLoad_&lt;LibraryBasename&gt;(..)</code> setting the
static <code>JavaVM*</code> instance for <code>LibraryBasename</code>,
used for static libraries,</li>
</ul>
<p>Further the following functions are produced to attach and detach the
current thread to and from the JVM, getting and releasing the
<code>JNIEnv*</code></p>
<ul>
<li><code>JNIEnv* JVMUtil_GetJNIEnv(int asDaemon, int* jvmAttached)</code>
returns the <code>JNIEnv*</code> with current thread being newly
attached to the <code>JavaVM*</code> <strong>if</strong> result
<code>*jvmAttached == true</code>, otherwise the current thread was
already attached to the <code>JavaVM*</code></li>
<li><code>void JVMUtil_ReleaseJNIEnv(JNIEnv* env, int detachJVM)</code>
releases the <code>JNIEnv*</code>, i.e. detaching the current thread
from the <code>JavaVM*</code> <strong>if</strong>
<code>detachJVM == true</code>, otherwise funtion does nothing.</li>
</ul>
<h2 id="platform-header-files">Platform Header Files</h2>
<p>GlueGen provides convenient platform headers, which can be included
in your C header files for native compilation and GlueGen code
generation.</p>
<p>Example:</p>
<pre><code>   #include &lt;gluegen_stdint.h&gt;
   #include &lt;gluegen_stddef.h&gt;

   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>