diff options
Diffstat (limited to 'src/javax/media/j3d/Billboard.java')
| -rw-r--r-- | src/javax/media/j3d/Billboard.java | 675 |
1 files changed, 675 insertions, 0 deletions
diff --git a/src/javax/media/j3d/Billboard.java b/src/javax/media/j3d/Billboard.java new file mode 100644 index 0000000..0372062 --- /dev/null +++ b/src/javax/media/j3d/Billboard.java @@ -0,0 +1,675 @@ +/* + * Copyright 1996-2008 Sun Microsystems, Inc. All Rights Reserved. + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * This code is free software; you can redistribute it and/or modify it + * under the terms of the GNU General Public License version 2 only, as + * published by the Free Software Foundation. Sun designates this + * particular file as subject to the "Classpath" exception as provided + * by Sun in the LICENSE file that accompanied this code. + * + * This code is distributed in the hope that it will be useful, but WITHOUT + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License + * version 2 for more details (a copy is included in the LICENSE file that + * accompanied this code). + * + * You should have received a copy of the GNU General Public License version + * 2 along with this work; if not, write to the Free Software Foundation, + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. + * + * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara, + * CA 95054 USA or visit www.sun.com if you need additional information or + * have any questions. + * + */ + +package javax.media.j3d; + +import java.util.Enumeration; + +import javax.vecmath.AxisAngle4d; +import javax.vecmath.Point3d; +import javax.vecmath.Point3f; +import javax.vecmath.Vector3d; +import javax.vecmath.Vector3f; + +/** + * The Billboard behavior node operates on the TransformGroup node + * to cause the local +z axis of the TransformGroup to point at + * the viewer's eye position. This is done regardless of the transforms + * above the specified TransformGroup node in the scene graph. + * + * <p> + * If the alignment mode is ROTATE_ABOUT_AXIS, the rotation will be + * around the specified axis. If the alignment mode is + * ROTATE_ABOUT_POINT, 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. + * + * <p> + * Note that in a multiple View system, the alignment is done to + * the primary View only. + * + * <p> + * Billboard 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. + * + * @see OrientedShape3D + */ +public class Billboard extends Behavior { + /** + * Specifies that rotation should be about the specified axis. + */ + public static final int ROTATE_ABOUT_AXIS = 0; + + /** + * Specifies that rotation should be about the specified point and + * that the children's Y-axis should match the view object's Y-axis. + */ + public static final int ROTATE_ABOUT_POINT = 1; + + // Wakeup condition for Billboard node + WakeupOnElapsedFrames wakeupFrame = new WakeupOnElapsedFrames(0, true); + + + // Specifies the billboard's mode of operation. One of ROTATE_AXIAL, + // ROTATE_POINT_VIEW, or ROTATE_POINT_WORLD. + int mode = ROTATE_ABOUT_AXIS; + + // Axis about which to rotate. + Vector3f axis = new Vector3f(0.0f, 1.0f, 0.0f); + Point3f rotationPoint = new Point3f(0.0f, 0.0f, 1.0f); + private Vector3d nAxis = new Vector3d(0.0, 1.0, 0.0); // normalized axis + + // TransformGroup to operate on. + TransformGroup tg = null; + + + // reused temporaries + private Point3d viewPosition = new Point3d(); + private Point3d yUpPoint = new Point3d(); + + private Vector3d eyeVec = new Vector3d(); + private Vector3d yUp = new Vector3d(); + private Vector3d zAxis = new Vector3d(); + private Vector3d yAxis = new Vector3d(); + private Vector3d vector = new Vector3d(); + + private AxisAngle4d aa = new AxisAngle4d(); + + static final double EPSILON = 1.0e-6; + + /** + * Constructs a Billboard node with default parameters. + * The default values are as follows: + * <ul> + * alignment mode : ROTATE_ABOUT_AXIS<br> + * alignment axis : Y-axis (0,1,0)<br> + * rotation point : (0,0,1)<br> + * target transform group: null<br> + *</ul> + */ + public Billboard() { + nAxis.x = 0.0; + nAxis.y = 1.0; + nAxis.z = 0.0; + } + + + /** + * Constructs a Billboard node with default parameters that operates + * on the specified TransformGroup node. + * The default alignment mode is ROTATE_ABOUT_AXIS rotation with the axis + * pointing along the Y axis. + * @param tg the TransformGroup node that this Billboard + * node operates upon + */ + public Billboard(TransformGroup tg) { + this.tg = tg; + nAxis.x = 0.0; + nAxis.y = 1.0; + nAxis.z = 0.0; + + } + + + /** + * Constructs a Billboard node with the specified axis and mode + * that operates on the specified TransformGroup node. + * The specified axis must not be parallel to the <i>Z</i> + * axis--(0,0,<i>z</i>) for any value of <i>z</i>. It is not + * possible for the +<i>Z</i> axis to point at the viewer's eye + * position by rotating about itself. The target transform will + * be set to the identity if the axis is (0,0,<i>z</i>). + * + * @param tg the TransformGroup node that this Billboard + * node operates upon + * @param mode alignment mode, one of ROTATE_ABOUT_AXIS or + * ROTATE_ABOUT_POINT + * @param axis the ray about which the billboard rotates + */ + public Billboard(TransformGroup tg, int mode, Vector3f axis) { + this.tg = tg; + this.mode = mode; + this.axis.set(axis); + double invMag; + invMag = 1.0/Math.sqrt(axis.x*axis.x + axis.y*axis.y + axis.z*axis.z); + nAxis.x = (double)axis.x*invMag; + nAxis.y = (double)axis.y*invMag; + nAxis.z = (double)axis.z*invMag; + + } + + /** + * Constructs a Billboard node with the specified rotation point and mode + * that operates on the specified TransformGroup node. + * @param tg the TransformGroup node that this Billboard + * node operates upon + * @param mode alignment mode, one of ROTATE_ABOUT_AXIS or + * ROTATE_ABOUT_POINT + * @param point the position about which the billboard rotates + */ + public Billboard(TransformGroup tg, int mode, Point3f point) { + this.tg = tg; + this.mode = mode; + this.rotationPoint.set(point); + } + + /** + * Sets the alignment mode. + * @param mode one of: ROTATE_ABOUT_AXIS or ROTATE_ABOUT_POINT + */ + public void setAlignmentMode(int mode) { + this.mode = mode; + } + + + /** + * Gets the alignment mode. + * @return one of: ROTATE_ABOUT_AXIS or ROTATE_ABOUT_POINT + */ + public int getAlignmentMode() { + return this.mode; + } + + + /** + * Sets the alignment axis. + * The specified axis must not be parallel to the <i>Z</i> + * axis--(0,0,<i>z</i>) for any value of <i>z</i>. It is not + * possible for the +<i>Z</i> axis to point at the viewer's eye + * position by rotating about itself. The target transform will + * be set to the identity if the axis is (0,0,<i>z</i>). + * + * @param axis the ray about which the billboard rotates + */ + public void setAlignmentAxis(Vector3f axis) { + this.axis.set(axis); + double invMag; + invMag = 1.0/Math.sqrt(axis.x*axis.x + axis.y*axis.y + axis.z*axis.z); + nAxis.x = (double)axis.x*invMag; + nAxis.y = (double)axis.y*invMag; + nAxis.z = (double)axis.z*invMag; + + } + + + /** + * Sets the alignment axis. + * The specified axis must not be parallel to the <i>Z</i> + * axis--(0,0,<i>z</i>) for any value of <i>z</i>. It is not + * possible for the +<i>Z</i> axis to point at the viewer's eye + * position by rotating about itself. The target transform will + * be set to the identity if the axis is (0,0,<i>z</i>). + * + * @param x the x component of the ray about which the billboard rotates + * @param y the y component of the ray about which the billboard rotates + * @param z the z component of the ray about which the billboard rotates + */ + public void setAlignmentAxis(float x, float y, float z) { + this.axis.set(x, y, z); + this.axis.set(axis); + double invMag; + invMag = 1.0/Math.sqrt(axis.x*axis.x + axis.y*axis.y + axis.z*axis.z); + nAxis.x = (double)axis.x*invMag; + nAxis.y = (double)axis.y*invMag; + nAxis.z = (double)axis.z*invMag; + + } + + + /** + * Gets the alignment axis and sets the parameter to this value. + * @param axis the vector that will contain the ray about which + * the billboard rotates + */ + public void getAlignmentAxis(Vector3f axis) { + axis.set(this.axis); + } + + /** + * Sets the rotation point. + * @param point the point about which the billboard rotates + */ + public void setRotationPoint(Point3f point) { + this.rotationPoint.set(point); + } + + + /** + * Sets the rotation point. + * @param x the x component of the point about which the billboard rotates + * @param y the y component of the point about which the billboard rotates + * @param z the z component of the point about which the billboard rotates + */ + public void setRotationPoint(float x, float y, float z) { + this.rotationPoint.set(x, y, z); + } + + + /** + * Gets the rotation point and sets the parameter to this value. + * @param point the position the Billboard rotates about + */ + public void getRotationPoint(Point3f point) { + point.set(this.rotationPoint); + } + /** + * Sets the tranformGroup for this Billboard object. + * @param tg the transformGroup node which replaces the current + * transformGroup node for this Billboard + */ + public void setTarget(TransformGroup tg ) { + this.tg = tg; + } + + /** + * Returns a copy of the transformGroup associated with this Billboard. + * @return the TranformGroup for this Billboard + */ + public TransformGroup getTarget() { + return(tg); + } + + + /** + * Initialize method that sets up initial wakeup criteria. + */ + @Override + public void initialize() { + // Insert wakeup condition into queue + wakeupOn(wakeupFrame); + } + + + /** + * Process stimulus method that computes appropriate transform. + * @param criteria an enumeration of the criteria that caused the + * stimulus + */ + @Override + public void processStimulus(Enumeration criteria) { + double angle = 0.0; + double sign; + + if( tg == null ){ + wakeupOn(wakeupFrame); + return; + } + + // get viewplatforms's location in virutal world + View v = this.getView(); + if( v == null ) { + wakeupOn(wakeupFrame); + return; + } + Canvas3D canvas = v.getCanvas3D(0); + boolean status; + + Transform3D xform = new Transform3D(); + Transform3D bbXform = new Transform3D(); + Transform3D prevTransform = new Transform3D(); + + ((TransformGroupRetained) tg.retained).getTransform(prevTransform); + + if (mode == ROTATE_ABOUT_AXIS ) { // rotate about axis + canvas.getCenterEyeInImagePlate(viewPosition); + canvas.getImagePlateToVworld(xform); // xform is imagePlateToLocal + xform.transform(viewPosition); + + // get billboard's transform + + // since we are using getTransform() to get the transform + // of the transformGroup, we need to use getLocalToVworld() + // to get the localToVworld which includes the static transform + + ((NodeRetained)tg.retained).getLocalToVworld(xform); + + xform.invert(); // xform is now vWorldToLocal + + // transform the eye position into the billboard's coordinate system + xform.transform(viewPosition); + + // eyeVec is a vector from the local origin to the eye pt in local + eyeVec.set(viewPosition); + eyeVec.normalize(); + + // project the eye into the rotation plane + status = projectToPlane(eyeVec, nAxis); + + // If the first project was successful .. + if (status) { + // project the z axis into the rotation plane + zAxis.x = 0.0; + zAxis.y = 0.0; + zAxis.z = 1.0; + status = projectToPlane(zAxis, nAxis); + } + + + ((TransformGroupRetained) tg.retained).getTransform(xform); + if (status) { + // compute the sign of the angle by checking if the cross product + // of the two vectors is in the same direction as the normal axis + vector.cross(eyeVec, zAxis); + if (vector.dot(nAxis) > 0.0) { + sign = 1.0; + } else { + sign = -1.0; + } + + // compute the angle between the projected eye vector and the + // projected z + double dot = eyeVec.dot(zAxis); + + if (dot > 1.0f) { + dot = 1.0f; + } else if (dot < -1.0f) { + dot = -1.0f; + } + + angle = sign*Math.acos(dot); + + // use -angle because xform is to *undo* rotation by angle + aa.x = nAxis.x; + aa.y = nAxis.y; + aa.z = nAxis.z; + aa.angle = -angle; + bbXform.set(aa); + if( !prevTransform.epsilonEquals(bbXform, EPSILON)) { + // Optimization for Billboard since it use passive + // behavior + // set the transform on the Billboard TG + tg.setTransform(bbXform); + } + } + else { + bbXform.setIdentity(); + if (!prevTransform.epsilonEquals(bbXform, EPSILON)) { + tg.setTransform(bbXform); + } + } + + } else { // rotate about point + // Need to rotate Z axis to point to eye, and Y axis to be + // parallel to view platform Y axis, rotating around rotation pt + + Transform3D zRotate = new Transform3D(); + + // get the eye point + canvas.getCenterEyeInImagePlate(viewPosition); + + // derive the yUp point + yUpPoint.set(viewPosition); + yUpPoint.y += 0.01; // one cm in Physical space + + // transform the points to the Billboard's space + canvas.getImagePlateToVworld(xform); // xform is ImagePlateToVworld + + xform.transform(viewPosition); + xform.transform(yUpPoint); + + // get billboard's transform + + // since we are using getTransform() to get the transform + // of the transformGroup, we need to use getLocalToVworld() + // to get the localToVworld which includes the static transform + + ((NodeRetained)tg.retained).getLocalToVworld(xform); + + xform.invert(); // xform is vWorldToLocal + + // transfom points to local coord sys + xform.transform(viewPosition); + xform.transform(yUpPoint); + + // Make a vector from viewPostion to 0,0,0 in the BB coord sys + eyeVec.set(viewPosition); + eyeVec.normalize(); + + // create a yUp vector + yUp.set(yUpPoint); + yUp.sub(viewPosition); + yUp.normalize(); + + + // find the plane to rotate z + zAxis.x = 0.0; + zAxis.y = 0.0; + zAxis.z = 1.0; + + // rotation axis is cross product of eyeVec and zAxis + vector.cross(eyeVec, zAxis); // vector is cross product + + // if cross product is non-zero, vector is rotation axis and + // rotation angle is acos(eyeVec.dot(zAxis))); + double length = vector.length(); + + if (length > 0.0001) { + double dot = eyeVec.dot(zAxis); + + if (dot > 1.0f) { + dot = 1.0f; + } else if (dot < -1.0f) { + dot = -1.0f; + } + + angle = Math.acos(dot); + aa.x = vector.x; + aa.y = vector.y; + aa.z = vector.z; + aa.angle = -angle; + zRotate.set(aa); + } else { + // no rotation needed, set to identity (scale = 1.0) + zRotate.set(1.0); + } + + // Transform the yAxis by zRotate + yAxis.x = 0.0; + yAxis.y = 1.0; + yAxis.z = 0.0; + zRotate.transform(yAxis); + + // project the yAxis onto the plane perp to the eyeVec + status = projectToPlane(yAxis, eyeVec); + + if (status) { + // project the yUp onto the plane perp to the eyeVec + status = projectToPlane(yUp, eyeVec); + } + + ((TransformGroupRetained) tg.retained).getTransform(xform); + if (status) { + // rotation angle is acos(yUp.dot(yAxis)); + double dot = yUp.dot(yAxis); + + // Fix numerical error, otherwise acos return NULL + if (dot > 1.0f) { + dot = 1.0f; + } else if (dot < -1.0f) { + dot = -1.0f; + } + + angle = Math.acos(dot); + + // check the sign by looking a the cross product vs the eyeVec + vector.cross(yUp, yAxis); // vector is cross product + if (eyeVec.dot(vector) < 0) { + angle *= -1; + } + aa.x = eyeVec.x; + aa.y = eyeVec.y; + aa.z = eyeVec.z; + aa.angle = -angle; + + xform.set(aa); // xform is now yRotate + + // rotate around the rotation point + vector.x = rotationPoint.x; + vector.y = rotationPoint.y; + vector.z = rotationPoint.z; // vector to translate to RP + bbXform.set(vector); // translate to RP + bbXform.mul(xform); // yRotate + bbXform.mul(zRotate); // zRotate + vector.scale(-1.0); // vector to translate back + xform.set(vector); // xform to translate back + bbXform.mul(xform); // translate back + + + if (!prevTransform.epsilonEquals(bbXform, EPSILON)) { + // set the transform on the Billboard TG + tg.setTransform(bbXform); + } + } + else { + bbXform.setIdentity(); + if (!prevTransform.epsilonEquals(bbXform, EPSILON)) { + tg.setTransform(bbXform); + } + } + } + + // Insert wakeup condition into queue + wakeupOn(wakeupFrame); +} + +private boolean projectToPlane(Vector3d projVec, Vector3d planeVec) { + double dis = planeVec.dot(projVec); + projVec.x = projVec.x - planeVec.x*dis; + projVec.y = projVec.y - planeVec.y*dis; + projVec.z = projVec.z - planeVec.z*dis; + + double length = projVec.length(); + + if (length < EPSILON) { + return false; + } + projVec.scale(1 / length); + return true; +} + + /** + * Creates a new instance of the node. This routine is called + * by <code>cloneTree</code> to duplicate the current node. + * @param forceDuplicate when set to <code>true</code>, causes the + * <code>duplicateOnCloneTree</code> flag to be ignored. When + * <code>false</code>, the value of each node's + * <code>duplicateOnCloneTree</code> variable determines whether + * NodeComponent data is duplicated or copied. + * + * @see Node#cloneTree + * @see Node#cloneNode + * @see Node#duplicateNode + * @see NodeComponent#setDuplicateOnCloneTree + */ + @Override + public Node cloneNode(boolean forceDuplicate) { + Billboard b = new Billboard(); + b.duplicateNode(this, forceDuplicate); + return b; + } + + + /** + * Copies all Billboard information from + * <code>originalNode</code> into + * the current node. This method is called from the + * <code>cloneNode</code> method which is, in turn, called by the + * <code>cloneTree</code> method.<P> + * + * @param originalNode the original node to duplicate. + * @param forceDuplicate when set to <code>true</code>, causes the + * <code>duplicateOnCloneTree</code> flag to be ignored. When + * <code>false</code>, the value of each node's + * <code>duplicateOnCloneTree</code> variable determines whether + * NodeComponent data is duplicated or copied. + * + * @exception RestrictedAccessException if this object is part of a live + * or compiled scenegraph. + * + * @see Node#duplicateNode + * @see Node#cloneTree + * @see NodeComponent#setDuplicateOnCloneTree + */ + @Override + void duplicateAttributes(Node originalNode, boolean forceDuplicate) { + super.duplicateAttributes(originalNode, forceDuplicate); + + Billboard bb = (Billboard) originalNode; + + setAlignmentMode(bb.getAlignmentMode()); + + Vector3f v = new Vector3f(); + bb.getAlignmentAxis(v); + setAlignmentAxis(v); + + Point3f p = new Point3f(); + bb.getRotationPoint(p); + setRotationPoint(p); + + // this will be updated by updateNodeReferences() later + setTarget(bb.getTarget()); + } + + + /** + * Callback used to allow a node to check if any scene graph objects + * referenced + * by that node have been duplicated via a call to <code>cloneTree</code>. + * This method is called by <code>cloneTree</code> after all nodes in + * the sub-graph have been duplicated. The cloned Leaf node's method + * will be called and the Leaf node can then look up any object references + * by using the <code>getNewObjectReference</code> method found in the + * <code>NodeReferenceTable</code> object. If a match is found, a + * reference to the corresponding object in the newly cloned sub-graph + * is returned. If no corresponding reference is found, either a + * DanglingReferenceException is thrown or a reference to the original + * object is returned depending on the value of the + * <code>allowDanglingReferences</code> parameter passed in the + * <code>cloneTree</code> call. + * <p> + * NOTE: Applications should <i>not</i> call this method directly. + * It should only be called by the cloneTree method. + * + * @param referenceTable a NodeReferenceTableObject that contains the + * <code>getNewObjectReference</code> method needed to search for + * new object instances. + * @see NodeReferenceTable + * @see Node#cloneTree + * @see DanglingReferenceException + */ + @Override + public void updateNodeReferences(NodeReferenceTable referenceTable) { + super.updateNodeReferences(referenceTable); + + // check for new TransformGroup + TransformGroup g = getTarget(); + if (g != null) { + setTarget((TransformGroup) referenceTable.getNewObjectReference(g)); + } + } +} + |