Developing jReality Applications with Plugins

(Problems with this tutorial? Let me know: kutschan [at] math.tu-berlin.de)

Exercise 1 - Create the simplest JRViewer application and customize it

Write an Applicatin using the JRViewer.

Play around with all of its abilities.

See what the different add... methods do. Especially the addVRSupport() method. In Eclipse right click on the method name and choose "Open Declaration" (or type F3 instead) to see, what's behing these add methods. You don't have to understand Plugins by now. Just note how your application works by the interaction of certain plugins, which you can add to or remove from your application. (If you like, read about plugins in the "Graphical user interface" section of the jReality Developer Tutorials)

Use File/LoadContent from the menu bar to load some geometry. .obj files for that can be found on the internet. (Hint: you have to call the right add... method to install this functionality)

 
public static void main(String[] args) {
		JRViewer j = new JRViewer();
		//this is a useful method. The Slots can be toggled in the running application using Alt-Shift-Arrow
		j.setShowPanelSlots(true, true, true, true);
		j.addBasicUI();
		j.add...
		j.startup();
}

Exercise 2 - Register Plugins manually

You can add Plugins manually if you have access to the so called Controller, which you get by calling getController(). Play around with all the different Plugins you can find in the src-plugin folder in the jReality project

 
public static void main(String[] args) {
		JRViewer j = new JRViewer();
		j.getController().registerPlugin(new Avatar());
		j.getController().registerPlugin(new Terrain());
		j.startup();
}

Exercise 3 - Write your own Plugin that does nothing

To add genuinely new functionality to jReality you would have to write a new Plugin.

All Plugins can communicate with one another through the Controller. The Controller has references to each Plugin. And each Plugin knows the controller. So if Plugin A wants to talk to Plugin B it can call something like B = c.getPlugin(B.class)

A Plugin looks as follows

 
public class MyNewPlugin extends Plugin{
	
	public MyNewPlugin(){
		
	}
 
	//@Override
	public void install(Controller c) throws Exception{
		super.install(c);
		
	}
}

When the startup() method of JRViewer is called, then the Controller "installs" all the registered Plugins by calling the install(Controller c) method of each Plugin.

Exercise 4 - Make a Plugin that displays something

By now you should have read the "Graphical user interface" section in the Developer Tutorial.

Now You probably want your Plugin to do something, like display some geometry. But where to put the geometry? There is a bunch of Plugins that are essential part of the JRViewer: Scene, View, ViewPreferences, ToolSystemPlugin and Lights. You will have to learn how to interact with these 5 Plugins. What is each of them for?

- Scene contains the jReality scene graph. The scene graph is the tree structure containing all the geometry, lights, transformations needed to describe the three-dimensional scene. You should read this page http://www3.math.tu-berlin.de/jreality/index.php?article_id=68

- View contains the different rendering backends, that is the algorithms that transform the scenegraph into the 2D image you're seeing on the screen.

- The ToolSystemPlugin makes it possible to handle input (mouse, keyboard, joystick, ...) in an abstract way. It converts clicks to positions in 3D, and dragging to transformation matrices. This will be really useful later.

- Lights does what it stands for I guess.

So now you can modify the install method of your plugin such that displays a Cube. Try! Here's the solution:

 
public void install(Controller c) throws Exception{
		super.install(c);
		//retrieve a reference to the Scene plugin
		Scene s = c.getPlugin(Scene.class);
		//get the SceneGraphComponent reserved for our geometry of interest
		//note that we actually get the whole path to the content component, because sometimes it's important to know all the transformations (or appearances) along the path. And one single SceneGraphComponent
		//can be attached at different places in the SceneGraph, e.g. if you want 2 identical cubes with different positions
		SceneGraphComponent sgc = (SceneGraphComponent) s.getContentPath().getLastElement();
		//the Primitives class contains pre-defined geometries, but we will make our own later
		sgc.setGeometry(Primitives.coloredCube());
}

You should read about GeometryFactories on the jReality developer wiki: http://www3.math.tu-berlin.de/jreality/mediawiki/index.php/Developer_Tutorial

Exercise 5 - Interacting with your scene, writing your own Tool

Tools are part of the SceneGraph, they can be added and removed like Geometries. So in the same way as you have added the Geometry in the last exercise you can add a Tool:

 
sgc.addTool(new MyNewTool());

Task: Write a Tool called "MyNewTool" that writes to the console, when you click on the cube. For this, read about Tools in the jReality Developer Tutorials.

Solution:

 
public class MyNewTool extends AbstractTool {
	public MyNewTool() {
		super(InputSlot.LEFT_BUTTON);
		addCurrentSlot(InputSlot.POINTER_TRANSFORMATION);
		
	}
	
	public void activate(ToolContext tc) {
		if(tc.getCurrentPick() != null){
			System.out.println("picked cube");
		}
	}
}

Exercise 6 - Adding swing GUI elements to your application, the SceneShrinkPanel plugin

You can create a plugin that has access to the left slot by inheriting from SceneShrinkPanel. A template for doing this is shown below.

 
public class MyGUIPlugin extends SceneShrinkPanel{
	
	public MyGUIPlugin(){
		
	}
	public void install(Controller c) throws Exception{
		
		super.install(c);
		editorInspector = new JPanel();
		//...
		
		shrinkPanel.setLayout(new GridLayout());
		shrinkPanel.add(editorInspector);
	}
	public PluginInfo getPluginInfo() {
		return new PluginInfo("Domain");
	}
	JPanel editorInspector = null;
}