These three steps will get JReality running:
- Complete prerequisites: JDK, Eclipse, and SVN must be set up,
- Then you can check out JReality from SVN and
- Test the setup by running some introductory tutorials
They are described in greater detail below.
Prerequisites: JDK, Eclipse, and SVN:
1. Download and install the most recent JDK (Java Development Kit)
You need Java SE Development Kit 6 or higher.
If you don't know Java yet, follow the tutorial: java-unix-tutorial java-win32-tutorial
2. Install Eclipse IDE for Java Developers from eclipse download site
(or alternatively use Eclipse IDE for Java Developers or add Java to another package). When you first run Eclipse, check the box that says "Always use this workspace" and continue until you see the main window with the menubar.
Click the X next to "Welcome" now and if you ever see it again.
3. Install Subversive as recommended here: (or alternatively use Subclipse)
Click "Help"-> "Install New Software...".
Choose at "Work with:" "--All Available Sites--".
When the site is loaded check at "Collaboration" the Subversive boxes, like in the picture below and click -> "Next"
[Keep confirming until restart, then choose the highest numbered SVNKit connector]
JReality checkout
When subversive is installed, go to Menu: "Window"->"Open Perspective"->"Other..." and select "SVN Repository Exploring". Add the new repository location:
http://fs.math.tu-berlin.de:8000/svn/jreality
The login is guest with blank password and click "Finish"
Choose the "trunk" folder and choose "Checkout as..." like in the picture below: Eclipse will suggest you to checkout as a project "jreality", click Finish.
After the checkout, switch back to the Java Perspective: Menu: "Window"->"Open Perspective"->"Other..." and select "Java".
Note that there are other ways of switching between perspectives: Usually on the upper right of the Eclipse window there is a perspective switcher, try a right-click to configure it...
Additionally you can generate useful JavaDoc documentation, which you can read by hovering over identifiers: Menu: "Project" -> "Generate Javadoc..."
Change settings for Java 1.5
Now check if we we need to change the project to java 5 (this is for instance necessary on macosx 10.4). Expand the jreality project, and see if there is a red mark at the folder src-swing. If not, you have Java 6, nothing to change. If it is red, expand src-swing->de.jreality.swing.
First we add FakeFramePeer5.java and FakeToolKit5.java to the classpath: Select both files and right-click on the selection: choose Build Path->Include.
Now remove FakeFramePeer6.java and FakeToolKit6.java from the build path: Select both files (use Ctrl-Key) and right-click on the selection: choose Build Path->Exclude.
Maybe you also take a look at the README file in that folder.
Now we have set up jreality for java 1.5.
Testing (jogl)
Now we can start a tutorial example:
Open "jreality"->"src-tutorial"->"de.jreality.tutorial.intro" and double-click on Icosahedron.java. The file opens in the java editor.
(Later on, try intro01.java, intro02.java, and browse for other examples provided in the project)
Now go to the menu: Run->Run As...->Java Application or click the run icon:
You should see an app frame like this:
If you have two viewer entries at the top of the View menu, jogl is already running. You possibly have a linux64 system, which we have chosen as default. If the View menu looks as in the image above, you have to select the correct jni folder for your OS: Go to menu: "Project"->"Properties". Select Java Build Path on the left side. Open the source tab, and expand jreality/src-core and double-click on Native library location: jreality/jni/linux64:
In the following dialog, select Workspace, and choose the folder that matches your OS:
If you do not find the right folder go to the jogl homepage and look directly for your architecture. Extract the zip file (we are using the latest stable release 1.1.1) and put the native libs into a folder unter jreality/jni and select it then as Native Library Location. Note that you need to tell eclipse to refresh, after adding files to a project. (Menu: Project->Refresh).
Now run ViewerApp again, the View menu should now look like this:
Adding VR data to the project
ViewerVR is a viewer that has already a floor, a skybox, a navigation tool for walking and jumping etc, and it also offers some demo geometries to explore. See the ViewerVR User Manual.
It is used in the application IcosahedronVR.java, which is right below Icosahedron.java. When you run it (Run->Run As...->Java Application) it will look like this:
We have to add the two jars vrData.jar and vrExamples.jar to the classpath. Go to the download page and save the two jars under jreality/lib/.
In Eclipse, right-click on the jreality/lib folder and say Refresh... Then expand the folder, select the two jars and add them to the build path: Right-click on the selection: Build Path->Add to Build Path.
Now run ViewerVR again, you should see the following:
Create own projects for programming with jreality
We suggest that you do not add your own code into the jreality project. Then you can always update to the newest jreality version, without having conflicts.
Instead, we create a new project and reference the jreality project therein:
In the Java Perspective, choose Menu: File->New...->Java Project, choose a project name and click "Finish".
Open the project Properties (just as for the jreality project): Menu: Project->Properties
Select "Java Build Path" on the left, and choose the "Projects"-Tab.
Click on "Add..." and select jreality. Then confirm by clicking "OK" and close the dialog.
As a test, copy&paste a tutorial file, say de.jreality.tutorial.geom.Cube04.java into the new project and try to run it there. Note that you have to paste it into a source folder.
Tipps and Tricks
Add more memory when running an application
If a program is too slow or often interrupts for garbage collection, increase the heap size in the run configuration: Run->Run Configurations, as in the figure below.
Installing a Git plugin (TESTING, is not in official use)
First of all we need to install an Eclipse plugin which allows us to check out code from a Git repository:
- Git, developed by Linus Torvalds for the Linux Kernel. You will find a how to install an Eclipse-version of Git here
- If you have never used Git or SVN before, you'll find a good tutorial here or here for a short overview
- If you are already a common SVN-User, you'll find a perfect tutorial about the differences here
jReality Git-clone (TESTING, is not in official use)
When an Git plugin is installed, go to Menu: Window->Perspectives->Other... and select Git Repository Exploring. Press the button: "Clone a Git Repository and add the clone to this view"
http://git.gitorious.org/jr-test/jr-test.git
The login is guest with empty password.
Then select the master branch and press "Next" and then click Finish. Because Git copies the whole history, this can take a while...
... to continue ...
After the clone, switch back to the Java Perspective: Menu: Window->Open Perspective->Other... and select Java.