jMonkeyEngine in ICE

ICE uses jMonkeyEngine (jME) for displaying 3D graphics. This article describes the framework used for creating custom jME-based 3D views in ICE.

The content below assumes no prior knowledge of jME but familiarity with ICE and Eclipse development.

Table of Contents

• Background
  • What is jMonkeyEngine?
  • Why does ICE use jME?
• jME in ICE: Under the hood
  • The basics
    • The scene graph
    • A simple example
    • SimpleApplication
    • AppState
  • jME in ICE
    • A UML-based overview
    • SimpleApplication caveat
    • ViewAppState
    • SimpleAppState
• Creating your very own jME view

Background

Before showing you how jME works in ICE or how to create your own jME-based views in ICE, we should explain a little about jME and why we use it.

What is jMonkeyEngine?

Perhaps the best, simplest explanation of jME can be found on their website (http://jmonkeyengine.org/):

jMonkeyEngine is a 3D game engine for adventurous Java developers. It’s open source, cross platform and cutting edge. And it is all beautifully documented.

Simply put, jME is a Java-friendly 3D gaming engine for rendering 3D views in a Java application.

Why does ICE use jME?

ICE uses jME to render 3D views ranging from simple, 2D, polygon-based meshes to 3D reactor plants with pipes, heat exchangers, junctions, and reactors. Part of what makes jME great is that, being designed for game developers, it can handle a wide variety of applications out of the box. One component of this is its scene graph, which makes it reasonably straightforward to contribute custom 3D graphics to a jME-based view.

Examples of jME in ICE include the Geometry Editor, Mesh Editor, and Reactor Analyzer. Each of these provides a different view composed of different components that are rendered as 3D objects on the screen.

For the original jME documentation, see http://hub.jmonkeyengine.org/wiki/doku.php/. Of particular interest are their beginner, intermediate, and advanced tutorials.

jME in ICE: Under the hood

This section describes a little bit about how jME works and how it is used in ICE, and it may be useful for understanding how to create your own jME views in or out of ICE.

The basics

The scene graph

The jME community has a good tutorial on the scene graph here.

The following are important ideas to understand about the scene graph:

• The scene graph is a tree of spatials.
• Spatials can be transformed (translated, rotated, scaled).
• There are two types of spatials:
  • A node can contain other spatials. Essentially, this is a group of objects.
  • A geometry represents an object in the scene and has an associated mesh and material.
• Transformations on a node are applied to all its child spatials as if they were a single unit.
• The root node is the lone ancestor or parent of all spatials in the scene.

If it helps, you can think of sub-trees of nodes in the scene graph as separate scenes.

A simple example

The image below comes from the source of ICE's Mesh Editor.

The different components of the scene are described below:

• Green - This is the jME view. Specifically, this is an AwtPanel with a ViewPort and Camera that shows a jME scene graph.
• Cyan - These are nodes in the scene. Each node is composed of 8 geometries (4 lines and 4 spheres) to represent a quad.
• Orange - These are custom x, y, and z axes attached to the scene. These are 3 geometries (all lines) attached to a single node.
• Magenta - This is the Graphical User Interface (GUI) or Heads-Up Display (HUD). These are also geometries attached to a single root node separate from the root of the scene graph.
• Other - The blue grid in the background is a geometry in the scene graph. The buttons at the top are Eclipse SWT widgets external to the jME view.

SimpleApplication

SimpleApplication is a basic class for creating and running a jME view. You can think of it as a generic Java application that allocates the resources it needs to render a 3D scene.

When working with a SimpleApplication, you usually only need to think about two methods:

public void simpleInitApp()
This is the method that you use to initialize your scene graph. For instance, if your view requires a flat grid, you would initialize the grid in this method. You might also set up your controls and camera in this method.

public void simpleUpdate(float tpf)
This method is called periodically (although quickly by human standards). Any updates to your scene should be implemented here. For example, if you need to create a sphere when the mouse clicks, you would add the sphere to the scene graph here.

To use these methods properly, SimpleApplication also provides you with a reference to the root node of your scene graph and a separate node for displaying a Graphical User Interface (GUI) or Heads-up Display (HUD).

A good tutorial for the SimpleApplication can be found here.

AppState

In jME, an AppState is used to control application logic or mechanics. In other words, it manages the state of the application. If it helps, you can think of an AppState as being a mode of operation for a jME Application.

AppState provides the following methods for handling the mechanics for the application (not all methods are listed):

public void initialize(AppStateManager stateManager, Application app)
This is called when the AppState is initialized, or "attached" to an Application.
This is analogous to SimpleApplication.simpleInitApp().

public void setEnabled(boolean active)
This is called when the AppState is "paused" or "unpaused". Normally you would activate or deactivate controls and listeners here.

public void update(float tpf)
This is called when the AppState is running.
This is analogous to SimpleApplication.simpleUpdate(float tpf).

public void cleanup()
This is called when the AppState is stopped, or "detached" from an Application.

You may have noticed the "Mode" button in the example jME view above. For that view, the "Mode" button changes the current AppState between a mode for adding new polygons and a mode for editing existing polygons.

The jME introduction to AppStates can be found here.

jME in ICE

A UML-based overview

SimpleApplication caveat

ViewAppState

SimpleAppState

Creating your very own jME view

This section provides you with an example for creating a custom jME view using the classes available in ICE.