| java.lang.Object
 javax.media.j3d.SceneGraphObject
javax.media.j3d.Node
javax.media.j3d.Leaf
javax.media.j3d.Background
| Background | | public class Background extends Leaf (Code) | | The Background leaf node defines a solid background color
and a background image that are used to fill the window at the
beginning of each new frame. The background image may be null.
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. A Background node is
active when its application region intersects the ViewPlatform's
activation volume. If multiple Background nodes are active, the
Background node that is "closest" to the eye will be used. If no
Background nodes are active, then the window is cleared to black.
The set of nodes that can be added to a BranchGroup associated with
a Background node is limited. All Group nodes except
ViewSpecificGroup are legal in a background geometry branch
graph. The only Leaf nodes that are legal are Shape3D (except
OrientedShape3D), Morph, Light, and Fog. The presence of any other
Leaf node, including OrientedShape3D, or of a ViewSpecificGroup
node will cause an IllegalSceneGraphException to be thrown. Note
that Link nodes are not allowed; a background geometry branch graph
must not reference shared subgraphs. NodeComponent objects can be
shared between background branches and ordinary (non-background)
branches or among different background branches, however.
Light and Fog nodes in a background geometry branch graph do not
affect nodes outside of the background geometry branch graph, and
vice versa. Light and Fog nodes that appear in a background
geometry branch graph must not be hierarchically scoped to any
group node outside of that background geometry branch graph.
Conversely, Light and Fog nodes that appear outside of a particular
background geometry branch graph must not be hierarchically scoped
to any group node in that background geometry branch graph. Any
attempt to do so will be ignored.
The influencing bounds of any Light or Fog node in a background
geometry branch graph is effectively infinite (meaning that all
lights can affect all geometry objects nodes within the background
geometry graph, and that an arbitrary fog is selected). An
application wishing to limit the scope of a Light or Fog node must
use hierarchical scoping.
Picking and collision is ignored for nodes inside a background
geometry branch graph.
|
| Field Summary | |
| final public static int | ALLOW_APPLICATION_BOUNDS_READ
Specifies that the Background allows read access to its application
bounds and bounding leaf at runtime. | | final public static int | ALLOW_APPLICATION_BOUNDS_WRITE
Specifies that the Background allows write access to its application
bounds and bounding leaf at runtime. | | final public static int | ALLOW_COLOR_READ
Specifies that the Background allows read access to its color
at runtime. | | final public static int | ALLOW_COLOR_WRITE
Specifies that the Background allows write access to its color
at runtime. | | final public static int | ALLOW_GEOMETRY_READ
Specifies that the Background allows read access to its
background geometry at runtime. | | final public static int | ALLOW_GEOMETRY_WRITE
Specifies that the Background allows write access to its
background geometry at runtime. | | final public static int | ALLOW_IMAGE_READ
Specifies that the Background allows read access to its image
at runtime. | | final public static int | ALLOW_IMAGE_SCALE_MODE_READ
Specifies that the Background allows read access to its image
scale mode at runtime. | | final public static int | ALLOW_IMAGE_SCALE_MODE_WRITE
Specifies that the Background allows write access to its image
scale mode at runtime. | | final public static int | ALLOW_IMAGE_WRITE
Specifies that the Background allows write access to its image
at runtime. | | final public static int | SCALE_FIT_ALL
Indicates that the background image is scaled to fit the
window. | | final public static int | SCALE_FIT_MAX
Indicates that the background image is uniformly scaled to fit
the window such that the entire window is filled. | | final public static int | SCALE_FIT_MIN
Indicates that the background image is uniformly scaled to fit
the window such that the entire image is visible. | | final public static int | SCALE_NONE
Indicates that no scaling of the background image is done. | | final public static int | SCALE_NONE_CENTER
Indicates that the background image is centered in the window
and that no scaling of the image is done. | | final public static int | SCALE_REPEAT
Indicates that the background image is tiled to fill the entire
window. |
| Constructor Summary | |
| public | Background()
Constructs a Background node with default parameters. | | public | Background(Color3f color)
Constructs a Background node with the specified color. | | public | Background(float r, float g, float b)
Constructs a Background node with the specified color. | | public | Background(ImageComponent2D image)
Constructs a Background node with the specified image. | | 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 and image using a projection
matrix that essentially puts the geometry at infinity. |
| Method Summary | |
| public Node | cloneNode(boolean forceDuplicate)
Creates a new instance of the node. | | void | createRetained()
Creates the retained mode BackgroundRetained object that this
Background component object will point to. | | void | duplicateAttributes(Node originalNode, boolean forceDuplicate)
Copies all Background information from
originalNode into
the current node. | | public void | duplicateNode(Node originalNode, boolean forceDuplicate)
Copies all node information from originalNode into
the current node. | | public BoundingLeaf | getApplicationBoundingLeaf()
Retrieves the Background node's application bounding leaf. | | public Bounds | getApplicationBounds()
Retrieves the Background node's application bounds. | | public void | getColor(Color3f color)
Retrieves the background color. | | public BranchGroup | getGeometry()
Retrieves the background geometry. | | public ImageComponent2D | getImage()
Retrieves the background image. | | public int | getImageScaleMode()
Retrieves the current image scale mode. | | public void | setApplicationBoundingLeaf(BoundingLeaf region)
Set the Background's application region to the specified bounding leaf. | | public void | setApplicationBounds(Bounds region)
Set the Background's application region to the specified bounds. | | public void | setColor(Color3f color)
Sets the background color to the specified color. | | public void | setColor(float r, float g, float b)
Sets the background color to the specified color. | | public 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 and image using a projection
matrix that essentially puts the geometry at infinity. | | public void | setImage(ImageComponent2D image)
Sets the background image to the specified image. | | public void | setImageScaleMode(int imageScaleMode)
Sets the image scale mode for this Background node. | | 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. |
| ALLOW_APPLICATION_BOUNDS_READ | | final public static int ALLOW_APPLICATION_BOUNDS_READ(Code) | | Specifies that the Background allows read access to its application
bounds and bounding leaf at runtime.
|
| ALLOW_APPLICATION_BOUNDS_WRITE | | final public static int ALLOW_APPLICATION_BOUNDS_WRITE(Code) | | Specifies that the Background allows write access to its application
bounds and bounding leaf at runtime.
|
| ALLOW_COLOR_READ | | final public static int ALLOW_COLOR_READ(Code) | | Specifies that the Background allows read access to its color
at runtime.
|
| ALLOW_COLOR_WRITE | | final public static int ALLOW_COLOR_WRITE(Code) | | Specifies that the Background allows write access to its color
at runtime.
|
| ALLOW_GEOMETRY_READ | | final public static int ALLOW_GEOMETRY_READ(Code) | | Specifies that the Background allows read access to its
background geometry at runtime.
|
| ALLOW_GEOMETRY_WRITE | | final public static int ALLOW_GEOMETRY_WRITE(Code) | | Specifies that the Background allows write access to its
background geometry at runtime.
|
| ALLOW_IMAGE_READ | | final public static int ALLOW_IMAGE_READ(Code) | | Specifies that the Background allows read access to its image
at runtime.
|
| ALLOW_IMAGE_SCALE_MODE_READ | | final public static int ALLOW_IMAGE_SCALE_MODE_READ(Code) | | Specifies that the Background allows read access to its image
scale mode at runtime.
since:
Java 3D 1.3 |
| ALLOW_IMAGE_SCALE_MODE_WRITE | | final public static int ALLOW_IMAGE_SCALE_MODE_WRITE(Code) | | Specifies that the Background allows write access to its image
scale mode at runtime.
since:
Java 3D 1.3 |
| ALLOW_IMAGE_WRITE | | final public static int ALLOW_IMAGE_WRITE(Code) | | Specifies that the Background allows write access to its image
at runtime.
|
| SCALE_FIT_ALL | | final public static int SCALE_FIT_ALL(Code) | | Indicates that the background image is scaled to fit the
window. The image is scaled non-uniformly in x and
y by window.width/image.width and and
window.height/image.height, respectively. The
image will entirely fill the window.
See Also: Background.setImageScaleMode
since:
Java 3D 1.3 |
| SCALE_FIT_MAX | | final public static int SCALE_FIT_MAX(Code) | | Indicates that the background image is uniformly scaled to fit
the window such that the entire window is filled. The image is
scaled by the larger of window.width/image.width
and window.height/image.height. The image will
entirely fill the window, but may by clipped either in X
or Y.
The upper left corner of the image is anchored at the
upper-left corner of the window.
See Also: Background.setImageScaleMode
since:
Java 3D 1.3 |
| SCALE_FIT_MIN | | final public static int SCALE_FIT_MIN(Code) | | Indicates that the background image is uniformly scaled to fit
the window such that the entire image is visible. The image is
scaled by the smaller of window.width/image.width
and window.height/image.height. The image will
exactly fill either the width or height of the window, but not
necessarily both. The portion of the window not filled by the
image will be filled with the background color.
The upper left corner of the image is anchored at the
upper-left corner of the window.
See Also: Background.setImageScaleMode
since:
Java 3D 1.3 |
| SCALE_NONE | | final public static int SCALE_NONE(Code) | | Indicates that no scaling of the background image is done. The
image will be drawn in its actual size. If the window is
smaller than the image, the image will be clipped. If the
window is larger than the image, the portion of the window not
filled by the image will be filled with the background color.
In all cases, the upper left corner of the image is anchored at
the upper-left corner of the window.
This is the default mode.
See Also: Background.setImageScaleMode
since:
Java 3D 1.3 |
| SCALE_NONE_CENTER | | final public static int SCALE_NONE_CENTER(Code) | | Indicates that the background image is centered in the window
and that no scaling of the image is done. The image will be
drawn in its actual size. If the window is smaller than the
image, the image will be clipped. If the window is larger than
the image, the portion of the window not filled by the image
will be filled with the background color.
See Also: Background.setImageScaleMode
since:
Java 3D 1.3 |
| SCALE_REPEAT | | final public static int SCALE_REPEAT(Code) | | Indicates that the background image is tiled to fill the entire
window. The image is not scaled.
The upper left corner of the image is anchored at the
upper-left corner of the window.
See Also: Background.setImageScaleMode
since:
Java 3D 1.3 |
| Background | | public Background()(Code) | | Constructs a Background node with default parameters. The default
values are as follows:
color : black (0,0,0)
image : null
geometry : null
image scale mode : SCALE_NONE
application bounds : null
application bounding leaf : null
|
| Background | | public Background(Color3f color)(Code) | | Constructs a Background node with the specified color.
This color is used to fill the window prior to drawing any
objects in the scene.
|
| Background | | public Background(float r, float g, float b)(Code) | | Constructs a Background node with the specified color.
This color is used to fill the window prior to drawing any
objects in the scene.
|
| Background | | public Background(ImageComponent2D image)(Code) | | Constructs a Background node with the specified image. If this
image is non-null, it is rendered to the window prior to
drawing any objects in the scene. If the image is smaller
than the window,
then that portion of the window not covered by the image is
filled with the background color.
Parameters:
image - pixel array object used as the background image
exception:
IllegalArgumentException - if the image class of the specifiedImageComponent2D is ImageClass.NIO_IMAGE_BUFFER. |
| Background | | public Background(BranchGroup branch)(Code) | | Constructs a Background node with the specified geometry.
If non-null, this background geometry is drawn on top of
the background color and 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
exception:
IllegalSharingException - if the BranchGroup nodeis a child of any Group node, or is already attached to a Locale,or is already referenced by another Background node.
exception:
IllegalSceneGraphException - if specified branch graphcontains an illegal node. |
| cloneNode | | public Node cloneNode(boolean forceDuplicate)(Code) | | Creates a new instance of the node. This routine is called
by cloneTree to duplicate the current node.
Parameters:
forceDuplicate - when set to true, causes theduplicateOnCloneTree flag to be ignored. Whenfalse, the value of each node'sduplicateOnCloneTree variable determines whetherNodeComponent data is duplicated or copied.
Background geometry will not clone in this operation. It is the user's responsibilityto call cloneTree on that branchGroup.
See Also: Node.cloneTree
See Also: Node.cloneNode
See Also: Node.duplicateNode
See Also: NodeComponent.setDuplicateOnCloneTree |
| createRetained | | void createRetained()(Code) | | Creates the retained mode BackgroundRetained object that this
Background component object will point to.
|
| duplicateAttributes | | void duplicateAttributes(Node originalNode, boolean forceDuplicate)(Code) | | Copies all Background information from
originalNode into
the current node. This method is called from the
cloneNode method which is, in turn, called by the
cloneTree method.
Parameters:
originalNode - the original node to duplicate
Parameters:
forceDuplicate - when set to true, causes theduplicateOnCloneTree flag to be ignored. Whenfalse, the value of each node'sduplicateOnCloneTree variable determines whetherNodeComponent data is duplicated or copied.
exception:
RestrictedAccessException - if this object is part of a liveor compiled scenegraph.
See Also: Node.duplicateNode
See Also: Node.cloneTree
See Also: NodeComponent.setDuplicateOnCloneTree |
| duplicateNode | | public void duplicateNode(Node originalNode, boolean forceDuplicate)(Code) | | 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.
NOTE: Applications should not call this method directly.
It should only be called by the cloneNode method.
Parameters:
originalNode - the original node to duplicate.
Parameters:
forceDuplicate - when set to true, causes theduplicateOnCloneTree flag to be ignored. Whenfalse, the value of each node'sduplicateOnCloneTree variable determines whetherNodeComponent data is duplicated or copied.
exception:
ClassCastException - if originalNode is not an instance of Background
See Also: Node.cloneTree
See Also: Node.cloneNode
See Also: NodeComponent.setDuplicateOnCloneTree |
| getApplicationBoundingLeaf | | public BoundingLeaf getApplicationBoundingLeaf()(Code) | | Retrieves the Background node's application bounding leaf.
this Background's application bounding leaf information
exception:
CapabilityNotSetException - if appropriate capability isnot set and this object is part of live or compiled scene graph |
| getApplicationBounds | | public Bounds getApplicationBounds()(Code) | | Retrieves the Background node's application bounds.
this Background's application bounds information
exception:
CapabilityNotSetException - if appropriate capability isnot set and this object is part of live or compiled scene graph |
| getColor | | public void getColor(Color3f color)(Code) | | Retrieves the background color.
Parameters:
color - the vector that will receive the current background color
exception:
CapabilityNotSetException - if appropriate capability isnot set and this object is part of live or compiled scene graph |
| getGeometry | | public BranchGroup getGeometry()(Code) | | Retrieves the background geometry.
the BranchGroup node that is the root of the backgroundgeometry
exception:
CapabilityNotSetException - if appropriate capability isnot set and this object is part of live or compiled scene graph |
| getImage | | public ImageComponent2D getImage()(Code) | | Retrieves the background image.
the current background image
exception:
CapabilityNotSetException - if appropriate capability isnot set and this object is part of live or compiled scene graph |
| getImageScaleMode | | public int getImageScaleMode()(Code) | | Retrieves the current image scale mode.
the current image scale mode, one of:SCALE_NONE, SCALE_FIT_MIN, SCALE_FIT_MAX, SCALE_FIT_ALL,SCALE_REPEAT, or SCALE_NONE_CENTER.
exception:
CapabilityNotSetException - if appropriate capability isnot set and this object is part of live or compiled scene graph
since:
Java 3D 1.3 |
| setApplicationBoundingLeaf | | public void setApplicationBoundingLeaf(BoundingLeaf region)(Code) | | 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 Backgroundnode's new application region.
exception:
CapabilityNotSetException - if appropriate capability isnot set and this object is part of live or compiled scene graph |
| setApplicationBounds | | public void setApplicationBounds(Bounds region)(Code) | | 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 applicationregion.
exception:
CapabilityNotSetException - if appropriate capability isnot set and this object is part of live or compiled scene graph |
| setColor | | public void setColor(Color3f color)(Code) | | Sets the background color to the specified color.
This color is used to fill the window prior to drawing any
objects in the scene.
Parameters:
color - the new background color
exception:
CapabilityNotSetException - if appropriate capability isnot set and this object is part of live or compiled scene graph |
| setColor | | public void setColor(float r, float g, float b)(Code) | | Sets the background color to the specified color.
This color is used to fill the window prior to drawing any
objects in the scene.
Parameters:
r - the red component of the background color
Parameters:
g - the green component of the background color
Parameters:
b - the blue component of the background color
exception:
CapabilityNotSetException - if appropriate capability isnot set and this object is part of live or compiled scene graph |
| setGeometry | | public void setGeometry(BranchGroup branch)(Code) | | Sets the background geometry to the specified BranchGroup node.
If non-null, this background geometry is drawn on top of
the background color and 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
exception:
CapabilityNotSetException - if appropriate capability isnot set and this object is part of live or compiled scene graph
exception:
IllegalSharingException - if the BranchGroup nodeis a child of any Group node, or is already attached to a Locale,or is already referenced by another Background node.
exception:
IllegalSceneGraphException - if specified branch graphcontains an illegal node. |
| setImage | | public void setImage(ImageComponent2D image)(Code) | | Sets the background image to the specified image. If this
image is non-null, it is rendered to the window prior to
drawing any objects in the scene. If the image is smaller
than the window,
then that portion of the window not covered by the image is
filled with the background color.
Parameters:
image - new pixel array object used as the background image
exception:
CapabilityNotSetException - if appropriate capability isnot set and this object is part of live or compiled scene graph
exception:
IllegalSharingException - if this Background is live andthe specified image is being used by a Canvas3D as an off-screen buffer.
exception:
IllegalSharingException - if this Background isbeing used by an immediate mode context andthe specified image is being used by a Canvas3D as an off-screen buffer.
exception:
IllegalArgumentException - if the image class of the specifiedImageComponent2D is ImageClass.NIO_IMAGE_BUFFER. |
| setImageScaleMode | | public void setImageScaleMode(int imageScaleMode)(Code) | | Sets the image scale mode for this Background node.
Parameters:
imageScaleMode - the new image scale mode, one of:SCALE_NONE, SCALE_FIT_MIN, SCALE_FIT_MAX, SCALE_FIT_ALL,SCALE_REPEAT, or SCALE_NONE_CENTER.
exception:
IllegalArgumentException - if imageScaleModeis a value other than SCALE_NONE, SCALE_FIT_MIN, SCALE_FIT_MAX,SCALE_FIT_ALL, SCALE_REPEAT, or SCALE_NONE_CENTER.
exception:
CapabilityNotSetException - if appropriate capability isnot set and this object is part of live or compiled scene graph
since:
Java 3D 1.3 |
| updateNodeReferences | | public void updateNodeReferences(NodeReferenceTable referenceTable)(Code) | | 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.
NOTE: Applications should not call this method directly.
It should only be called by the cloneTree method.
Parameters:
referenceTable - a NodeReferenceTableObject that contains thegetNewObjectReference method needed to search fornew object instances
See Also: NodeReferenceTable
See Also: Node.cloneTree
See Also: DanglingReferenceException |
|
|