GlueGen Struct [5]: Revised Struct Mapping + Documentation

GlueGen Revised Struct Mapping (esp pointer to array or single element), Struct String Charset, .. and Documentation

- Documentation:
    - Added README.md
      Let's have a proper face for the git repo

    - Added doc/GlueGen_Mapping.md (and its html conversion doc/GlueGen_Mapping.html)
      Created a new document covering application and implementation details suitable for users/devs.

    - Added doc/JogAmpMacOSVersions.md conversion to doc/JogAmpMacOSVersions.html

    - Updated www/index.html

- Use *CodeUnit instead of PrintWriter, representing a Java or C code unit covering a set of functions and structs.
    The CCodeUnit also handles common code shared by its unit across functions etc.

- Dropping 'static initializer', as its no more required
    due to simplified `JVMUtil_NewDirectByteBufferCopy()` variant.

- Revised Struct Mapping:
  - Pure Java implementation to map primitive and struct fields within a struct
    by utilizing ElementBuffer.

    Only 'Function Pointer' fields within a struct require native code.

    Exposes `static boolean usesNativeCode()` to query whether native code is used/required.

  - Transparent native memory address API

    Expose `long getDirectBufferAddress()` and `static TK_Struct derefPointer(long addr)`,
    allowing to
    - pass the native struct-pointer with native code
    - reconstruct the struct from a native struct-pointer
    - have a fully functional `TK_Struct.derefPointer(struct.getDirectBufferAddress())` cycle.

  - Add 'boolean is<Val>Null() to query whether a pointer (array) is NULL

  - *Changed* array get/set method for more flexibility alike `System.arraycopy(src, srcPos, dest, destPos, len)`,
    where 'src' is being dropped for the getter and 'dest' is being dropped for the setter
    as both objects are reflected by the struct instance.

  - *Changed* `get<Val>ArrayLength()` -> `get<Val>ElemCount()` for clarity

  - Considering all ConstElemCount values with config 'ReturnedArrayLength <int>'
    to be owned by native code -> NativeOwnership -> Not changing the underlying memory region!
    JavaOwnership is considered for all pointer-arrays not of NativeOwnership.
    Hence any setter on a NativeOwnership pointer-array will fail with non-matching elem-count.

  - Add 'release<Val>()' for JavaOwnership pointer-arrays,
    allowing to release the Java owned native memory incl. null-ing pointer and set<Val>ElemCount(0).

  - Support setter for 'const <type>*' w/ JavaOwnership, i.e. pointer to const value of a primitive or struct,
    setter and getter using pointer to array or single element in general.

  - Added Config `ImmutableAccess symbol` to disable all setter for whole struct or a field

  - Added Config `MaxOneElement symbol` to restrict a pointer to maximum one element and unset
    initial value (zero elements)

  - Added Config `ReturnsStringOnly symbol` to restrict mapping only to a Java String,
    dropping the ByteBuffer variant for 'char'

  - String mapping default is UTF-8 and can be read and set via [get|set]Charset(..) per class.

  - Dynamic string length retrieval in case no `ReturnedArrayLength` has been configured
    has changed from `strlen()` to `strnlen(aptr, max_len)` to be on the safe site.

    The maximum length default is 8192 bytes and can be read and set via [get|set]MaxStrnlen(..) per class.

    FIXME: strnlen(..) using EOS byte non-functional for non 8-bit codecs like UTF-8, US-ASCII.
           This is due to e.g. UTF-16 doesn't use an EOS byte, but interprets it as part of a code point.

  - TODO: Perhaps a few more unit tests

  - TODO: Allow plain 'int' to be mapped in structs IFF their size is same for all MachineDescriptions used.
          Currently this is the case -> 4 bytes like int32_t.

1 files changed, 79 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..e6a0a57
--- /dev/null
+++ b/README.md
@@ -0,0 +1,79 @@
+# GlueGen, Native Binding Generator for Java™
+
+[Original document location](https://jogamp.org/cgit/gluegen.git/about/)
+
+## Git Repository
+This project's canonical repositories is hosted on [JogAmp](https://jogamp.org/cgit/gluegen.git/).
+
+## Overview
+[GlueGen](https://jogamp.org/gluegen/www/) 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.
+
+It reads ANSI C header files
+and separate configuration files which provide control over many
+aspects of the glue code generation. GlueGen uses a complete ANSI C
+parser and an internal representation (IR) capable of representing all
+C types to represent the APIs for which it generates interfaces. It
+has the ability to perform significant transformations on the IR
+before glue code emission. 
+
+GlueGen can produce native foreign function bindings to Java™ as well as
+map native data structures to be fully accessible from Java™ including 
+potential calls to embedded function pointer.
+
+GlueGen is also capable to bind even low-level APIs such as the Java™ Native Interface (JNI) and
+the AWT Native Interface (JAWT) back up to the Java™ programming language.
+
+GlueGen utilizes [JCPP](https://jogamp.org/cgit/jcpp.git/about/), migrated C preprocessor written in Java™.
+
+GlueGen is used for the [JogAmp](https://jogamp.org) projects
+[JOAL](https://jogamp.org/cgit/joal.git/about/),
+[JOGL](https://jogamp.org/cgit/jogl.git/about/) and
+[JOCL](https://jogamp.org/cgit/jocl.git/).
+
+GlueGen is part of [the JogAmp project](https://jogamp.org).
+
+**The JogAmp project needs funding and we offer [commercial support](https://jogamp.org/wiki/index.php?title=Maintainer_and_Contacts#Commercial_Support)!**<br/>
+Please contact [Göthel Software (Jausoft)](https://jausoft.com/).
+
+### License
+See [LICENSE.txt](LICENSE.txt).
+
+## Documentation
+
+* [GlueGen Java™ API-Doc](https://jogamp.org/deployment/jogamp-next/javadoc/gluegen/javadoc/)
+* [GlueGen Native Data & Function Mapping for Java™](doc/GlueGen_Mapping.md)
+* [GlueGen Manual](doc/manual/)
+* [JogAmp's MacOS Version Support](doc/JogAmpMacOSVersions.md)
+* [How To Build](https://jogamp.org/gluegen/doc/HowToBuild.html)
+
+## Build Requirements
+Check [GlueGen's HowToBuild](https://jogamp.org/gluegen/doc/HowToBuild.html).
+
+## Directory Organization:
+```
+make/           Build-related files and the main build.xml
+doc/            Documentation
+jcpp/           JCPP (git sub-module), migrated C preprocessor written in Java
+src/            The actual source for the JOAL APIs.
+src/junit/      Unit tests
+test/           Standalone manual tests
+build/          (generated directory) Where the Jar and DLL files get built to
+www/            JOAL project webpage files
+```
+
+## Contact Us
+- JogAmp             [http://jogamp.org/](https://jogamp.org/)
+- JOAL Web           [http://jogamp.org/](https://jogamp.org/joal/)
+- Forum/Mailinglist  [http://forum.jogamp.org/](https://forum.jogamp.org/)
+- Repository         [http://jogamp.org/git/](https://jogamp.org/git/)
+- Wiki               [https://jogamp.org/wiki/](https://jogamp.org/wiki/)
+- Maintainer         [https://jogamp.org/wiki/index.php/Maintainer_and_Contacts](https://jogamp.org/wiki/index.php/Maintainer_and_Contacts)
+- Sven's Blog        [https://jausoft.com/blog/tag/jogamp/](https://jausoft.com/blog/tag/jogamp/)
+- Email              sgothel _at_ jausoft _dot_ com
+
+## History
+Since roughly 2010, GlueGen development has been continued
+by individuals of the JogAmp community, see git log for details.
+