Leaf Node Objects

The Java 3D API Specification |

C H A P T E R 6

Leaf Node Objects

> LEAF nodes define atomic entities such as geometry, lights, and sounds. The leaf nodes and their associated meanings follow.

> ## 6.1 Leaf Node

> The Leaf node is an abstract class for all scene graph nodes that have no children. Leaf nodes specify lights, geometry, and sounds; provide special linking and instancing capabilities for sharing scene graphs; and provide a view platform for positioning and orienting a view in the virtual world. Figure 6-1 shows the Leaf node object hierarchy.

> ##### Constructors

>     public Leaf()

> Constructs and initializes a new Leaf object.

> ## 6.2 Shape3D Node

> The Shape3D leaf node object specifies all geometric objects. It contains a list of one or more Geometry component objects and a single Appearance component object. The Geometry objects define the shape node's geometric data. The Appearance object specifies that object's appearance attributes, including color, material, texture, and so on. See Chapter 8, "Node Component Objects" for details of the Geometry and Appearance objects.

> Figure 6-1 Leaf Node Hierarchy

> The list of geometry objects must all be of the same equivalence class; that is, the same basic type of primitive. For subclasses of GeometryArray, all point objects are equivalent, all line objects are equivalent, and all polygon objects are equivalent. For other subclasses of Geometry, only objects of the same subclass are equivalent. The equivalence classes are as follows:

> - GeometryArray (point): [Indexed]PointArray

> - GeometryArray (line): [Indexed]{LineArray, LineStripArray}

> - GeometryArray (polygon): [Indexed]{TriangleArray, TriangleStripArray, TriangleFanArray, QuadArray}

> - CompressedGeometry

> - Raster

> - Text3D

> ##### Constants

> The Shape3D node object defines the following flags:

>     public static final int ALLOW_GEOMETRY_READ
>     public static final int ALLOW_GEOMETRY_WRITE
>     public static final int ALLOW_APPEARANCE_READ
>     public static final int ALLOW_APPEARANCE_WRITE
>     public static final int ALLOW_COLLISION_BOUNDS_WRITE
>     public static final int ALLOW_COLLISION_BOUNDS_READ
>     public static final int ALLOW_APPEARANCE_OVERRIDE_WRITE
>     public static final int ALLOW_APPEARANCE_OVERRIDE_READ

> These flags, when enabled using the `setCapability` method, allow reading and writing of the Geometry and Appearance component objects, the collision bounds, and the appearance override enable, respectively. These capability flags are enforced only when the node is part of a live or compiled scene graph.

> ##### Constructors

> The Shape3D node object defines the following constructors:

>     public Shape3D()

> Constructs a Shape3D node with default parameters:

> Parameter | Default Value
> --- | ---
> appearance | null (default values are used for all appearance attributes)
> geometry | { null }
> collisionBounds | null
> appearanceOverrideEnable | false

> The list of geometry components is initialized with a null geometry component as the single element with an index of 0. A null geometry component specifies that no geometry is drawn. A null appearance component specifies that default values are used for all appearance attributes.

>     public Shape3D(Geometry geometry, Appearance appearance)
>     public Shape3D(Geometry geometry)

> The first form constructs and initializes a new Shape3D object with the specified geometry and appearance components. The second form uses the specified geometry and a `null` appearance component. The list of geometry components is initialized with the specified geometry component as the single element with an index of 0. If the geometry component is `null`, no geometry is drawn. A null appearance component specifies that default values are used for all appearance attributes.

> ##### Methods

> The Shape3D node object defines the following methods:

>     public void setGeometry(Geometry geometry)
>     public void setGeometry(Geometry geometry, int index)
>     public Geometry getGeometry()
>     public Geometry getGeometry(int index)

> These methods access or modify the Geometry component object associated with this Shape3D node. The first `setGeometry` method replaces the geometry component at index 0 in this Shape3D node's list of geometry components with the specified geometry component. The second `setGeometry` method replaces the geometry component at the specified index in this Shape3D node's list of geometry components with the specified geometry component. If there are existing geometry components in the list (besides the one being replaced), the new geometry component must be of the same equivalence class (point, line, polygon, CompressedGeometry, Raster, Text3D) as the others. The first `getGeometry` method retrieves the geometry component at index 0 from this Shape3D node's list of geometry components. The second `getGeometry` method retrieves the geometry component at the specified index from this Shape3D node's list of geometry components.

>     public void insertGeometry(Geometry geometry, int index)
>     public void removeGeometry(int index)

> These methods insert and remove the specified geometry component into or from this Shape3D node's list of geometry components. The `insertGeometry` method inserts the specified geometry component into this Shape3D node's list of geometry components at the specified index. If there are existing geometry components in the list, the new geometry component must be of the same equivalence class (point, line, polygon, CompressedGeometry, Raster, Text3D) as the others. The `removeGeometry` method removes the geometry component at the specified index from this Shape3D node's list of geometry components.

>     public void addGeometry(Geometry geometry)

> This method appends the specified geometry component to this Shape3D node's list of geometry components. If there are existing geometry components in the list, the new geometry component must be of the same equivalence class (point, line, polygon, CompressedGeometry, Raster, Text3D) as the others.

>     public Enumeration getAllGeometries()

> This method returns an enumeration of this Shape3D node's list of geometry components.

>     public int numGeometries()

> This method appends the specified geometry component to this Shape3D node's list of geometry components. If there are existing geometry components in the list, the new geometry component must be of the same equivalence class (point, line, polygon, CompressedGeometry, Raster, Text3D) as the others.

>     public void setAppearance(Appearance appearance)
>     public Appearance getAppearance()

> These methods access or modify the Appearance component object associated with this Shape3D node. Setting it to `null` results in default attribute use.

>     public void setCollisionBounds(Bounds bounds)
>     public Bounds getCollisionBounds()

> These methods set and retrieve the collision bounds for this node.

>     public boolean intersect(SceneGraphPath path, PickShape pickShape)
>     public boolean intersect(SceneGraphPath path, PickRay pickRay,
>            double[] dist)

> These two methods check if the geometry component of this shape node under path intersects with the pickShape.

>     public void setAppearanceOverrideEnable(boolean flag)
>     public boolean getAppearanceOverrideEnable()

> These methods set and retrieve the flag that indicates whether this node's appearance can be overridden. If the flag is true, this node's appearance may be overridden by an AlternateAppearance leaf node, regardless of the value of the `ALLOW_APPEARANCE_WRITE` capability bit. The default value is false. See Section 6.15, "AlternateAppearance Node."

> ### 6.2.1 OrientedShape3D Node

> The OrientedShape3D leaf node is a Shape3D node that is oriented along a specified axis or about a specified point. It defines an alignment mode and a rotation point or axis. This will cause the local +z axis of the object to point at the viewer's eye position. This is done regardless of the transforms above this OrientedShape3D node in the scene graph.

> The OrientedShape3D node is similar in functionality to the Billboard behavior (see Section 10.8, "Billboard Behavior"), but OrientedShape3D nodes will orient themselves correctly for each view, and they can be used within a SharedGroup.

> If the alignment mode is `ROTATE_AXIS`, the rotation will be around the specified axis. If the alignment mode is `ROTATE_ABOUT_POINT`, the rotation will be about the specified point, with an additional rotation to align the +y axis of the TransformGroup with the +y axis in the View.

> OrientedShape3D nodes are ideal for drawing screen-aligned text or for drawing roughly symmetrical objects. A typical use might consist of a quadrilateral that contains a texture of a tree.

> ##### Constants

> The OrientedShape3D node object defines the following flags:

>     public static final int ALLOW_MODE_READ
>     public static final int ALLOW_MODE_WRITE
>     public static final int ALLOW_AXIS_READ
>     public static final int ALLOW_AXIS_WRITE
>     public static final int ALLOW_POINT_READ
>     public static final int ALLOW_POINT_WRITE

> These flags, when enabled using the `setCapability` method, allow reading and writing of the alignment mode, alignment axis, and rotation point information, respectively. These capability flags are enforced only when the node is part of a live or compiled scene graph.

>     public static final int ROTATE_ABOUT_AXIS

> Specifies that rotation should be about the specified axis.

>     public static final int ROTATE_ABOUT_POINT

> Specifies that rotation should be about the specified point and that the children's y-axis should match the view object's y-axis.

> ##### Constructors

> The OrientedShape3D node specifies the following constructors:

>     public OrientedShape3D()

> Constructs an OrientedShape3D node with default parameters. The default values are as follows:

> Parameter | Default Value
> --- | ---
> alignmentMode | ROTATE_ABOUT_AXIS
> alignmentAxis | y-axis (0,1,0)
> rotationPoint | (0,0,1)

>     public OrientedShape3D(Geometry geometry, Appearance appearance,
>            int mode, Vector3f axis)
>     public OrientedShape3D(Geometry geometry, Appearance appearance,
>            int mode, Point3f point)

> The first constructor constructs an OrientedShape3D node with the specified geometry component, appearance component, mode, and axis. The second constructor constructs an OrientedShape3D node with the specified geometry component, appearance component, mode, and rotation point.

> ##### Methods

>     public void setAlignmentMode(int mode)
>     public int getAlignmentMode()

> These methods set and retrieve the alignment mode. The alignment mode is one of `ROTATE_ABOUT_AXIS` or `ROTATE_ABOUT_POINT`.

>     public void setAlignmentAxis(Vector3f axis)
>     public void setAlignmentAxis(float x, float y, float z)
>     public void getAlignmentAxis(Vector3f axis)

> These methods set and retrieve the alignment axis. This is the ray about which this OrientedShape3D rotates when the mode is `ROTATE_ABOUT_AXIS`.

>     public void setRotationPoint(Point3f point)
>     public void setRotationPoint(float x, float y, float z)
>     public void getRotationPoint(Point3f point)

> These methods set and retrieve the rotation point. This is the point about which the OrientedShape3D rotates when the mode is `ROTATE_ABOUT_POINT`.

> ## 6.3 BoundingLeaf Node

> The BoundingLeaf node defines a bounding region object that can be referenced by other leaf nodes to define a region of influence (Fog and Light nodes), an activation region (Background, Clip, and Soundscape nodes), or a scheduling region (Sound and Behavior nodes). The bounding region is defined in the local coordinate system of the BoundingLeaf node. A reference to a BoundingLeaf node can be used in place of a locally defined bounds object for any of the aforementioned regions.

> This allows an application to specify a bounding region in one coordinate system (the local coordinate system of the BoundingLeaf node) other than the local coordinate system of the node that references the bounds. For an example of how this might be used, consider a closed room with a number of track lights. Each light can move independently of the other lights and, as such, needs its own local coordinate system. However, the bounding volume is used by all the lights in the boundary of the room, which doesn't move when the lights move. In this example, the BoundingLeaf node allows the bounding region to be defined in the local coordinate system of the room, rather than in the local coordinate system of a particular light. All lights can then share this single bounding volume.

> ##### Constants

> The BoundingLeaf node object defines the following flags:

>     public static final int ALLOW_REGION_READ
>     public static final int ALLOW_REGION_WRITE

> These flags, when enabled using the `setCapability` method, allow an application to invoke methods that respectively read and write the bounding region object.

> ##### Constructors

> The BoundingLeaf node object defines the following constructors:

>     public BoundingLeaf()

> Constructs a BoundingLeaf node with a null (empty) bounding region.

>     public BoundingLeaf(Bounds region)

> Constructs a BoundingLeaf node with the specified bounding region.

> ##### Methods

>     public void setRegion(Bounds region)
>     public Bounds getRegion()

> These methods set and retrieve the BoundingLeaf node's bounding region.

> ## 6.4 Background Node

> 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 also specifies an application region in which this Background node 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.

> ##### Constants

> The Background node object defines the following flags:

>     public static final int ALLOW_APPLICATION_BOUNDS_READ
>     public static final int ALLOW_APPLICATION_BOUNDS_WRITE
>     public static final int ALLOW_IMAGE_READ
>     public static final int ALLOW_IMAGE_WRITE
>     public static final int ALLOW_COLOR_READ
>     public static final int ALLOW_COLOR_WRITE
>     public static final int ALLOW_GEOMETRY_READ
>     public static final int ALLOW_GEOMETRY_WRITE

> These flags, when enabled using the `setCapability` method, allow an application to invoke methods that respectively read and write the application region, the image, the color, and the background geometry. These capability flags are enforced only when the node is part of a live or compiled scene graph.

> ##### Constructors

> The Background node object defines the following constructors:

>     public Background()

> Constructs a Background leaf node with default parameters:

> Parameter | Default Value
> --- | ---
> color | black (0,0,0)
> image | null
> geometry | null
> applicationBounds | null
> applicationBoundingLeaf | null

>     public Background(Color3f color)
>     public Background(float r, float g, float b)
>     public Background(ImageComponent2D image)
>     public Background(Branchgroup branch)

> The first two forms construct a Background leaf node with the specified color. The second form constructs a Background leaf node with the specified 2D image. The final form constructs a Background leaf node with the specified geometry.

> ##### Methods

> The Background node object defines the following methods:

>     public void getColor(Color3f color)
>     public void setColor(Color3f color)
>     public void setColor(float r, float g, float b)

> These three methods access or modify the background color.

>     public ImageComponent2D getImage()
>     public void setImage(ImageComponent2D image)

> These two methods access or modify the background image. If the image is not `null` then it is used in place of the color.

>     public void setGeometry(BranchGroup branch)
>     public BranchGroup getGeometry()

> These two methods access or modify the Background geometry. The `setGeometry` method 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 pretessellated onto a unit sphere.

>     public void setApplicationBounds(Bounds region)
>     public Bounds getApplicationBounds()

> These two methods access or modify the Background node's application bounds. This bounds is used as the application region when the application bounding leaf is set to `null`. The `getApplicationBounds` method returns a copy of the associated bounds.

>     public void setApplicationBoundingLeaf(BoundingLeaf region)
>     public BoundingLeaf getApplicationBoundingLeaf()

> These two methods access or modify the Background node's application bounding leaf. When set to a value other than `null`, this bounding leaf overrides the application bounds object and is used as the application region.

> ## 6.5 Clip Node

> The Clip leaf node defines the far clipping plane used to clip objects in the virtual universe. It also specifies an application region in which this Clip node is active. A Clip node is active when its application region intersects the ViewPlatform's activation volume. If multiple Clip nodes are active, the Clip node that is "closest" to the eye will be used. The back distance value specified by this Clip node overrides the value specified in the View object. If no Clip nodes are active, then the back clip distance is used from the View object.

> ##### Constants

>     public static final int ALLOW_APPLICATION_BOUNDS_READ
>     public static final int ALLOW_APPLICATION_BOUNDS_WRITE
>     public static final int ALLOW_BACK_DISTANCE_READ
>     public static final int ALLOW_BACK_DISTANCE_WRITE

> These flags, when enabled using the `setCapability` method, allow an application to invoke methods that respectively read and write the application region and the back distance. These capability flags are enforced only when the node is part of a live or compiled scene graph.

> ##### Constructors

> The Clip node object defines the following constructors:

>     public Clip()

> Constructs a Clip node with default parameters:

> Parameter | Default Value
> --- | ---
> backDistance | 100
> applicationBounds | null
> applicationBoundingLeaf | null

>     public Clip(double backDistance)

> Constructs a Clip leaf node with the rear clip plane at the specified distance, in the local coordinate system, from the eye.

> ##### Methods

> The Clip node object defines the following methods:

>     public void setBackDistance(double backDistance)
>     public double getBackDistance()

> These methods access or modify the back-clipping distances in the Clip node. This distance specifies the back-clipping plane in the local coordinate system of the node. There are several considerations that need to be taken into account when choosing values for the front and back clip distances. See Section 9.7.3, "Projection and Clip Parameters," for details.

>     public void setApplicationBounds(Bounds region)
>     public Bounds getApplicationBounds()

> These two methods access or modify the Clip node's application bounds. This bounds is used as the application region when the application bounding leaf is set to `null`. The `getApplicationBounds` method returns a copy of the associated bounds.

>     public void setApplicationBoundingLeaf(BoundingLeaf region)
>     public BoundingLeaf getApplicationBoundingLeaf()

> These two methods access or modify the Clip node's application bounding leaf. When set to a value other than `null`, this bounding leaf overrides the application bounds object and is used as the application region.

> ## 6.6 ModelClip Node

> The ModelClip leaf node defines a set of six arbitrary clipping planes in the virtual universe. The planes are specified in the local coordinate system of this node, and may be individually enabled or disabled. This node also specifies a region of influence in which this set of planes is active.

> A ModelClip node also contains a list of Group nodes that specifies the hierarchical scope of this ModelClip. If the scope list is empty, the ModelClip node has universe scope; all nodes within the region of influence are affected by this ModelClip node. If the scope list is nonempty, then only those Leaf nodes under the Group nodes in the scope list are affected by this ModelClip node (subject to the influencing bounds).

> If the regions of influence of multiple ModelClip nodes overlap, the Java 3D system will choose a single set of model clip planes for those objects that lie in the intersection. This is done in an implementation-dependent manner, but in general, the ModelClip node that is "closest" to the object is chosen.

> The individual planes specify a half space defined by the following equation:

> Ax + By + Cz + D 0

>   where A, B, C, and D are the parameters that specify the plane.

> The parameters are passed in the x, y, z, and w fields, respectively, of a Vector4d object. The intersection of the set of half spaces corresponding to the enabled planes in this ModelClip node defines a region in which points are accepted. Points in this acceptance region will be rendered (subject to view clipping and other attributes). Points that are not in the acceptance region will not be rendered.

> ##### Constants

> The ModelClip node object defines the following flags:

>     public static final int ALLOW_INFLUENCING_BOUNDS_READ
>     public static final int ALLOW_INFLUENCING_BOUNDS_WRITE
>     public static final int ALLOW_PLANE_READ
>     public static final int ALLOW_PLANE_WRITE
>     public static final int ALLOW_ENABLE_READ
>     public static final int ALLOW_ENABLE_WRITE
>     public static final int ALLOW_SCOPE_READ
>     public static final int ALLOW_SCOPE_WRITE

> These flags, when enabled using the `setCapability` method, allow an application to invoke methods that respectively read and write the influencing bounds and bounding leaf, planes, enable, and scope flags. These capability flags are enforced only when the node is part of a live or compiled scene graph.

> ##### Constructors

> The ModelClip node object defines the following constructors:

>     public ModelClip()

> Constructs a ModelClip node with default parameters:

> Parameter | Default Value
> --- | ---
> planes[0] | x 1 (1,0,0,-1)
> planes[1] | -x 1 (-1,0,0,-1)
> planes[2] | y 1 (0,1,0,-1)
> planes[3] | -y 1 (0-1,0-1)
> planes[4] | z 1 (0,0,1,-1)
> planes[5] | -z 1 (0,0,-1,-1)
> enables | all planes enabled
> scope | empty (universe scope)
> influencingBounds | null
> influencingBoundingLeaf | null

>     public ModelClip(Vector4d[] planes, boolean[] enables)
>     public ModelClip(Vector4d[] planes)

> These constructors construct a new ModelClip node. The first constructor uses the specified planes and enable flags. The second constructor uses the specified parameters and uses defaults for those parameters not specified. Default values are described above.

> ##### Methods

> The ModelClip node object defines the following methods:

>     public void setInfluencingBounds(Bounds region)
>     public Bounds getInfluencingBounds()

> These methods access or modify the ModelClip node's influencing region. This is used when the influencing bounding leaf is set to null.

>     public void setInfluencingBoundingLeaf(BoundingLeaf region)
>     public BoundingLeaf getInfluencingBoundingLeaf()

> These methods access or modify the ModelClip node's influencing region. When set to a value other than null, this overrides the influencing bounds object.

>     public void setPlanes(Vector4d[] planes)
>     public void setPlane(int planeNum, Vector4d plane)
>     public void getPlanes(Vector4d[] planes)
>     public void getPlane(int planeNum, Vector4d plane)

> These methods access or modify the specified ModelClip node's clipping planes. The planes are an array of six model clipping planes. The set methods copy the individual planes into this node. The get methods copy the individual planes into the specified planes, which must be allocated by the caller.

>     public void setEnables(boolean[] enables)
>     public void setEnable(int planeNum, boolean enable)
>     public void getEnables(boolean[] enables)
>     public boolean getEnable(int planeNum)

> These methods access or modify the specified ModelClip node's enable flag. The enables are an array of six booleans.

>     public void setScope(Group scope, int index)

> This method replaces the node at the specified index in this ModelClip node's list of scopes with the specified Group node. By default, ModelClip nodes are scoped only by their influencing bounds. This allows them to be scoped further by a list of nodes in the hierarchy.

>     public Group getScope(int index)

> This method retrieves the Group node at the specified index from this ModelClip node's list of scopes.

>     public void insertScope(Group scope, int index)

> This method inserts the specified Group node into this ModelClip node's list of scopes at the specified index. By default, ModelClip nodes are scoped only by their influencing bounds. This allows them to be scoped further by a list of nodes in the hierarchy.

>     public void removeScope(int index)

> This method removes the node at the specified index from this ModelClip node's list of scopes. If this operation causes the list of scopes to become empty, this ModelClip will have universe scope; all nodes within the region of influence will be affected by this ModelClip node.

>     public Enumeration getAllScopes()

> This method returns an enumeration of this ModelClip node's list of scopes.

>     public void addScope(Group scope)

> This method appends the specified Group node to this ModelClip node's list of scopes. By default, ModelClip nodes are scoped only by their influencing bounds. This allows them to be scoped further by a list of nodes in the hierarchy.

>     public int numScopes()

> This method returns the number of nodes in this ModelClip node's list of scopes. If this number is 0, the list of scopes is empty and this ModelClip node has universe scope: All nodes within the region of influence are affected by this ModelClip node.

> ## 6.7 Fog Node

> The Fog leaf node is an abstract class that defines a common set of attributes that control fog, or depth cueing, in the scene. The Fog node includes a parameter that specifies the fog color and a Bounds object that specifies the region of influence for the Fog node.

> Objects whose bounding volumes intersect the Fog node's region of influence have fog applied to their color after lighting and texturing have been applied. The Fog node also contains a list of Group nodes that indicates the hierarchical scope of this fog. If the list of scoping nodes is empty, the fog has universe scope and will apply to all nodes in the virtual universe that are within the Fog node's region of influence.

> If the regions of influence of multiple Fog nodes overlap, the Java 3D system will choose a single set of fog parameters for those objects that lie in the intersection. This is done in an implementation-dependent manner, but in general, the Fog node that is "closest" to the object is chosen.

> ##### Constants

> The Fog node object defines the following flags:

>     public static final int ALLOW_INFLUENCING_BOUNDS_READ
>     public static final int ALLOW_INFLUENCING_BOUNDS_WRITE
>     public static final int ALLOW_COLOR_READ
>     public static final int ALLOW_COLOR_WRITE
>     public static final int ALLOW_SCOPE_READ
>     public static final int ALLOW_SCOPE_WRITE

> These flags, when enabled using the `setCapability` method, allow an application to invoke methods that respectively read and write the region of influence, read and write color, and read and write scope information. These capability flags are enforced only when the node is part of a live or compiled scene graph.

> ##### Constructors

> The Fog node object defines the following constructors:

>     public Fog()

> Constructs a Fog node with default parameters:

> Parameter | Default Value
> --- | ---
> color | black (0,0,0)
> scope | empty (universe scope)
> influencingBounds | null
> influencingBoundingLeaf | null

>     public Fog(float r, float g, float b)
>     public Fog(Color3f color)

> These constructors construct a new Fog node. The first constructor uses default values for all parameters. The second constructor uses the specified parameters and uses defaults for those parameters not specified. Default values are described above.

> ##### Methods

> The Fog node object defines the following methods:

>     public void setColor(float r, float g, float b)
>     public void setColor(Color3f color)
>     public void getColor(Color3f color)

> These three methods access or modify the Fog node's color. An application will typically set this to the same value as the background color.

>     public void setInfluencingBounds(Bounds region)
>     public Bounds getInfluencingBounds()

> These methods access or modify the Fog node's influencing bounds. This bounds is used as the region of influence when the influencing bounding leaf is set to `null`. The Fog node operates on all objects that intersect its region of influence. The `getInfluencingBounds` method returns a copy of the associated bounds.

>     public void setInfluencingBoundingLeaf(BoundingLeaf region)
>     public BoundingLeaf getInfluencingBoundingLeaf()

> These methods access or modify the Fog node's influencing bounding leaf. When set to a value other than `null`, this overrides the influencing bounds object, and it is used as the region of influence.

>     public void setScope(Group scope, int index)
>     public Group getScope(int index)
>     public void addScope(Group scope)
>     public void insertScope(Group scope, int index)
>     public void removeScope(int index)
>     public int numScopes()
>     public Enumeration getAllScopes()

> These methods access or modify the Fog node's hierarchical scope. By default, Fog nodes are scoped only by their regions of influence. These methods allow them to be scoped further by a Group node in the hierarchy. The hierarchical scoping of a Fog node cannot be accessed or modified if the node is part of a live or compiled scene graph.

> ### 6.7.1 ExponentialFog Node

> The ExponentialFog leaf node extends the Fog leaf node by adding a fog density that is used as the exponent of the fog equation. For more information on the fog equation, see Appendix E, "Equations."

> The density is defined in the local coordinate system of the node, but the actual fog equation will ideally take place in eye coordinates.

> ##### Constants

> The ExponentialFog node object defines the following flags:

>     public static final int ALLOW_DENSITY_READ
>     public static final int ALLOW_DENSITY_WRITE

> These flags, when enabled using the `setCapability` method, allow an application to invoke methods that respectively read and write the density values. These capability flags are enforced only when the node is part of a live or compiled scene graph.

> ##### Constructors

> The ExponentialFog node object defines the following constructors:

>     public ExponentialFog()

> Constructs an ExponentialFog node with default parameters:

> Parameter | Default Value
> --- | ---
> density | 1.0

>     public ExponentialFog(float r, float g, float b)
>     public ExponentialFog(Color3f color)
>     public ExponentialFog(float r, float g, float b, float density)
>     public ExponentialFog(Color3f color, float density)

> Each of these constructors creates a new ExponentialFog node using the specified parameters and use defaults for those parameters not specified.

> ##### Methods

> The ExponentialFog node object defines the following methods:

>     public void setDensity(float density)
>     public float getDensity()

> These two methods access or modify the density in the ExponentialFog object.

> ### 6.7.2 LinearFog Node

> The LinearFog leaf node extends the Fog leaf node by adding a pair of distance values, in z, at which fog should start obscuring the scene and should maximally obscure the scene.

> The front and back fog distances are defined in the local coordinate system of the node, but the actual fog equation will ideally take place in eye coordinates. For more information on the fog equation, see Appendix E, "Equations."

> ##### Constants

> The LinearFog node object defines the following flags:

>     public static final int ALLOW_DISTANCE_READ
>     public static final int ALLOW_DISTANCE_WRITE

> These flags, when enabled using the `setCapability` method, allow an application to invoke methods that respectively read and write the distance values. These capability flags are enforced only when the node is part of a live or compiled scene graph.

> ##### Constructors

> The LinearFog node object defines the following constructors:

>     public LinearFog()

> Constructs a LinearFog node with default parameters:

> Parameter | Default Value
> --- | ---
> frontDistance | 0.1
> backDistance | 1.0

>     public LinearFog(float r, float g, float b)
>     public LinearFog(Color3f color)
>     public LinearFog(float r, float g, float b, double  frontDistance,
>            double backDistance)
>     public LinearFog(Color3f color, double frontDistance,
>            double  backDistance)

> These constructors construct a new LinearFog node with the specified parameters and use defaults for those parameters not specified.

> ##### Methods

> The LinearFog node object defines the following methods:

>     public void setFrontDistance(float frontDistance)
>     public float getFrontDistance()
>     public void setBackDistance(float backDistance)
>     public float getBackDistance()

> These four methods access or modify the front and back distances in the LinearFog object. The front distance is the distance at which the fog starts obscuring objects; the back distance is the distance at which the fog fully obscures objects. Objects drawn closer than the front fog distance are not affected by fog. Objects drawn farther than the back fog distance are drawn entirely in the fog color.

> ## 6.8 Light Node

> The Light leaf node is an abstract class that defines the properties common to all Light nodes. A light has associated with it a color, a state (whether it is on or off), and a Bounds object that specifies the region of influence for the light. Objects whose bounding volumes intersect the Light node's region of influence are lit by this light. The Light node also contains a Group node that indicates the hierarchical scope of this light. If no scoping node is specified, then the light has universe scope and applies to all nodes in the virtual universe that are within the light's region of influence.

> The Java 3D lighting model is based on a subset of the OpenGL lighting model.

> ##### Constants

> The Light node object defines the following flags:

>     public static final int ALLOW_INFLUENCING_BOUNDS_READ
>     public static final int ALLOW_INFLUENCING_BOUNDS_WRITE
>     public static final int ALLOW_STATE_READ
>     public static final int ALLOW_STATE_WRITE
>     public static final int ALLOW_COLOR_READ
>     public static final int ALLOW_COLOR_WRITE
>     public static final int ALLOW_SCOPE_READ
>     public static final int ALLOW_SCOPE_WRITE

> These flags, when enabled using the `setCapability` method, allow reading and writing of the region of influence, the state, the color, and the scope information, respectively. These capability flags are enforced only when the node is part of a live or compiled scene graph.

> ##### Constructors

> The Light node object defines the following constructors:

>     public Light()

> Constructs and initializes a light with the following default values:

> Parameter | Default Value
> --- | ---
> enable | true
> color | white (1,1,1)
> scope | empty (universe scope)
> influencingBounds | null
> influencingBoundingLeaf | null

>     public Light(Color3f color)
>     public Light(boolean lightOn, Color3f color)

> These two constructors construct and initialize a light with the specified values.

> ##### Methods

> The Light node object defines the following methods:

>     public void setEnable(boolean state)
>     public boolean getEnable()

> These methods access or modify the state of this light (that is, whether the light is enabled).

>     public void setColor(Color3f color)
>     public void getColor(Color3f color)

> These methods access or modify the current color of this light.

>     public setInfluencingBounds(Bounds region)
>     public Bounds getInfluencingBounds()

> These methods access or modify the Light node's influencing bounds. This bounds is used as the region of influence when the influencing bounding leaf is set to `null`. The Light node operates on all objects that intersect its region of influence. The `getInfluencingBounds` method returns a copy of the associated bounds.

>     public setInfluencingBoundingLeaf(BoundingLeaf region)
>     public BoundingLeaf getInfluencingBoundingLeaf()

> These methods access or modify the Light node's influencing bounding leaf. A value other than `null` overrides the influencing bounds object and it is used as the region of influence.

>     public void setScope(Group scope, int index)
>     public Group getScope(int index)
>     public void addScope(Group scope)
>     public void insertScope(Group scope, int index)
>     public void removeScope(int index)
>     public int numScopes()
>     public Enumeration getAllScopes()

> These methods access or modify the Light node's hierarchical scope. By default, Light nodes are scoped only by their regions of influence bounds. These methods allow them to be scoped further by a node in the hierarchy.

> ### 6.8.1 AmbientLight Node

> An AmbientLight node defines an ambient light source. It has the same attributes as the abstract Light node.

> ##### Constructors

> The AmbientLight node defines the following constructors:

>     public AmbientLight()
>     public AmbientLight(Color3f color)
>     public AmbientLight(boolean lightOn, Color3f color)

> The first constructor constructs and initializes a new AmbientLight node using default parameters. The next two constructors construct and initialize a new AmbientLight node using the specified parameters. The `color` parameter is the color of the light source. The `lightOn` flag indicates whether this light is on or off.

> ### 6.8.2 DirectionalLight Node

> A DirectionalLight node defines an oriented light with an origin at infinity. It has the same attributes as a Light node, with the addition of a direction vector to specify the direction in which it shines.

> ##### Constants

> The DirectionalLight node object defines the following flags:

>     public static final int ALLOW_DIRECTION_READ
>     public static final int ALLOW_DIRECTION_WRITE

> These flags, when enabled using the `setCapability` method, allow an application to invoke methods that respectively read or write the associated direction. These capability flags are enforced only when the node is part of a live or compiled scene graph.

> The DirectionalLight's direction vector is defined in the local coordinate system of the node.

> ##### Constructors

> The DirectionalLight node object defines the following constructors:

>     public DirectionalLight()

> Constructs and initializes a directional light with default parameters:

> Parameter | Default Value
> --- | ---
> direction | (0,0,-1)

>     public DirectionalLight(Color3f color, Vector3f direction)
>     public DirectionalLight(boolean LightOn, Color3f color,
>            Vector3f  direction)

> These constructors construct and initialize a directional light with the parameters provided.

> ##### Methods

> The DirectionalLight node object defines the following methods:

>     public void setDirection(Vector3f direction)
>     public void setDirection(float x, float y, float z)
>     public void getDirection(Vector3f direction)

> These methods access or modify the light's current direction.

> ### 6.8.3 PointLight Node

> A PointLight node defines a point light source located at some point in space and radiating light in all directions (also known as a positional light). It has the same attributes as a Light node, with the addition of location and attenuation parameters.

> The PointLight's position is defined in the local coordinate system of the node.

> ##### Constants

> The PointLight node object defines the following flags:

>     public static final int ALLOW_POSITION_READ
>     public static final int ALLOW_POSITION_WRITE
>     public static final int ALLOW_ATTENUATION_READ
>     public static final int ALLOW_ATTENUATION_WRITE

> These flags, when enabled using the `setCapability` method, allow an application to invoke methods that respectively read position, write position, read attenuation parameters, and write attenuation parameters. These capability flags are enforced only when the node is part of a live or compiled scene graph.

> ##### Constructors

> The PointLight Node defines the following constructors:

>     public PointLight()

> Constructs and initializes a point light source with the following default parameters:

> Parameter | Default Value
> --- | ---
> position | (0,0,0)
> attenuation | (1,0,0)

>     public PointLight(Color3f color, Point3f position,
>            Point3f  attenuation)
>     public PointLight(boolean lightOn, Color3f color,
>            Point3f  position, Point3f attenuation)

> These constructors construct and initialize a point light with the specified parameters.

> ##### Methods

> The PointLight node object defines the following methods:

>     public void setPosition(Point3f position)
>     public void setPosition(float x, float y, float z)
>     public void getPosition(Point3f position)

> These methods access or modify the point light's current position.

>     public void setAttenuation(Point3f attenuation)
>     public void setAttenuation(float constant, float linear,
>            float  quadratic)
>     public void getAttenuation(Point3f attenuation)

> These methods access or modify the point light's current attenuation. The values presented to the methods specify the coefficients of the attenuation polynomial, with `constant` providing the constant term, `linear` providing the linear coefficient, and `quadratic` providing the quadratic coefficient.

> ### 6.8.4 SpotLight Node

> A SpotLight node defines a point light source located at some point in space and radiating in a specific direction. It has the same attributes as a PointLight node, with the addition of a direction of radiation, a spread angle to specify its limits, and a concentration factor that specifies how quickly the light intensity attenuates as a function of the angle of radiation as measured from the direction of radiation.

> ##### Constants

> The SpotLight node object defines the following flags:

>     public static final int ALLOW_SPREAD_ANGLE_READ
>     public static final int ALLOW_SPREAD_ANGLE_WRITE
>     public static final int ALLOW_CONCENTRATION_READ
>     public static final int ALLOW_CONCENTRATION_WRITE
>     public static final int ALLOW_DIRECTION_READ
>     public static final int ALLOW_DIRECTION_WRITE

> These flags, when enabled using the `setCapability` method, allow an application to invoke methods that respectively read and write spread angle, concentration, and direction. These capability flags are enforced only when the node is part of a live or compiled scene graph.

> The SpotLight's direction vector and spread angle are defined in the local coordinate system of the node.

> ##### Constructors

> The SpotLight node object defines the following constructors:

>     public SpotLight()

> Constructs and initializes a new spotlight with the default values:

> Parameter | Default Value
> --- | ---
> direction | (0,0 -1)
> spreadAngle | radians
> concentration | 0.0

>     public SpotLight(Color3f color, Point3f position,
>            Point3f  attenuation, Vector3f direction, float  spreadAngle,
>            float  concentration)
>     public SpotLight(boolean lightOn, Color3f color, Point3f  position,
>            Point3f attenuation, Vector3f  direction, float  spreadAngle,
>            float  concentration)

> These construct and initialize a new spotlight with the parameters specified.

> ##### Methods

> The SpotLight node object defines the following methods:

>     public void setSpreadAngle(float spreadAngle)
>     public float getSpreadAngle()

> These methods access or modify the spread angle, in radians, of this spotlight.

>     public void setConcentration(float concentration)
>     public float getConcentration()

> These methods access or modify the concentration of this spotlight.

>     public void setDirection(float x, float y, float z)
>     public void setDirection(Vector3f direction)
>     public void getDirection(Vector3f direction)

> These methods access or modify the direction of this spotlight.

> ## 6.9 Sound Node

> The Sound leaf node is an abstract class that defines the properties common to all Sound nodes. A scene graph can contain multiple sounds. Each Sound node contains a reference to the sound data, an amplitude scale factor, a release flag denoting that the sound associated with this node is to play to the end when the sound is disabled, the number of times the sound is to be repeated, a state (whether the sound is on or off), a scheduling region, a priority, and a flag denoting if the sound is to continue playing "silently" even while it is inactive. Whenever the listener is within the Sound node's scheduling bounds, the sound is potentially audible.

> ##### Constants

> The Sound object contains the following flags:

>     public static final int ALLOW_SOUND_DATA_READ
>     public static final int ALLOW_SOUND_DATA_WRITE
>     public static final int ALLOW_INITIAL_GAIN_READ
>     public static final int ALLOW_INITIAL_GAIN_WRITE
>     public static final int ALLOW_LOOP_READ
>     public static final int ALLOW_LOOP_WRITE
>     public static final int ALLOW_RELEASE_READ
>     public static final int ALLOW_RELEASE_WRITE
>     public static final int ALLOW_CONT_PLAY_READ
>     public static final int ALLOW_CONT_PLAY_WRITE
>     public static final int ALLOW_ENABLE_READ
>     public static final int ALLOW_ENABLE_WRITE
>     public static final int ALLOW_SCHEDULING_BOUNDS_READ
>     public static final int ALLOW_SCHEDULING_BOUNDS_WRITE
>     public static final int ALLOW_PRIORITY_READ
>     public static final int ALLOW_PRIORITY_WRITE
>     public static final int ALLOW_DURATION_READ
>     public static final int ALLOW_CHANNELS_USED_READ
>     public static final int ALLOW_IS_PLAYING_READ
>     public static final int ALLOW_IS_READY_READ

> These flags, when enabled using the `setCapability` method, allow an application to invoke methods that respectively read and write the sound data, the initial gain information, the loop information, the release flag, the continuous play flag, the sound on/off switch, the scheduling region, the prioritization value, the duration information, and the sound playing information. These capability flags are enforced only when the node is part of a live or compiled scene graph.

>     public static final float NO_FILTER

> This constant defines a floating point value that denotes that no filter value is set. Filters are described in Section 6.9.3, "ConeSound Node."

>     public static final int DURATION_UNKNOWN

> This constant denotes that the sound's duration could not be calculated; a fallback for `getDuration` of a noncached sound.

> ##### Constructors

> The Sound node object defines the following constructors:

>     public Sound()

> Constructs and initializes a new Sound node object that includes the following defaults for its fields:

> Parameter | Default Value
> --- | ---
> soundData | null
> initialGain | 1.0
> loop | 0
> releaseEnable flag | false
> continuousEnable flag | false
> enable | false
> schedulingBounds | null (cannot be scheduled)
> schedulingBoundingLeaf | null
> priority | 1.0

>     public Sound(MediaContainer soundData, float initialGain)

> Constructs and initializes a new Sound node object using the provided data and gain parameter values and defaults for all other fields. This constructor implicitly loads the sound data associated with this node if the implementation uses sound caching.

>     public Sound(MediaContainer soundData, float initialGain,
>            int  loopCount, boolean release, boolean continuous,
>            boolean  enable, Bounds region, float priority)

> Constructs and initializes a new Sound node object using the provided parameter values.

> ##### Methods

> The Sound node object defines the following methods:

>     public void setSoundData(MediaContainer soundData)
>     public MediaContainer getSoundData()

> These methods provide a way to associate different types of audio data with a Sound node. This data can be cached (buffered) or noncached (unbuffered or streaming). If the AudioDevice has been attached to the PhysicalEnvironment, the sound data is made ready to begin playing. Certain functionality cannot be applied to true streaming sound data: sound duration is unknown, looping is disabled, and the sound cannot be restarted. Furthermore, depending on the implementation of the AudioDevice used, streaming, noncached data may not be fully spatialized.

>     public void setInitialGain(float amplitude)
>     public float getInitialGain()

> This gain is a scale factor that is applied to the sound data associated with this sound source to increase or decrease its overall amplitude.

>     public void setLoop(int loopCount)
>     public int getLoop()

> Data for nonstreaming sound (such as a sound sample) can contain two loop points marking a section of the data that is to be looped a specific number of times. Thus, sound data can be divided into three segments: the attack (before the begin loop point), the sustain (between the begin and end loop points), and the release (after the end loop point). If there are no loop begin and end points defined as part of the sound data (say for Java Media Player types that do not contain sound samples), then the begin loop point is set at the beginning of the sound data, and the end loop point at the end of the sound data. If this is the case, looping the sound means repeating the whole sound. However, these begin and end loop points can be placed anywhere within the sound data, allowing a portion in the middle of the sound to be looped.

> A sound can be looped a specified number of times after it is activated and before it is completed. The loop count value explicitly sets the number of times the sound is looped. Any nonnegative number is a valid value. A value of 0 denotes that the looped section is not repeated but is played only once. A value of -1 denotes that the loop is repeated indefinitely.

> Changing the loop count of a sound after the sound has been started will not dynamically affect the loop count currently used by the sound playing. The new loop count will be used the next time the sound is enabled.

>     public void setReleaseEnable(boolean state)
>     public boolean getReleaseEnable()

> When a sound is disabled, its playback would normally stop immediately no matter what part of the sound data was currently being played. By setting the Release flag to `true` for nodes with nonstreaming sound data, the sound is allowed to play from its current position in the sound data to the end of the data (without repeats), thus playing the release portion of the sound before stopping.

>     public void setContinuousEnable(boolean state)
>     public boolean getContinuousEnable()

> For some applications, it's useful to turn a sound source "off" but to continue playing the sound "silently" so that when it is turned back "on," the sound picks up playing in the same location (over time) it would have played if the sound had never been disabled (turned off). Setting the continuous flag to `true` causes the sound renderer to keep track of where (over time) the sound would be playing even when the sound is disabled.

>     public setSchedulingBounds(Bounds region)
>     public Bounds getSchedulingBounds()

> These two methods access or modify the Sound node's scheduling bounds. This bounds is used as the scheduling region when the scheduling bounding leaf is set to `null`. A sound is scheduled for activation when its scheduling region intersects the ViewPlatform's activation volume. The `getSchedulingBounds` method returns a copy of the associated bounds.

>     public void setSchedulingBoundingLeaf(BoundingLeaf region)
>     public BoundingLeaf getSchedulingBoundingLeaf()

> These two methods access or modify the Sound node's scheduling bounding leaf. When set to a value other than `null`, this bounding leaf overrides the scheduling bounds object and is used as the scheduling region.

>     public void setPriority(float ranking)
>     public float getPriority()

> These methods access or modify the Sound node's priority, which is used to rank concurrently playing sounds in order of importance during playback. When more sounds are started than the AudioDevice can handle, the Sound node with the lowest priority ranking is deactivated. If a sound is deactivated (due to a sound with a higher priority being started), it is automatically reactivated when resources become available (for example, when a sound with a higher priority finishes playing) or when the ordering of sound nodes is changed due to a change in a Sound node's priority.

> If a sound cannot be played due to a lack of channels, a lower priority sound requiring fewer channels will be played. For example, assume we have eight channels available for playing sounds. After ordering four sounds, we begin playing them in order, checking if the required channels to play a given sound are actually available before the sound is played. Furthermore, say the first sound needs three channels to play, the second sound needs four channels, the third sound needs three channels, and the fourth sound needs only one channel. The first and second sounds can be started because they require seven of the eight available channels. The third sound cannot be audibly started because it requires three channels and only one is still available. Consequently, the third sound starts playing "silently." The fourth sound can and will be started since it requires only one channel. The third sound will be made audible when three channels become available (that is, when the first or second sound is finished playing).

> Sounds given the same priority are ordered randomly. If the application wants a specific ordering it must assign unique priorities to each sound.

> Methods to determine what audio output resources are required for playback of a Sound node on a particular AudioDevice and to determine the currently available audio output resources are described in Chapter 12, "Audio Devices."

>     public void setEnable(boolean state)
>     public boolean getEnable()

> These two methods access or modify the playing state of this sound (that is, whether the sound is enabled). When enabled, the sound source is started and thus can potentially be heard, depending on its activation state, gain control parameters, continuation state, and spatialization parameters. If the continuous state is `true` and the sound is not active, enabling the sound starts the sound silently "playing" so that when the sound is activated, the sound is (potentially) heard from somewhere in the middle of the sound data. The activation state can change from active to inactive any number of times without stopping or starting the sound. To restart a sound at the beginning of its data, re-enable the sound by calling `setEnable` with a value of `true`.

> Setting the enable flag to `true` during construction will act as a request to start the sound playing "as soon as it can" be started. This could be close to immediately in limited cases, but several conditions, following, must be meet for a sound to be ready to be played.

>     public boolean isReady()

> This method retrieves the sound's "ready" status. If this sound is fully prepared for playing (either audibly or silently) on all initialized audio devices, this method returns `true`. Sound data associated with a Sound node, either during construction (when the MediaContainer is passed into the constructor as a parameter) or by calling `setSoundData()`, it can be prepared to begin playing only after the following conditions are satisfied:

> - The Sound node has non-null sound data associated with it.

> - The Sound node is live.

> - There is an active View in the Universe.

> - There is an initialized AudioDevice associated with the PhysicalEnvironment.

> Depending on the type of MediaContainer the sound data is and on the implementation of the AudioDevice used, sound data preparation could consist of opening, attaching, loading, or copying into memory the associated sound data. The query method, `isReady()`, returns `true` when the sound is fully preprocessed so that it is playable (audibly if active, silently if not active).

>     public boolean isPlaying()

> A sound source will not be heard unless it is both enabled (turned on) and activated. If this sound is audibly playing on any initialized audio device, this method will return a status of `true`.

> When the sound finishes playing its sound data (including all loops), it is implicitly disabled.

>     public boolean isPlayingSilently()

> This method returns the sound's silent status. If this sound is silently playing on any initialized audio device, this method returns `true`.

>     public long getDuration()

> This method returns the length of time (in milliseconds) that the sound media associated with the sound source could run (including the number of times its loop section is repeated) if it plays to completion. If the sound media type is streaming or if the sound is looped indefinitely, a value of -1 (implying infinite length) is returned.

>     public int getNumberOfChannelsUsed()

> When a sound is started it could use more than one channel on the selected AudioDevice it is to be played on. This method retrieves the number of channels that are being used to render this sound on the audio device associated with the VirtualUniverse's primary view. The method returns 0 if sound is not playing.

> ### 6.9.1 BackgroundSound Node

> A BackgroundSound node defines an unattenuated, nonspatialized sound source that has no position or direction. It has the same attributes as a Sound node. This type of sound is simply added to the sound mix without modification and is useful for playing a mono or stereo music track or an ambient sound effect. Unlike a Background (visual) node, more than one BackgroundSound node can be simultaneously enabled and active.

> ##### Constructors

> The BackgroundSound node specifies the following constructor:

>     public BackgroundSound()

> Constructs a BackgroundSound node object using the default parameters for Sound nodes.

>     public BackgroundSound(MediaContainer soundData,
>            float  initialGain)
>     public BackgroundSound(MediaContainer soundData,
>            float  initialGain, int loopCount, boolean release,
>            boolean  continuous, boolean  enable, Bounds  region,
>            float  priority)

> The first constructor constructs a new BackgroundSound node using only the provided parameter values for the sound data and initial gain. The second constructor uses the provided parameter values for the sound data, initial gain, the number of times the loop is looped, a flag denoting whether the sound data is played to the end, a flag denoting whether the sound plays silently when disabled, a flag denoting whether sound is switched on or off, the sound activation region, and a priority value denoting the playback priority ranking.

> ### 6.9.2 PointSound Node

> The PointSound node defines a spatially located sound whose waves radiate uniformly in all directions from some point in space. It has the same attributes as a Sound object, with the addition of a location and the specification of distance-based gain attenuation for listener positions between an array of distances.

> The sound's amplitude is attenuated based on the distance between the listener and the sound source position. A piecewise linear curve (defined in terms of pairs consisting of a distance and a gain scale factor) specifies the gain scale factor slope.

> The PointSound's location and attenuation distances are defined in the local coordinate system of the node.

> ##### Constants

> The PointSound object contains the following flags:

>     public static final int ALLOW_POSITION_READ
>     public static final int ALLOW_POSITION_WRITE
>     public static final int ALLOW_DISTANCE_GAIN_READ
>     public static final int ALLOW_DISTANCE_GAIN_WRITE

> These flags, when enabled using the `setCapability` method, allow an application to invoke methods that respectively read and write the position and the distance gain array. These capability flags are enforced only when the node is part of a live or compiled scene graph.

> ##### Constructors

> The PointSound node object defines the following constructors:

>     public PointSound()

> Constructs a PointSound node object that includes the defaults for a Sound object plus the following defaults for its own fields:

> Parameter | Default Value
> --- | ---
> position | (0.0, 0.0, 0.0)
> distanceGain | null (no attenuation performed)

>     public PointSound(MediaContainer soundData, float initialGain,
>            Point3f position)
>     public PointSound(MediaContainer soundData, float initialGain,
>            float posX, float posY, float posZ)

> Both of these constructors construct a PointSound node object using only the provided parameter values for sound data, sample gain, and position. The remaining fields are set to the default values specified earlier. The first form uses vectors as input for its position; the second form uses individual float parameters for the elements of the position vector.

>     public PointSound(MediaContainer soundData, float initialGain,
>            int  loopCount, boolean release, boolean continuous,
>            boolean  enable, Bounds region, float priority,
>            Point3f  position, Point2f distanceGain[])
>     public PointSound(MediaContainer soundData, float initialGain,
>            int  loopCount, boolean release, boolean continuous,
>            boolean  enable, Bounds region, float priority, float  posX,
>            float posY, float posZ, Point2f  distanceGain[])
>     public PointSound(MediaContainer soundData, float initialGain,
>            int  loopCount, boolean release, boolean continuous,
>            boolean  enable, Bounds region, float priority,
>            Point3f  position, float  attenuationDistance[],
>            float  attenuationGain[])
>     public PointSound(MediaContainer soundData, float initialGain,
>            int  loopCount, boolean release, boolean continuous,
>            boolean  enable, Bounds region, float priority, float  posX,
>            float posY, float posZ, float  attenuationDistance[],
>            float  attenuationGain[])

> These four constructors construct a PointSound node object using the provided parameter values. The first and third forms use points as input for the position. The second and fourth forms use individual float parameters for the elements of the position. The first and second forms accept an array of Point2f for the distance attenuation values where each pair in the array contains a distance and a gain scale factor. The third and fourth forms accept separate arrays for the components of distance attenuation, namely, the distance and gain scale factors. See the description for the `setDistanceGain` method, below, for details on how the separate arrays are interpreted.

> ##### Methods

> The PointSound node object defines the following methods:

>     public void setPosition(Point3f position)
>     public void setPosition(float x, float y, float z)
>     public void getPosition(Point3f position)

> These methods set and retrieve the position in 3D space from which the sound radiates.

>     public void setDistanceGain(Point2f attenuation[])
>     public void setDistanceGain(float distance[], float  gain[])
>     public int getDistanceGainLength()
>     public void getDistanceGain(Point2f attenuation[])
>     public void getDistanceGain(float distance[], float  gain[])

> These methods set and retrieve the sound's distance attenuation. If this is not set, no distance gain attenuation is performed (equivalent to using a gain scale factor of 1.0 for all distances). See Figure 6-2. Gain scale factors are associated with distances from the listener to the sound source via an array of distance and gain scale factor pairs. The gain scale factor applied to the sound source is determined by finding the range of values `distance[i]` and `distance[i+1]` that includes the current distance from the listener to the sound source then linearly interpolating the corresponding values `gain[i]` and `gain[i+1]` by the same amount.

> If the distance from the listener to the sound source is less than the first distance in the array, the first gain scale factor is applied to the sound source. This creates a spherical region around the listener within which all sound gain is uniformly scaled by the first gain in the array.

> If the distance from the listener to the sound source is greater than the last distance in the array, the last gain scale factor is applied to the sound source.

> The first form of `setDistanceGain` takes these pairs of values as an array of Point2f. The second form accepts two separate arrays for these values. The `distance` and `gainScale` arrays should be of the same length. If the `gainScale` array length is greater than the `distance` array length, the `gainScale` array elements beyond the length of the `distance` array are ignored. If the `gainScale` array is shorter than the `distance` array, the last `gainScale` array value is repeated to fill an array of length equal to `distance` array.

> There are two methods for `getDistanceGain`: one returning an array of points, the other returning separate arrays for each attenuation component.

> Figure 6-2 PointSound Distance Gain Attenuation

> Distance elements in this array of Point2f are a monotonically increasing set of floating-point numbers measured from the location of the sound source. Gain scale factor elements in this list of pairs can be any positive floating-point numbers. While for most applications this list of gain scale factors will usually be monotonically decreasing, they do not have to be.

> Figure 6-2 shows a graphical representation of a distance gain attenuation list. The values given for distance/gain pairs would be

>   ( (10.0, 1.0), (12.0, 0.9), (16.0, 0.5), (17.0, 0.3),
>   (20.0, 0.16), (24.0, 0.12), (28.0, 0.05), (30.0, 0.0) )

> Thus if the current distance from the listener to the sound source is 22 units, a scale factor of 0.14 would be applied to the sound amplitude. If the current distance from the listener to the sound source is less than 10 units, the scale factor of 1.0 would be applied to the sound amplitude. If the current distance from the listener to the sound source is greater than 30 units, the scale factor of 0.0 would be applied to the sound amplitude.

> The `getDistanceGainLength` method returns the length of the distance gain attenuation arrays. Arrays passed into `getDistanceGain` methods should all be at least this size.

> ### 6.9.3 ConeSound Node

> The ConeSound node object defines a PointSound node whose sound source is directed along a specific vector in space. A ConeSound source is attenuated by gain scale factors and filters based on the angle between the vector from the source to the listener, and the ConeSound's direction vector. This attenuation is either a single spherical distance gain attenuation (as for a general PointSound source) or dual front and back distance gain attenuations defining elliptical attenuation volumes. The angular filter and the active AuralAttribute component filter define what filtering is applied to the sound source.

> This node has the same attributes as a PointSound node, with the addition of a direction vector and an array of points that each contain an angular distance (in radians), a gain scale factor, and a filter (which for now consists of a lowpass filter cutoff frequency). Similar to the definition of the distance gain array for PointSounds, a piecewise linear curve (defined in terms of radians from the axis) specifies the slope of these additional attenuation values.

> Figure 6-3 shows an approximation of angular attenuation (disregarding distance attenuation).

> Figure 6-3 ConeSound

> ##### Constants

> The ConeSound object contains the following flags:

>     public static final int ALLOW_DIRECTION_READ
>     public static final int ALLOW_DIRECTION_WRITE
>     public static final int ALLOW_ANGULAR_ATTENUATION_READ
>     public static final int ALLOW_ANGULAR_ATTENUATION_WRITE

> These flags, when enabled using the `setCapability` method, allow an application to invoke methods that respectively read and write the direction and the angular attenuation array. These capability flags are enforced only when the node is part of a live or compiled scene graph.

> ##### Constructors

> The ConeSound node object defines the following constructors:

>     public ConeSound()

> Constructs a ConeSound node object that includes the defaults for a PointSound object plus the following defaults for its own fields:

> Parameter | Default Value
> --- | ---
> direction | (0.0, 0.0, 1.0)
> angularAttenuation | ((0.0, 1.0, NO_FILTER),(/2, 0.0, NO_FILTER))

>     public ConeSound(MediaContainer soundData, float initialGain,
>            Point3f position, Vector3f direction)
>     public ConeSound(MediaContainer soundData, float initialGain,
>            float posX, float posY, float posZ, float dirX, float  dirY,
>            float dirZ)

> Both of these constructors construct a ConeSound node object using only the provided parameter values for sound, overall initial gain, position, and direction. The remaining fields are set to the default values listed earlier. The first form uses points as input for its position and direction. The second form uses individual float parameters for the elements of the position and direction vectors.

>     public ConeSound(MediaContainer soundData, float initialGain,
>            int  loopCount, boolean release, boolean continuous,
>            boolean  enable, Bounds region, float priority,
>            Point3f  position, Point2f frontDistanceAttenuation[],
>            Point2f  backDistanceAttenuation[], Vector3f direction)
>     public ConeSound(MediaContainer soundData, float initialGain,
>            int  loopCount, boolean release, boolean continuous,
>            boolean  enable, Bounds region, float priority, float  posX,
>            float  posY, float posZ, float  frontDistance[],
>            float  frontDistanceGain[], float  backDistance[],
>            float  backDistanceGain[], float  dirX, float dirY, float  dirZ)

> These constructors construct a ConeSound node object using the provided parameter values. The first form uses points or vectors as input for its position, direction, and front/back distance attenuation arrays. The second form uses individual float parameters for the elements of the position, direction, and two distance attenuation arrays.

> Unlike the single distance gain attenuation array for PointSounds, which define spherical areas about the sound source between which gains are linearly interpolated, this directed ConeSound can have two distance gain attenuation arrays that define ellipsoidal attenuation areas. See the `setDistanceGain` PointSound method for details on how the separate `distance` and `distanceGain` arrays are interpreted.

> The ConeSound's direction vector and angular measurements are defined in the local coordinate system of the node.

>     public ConeSound(MediaContainer soundData, float initialGain,
>            int  loopCount, boolean release, boolean continuous,
>            boolean  enable, Bounds region, float priority,
>            Point3f  position, Point2f distanceAttenuation[],
>            Vector3f  direction, Point3f  angularAttenuation[])
>     public ConeSound(MediaContainer soundData, float initialGain,
>            int  loopCount, boolean release, boolean continuous,
>            boolean  enable, Bounds region, float priority, float  posX,
>            float posY, float posZ, float distance[],
>            float  distanceGain[], float dirX, float dirY, float dirZ,
>            float  angle[], float  angularGain[], float  frequencyCutoff[])

> These constructors construct a ConeSound node object using the provided parameter values, which include a single spherical distance attenuation array. The first form uses points and vectors as input for its position, direction, single spherical `distanceAttenuation` array, and `angularAttenuation` array. The second form uses individual float parameters for the elements of the position, direction, `distanceAttenuation` array, and `angularAttenuation` array.

> The first form accepts arrays of points for the distance attenuation and angular values. Each Point2f in the `distanceAttenuation` array contains a distance and a gain scale factor. Each Point3f in the `angularAttenuation` array contains an angular distance, a gain scale factor, and a filtering value (which is currently defined as a simple cutoff frequency).

> The second form accepts separate arrays for the distance and gain scale factor components of distance attenuation, and separate arrays for the angular distance, angular gain, and filtering components of angular attenuation. See the `setDistanceGain` PointSound method for details on how the separate `distance` and `distanceGain` arrays are interpreted. See the `setAngularAttenuation` ConeSound method for details on how the separate `angularDistance`, `angularGain`, and `filter` arrays are interpreted.

>     public ConeSound(MediaContainer soundData, float initialGain,
>            int  loopCount, boolean release, boolean continuous,
>            boolean  enable, Bounds region, float priority,
>            Point3f  position, Point2f frontDistanceAttenuation[],
>            Point2f  backDistanceAttenuation[], Vector3f  direction,
>            Point3f angularAttenuation[])
>     public ConeSound(MediaContainer soundData, float initialGain,
>            int  loopCount, boolean release, float priority,
>            boolean  continuous, boolean enable, Bounds region,
>            float  posX, float posY, float posZ, float  frontDistance[],
>            float frontDistanceGain[], float  backDistance[],
>            float  backDistanceGain[], float  dirX, float dirY, float  dirZ,
>            float  angle[], float  angularGain[], float  frequencyCutoff[])

> These constructors construct a ConeSound node object using the provided parameter values, which include two distance attenuation arrays defining elliptical distance attenuation regions. The first form uses points and vectors as input for its position, direction, and attenuation arrays. The second form uses individual float parameters for these same elements.

> These two constructors differ from the previous two constructors only in the definition of the two distinct front and back distance attenuation arrays. See the `setDistanceGain` ConeSound method for details on how the separate `distance` and `distanceGain` arrays are interpreted. See the `setAngularAttenuation` ConeSound method for details on how the separate `angularDistance`, `angularGain`, and `filter` arrays are interpreted.

> ##### Methods

> The ConeSound node object defines the following methods:

>     public void setDistanceGain(Point2f frontAttenuation[], Point2f
>            backAttenuation[])
>     public void setDistanceGain(float frontDistance[],
>            float  frontGain[], float backDistance[], float  backGain[])
>     public void setBackDistanceGain(Point2f attenuation[])
>     public void setBackDistanceGain(float distance[], float  gain[])
>     public void getDistanceGain(Point2f  frontAttenuation[], Point2f
>            backAttenuation[])
>     public void getDistanceGain(float frontDistance[],
>            float  frontGain[], float backDistance[], float  backGain[])

> These methods set and retrieve the ConeSound's two distance attenuation arrays. If these are not set, no distance gain attenuation is performed (equivalent to using a distance gain of 1.0 for all distances). If only one distance attenuation array is set, spherical attenuation is assumed (see Figure 6-4). If both a front and back distance attenuation are set, elliptical attenuation regions are defined (see Figure 6-5). Use the PointSound `setDistanceGain` method to set the front distance attenuation array separately from the back distance attenuation array.

> A front distance attenuation array defines monotonically increasing distances from the sound source origin along the position direction vector. A back distance attenuation array (if given) defines monotonically increasing distances from the sound source origin along the negative direction vector. The two arrays must be of the same length. The `backDistance[i]` gain values must be less than or equal to `frontDistance[i]` gain values.

> Figure 6-4 ConeSound with a Single Distance Gain Attenuation Array

> Figure 6-5 ConeSound with Two Distance Gain Attenuation Arrays

> Gain scale factors are associated with distances from the listener to the sound source via an array of distance and gain scale factor pairs (see Figure 6-2). The gain scale factor applied to the sound source is the linear interpolated gain value within the distance value range that includes the current distance from the listener to the sound source.

> The `getDistanceGainLength` method (defined in PointSound) returns the length of all distance gain attenuation arrays, including the back distance gain arrays. Arrays passed into getBackDistanceGain methods should all be at least this size.

>     public void setDirection(Vector3f direction)
>     public void setDirection(float x, float y, float z)
>     public void getDirection(Vector3f direction)

> This value is the sound source's direction vector. It is the axis from which angular distance is measured.

>     public void setAngularAttenuation(Point2f attenuation[])
>     public void setAngularAttenuation(Point3f attenuation[])
>     public void setAngularAttenuation(float angle[],
>            float  angularGain[], float frequencyCutoff[])
>     public int getAngularAttenuationLength()
>     public void getAngularAttenuation(Point3f attenuation[])
>     public void getAngularAttenuation(float angle[],
>            float  angularGain[], float frequencyCutoff[])

> These methods set and retrieve the sound's angular gain and filter attenuation arrays. If these are not set, no angular gain attenuation or filtering is performed (equivalent to using an angular gain scale factor of 1.0 and an angular filter of `NO_FILTER` for all distances). This attenuation is defined as a triple of angular distance, gain scale factor, and filter values. The distance is measured as the angle in radians between the ConeSound's direction vector and the vector from the sound source position to the listener. Both the gain scale factor and filter applied to the sound source are the linear interpolation of values within the distance value range that includes the angular distance from the sound source axis.

> If the angular distance from the listener-sound-position vector and the sound's direction vector is less than the first distance in the array, the first gain scale factor and first filter are applied to the sound source. This creates a conical region around the listener within which the sound is uniformly attenuated by the first gain and the first filter in the array.

> If the distance from the listener-sound-position vector and the sound's direction vector is greater than the last distance in the array, the last gain scale factor and last filter are applied to the sound source.

> Distance elements in this array of points are a monotonically increasing set of floating point numbers measured from 0 to radians. Gain scale factor elements in this list of points can be any positive floating-point numbers. While for most applications this list of gain scale factors will usually be monotonically decreasing, they do not have to be. The filter (for now) is a single simple frequency cutoff value.

> In the first form of `setAngularAttenuation`, only the angular distance and angular gain scale factor pairs are given. The filter values for these tuples are implicitly set to `NO_FILTER`. In the second form of `setAngularAttenuation`, an array of all three values is supplied.

> The third form of `setAngularAttenuation` accepts three separate arrays for these angular attenuation values. These arrays should be of the same length. If the `angularGain` or filtering array length is greater than the `angularDistance` array length, the array elements beyond the length of the `angularDistance` array are ignored. If the `angularGain` or filtering array is shorter than the `angularDistance` array, the last value of the short array is repeated to fill an array of length equal to the `angularDistance` array.

> The `getAngularAttenuationArrayLength` method returns the length of the angular attenuation arrays. Arrays passed into `getAngularAttenuation` methods should all be at least this size.

> There are two methods for `getAngularAttenuation`, one returning an array of points, the other returning separate arrays for each attenuation component.

> Figure 6-3 shows an example of an angular attenuation defining four points of the form (radiant distance, gain scale factor, cutoff filter frequency):

>   ( (0.12, 0.8, NO_FILTER), (0.26, 0.6, 18000.0), (0.32, 0.4, 15000.0),
>   (0.40, 0.2, 11000.0) )

> ## 6.10 Soundscape Node

> The Soundscape leaf node defines the attributes that characterize the listener's aural environment. This node defines an application region and an associated aural attribute component object that controls reverberation and atmospheric properties that affect sound source rendering. (Aural attributes are described in Section 8.1.17, "AuralAttributes Object.") Multiple Soundscape nodes can be included in a single scene graph.

> The Soundscape application region, different from a Sound node's scheduling region, is used to select which Soundscape (and thus which aural attribute object) is to be applied to the sounds being rendered. This selection is based on the position of the ViewPlatform (the "listener"), not on the position of the sound.

> It will be common for multiple Soundscape regions to be contained within a scene graph. Figure 6-6 shows application regions for two Soundscape nodes: a region with a large open area on the right, and a smaller, more constricted, less reverberant area on the left.

> Figure 6-6 Multiple Soundscape Application Regions

> The reverberation attributes for these two regions could be set to represent their physical differences so that active sounds are rendered differently depending on which region the listener is in.

> ##### Constants

> The Soundscape node object defines the following flags:

>     public static final int ALLOW_APPLICATION_BOUNDS_READ
>     public static final int ALLOW_APPLICATION_BOUNDS_WRITE
>     public static final int ALLOW_ATTRIBUTES_READ
>     public static final int ALLOW_ATTRIBUTES_WRITE

> These flags, when enabled using the `setCapability` method, allow an application to invoke methods that respectively read and write the application region and the aural attributes. These capability flags are enforced only when the node is part of a live or compiled scene graph.

> ##### Constructors

> The Soundscape node object defines the following constructors:

>     public Soundscape()

> Constructs a Soundscape node object that includes the following defaults for its elements:

> Parameter | Default Value
> --- | ---
> applicationBounds | null (no active region)
> auralAttributes | null (uses default aural attributes)

>     public Soundscape(Bounds region, AuralAttributes attributes)

> This method constructs a Soundscape node object using the specified application region and aural attributes.

> ##### Methods

> The Soundscape node object defines the following methods:

>     public void setApplicationBounds(Bounds region)
>     public Bounds getApplicationBounds()

> These two methods access or modify the Soundscape node's application bounds. This bounds is used as the application region when the application bounding leaf is set to `null`. The aural attributes associated with this Soundscape are used to render the active sounds when this application region intersects the ViewPlatform's activation volume. The `getApplicationBounds` method returns a copy of the associated bounds.

>     public void setApplicationBoundingLeaf(BoundingLeaf region)
>     public BoundingLeaf getApplicationBoundingLeaf()

> These two methods access or modify the Soundscape node's application bounding leaf. When set to a value other than `null`, this bounding leaf overrides the application bounds object and is used as the application region.

>     public void setAuralAttributes(AuralAttributes attributes)
>     public AuralAttributes getAuralAttributes()

> These two methods access or modify the aural attributes of this Soundscape. Setting it to `null` results in default attribute use.

> ## 6.11 ViewPlatform Node

> The ViewPlatform node object defines a viewing platform that is referenced by a View object. The location, orientation, and scale of the composite transforms in the scene graph from the root to the ViewPlatform specify where the viewpoint is located and in which direction it is pointing. A viewer navigates through the virtual universe by changing the transform in the scene graph hierarchy above the ViewPlatform.

> ##### Constants

> The ViewPlatform node object defines the following flags:

>     public static final int ALLOW_POLICY_READ
>     public static final int ALLOW_POLICY_WRITE

> These flags, when enabled using the `setCapability` method, allow an application to invoke methods that respectively read and write the view attach policy. These capability flags are enforced only when the node is part of a live or compiled scene graph.

> ##### Constructors

>     public ViewPlatform()

> Constructs and initializes a new ViewPlatform leaf node object with default parameters:

> Parameter | Default Value
> --- | ---
> viewAttachPolicy | View.NOMINAL_HEAD
> activationRadius | 62

> ##### Methods

> The ViewPlatform node object defines the following methods:

>     public void setActivationRadius(float activationRadius)
>     public float getActivationRadius()

> The activation radius defines an activation volume surrounding the center of the ViewPlatform. This activation volume intersects with the scheduling regions and application regions of other leaf node objects to determine which of those objects may affect rendering.

> Different leaf objects interact with the ViewPlatform's activation volume differently. The Background, Clip, and Soundscape leaf objects each define a set of attributes and an application region in which those attributes are applied. If more than one node of a given type (Background, Clip, or Soundscape) intersects the ViewPlatform's activation volume, the "most appropriate" node is selected.

> Sound leaf objects begin playing their associated sounds when their scheduling region intersects a ViewPlatform's activation volume. Multiple sounds may be active at the same time.

> Behavior objects act somewhat differently. Those Behavior objects with scheduling regions that intersect a ViewPlatform's activation volume become candidates for scheduling. Effectively, a ViewPlatform's activation volume becomes an additional qualifier on the scheduling of all Behavior objects. See Chapter 10, "Behaviors and Interpolators," for more details.

>     public void setViewAttachPolicy(int policy)
>     public int getViewAttachPolicy()

> The view attach policy determines how Java 3D places the user's virtual eye point as a function of head position. See Section 9.4.3, "View Attach Policy," for details.

> ## 6.12 Behavior Node

> The Behavior leaf node allows an application to manipulate a scene graph at run time. Behavior is an abstract class that defines properties common to all Behavior objects in Java 3D. There are several predefined behaviors that are subclasses of Behavior. Additionally, a Behavior leaf node may be subclassed by the user. Behaviors are described in Chapter 10, "Behaviors and Interpolators."

> ## 6.13 Morph Node

> The Morph leaf node permits an application to morph between multiple GeometryArrays. The Morph node contains a single Appearance node, an array of GeometryArray objects, and an array of corresponding weights. The Morph node combines these GeometryArrays into an aggregate shape based on each GeometryArray's corresponding weight. Typically, Behavior nodes will modify the weights to achieve various morphing effects.

> ##### Constants

> The Morph node specifies the following flags:

>     public static final int ALLOW_GEOMETRY_ARRAY_READ
>     public static final int ALLOW_GEOMETRY_ARRAY_WRITE
>     public static final int ALLOW_APPEARANCE_READ
>     public static final int ALLOW_APPEARANCE_WRITE
>     public static final int ALLOW_WEIGHTS_READ
>     public static final int ALLOW_WEIGHTS_WRITE
>     public static final int ALLOW_COLLISION_BOUNDS_READ
>     public static final int ALLOW_COLLISION_BOUNDS_WRITE
>     public static final int ALLOW_APPEARANCE_OVERRIDE_READ
>     public static final int ALLOW_APPEARANCE_OVERRIDE_WRITE

> These flags, when enabled using the `setCapability` method, allow an application to invoke methods that respectively read and write the node's array of GeometryArray objects, appearance, weights, collision Bounds, and appearance override enable components.

> ##### Constructors

> The Morph node specifies the following constructors:

>     public Morph(GeometryArray geometryArrays[])

> Constructs and initializes a new Morph leaf node with the specified array of GeometryArray objects. Default values are used for all other parameters:

> Parameter | Default Value
> --- | ---
> appearance | null
> weights | [1, 0, 0, 0, ...]
> collisionBounds | null
> appearanceOverrideEnable | false

> A null appearance object specifies that default values are used for all appearance attributes.

>     public Morph(GeometryArray geometryArrays[],
>            Appearance  appearance)

> Constructs and initializes a new Morph leaf node with the specified array of GeometryArray objects and the specified Appearance object. The length of the `geometryArrays` parameter determines the number of weighted geometry arrays in this Morph node. If `geometryArrays` is `null`, then a `NullPointerException` is thrown. If the Appearance component is `null`, then default values are used for all appearance attributes.

> ##### Methods

> The Morph node specifies the following methods:

>     public void setGeometryArrays(GeometryArray geometryArrays[])

> This method sets the array of GeometryArray objects in the Morph node. Each GeometryArray component specifies colors, normals, and texture coordinates. The length of the `geometryArrays` parameter must be equal to the length of the array with which this Morph node was created; otherwise, an `Illegal-ArgumentException` is thrown.

>     public GeometryArray getGeometryArray(int index)

> This method retrieves a single geometry array from the Morph node. The `index` parameter specifies which array is returned.

>     public void setAppearance(Appearance appearance)
>     public Appearance getAppearance()

> These methods set and retrieve the Appearance component of this Morph node. The Appearance component specifies material, texture, texture environment, transparency, or other rendering parameters. Setting it to `null` results in default attribute use.

>     public void setWeights(double weights[])
>     public double[] getWeights()

> These methods set and retrieve the morph weight vector component of this Morph node. The Morph node "weights" the corresponding GeometryArray by the amount specified. The length of the `weights` parameter must be equal to the length of the array with which this Morph node was created; otherwise, an `IllegalArgumentException` is thrown.

>     public void setCollisionBounds(Bounds bounds)
>     public Bounds getCollisionBounds()

> These methods set and retrieve the collision bounding object of this node.

>     public boolean intersect(SceneGraphPath path, PickShape pickShape)
>     public boolean intersect(SceneGraphPath path, PickRay pickRay,
>            double[] dist)

> These methods check if the geometry component of this morph node under path intersects with the pickShape.

>     public void setAppearanceOverrideEnable(boolean flag)
>     public boolean getAppearanceOverrideEnable()

> These methods set and retrieve the flag that indicates whether this node's appearance can be overridden. If the flag is true, this node's appearance may be overridden by an AlternateAppearance leaf node, regardless of the value of the `ALLOW_APPEARANCE_WRITE` capability bit. The default value is false. See Section 6.15, "AlternateAppearance Node."

> ## 6.14 Link Node

> The Link leaf node allows an application to reference a shared subgroup, rooted by a SharedGroup node, from within a branch of the scene graph. Any number of Link nodes can refer to the same SharedGroup node. See Section 7.1.2, "Link Leaf Node," for a description of this node.

> ## 6.15 AlternateAppearance Node

> The AlternateAppearance leaf node is used for overriding the Appearance component of selected nodes. It defines an Appearance component object and a region of influence in which this AlternateAppearance node is active. An AlternateAppearance node also contains a list of Group nodes that specifies the hierarchical scope of this AlternateAppearance. If the scope list is empty, the AlternateAppearance node has universe scope; all nodes within the region of influence are affected by this AlternateAppearance node. If the scope list is non-empty, only those Leaf nodes under the Group nodes in the scope list are affected by this AlternateAppearance node (subject to the influencing bounds).

> An AlternateAppearance node affects Shape3D and Morph nodes by overriding their appearance component with the appearance component in this AlternateAppearance node. Only those Shape3D and Morph nodes that explicitly allow their appearance to be overridden are affected. The AlternateAppearance node has no effect on Shape3D and Morph nodes that do not allow their appearance to be overridden.

> If the regions of influence of multiple AlternateAppearance nodes overlap, the Java 3D system will choose a single alternate appearance for those objects that lie in the intersection. This is done in an implementation-dependent manner, but in general, the AlternateAppearance node that is "closest" to the object is chosen.

> ##### Constants

> The AlternateAppearance node specifies the following flags:

>     public static final int ALLOW_INFLUENCING_BOUNDS_READ
>     public static final int ALLOW_INFLUENCING_BOUNDS_WRITE
>     public static final int ALLOW_APPEARANCE_READ
>     public static final int ALLOW_APPEARANCE_WRITE
>     public static final int ALLOW_SCOPE_READ
>     public static final int ALLOW_SCOPE_WRITE

> These flags, when enabled using the `setCapability` method, allow an application to invoke methods that respectively read and write the node's influencing bounds and bounds leaf information, appearance information, and scope information components.

> ##### Constructors

> The AlternateAppearance node specifies the following constructors:

>     public AlternateAppearance()

> Constructs an AlternateAppearance node with default parameters. The default values are as follows:

> Parameter | Default Value
> --- | ---
> appearance | null
> scope | empty (universe scope)
> influencingBounds | null
> influencingBoundingLeaf | null

>     public AlternateAppearance(Appearance appearance)

> Constructs an AlternateAppearance node with the specified appearance.

> ##### Methods

> The AlternateAppearance node specifies the following methods:

>     public void setAppearance(Appearance appearance)
>     public Appearance getAppearance()

> These methods set and retrieve the appearance of this AlternateAppearance node. This appearance overrides the appearance in those Shape3D and Morph nodes affected by this AlternateAppearance node.

>     public void setInfluencingBounds(Bounds region)
>     public Bounds getInfluencingBounds()

> These methods set and retrieve the AlternateAppearance's influencing region to the specified bounds. This is used when the influencing bounding leaf is set to null.

>     public void setInfluencingBoundingLeaf(BoundingLeaf region)
>     public BoundingLeaf getInfluencingBoundingLeaf()

> These methods set and retrieve the AlternateAppearance's influencing region to the specified bounding leaf. When set to a value other than null, this overrides the influencing bounds object.

>     public void setScope(Group scope, int index)
>     public Group getScope(int index)

> The first method replaces the node at the specified index in this AlternateAppearance node's list of scopes with the specified Group node. The second method retrieves the Group node at the specified index from this AlternateAppearance node's list of scopes. By default, AlternateAppearance nodes are scoped only by their influencing bounds. This allows them to be scoped further by a list of nodes in the hierarchy.

>     public void insertScope(Group scope, int index)
>     public void removeScope(int index)

> The first method inserts the specified Group node into this AlternateAppearance node's list of scopes at the specified index. The second method removes the node at the specified index from this AlternateAppearance node's list of scopes. If this operation causes the list of scopes to become empty, this AlternateAppearance will have universe scope; all nodes within the region of influence will be affected by this AlternateAppearance node. By default, AlternateAppearance nodes are scoped only by their influencing bounds. This allows them to be scoped further by a list of nodes in the hierarchy.

>     public Enumeration getAllScopes()

> This method returns an enumeration of this AlternateAppearance node's list of scopes.

>     public void addScope(Group scope)

> This method appends the specified Group node to this AlternateAppearance node's list of scopes. By default, AlternateAppearance nodes are scoped only by their influencing bounds. This allows them to be scoped further by a list of nodes in the hierarchy.

>     public int numScopes()

> This method returns the number of nodes in this AlternateAppearance node's list of scopes. If this number is 0, the list of scopes is empty and this AlternateAppearance node has universe scope; all nodes within the region of influence are affected by this AlternateAppearance node.

The Java 3D API Specification |

##### Copyright © 2000, Sun Microsystems, Inc. All rights reserved.