The Java 3D API Specification |
C H A P T E R6 |
Leaf Node Objects |
6.1
The Leaf node is an abstract class for all scene graph nodes that have no children. Leaf nodes specify lights, geometry, and sounds; provide special linking and instancing capabilities for sharing scene graphs; and provide a view platform for positioning and orienting a view in the virtual world. Figure 6-1 shows the Leaf node object hierarchy.Leaf Node public Leaf()Constructs and initializes a new Leaf object.
6.2
The Shape3D leaf node object specifies all geometric objects. It contains a list of one or more Geometry component objects and a single Appearance component object. The Geometry objects define the shape node's geometric data. The Appearance object specifies that object's appearance attributes, including color, material, texture, and so on. See Chapter 8, "Node Component Objects" for details of the Geometry and Appearance objects.Shape3D Node
Figure 6-1 Leaf Node Hierarchy
- GeometryArray (point): [Indexed]PointArray
- GeometryArray (line): [Indexed]{LineArray, LineStripArray}
- GeometryArray (polygon): [Indexed]{TriangleArray, TriangleStripArray, TriangleFanArray, QuadArray}
- CompressedGeometry
- Raster
- Text3D
Constants
The Shape3D node object defines the following flags:public static final int ALLOW_GEOMETRY_READ public static final int ALLOW_GEOMETRY_WRITE public static final int ALLOW_APPEARANCE_READ public static final int ALLOW_APPEARANCE_WRITE public static final int ALLOW_COLLISION_BOUNDS_WRITE public static final int ALLOW_COLLISION_BOUNDS_READ public static final int ALLOW_APPEARANCE_OVERRIDE_WRITE public static final int ALLOW_APPEARANCE_OVERRIDE_READThese flags, when enabled using thesetCapability
method, allow reading and writing of the Geometry and Appearance component objects, the collision bounds, and the appearance override enable, respectively. These capability flags are enforced only when the node is part of a live or compiled scene graph.
Constructors
The Shape3D node object defines the following constructors:public Shape3D()Constructs a Shape3D node with default parameters:
Parameter Default Value appearance null (default values are used for all appearance attributes) geometry { null } collisionBounds null appearanceOverrideEnable false
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 anull
appearance component. The list of geometry components is initialized with the specified geometry component as the single element with an index of 0. If the geometry component isnull
, no geometry is drawn. A null appearance component specifies that default values are used for all appearance attributes.
Methods
The Shape3D node object defines the following methods:public void setGeometry(Geometry geometry) public void setGeometry(Geometry geometry, int index) public Geometry getGeometry() public Geometry getGeometry(int index)These methods access or modify the Geometry component object associated with this Shape3D node. The firstsetGeometry
method replaces the geometry component at index 0 in this Shape3D node's list of geometry components with the specified geometry component. The secondsetGeometry
method replaces the geometry component at the specified index in this Shape3D node's list of geometry components with the specified geometry component. If there are existing geometry components in the list (besides the one being replaced), the new geometry component must be of the same equivalence class (point, line, polygon, CompressedGeometry, Raster, Text3D) as the others. The firstgetGeometry
method retrieves the geometry component at index 0 from this Shape3D node's list of geometry components. The secondgetGeometry
method retrieves the geometry component at the specified index from this Shape3D node's list of geometry components.public void insertGeometry(Geometry geometry, int index) public void removeGeometry(int index)These methods insert and remove the specified geometry component into or from this Shape3D node's list of geometry components. TheinsertGeometry
method inserts the specified geometry component into this Shape3D node's list of geometry components at the specified index. If there are existing geometry components in the list, the new geometry component must be of the same equivalence class (point, line, polygon, CompressedGeometry, Raster, Text3D) as the others. TheremoveGeometry
method removes the geometry component at the specified index from this Shape3D node's list of geometry components.public void addGeometry(Geometry geometry)This method appends the specified geometry component to this Shape3D node's list of geometry components. If there are existing geometry components in the list, the new geometry component must be of the same equivalence class (point, line, polygon, CompressedGeometry, Raster, Text3D) as the others.public Enumeration getAllGeometries()This method returns an enumeration of this Shape3D node's list of geometry components.public int numGeometries()This method appends the specified geometry component to this Shape3D node's list of geometry components. If there are existing geometry components in the list, the new geometry component must be of the same equivalence class (point, line, polygon, CompressedGeometry, Raster, Text3D) as the others.public void setAppearance(Appearance appearance) public Appearance getAppearance()These methods access or modify the Appearance component object associated with this Shape3D node. Setting it tonull
results in default attribute use.public void setCollisionBounds(Bounds bounds) public Bounds getCollisionBounds()These methods set and retrieve the collision bounds for this node.public boolean intersect(SceneGraphPath path, PickShape pickShape) public boolean intersect(SceneGraphPath path, PickRay pickRay, double[] dist)These two methods check if the geometry component of this shape node under path intersects with the pickShape.public void setAppearanceOverrideEnable(boolean flag) public boolean getAppearanceOverrideEnable()These methods set and retrieve the flag that indicates whether this node's appearance can be overridden. If the flag is true, this node's appearance may be overridden by an AlternateAppearance leaf node, regardless of the value of theALLOW_APPEARANCE_WRITE
capability bit. The default value is false. See Section 6.15, "AlternateAppearance Node."
6.2.1
The OrientedShape3D leaf node is a Shape3D node that is oriented along a specified axis or about a specified point. It defines an alignment mode and a rotation point or axis. This will cause the local +z axis of the object to point at the viewer's eye position. This is done regardless of the transforms above this OrientedShape3D node in the scene graph.OrientedShape3D Node The OrientedShape3D node is similar in functionality to the Billboard behavior (see Section 10.8, "Billboard Behavior"), but OrientedShape3D nodes will orient themselves correctly for each view, and they can be used within a SharedGroup.
Constants
The OrientedShape3D node object defines the following flags:public static final int ALLOW_MODE_READ public static final int ALLOW_MODE_WRITE public static final int ALLOW_AXIS_READ public static final int ALLOW_AXIS_WRITE public static final int ALLOW_POINT_READ public static final int ALLOW_POINT_WRITEThese flags, when enabled using thesetCapability
method, allow reading and writing of the alignment mode, alignment axis, and rotation point information, respectively. These capability flags are enforced only when the node is part of a live or compiled scene graph.public static final int ROTATE_ABOUT_AXISSpecifies that rotation should be about the specified axis.public static final int ROTATE_ABOUT_POINTSpecifies that rotation should be about the specified point and that the children's y-axis should match the view object's y-axis.
Constructors
The OrientedShape3D node specifies the following constructors:public OrientedShape3D()Constructs an OrientedShape3D node with default parameters. The default values are as follows:
Parameter Default Value alignmentMode ROTATE_ABOUT_AXIS alignmentAxis y-axis (0,1,0) rotationPoint (0,0,1)
public OrientedShape3D(Geometry geometry, Appearance appearance, int mode, Vector3f axis) public OrientedShape3D(Geometry geometry, Appearance appearance, int mode, Point3f point)The first constructor constructs an OrientedShape3D node with the specified geometry component, appearance component, mode, and axis. The second constructor constructs an OrientedShape3D node with the specified geometry component, appearance component, mode, and rotation point.public void setAlignmentMode(int mode) public int getAlignmentMode()These methods set and retrieve the alignment mode. The alignment mode is one ofROTATE_ABOUT_AXIS
orROTATE_ABOUT_POINT
.public void setAlignmentAxis(Vector3f axis) public void setAlignmentAxis(float x, float y, float z) public void getAlignmentAxis(Vector3f axis)These methods set and retrieve the alignment axis. This is the ray about which this OrientedShape3D rotates when the mode isROTATE_ABOUT_AXIS
.public void setRotationPoint(Point3f point) public void setRotationPoint(float x, float y, float z) public void getRotationPoint(Point3f point)These methods set and retrieve the rotation point. This is the point about which the OrientedShape3D rotates when the mode isROTATE_ABOUT_POINT
.
6.3
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.BoundingLeaf Node
Constants
The BoundingLeaf node object defines the following flags:public static final int ALLOW_REGION_READ public static final int ALLOW_REGION_WRITEThese flags, when enabled using thesetCapability
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.public void setRegion(Bounds region) public Bounds getRegion()These methods set and retrieve the BoundingLeaf node's bounding region.
6.4
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.Background Node
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_WRITEThese flags, when enabled using thesetCapability
method, allow an application to invoke methods that respectively read and write the application region, the image, the color, and the background geometry. These capability flags are enforced only when the node is part of a live or compiled scene graph.
Constructors
The Background node object defines the following constructors:public Background()Constructs a Background leaf node with default parameters:
Parameter Default Value color black (0,0,0) image null geometry null applicationBounds null applicationBoundingLeaf null
public Background(Color3f color) public Background(float r, float g, float b) public Background(ImageComponent2D image) public Background(Branchgroup branch)The first two forms construct a Background leaf node with the specified color. The second form constructs a Background leaf node with the specified 2D image. The final form constructs a Background leaf node with the specified geometry.
Methods
The Background node object defines the following methods:public void getColor(Color3f color) public void setColor(Color3f color) public void setColor(float r, float g, float b)These three methods access or modify the background color.public ImageComponent2D getImage() public void setImage(ImageComponent2D image)These two methods access or modify the background image. If the image is notnull
then it is used in place of the color.public void setGeometry(BranchGroup branch) public BranchGroup getGeometry()These two methods access or modify the Background geometry. ThesetGeometry
method sets the background geometry to the specified BranchGroup node. If non-null, this background geometry is drawn on top of the background color or image using a projection matrix that essentially puts the geometry at infinity. The geometry should be pretessellated onto a unit sphere.public void setApplicationBounds(Bounds region) public Bounds getApplicationBounds()These two methods access or modify the Background node's application bounds. This bounds is used as the application region when the application bounding leaf is set tonull
. ThegetApplicationBounds
method returns a copy of the associated bounds.public void setApplicationBoundingLeaf(BoundingLeaf region) public BoundingLeaf getApplicationBoundingLeaf()These two methods access or modify the Background node's application bounding leaf. When set to a value other thannull
, this bounding leaf overrides the application bounds object and is used as the application region.
6.5
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.Clip Node 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_WRITEThese flags, when enabled using thesetCapability
method, allow an application to invoke methods that respectively read and write the application region and the back distance. These capability flags are enforced only when the node is part of a live or compiled scene graph.
Constructors
The Clip node object defines the following constructors:public Clip()Constructs a Clip node with default parameters:
Parameter Default Value backDistance 100 applicationBounds null applicationBoundingLeaf null
public Clip(double backDistance)Constructs a Clip leaf node with the rear clip plane at the specified distance, in the local coordinate system, from the eye.
Methods
The Clip node object defines the following methods:public void setBackDistance(double backDistance) public double getBackDistance()These methods access or modify the back-clipping distances in the Clip node. This distance specifies the back-clipping plane in the local coordinate system of the node. There are several considerations that need to be taken into account when choosing values for the front and back clip distances. See Section 9.7.3, "Projection and Clip Parameters," for details.public void setApplicationBounds(Bounds region) public Bounds getApplicationBounds()These two methods access or modify the Clip node's application bounds. This bounds is used as the application region when the application bounding leaf is set tonull
. ThegetApplicationBounds
method returns a copy of the associated bounds.public void setApplicationBoundingLeaf(BoundingLeaf region) public BoundingLeaf getApplicationBoundingLeaf()These two methods access or modify the Clip node's application bounding leaf. When set to a value other thannull
, this bounding leaf overrides the application bounds object and is used as the application region.
6.6
The ModelClip leaf node defines a set of six arbitrary clipping planes in the virtual universe. The planes are specified in the local coordinate system of this node, and may be individually enabled or disabled. This node also specifies a region of influence in which this set of planes is active.ModelClip Node The individual planes specify a half space defined by the following equation:
The parameters are passed in the x, y, z, and w fields, respectively, of a Vector4d object. The intersection of the set of half spaces corresponding to the enabled planes in this ModelClip node defines a region in which points are accepted. Points in this acceptance region will be rendered (subject to view clipping and other attributes). Points that are not in the acceptance region will not be rendered.
- where A, B, C, and D are the parameters that specify the plane.
Constants
The ModelClip node object defines the following flags:public static final int ALLOW_INFLUENCING_BOUNDS_READ public static final int ALLOW_INFLUENCING_BOUNDS_WRITE public static final int ALLOW_PLANE_READ public static final int ALLOW_PLANE_WRITE public static final int ALLOW_ENABLE_READ public static final int ALLOW_ENABLE_WRITE public static final int ALLOW_SCOPE_READ public static final int ALLOW_SCOPE_WRITEThese flags, when enabled using thesetCapability
method, allow an application to invoke methods that respectively read and write the influencing bounds and bounding leaf, planes, enable, and scope flags. These capability flags are enforced only when the node is part of a live or compiled scene graph.
Constructors
The ModelClip node object defines the following constructors:public ModelClip()Constructs a ModelClip node with default parameters:
public ModelClip(Vector4d[] planes, boolean[] enables) public ModelClip(Vector4d[] planes)These constructors construct a new ModelClip node. The first constructor uses the specified planes and enable flags. The second constructor uses the specified parameters and uses defaults for those parameters not specified. Default values are described above.
Methods
The ModelClip node object defines the following methods:public void setInfluencingBounds(Bounds region) public Bounds getInfluencingBounds()These methods access or modify the ModelClip node's influencing region. This is used when the influencing bounding leaf is set to null.public void setInfluencingBoundingLeaf(BoundingLeaf region) public BoundingLeaf getInfluencingBoundingLeaf()These methods access or modify the ModelClip node's influencing region. When set to a value other than null, this overrides the influencing bounds object.public void setPlanes(Vector4d[] planes) public void setPlane(int planeNum, Vector4d plane) public void getPlanes(Vector4d[] planes) public void getPlane(int planeNum, Vector4d plane)These methods access or modify the specified ModelClip node's clipping planes. The planes are an array of six model clipping planes. The set methods copy the individual planes into this node. The get methods copy the individual planes into the specified planes, which must be allocated by the caller.public void setEnables(boolean[] enables) public void setEnable(int planeNum, boolean enable) public void getEnables(boolean[] enables) public boolean getEnable(int planeNum)These methods access or modify the specified ModelClip node's enable flag. The enables are an array of six booleans.public void setScope(Group scope, int index)This method replaces the node at the specified index in this ModelClip node's list of scopes with the specified Group node. By default, ModelClip nodes are scoped only by their influencing bounds. This allows them to be scoped further by a list of nodes in the hierarchy.public Group getScope(int index)This method retrieves the Group node at the specified index from this ModelClip node's list of scopes.public void insertScope(Group scope, int index)This method inserts the specified Group node into this ModelClip node's list of scopes at the specified index. By default, ModelClip nodes are scoped only by their influencing bounds. This allows them to be scoped further by a list of nodes in the hierarchy.public void removeScope(int index)This method removes the node at the specified index from this ModelClip node's list of scopes. If this operation causes the list of scopes to become empty, this ModelClip will have universe scope; all nodes within the region of influence will be affected by this ModelClip node.public Enumeration getAllScopes()This method returns an enumeration of this ModelClip node's list of scopes.public void addScope(Group scope)This method appends the specified Group node to this ModelClip node's list of scopes. By default, ModelClip nodes are scoped only by their influencing bounds. This allows them to be scoped further by a list of nodes in the hierarchy.public int numScopes()This method returns the number of nodes in this ModelClip node's list of scopes. If this number is 0, the list of scopes is empty and this ModelClip node has universe scope: All nodes within the region of influence are affected by this ModelClip node.
6.7
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.Fog Node
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_WRITEThese flags, when enabled using thesetCapability
method, allow an application to invoke methods that respectively read and write the region of influence, read and write color, and read and write scope information. These capability flags are enforced only when the node is part of a live or compiled scene graph.
Constructors
The Fog node object defines the following constructors:public Fog()Constructs a Fog node with default parameters:
Parameter Default Value color black (0,0,0) scope empty (universe scope) influencingBounds null influencingBoundingLeaf null
public Fog(float r, float g, float b) public Fog(Color3f color)These constructors construct a new Fog node. The first constructor uses default values for all parameters. The second constructor uses the specified parameters and uses defaults for those parameters not specified. Default values are described above.
Methods
The Fog node object defines the following methods:public void setColor(float r, float g, float b) public void setColor(Color3f color) public void getColor(Color3f color)These three methods access or modify the Fog node's color. An application will typically set this to the same value as the background color.public void setInfluencingBounds(Bounds region) public Bounds getInfluencingBounds()These methods access or modify the Fog node's influencing bounds. This bounds is used as the region of influence when the influencing bounding leaf is set tonull
. The Fog node operates on all objects that intersect its region of influence. ThegetInfluencingBounds
method returns a copy of the associated bounds.public void setInfluencingBoundingLeaf(BoundingLeaf region) public BoundingLeaf getInfluencingBoundingLeaf()These methods access or modify the Fog node's influencing bounding leaf. When set to a value other thannull
, this overrides the influencing bounds object, and it is used as the region of influence.public void setScope(Group scope, int index) public Group getScope(int index) public void addScope(Group scope) public void insertScope(Group scope, int index) public void removeScope(int index) public int numScopes() public Enumeration getAllScopes()These methods access or modify the Fog node's hierarchical scope. By default, Fog nodes are scoped only by their regions of influence. These methods allow them to be scoped further by a Group node in the hierarchy. The hierarchical scoping of a Fog node cannot be accessed or modified if the node is part of a live or compiled scene graph.
6.7.1
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."ExponentialFog Node
Constants
The ExponentialFog node object defines the following flags:public static final int ALLOW_DENSITY_READ public static final int ALLOW_DENSITY_WRITEThese flags, when enabled using thesetCapability
method, allow an application to invoke methods that respectively read and write the density values. These capability flags are enforced only when the node is part of a live or compiled scene graph.
Constructors
The ExponentialFog node object defines the following constructors:public ExponentialFog()Constructs an ExponentialFog node with default parameters:
Parameter Default Value density 1.0
public ExponentialFog(float r, float g, float b) public ExponentialFog(Color3f color) public ExponentialFog(float r, float g, float b, float density) public ExponentialFog(Color3f color, float density)Each of these constructors creates a new ExponentialFog node using the specified parameters and use defaults for those parameters not specified.
Methods
The ExponentialFog node object defines the following methods:public void setDensity(float density) public float getDensity()These two methods access or modify the density in the ExponentialFog object.
6.7.2
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.LinearFog Node 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_WRITEThese flags, when enabled using thesetCapability
method, allow an application to invoke methods that respectively read and write the distance values. These capability flags are enforced only when the node is part of a live or compiled scene graph.
Constructors
The LinearFog node object defines the following constructors:public LinearFog()Constructs a LinearFog node with default parameters:
Parameter Default Value frontDistance 0.1 backDistance 1.0
public LinearFog(float r, float g, float b) public LinearFog(Color3f color) public LinearFog(float r, float g, float b, double frontDistance, double backDistance) public LinearFog(Color3f color, double frontDistance, double backDistance)These constructors construct a new LinearFog node with the specified parameters and use defaults for those parameters not specified.
Methods
The LinearFog node object defines the following methods:public void setFrontDistance(float frontDistance) public float getFrontDistance() public void setBackDistance(float backDistance) public float getBackDistance()These four methods access or modify the front and back distances in the LinearFog object. The front distance is the distance at which the fog starts obscuring objects; the back distance is the distance at which the fog fully obscures objects. Objects drawn closer than the front fog distance are not affected by fog. Objects drawn farther than the back fog distance are drawn entirely in the fog color.
6.8
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.Light Node 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_WRITEThese flags, when enabled using thesetCapability
method, allow reading and writing of the region of influence, the state, the color, and the scope information, respectively. These capability flags are enforced only when the node is part of a live or compiled scene graph.
Constructors
The Light node object defines the following constructors:public Light()Constructs and initializes a light with the following default values:
Parameter Default Value enable true color white (1,1,1) scope empty (universe scope) influencingBounds null influencingBoundingLeaf null
public Light(Color3f color) public Light(boolean lightOn, Color3f color)These two constructors construct and initialize a light with the specified values.
Methods
The Light node object defines the following methods:public void setEnable(boolean state) public boolean getEnable()These methods access or modify the state of this light (that is, whether the light is enabled).public void setColor(Color3f color) public void getColor(Color3f color)These methods access or modify the current color of this light.public setInfluencingBounds(Bounds region) public Bounds getInfluencingBounds()These methods access or modify the Light node's influencing bounds. This bounds is used as the region of influence when the influencing bounding leaf is set tonull
. The Light node operates on all objects that intersect its region of influence. ThegetInfluencingBounds
method returns a copy of the associated bounds.public setInfluencingBoundingLeaf(BoundingLeaf region) public BoundingLeaf getInfluencingBoundingLeaf()These methods access or modify the Light node's influencing bounding leaf. A value other thannull
overrides the influencing bounds object and it is used as the region of influence.public void setScope(Group scope, int index) public Group getScope(int index) public void addScope(Group scope) public void insertScope(Group scope, int index) public void removeScope(int index) public int numScopes() public Enumeration getAllScopes()These methods access or modify the Light node's hierarchical scope. By default, Light nodes are scoped only by their regions of influence bounds. These methods allow them to be scoped further by a node in the hierarchy.
6.8.1
An AmbientLight node defines an ambient light source. It has the same attributes as the abstract Light node.AmbientLight 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. Thecolor
parameter is the color of the light source. ThelightOn
flag indicates whether this light is on or off.
6.8.2
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.DirectionalLight Node
Constants
The DirectionalLight node object defines the following flags:public static final int ALLOW_DIRECTION_READ public static final int ALLOW_DIRECTION_WRITEThese flags, when enabled using thesetCapability
method, allow an application to invoke methods that respectively read or write the associated direction. These capability flags are enforced only when the node is part of a live or compiled scene graph.The DirectionalLight's direction vector is defined in the local coordinate system of the node.
Constructors
The DirectionalLight node object defines the following constructors:public DirectionalLight()Constructs and initializes a directional light with default parameters:
Parameter Default Value direction (0,0,-1)
public DirectionalLight(Color3f color, Vector3f direction) public DirectionalLight(boolean LightOn, Color3f color, Vector3f direction)These constructors construct and initialize a directional light with the parameters provided.
Methods
The DirectionalLight node object defines the following methods:public void setDirection(Vector3f direction) public void setDirection(float x, float y, float z) public void getDirection(Vector3f direction)These methods access or modify the light's current direction.
6.8.3
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.PointLight Node 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_WRITEThese flags, when enabled using thesetCapability
method, allow an application to invoke methods that respectively read position, write position, read attenuation parameters, and write attenuation parameters. These capability flags are enforced only when the node is part of a live or compiled scene graph.
Constructors
The PointLight Node defines the following constructors:public PointLight()Constructs and initializes a point light source with the following default parameters:
Parameter Default Value position (0,0,0) attenuation (1,0,0)
public PointLight(Color3f color, Point3f position, Point3f attenuation) public PointLight(boolean lightOn, Color3f color, Point3f position, Point3f attenuation)These constructors construct and initialize a point light with the specified parameters.
Methods
The PointLight node object defines the following methods:public void setPosition(Point3f position) public void setPosition(float x, float y, float z) public void getPosition(Point3f position)These methods access or modify the point light's current position.public void setAttenuation(Point3f attenuation) public void setAttenuation(float constant, float linear, float quadratic) public void getAttenuation(Point3f attenuation)These methods access or modify the point light's current attenuation. The values presented to the methods specify the coefficients of the attenuation polynomial, withconstant
providing the constant term,linear
providing the linear coefficient, andquadratic
providing the quadratic coefficient.
6.8.4
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.SpotLight Node
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_WRITEThese flags, when enabled using thesetCapability
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.
Constructors
The SpotLight node object defines the following constructors:public SpotLight()Constructs and initializes a new spotlight with the default values:
Parameter Default Value direction (0,0 -1) spreadAngle radians concentration 0.0
public SpotLight(Color3f color, Point3f position, Point3f attenuation, Vector3f direction, float spreadAngle, float concentration) public SpotLight(boolean lightOn, Color3f color, Point3f position, Point3f attenuation, Vector3f direction, float spreadAngle, float concentration)These construct and initialize a new spotlight with the parameters specified.
Methods
The SpotLight node object defines the following methods:public void setSpreadAngle(float spreadAngle) public float getSpreadAngle()These methods access or modify the spread angle, in radians, of this spotlight.public void setConcentration(float concentration) public float getConcentration()These methods access or modify the concentration of this spotlight.public void setDirection(float x, float y, float z) public void setDirection(Vector3f direction) public void getDirection(Vector3f direction)These methods access or modify the direction of this spotlight.
6.9
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.Sound Node
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_READThese flags, when enabled using thesetCapability
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_FILTERThis constant defines a floating point value that denotes that no filter value is set. Filters are described in Section 6.9.3, "ConeSound Node."public static final int DURATION_UNKNOWNThis constant denotes that the sound's duration could not be calculated; a fallback forgetDuration
of a noncached sound.
Constructors
The Sound node object defines the following constructors:public Sound()Constructs and initializes a new Sound node object that includes the following defaults for its fields:
public Sound(MediaContainer soundData, float initialGain)Constructs and initializes a new Sound node object using the provided data and gain parameter values and defaults for all other fields. This constructor implicitly loads the sound data associated with this node if the implementation uses sound caching.public Sound(MediaContainer soundData, float initialGain, int loopCount, boolean release, boolean continuous, boolean enable, Bounds region, float priority)Constructs and initializes a new Sound node object using the provided parameter values.
Methods
The Sound node object defines the following methods:public void setSoundData(MediaContainer soundData) public MediaContainer getSoundData()These methods provide a way to associate different types of audio data with a Sound node. This data can be cached (buffered) or noncached (unbuffered or streaming). If the AudioDevice has been attached to the PhysicalEnvironment, the sound data is made ready to begin playing. Certain functionality cannot be applied to true streaming sound data: sound duration is unknown, looping is disabled, and the sound cannot be restarted. Furthermore, depending on the implementation of the AudioDevice used, streaming, noncached data may not be fully spatialized.public void setInitialGain(float amplitude) public float getInitialGain()This gain is a scale factor that is applied to the sound data associated with this sound source to increase or decrease its overall amplitude.public void setLoop(int loopCount) public int getLoop()Data for nonstreaming sound (such as a sound sample) can contain two loop points marking a section of the data that is to be looped a specific number of times. Thus, sound data can be divided into three segments: the attack (before the begin loop point), the sustain (between the begin and end loop points), and the release (after the end loop point). If there are no loop begin and end points defined as part of the sound data (say for Java Media Player types that do not contain sound samples), then the begin loop point is set at the beginning of the sound data, and the end loop point at the end of the sound data. If this is the case, looping the sound means repeating the whole sound. However, these begin and end loop points can be placed anywhere within the sound data, allowing a portion in the middle of the sound to be looped.public void setReleaseEnable(boolean state) public boolean getReleaseEnable()When a sound is disabled, its playback would normally stop immediately no matter what part of the sound data was currently being played. By setting the Release flag totrue
for nodes with nonstreaming sound data, the sound is allowed to play from its current position in the sound data to the end of the data (without repeats), thus playing the release portion of the sound before stopping.public void setContinuousEnable(boolean state) public boolean getContinuousEnable()For some applications, it's useful to turn a sound source "off" but to continue playing the sound "silently" so that when it is turned back "on," the sound picks up playing in the same location (over time) it would have played if the sound had never been disabled (turned off). Setting the continuous flag totrue
causes the sound renderer to keep track of where (over time) the sound would be playing even when the sound is disabled.public setSchedulingBounds(Bounds region) public Bounds getSchedulingBounds()These two methods access or modify the Sound node's scheduling bounds. This bounds is used as the scheduling region when the scheduling bounding leaf is set tonull
. A sound is scheduled for activation when its scheduling region intersects the ViewPlatform's activation volume. ThegetSchedulingBounds
method returns a copy of the associated bounds.public void setSchedulingBoundingLeaf(BoundingLeaf region) public BoundingLeaf getSchedulingBoundingLeaf()These two methods access or modify the Sound node's scheduling bounding leaf. When set to a value other thannull
, this bounding leaf overrides the scheduling bounds object and is used as the scheduling region.public void setPriority(float ranking) public float getPriority()These methods access or modify the Sound node's priority, which is used to rank concurrently playing sounds in order of importance during playback. When more sounds are started than the AudioDevice can handle, the Sound node with the lowest priority ranking is deactivated. If a sound is deactivated (due to a sound with a higher priority being started), it is automatically reactivated when resources become available (for example, when a sound with a higher priority finishes playing) or when the ordering of sound nodes is changed due to a change in a Sound node's priority.Methods to determine what audio output resources are required for playback of a Sound node on a particular AudioDevice and to determine the currently available audio output resources are described in Chapter 12, "Audio Devices."
public void setEnable(boolean state) public boolean getEnable()These two methods access or modify the playing state of this sound (that is, whether the sound is enabled). When enabled, the sound source is started and thus can potentially be heard, depending on its activation state, gain control parameters, continuation state, and spatialization parameters. If the continuous state istrue
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 callingsetEnable
with a value oftrue
.public boolean isReady()This method retrieves the sound's "ready" status. If this sound is fully prepared for playing (either audibly or silently) on all initialized audio devices, this method returnstrue
. Sound data associated with a Sound node, either during construction (when the MediaContainer is passed into the constructor as a parameter) or by callingsetSoundData()
, 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.
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,
- There is an initialized AudioDevice associated with the PhysicalEnvironment.
isReady()
, returnstrue
when the sound is fully preprocessed so that it is playable (audibly if active, silently if not active).public boolean isPlaying()A sound source will not be heard unless it is both enabled (turned on) and activated. If this sound is audibly playing on any initialized audio device, this method will return a status oftrue
.When the sound finishes playing its sound data (including all loops), it is implicitly disabled.
public boolean isPlayingSilently()This method returns the sound's silent status. If this sound is silently playing on any initialized audio device, this method returnstrue
.public long getDuration()This method returns the length of time (in milliseconds) that the sound media associated with the sound source could run (including the number of times its loop section is repeated) if it plays to completion. If the sound media type is streaming or if the sound is looped indefinitely, a value of -1 (implying infinite length) is returned.public int getNumberOfChannelsUsed()When a sound is started it could use more than one channel on the selected AudioDevice it is to be played on. This method retrieves the number of channels that are being used to render this sound on the audio device associated with the VirtualUniverse's primary view. The method returns 0 if sound is not playing.
6.9.1
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.BackgroundSound Node
Constructors
The BackgroundSound node specifies the following constructor:public BackgroundSound()Constructs a BackgroundSound node object using the default parameters for Sound nodes.public BackgroundSound(MediaContainer soundData, float initialGain) public BackgroundSound(MediaContainer soundData, float initialGain, int loopCount, boolean release, boolean continuous, boolean enable, Bounds region, float priority)The first constructor constructs a new BackgroundSound node using only the provided parameter values for the sound data and initial gain. The second constructor uses the provided parameter values for the sound data, initial gain, the number of times the loop is looped, a flag denoting whether the sound data is played to the end, a flag denoting whether the sound plays silently when disabled, a flag denoting whether sound is switched on or off, the sound activation region, and a priority value denoting the playback priority ranking.
6.9.2
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.PointSound 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_WRITEThese flags, when enabled using thesetCapability
method, allow an application to invoke methods that respectively read and write the position and the distance gain array. These capability flags are enforced only when the node is part of a live or compiled scene graph.
Constructors
The PointSound node object defines the following constructors:public PointSound()Constructs a PointSound node object that includes the defaults for a Sound object plus the following defaults for its own fields:
Parameter Default Value position (0.0, 0.0, 0.0) distanceGain null (no attenuation performed)
public PointSound(MediaContainer soundData, float initialGain, Point3f position) public PointSound(MediaContainer soundData, float initialGain, float posX, float posY, float posZ)Both of these constructors construct a PointSound node object using only the provided parameter values for sound data, sample gain, and position. The remaining fields are set to the default values specified earlier. The first form uses vectors as input for its position; the second form uses individual float parameters for the elements of the position vector.public PointSound(MediaContainer soundData, float initialGain, int loopCount, boolean release, boolean continuous, boolean enable, Bounds region, float priority, Point3f position, Point2f distanceGain[]) public PointSound(MediaContainer soundData, float initialGain, int loopCount, boolean release, boolean continuous, boolean enable, Bounds region, float priority, float posX, float posY, float posZ, Point2f distanceGain[]) public PointSound(MediaContainer soundData, float initialGain, int loopCount, boolean release, boolean continuous, boolean enable, Bounds region, float priority, Point3f position, float attenuationDistance[], float attenuationGain[]) public PointSound(MediaContainer soundData, float initialGain, int loopCount, boolean release, boolean continuous, boolean enable, Bounds region, float priority, float posX, float posY, float posZ, float attenuationDistance[], float attenuationGain[])These four constructors construct a PointSound node object using the provided parameter values. The first and third forms use points as input for the position. The second and fourth forms use individual float parameters for the elements of the position. The first and second forms accept an array of Point2f for the distance attenuation values where each pair in the array contains a distance and a gain scale factor. The third and fourth forms accept separate arrays for the components of distance attenuation, namely, the distance and gain scale factors. See the description for thesetDistanceGain
method, below, for details on how the separate arrays are interpreted.
Methods
The PointSound node object defines the following methods:public void setPosition(Point3f position) public void setPosition(float x, float y, float z) public void getPosition(Point3f position)These methods set and retrieve the position in 3D space from which the sound radiates.public void setDistanceGain(Point2f attenuation[]) public void setDistanceGain(float distance[], float gain[]) public int getDistanceGainLength() public void getDistanceGain(Point2f attenuation[]) public void getDistanceGain(float distance[], float gain[])These methods set and retrieve the sound's distance attenuation. If this is not set, no distance gain attenuation is performed (equivalent to using a gain scale factor of 1.0 for all distances). See Figure 6-2. Gain scale factors are associated with distances from the listener to the sound source via an array of distance and gain scale factor pairs. The gain scale factor applied to the sound source is determined by finding the range of valuesdistance[i]
anddistance[i+1]
that includes the current distance from the listener to the sound source then linearly interpolating the corresponding valuesgain[i]
andgain[i+1]
by the same amount.
Figure 6-2 PointSound Distance Gain Attenuation
Figure 6-2 shows a graphical representation of a distance gain attenuation list. The values given for distance/gain pairs would be
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.
- ( (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) )
6.9.3
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.ConeSound Node Figure 6-3 shows an approximation of angular attenuation (disregarding distance attenuation).
Figure 6-3 ConeSound
Constants
The ConeSound object contains the following flags:public static final int ALLOW_DIRECTION_READ public static final int ALLOW_DIRECTION_WRITE public static final int ALLOW_ANGULAR_ATTENUATION_READ public static final int ALLOW_ANGULAR_ATTENUATION_WRITEThese flags, when enabled using thesetCapability
method, allow an application to invoke methods that respectively read and write the direction and the angular attenuation array. These capability flags are enforced only when the node is part of a live or compiled scene graph.
Constructors
The ConeSound node object defines the following constructors:public ConeSound()Constructs a ConeSound node object that includes the defaults for a PointSound object plus the following defaults for its own fields:
Parameter Default Value direction (0.0, 0.0, 1.0) angularAttenuation ((0.0, 1.0, NO_FILTER),(/2, 0.0, NO_FILTER))
public ConeSound(MediaContainer soundData, float initialGain, Point3f position, Vector3f direction) public ConeSound(MediaContainer soundData, float initialGain, float posX, float posY, float posZ, float dirX, float dirY, float dirZ)Both of these constructors construct a ConeSound node object using only the provided parameter values for sound, overall initial gain, position, and direction. The remaining fields are set to the default values listed earlier. The first form uses points as input for its position and direction. The second form uses individual float parameters for the elements of the position and direction vectors.public ConeSound(MediaContainer soundData, float initialGain, int loopCount, boolean release, boolean continuous, boolean enable, Bounds region, float priority, Point3f position, Point2f frontDistanceAttenuation[], Point2f backDistanceAttenuation[], Vector3f direction) public ConeSound(MediaContainer soundData, float initialGain, int loopCount, boolean release, boolean continuous, boolean enable, Bounds region, float priority, float posX, float posY, float posZ, float frontDistance[], float frontDistanceGain[], float backDistance[], float backDistanceGain[], float dirX, float dirY, float dirZ)These constructors construct a ConeSound node object using the provided parameter values. The first form uses points or vectors as input for its position, direction, and front/back distance attenuation arrays. The second form uses individual float parameters for the elements of the position, direction, and two distance attenuation arrays.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 sphericaldistanceAttenuation
array, andangularAttenuation
array. The second form uses individual float parameters for the elements of the position, direction,distanceAttenuation
array, andangularAttenuation
array.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.
Methods
The ConeSound node object defines the following methods:public void setDistanceGain(Point2f frontAttenuation[], Point2f backAttenuation[]) public void setDistanceGain(float frontDistance[], float frontGain[], float backDistance[], float backGain[]) public void setBackDistanceGain(Point2f attenuation[]) public void setBackDistanceGain(float distance[], float gain[]) public void getDistanceGain(Point2f frontAttenuation[], Point2f backAttenuation[]) public void getDistanceGain(float frontDistance[], float frontGain[], float backDistance[], float backGain[])These methods set and retrieve the ConeSound's two distance attenuation arrays. If these are not set, no distance gain attenuation is performed (equivalent to using a distance gain of 1.0 for all distances). If only one distance attenuation array is set, spherical attenuation is assumed (see Figure 6-4). If both a front and back distance attenuation are set, elliptical attenuation regions are defined (see Figure 6-5). Use the PointSoundsetDistanceGain
method to set the front distance attenuation array separately from the back distance attenuation array.
Figure 6-4 ConeSound with a Single Distance Gain Attenuation Array
Figure 6-5 ConeSound with Two Distance Gain Attenuation Arrays
Gain scale factors are associated with distances from the listener to the sound source via an array of distance and gain scale factor pairs (see Figure 6-2). The gain scale factor applied to the sound source is the linear interpolated gain value within the distance value range that includes the current distance from the listener to the sound source.
public void setDirection(Vector3f direction) public void setDirection(float x, float y, float z) public void getDirection(Vector3f direction)This value is the sound source's direction vector. It is the axis from which angular distance is measured.public void setAngularAttenuation(Point2f attenuation[]) public void setAngularAttenuation(Point3f attenuation[]) public void setAngularAttenuation(float angle[], float angularGain[], float frequencyCutoff[]) public int getAngularAttenuationLength() public void getAngularAttenuation(Point3f attenuation[]) public void getAngularAttenuation(float angle[], float angularGain[], float frequencyCutoff[])These methods set and retrieve the sound's angular gain and filter attenuation arrays. If these are not set, no angular gain attenuation or filtering is performed (equivalent to using an angular gain scale factor of 1.0 and an angular filter ofNO_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.Figure 6-3 shows an example of an angular attenuation defining four points of the form (radiant distance, gain scale factor, cutoff filter frequency):
- ( (0.12, 0.8, NO_FILTER), (0.26, 0.6, 18000.0), (0.32, 0.4, 15000.0),
(0.40, 0.2, 11000.0) )6.10
The Soundscape leaf node defines the attributes that characterize the listener's aural environment. This node defines an application region and an associated aural attribute component object that controls reverberation and atmospheric properties that affect sound source rendering. (Aural attributes are described in Section 8.1.17, "AuralAttributes Object.") Multiple Soundscape nodes can be included in a single scene graph.Soundscape Node It will be common for multiple Soundscape regions to be contained within a scene graph. Figure 6-6 shows application regions for two Soundscape nodes: a region with a large open area on the right, and a smaller, more constricted, less reverberant area on the left.
Figure 6-6 Multiple Soundscape Application Regions
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_WRITEThese flags, when enabled using thesetCapability
method, allow an application to invoke methods that respectively read and write the application region and the aural attributes. These capability flags are enforced only when the node is part of a live or compiled scene graph.
Constructors
The Soundscape node object defines the following constructors:public Soundscape()Constructs a Soundscape node object that includes the following defaults for its elements:
Parameter Default Value applicationBounds null (no active region) auralAttributes null (uses default aural attributes)
public Soundscape(Bounds region, AuralAttributes attributes)This method constructs a Soundscape node object using the specified application region and aural attributes.
Methods
The Soundscape node object defines the following methods:public void setApplicationBounds(Bounds region) public Bounds getApplicationBounds()These two methods access or modify the Soundscape node's application bounds. This bounds is used as the application region when the application bounding leaf is set tonull
. The aural attributes associated with this Soundscape are used to render the active sounds when this application region intersects the ViewPlatform's activation volume. ThegetApplicationBounds
method returns a copy of the associated bounds.public void setApplicationBoundingLeaf(BoundingLeaf region) public BoundingLeaf getApplicationBoundingLeaf()These two methods access or modify the Soundscape node's application bounding leaf. When set to a value other thannull
, this bounding leaf overrides the application bounds object and is used as the application region.public void setAuralAttributes(AuralAttributes attributes) public AuralAttributes getAuralAttributes()These two methods access or modify the aural attributes of this Soundscape. Setting it tonull
results in default attribute use.
6.11
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.ViewPlatform Node
Constants
The ViewPlatform node object defines the following flags:public static final int ALLOW_POLICY_READ public static final int ALLOW_POLICY_WRITEThese flags, when enabled using thesetCapability
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.public ViewPlatform()Constructs and initializes a new ViewPlatform leaf node object with default parameters:
Parameter Default Value viewAttachPolicy View.NOMINAL_HEAD activationRadius 62
Methods
The ViewPlatform node object defines the following methods:public void setActivationRadius(float activationRadius) public float getActivationRadius()The activation radius defines an activation volume surrounding the center of the ViewPlatform. This activation volume intersects with the scheduling regions and application regions of other leaf node objects to determine which of those objects may affect rendering.Behavior objects act somewhat differently. Those Behavior objects with scheduling regions that intersect a ViewPlatform's activation volume become candidates for scheduling. Effectively, a ViewPlatform's activation volume becomes an additional qualifier on the scheduling of all Behavior objects. See Chapter 10, "Behaviors and Interpolators," for more details.
public void setViewAttachPolicy(int policy) public int getViewAttachPolicy()The view attach policy determines how Java 3D places the user's virtual eye point as a function of head position. See Section 9.4.3, "View Attach Policy," for details.
6.12
The Behavior leaf node allows an application to manipulate a scene graph at run time. Behavior is an abstract class that defines properties common to all Behavior objects in Java 3D. There are several predefined behaviors that are subclasses of Behavior. Additionally, a Behavior leaf node may be subclassed by the user. Behaviors are described in Chapter 10, "Behaviors and Interpolators."Behavior Node
6.13
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.Morph Node
Constants
The Morph node specifies the following flags:public static final int ALLOW_GEOMETRY_ARRAY_READ public static final int ALLOW_GEOMETRY_ARRAY_WRITE public static final int ALLOW_APPEARANCE_READ public static final int ALLOW_APPEARANCE_WRITE public static final int ALLOW_WEIGHTS_READ public static final int ALLOW_WEIGHTS_WRITE public static final int ALLOW_COLLISION_BOUNDS_READ public static final int ALLOW_COLLISION_BOUNDS_WRITE public static final int ALLOW_APPEARANCE_OVERRIDE_READ public static final int ALLOW_APPEARANCE_OVERRIDE_WRITEThese flags, when enabled using thesetCapability
method, allow an application to invoke methods that respectively read and write the node's array of GeometryArray objects, appearance, weights, collision Bounds, and appearance override enable components.
Constructors
The Morph node specifies the following constructors:public Morph(GeometryArray geometryArrays[])Constructs and initializes a new Morph leaf node with the specified array of GeometryArray objects. Default values are used for all other parameters:
Parameter Default Value appearance null weights [1, 0, 0, 0, ...] collisionBounds null appearanceOverrideEnable false
A null appearance object specifies that default values are used for all appearance attributes.
public Morph(GeometryArray geometryArrays[], Appearance appearance)Constructs and initializes a new Morph leaf node with the specified array of GeometryArray objects and the specified Appearance object. The length of thegeometryArrays
parameter determines the number of weighted geometry arrays in this Morph node. IfgeometryArrays
isnull
, then aNullPointerException
is thrown. If the Appearance component isnull
, then default values are used for all appearance attributes.
Methods
The Morph node specifies the following methods:public void setGeometryArrays(GeometryArray geometryArrays[])This method sets the array of GeometryArray objects in the Morph node. Each GeometryArray component specifies colors, normals, and texture coordinates. The length of thegeometryArrays
parameter must be equal to the length of the array with which this Morph node was created; otherwise, anIllegal-ArgumentException
is thrown.public GeometryArray getGeometryArray(int index)This method retrieves a single geometry array from the Morph node. Theindex
parameter specifies which array is returned.public void setAppearance(Appearance appearance) public Appearance getAppearance()These methods set and retrieve the Appearance component of this Morph node. The Appearance component specifies material, texture, texture environment, transparency, or other rendering parameters. Setting it tonull
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 theweights
parameter must be equal to the length of the array with which this Morph node was created; otherwise, anIllegalArgumentException
is thrown.public void setCollisionBounds(Bounds bounds) public Bounds getCollisionBounds()These methods set and retrieve the collision bounding object of this node.public boolean intersect(SceneGraphPath path, PickShape pickShape) public boolean intersect(SceneGraphPath path, PickRay pickRay, double[] dist)These methods check if the geometry component of this morph node under path intersects with the pickShape.public void setAppearanceOverrideEnable(boolean flag) public boolean getAppearanceOverrideEnable()These methods set and retrieve the flag that indicates whether this node's appearance can be overridden. If the flag is true, this node's appearance may be overridden by an AlternateAppearance leaf node, regardless of the value of theALLOW_APPEARANCE_WRITE
capability bit. The default value is false. See Section 6.15, "AlternateAppearance Node."
6.14
The Link leaf node allows an application to reference a shared subgroup, rooted by a SharedGroup node, from within a branch of the scene graph. Any number of Link nodes can refer to the same SharedGroup node. See Section 7.1.2, "Link Leaf Node," for a description of this node.Link Node
6.15
The AlternateAppearance leaf node is used for overriding the Appearance component of selected nodes. It defines an Appearance component object and a region of influence in which this AlternateAppearance node is active. An AlternateAppearance node also contains a list of Group nodes that specifies the hierarchical scope of this AlternateAppearance. If the scope list is empty, the AlternateAppearance node has universe scope; all nodes within the region of influence are affected by this AlternateAppearance node. If the scope list is non-empty, only those Leaf nodes under the Group nodes in the scope list are affected by this AlternateAppearance node (subject to the influencing bounds).AlternateAppearance Node
Constants
The AlternateAppearance node specifies the following flags:public static final int ALLOW_INFLUENCING_BOUNDS_READ public static final int ALLOW_INFLUENCING_BOUNDS_WRITE public static final int ALLOW_APPEARANCE_READ public static final int ALLOW_APPEARANCE_WRITE public static final int ALLOW_SCOPE_READ public static final int ALLOW_SCOPE_WRITEThese flags, when enabled using thesetCapability
method, allow an application to invoke methods that respectively read and write the node's influencing bounds and bounds leaf information, appearance information, and scope information components.
Constructors
The AlternateAppearance node specifies the following constructors:public AlternateAppearance()Constructs an AlternateAppearance node with default parameters. The default values are as follows:
Parameter Default Value appearance null scope empty (universe scope) influencingBounds null influencingBoundingLeaf null
public AlternateAppearance(Appearance appearance)Constructs an AlternateAppearance node with the specified appearance.
Methods
The AlternateAppearance node specifies the following methods:public void setAppearance(Appearance appearance) public Appearance getAppearance()These methods set and retrieve the appearance of this AlternateAppearance node. This appearance overrides the appearance in those Shape3D and Morph nodes affected by this AlternateAppearance node.public void setInfluencingBounds(Bounds region) public Bounds getInfluencingBounds()These methods set and retrieve the AlternateAppearance's influencing region to the specified bounds. This is used when the influencing bounding leaf is set to null.public void setInfluencingBoundingLeaf(BoundingLeaf region) public BoundingLeaf getInfluencingBoundingLeaf()These methods set and retrieve the AlternateAppearance's influencing region to the specified bounding leaf. When set to a value other than null, this overrides the influencing bounds object.public void setScope(Group scope, int index) public Group getScope(int index)The first method replaces the node at the specified index in this AlternateAppearance node's list of scopes with the specified Group node. The second method retrieves the Group node at the specified index from this AlternateAppearance node's list of scopes. By default, AlternateAppearance nodes are scoped only by their influencing bounds. This allows them to be scoped further by a list of nodes in the hierarchy.public void insertScope(Group scope, int index) public void removeScope(int index)The first method inserts the specified Group node into this AlternateAppearance node's list of scopes at the specified index. The second method removes the node at the specified index from this AlternateAppearance node's list of scopes. If this operation causes the list of scopes to become empty, this AlternateAppearance will have universe scope; all nodes within the region of influence will be affected by this AlternateAppearance node. By default, AlternateAppearance nodes are scoped only by their influencing bounds. This allows them to be scoped further by a list of nodes in the hierarchy.public Enumeration getAllScopes()This method returns an enumeration of this AlternateAppearance node's list of scopes.public void addScope(Group scope)This method appends the specified Group node to this AlternateAppearance node's list of scopes. By default, AlternateAppearance nodes are scoped only by their influencing bounds. This allows them to be scoped further by a list of nodes in the hierarchy.public int numScopes()This method returns the number of nodes in this AlternateAppearance node's list of scopes. If this number is 0, the list of scopes is empty and this AlternateAppearance node has universe scope; all nodes within the region of influence are affected by this AlternateAppearance node.
The Java 3D API Specification |