panda3d.core.TransformState

from panda3d.core import TransformState
class TransformState

Bases: NodeCachedReferenceCount

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 diagram

Inheritance diagram of TransformState

compareTo(other: TransformState) → int

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.

Note that if this returns 0, it doesn’t necessarily imply that operator == returns true; it uses a very slightly different comparison threshold.

compareTo(other: TransformState, uniquify_matrix: bool) → int

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.

Note that if this returns 0, it doesn’t necessarily imply that operator == returns true; it uses a very slightly different comparison threshold.

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.

getHash() → size_t

Returns a suitable hash value for phash_map.

Return type

size_t

static makeIdentity() → TransformState

Constructs an identity transform.

Return type

TransformState

static makeInvalid() → TransformState

Constructs an invalid transform; for instance, the result of inverting a singular matrix.

Return type

TransformState

static makePos(pos: LVecBase3) → TransformState

Makes a new TransformState with the specified components.

Return type

TransformState

static makeHpr(hpr: LVecBase3) → TransformState

Makes a new TransformState with the specified components.

Return type

TransformState

static makeQuat(quat: LQuaternion) → TransformState

Makes a new TransformState with the specified components.

Return type

TransformState

static makePosHpr(pos: LVecBase3, hpr: LVecBase3) → TransformState

Makes a new TransformState with the specified components.

Return type

TransformState

static makeScale(scale: LVecBase3) → TransformState

Makes a new TransformState with the specified components.

Return type

TransformState

static makeScale(scale: float) → TransformState

Makes a new TransformState with the specified components.

Return type

TransformState

static makeShear(shear: LVecBase3) → TransformState

Makes a new TransformState with the specified components.

Return type

TransformState

static makePosHprScale(pos: LVecBase3, hpr: LVecBase3, scale: LVecBase3) → TransformState

Makes a new TransformState with the specified components.

Return type

TransformState

static makePosQuatScale(pos: LVecBase3, quat: LQuaternion, scale: LVecBase3) → TransformState

Makes a new TransformState with the specified components.

Return type

TransformState

static makePosHprScaleShear(pos: LVecBase3, hpr: LVecBase3, scale: LVecBase3, shear: LVecBase3) → TransformState

Makes a new TransformState with the specified components.

Return type

TransformState

static makePosQuatScaleShear(pos: LVecBase3, quat: LQuaternion, scale: LVecBase3, shear: LVecBase3) → TransformState

Makes a new TransformState with the specified components.

Return type

TransformState

static makeMat(mat: LMatrix4) → TransformState

Makes a new TransformState with the specified transformation matrix.

Return type

TransformState

static makePos2d(pos: LVecBase2) → TransformState

Makes a new 2-d TransformState with the specified components.

Return type

TransformState

static makeRotate2d(rotate: float) → TransformState

Makes a new 2-d TransformState with the specified components.

Return type

TransformState

static makePosRotate2d(pos: LVecBase2, rotate: float) → TransformState

Makes a new 2-d TransformState with the specified components.

Return type

TransformState

static makeScale2d(scale: LVecBase2) → TransformState

Makes a new 2-d TransformState with the specified components.

Return type

TransformState

static makeScale2d(scale: float) → TransformState

Makes a new 2-d TransformState with the specified components.

Return type

TransformState

static makeShear2d(shear: float) → TransformState

Makes a new 2-d TransformState with the specified components.

Return type

TransformState

static makePosRotateScale2d(pos: LVecBase2, rotate: float, scale: LVecBase2) → TransformState

Makes a new 2-d TransformState with the specified components.

Return type

TransformState

static makePosRotateScaleShear2d(pos: LVecBase2, rotate: float, scale: LVecBase2, shear: float) → TransformState

Makes a new two-dimensional TransformState with the specified components.

Return type

TransformState

static makeMat3(mat: LMatrix3) → TransformState

Makes a new two-dimensional TransformState with the specified 3x3 transformation matrix.

Return type

TransformState

isIdentity() → bool

Returns true if the transform represents the identity matrix, false otherwise.

isInvalid() → bool

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

Returns true if the transform represents a singular transform (that is, it has a zero scale, and it cannot be inverted), or false otherwise.

is2d() → bool

Returns true if the transform has been constructed entirely using the 2-d transform operations, e.g. makePos2d(), and therefore operates strictly in two-dimensional space on X and Y only.

hasComponents() → bool

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 getHpr() and getScale() to retrieve the components. (You may always safely call getPos() whether this returns true or false.)

componentsGiven() → bool

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 getPos() and getScale() 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; hprGiven() or quatGiven() can resolve the difference.

hprGiven() → bool

Returns true if the rotation was specified via a trio of Euler angles, false otherwise. If this is true, getHpr() will be exactly as set; otherwise, it will return a computed value.

quatGiven() → bool

Returns true if the rotation was specified via a quaternion, false otherwise. If this is true, getQuat() will be exactly as set; otherwise, it will return a computed value.

hasPos() → bool

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. isInvalid() returns true).

hasHpr() → bool

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 hasComponents() is true.

hasQuat() → bool

Returns true if the transform’s rotation component can be extracted out separately and described as a quaternion. This is generally true only when hasComponents() is true.

hasScale() → bool

Returns true if the transform’s scale component can be extracted out separately. This is generally true only when hasComponents() is true.

hasIdentityScale() → bool

Returns true if the scale is uniform 1.0, or false if the scale has some real value.

hasUniformScale() → bool

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.

hasShear() → bool

Returns true if the transform’s shear component can be extracted out separately. This is generally true only when hasComponents() is true.

hasNonzeroShear() → bool

Returns true if the shear component is non-zero, false if it is zero or if the matrix cannot be decomposed.

hasMat() → bool

Returns true if the transform can be described as a matrix. This is generally always true, unless isInvalid() is true.

getPos() → LPoint3

Returns the pos component of the transform. It is an error to call this if hasPos() returned false.

Return type

LPoint3

getHpr() → LVecBase3

Returns the rotation component of the transform as a trio of Euler angles. It is an error to call this if hasComponents() returned false.

Return type

LVecBase3

getQuat() → LQuaternion

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 getNormQuat().

It is an error to call this if hasComponents() returned false.

Return type

LQuaternion

getNormQuat() → LQuaternion

Returns the rotation component of the transform as a quaternion. Unlike the result of getQuat(), the return value of this method is guaranteed to be normalized. It is an error to call this if hasComponents() returned false.

Return type

LQuaternion

getScale() → LVecBase3

Returns the scale component of the transform. It is an error to call this if hasComponents() returned false.

Return type

LVecBase3

getUniformScale() → float

Returns the scale component of the transform, as a single number. It is an error to call this if hasUniformScale() returned false.

getShear() → LVecBase3

Returns the shear component of the transform. It is an error to call this if hasComponents() returned false.

Return type

LVecBase3

getMat() → LMatrix4

Returns the matrix that describes the transform.

Return type

LMatrix4

getPos2d() → LVecBase2

Returns the pos component of the 2-d transform. It is an error to call this if hasPos() or is2d() returned false.

Return type

LVecBase2

getRotate2d() → float

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 hasComponents() or is2d() returned false.

getScale2d() → LVecBase2

Returns the scale component of the 2-d transform. It is an error to call this if hasComponents() or is2d() returned false.

Return type

LVecBase2

getShear2d() → float

Returns the shear component of the 2-d transform. It is an error to call this if hasComponents() or is2d() returned false.

getMat3() → LMatrix3

Returns the 3x3 matrix that describes the 2-d transform. It is an error to call this if is2d() returned false.

Return type

LMatrix3

setPos(pos: LVecBase3) → TransformState

Returns a new TransformState object that represents the original TransformState with its pos component replaced with the indicated value.

Return type

TransformState

setHpr(hpr: LVecBase3) → TransformState

Returns a new TransformState object that represents the original TransformState with its rotation component replaced with the indicated value, if possible.

Return type

TransformState

setQuat(quat: LQuaternion) → TransformState

Returns a new TransformState object that represents the original TransformState with its rotation component replaced with the indicated value, if possible.

Return type

TransformState

setScale(scale: LVecBase3) → TransformState

Returns a new TransformState object that represents the original TransformState with its scale component replaced with the indicated value, if possible.

Return type

TransformState

setShear(shear: LVecBase3) → TransformState

Returns a new TransformState object that represents the original TransformState with its shear component replaced with the indicated value, if possible.

Return type

TransformState

setPos2d(pos: LVecBase2) → TransformState

Returns a new TransformState object that represents the original 2-d TransformState with its pos component replaced with the indicated value.

Return type

TransformState

setRotate2d(rotate: float) → TransformState

Returns a new TransformState object that represents the original 2-d TransformState with its rotation component replaced with the indicated value, if possible.

Return type

TransformState

setScale2d(scale: LVecBase2) → TransformState

Returns a new TransformState object that represents the original 2-d TransformState with its scale component replaced with the indicated value, if possible.

Return type

TransformState

setShear2d(shear: float) → TransformState

Returns a new TransformState object that represents the original 2-d TransformState with its shear component replaced with the indicated value, if possible.

Return type

TransformState

compose(other: TransformState) → TransformState

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.

Return type

TransformState

invertCompose(other: TransformState) → TransformState

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.

Return type

TransformState

getInverse() → TransformState

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 invertCompose().

Return type

TransformState

getUnique() → TransformState

Returns the pointer to the unique TransformState in the cache that is equivalent to this one. This may be the same pointer as this object, or it may be a different pointer; but it will be an equivalent object, and it will be a shared pointer. This may be called from time to time to improve cache benefits.

Return type

TransformState

getGeomRendering(geom_rendering: int) → int

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 getGeomRendering() should already have been applied.

cacheRef() → None

Overrides this method to update PStats appropriately.

cacheUnref() → bool

Overrides this method to update PStats appropriately.

nodeRef() → None

Overrides this method to update PStats appropriately.

nodeUnref() → bool

Overrides this method to update PStats appropriately.

getCompositionCacheNumEntries() → size_t

Returns the number of entries in the composition cache for this TransformState. This is the number of other TransformStates whose composition with this one has been cached. This number is not useful for any practical reason other than performance analysis.

Return type

size_t

getInvertCompositionCacheNumEntries() → size_t

Returns the number of entries in the invert_composition cache for this TransformState. This is similar to the composition cache, but it records cache entries for the invertCompose() operation. See getCompositionCacheNumEntries().

Return type

size_t

getCompositionCacheSize() → size_t

Returns the number of slots in the composition cache for this TransformState. You may use this as an upper bound when walking through all of the composition cache results via getCompositionCacheSource() or result().

This has no practical value other than for examining the cache for performance analysis.

Return type

size_t

getCompositionCacheSource(n: size_t) → TransformState

Returns the source TransformState of the nth element in the composition cache. Returns NULL if there doesn’t happen to be an entry in the nth element. See getCompositionCacheResult().

This has no practical value other than for examining the cache for performance analysis.

Return type

TransformState

getCompositionCacheResult(n: size_t) → TransformState

Returns the result TransformState of the nth element in the composition cache. Returns NULL if there doesn’t happen to be an entry in the nth element.

In general, a->compose(a->get_composition_cache_source(n)) == a->get_composition_cache_result(n).

This has no practical value other than for examining the cache for performance analysis.

Return type

TransformState

getInvertCompositionCacheSize() → size_t

Returns the number of slots in the composition cache for this TransformState. You may use this as an upper bound when walking through all of the composition cache results via getInvertCompositionCacheSource() or result().

This has no practical value other than for examining the cache for performance analysis.

Return type

size_t

getInvertCompositionCacheSource(n: size_t) → TransformState

Returns the source TransformState of the nth element in the invert composition cache. Returns NULL if there doesn’t happen to be an entry in the nth element. See getInvertCompositionCacheResult().

This has no practical value other than for examining the cache for performance analysis.

Return type

TransformState

getInvertCompositionCacheResult(n: size_t) → TransformState

Returns the result TransformState of the nth element in the invert composition cache. Returns NULL if there doesn’t happen to be an entry in the nth element.

In general, a->invert_compose(a->get_invert_composition_cache_source(n)) == a->get_invert_composition_cache_result(n).

This has no practical value other than for examining the cache for performance analysis.

Return type

TransformState

validateCompositionCache() → bool

Returns true if the composition cache and invert composition cache for this particular TransformState are self-consistent and valid, false otherwise.

getCompositionCache() → object
getInvertCompositionCache() → object
output(out: ostream) → None
write(out: ostream, indent_level: int) → None
writeCompositionCache(out: ostream, indent_level: int) → None

Writes a brief description of the composition cache and invert composition cache to the indicated ostream. This is not useful except for performance analysis, to examine the cache structure.

static getNumStates() → int

Returns the total number of unique TransformState objects allocated in the world. This will go up and down during normal operations.

static getNumUnusedStates() → int

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 listCycles() to get an idea of the number of actual “leaked” TransformState objects.

static clearCache() → int

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.

static garbageCollect() → int

Performs a garbage-collection cycle. This must be called periodically if garbage-collect-states is true to ensure that TransformStates get cleaned up appropriately. It does no harm to call it even if this variable is not true, but there is probably no advantage in that case.

static listCycles(out: ostream) → None

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 clearCache(); but they will not be reclaimed automatically.

static listStates(out: ostream) → None

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.

static validateStates() → bool

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).

static getStates() → object
static getUnusedStates() → object
static getClassType() → TypeHandle
Return type

TypeHandle

property pos

Returns the pos component of the transform. It is an error to call this if hasPos() returned false.

Return type

LPoint3

property hpr

Returns the rotation component of the transform as a trio of Euler angles. It is an error to call this if hasComponents() returned false.

Return type

LVecBase3

property quat

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 getNormQuat().

It is an error to call this if hasComponents() returned false.

Return type

LQuaternion

property norm_quat

Returns the rotation component of the transform as a quaternion. Unlike the result of getQuat(), the return value of this method is guaranteed to be normalized. It is an error to call this if hasComponents() returned false.

Return type

LQuaternion

property scale

Returns the scale component of the transform. It is an error to call this if hasComponents() returned false.

Return type

LVecBase3

property shear

Returns the shear component of the transform. It is an error to call this if hasComponents() returned false.

Return type

LVecBase3

property mat

Returns the matrix that describes the transform.

Return type

LMatrix4