**** JREALITY OVERVIEW **** jReality is a pure java library and comes with all necessary 3rd party jars included. All current jReality contributors use Eclipse as IDE. This folder contains all eclipse project information. For compiling the whole project from command line, we use ant. jReality is developed with Sun Java 6, but we maintain compatibility with Java 5, since for many Mac OS X machines Java 6 is not available. Other JDKs may also work, but we do no testing with other JDKs. In addition to the following instructions, you may want to look at the jReality wiki and forum: * http://www3.math.tu-berlin.de/jreality/mediawiki * http://www3.math.tu-berlin.de/jreality/phpbb **** SUPPORTED PLATFORMS **** As a java library jReality should run on all major platforms with sufficient Java support. The following is a list of platforms+JDKs on which we have successfully built and run jReality: OS JDK ------------------------------------------------------ Ubuntu 8.04, amd64 java-6-sun-1.6.0.7 Ubuntu 8.04, amd64 java-1.5.0-sun-1.5.0.16 Ubuntu Studio 8.04.2, i386 java-1.5.0-sun-1.5.0.16 Ubuntu Studio 8.04.2, i386 java-6-sun-1.6.0.07 Mac OS X 10.5.7, i386 java-1.5.0_16 Ubuntu 9.04, i386 java-6-sun-1.6.0.13 Ubuntu 9.04, i386 java-1.5.0-sun-1.5.0.18 Windows XP sp3 java-1.6.0_13-b03 Windows Vista Business java-1-6-0_13-b03 **** JREALITY BUILD INSTRUCTIONS **** jReality is built using an ant file. For a special feature (immersing Java frames into the 3D scene), we have source incompatibility between Java 1.5 and Java 6. This makes it necessary to modify the excludes.txt file when using a 1.5 JDK. Given the choice, we recommend Java 6. * Requirements * For a complete build from sources you need: - a Sun Java 1.5 or 6 JDK (or SDK) (java.sun.com) - ant, including optional tasks (ant.apache.org) * Build instructions * Only when using Java 1.5: Edit the excludes.txt file, and toggle the comment in lines 13/14: **/Fake*6.java # **/Fake*5.java - Set the JAVA_HOME environment variable to the Sun Java 6 JDK folder, for instance on an ubuntu installation or in a windows command prompt: $> export JAVA_HOME=/usr/lib/jvm/java-6-sun c:\jreality>set JAVA_HOME=C:\Program Files\Java\jdk1.6.0_12 - Run the ant build: $> ant c:\jreality>ant Some hints for Mac OS X: - The following JAVA_HOME setting should work: export JAVA_HOME=/System/Library/Frameworks/JavaVM.framework/Home - You may have to find and download the file ant-antlr.jar and copy it to /usr/share/ant/lib. **** RUNNING JREALITY APPS **** Set up the class path. Most of the jars in the lib folder are required, as well as most of the jars created by the build file, in the dist folder. The commands to set the required classpath in a linux BASH or the Windows command propt are, for instance: jReality jars: $> export CLASSPATH=dist/jReality-audio.jar:dist/jReality-backends-share.jar:dist/jReality-core.jar:dist/jReality-io.jar:dist/jReality-jogl.jar:dist/jReality-plugin.jar:dist/jReality-renderman.jar:dist/jReality-soft.jar:dist/jReality-sunflow.jar:dist/jReality-swing.jar:dist/jReality-tools.jar:dist/jReality-ui.jar:dist/jReality-vr.jar:dist/jReality-tutorial.jar C:\jreality>set CLASSPATH=dist/jReality-audio.jar;dist/jReality-backends-share.jar;dist/jReality-core.jar;dist/jReality-io.jar;dist/jReality-jogl.jar;dist/jReality-plugin.jar;dist/jReality-renderman.jar;dist/jReality-soft.jar;dist/jReality-sunflow.jar;dist/jReality-swing.jar;dist/jReality-tools.jar;dist/jReality-ui.jar;dist/jReality-vr.jar;dist/jReality-tutorial.jar Required 3rd-party libraries: $> export CLASSPATH=$CLASSPATH:lib/antlr.jar:lib/bsh.jar:lib/colorpicker.jar:lib/gluegen-rt.jar:lib/iText-2.1.3.jar:lib/janino.jar:lib/jogl.jar:lib/jrworkspace.jar:lib/beans.jar:lib/jterm.jar:lib/sunflow.jar:lib/xpp3.jar:lib/xstream.jar C:\jreality>set CLASSPATH=%CLASSPATH%;lib/antlr.jar;lib/bsh.jar;lib/colorpicker.jar;lib/gluegen-rt.jar;lib/iText-2.1.3.jar;lib/janino.jar;lib/jogl.jar;lib/jrworkspace.jar;lib/beans.jar;lib/jterm.jar;lib/sunflow.jar;lib/xpp3.jar;lib/xstream.jar Data (textures, skyboxes, sample geometry files): $> export CLASSPATH=$CLASSPATH:lib/vrData.jar:liv/vrExamples.jar C:\jreality>set CLASSPATH=%CLASSPATH%;lib/vrData.jar;lib/vrExamples.jar Now you can run one of the examples included in jReality, for instance: $> java de.jreality.plugin.JRViewer -vr This will start up a viewer where one can walk and look around using WASD-keys and the right-mouse for mouse look. Rendering will be fairly slow, since we have only software rendering up to now. Enable OpenGL rendering: To make use of OpenGL rendering, a native library is required. This library depends on the OS and is in a sub-folder of jni. Look into that folder and see if there is a sub folder matching your platform. For instance, for a 64-bit linux system or a 32 bit windows, set the following environment variable (BASH and Windows command prompt again): $> export LD_LIBRARY_PATH=jni/linux64 c:\jreality>set PATH=%PATH%;jni/win32 Now the examples will start up using the much faster OpenGL rendering backend. NOTE: The OpenGL rendering requires JOGL (Java Bindings for OpenGL). JOGL is available for many more platforms that are contained in the jni folder. In case you are working on a platform for which you find no subfolder under jni go to the jogl website (https://jogl.dev.java.net/) directly and download it for your platform. The JOGL version we are using is JSR-231 1.1.1 - May 22 2008. We will keep up to date with the latest release version of jogl. VISTA BUG: For Windows Vista users we suggest to use the runtime option -Dsun.java2d.d3d=false to avoid graphics errors in the menu bar. Java VM Flags: The apps run much better if one allows the JVM to use more memory. Add for instance -Xms512M -Xmx1024M when launching the examples. **** JReality Examples **** To get an idea of jreality, please check out the following examples. Usually, the VR Viewer is used, please see the ViewerVR User tutorial: http://www3.math.tu-berlin.de/jreality/mediawiki/index.php/ViewerVR_User_Manual * ViewerVR, showing different example geometries. Use the GUI on the left to select different examples and change appearance in the Content Appearance panel. Object size can also be adapted. Start with: $> java de.jreality.plugin.JRViewer -vr * Audio examples: $> java de.jreality.tutorial.audio.AudioExample $> java de.jreality.tutorial.audio.DopplerDemo Let Leslie speaker rotate by typing PgUp or PgDn: $> java de.jreality.tutorial.audio.LeslieDemo * Misc: type 1 to toggle camera paths $> java de.jreality.tutorial.scene.CameraPathExample * Plain File Viewer: To get a plain viewer for loading 3D files, try: $> java de.jreality.plugin.JRViewer **** 3rd party libraries **** jReality uses several 3rd party libraries. Please look into the folder 3rd-party, the README file contains information about these libraries and their licenses. **** Using Eclipse **** The project file contains Eclipse project information. You can open it using New...->Java Project->"Create from existing source" with the jreality folder folder selected. The native library location needs to be set for the source folder jreality/src-core under "Java Build Path"->"Source".