Overview

Basic Java Bindings for Horde3D
-------------------------------
Well, it's what it says on the package. These bindings merely provide a direct
mapping of the plain C interface. For a basic overview of these bindings, read
on or refer to the autogenerated documentation (in the 'javadoc' directory
after the build), for proper semantic documentation, read the Horde3D
documentation.

How to Build
------------
1. Requirements:
   - get JNA (from http://jna.dev.java.net); you'll need at least version 3.2.0
   - install Scons (http://scons.org)
2. To build:
   - either drop jna.jar into the source directory and do 'scons'
   - put jna.jar somewhere else and run 'scons JNACLASSPATH=<path to jna.jar>'
3. To check if it works:
  'java -Djna.library.path=<directory with compiled Horde3D libraries> \
   -classpath .:<path to jna.jar> Horde3DCheck'
  (run in the source directory; replace ':' with ';' if you're on Windows)

How to Use in a Project
-----------------------
To use it, you have to:
 - add horde3d.jar to your class path
 - add jna.jar to your class path
 - either:
   * set the property jna.library.path to the directory where your compiled
     Horde3D libraries reside
   * put those libraries in a directory that your system searches when looking
     for dynamic libraries
If you plan to use Horde3DUtils, load Horde3D before you load Horde3DUtils:
Because Horde3DUtils links against Horde3D, it will try to find it when it gets
loaded. That will not work, however, if Horde3D is not on your library search
path (presumably because you only set jna.library.path). If Horde3D was already
loaded, Horde3DUtils will *not* try to find it by itself, as it's already
there. Obvious, isn't it?

(Not really.)


Short Usage Guide
-----------------
All enums are wrapped as Java interfaces with static final integer fields; the
H3DNode and H3DRes typedefs got their own classes, i.e. you'll get strong
typechecking for those. Other constants and all functions are static fields in
the main class for a given part of the Horde3D API:
 - org.horde3d.Horde3D for the main library
 - org.horde3d.Horde3DUtils for the utility library
 - org.horde3d.terrain.TerrainExtension for the terrain extension
 - org.horde3d.sound.SoundExtension for the sound extension
To use the interface exported by one of those classes, you have to call the
class's initialise() function first; this will actually load the corresponding
library, so when a given interface is not available (e.g. an extension wasn't
built in), you'll get an UnsatisfiedLinkError when you call initialise(). See
also test/Horde3DCheck.java.

Known Issues
------------
 - There are some functions with quite complex signatures that I wasn't sure
   how to wrap correctly. These are exclusively in Horde3D.java and all marked
   with a TODO comment.
 - I have not tested this beyond some basic experimentation, but as far as I
   can tell, most functions should work as intended. However, keep your guard
   up (or write proper unit tests).
 - It probably makes more sense to just use some code generator.



---
Copyright © 2010 Felix Krull

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.