M3G 1.1 -- Jun 22, 2005

javax.microedition.m3g
Class World

java.lang.Object
  extended byjavax.microedition.m3g.Object3D
      extended byjavax.microedition.m3g.Transformable
          extended byjavax.microedition.m3g.Node
              extended byjavax.microedition.m3g.Group
                  extended byjavax.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:

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

M3G 1.1 -- Jun 22, 2005

Copyright © 2005 Nokia Corporation. See the Copyright Notice for details.