javax.media.j3d
Class OrientedShape3D

java.lang.Object
  |
  +--javax.media.j3d.SceneGraphObject
        |
        +--javax.media.j3d.Node
              |
              +--javax.media.j3d.Leaf
                    |
                    +--javax.media.j3d.Shape3D
                          |
                          +--javax.media.j3d.OrientedShape3D

public class OrientedShape3D

extends Shape3D

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.

It is similar in functionality to the Billboard behavior, but OrientedShape3D nodes will orient themselves correctly for each view, and they can be used within a SharedGroup.

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

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

Since:

Java 3D 1.2

See Also:

Billboard

Field Summary

static int	ALLOW_AXIS_READ Specifies that this OrientedShape3D node allows reading its alignment axis information.
static int	ALLOW_AXIS_WRITE Specifies that this OrientedShape3D node allows writing its alignment axis information.
static int	ALLOW_MODE_READ Specifies that this OrientedShape3D node allows reading its alignment mode information.
static int	ALLOW_MODE_WRITE Specifies that this OrientedShape3D node allows writing its alignment mode information.
static int	ALLOW_POINT_READ Specifies that this OrientedShape3D node allows reading its rotation point information.
static int	ALLOW_POINT_WRITE Specifies that this OrientedShape3D node allows writing its rotation point information.
static int	ROTATE_ABOUT_AXIS Specifies that rotation should be about the specified axis.
static int	ROTATE_ABOUT_POINT Specifies that rotation should be about the specified point and that the children's Y-axis should match the view object's Y-axis.

Fields inherited from class javax.media.j3d.Shape3D

ALLOW_APPEARANCE_OVERRIDE_READ, ALLOW_APPEARANCE_OVERRIDE_WRITE, ALLOW_APPEARANCE_READ, ALLOW_APPEARANCE_WRITE, ALLOW_COLLISION_BOUNDS_READ, ALLOW_COLLISION_BOUNDS_WRITE, ALLOW_GEOMETRY_READ, ALLOW_GEOMETRY_WRITE

Fields inherited from class javax.media.j3d.Node

ALLOW_AUTO_COMPUTE_BOUNDS_READ, ALLOW_AUTO_COMPUTE_BOUNDS_WRITE, ALLOW_BOUNDS_READ, ALLOW_BOUNDS_WRITE, ALLOW_COLLIDABLE_READ, ALLOW_COLLIDABLE_WRITE, ALLOW_LOCAL_TO_VWORLD_READ, ALLOW_PICKABLE_READ, ALLOW_PICKABLE_WRITE, ENABLE_COLLISION_REPORTING, ENABLE_PICK_REPORTING

Constructor Summary

OrientedShape3D()
Constructs an OrientedShape3D node with default parameters.

OrientedShape3D(Geometry geometry, Appearance appearance, int mode, Point3f point)
Constructs an OrientedShape3D node with the specified geometry component, appearance component, mode, and rotation point.

OrientedShape3D(Geometry geometry, Appearance appearance, int mode, Vector3f axis)
Constructs an OrientedShape3D node with the specified geometry component, appearance component, mode, and axis.

Method Summary

Node	cloneNode(boolean forceDuplicate) Used to create a new instance of the node.
void	duplicateNode(Node originalNode, boolean forceDuplicate) Copies all node information from originalNode into the current node.
void	getAlignmentAxis(Vector3f axis) Retrieves the alignment axis of this OrientedShape3D node, and copies it into the specified vector.
int	getAlignmentMode() Retrieves the alignment mode.
void	getRotationPoint(Point3f point) Retrieves the rotation point of this OrientedShape3D node, and copies it into the specified vector.
void	setAlignmentAxis(float x, float y, float z) Sets the new alignment axis.
void	setAlignmentAxis(Vector3f axis) Sets the new alignment axis.
void	setAlignmentMode(int mode) Sets the alignment mode.
void	setRotationPoint(float x, float y, float z) Sets the new rotation point.
void	setRotationPoint(Point3f point) Sets the new rotation point.

Methods inherited from class javax.media.j3d.Shape3D

addGeometry, getAllGeometries, getAppearance, getAppearanceOverrideEnable, getCollisionBounds, getGeometry, getGeometry, insertGeometry, intersect, intersect, numGeometries, removeGeometry, setAppearance, setAppearanceOverrideEnable, setCollisionBounds, setGeometry, setGeometry

Methods inherited from class javax.media.j3d.Node

cloneTree, cloneTree, cloneTree, cloneTree, cloneTree, cloneTree, getBounds, getBoundsAutoCompute, getCollidable, getLocalToVworld, getLocalToVworld, getParent, getPickable, setBounds, setBoundsAutoCompute, setCollidable, setPickable

Methods inherited from class javax.media.j3d.SceneGraphObject

clearCapability, duplicateSceneGraphObject, getCapability, getUserData, isCompiled, isLive, setCapability, setUserData, updateNodeReferences

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

ROTATE_ABOUT_AXIS

public static final int ROTATE_ABOUT_AXIS

Specifies that rotation should be about the specified axis.

See Also:

setAlignmentMode(int)

ROTATE_ABOUT_POINT

public static final int ROTATE_ABOUT_POINT

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

See Also:

setAlignmentMode(int)

ALLOW_MODE_READ

public static final int ALLOW_MODE_READ

Specifies that this OrientedShape3D node allows reading its alignment mode information.

ALLOW_MODE_WRITE

public static final int ALLOW_MODE_WRITE

Specifies that this OrientedShape3D node allows writing its alignment mode information.

ALLOW_AXIS_READ

public static final int ALLOW_AXIS_READ

Specifies that this OrientedShape3D node allows reading its alignment axis information.

ALLOW_AXIS_WRITE

public static final int ALLOW_AXIS_WRITE

Specifies that this OrientedShape3D node allows writing its alignment axis information.

ALLOW_POINT_READ

public static final int ALLOW_POINT_READ

Specifies that this OrientedShape3D node allows reading its rotation point information.

ALLOW_POINT_WRITE

public static final int ALLOW_POINT_WRITE

Specifies that this OrientedShape3D node allows writing its rotation point information.

Constructor Detail

OrientedShape3D

public OrientedShape3D()

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

alignment mode : ROTATE_ABOUT_AXIS
alignment axis : Y-axis (0,1,0)
rotation point : (0,0,1)

OrientedShape3D

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

Constructs an OrientedShape3D node with the specified geometry component, appearance component, mode, and axis.

Parameters:

geometry - the geometry component with which to initialize this shape node

appearance - the appearance component of the shape node

mode - alignment mode, one of ROTATE_ABOUT_AXIS or ROTATE_ABOUT_POINT

axis - the ray about which the OrientedShape3D rotates

OrientedShape3D

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

Constructs an OrientedShape3D node with the specified geometry component, appearance component, mode, and rotation point.

Parameters:

geometry - the geometry component with which to initialize this shape node

appearance - the appearance component of the shape node

mode - alignment mode, one of ROTATE_ABOUT_AXIS or ROTATE_ABOUT_POINT

point - the position about which the OrientedShape3D rotates

Method Detail

setAlignmentMode

public void setAlignmentMode(int mode)

Sets the alignment mode.

Parameters:

mode - one of: ROTATE_ABOUT_AXIS or ROTATE_ABOUT_POINT

Throws:

CapabilityNotSetException - if appropriate capability is not set and this object is part of live or compiled scene graph

getAlignmentMode

public int getAlignmentMode()

Retrieves the alignment mode.

Returns:

one of: ROTATE_ABOUT_AXIS or ROTATE_ABOUT_POINT

Throws:

CapabilityNotSetException - if appropriate capability is not set and this object is part of live or compiled scene graph

setAlignmentAxis

public void setAlignmentAxis(Vector3f axis)

Sets the new alignment axis. This is the ray about which this OrientedShape3D rotates when the mode is ROTATE_ABOUT_AXIS.

Parameters:

axis - the new alignment axis

Throws:

CapabilityNotSetException - if appropriate capability is not set and this object is part of live or compiled scene graph

setAlignmentAxis

public void setAlignmentAxis(float x,
                             float y,
                             float z)

Sets the new alignment axis. This is the ray about which this OrientedShape3D rotates when the mode is ROTATE_ABOUT_AXIS.

Parameters:

x - the x component of the alignment axis

y - the y component of the alignment axis

z - the z component of the alignment axis

Throws:

CapabilityNotSetException - if appropriate capability is not set and this object is part of live or compiled scene graph

getAlignmentAxis

public void getAlignmentAxis(Vector3f axis)

Retrieves the alignment axis of this OrientedShape3D node, and copies it into the specified vector.

Parameters:

axis - the vector that will contain the alignment axis

Throws:

CapabilityNotSetException - if appropriate capability is not set and this object is part of live or compiled scene graph

setRotationPoint

public void setRotationPoint(Point3f point)

Sets the new rotation point. This is the point about which the OrientedShape3D rotates when the mode is ROTATE_ABOUT_POINT.

Parameters:

point - the new rotation point

Throws:

CapabilityNotSetException - if appropriate capability is not set and this object is part of live or compiled scene graph

setRotationPoint

public void setRotationPoint(float x,
                             float y,
                             float z)

Sets the new rotation point. This is the point about which the OrientedShape3D rotates when the mode is ROTATE_ABOUT_POINT.

Parameters:

x - the x component of the rotation point

y - the y component of the rotation point

z - the z component of the rotation point

Throws:

CapabilityNotSetException - if appropriate capability is not set and this object is part of live or compiled scene graph

getRotationPoint

public void getRotationPoint(Point3f point)

Retrieves the rotation point of this OrientedShape3D node, and copies it into the specified vector.

Parameters:

axis - the point that will contain the rotation point

Throws:

CapabilityNotSetException - if appropriate capability is not set and this object is part of live or compiled scene graph

cloneNode

public Node cloneNode(boolean forceDuplicate)

Used to create a new instance of the node. This routine is called by cloneTree to duplicate the current node. cloneNode should be overridden by any user subclassed objects. All subclasses must have their cloneNode method consist of the following lines:

     public Node cloneNode(boolean forceDuplicate) {
         UserSubClass usc = new UserSubClass();
         usc.duplicateNode(this, forceDuplicate);
         return usc;
     }
 

Overrides:

cloneNode in class Shape3D

Parameters:

forceDuplicate - when set to true, causes the duplicateOnCloneTree flag to be ignored. When false, the value of each node's duplicateOnCloneTree variable determines whether NodeComponent data is duplicated or copied.

See Also:

Node.cloneTree(), Node.duplicateNode(javax.media.j3d.Node, boolean), NodeComponent.setDuplicateOnCloneTree(boolean)

duplicateNode

public void duplicateNode(Node originalNode,
                          boolean forceDuplicate)

Copies all node information from originalNode into the current node. This method is called from the cloneNode method which is, in turn, called by the cloneTree method.

For any NodeComponent objects contained by the object being duplicated, each NodeComponent object's duplicateOnCloneTree value is used to determine whether the NodeComponent should be duplicated in the new node or if just a reference to the current node should be placed in the new node. This flag can be overridden by setting the forceDuplicate parameter in the cloneTree method to true.
NOTE: Applications should not call this method directly. It should only be called by the cloneNode method.

Overrides:

duplicateNode in class Shape3D

Parameters:

originalNode - the original node to duplicate.

forceDuplicate - when set to true, causes the duplicateOnCloneTree flag to be ignored. When false, the value of each node's duplicateOnCloneTree variable determines whether NodeComponent data is duplicated or copied.

Throws:

ClassCastException - if originalNode is not an instance of Shape3D

See Also:

Node.cloneTree(), Node.cloneNode(boolean), NodeComponent.setDuplicateOnCloneTree(boolean)