: Class Background

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## javax.media.j3d
Class Background

    java.lang.Object
      |
      +--javax.media.j3d.SceneGraphObject
            |
            +--javax.media.j3d.Node
                  |
                  +--javax.media.j3d.Leaf
                        |
                        +--javax.media.j3d.Background

public class Background
extends Leaf

The Background leaf node defines either a solid background color or a background image that is used to fill the window at the beginning of each new frame. It optionally allows background geometry---which is pre-tessellated onto a unit sphere and is drawn at infinity---to be referenced. It also specifies an application region in which this background is active.

Field Summary
`static int` | `ALLOW_APPLICATION_BOUNDS_READ` Specifies that the Background allows read access to its application bounds and bounds leaf at runtime.
`static int` | `ALLOW_APPLICATION_BOUNDS_WRITE` Specifies that the Background allows write access to its application bounds and bounds leaf at runtime.
`static int` | `ALLOW_COLOR_READ` Specifies that the Background allows read access to its color at runtime.
`static int` | `ALLOW_COLOR_WRITE` Specifies that the Background allows write access to its color at runtime.
`static int` | `ALLOW_GEOMETRY_READ` Specifies that the Background allows read access to its background geometry at runtime.
`static int` | `ALLOW_GEOMETRY_WRITE` Specifies that the Background allows write access to its background geometry at runtime.
`static int` | `ALLOW_IMAGE_READ` Specifies that the Background allows read access to its image at runtime.
`static int` | `ALLOW_IMAGE_WRITE` Specifies that the Background allows write access to its image at runtime.

Fields inherited from class javax.media.j3d.Node
`ALLOW_AUTO_COMPUTE_BOUNDS_READ, ALLOW_AUTO_COMPUTE_BOUNDS_WRITE, ALLOW_BOUNDS_READ, ALLOW_BOUNDS_WRITE, ALLOW_COLLIDABLE_READ, ALLOW_COLLIDABLE_WRITE, ALLOW_LOCAL_TO_VWORLD_READ, ALLOW_PICK, ALLOW_PICKABLE_READ, ALLOW_PICKABLE_WRITE, ENABLE_COLLISION_REPORTING, ENABLE_PICK_REPORTING`

Constructor Summary
`Background()` Constructs a Background node with default parameters.
`Background(BranchGroup branch)` Constructs a Background node with the specified geometry.
`Background(Color3f color)` Constructs a Background node with the specified color.
`Background(float r, float g, float b)` Constructs a Background node with the specified color.
`Background(ImageComponent2D image)` Constructs a Background node with the specified image.

Method Summary
`Node` | `cloneNode(boolean forceDuplicate)` Creates a new instance of the node.
`void` | `duplicateNode(Node originalNode, boolean forceDuplicate)` Copies all node information from `originalNode` into the current node.
`BoundingLeaf` | `getApplicationBoundingLeaf()` Retrieves the Background node's application bounding leaf.
`Bounds` | `getApplicationBounds()` Retrieves the Background node's application bounds.
`void` | `getColor(Color3f color)` Retrieves the background color.
`BranchGroup` | `getGeometry()` Retrieves the background geometry.
`ImageComponent2D` | `getImage()` Retrieves the background image.
`void` | `setApplicationBoundingLeaf(BoundingLeaf region)` Set the Background's application region to the specified bounding leaf.
`void` | `setApplicationBounds(Bounds region)` Set the Background's application region to the specified bounds.
`void` | `setColor(Color3f color)` Sets the background color to the specified color.
`void` | `setColor(float r, float g, float b)` Sets the background color to the specified color.
`void` | `setGeometry(BranchGroup branch)` Sets the background geometry to the specified BranchGroup node.
`void` | `setImage(ImageComponent2D image)` Sets the background image to the specified image.
`void` | `updateNodeReferences(NodeReferenceTable referenceTable)` Callback used to allow a node to check if any scene graph objects referenced by that node have been duplicated via a call to `cloneTree`.

Methods inherited from class javax.media.j3d.Node
`cloneTree, cloneTree, cloneTree, getBounds, getBoundsAutoCompute, getCollidable, getLocalToVworld, getLocalToVworld, getParent, getPickable, setBounds, setBoundsAutoCompute, setCollidable, setPickable`

Methods inherited from class javax.media.j3d.SceneGraphObject
`clearCapability, duplicateSceneGraphObject, getCapability, getUserData, isCompiled, isLive, setCapability, setUserData`

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Field Detail

### ALLOW_APPLICATION_BOUNDS_READ

    public static final int ALLOW_APPLICATION_BOUNDS_READ

  Specifies that the Background allows read access to its application bounds and bounds leaf at runtime.

### ALLOW_APPLICATION_BOUNDS_WRITE

    public static final int ALLOW_APPLICATION_BOUNDS_WRITE

  Specifies that the Background allows write access to its application bounds and bounds leaf at runtime.

### ALLOW_IMAGE_READ

    public static final int ALLOW_IMAGE_READ

  Specifies that the Background allows read access to its image at runtime.

### ALLOW_IMAGE_WRITE

    public static final int ALLOW_IMAGE_WRITE

  Specifies that the Background allows write access to its image at runtime.

### ALLOW_COLOR_READ

    public static final int ALLOW_COLOR_READ

  Specifies that the Background allows read access to its color at runtime.

### ALLOW_COLOR_WRITE

    public static final int ALLOW_COLOR_WRITE

  Specifies that the Background allows write access to its color at runtime.

### ALLOW_GEOMETRY_READ

    public static final int ALLOW_GEOMETRY_READ

  Specifies that the Background allows read access to its background geometry at runtime.

### ALLOW_GEOMETRY_WRITE

    public static final int ALLOW_GEOMETRY_WRITE

  Specifies that the Background allows write access to its background geometry at runtime.

Constructor Detail

### Background

    public Background()

  Constructs a Background node with default parameters. The default values are as follows:
  color : black (0,0,0)
  image : null
  geometry : null
  application bounds : null
  application bounding leaf : null

### Background

    public Background(Color3f color)

  Constructs a Background node with the specified color.

### Background

    public Background(float r,
                      float g,
                      float b)

  Constructs a Background node with the specified color.

### Background

    public Background(ImageComponent2D image)

  Constructs a Background node with the specified image. If this image is non-null then the color is ignored.
  Parameters:
    `image` - pixel array object used as the background image

### Background

    public Background(BranchGroup branch)

  Constructs a Background node with the specified geometry. If non-null, this background geometry is drawn on top of the background color or image using a projection matrix that essentially puts the geometry at infinity. The geometry should be pre-tessellated onto a unit sphere.
  Parameters:
    `branch` - the root of the background geometry
  Throws:
    IllegalSharingException - if the BranchGroup node is a child of any Group node, or is already attached to a Locale, or is already referenced by another Background node.

Method Detail

### setColor

    public final void setColor(Color3f color)

  Sets the background color to the specified color. This color is used if the image is null.
  Parameters:
    `color` - the new background color
  Throws:
    CapabilityNotSetException - if appropriate capability is not set and this object is part of live or compiled scene graph

### setColor

    public final void setColor(float r,
                               float g,
                               float b)

  Sets the background color to the specified color. This color is used if the image is null.
  Parameters:
    `r` - the red component of the background color
    `g` - the green component of the background color
    `b` - the blue component of the background color
  Throws:
    CapabilityNotSetException - if appropriate capability is not set and this object is part of live or compiled scene graph

### getColor

    public final void getColor(Color3f color)

  Retrieves the background color.
  Parameters:
    `color` - the vector that will receive the current background color
  Throws:
    CapabilityNotSetException - if appropriate capability is not set and this object is part of live or compiled scene graph

### setImage

    public final void setImage(ImageComponent2D image)

  Sets the background image to the specified image. If this image is non-null then the color is ignored.
  Parameters:
    `image` - new pixel array object used as the background image
  Throws:
    CapabilityNotSetException - if appropriate capability is not set and this object is part of live or compiled scene graph

### getImage

    public final ImageComponent2D getImage()

  Retrieves the background image.
  Returns:
    the current background image
  Throws:
    CapabilityNotSetException - if appropriate capability is not set and this object is part of live or compiled scene graph

### setGeometry

    public final void setGeometry(BranchGroup branch)

  Sets the background geometry to the specified BranchGroup node. If non-null, this background geometry is drawn on top of the background color or image using a projection matrix that essentially puts the geometry at infinity. The geometry should be pre-tessellated onto a unit sphere.
  Parameters:
    `branch` - the root of the background geometry
  Throws:
    CapabilityNotSetException - if appropriate capability is not set and this object is part of live or compiled scene graph
    IllegalSharingException - if the BranchGroup node is a child of any Group node, or is already attached to a Locale, or is already referenced by another Background node.

### getGeometry

    public final BranchGroup getGeometry()

  Retrieves the background geometry.
  Returns:
    the BranchGroup node that is the root of the background geometry
  Throws:
    CapabilityNotSetException - if appropriate capability is not set and this object is part of live or compiled scene graph

### setApplicationBounds

    public final void setApplicationBounds(Bounds region)

  Set the Background's application region to the specified bounds. This is used when the application bounding leaf is set to null.
  Parameters:
    `region` - the bounds that contains the Background's new application region.
  Throws:
    CapabilityNotSetException - if appropriate capability is not set and this object is part of live or compiled scene graph

### getApplicationBounds

    public final Bounds getApplicationBounds()

  Retrieves the Background node's application bounds.
  Returns:
    this Background's application bounds information
  Throws:
    CapabilityNotSetException - if appropriate capability is not set and this object is part of live or compiled scene graph

### setApplicationBoundingLeaf

    public final void setApplicationBoundingLeaf(BoundingLeaf region)

  Set the Background's application region to the specified bounding leaf. When set to a value other than null, this overrides the application bounds object.
  Parameters:
    `region` - the bounding leaf node used to specify the Background node's new application region.
  Throws:
    CapabilityNotSetException - if appropriate capability is not set and this object is part of live or compiled scene graph

### getApplicationBoundingLeaf

    public final BoundingLeaf getApplicationBoundingLeaf()

  Retrieves the Background node's application bounding leaf.
  Returns:
    this Background's application bounding leaf information
  Throws:
    CapabilityNotSetException - if appropriate capability is not set and this object is part of live or compiled scene graph

### cloneNode

    public Node cloneNode(boolean forceDuplicate)

  Creates a new instance of the node. This routine is called by `cloneTree` to duplicate the current node.
  Overrides:
    cloneNode in class Node
  Parameters:
    `forceDuplicate` - when set to `true`, causes the `duplicateOnCloneTree` flag to be ignored. When `false`, the value of each node's `duplicateOnCloneTree` variable determines whether NodeComponent data is duplicated or copied.
    Background geometry will not clone in this operation. It is the user responsible to call `cloneTree` on that branchGroup.
  See Also:
    `Node.cloneTree()`, `Node.cloneNode(boolean)`, `Node.duplicateNode(javax.media.j3d.Node, boolean)`, `NodeComponent.setDuplicateOnCloneTree(boolean)`

### duplicateNode

    public void duplicateNode(Node originalNode,
                              boolean forceDuplicate)

  Copies all node information from `originalNode` into the current node. This method is called from the `cloneNode` method which is, in turn, called by the `cloneTree` method.

  For any NodeComponent objects contained by the object being duplicated, each NodeComponent object's `duplicateOnCloneTree` value is used to determine whether the NodeComponent should be duplicated in the new node or if just a reference to the current node should be placed in the new node. This flag can be overridden by setting the `forceDuplicate` parameter in the `cloneTree` method to `true`.
  Background geometry will not clone in this operation. It is the user responsible to call `cloneTree` on that branchGroup.

  Overrides:
    duplicateNode in class Node
  Parameters:
    `originalNode` - the original node to duplicate.
    `forceDuplicate` - when set to `true`, causes the `duplicateOnCloneTree` flag to be ignored. When `false`, the value of each node's `duplicateOnCloneTree` variable determines whether NodeComponent data is duplicated or copied.
  See Also:
    `Node.cloneTree()`, `Node.cloneNode(boolean)`, `NodeComponent.setDuplicateOnCloneTree(boolean)`

### updateNodeReferences

    public void updateNodeReferences(NodeReferenceTable referenceTable)

  Callback used to allow a node to check if any scene graph objects referenced by that node have been duplicated via a call to `cloneTree`. This method is called by `cloneTree` after all nodes in the sub-graph have been duplicated. The cloned Leaf node's method will be called and the Leaf node can then look up any object references by using the `getNewObjectReference` method found in the `NodeReferenceTable` object. If a match is found, a reference to the corresponding object in the newly cloned sub-graph is returned. If no corresponding reference is found, either a DanglingReferenceException is thrown or a reference to the original object is returned depending on the value of the `allowDanglingReferences` parameter passed in the `cloneTree` call.
  Overrides:
    updateNodeReferences in class Leaf
  Parameters:
    `referenceTable` - a NodeReferenceTableObject that contains the `getNewObjectReference` method needed to search for new object instances.
  See Also:
    `NodeReferenceTable`, `Node.cloneTree()`, `DanglingReferenceException`

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD