Java 3D API Specification

C H A P T E R5

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

5.1 Leaf Node

The Leaf node is an abstract class for all scene graph nodes which have no children. Leaf nodes specify lights, geometry and sounds as well as provide special linking and instancing capabilities for sharing scene graphs, and 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.

The NodeReferenceTable object is passed to the updateNodeReferences method and allows for references from the old subgraph to be translated into references in the cloned subgraph. See Section 7.4, "NodeReferenceTable Object," for more details.

Figure 5-1 Leaf Node Hierarchy

public Node cloneTree(boolean forceDuplicate)

This method duplicates all nodes of the specified sub-graph. For Group Nodes, the group 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 three components: a reference to the shape's geometry, its appearance, and its squash 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. The Squash object specifies whether the object's shape is distorted by stretching or squashing.

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_SQUASH_READ
public static final int ALLOW_SQUASH_WRITE

These flags, when enabled using the setCapability method, allow reading and writing the Geometry, Appearance, and Squash component objects, 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()
public Shape3D(Geometry geometry, Appearance appearance)
public Shape3D(Geometry geometry)

Constructs and initializes a new Shape3D object with the geometry specified. The first form constructs and initializes a Shape3D object with null geometry, default appearance, and null squash component. The second form includes the appearance component of the shape. The third form uses the default appearance.

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.

public final void setSquash(Squash squash)
public final Squash getSquash()

These two methods set and retrieve the squash component of this Shape3D node. The Squash component object is applied to the geometry referenced by this Shape3D node. The Squash component object is used to stretch or squash an object, such as to turn a sphere into an ellipsoid. If sqaush is null, no scaling is applied to the geometry.

public Node cloneNode(boolean forceDuplicate)

This method duplicates the node as if it were a single entity. It does not duplicate the children or parent information.

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 track lights. Each light can move independently from the other lights and, as such, needs its own local coordinate system. However, the bounding volume 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()
Public BoundingLeaf(Bounds region)

The first form constructs a BoundingLeaf node with a unit sphere region object. The second form 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, and write 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()
public Background(Color3f color)
public Background(float r, float g, float b)
public Background(PixelArray2D image)

The first form constructs a Background leaf node with a default color of black (0.0,0.0,0.0). The next two forms construct a Background leaf node with the specified color. The final form constructs a Background leaf node with the specified 2D image.

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 PixelArray2D getImage()
public final void setImage(PixelArray2D 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 pre-tessellated onto a unit sphere.

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

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

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

These two methods access or modify the Background nodes application bounds. This is used when the application bounding leaf is set to null.

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.

Constructors

The Clip node object defines the following constructor.

public Clip(float backDistance)

This 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(float backDistance)
public final float 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.

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

These methods access and modify the Clip node's application bounds. The Clip node is active when its application region intersects the ViewPlatform's activation volume.

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

These methods access and modify the Clip node's application region. When set to a value other than null, this overrides the application bounds object.

5.6 Fog Node

The Fog leaf node is an abtract 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 volume intersects the Fog'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 applies 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

These flags, when enabled using the setCapability method, allow an application to invoke methods that respectively read the region of influence, write the region of influence, read color, and write color. 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()
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:

color: black (0,0,0)
list of scoping nodes: empty
influencingRegion: empty

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 setInfluencingBounds(Bounds region)
public final Bounds getInfluencingBounds()

These methods access or modify the Fog node's influencing region. The Fog node operates on all objects that intersect the specified Bounds. This is used when the influencing bounding leaf is set to null.

public final setInfluencingBoundingLeaf(BoundingLeaf region)
public final getInfluencingBoundingLeaf()

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

public final void setScope(Group scope)
public final Group getScope()
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. This allows them to be further scoped by a Group node in the hierarchy. The hierarchical scoping of a Fog node may not 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.

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

These constructors each construct a new ExponentialFog 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:

density: 1.0

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.

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()
public LinearFog(float r, float g, float b)
public LinearFog(Color3f color)
public LinearFog(float r, float g, float b, float frontDistance, 
       float backDistance)
public LinearFog(Color3f color, float frontDistance,
       float backDistance)

These constructors each construct a new LinearFog 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:

front distance: 0.1
back distance: 1.0

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 volume intersects 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

These flags, when enabled using the setCapability method, allow reading and writing the region of influence, the state, and the color, 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()
public Light(Color3f color)
public Light(boolean lightOn, Color3f color)

These three constructors construct and initialize a light.

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 (i.e., 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 region. The Light node operates on all objects that intersect the specified Bounds. This is used when the influencing bounding leaf is set to null.

public final setInfluencingBoundingLeaf(BoundingLeaf region)
public final getInfluencingBoundingLeaf()

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

public final void setScope(Group scope)
public final Group getScope()
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. This allows 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.

Constructors

The DirectionalLight node object defines the following constructors.

public DirectionalLight()

Constructs and initializes a directional light. The default direction of the light is toward the screen, along the negative z axis.

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 a location and attenuation parameters.

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 default position at 0.0, 0.0, 0.0.

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

These methods 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, read and write concentration, and read and write direction. These capability flags are enforced only when the node is part of a live or compiled scene graph.

Constructors

The SpotLight node object defines the following constructors.

public SpotLight()

Constructs and initializes a new spot light with the default values.

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)

Constructs and initializes a new spot light 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 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 node is an abstract class that defines the properties common to all sound nodes. A scene graph can contain multiple sounds. Associated with each sound source are: reference to sound data, an amplitude scale factor, a release flag denoting that the sound associated with this node is to play to the end when it is disabled, the number of times the sound is to be repeated, a state (whether the sound is on or off), a scheduling region, 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_SOUND_ON_READ
public static final int ALLOW_SOUND_ON_WRITE
public static final int ALLOW_SCHEDULING_BOUNDS_READ
public static final int ALLOW_SCHEDULING_BOUNDS_WRITE
public static final int ALLOW_DURATION_READ
public static final int ALLOW_IS_PLAYING_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 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.

The Sound object contains the following constant.

public static final int NO_FILTER

This value is used by Sound node and AuralAttribute component objects to denote that no filter is associated with a distance and angular attenuation array.

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:

sound data: null
initial gain: 1.0
loop: 0
release flag: false
continuous flag: false
on switch: false
scheduling region: null (cannot be scheduled)

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)

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 Java Media Players containing audio data with a SoundNode. This data can be cached or non-cached, and the non-cached data can be streaming or not. This method explicitly loads a sound if the implementation uses sound data caching, or it makes streaming data audible. While all supported types of MediaContainers can be associated with a non-spatialized Sound node, only specific types can be 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 non-streaming 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 would mean 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 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 zero denotes that the looped section is not repeated, but is played only once. A value of -1 denotes that the loop is repeated indefinitely.

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 non-streaming 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 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 methods access or modify the Sound node's scheduling bounds region. A Sound is scheduled for activation when its scheduling region intersects the ViewPlatform's activation volume. This is used when the scheduling bounding leaf is set to null.

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

These methods access or modify the Sound node's scheduling bounding leaf. When set to a value other than null, this overrides the scheduling bounds object.

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

These two methods access or modify the playing state of this sound (i.e., whether the sound is enabled). When enabled, the sound source is started playing and thus can potentially be heard, depending on its activation state, gain control parameters, continuation state, and spatiallization parameters. If the continuous state is true, even if 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. Activation state can change from active to inactive any number of times without stopping or starting the sound. To re-start a sound at the beginning of its data, re-enable the sound by calling setEnable with true.

public final boolean isPlaying()

A sound source will not be heard unless it is both enabled (turned on) and activated. After a sound source has been enabled and thus has begun playing, the end of the sound could be reached before the sound is disabled, or the sound could be deactivated without being stopped. This method returns a flag denoting if the sound is actually playing and thus is potentally audible.

public final long getDuration()

This method returns the length of time in millisecond 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.

5.8.1 BackgroundSound Node

A BackgroundSound node defines an unattenuated, non-spatialized 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 playing 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()

This constructs and initializes a new BackgroundSound node.

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. These distances are specified in the local coordinate system.

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 of distance and gain scale factor) specifies the gain scale factor slope.

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:

position vector: (0.0, 0.0, 0.0)
distance gain attenuation: 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 above default values. 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, Point3f position, 
       Point2f[] distanceAttenuation)
public PointSound(MediaContainer soundData, float initialGain, 
       int loopCount, boolean release, boolean continuous, 
       boolean enable, Bounds region, float posX, float posY, 
       float posZ, Point2f[] distanceAttenuation)
public PointSound(MediaContainer soundData, float initialGain, 
       int loopCount, boolean release, boolean continuous, 
       boolean enable, Bounds region, Point3f position, float[] 
       distance, float[] gainScale)
public PointSound(MediaContainer soundData, float initialGain, 
       int loopCount, boolean release, boolean continuous, 
       boolean enable, Bounds region, float posX, float posY, 
       float posZ, float[] distance, float[] gainScale)

These four constructors construct a PointSound node object using the provided parameter values. The first and third forms use vectors as input for the position. The second and fourth forms use individual float parameters for the elements of the position vector. 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 distance and gain scale factors components of distance attenuation. 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[] gainScale)
public final void getDistanceGain(Point2f[] attenuation)
public final void getDistanceGain(float[] distance,
       float[] gainScale)

These methods set and retrieve the sound's distance attenuation. If this is not set then no distance gain attenuation is performed (equivalent to using a distance gain 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, gain-scale-factor) pairs. The gain scale factor applied to the sound source is the linear interpolated gain value between the distance value range that includes the current distance from the listener to the sound source.

Figure 5-2 PointSound Distance Gain Attenuation

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

Distance elements in this array of Point2f is a monotonically-increasing set of floating point numbers measured from the location of the sound source in local coordinates. Gain scale factors 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 an example 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) )

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

public final void setSoundData(MediaContainer soundData)

This method sets fields that define the sound source data of this node. This method differs from the Sound node method, in that it calls the PointSoundRetained version of this method.

public final void setEnable(boolean state)

This method enables or disables sound. This method differs from the Sound node method, in that it calls the PointSoundRetained version of this method.

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 in addition to the distance gain attenuation for a general PointSound source and the active AuralAttribute component filter (see Section 5.8.2, "PointSound Node").

This node has the same attributes as a PointSound node with the addition of a direction vector and an array of points each containing: angular distance (in radians), gain scale factor, and filter (which for now consists of a lowpass filter cutoff frequency). Similar to the definition of the distance gain array for PointSounds, a piece-wise 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 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:

Direction vector: (0.0, 0.0, 1.0)
Angular attenuation:
((0.0, 1.0), Sound.NO_FILTER,(/2, 0.0, Sound.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 above. The first form uses vectors 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, 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 posX, float posY,
       float posZ, Point2f[] distanceAttenuation, float dirX,
       float dirY, float dirZ, float innerConeAngle,
       float outerConeAngle, Point3f[] angularAttenuation)
public ConeSound(MediaContainer soundData, float initialGain,
       int loopCount, boolean release, boolean continuous,
       boolean enable, Bounds region, Point3f position,
       float[] distance, float[] distanceGain, Vector3f direction, 
       float[] angle, float[] angularGain, 
       float[] frequencyCutoff)
public ConeSound(MediaContainer soundData, float initialGain,
       int loopCount, boolean release, boolean continuous,
       boolean enable, Bounds region, 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. The first and third forms use vectors as input for its position and direction. The second and fourth forms use individual float parameters for the elements of the position and direction vectors.

The first and second forms accept arrays of points for the distance attenuation and angular values. Each pair 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 third and fourth forms accept separate arrays for the distance and gain scale factors 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 intrepreted. See the setAngularAttenuation ConeSound method for details on how the separate angularDistance, angularGain, and filter arrays are intrepreted.

Methods

The ConeSound 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)

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[] frequency Cutoff)
public final void getAngularAttenuation(Point3f[] attenuation)
public final void getAngularAttenuation(float[] angle,
       float[] angularGain, float[] frequency Cutoff)

These methods set and retrieve the sound's angular gain and filter attenuation. If this is 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 Sound.NO_FILTER for all distances). This attenuation is defined as a triple of (angular distance, gain-scale-factor, filter). 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 specified in local corrdinates. Both the gain scale factor and filter applied to the sound source is the linear interpolation of values between 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 is a monotonically-increasing set of floating point numbers measured from 0 to radians. Gain scale factors 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 distances and angular gain scale factors pairs are given. The filter values for these tuples are implicitly set to Sound.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 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 angularDistance array.

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, Sound.NO_FILTER), (0.26, 0.6, 18000.0), (0.32, 0.4, 15000.0), (0.40, 0.2, 11000.0) ,(20.0, 0.16), (24.0, 0.12), (28.0, 0.05), (30.0, 0.0) )

5.9 Soundscape Node

The Soundscape leaf node defines the attributes that characterize the listener's environment as it pertains to sound. 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 (i.e., the listener), not the position of the sound.

It will be common that multiple Soundscape regions are contained within a scene graph. Figure 5-4 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-4 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:

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's application bounds region specified in the local coordinate system of this leaf node. The aural attributes associated with this Soundscape are used to render the active sounds when this application region intersects the ViewPlatform's activation volume.

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

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

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

These two methods access or modify the aural attributes of this Soundscape.

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 specifies where the viewpoint is located and which direction it is pointing. Changing the transform in the scene graph hierarchy above the ViewPlatform is the way in which a viewer navigates through the Virtual Universe.

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.

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 is intersected 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 Sound) intersects the ViewPlatform's activation volume, the "most appropriate" node is selected.

Sound leaf objects begin playing their associated sounds when their Scheduling volume 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, Interpolators, and Picking," 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.3.3, "View Attach Policy," for details.

5.11 Behavior Node

The Behavior leaf node allows an application to manipulate a scene graph at runtime. 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, Interpolators, and Picking."

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_GEOSET_READ
public static final int ALLOW_GEOSET_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_SQUASH_READ
public static final int ALLOW_SQUASH_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 squash components.

Constructors

The Morph node specifies the following constructors.

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

Construct and initialize a Morph leaf node.

Methods

The Morph node specifies the following methods.

public final void setGeometryArrays(GeometryArray 
       geometryArrays[])
public final geometryArray[] getGeometryArrays()

These methods set and retrieve the geometryArrays component of the Morph node. The geometryArrays component specifies colors, normals and texture coordinates.

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, TexGen, texture environment, transparency or other rendering parameters.

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.

public final void setSquash(Squash squash)
public final void getSquash()

These methods set and retrieve the squash component of this Morph node. The squash component is used to stretch or squash an object (e.g., to turn a sphere into an ellipsoid). If squash is null, no scaling is applied to the geometryArrays.

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 © 1997, Sun Microsystems, Inc. All rights reserved.