javax.media.j3d.TransformGroup Maven / Gradle / Ivy
Show all versions of java3d-core Show documentation
/*
* 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;
/**
* Group node that contains a transform. The TransformGroup node
* specifies a single spatial transformation, via a Transform3D
* object, that can position, orient, and scale all of its children.
*
* The specified transformation must be affine. Further, if the
* TransformGroup node is used as an ancestor of a ViewPlatform node
* in the scene graph, the transformation must be congruent-only
* rotations, translations, and uniform scales are allowed in
* a direct path from a Locale to a ViewPlatform node.
*
* Note: Even though arbitrary affine transformations are
* allowed, better performance will result if all matrices
* within a branch graph are congruent, containing only rotations
* translation, and uniform scale.
*
* The effects of transformations in the scene graph are cumulative.
* The concatenation of the transformations of each TransformGroup in
* a direct path from the Locale to a Leaf node defines a composite
* model transformation (CMT) that takes points in that Leaf node's
* local coordinates and transforms them into Virtual World (Vworld)
* coordinates. This composite transformation is used to
* transform points, normals, and distances into Vworld coordinates.
* Points are transformed by the CMT. Normals are transformed by the
* inverse-transpose of the CMT. Distances are transformed by the scale
* of the CMT. In the case of a transformation containing a nonuniform
* scale or shear, the maximum scale value in
* any direction is used. This ensures, for example, that a transformed
* bounding sphere, which is specified as a point and a radius,
* continues to enclose all objects that are also transformed using
* a nonuniform scale.
*
*/
public class TransformGroup extends Group {
/**
* Specifies that the node allows access to
* its object's transform information.
*/
public static final int
ALLOW_TRANSFORM_READ = CapabilityBits.TRANSFORM_GROUP_ALLOW_TRANSFORM_READ;
/**
* Specifies that the node allows writing
* its object's transform information.
*/
public static final int
ALLOW_TRANSFORM_WRITE = CapabilityBits.TRANSFORM_GROUP_ALLOW_TRANSFORM_WRITE;
// Array for setting default read capabilities
private static final int[] readCapabilities = {
ALLOW_TRANSFORM_READ
};
/**
* Constructs and initializes a TransformGroup using an
* identity transform.
*/
public TransformGroup() {
// set default read capabilities
setDefaultReadCapabilities(readCapabilities);
}
/**
* Constructs and initializes a TransformGroup from
* the Transform passed.
* @param t1 the transform3D object
* @exception BadTransformException if the transform is not affine.
*/
public TransformGroup(Transform3D t1) {
if (!t1.isAffine()) {
throw new BadTransformException(J3dI18N.getString("TransformGroup0"));
}
// set default read capabilities
setDefaultReadCapabilities(readCapabilities);
((TransformGroupRetained)this.retained).setTransform(t1);
}
/**
* Creates the retained mode TransformGroupRetained object that this
* TransformGroup object will point to.
*/
@Override
void createRetained() {
this.retained = new TransformGroupRetained();
this.retained.setSource(this);
}
/**
* Sets the transform component of this TransformGroup to the value of
* the passed transform.
* @param t1 the transform to be copied
* @exception CapabilityNotSetException if appropriate capability is
* not set and this object is part of live or compiled scene graph
* @exception BadTransformException if the transform is not affine.
*/
public void setTransform(Transform3D t1) {
if (isLiveOrCompiled())
if(!this.getCapability(ALLOW_TRANSFORM_WRITE))
throw new CapabilityNotSetException(J3dI18N.getString("TransformGroup1"));
if (!t1.isAffine()) {
throw new BadTransformException(J3dI18N.getString("TransformGroup0"));
}
((TransformGroupRetained)this.retained).setTransform(t1);
}
/**
* Copies the transform component of this TransformGroup into
* the passed transform object.
* @param t1 the transform object to be copied into
* @exception CapabilityNotSetException if appropriate capability is
* not set and this object is part of live or compiled scene graph
*/
public void getTransform(Transform3D t1) {
if (isLiveOrCompiled())
if(!this.getCapability(ALLOW_TRANSFORM_READ))
throw new CapabilityNotSetException(J3dI18N.getString("TransformGroup2"));
((TransformGroupRetained)this.retained).getTransform(t1);
}
/**
* Creates a new instance of the node. This routine is called
* by cloneTree to duplicate the current node.
* @param 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 Node#cloneTree
* @see Node#cloneNode
* @see Node#duplicateNode
* @see NodeComponent#setDuplicateOnCloneTree
*/
@Override
public Node cloneNode(boolean forceDuplicate) {
TransformGroup tg = new TransformGroup();
tg.duplicateNode(this, forceDuplicate);
return tg;
}
/**
* Copies all TransformGroup information from
* originalNode into
* the current node. This method is called from the
* cloneNode method which is, in turn, called by the
* cloneTree method.
*
* @param originalNode the original node to duplicate.
* @param 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.
*
* @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);
Transform3D t = new Transform3D();
((TransformGroupRetained) originalNode.retained).getTransform(t);
((TransformGroupRetained) retained).setTransform(t);
}
}