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.