001: /*
002: * $RCSfile: TransformGroup.java,v $
003: *
004: * Copyright 1996-2008 Sun Microsystems, Inc. All Rights Reserved.
005: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
006: *
007: * This code is free software; you can redistribute it and/or modify it
008: * under the terms of the GNU General Public License version 2 only, as
009: * published by the Free Software Foundation. Sun designates this
010: * particular file as subject to the "Classpath" exception as provided
011: * by Sun in the LICENSE file that accompanied this code.
012: *
013: * This code is distributed in the hope that it will be useful, but WITHOUT
014: * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
015: * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
016: * version 2 for more details (a copy is included in the LICENSE file that
017: * accompanied this code).
018: *
019: * You should have received a copy of the GNU General Public License version
020: * 2 along with this work; if not, write to the Free Software Foundation,
021: * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
022: *
023: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
024: * CA 95054 USA or visit www.sun.com if you need additional information or
025: * have any questions.
026: *
027: * $Revision: 1.7 $
028: * $Date: 2008/02/28 20:17:32 $
029: * $State: Exp $
030: */
031:
032: package javax.media.j3d;
033:
034: /**
035: * Group node that contains a transform. The TransformGroup node
036: * specifies a single spatial transformation, via a Transform3D
037: * object, that can position, orient, and scale all of its children.
038: * <P>
039: * The specified transformation must be affine. Further, if the
040: * TransformGroup node is used as an ancestor of a ViewPlatform node
041: * in the scene graph, the transformation must be congruent-only
042: * rotations, translations, and uniform scales are allowed in
043: * a direct path from a Locale to a ViewPlatform node.
044: * <P>
045: * Note: Even though arbitrary affine transformations are
046: * allowed, better performance will result if all matrices
047: * within a branch graph are congruent, containing only rotations
048: * translation, and uniform scale.
049: * <P>
050: * The effects of transformations in the scene graph are cumulative.
051: * The concatenation of the transformations of each TransformGroup in
052: * a direct path from the Locale to a Leaf node defines a composite
053: * model transformation (CMT) that takes points in that Leaf node's
054: * local coordinates and transforms them into Virtual World (Vworld)
055: * coordinates. This composite transformation is used to
056: * transform points, normals, and distances into Vworld coordinates.
057: * Points are transformed by the CMT. Normals are transformed by the
058: * inverse-transpose of the CMT. Distances are transformed by the scale
059: * of the CMT. In the case of a transformation containing a nonuniform
060: * scale or shear, the maximum scale value in
061: * any direction is used. This ensures, for example, that a transformed
062: * bounding sphere, which is specified as a point and a radius,
063: * continues to enclose all objects that are also transformed using
064: * a nonuniform scale.
065: * <P>
066: */
067:
068: public class TransformGroup extends Group {
069: /**
070: * Specifies that the node allows access to
071: * its object's transform information.
072: */
073: public static final int ALLOW_TRANSFORM_READ = CapabilityBits.TRANSFORM_GROUP_ALLOW_TRANSFORM_READ;
074:
075: /**
076: * Specifies that the node allows writing
077: * its object's transform information.
078: */
079: public static final int ALLOW_TRANSFORM_WRITE = CapabilityBits.TRANSFORM_GROUP_ALLOW_TRANSFORM_WRITE;
080:
081: // Array for setting default read capabilities
082: private static final int[] readCapabilities = { ALLOW_TRANSFORM_READ };
083:
084: /**
085: * Constructs and initializes a TransformGroup using an
086: * identity transform.
087: */
088: public TransformGroup() {
089: // set default read capabilities
090: setDefaultReadCapabilities(readCapabilities);
091: }
092:
093: /**
094: * Constructs and initializes a TransformGroup from
095: * the Transform passed.
096: * @param t1 the transform3D object
097: * @exception BadTransformException if the transform is not affine.
098: */
099: public TransformGroup(Transform3D t1) {
100: if (!t1.isAffine()) {
101: throw new BadTransformException(J3dI18N
102: .getString("TransformGroup0"));
103: }
104:
105: // set default read capabilities
106: setDefaultReadCapabilities(readCapabilities);
107:
108: ((TransformGroupRetained) this .retained).setTransform(t1);
109: }
110:
111: /**
112: * Creates the retained mode TransformGroupRetained object that this
113: * TransformGroup object will point to.
114: */
115: void createRetained() {
116: this .retained = new TransformGroupRetained();
117: this .retained.setSource(this );
118: }
119:
120: /**
121: * Sets the transform component of this TransformGroup to the value of
122: * the passed transform.
123: * @param t1 the transform to be copied
124: * @exception CapabilityNotSetException if appropriate capability is
125: * not set and this object is part of live or compiled scene graph
126: * @exception BadTransformException if the transform is not affine.
127: */
128: public void setTransform(Transform3D t1) {
129: if (isLiveOrCompiled())
130: if (!this .getCapability(ALLOW_TRANSFORM_WRITE))
131: throw new CapabilityNotSetException(J3dI18N
132: .getString("TransformGroup1"));
133:
134: if (!t1.isAffine()) {
135: throw new BadTransformException(J3dI18N
136: .getString("TransformGroup0"));
137: }
138:
139: ((TransformGroupRetained) this .retained).setTransform(t1);
140: }
141:
142: /**
143: * Copies the transform component of this TransformGroup into
144: * the passed transform object.
145: * @param t1 the transform object to be copied into
146: * @exception CapabilityNotSetException if appropriate capability is
147: * not set and this object is part of live or compiled scene graph
148: */
149: public void getTransform(Transform3D t1) {
150: if (isLiveOrCompiled())
151: if (!this .getCapability(ALLOW_TRANSFORM_READ))
152: throw new CapabilityNotSetException(J3dI18N
153: .getString("TransformGroup2"));
154:
155: ((TransformGroupRetained) this .retained).getTransform(t1);
156: }
157:
158: /**
159: * Creates a new instance of the node. This routine is called
160: * by <code>cloneTree</code> to duplicate the current node.
161: * @param forceDuplicate when set to <code>true</code>, causes the
162: * <code>duplicateOnCloneTree</code> flag to be ignored. When
163: * <code>false</code>, the value of each node's
164: * <code>duplicateOnCloneTree</code> variable determines whether
165: * NodeComponent data is duplicated or copied.
166: *
167: * @see Node#cloneTree
168: * @see Node#cloneNode
169: * @see Node#duplicateNode
170: * @see NodeComponent#setDuplicateOnCloneTree
171: */
172: public Node cloneNode(boolean forceDuplicate) {
173: TransformGroup tg = new TransformGroup();
174: tg.duplicateNode(this , forceDuplicate);
175: return tg;
176: }
177:
178: /**
179: * Copies all TransformGroup information from
180: * <code>originalNode</code> into
181: * the current node. This method is called from the
182: * <code>cloneNode</code> method which is, in turn, called by the
183: * <code>cloneTree</code> method.<P>
184: *
185: * @param originalNode the original node to duplicate.
186: * @param forceDuplicate when set to <code>true</code>, causes the
187: * <code>duplicateOnCloneTree</code> flag to be ignored. When
188: * <code>false</code>, the value of each node's
189: * <code>duplicateOnCloneTree</code> variable determines whether
190: * NodeComponent data is duplicated or copied.
191: *
192: * @exception RestrictedAccessException if this object is part of a live
193: * or compiled scenegraph.
194: *
195: * @see Node#duplicateNode
196: * @see Node#cloneTree
197: * @see NodeComponent#setDuplicateOnCloneTree
198: */
199: void duplicateAttributes(Node originalNode, boolean forceDuplicate) {
200: super .duplicateAttributes(originalNode, forceDuplicate);
201:
202: Transform3D t = new Transform3D();
203: ((TransformGroupRetained) originalNode.retained)
204: .getTransform(t);
205: ((TransformGroupRetained) retained).setTransform(t);
206: }
207: }
|