org.j3d.renderer.aviatrix3d.nodes

Class Billboard

java.lang.Object

org.j3d.aviatrix3d.SceneGraphObject

org.j3d.aviatrix3d.Node

org.j3d.aviatrix3d.BaseNode

org.j3d.aviatrix3d.BaseGroup

org.j3d.renderer.aviatrix3d.nodes.Billboard

All Implemented Interfaces:

CustomPickTarget, PickableObject, PickTarget, Cullable, CustomCullable, TransformHierarchy

public class Billboard
extends BaseGroup
implements CustomCullable, CustomPickTarget, PickableObject

A class that automatically orients its children towards the camera location.

This class is design to operate in a shared scene graph structure. It works with the Cullable interface to make sure that regardless of the traversal path, it will have the children pointing towards the camera location. This makes it safe to share between layers as well as normal scene graph usage. Correctness is ensured regardless of culling traversal.

Bounds of this object is represented as a spherical object that is based on the largest dimension of all the children combined.

In order to use this node effectively, you will need to use the FrustumCullStage to process the children. It uses custom culling routines internally and that is the only cull stage that will do something useful with ths node.

Internationalisation Resource Names

• pickTimingMsg: Error message when attempting to pick outside the app update observer callback.
• notPickableMsg: Error message when the user has set the pickmask to zero and then requested a pick directly on this object.

Version:

$Revision: 1.8 $

Author:

Rune Aasgaard, (c) SINTEF, Justin Couch

Field Summary

Fields inherited from class org.j3d.aviatrix3d.BaseGroup

childList, dirtyBoundsCount, lastChild

Fields inherited from class org.j3d.aviatrix3d.Node

bounds, implicitBounds, parent

Fields inherited from class org.j3d.aviatrix3d.SceneGraphObject

alive, LISTENER_SET_TIMING_ERR_PROP, updateHandler

Fields inherited from interface org.j3d.aviatrix3d.picking.PickTarget

CUSTOM_PICK_TYPE, GROUP_PICK_TYPE, LEAF_PICK_TYPE, SINGLE_PICK_TYPE

Fields inherited from interface org.j3d.aviatrix3d.picking.PickableObject

COLLIDABLE_OBJECT, GENERAL_OBJECT, PROXIMITY_OBJECT, VISIBLE_OBJECT

Constructor Summary

Constructors

Constructor and Description
Billboard() Construct a default billboard that uses point mode for the default axis.
Billboard(boolean pointMode) Create a new billboard with the option of rotating around a point in space or any nominal axis.

Method Summary

Modifier and Type	Method and Description
boolean	checkPickMask(int mask) Check the given pick mask against the node's internal pick mask representation.
void	cullChildren(CullInstructions output, org.j3d.maths.vector.Matrix4d vworldTx, org.j3d.maths.vector.Matrix4d viewTransform, org.j3d.maths.vector.Vector4d[] frustumPlanes, float angularRes) Check this node for children to traverse.
void	getAxisOfRotation(float[] axis) Fetch the currently set axis of rotation.
BoundingVolume	getPickableBounds() Get the bounds of this picking target so that testing can be performed on the object.
int	getPickMask() Get the current pickable state mask of this object.
int	getPickTargetType() Return the type constant that represents the type of pick target this is.
boolean	isPointMode() Check to see whether this billboard is operating as a point in space or along an axis.
void	pickBatch(PickRequest[] reqs, int numRequests) Check for all intersections against this geometry and it's children to see if there is an intersection with the given set of requests.
void	pickChildren(PickInstructions output, org.j3d.maths.vector.Matrix4d vworldTx, PickRequest req) This node is being subjected to picking, so process the provided data and return the instructions on the list of available children and any transformation information to the system.
void	pickSingle(PickRequest req) Check for all intersections against this geometry and it's children to see if there is an intersection with the given set of requests.
protected void	recomputeBounds() Implementation of recompute bounds.
void	setAxisOfRotation(float[] axis) Set the axis of rotation used when the billboard is not operating in point mode.
void	setPickMask(int state) Set the node as being pickable currently using the given bit mask.

Methods inherited from class org.j3d.aviatrix3d.BaseGroup

addChild, checkForCyclicChild, getAllChildren, getChild, indexOfChild, markBoundsDirty, numChildren, removeAllChildren, removeChild, removeChild, requestBoundsUpdate, setBounds, setChild, setLive, setUpdateHandler, updateBounds

Methods inherited from class org.j3d.aviatrix3d.BaseNode

checkForCyclicChild, checkForCyclicParent, clearUpdateHandler, removeParent, setLive, setParent, setUpdateHandler

Methods inherited from class org.j3d.aviatrix3d.Node

boundsChanged, checkForCyclicParent, getBounds, getParent, removeParent, setParent, updateParentBounds

Methods inherited from class org.j3d.aviatrix3d.SceneGraphObject

dataChanged, getAppUpdateWriteTimingMessage, getBoundsWriteTimingMessage, getDataWriteTimingMessage, getUserData, isLive, setUserData

Methods inherited from class java.lang.Object

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

Constructor Detail

Billboard

public Billboard()

Construct a default billboard that uses point mode for the default axis.

Billboard

public Billboard(boolean pointMode)

Create a new billboard with the option of rotating around a point in space or any nominal axis.

Parameters:

pointMode - true if this should be rotating around a point in space

Method Detail

cullChildren

public void cullChildren(CullInstructions output,
                         org.j3d.maths.vector.Matrix4d vworldTx,
                         org.j3d.maths.vector.Matrix4d viewTransform,
                         org.j3d.maths.vector.Vector4d[] frustumPlanes,
                         float angularRes)

Check this node for children to traverse. The angular resolution is defined as Field Of View (in radians) / viewport width in pixels.

Specified by:

cullChildren in interface CustomCullable

Parameters:

output - Fill in the child information here

vworldTx - The transformation from the root of the scene to this node according to the current traversal path

viewTransform - The transformation from the root of the scene graph to the active viewpoint

frustumPlanes - Listing of frustum planes in the order: right, left, bottom, top, far, near

angularRes - Angular resolution of the screen, or 0 if not calculable from the available data.

pickChildren

public void pickChildren(PickInstructions output,
                         org.j3d.maths.vector.Matrix4d vworldTx,
                         PickRequest req)

This node is being subjected to picking, so process the provided data and return the instructions on the list of available children and any transformation information to the system.

Specified by:

pickChildren in interface CustomPickTarget

Parameters:

output - Fill in the picking results here

vworldTx - The transformation from the root of the scene to this node according to the current traversal path

req - The details of the picking request that are to be processed

checkPickMask

public boolean checkPickMask(int mask)

Check the given pick mask against the node's internal pick mask representation. If there is a match in one or more bitfields then this will return true, allowing picking to continue to process for this target.

Specified by:

checkPickMask in interface PickTarget

Parameters:

mask - The bit mask to check against

Returns:

True if the mask has an overlapping set of bitfields

getPickableBounds

public BoundingVolume getPickableBounds()

Get the bounds of this picking target so that testing can be performed on the object.

Specified by:

getPickableBounds in interface PickTarget

Returns:

The bounding volume defining the pickable target space

getPickTargetType

public int getPickTargetType()

Return the type constant that represents the type of pick target this is. Used to provided optimised picking implementations.

Specified by:

getPickTargetType in interface PickTarget

Returns:

The CUSTOM_PICK_TYPE constant

setPickMask

public void setPickMask(int state)

Set the node as being pickable currently using the given bit mask. A mask of 0 will completely disable picking.

Specified by:

setPickMask in interface PickableObject

Parameters:

state - A bit mask of available options to pick for

getPickMask

public int getPickMask()

Get the current pickable state mask of this object. A value of zero means it is completely unpickable.

Specified by:

getPickMask in interface PickableObject

Returns:

A bit mask of available options to pick for

pickBatch

public void pickBatch(PickRequest[] reqs,
                      int numRequests)
               throws NotPickableException,
                      InvalidPickTimingException

Check for all intersections against this geometry and it's children to see if there is an intersection with the given set of requests.

Specified by:

pickBatch in interface PickableObject

Parameters:

reqs - The list of picks to be made, starting at this object

numRequests - The number of valid pick requests to process

Throws:

NotPickableException - This object has been marked as non pickable, but you decided to try to call the method anyway

InvalidPickTimingException - An attempt was made to pick outside of the ApplicationUpdateObserver callback method

pickSingle

public void pickSingle(PickRequest req)
                throws NotPickableException,
                       InvalidPickTimingException

Check for all intersections against this geometry and it's children to see if there is an intersection with the given set of requests.

Specified by:

pickSingle in interface PickableObject

Parameters:

req - The details of the pick to be made

Throws:

NotPickableException - This object has been marked as non pickable, but you decided to try to call the method anyway

InvalidPickTimingException - An attempt was made to pick outside of the ApplicationUpdateObserver callback method

recomputeBounds

protected void recomputeBounds()

Implementation of recompute bounds. Expands the boundingbox to compensate for rotation of the children

Overrides:

recomputeBounds in class BaseGroup

isPointMode

public boolean isPointMode()

Check to see whether this billboard is operating as a point in space or along an axis.

Returns:

true if this is rotating around a point in space

setAxisOfRotation

public void setAxisOfRotation(float[] axis)

Set the axis of rotation used when the billboard is not operating in point mode. If the billboard is in point mode, the values set by this method are ignored. Setting an axis with all three components equal to zero is an error if this is not in point mode. In point mode, no checks are performed.

Parameters:

axis - An array containing the 3 axis coordinates

getAxisOfRotation

public void getAxisOfRotation(float[] axis)

Fetch the currently set axis of rotation.

Parameters:

axis - An array of at least length 3 to copy the rotation axis into