Panda3D
Public Types | Public Member Functions | Static Public Member Functions | Public Attributes | List of all members
PartBundle Class Reference

This is the root of a MovingPart hierarchy. More...

Inheritance diagram for PartBundle:
PartGroup TypedWritableReferenceCount Namable TypedWritable ReferenceCount TypedObject CharacterJointBundle

Public Types

enum  BlendType { BT_linear = 0, BT_normalized_linear = 1, BT_componentwise = 2, BT_componentwise_quat = 3 }
 
- Public Types inherited from PartGroup
enum  HierarchyMatchFlags { HMF_ok_part_extra = 1, HMF_ok_anim_extra = 2, HMF_ok_wrong_root_name = 4 }
 

Public Member Functions

 __init__ (str name)
 Normally, a PartBundle constructor should not be called directly–it will get created when a PartBundleNode is created. More...
 
PartBundle applyTransform (const TransformState transform)
 Returns a PartBundle that is a duplicate of this one, but with the indicated transform applied. More...
 
AnimControl bindAnim (AnimBundle anim, int hierarchy_match_flags, const PartSubset subset)
 Binds the animation to the bundle, if possible, and returns a new AnimControl that can be used to start and stop the animation. More...
 
 clearAnimPreload ()
 Removes any AnimPreloadTable associated with the PartBundle. More...
 
 clearControlEffects ()
 Sets the control effect of all AnimControls to zero (but does not "stop" the AnimControls). More...
 
bool controlJoint (str joint_name, PandaNode node)
 Specifies that the joint with the indicated name should be animated with the transform on the indicated node. More...
 
bool forceUpdate ()
 Updates all the parts in the bundle to reflect the data for the current frame, whether we believe it needs it or not. More...
 
bool freezeJoint (str joint_name, const LVecBase3 pos, const LVecBase3 hpr, const LVecBase3 scale)
 Specifies that the joint with the indicated name should be frozen with the specified transform. More...
 
bool freezeJoint (str joint_name, float value)
 Specifies that the joint with the indicated name should be frozen with the specified transform. More...
 
bool freezeJoint (str joint_name, const TransformState transform)
 Specifies that the joint with the indicated name should be frozen with the specified transform. More...
 
bool getAnimBlendFlag ()
 Returns whether the character allows multiple different animations to be bound simultaneously. More...
 
const AnimPreloadTable getAnimPreload ()
 Returns the AnimPreloadTable associated with the PartBundle. More...
 
PartBundle::BlendType getBlendType ()
 Returns the algorithm that is used when blending multiple frames or multiple animations together, when either anim_blend_flag or frame_blend_flag is set to true. More...
 
float getControlEffect (AnimControl control)
 Returns the amount by which the character is affected by the indicated AnimControl and its associated animation. More...
 
bool getFrameBlendFlag ()
 Returns whether the character interpolates (blends) between two sequential animation frames, or whether it holds the current frame until the next one is ready. More...
 
PartBundleNode getNode (int n)
 Returns the nth PartBundleNode associated with this PartBundle. More...
 
list getNodes ()
 
int getNumNodes ()
 Returns the number of PartBundleNodes that contain a pointer to this PartBundle. More...
 
const LMatrix4 getRootXform ()
 Returns the transform matrix which is implicitly applied at the root of the animated hierarchy. More...
 
AnimControl loadBindAnim (Loader loader, const Filename filename, int hierarchy_match_flags, const PartSubset subset, bool allow_async)
 Binds an animation to the bundle. More...
 
 mergeAnimPreloads (const PartBundle other)
 Copies the contents of the other PartBundle's preload table into this one. More...
 
AnimPreloadTable modifyAnimPreload ()
 Returns a modifiable pointer to the AnimPreloadTable associated with the PartBundle, if any. More...
 
 output (Ostream out)
 Writes a one-line description of the bundle. More...
 
bool releaseJoint (str joint_name)
 Releases the named joint from the effects of a previous call to freeze_joint() or control_joint(). More...
 
 setAnimBlendFlag (bool anim_blend_flag)
 Defines the way the character responds to multiple calls to set_control_effect()). More...
 
 setAnimPreload (AnimPreloadTable table)
 Replaces the AnimPreloadTable associated with the PartBundle. More...
 
 setBlendType (PartBundle::BlendType bt)
 Defines the algorithm that is used when blending multiple frames or multiple animations together, when either anim_blend_flag or frame_blend_flag is set to true. More...
 
 setControlEffect (AnimControl control, float effect)
 Sets the amount by which the character is affected by the indicated AnimControl (and its associated animation). More...
 
 setFrameBlendFlag (bool frame_blend_flag)
 Specifies whether the character interpolates (blends) between two sequential frames of an active animation, showing a smooth intra-frame motion, or whether it holds each frame until the next frame is ready, showing precisely the specified animation. More...
 
 setRootXform (const LMatrix4 root_xform)
 Specifies the transform matrix which is implicitly applied at the root of the animated hierarchy. More...
 
bool update ()
 Updates all the parts in the bundle to reflect the data for the current frame (as set in each of the AnimControls). More...
 
 waitPending ()
 Blocks the current thread until all currently-pending AnimControls, with a nonzero control effect, have been loaded and are properly bound. More...
 
 xform (const LMatrix4 mat)
 Applies the indicated transform to the root of the animated hierarchy. More...
 
- Public Member Functions inherited from PartGroup
 __init__ (PartGroup parent, str name)
 Creates the PartGroup, and adds it to the indicated parent. More...
 
bool applyControl (PandaNode node)
 Specifies a node to influence this particular joint so that it will always hold the node's transform. More...
 
bool applyFreeze (const TransformState transform)
 Freezes this particular joint so that it will always hold the specified transform. More...
 
bool applyFreezeMatrix (const LVecBase3 pos, const LVecBase3 hpr, const LVecBase3 scale)
 Freezes this particular joint so that it will always hold the specified transform. More...
 
bool applyFreezeScalar (float value)
 Freezes this particular joint so that it will always hold the specified transform. More...
 
bool clearForcedChannel ()
 Undoes the effect of a previous call to apply_freeze() or apply_control(). More...
 
PartGroup copySubgraph ()
 Allocates and returns a new copy of this node and of all of its children. More...
 
PartGroup findChild (str name)
 Returns the first descendant found with the indicated name, or NULL if no such descendant exists. More...
 
PartGroup getChild (int n)
 Returns the nth child of the group. More...
 
PartGroup getChildNamed (str name)
 Returns the first child found with the indicated name, or NULL if no such child exists. More...
 
list getChildren ()
 
AnimChannelBase getForcedChannel ()
 Returns the AnimChannelBase that has been forced to this joint by a previous call to apply_freeze() or apply_control(), or NULL if no such channel has been applied. More...
 
int getNumChildren ()
 Returns the number of child nodes of the group. More...
 
bool isCharacterJoint ()
 Returns true if this part is a CharacterJoint, false otherwise. More...
 
PartGroup makeCopy ()
 Allocates and returns a new copy of the node. More...
 
 sortDescendants ()
 Sorts the children nodes at each level of the hierarchy into alphabetical order. More...
 
 write (Ostream out, int indent_level)
 Writes a brief description of the group and all of its descendants. More...
 
 writeWithValue (Ostream out, int indent_level)
 Writes a brief description of the group, showing its current value, and that of all of its descendants. More...
 
- Public Member Functions inherited from TypedWritable
object __reduce__ ()
 
object __reduce_persist__ (object pickler)
 
VectorUchar encodeToBamStream ()
 Converts the TypedWritable object into a single stream of data using a BamWriter, and returns that data as a bytes object. More...
 
bool encodeToBamStream (VectorUchar data, BamWriter writer)
 Converts the TypedWritable object into a single stream of data using a BamWriter, and stores that data in the indicated string. More...
 
 fillin (DatagramIterator scan, BamReader manager)
 This internal function is intended to be called by each class's make_from_bam() method to read in all of the relevant data from the BamFile for the new object. More...
 
UpdateSeq getBamModified ()
 Returns the current bam_modified counter. More...
 
 markBamModified ()
 Increments the bam_modified counter, so that this object will be invalidated and retransmitted on any open bam streams. More...
 
- Public Member Functions inherited from TypedObject
TypeHandle getType ()
 
int getTypeIndex ()
 Returns the internal index number associated with this object's TypeHandle, a unique number for each different type. More...
 
bool isExactType (TypeHandle handle)
 Returns true if the current object is the indicated type exactly. More...
 
bool isOfType (TypeHandle handle)
 Returns true if the current object is or derives from the indicated type. More...
 
- Public Member Functions inherited from ReferenceCount
int getRefCount ()
 Returns the current reference count. More...
 
 ref ()
 Explicitly increments the reference count. More...
 
bool testRefCountIntegrity ()
 Does some easy checks to make sure that the reference count isn't completely bogus. More...
 
bool testRefCountNonzero ()
 Does some easy checks to make sure that the reference count isn't zero, or completely bogus. More...
 
bool unref ()
 Explicitly decrements the reference count. More...
 
- Public Member Functions inherited from Namable
 __init__ (const Namable)
 
 __init__ (str initial_name)
 
 clearName ()
 Resets the Namable's name to empty. More...
 
str getName ()
 
bool hasName ()
 Returns true if the Namable has a nonempty name set, false if the name is empty. More...
 
 output (Ostream out)
 Outputs the Namable. More...
 
 setName (str name)
 

Static Public Member Functions

static TypeHandle getClassType ()
 
- Static Public Member Functions inherited from PartGroup
static TypeHandle getClassType ()
 
- Static Public Member Functions inherited from TypedWritableReferenceCount
static TypedWritableReferenceCount decodeFromBamStream (VectorUchar data, BamReader reader)
 Reads the bytes created by a previous call to encode_to_bam_stream(), and extracts and returns the single object on those bytes. More...
 
static TypeHandle getClassType ()
 
- Static Public Member Functions inherited from TypedWritable
static TypeHandle getClassType ()
 
- Static Public Member Functions inherited from TypedObject
static TypeHandle getClassType ()
 
- Static Public Member Functions inherited from ReferenceCount
static TypeHandle getClassType ()
 
- Static Public Member Functions inherited from Namable
static TypeHandle getClassType ()
 

Public Attributes

bool anim_blend_flag
 Returns whether the character allows multiple different animations to be bound simultaneously. More...
 
PartBundle::BlendType blend_type
 Returns the algorithm that is used when blending multiple frames or multiple animations together, when either anim_blend_flag or frame_blend_flag is set to true. More...
 
bool frame_blend_flag
 Returns whether the character interpolates (blends) between two sequential animation frames, or whether it holds the current frame until the next one is ready. More...
 
PartBundleNode nodes []
 
const LMatrix4 root_xform
 Returns the transform matrix which is implicitly applied at the root of the animated hierarchy. More...
 
- Public Attributes inherited from PartGroup
PartGroup children []
 
- Public Attributes inherited from TypedObject
TypeHandle type
 Returns the TypeHandle representing this object's type. More...
 
- Public Attributes inherited from ReferenceCount
int ref_count
 The current reference count. More...
 
- Public Attributes inherited from Namable
const String name
 

Detailed Description

This is the root of a MovingPart hierarchy.

It defines the hierarchy of moving parts that make up an animatable object.

Member Enumeration Documentation

◆ BlendType

enum BlendType
Enumerator
BT_linear 

BT_linear does a componentwise average of all blended matrices, which is a linear blend. The result of this is that if a particular vertex would have been at point P in one animation and point Q in another one, it will end up on the line in between them in the resulting blend animation. However, this tends to stretch and squash limbs in strange and disturbing ways.

BT_normalized_linear 

BT_normalized_linear is a compromise on BT_linear. The matrix is blended linearly without the scale and shear components, and the blended scale and shear components are applied separately. This keeps all of the character's body parts in the correct size and shape. However, if the hierarchy is disconnected, body parts can fly off. It's essential the skeleton hierarchy be completely connected to use this blend mode successully.

BT_componentwise 

BT_componentwise linearly blends all components separately, including H, P, and R, and recomposes the matrix.

BT_componentwise_quat 

BT_componentwise_quat linearly blends all components separately, except for rotation which is blended as a quaternion.

Member Function Documentation

◆ __init__()

__init__ ( str  name)

Normally, a PartBundle constructor should not be called directly–it will get created when a PartBundleNode is created.

◆ applyTransform()

PartBundle applyTransform ( const TransformState  transform)

Returns a PartBundle that is a duplicate of this one, but with the indicated transform applied.

If this is called multiple times with the same TransformState pointer, it returns the same PartBundle each time.

◆ bindAnim()

AnimControl bindAnim ( AnimBundle  anim,
int  hierarchy_match_flags,
const PartSubset  subset 
)

Binds the animation to the bundle, if possible, and returns a new AnimControl that can be used to start and stop the animation.

If the anim hierarchy does not match the part hierarchy, returns NULL.

If hierarchy_match_flags is 0, only an exact match is accepted; otherwise, it may contain a union of PartGroup::HierarchyMatchFlags values indicating conditions that will be tolerated (but warnings will still be issued).

If subset is specified, it restricts the binding only to the named subtree of joints.

The AnimControl is not stored within the PartBundle; it is the user's responsibility to maintain the pointer. The animation will automatically unbind itself when the AnimControl destructs (i.e. its reference count goes to zero).

◆ clearAnimPreload()

clearAnimPreload ( )

Removes any AnimPreloadTable associated with the PartBundle.

◆ clearControlEffects()

clearControlEffects ( )

Sets the control effect of all AnimControls to zero (but does not "stop" the AnimControls).

The character will no longer be affected by any animation, and will return to its default pose (unless restore-initial-pose is false).

The AnimControls which are no longer associated will not be using any CPU cycles, but they may still be in the "playing" state; if they are later reassociated with the PartBundle they will resume at their current frame as if they'd been running all along.

◆ controlJoint()

bool controlJoint ( str  joint_name,
PandaNode  node 
)

Specifies that the joint with the indicated name should be animated with the transform on the indicated node.

It will henceforth always follow the node's transform, regardless of any animations that may subsequently be bound to the joint.

Returns true if the joint is successfully controlled, or false if the named child is not a joint (or slider) or does not exist.

◆ forceUpdate()

bool forceUpdate ( )

Updates all the parts in the bundle to reflect the data for the current frame, whether we believe it needs it or not.

◆ freezeJoint() [1/3]

bool freezeJoint ( str  joint_name,
const LVecBase3  pos,
const LVecBase3  hpr,
const LVecBase3  scale 
)

Specifies that the joint with the indicated name should be frozen with the specified transform.

It will henceforth always hold this fixed transform, regardless of any animations that may subsequently be bound to the joint.

Returns true if the joint is successfully frozen, or false if the named child is not a joint (or slider) or does not exist.

◆ freezeJoint() [2/3]

bool freezeJoint ( str  joint_name,
float  value 
)

Specifies that the joint with the indicated name should be frozen with the specified transform.

It will henceforth always hold this fixed transform, regardless of any animations that may subsequently be bound to the joint.

Returns true if the joint is successfully frozen, or false if the named child is not a joint (or slider) or does not exist.

◆ freezeJoint() [3/3]

bool freezeJoint ( str  joint_name,
const TransformState  transform 
)

Specifies that the joint with the indicated name should be frozen with the specified transform.

It will henceforth always hold this fixed transform, regardless of any animations that may subsequently be bound to the joint.

Returns true if the joint is successfully frozen, or false if the named child is not a joint (or slider) or does not exist.

◆ getAnimBlendFlag()

bool getAnimBlendFlag ( )

Returns whether the character allows multiple different animations to be bound simultaneously.

See set_anim_blend_flag().

◆ getAnimPreload()

const AnimPreloadTable getAnimPreload ( )

Returns the AnimPreloadTable associated with the PartBundle.

This table, if present, can be used for the benefit of load_bind_anim() to allow asynchronous binding.

◆ getBlendType()

PartBundle::BlendType getBlendType ( )

Returns the algorithm that is used when blending multiple frames or multiple animations together, when either anim_blend_flag or frame_blend_flag is set to true.

◆ getClassType()

static TypeHandle getClassType ( )
static

◆ getControlEffect()

float getControlEffect ( AnimControl  control)

Returns the amount by which the character is affected by the indicated AnimControl and its associated animation.

See set_control_effect().

◆ getFrameBlendFlag()

bool getFrameBlendFlag ( )

Returns whether the character interpolates (blends) between two sequential animation frames, or whether it holds the current frame until the next one is ready.

See set_frame_blend_flag().

◆ getNode()

PartBundleNode getNode ( int  n)

Returns the nth PartBundleNode associated with this PartBundle.

◆ getNodes()

list getNodes ( )

◆ getNumNodes()

int getNumNodes ( )

Returns the number of PartBundleNodes that contain a pointer to this PartBundle.

◆ getRootXform()

const LMatrix4 getRootXform ( )

Returns the transform matrix which is implicitly applied at the root of the animated hierarchy.

◆ loadBindAnim()

AnimControl loadBindAnim ( Loader  loader,
const Filename  filename,
int  hierarchy_match_flags,
const PartSubset  subset,
bool  allow_async 
)

Binds an animation to the bundle.

The animation is loaded from the disk via the indicated Loader object. In other respects, this behaves similarly to bind_anim(), with the addition of asynchronous support.

If allow_aysnc is true, the load will be asynchronous if possible. This requires that the animation basename can be found in the PartBundle's preload table (see get_anim_preload()).

In an asynchronous load, the animation file will be loaded and bound in a sub-thread. This means that the animation will not necessarily be available at the time this method returns. You may still use the returned AnimControl immediately, though, but no visible effect will occur until the animation eventually becomes available.

You can test AnimControl::is_pending() to see if the animation has been loaded yet, or wait for it to finish with AnimControl::wait_pending() or even PartBundle::wait_pending(). You can also set an event to be triggered when the animation finishes loading with AnimControl::set_pending_done_event().

◆ mergeAnimPreloads()

mergeAnimPreloads ( const PartBundle  other)

Copies the contents of the other PartBundle's preload table into this one.

◆ modifyAnimPreload()

AnimPreloadTable modifyAnimPreload ( )

Returns a modifiable pointer to the AnimPreloadTable associated with the PartBundle, if any.

◆ output()

output ( Ostream  out)

Writes a one-line description of the bundle.

◆ releaseJoint()

bool releaseJoint ( str  joint_name)

Releases the named joint from the effects of a previous call to freeze_joint() or control_joint().

It will henceforth once again follow whatever transforms are dictated by the animation.

Returns true if the joint is released, or false if the named child was not previously controlled or frozen, or it does not exist.

◆ setAnimBlendFlag()

setAnimBlendFlag ( bool  anim_blend_flag)

Defines the way the character responds to multiple calls to set_control_effect()).

By default, this flag is set false, which disallows multiple animations. When this flag is false, it is not necessary to explicitly set the control_effect when starting an animation; starting the animation will implicitly remove the control_effect from the previous animation and set it on the current one.

However, if this flag is set true, the control_effect must be explicitly set via set_control_effect() whenever an animation is to affect the character.

◆ setAnimPreload()

setAnimPreload ( AnimPreloadTable  table)

Replaces the AnimPreloadTable associated with the PartBundle.

◆ setBlendType()

setBlendType ( PartBundle::BlendType  bt)

Defines the algorithm that is used when blending multiple frames or multiple animations together, when either anim_blend_flag or frame_blend_flag is set to true.

See partBundle.h for a description of the meaning of each of the BlendType values.

◆ setControlEffect()

setControlEffect ( AnimControl  control,
float  effect 
)

Sets the amount by which the character is affected by the indicated AnimControl (and its associated animation).

Normally, this will only be zero or one. Zero indicates the animation does not affect the character, and one means it does.

If the _anim_blend_flag is not false (see set_anim_blend_flag()), it is possible to have multiple AnimControls in effect simultaneously. In this case, the effect is a weight that indicates the relative importance of each AnimControl to the final animation.

◆ setFrameBlendFlag()

setFrameBlendFlag ( bool  frame_blend_flag)

Specifies whether the character interpolates (blends) between two sequential frames of an active animation, showing a smooth intra-frame motion, or whether it holds each frame until the next frame is ready, showing precisely the specified animation.

When this value is false, the character holds each frame until the next is ready. When this is true, the character will interpolate between two consecutive frames of animation for each frame the animation is onscreen, according to the amount of time elapsed between the frames.

The default value of this flag is determined by the interpolate-frames Config.prc variable.

Use set_blend_type() to change the algorithm that the character uses to interpolate matrix positions.

◆ setRootXform()

setRootXform ( const LMatrix4  root_xform)

Specifies the transform matrix which is implicitly applied at the root of the animated hierarchy.

◆ update()

bool update ( )

Updates all the parts in the bundle to reflect the data for the current frame (as set in each of the AnimControls).

Returns true if any part has changed as a result of this, or false otherwise.

◆ waitPending()

waitPending ( )

Blocks the current thread until all currently-pending AnimControls, with a nonzero control effect, have been loaded and are properly bound.

◆ xform()

xform ( const LMatrix4  mat)

Applies the indicated transform to the root of the animated hierarchy.

Member Data Documentation

◆ anim_blend_flag

bool anim_blend_flag

Returns whether the character allows multiple different animations to be bound simultaneously.

See set_anim_blend_flag().

◆ blend_type

Returns the algorithm that is used when blending multiple frames or multiple animations together, when either anim_blend_flag or frame_blend_flag is set to true.

◆ frame_blend_flag

bool frame_blend_flag

Returns whether the character interpolates (blends) between two sequential animation frames, or whether it holds the current frame until the next one is ready.

See set_frame_blend_flag().

◆ nodes

PartBundleNode nodes[]

◆ root_xform

const LMatrix4 root_xform

Returns the transform matrix which is implicitly applied at the root of the animated hierarchy.