# TransformState

from pandac.PandaModules import TransformState

Class : TransformState
Description : Indicates a coordinate-system transform on vertices. TransformStates are the primary means for storing transformations on the scene graph.
Transforms may be specified in one of two ways: componentwise, with a pos-hpr-scale, or with an arbitrary transform matrix. If you specify a transform componentwise, it will remember its original components.
TransformState objects are managed very much like RenderState objects. They are immutable and reference-counted automatically.
You should not attempt to create or modify a TransformState object directly. Instead, call one of the make() functions to create one for you. And instead of modifying a TransformState object, create a new one.

## Inheritance:

TransformState: NodeCachedReferenceCount
NodeCachedReferenceCount: CachedTypedWritableReferenceCount
CachedTypedWritableReferenceCount: TypedWritableReferenceCount
TypedWritableReferenceCount: TypedWritable ReferenceCount
TypedWritable: TypedObject
TypedObject: MemoryBase
MemoryBase:
ReferenceCount: MemoryBase

## Methods of TransformState:

cacheRef
cacheUnref
clearCache
componentsGiven
compose
getClassType
getGeomRendering
getHash
getHpr
getInverse
getMat
getMat3
getNormQuat
getNumStates
getNumUnusedStates
getPos
getPos2d
getQuat
getRotate2d
getScale
getScale2d
getShear
getShear2d
getUniformScale
hasComponents
hasHpr
hasIdentityScale
hasMat
hasNonzeroShear
hasPos
hasQuat
hasScale
hasShear
hasUniformScale
hprGiven
invertCompose
is2d
isIdentity
isInvalid
isSingular
listCycles
listStates
makeHpr
makeIdentity
makeInvalid
makeMat
makeMat3
makePos
makePos2d
makePosHpr
makePosHprScale
makePosHprScaleShear
makePosQuatScale
makePosQuatScaleShear
makePosRotate2d
makePosRotateScale2d
makePosRotateScaleShear2d
makeQuat
makeRotate2d
makeScale
makeScale2d
makeShear
makeShear2d
nodeRef
nodeUnref
operator <
output
quatGiven
setHpr
setPos
setPos2d
setQuat
setRotate2d
setScale
setScale2d
setShear
setShear2d
sortsLess
unref
validateStates
write

## Methods of NodeCachedReferenceCount:

getClassType
getNodeRefCount
getReferencedBits
nodeRef
nodeUnref
testRefCountIntegrity

## Methods of CachedTypedWritableReferenceCount:

cacheRef
cacheUnref
getCacheRefCount
getClassType
testRefCountIntegrity

## Methods of TypedWritableReferenceCount:

getClassType

## Methods of TypedWritable:

getClassType

## Methods of TypedObject:

getClassType
getType
getTypeIndex
isExactType
isOfType

## Methods of ReferenceCount:

getClassType
getRefCount
ref
testRefCountIntegrity
testRefCountNonzero
unref

## Constants in NodeCachedReferenceCount:

RNode | (Referenced)
RCache | (Referenced)

cacheRef void TransformState::cache_ref(void) const; Description: Overrides this method to update PStats appropriately.

cacheUnref bool TransformState::cache_unref(void) const; Description: Overrides this method to update PStats appropriately.

clearCache static int TransformState::clear_cache(void); Description: Empties the cache of composed TransformStates. This makes every TransformState forget what results when it is composed with other TransformStates. This will eliminate any TransformState objects that have been allocated but have no references outside of the internal TransformState map. It will not eliminate TransformState objects that are still in use. Nowadays, this method should not be necessary, as reference-count cycles in the composition cache should be automatically detected and broken. The return value is the number of TransformStates freed by this operation.

componentsGiven bool TransformState::components_given(void) const; Description: Returns true if the transform was specified componentwise, or false if it was specified with a general 4x4 matrix. If this is true, the components returned by get_pos() and get_scale() will be exactly those that were set; otherwise, these functions will return computed values. If this is true, the rotation may have been set either with a hpr trio or with a quaternion; hpr_given() or quat_given() can resolve the difference.

compose ConstPointerTo< TransformState > TransformState::compose(TransformState const *other) const; Description: Returns a new TransformState object that represents the composition of this state with the other state. The result of this operation is cached, and will be retained as long as both this TransformState object and the other TransformState object continue to exist. Should one of them destruct, the cached entry will be removed, and its pointer will be allowed to destruct as well.

getClassType static TypeHandle TransformState::get_class_type(void); Undocumented function.

getGeomRendering int TransformState::get_geom_rendering(int geom_rendering) const; Description: Returns the union of the Geom::GeomRendering bits that will be required once this TransformState is applied to a geom which includes the indicated geom_rendering bits. The RenderState's get_geom_rendering() should already have been applied.

getHash unsigned int TransformState::get_hash(void) const; Description: Returns a suitable hash value for phash_map.

getHpr LVecBase3f const &TransformState::get_hpr(void) const; Description: Returns the rotation component of the transform as a trio of Euler angles. It is an error to call this if has_components() returned false.

getInverse ConstPointerTo< TransformState > TransformState::get_inverse(void) const; Description: Returns the inverse of this transform. If you are going to immediately compose this result with another TransformState, it is faster to do it in one operation with invert_compose().

getMat LMatrix4f const &TransformState::get_mat(void) const; Description: Returns the matrix that describes the transform.

getMat3 LMatrix3f TransformState::get_mat3(void) const; Description: Returns the 3x3 matrix that describes the 2-d transform. It is an error to call this if is_2d() returned false.

getNormQuat LQuaternionf const &TransformState::get_norm_quat(void) const; Description: Returns the rotation component of the transform as a quaternion. Unlike the result of get_quat(), the return value of this method is guaranteed to be normalized. It is an error to call this if has_components() returned false.

getNumStates static int TransformState::get_num_states(void); Description: Returns the total number of unique TransformState objects allocated in the world. This will go up and down during normal operations.

getNumUnusedStates static int TransformState::get_num_unused_states(void); Description: Returns the total number of TransformState objects that have been allocated but have no references outside of the internal TransformState cache. A nonzero return value is not necessarily indicative of leaked references; it is normal for two TransformState objects, both of which have references held outside the cache, to have the result of their composition stored within the cache. This result will be retained within the cache until one of the base TransformStates is released. Use list_cycles() to get an idea of the number of actual "leaked" TransformState objects.

getPos LPoint3f const &TransformState::get_pos(void) const; Description: Returns the pos component of the transform. It is an error to call this if has_pos() returned false.

getPos2d LVecBase2f TransformState::get_pos2d(void) const; Description: Returns the pos component of the 2-d transform. It is an error to call this if has_pos() or is_2d() returned false.

getQuat LQuaternionf const &TransformState::get_quat(void) const; Description: Returns the rotation component of the transform as a quaternion. The return value will be normalized if a normalized quaternion was given to the constructor (or if the quaternion was computed implicitly); it will be non-normalized if a non-normalized quaternion was given to the constructor. See also get_norm_quat(). It is an error to call this if has_components() returned false.

getRotate2d float TransformState::get_rotate2d(void) const; Description: Returns the rotation component of the 2-d transform as an angle in degrees clockwise about the origin. It is an error to call this if has_components() or is_2d() returned false.

getScale LVecBase3f const &TransformState::get_scale(void) const; Description: Returns the scale component of the transform. It is an error to call this if has_components() returned false.

getScale2d LVecBase2f TransformState::get_scale2d(void) const; Description: Returns the scale component of the 2-d transform. It is an error to call this if has_components() or is_2d() returned false.

getShear LVecBase3f const &TransformState::get_shear(void) const; Description: Returns the shear component of the transform. It is an error to call this if has_components() returned false.

getShear2d float TransformState::get_shear2d(void) const; Description: Returns the shear component of the 2-d transform. It is an error to call this if has_components() or is_2d() returned false.

getUniformScale float TransformState::get_uniform_scale(void) const; Description: Returns the scale component of the transform, as a single number. It is an error to call this if has_uniform_scale() returned false.

hasComponents bool TransformState::has_components(void) const; Description: Returns true if the transform can be described by separate pos, hpr, and scale components. Most transforms we use in everyday life can be so described, but some kinds of transforms (for instance, those involving a skew) cannot. This is not related to whether the transform was originally described componentwise. Even a transform that was constructed with a 4x4 may return true here if the matrix is a simple affine matrix with no skew. If this returns true, you may safely call get_hpr() and get_scale() to retrieve the components. (You may always safely call get_pos() whether this returns true or false.)

hasHpr bool TransformState::has_hpr(void) const; Description: Returns true if the transform's rotation component can be extracted out separately and described as a set of Euler angles. This is generally true only when has_components() is true.

hasIdentityScale bool TransformState::has_identity_scale(void) const; Description: Returns true if the scale is uniform 1.0, or false if the scale has some real value.

hasMat bool TransformState::has_mat(void) const; Description: Returns true if the transform can be described as a matrix. This is generally always true, unless is_invalid() is true.

hasNonzeroShear bool TransformState::has_nonzero_shear(void) const; Description: Returns true if the shear component is non-zero, false if it is zero or if the matrix cannot be decomposed.

hasPos bool TransformState::has_pos(void) const; Description: Returns true if the transform's pos component can be extracted out separately. This is generally always true, unless the transform is invalid (i.e. is_invalid() returns true).

hasQuat bool TransformState::has_quat(void) const; Description: Returns true if the transform's rotation component can be extracted out separately and described as a quaternion. This is generally true only when has_components() is true.

hasScale bool TransformState::has_scale(void) const; Description: Returns true if the transform's scale component can be extracted out separately. This is generally true only when has_components() is true.

hasShear bool TransformState::has_shear(void) const; Description: Returns true if the transform's shear component can be extracted out separately. This is generally true only when has_components() is true.

hasUniformScale bool TransformState::has_uniform_scale(void) const; Description: Returns true if the scale is uniform across all three axes (and therefore can be expressed as a single number), or false if the transform has a different scale in different dimensions.

hprGiven bool TransformState::hpr_given(void) const; Description: Returns true if the rotation was specified via a trio of Euler angles, false otherwise. If this is true, get_hpr() will be exactly as set; otherwise, it will return a computed value.

invertCompose ConstPointerTo< TransformState > TransformState::invert_compose(TransformState const *other) const; Description: Returns a new TransformState object that represents the composition of this state's inverse with the other state. This is similar to compose(), but is particularly useful for computing the relative state of a node as viewed from some other node.

is2d bool TransformState::is_2d(void) const; Description: Returns true if the transform has been constructed entirely using the 2-d transform operations, e.g. make_pos2d(), and therefore operates strictly in two-dimensional space on X and Y only.

isIdentity bool TransformState::is_identity(void) const; Description: Returns true if the transform represents the identity matrix, false otherwise.

isInvalid bool TransformState::is_invalid(void) const; Description: Returns true if the transform represents an invalid matrix, for instance the result of inverting a singular matrix, or false if the transform is valid.

isSingular bool TransformState::is_singular(void) const; Description: Returns true if the transform represents a singular transform (that is, it has a zero scale, and it cannot be inverted), or false otherwise.

listCycles static void TransformState::list_cycles(ostream &out); Description: Detects all of the reference-count cycles in the cache and reports them to standard output. These cycles may be inadvertently created when state compositions cycle back to a starting point. Nowadays, these cycles should be automatically detected and broken, so this method should never list any cycles unless there is a bug in that detection logic. The cycles listed here are not leaks in the strictest sense of the word, since they can be reclaimed by a call to clear_cache(); but they will not be reclaimed automatically.

listStates static void TransformState::list_states(ostream &out); Description: Lists all of the TransformStates in the cache to the output stream, one per line. This can be quite a lot of output if the cache is large, so be prepared.

makeHpr static ConstPointerTo< TransformState > TransformState::make_hpr(LVecBase3f const &hpr); Description: Makes a new TransformState with the specified components.

makeIdentity static ConstPointerTo< TransformState > TransformState::make_identity(void); Description: Constructs an identity transform.

makeInvalid static ConstPointerTo< TransformState > TransformState::make_invalid(void); Description: Constructs an invalid transform; for instance, the result of inverting a singular matrix.

makeMat static ConstPointerTo< TransformState > TransformState::make_mat(LMatrix4f const &mat); Description: Makes a new TransformState with the specified transformation matrix.

makeMat3 static ConstPointerTo< TransformState > TransformState::make_mat3(LMatrix3f const &mat); Description: Makes a new two-dimensional TransformState with the specified 3x3 transformation matrix.

makePos static ConstPointerTo< TransformState > TransformState::make_pos(LVecBase3f const &pos); Description: Makes a new TransformState with the specified components.

makePos2d static ConstPointerTo< TransformState > TransformState::make_pos2d(LVecBase2f const &pos); Description: Makes a new 2-d TransformState with the specified components.

makePosHpr static ConstPointerTo< TransformState > TransformState::make_pos_hpr(LVecBase3f const &pos, LVecBase3f const &hpr); Description: Makes a new TransformState with the specified components.

makePosHprScale static ConstPointerTo< TransformState > TransformState::make_pos_hpr_scale(LVecBase3f const &pos, LVecBase3f const &hpr, LVecBase3f const &scale); Description: Makes a new TransformState with the specified components.

makePosHprScaleShear static ConstPointerTo< TransformState > TransformState::make_pos_hpr_scale_shear(LVecBase3f const &pos, LVecBase3f const &hpr, LVecBase3f const &scale, LVecBase3f const &shear); Description: Makes a new TransformState with the specified components.

makePosQuatScale static ConstPointerTo< TransformState > TransformState::make_pos_quat_scale(LVecBase3f const &pos, LQuaternionf const &quat, LVecBase3f const &scale); Description: Makes a new TransformState with the specified components.

makePosQuatScaleShear static ConstPointerTo< TransformState > TransformState::make_pos_quat_scale_shear(LVecBase3f const &pos, LQuaternionf const &quat, LVecBase3f const &scale, LVecBase3f const &shear); Description: Makes a new TransformState with the specified components.

makePosRotate2d static ConstPointerTo< TransformState > TransformState::make_pos_rotate2d(LVecBase2f const &pos, float rotate); Description: Makes a new 2-d TransformState with the specified components.

makePosRotateScale2d static ConstPointerTo< TransformState > TransformState::make_pos_rotate_scale2d(LVecBase2f const &pos, float rotate, LVecBase2f const &scale); Description: Makes a new 2-d TransformState with the specified components.

makePosRotateScaleShear2d static ConstPointerTo< TransformState > TransformState::make_pos_rotate_scale_shear2d(LVecBase2f const &pos, float rotate, LVecBase2f const &scale, float shear); Description: Makes a new two-dimensional TransformState with the specified components.

makeQuat static ConstPointerTo< TransformState > TransformState::make_quat(LQuaternionf const &quat); Description: Makes a new TransformState with the specified components.

makeRotate2d static ConstPointerTo< TransformState > TransformState::make_rotate2d(float rotate); Description: Makes a new 2-d TransformState with the specified components.

makeScale static ConstPointerTo< TransformState > TransformState::make_scale(float scale); Description: Makes a new TransformState with the specified components.

makeScale2d static ConstPointerTo< TransformState > TransformState::make_scale2d(float scale); Description: Makes a new 2-d TransformState with the specified components.

makeShear static ConstPointerTo< TransformState > TransformState::make_shear(LVecBase3f const &shear); Description: Makes a new TransformState with the specified components.

makeShear2d static ConstPointerTo< TransformState > TransformState::make_shear2d(float shear); Description: Makes a new 2-d TransformState with the specified components.

nodeRef void TransformState::node_ref(void) const; Description: Overrides this method to update PStats appropriately.

nodeUnref bool TransformState::node_unref(void) const; Description: Overrides this method to update PStats appropriately.

operator < bool TransformState::operator <(TransformState const &other) const; Filename: transformState.I Created by: drose (25Feb02) PANDA 3D SOFTWARE Copyright (c) 2001 - 2004, Disney Enterprises, Inc. All rights reserved All use of this software is subject to the terms of the Panda 3d Software license. You should have received a copy of this license along with this source code; you will also find a current copy of the license at http://etc.cmu.edu/panda3d/docs/license/ . To contact the maintainers of this program write to panda3d-general@lists.sourceforge.net . Description: Provides an arbitrary ordering among all unique TransformStates, so we can store the essentially different ones in a big set and throw away the rest. This is the same as sorts_less(), except the uniquify_matrix value is implicit from the Config.prc file.

output void TransformState::output(ostream &out) const; Description:

quatGiven bool TransformState::quat_given(void) const; Description: Returns true if the rotation was specified via a quaternion, false otherwise. If this is true, get_quat() will be exactly as set; otherwise, it will return a computed value.

setHpr ConstPointerTo< TransformState > TransformState::set_hpr(LVecBase3f const &hpr) const; Description: Returns a new TransformState object that represents the original TransformState with its rotation component replaced with the indicated value, if possible.

setPos ConstPointerTo< TransformState > TransformState::set_pos(LVecBase3f const &pos) const; Description: Returns a new TransformState object that represents the original TransformState with its pos component replaced with the indicated value.

setPos2d ConstPointerTo< TransformState > TransformState::set_pos2d(LVecBase2f const &pos) const; Description: Returns a new TransformState object that represents the original 2-d TransformState with its pos component replaced with the indicated value.

setQuat ConstPointerTo< TransformState > TransformState::set_quat(LQuaternionf const &quat) const; Description: Returns a new TransformState object that represents the original TransformState with its rotation component replaced with the indicated value, if possible.

setRotate2d ConstPointerTo< TransformState > TransformState::set_rotate2d(float rotate) const; Description: Returns a new TransformState object that represents the original 2-d TransformState with its rotation component replaced with the indicated value, if possible.

setScale ConstPointerTo< TransformState > TransformState::set_scale(LVecBase3f const &scale) const; Description: Returns a new TransformState object that represents the original TransformState with its scale component replaced with the indicated value, if possible.

setScale2d ConstPointerTo< TransformState > TransformState::set_scale2d(LVecBase2f const &scale) const; Description: Returns a new TransformState object that represents the original 2-d TransformState with its scale component replaced with the indicated value, if possible.

setShear ConstPointerTo< TransformState > TransformState::set_shear(LVecBase3f const &shear) const; Description: Returns a new TransformState object that represents the original TransformState with its shear component replaced with the indicated value, if possible.

setShear2d ConstPointerTo< TransformState > TransformState::set_shear2d(float shear) const; Description: Returns a new TransformState object that represents the original 2-d TransformState with its shear component replaced with the indicated value, if possible.

sortsLess bool TransformState::sorts_less(TransformState const &other, bool uniquify_matrix) const; Description: Provides an arbitrary ordering among all unique TransformStates, so we can store the essentially different ones in a big set and throw away the rest. If uniquify_matrix is true, then matrix-defined TransformStates are also uniqified. If uniquify_matrix is false, then only component-defined TransformStates are uniquified, which is less expensive.

unref bool TransformState::unref(void) const; Description: This method overrides ReferenceCount::unref() to check whether the remaining reference count is entirely in the cache, and if so, it checks for and breaks a cycle in the cache involving this object. This is designed to prevent leaks from cyclical references within the cache. Note that this is not a virtual method, and cannot be because ReferenceCount itself declares no virtual methods (it avoids the overhead of a virtual function pointer). But this doesn't matter, because PT(TransformState) is a template class, and will call the appropriate method even though it is non-virtual.

validateStates static bool TransformState::validate_states(void); Description: Ensures that the cache is still stored in sorted order, and that none of the cache elements have been inadvertently deleted. Returns true if so, false if there is a problem (which implies someone has modified one of the supposedly-const TransformState objects).

write void TransformState::write(ostream &out, int indent_level) const; Description:

getClassType static TypeHandle NodeCachedReferenceCount::get_class_type(void); Undocumented function.

getNodeRefCount int NodeCachedReferenceCount::get_node_ref_count(void) const; Description: Returns the current reference count.

getReferencedBits int NodeCachedReferenceCount::get_referenced_bits(void) const; Description: Returns the union of the values defined in the Referenced enum that represents the various things that appear to be holding a pointer to this object. If R_node is included, at least one node is holding a pointer; if R_cache is included, at least one cache element is.

nodeRef void NodeCachedReferenceCount::node_ref(void) const; Description: Explicitly increments the reference count. This function is const, even though it changes the object, because generally fiddling with an object's reference count isn't considered part of fiddling with the object. An object might be const in other ways, but we still need to accurately count the number of references to it.

nodeUnref bool NodeCachedReferenceCount::node_unref(void) const; Description: Explicitly decrements the reference count. Note that the object will not be implicitly deleted by unref() simply because the reference count drops to zero. (Having a member function delete itself is problematic; plus, we don't have a virtual destructor anyway.) However, see the helper function unref_delete(). User code should avoid using ref() and unref() directly, which can result in missed reference counts. Instead, let a PointerTo object manage the reference counting automatically. This function is const, even though it changes the object, because generally fiddling with an object's reference count isn't considered part of fiddling with the object. An object might be const in other ways, but we still need to accurately count the number of references to it. The return value is true if the new reference count is nonzero, false if it is zero.

testRefCountIntegrity bool NodeCachedReferenceCount::test_ref_count_integrity(void) const; Description: Does some easy checks to make sure that the reference count isn't completely bogus.

cacheRef void CachedTypedWritableReferenceCount::cache_ref(void) const; Description: Explicitly increments the reference count. This function is const, even though it changes the object, because generally fiddling with an object's reference count isn't considered part of fiddling with the object. An object might be const in other ways, but we still need to accurately count the number of references to it.

cacheUnref bool CachedTypedWritableReferenceCount::cache_unref(void) const; Description: Explicitly decrements the reference count. Note that the object will not be implicitly deleted by unref() simply because the reference count drops to zero. (Having a member function delete itself is problematic; plus, we don't have a virtual destructor anyway.) However, see the helper function unref_delete(). User code should avoid using ref() and unref() directly, which can result in missed reference counts. Instead, let a PointerTo object manage the reference counting automatically. This function is const, even though it changes the object, because generally fiddling with an object's reference count isn't considered part of fiddling with the object. An object might be const in other ways, but we still need to accurately count the number of references to it. The return value is true if the new reference count is nonzero, false if it is zero.

getCacheRefCount int CachedTypedWritableReferenceCount::get_cache_ref_count(void) const; Description: Returns the current reference count.

getClassType static TypeHandle CachedTypedWritableReferenceCount::get_class_type(void); Undocumented function.

testRefCountIntegrity bool CachedTypedWritableReferenceCount::test_ref_count_integrity(void) const; Description: Does some easy checks to make sure that the reference count isn't completely bogus.

getClassType static TypeHandle TypedWritableReferenceCount::get_class_type(void); Undocumented function.

getClassType static TypeHandle TypedWritable::get_class_type(void); Undocumented function.

getClassType static TypeHandle TypedObject::get_class_type(void); Undocumented function.

getType virtual TypeHandle TypedObject::get_type(void) const = 0; Derived classes should override this function to return get_class_type().

getTypeIndex int TypedObject::get_type_index(void) const; Description: Returns the internal index number associated with this object's TypeHandle, a unique number for each different type. This is equivalent to get_type().get_index().

isExactType bool TypedObject::is_exact_type(TypeHandle handle) const; Description: Returns true if the current object is the indicated type exactly.

isOfType bool TypedObject::is_of_type(TypeHandle handle) const; Description: Returns true if the current object is or derives from the indicated type.

getClassType static TypeHandle ReferenceCount::get_class_type(void); Undocumented function.

getRefCount int ReferenceCount::get_ref_count(void) const; Description: Returns the current reference count.

ref void ReferenceCount::ref(void) const; Description: Explicitly increments the reference count. User code should avoid using ref() and unref() directly, which can result in missed reference counts. Instead, let a PointerTo object manage the reference counting automatically. This function is const, even though it changes the object, because generally fiddling with an object's reference count isn't considered part of fiddling with the object. An object might be const in other ways, but we still need to accurately count the number of references to it.

testRefCountIntegrity bool ReferenceCount::test_ref_count_integrity(void) const; Description: Does some easy checks to make sure that the reference count isn't completely bogus. Returns true if ok, false otherwise.

testRefCountNonzero bool ReferenceCount::test_ref_count_nonzero(void) const; Description: Does some easy checks to make sure that the reference count isn't zero, or completely bogus. Returns true if ok, false otherwise.

unref bool ReferenceCount::unref(void) const; Description: Explicitly decrements the reference count. Note that the object will not be implicitly deleted by unref() simply because the reference count drops to zero. (Having a member function delete itself is problematic; plus, we don't have a virtual destructor anyway.) However, see the helper function unref_delete(). User code should avoid using ref() and unref() directly, which can result in missed reference counts. Instead, let a PointerTo object manage the reference counting automatically. This function is const, even though it changes the object, because generally fiddling with an object's reference count isn't considered part of fiddling with the object. An object might be const in other ways, but we still need to accurately count the number of references to it. The return value is true if the new reference count is nonzero, false if it is zero.