javax.microedition.m3g
Class World

java.lang.Object
  javax.microedition.m3g.Object3D
      javax.microedition.m3g.Transformable
          javax.microedition.m3g.Node
              javax.microedition.m3g.Group
                  javax.microedition.m3g.World

public class World

extends Group

A special Group node that is a top-level container for scene graphs. A scene graph is constructed from a hierarchy of nodes. In a complete scene graph, all nodes are ultimately connected to each other via a common root, which is a World node. An example of a complete scene graph is shown in the figure below.

Note that a scene graph need not be complete in order to be rendered; individual nodes and branches can be rendered using a separate method in Graphics3D. However, the semantics of rendering an incomplete scene graph are slightly different compared to rendering a World; see Graphics3D for more information.

Despite that it is called a graph, the scene graph is actually a tree structure. This implies that a node can belong to at most one group at a time, and cycles are prohibited. However, component objects, such as VertexArrays, may be referenced by an arbitrary number of nodes and components. The basic rules for building valid scene graphs are summarized below.

Even though World is a scene graph node, its special role as the singular root node has two noteworthy consequences. Firstly, a World can not be a child of any Node. Secondly, the node transformation is ignored for World objects when rendering. In all other respects (get, set, animate), the transformation behaves just like any other node transformation. Note also that there is no conceptual "Universe" coordinate system above the World, contrary to some other scene graph APIs.

The method render(World) in Graphics3D renders a World as observed by the currently active camera of that world. If the active camera is null, or the camera is not in the world, an exception is thrown. The world can still be rendered with the render(Node, Transform) method by treating the World as a Group. In that case, however, the application must explicitly clear the background and set up the camera and lights prior to rendering.

See Also:

Binary format

Field Summary

Fields inherited from class javax.microedition.m3g.Node

NONE, ORIGIN, X_AXIS, Y_AXIS, Z_AXIS

Constructor Summary

World()
Creates an empty World with default values.

Method Summary

Camera	getActiveCamera() Gets the currently active camera.
Background	getBackground() Retrieves the background settings of this World.
void	setActiveCamera(Camera camera) Sets the Camera to use when rendering this World.
void	setBackground(Background background) Sets the Background object for this World.

Methods inherited from class javax.microedition.m3g.Group

addChild, getChild, getChildCount, pick, pick, removeChild

Methods inherited from class javax.microedition.m3g.Node

align, getAlignmentReference, getAlignmentTarget, getAlphaFactor, getParent, getScope, getTransformTo, isPickingEnabled, isRenderingEnabled, setAlignment, setAlphaFactor, setPickingEnable, setRenderingEnable, setScope

Methods inherited from class javax.microedition.m3g.Transformable

getCompositeTransform, getOrientation, getScale, getTransform, getTranslation, postRotate, preRotate, scale, setOrientation, setScale, setTransform, setTranslation, translate

Methods inherited from class javax.microedition.m3g.Object3D

addAnimationTrack, animate, duplicate, find, getAnimationTrack, getAnimationTrackCount, getReferences, getUserID, getUserObject, removeAnimationTrack, setUserID, setUserObject

Constructor Detail

World

public World()

Creates an empty World with default values. The default values are:

• background : null (clear to black)
• active camera : null (the world is not renderable)

Method Detail

setBackground

public void setBackground(Background background)

Sets the Background object for this World. The background is used for clearing the frame buffer prior to rendering the World when Graphics3D.render(World) is called.

If the background object is null, the default values are used. That is, the color buffer is cleared to transparent black, and the depth buffer to the maximum depth (1.0).

Parameters:

background - attributes for clearing the frame buffer, or null to use defaults

See Also:

getBackground

getBackground

public Background getBackground()

Retrieves the background settings of this World.

Returns:

the current attributes for clearing the frame buffer

See Also:

setBackground

setActiveCamera

public void setActiveCamera(Camera camera)

Sets the Camera to use when rendering this World. At the time of rendering, the camera must also be a descendant of this World.

Parameters:

camera - the Camera object to set as the active camera

Throws:

java.lang.NullPointerException - if camera is null

See Also:

getActiveCamera

getActiveCamera

public Camera getActiveCamera()

Gets the currently active camera.

Returns:

the camera that is currently used to render this World

See Also:

setActiveCamera