GlueGen Code Generator

## JogAmp GlueGen Code Generator

#### GlueGen Data Type Mapping

Gluegen has build-in types (terminal symbols) for:

type | java bits | native bits | type | signed | origin
--- | --- | --- | --- | --- | ---
|  | x32 | x64 |  |  |
void | 0 | 0 | 0 | void | void | ANSI-C
char | 8 | 8 | 8 | integer | any | ANSI-C
short | 16 | 16 | 16 | integer | any | ANSI-C
int | 32 | 32 | 32 | integer | any | ANSI-C
long | 64 | 32 | 321 | integer | any | ANSI-C - Windows
long | 64 | 32 | 64 | integer | any | ANSI-C - Unix
float | 32 | 32 | 32 | float | signed | ANSI-C
double | 64 | 64 | 64 | double | signed | ANSI-C
__int32 | 32 | 32 | 32 | integer | any | windows
__int64 | 64 | 64 | 64 | integer | any | windows
int8_t | 8 | 8 | 8 | integer | signed | stdint.h
uint8_t | 8 | 8 | 8 | integer | unsigned | stdint.h
int16_t | 16 | 16 | 16 | integer | signed | stdint.h
uint16_t | 16 | 16 | 16 | integer | unsigned | stdint.h
int32_t | 32 | 32 | 32 | integer | signed | stdint.h
uint32_t | 32 | 32 | 32 | integer | unsigned | stdint.h
int64_t | 64 | 64 | 64 | integer | signed | stdint.h
uint64_t | 64 | 64 | 64 | integer | unsigned | stdint.h
intptr_t | 64 | 32 | 64 | integer | signed | stdint.h
uintptr_t | 64 | 32 | 64 | integer | unsigned | stdint.h
ptrdiff_t | 64 | 32 | 64 | integer | signed | stddef.h
size_t | 64 | 32 | 64 | integer | unsigned | stddef.h
wchar_t | 32 | 32 | 32 | integer | signed | stddef.h

Warning: Try to avoid unspecified bit sized types, especially long, since it differs on Unix and Windows!
Notes:

1. Type long will result in broken code on Windows, since we don't differentiate the OS and it's bit size is ambiguous.
2. Anonymous void-pointer void* are mapped to NIO Buffer.
3. Pointers to pointer-size types like intptr_t*, uintptr_t*, ptrdiff_t* and size_t* are mapped to PointerBuffer, to reflect the architecture depending storage size.

#### GlueGen Internal Alignment for Compound Data

In general, depending on CPU and it's configuration (OS), alignment is set up for each type (char, short, int, long, ..).

Compounds (structures) are aligned naturally, i.e. their inner components are aligned
and are itself aligned to it's largest element.

See:

- Wikipedia Data Structure Alignment
- Wikipedia Data Structure Alignment - Padding
- Viva64 Data Alignment
- Apple: Darwin 64bit Porting - Data Type Size & Alignment

##### Simple alignment arithmetic

Modulo operation, where the 2nd handles the case offset == alignment:

> padding = ( alignment - ( offset % alignment ) ) % alignment ;
> aligned_offset = offset + padding ;

Optimization utilizing alignment as a multiple of 2 `-> x % 2n == x & ( 2n - 1 )`

> remainder = offset & ( alignment - 1 ) ;
> padding = ( remainder > 0 ) ? alignment - remainder : 0 ;
> aligned_offset = offset + padding ;

Without branching, using the 2nd modulo operation for the case offset == alignment:

> padding = ( alignment - ( offset & ( alignment - 1 ) ) ) & ( alignment - 1 ) ;
> aligned_offset = offset + padding ;

See `com.jogamp.gluegen.cgram.types.SizeThunk.align(..)`.

##### Type Size & Alignment for x86, x86_64, armv6l-32bit-eabi and Window(mingw/mingw64)

Runtime query is implemented as follows:

       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) ;

type | 32 bits | 64 bits
--- | --- | ---
| size | alignment | size | alignment
char | 1 | 1 | 1 | 1
short | 2 | 2 | 2 | 2
int | 4 | 4 | 4 | 4
float | 4 | 4 | 4 | 4
long | 4 | 4 | 8†,4∗ | 8†,4∗
pointer | 4 | 4 | 8 | 8
long long | 8 | 4†,8∗+ | 8 | 8
double | 8 | 4†,8∗+ | 8 | 8
long double | 12†∗,8+,16- | 4†∗,8+,16- | 16 | 16

† Linux, Darwin
+armv7l-eabi
- MacOsX-32bit-gcc4
∗ Windows

#### GlueGen Platform Header Files

GlueGen provides convenient platform headers,
which can be included in your C header files for native compilation and GlueGen code generation.
Example:

       #include <gluegen_stdint.h>
       #include <gluegen_stddef.h>

       uint64_t test64;
       size_t size1;
       ptrdiff_t ptr1;

To compile this file you have to include the following folder to your compilers system includes, ie `-I`:

        gluegen/make/stub_includes/platform

To generate code for this file you have to include the following folder to your GlueGen `includeRefid` element:

        gluegen/make/stub_includes/gluegen

#### GlueGen Pre-Defined Macros

To identity a GlueGen code generation run, GlueGen defines the following macros:

         #define __GLUEGEN__ 2