Leaf Node Objects

Java 3D API Specification

C H A P T E R

Leaf Node Objects

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

5.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 5-1 shows the Leaf node object hierarchy.

Constructors
public Leaf()
Constructs and initializes a new Leaf object.

Methods
The Leaf node object defines the following methods.
public void updateNodeReferences(NodeReferenceTable 
       referenceTable)
This method is called by the cloneTree method (see Section 6.2, "Cloning Subgraphs") after all nodes in the subgraph have been cloned. The user can query the NodeReferenceTable object to determine if any nodes that the Leaf node references have been duplicated by the cloneTree call and, if so, what the corresponding Node is in the new subgraph. If a user extends a predefined Java 3D object and adds a reference to another node, this method must be defined in order to ensure proper operation of the cloneTree method. The first statement in the user's updateNodeReferences method must be super.updateNodeReferences(referenceTable). For predefined Java 3D nodes, this method will be implemented automatically.

Figure 5-1 Leaf Node Hierarchy
The NodeReferenceTable object is passed to the updateNodeReferences method and allows references from the old subgraph to be translated into references in the cloned subgraph. See Section 6.2.5, "NodeReferenceTable Object," for more details.
public Node cloneTree(boolean forceDuplicate)
This method duplicates all nodes of the specified subgraph. For group nodes, the node is first duplicated via a call to cloneNode and then cloneTree is called for each child node. For leaf nodes, component data can either be duplicated or be made a reference to the original data. Leaf node cloneTree behavior is determined by the duplicateOnCloneTree flag found in every leaf node's component data class and by the forceDuplicate parameter.

5.2 Shape3D Node
The Shape3D leaf node object specifies all geometric objects. It contains two components: a reference to the shape's geometry and its appearance component. The Geometry object defines the shape's geometric data. The Appearance object specifies that object's appearance attributes, including color, material, texture, and so on. See Chapter 7, "Node Component Objects" for details of the Geometry and Appearance objects.

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
These flags, when enabled using the setCapability method, allow reading and writing of the Geometry and Appearance component objects and the collision bounds, 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 (no geometry is drawn)

collision bounds null
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 third form uses both a null geometry component and a null appearance component. If the geometry component is null, then no geometry is drawn. If the appearance component is null, then default values are used for all appearance attributes.

Methods
The Shape3D node object defines the following methods.
public final void setGeometry(Geometry geometry)
public final Geometry getGeometry()
These methods access or modify the Geometry component object associated with this Shape3D node.
public final void setAppearance(Appearance appearance)
public final 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 final void setCollisionBounds(Bounds bounds)
public final 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 Node cloneNode(boolean forceDuplicate)
This method creates a new instance of the node. This routine is called by clone-Tree to duplicate the current node. cloneNode should be overridden by any user-subclassed objects. All subclasses must have their cloneNode method consist of the following lines:
public Node cloneNode(boolean forceDuplicate) {
    UserSubClass usc = new UserSubClass();
    usc.duplicateNode(this, forceDuplicate);
    return usc;
}
public void duplicateNode(Node originalNode, 
       boolean  forceDuplicate)
This method copies all the node information from the originalNode into the current node. This method is called from the cloneNode method, which is in turn called by the cloneTree method.
For each NodeComponent object contained by the object being duplicated, the NodeComponent's duplicateOnCloneTree flag is used to determine whether the NodeComponent should be duplicated in the new node or if just a reference to the current node should be placed in the new node. This flag can be overridden by setting the forceDuplicate parameter in the cloneTree method to true.
public void updateNodeReferences(NodeReferenceTable 
       referenceTable)
This method is called by the cloneTree method (see Section 6.2, "Cloning Subgraphs") after all nodes in the subgraph have been cloned. The user can query the NodeReferenceTable object to determine if any nodes that the leaf node references have been duplicated by the cloneTree call and, if so, what the corresponding node is in the new subgraph. If a user extends a predefined Java 3D object and adds a reference to another node, this method must be defined in order to ensure proper operation of the cloneTree method. The first statement in the user's updateNodeReferences method must be super.updateNodeReferences(referenceTable). For predefined Java 3D nodes, this method will be implemented automatically.
The NodeReferenceTable object is passed to the updateNodeReferences method and allows references from the old subgraph to be translated into references in the cloned subgraph. See Section 6.2.5, "NodeReferenceTable Object," for more details.

5.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 independent 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 final void setRegion(Bounds region)
public final Bounds getRegion()
These methods set and retrieve the BoundingLeaf node's bounding region.

5.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

application bounds null

application boundingLeaf 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 final void getColor(Color3f color)
public final void setColor(Color3f color)
public final void setColor(float r, float g, float b)
These three methods access or modify the background color.
public final ImageComponent2D getImage()
public final 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 final void setGeometry(BranchGroup branch)
public final 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 final void setApplicationBounds(Bounds region)
public final 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 final void setApplicationBoundingLeaf(BoundingLeaf region)
public final 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.

5.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

scheduling bounds null

scheduling boundingLeaf 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 final void setBackDistance(double backDistance)
public final 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 8.7.3, "Projection and Clip Parameters," for details.
public final void setApplicationBounds(Bounds region)
public final 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 final void setApplicationBoundingLeaf(BoundingLeaf region)
public final 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.

5.6 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)

influencing bounds null

influencing boundingLeaf null
public Fog(float r, float g, float b)
public Fog(Color3f color)
These constructors each construct a new Fog node. The first constructor uses default values for all parameters. The remaining constructors use the specified parameters and use defaults for those parameters not specified. Default values are as follows:

Methods
The Fog node object defines the following methods.
public final void setColor(float r, float g, float b)
public final void setColor(Color3f color)
public final 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 final void setInfluencingBounds(Bounds region)
public final 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 final void setInfluencingBoundingLeaf(BoundingLeaf region)
public final 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 is used as the region of influence.
public final void setScope(Group scope, int index)
public final Group getScope(int index)
public final void addScope(Group scope)
public final void insertScope(Group scope, int index)
public final void removeScope(int index)
public final int numScopes()
public final 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 further scoped 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.

5.6.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 final void setDensity(float density)
public final float getDensity()
These two methods access or modify the density in the ExponentialFog object.

5.6.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 each 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 final void setFrontDistance(float frontDistance)
public final float getFrontDistance()
public final void setBackDistance(float backDistance)
public final 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.

5.7 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 default values:

Parameter Default Value

enable flag true

color white (1,1,1)

scope empty (universe scope)

influencing bounds null

influencing boundingLeaf 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 final void setEnable(boolean state)
public final boolean getEnable()
These methods access or modify the state of this light (that is, whether the light is enabled).
public final void setColor(Color3f color)
public final void getColor(Color3f color)
These methods access or modify the current color of this light.
public final setInfluencingBounds(Bounds region)
public final 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 final setInfluencingBoundingLeaf(BoundingLeaf region)
public final BoundingLeaf getInfluencingBoundingLeaf()
These methods access or modify the Light node's influencing bounding leaf. When set to a value other than null, this overrides the influencing bounds object and is used as the region of influence.
public final void setScope(Group scope, int index)
public final Group getScope(int index)
public final void addScope(Group scope)
public final void insertScope(Group scope, int index)
public final void removeScope(int index)
public final int numScopes()
public final 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 further scoped by a node in the hierarchy.

5.7.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.

5.7.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 final void setDirection(Vector3f direction)
public final void setDirection(float x, float y, float z)
public final void getDirection(Vector3f direction)
These methods access or modify the light's current direction.

5.7.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 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 final void setPosition(Point3f position)
public final void setPosition(float x, float y, float z)
public final void getPosition(Point3f position)
These methods access or modify the point light's current position.
public final void setAttenuation(Point3f attenuation)
public final void setAttenuation(float constant, float linear, 
       float quadratic)
public final 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.

5.7.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 final void setSpreadAngle(float spreadAngle)
public final float getSpreadAngle()
These methods access or modify the spread angle, in radians, of this spotlight.
public final void setConcentration(float concentration)
public final float getConcentration()
These methods access or modify the concentration of this spotlight.
public final void setDirection(float x, float y, float z)
public final void setDirection(Vector3f direction)
public final void getDirection(Vector3f direction)
These methods access or modify the direction of this spotlight.

5.8 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 5.8.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 non-cached 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

release flag false

continuous flag false

on switch false

scheduling region null (cannot be scheduled)

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 final void setSoundData(MediaContainer soundData)
public final 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, non-cached data may not be fully spatialized.
public final void setInitialGain(float amplitude)
public final 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 final void setLoop(int loopCount)
public final 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 non-negative 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 final void setReleaseEnable(boolean state)
public final 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 final void setContinuousEnable(boolean state)
public final boolean getContinuousEnable()
For some applications, it's useful to turn a sound source "off" but to continue "silently" playing the sound so that when it is turned back "on" the sound picks up playing in the same location (over time) as it would have been 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 final setSchedulingBounds(Bounds region)
public final 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 final void setSchedulingBoundingLeaf(BoundingLeaf region)
public final 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 final void setPriority(float ranking)
public final 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.
Sounds with a lower priority than a sound that cannot be played due to a lack of 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 number of channels required 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 seconds 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 only requires one channel. The third sound will be made audible when three channels become available (i.e., 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 11, "Audio Devices."
public final void setEnable(boolean state)
public final 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, detailed below, must be meet for a sound to be ready to be played.
public final boolean isReady()
This method retrieves the sound's "ready" status denoting that the sound is fully prepared for playing (either audibly or silently) to begin. 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 final boolean isPlaying()
A sound source will not be heard unless it is both enabled (turned on) and activated. While these two conditions are meet, the sound is potentially audible and the method isPlaying() will return a status of true.
When the sound finishes playing its sound data (including all loops), it is implicitly disabled.
public final boolean isPlayingSilently()
This method returns the sound's silent status. If a sound is enabled before it is activated it is begun playing silently. If a sound is enabled then deactivated while playing it continues playing silently. In both of these cases isPlaying() returns false but the method isPlayingSilently() returns true.
public final 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, then a value of -1 (implying infinite length) is returned.
public final 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 returns the number of channels (on the executing audio device) being used by this sound. The method returns 0 if sound is not playing.

5.8.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, whether sound is switched on or off, the sound activation region, and a priority value denoting the playback priority ranking.

5.8.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 vector (0.0, 0.0, 0.0)

initialGain 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 final void setPosition(Point3f position)
public final void setPosition(float x, float y, float z)
public final void getPosition(Point3f position)
These methods set and retrieve the position in 3D space from which the sound radiates.
public final void setDistanceGain(Point2f attenuation[])
public final void setDistanceGain(float distance[], float  gain[])
public final int getDistanceGainLength()
public final void getDistanceGain(Point2f attenuation[])
public final 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 5-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 5-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 5-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.

5.8.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 5-3 shows an approximation of angular attenuation (disregarding distance attenuation).

Figure 5-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 vector (0.0, 0.0, 1.0)

BackDistanceAttenuation null

Angular attenuation ((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 final void setDistanceGain(Point2f frontAttenuation[], 
       Point2f backAttenuation[])
public final void setDistanceGain(float frontDistance[], 
       float  frontGain[], float backDistance[], float  backGain[])
public final void setBackDistanceGain(Point2f attenuation[])
public final void setBackDistanceGain(float distance[], 
       float  gain[])
public final void getDistanceGain(Point2f  frontAttenuation[], 
       Point2f backAttenuation[])
public final 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 5-4). If both a front and back distance attenuation are set, elliptical attenuation regions are defined (see Figure 5-5). Use the PointSound setDistanceGain method to set the front distance attenuation array separately from the back distance attenuation array.

Figure 5-4 ConeSound with a Single Distance Gain Attenuation Array

Figure 5-5 ConeSound with Two Distance Gain Attenuation Arrays
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.
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 5-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 final void setDirection(Vector3f direction)
public final void setDirection(float x, float y, float z)
public final void getDirection(Vector3f direction)
This value is the sound source's direction vector. It is the axis from which angular distance is measured.
public final void setAngularAttenuation(Point2f attenuation[])
public final void setAngularAttenuation(Point3f attenuation[])
public final void setAngularAttenuation(float angle[], 
       float  angularGain[], float frequencyCutoff[])
public final int getAngularAttenuationLength()
public final void getAngularAttenuation(Point3f attenuation[])
public final 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 5-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) )

5.9 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 7.1.15, "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 the position of the sound.
It will be common for multiple Soundscape regions to be contained within a scene graph. Figure 5-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 5-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

application region null (no active region)

aural attributes 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 final void setApplicationBounds(Bounds region)
public final 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 final void setApplicationBoundingLeaf(BoundingLeaf region)
public final 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 final void setAuralAttributes(AuralAttributes attributes)
public final AuralAttributes getAuralAttributes()
These two methods access or modify the aural attributes of this Soundscape. Setting it to null results in default attribute use.

5.10 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

view attach policy View.NOMINAL_HEAD

activation radius 62

Methods
The ViewPlatform node object defines the following methods:
public final void setActivationRadius(float activationRadius)
public final 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 9, "Behaviors and Interpolators," for more details.
public final void setViewAttachPolicy(int policy)
public final 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 8.4.3, "View Attach Policy," for details.

5.11 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 9, "Behaviors and Interpolators."

5.12 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
These flags, when enabled using the setCapability method, allow an application to invoke methods that respectively read and write the GeometryArrays, appearance, weights, and collision Bounds 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, ...]

collision bounds null
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 final 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 final GeometryArray getGeometryArray(int index)
This method retrieves a single geometry array from the Morph node. The index parameter specifies which array is returned.
public final void setAppearance(Appearance appearance)
public final 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 final void setCollisionBounds(Bounds bounds)
public final 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 shape node under path intersects with the pickShape.

5.13 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 6.1.2, "Link Leaf Node," for a description of this node.

Java 3D API Specification

Copyright © 1999, Sun Microsystems, Inc. All rights reserved.

Parameter	Default Value
`appearance`	null (default values are used for all appearance attributes)
`geometry`	null (no geometry is drawn)
collision `bounds`	null

Parameter	Default Value
`color`	black (0,0,0)
`image`	null
`geometry`	null
application `bounds`	null
application boundingLeaf	null

Parameter	Default Value
`backDistance`	100
scheduling `bounds`	null
scheduling `boundingLeaf`	null

Parameter	Default Value
`color`	black (0,0,0)
`scope`	empty (universe scope)
influencing `bounds`	null
influencing `boundingLeaf`	null

Parameter	Default Value
enable flag	true
`color`	white (1,1,1)
`scope`	empty (universe scope)
influencing `bounds`	null
influencing `boundingLeaf`	null

Parameter	Default Value
`soundData`	null
`initialGain`	1.0
`loop`	0
`release` flag	false
`continuous` flag	false
on switch	false
scheduling `region`	null (cannot be scheduled)
`priority`	1.0

Parameter	Default Value
Position vector	(0.0, 0.0, 0.0)
`initialGain`	null (no attenuation performed)

Parameter	Default Value
`direction` vector	(0.0, 0.0, 1.0)
`BackDistanceAttenuation`	null
Angular attenuation	((0.0, 1.0), NO_FILTER,(/2, 0.0, NO_FILTER))

Parameter	Default Value
application `region`	null (no active region)
aural `attributes`	null (uses default aural attributes)

Parameter	Default Value
`appearance`	null
`weights`	[1, 0, 0, 0, ...]
collision `bounds`	null