superdex::Actor Class Reference

Represents a simulated body (actor) in a scene. More...

#include <mochi_actor.h>

Public Member Functions
virtual void	AddArticulatedDeltaToPose (Span< real const > pose, Span< real const > deltaDofs, Span< real > outPose, Error &error) const =0
	Add a pose delta to a pose using joint-aware composition.
virtual void	AddArticulatedPoseController (PoseControllerParams const &params, Error &error)=0
	Add a pose controller to an articulated actor.
virtual void	AddBoundaryConditionConstrainedNodesAtRest (Error &error)=0
	Fix the "constrained nodes" at their world-space reference positions.
virtual void	AddBoundaryConditionConstrainedNodesAtRestPermanent (Error &error)=0
	Permanently fix the "constrained nodes" at their world-space reference positions.
virtual void	AddBoundaryConditionDofsWorld (Span< int const > dofIndices, Span< real const > dofValuesWorld, Error &error)=0
	Add boundary conditions to specified DoFs.
virtual void	AddBoundaryConditionDofsWorldPermanent (Span< int const > dofIndices, Span< real const > dofValuesWorld, Error &error)=0
	Add permanent boundary conditions to specified DoFs.
virtual void	AddBoundaryConditionNodesWorld (Span< int const > nodeIndices, Span< real const > nodePositionsWorld, Error &error)=0
	Add world-space boundary conditions for specified nodes.
virtual void	AddBoundaryConditionNodesWorldPermanent (Span< int const > nodeIndices, Span< real const > nodePositionsWorld, Error &error)=0
	Add permanent world-space boundary conditions for specified nodes.
virtual void	CancelQuery (QueryHandle handle)=0
	Cancel a previously registered query.
virtual void	ClearBoundaryConditions ()=0
	Remove all clearable boundary conditions previously added.
virtual void	ClearExternalForces ()=0
	Remove all the external forces previously added.
virtual void	ComputeArticulatedPoseDelta (Span< real const > poseBase, Span< real const > poseTarget, Span< real > outDeltaDofs, Error &error) const =0
	Compute the pose delta from a base pose to a target pose.
virtual Aabb	GetAabbLocal (Error &error) const =0
	Get an axis-aligned bounding box (AABB) that contains the full volume of the actor, in the actor's local frame.
virtual Aabb	GetAabbWorld (Error &error) const =0
	Get an axis-aligned bounding box (AABB) that contains the full volume of the actor, in world frame.
virtual Real3	GetAngularVelocity (Error &error) const =0
	Get the angular velocity of the actor in world frame.
virtual ActorHandle	GetArticulatedActor (Error &error) const =0
	Get the owning articulated actor.
virtual Span< real const >	GetArticulatedControllerForce (Error &error) const =0
	Get the generalized forces applied by the pose controller on each joint DoF.
virtual void	GetArticulatedDofLimits (Span< Real2 > outDofLimits, Error &error) const =0
	Get the limit values on all DoFs of the articulated actor.
virtual Span< real const >	GetArticulatedJacobian (Error &error) const =0
	Get the Jacobian with respect to the articulated DoFs in world frame.
virtual Span< ArticulatedJointFrictionParams const >	GetArticulatedJointFrictionParams (Error &error) const =0
	Get the per-joint friction parameters of the articulated actor.
virtual Span< real const >	GetArticulatedJointInertiaParams (Error &error) const =0
	Get the per-joint inertia coefficients of the articulated actor.
virtual Span< Constraint *const >	GetArticulatedJointLimitConstraints (Error &error) const =0
	Get the joint-limit constraints of the articulated actor.
virtual void	GetArticulatedJointVelocities (Span< real > outVelocities, Error &error) const =0
	Get time derivatives of the articulated actor DoFs.
virtual void	GetArticulatedLinkTransforms (Span< TransformRT > outWorldFromLinks, Error &error) const =0
	Get the pose of an articulated actor expressed as world-from-local link transforms.
virtual void	GetArticulatedPose (Span< real > outPose, Error &error) const =0
	Get the pose of an articulated actor expressed as joint DoFs.
virtual Span< PoseConstraintInfo const >	GetArticulatedPoseConstraints (Error &error) const =0
	Get the pose controller's constraints.
virtual void	GetArticulatedPoseControllerParams (PoseControllerParams &outParams, Error &error) const =0
	Get the pose controller's tracking parameters.
virtual void	GetArticulatedPoseDistance (Span< real const > poseA, Span< real const > poseB, Span< real > outTransDistances, Span< real > outRotDistances, Error &error) const =0
	Compute per-joint distances between two poses.
virtual ArticulatedShapeInfo	GetArticulatedShapeInfo (Error &error) const =0
	Get articulated shape information about the articulated actor.
virtual void	GetArticulatedTargetLinkTransforms (Span< TransformRT > outWorldFromTargets, Error &error) const =0
	Get the last target pose set to the pose controller, expressed as link transforms.
virtual void	GetArticulatedTargetPose (Span< real > outPose, Error &error) const =0
	Get the last target pose set to the pose controller.
virtual Span< int const >	GetBoundaryConditionDofIndices () const =0
	Get the DoF indices that are constrained by boundary conditions.
virtual Span< real const >	GetBoundaryConditionDofValuesWorld () const =0
	Get the target values of DoFs fixed by boundary conditions.
virtual TransformRT	GetCenterOfMassTransform (Error &error) const =0
	Get the world-space transform of the actor expressed at the center of mass.
virtual ColliderType	GetColliderType () const =0
	Get the collider type of the actor.
virtual Real3	GetContactForceFromActorWorld (Actor const *other, Error &error) const =0
	Get the total contact force on the actor from another specified actor.
virtual Real3	GetContactForceWorld (Error &error) const =0
	Get the total contact force on the actor.
virtual std::string_view	GetContactLayer () const =0
	Get the name of the contact layer of the actor.
virtual ContactParams	GetContactParams (Error &error) const =0
	Get the contact parameters of the actor.
virtual Span< ContactPoint const >	GetContactPointsWorld (Error &error) const =0
	Get all the active contact points of the actor.
virtual Real3	GetContactTorqueWorld (Error &error) const =0
	Get the total contact torque about the center of mass.
virtual Context const *	GetContext () const =0
	Get read-only access to the Context that owns this actor.
virtual Context *	GetContext ()=0
	Get the Context that owns this actor.
virtual ConvergenceStatus	GetConvergenceStatus () const =0
	Get the convergence status of the actor in the most recent simulation step.
virtual real	GetDensity (Error &error) const =0
	Get the density of the actor in the undeformed configuration.
virtual Span< real const >	GetDisplacements (Error &error) const =0
	Get the node displacements of the actor in the actor's local frame, relative to reference (rest) positions.
virtual void	GetDofValues (Span< int const > dofIndices, Span< real > outDofValues, Error &error) const =0
	Get the current value of the actor's degrees of freedom (DoFs) corresponding to the specified indices.
virtual real	GetElasticEnergy (Error &error) const =0
	Get the elastic energy of the actor, measured as the difference with respect to the rest state.
virtual Span< real const >	GetElementsDeformationGradient (Error &error) const =0
	Get the deformation gradient of each element.
virtual void	GetExternalForces (Span< real > outForces, Error &error)=0
	Get the external forces currently set on this actor as a dense array over all DoFs.
virtual ActorHandle	GetHandle () const =0
	Get the actor's handle.
virtual Real3	GetLinearVelocity (Error &error) const =0
	Get the linear velocity of the actor in world frame.
virtual real	GetMass (Error &error) const =0
	Get the total mass of the actor.
virtual MeshDataView	GetMesh () const =0
	Get a view of the actor's reference simulation mesh.
virtual char const *	GetName () const =0
	Get the name of the actor.
virtual Span< ActorHandle const >	GetNestedLinkActors (Error &error) const =0
	Get the actor handles for the nested rigid link actors.
virtual Span< ActorHandle const >	GetNestedSoftActors (Error &error) const =0
	Get the actor handles for the nested soft actors (if any).
virtual Span< NodeContactForce const >	GetNodeContactForcesWorld (Error &error) const =0
	Get contact forces on nodes.
virtual Span< real const >	GetNodePositionsLocal (Error &error) const =0
	Get the current position (reference + displacements) of each node in the actor's local frame.
virtual int	GetNumDofs () const =0
	Get the number of degrees of freedom (DoFs) of the actor.
virtual void	GetPointsDistanceToSurface (Span< Real3 const > pointsWorld, Span< real > outDistances, Error &error) const =0
	Query the signed distance to the closest point on the actor's surface.
virtual RecenteringParams	GetRecenteringParams () const =0
	Gets the recentering parameters of the actor.
virtual ShapeHandle	GetReferenceShape (Error &error) const =0
	Get a new ShapeHandle referencing the same shape data used to create this actor.
virtual Real3	GetRigidCenterOfMassLocal (Error &error) const =0
	Get the position of the center of mass in the actor's local coordinate frame (GetRootTransform).
virtual Real6	GetRigidMomentOfInertiaLocal (Error &error) const =0
	Get the moment of inertia tensor of the actor at the center of mass, aligned with the actor's local reference system (root transform), and using negative tensor notation.
virtual TransformRT	GetRootTransform () const =0
	Get the actor's world-from-local transform (root transform).
virtual Scene const *	GetScene () const =0
	Get the Scene that this actor belongs to (read only).
virtual Scene *	GetScene ()=0
	Get the Scene that this actor belongs to.
virtual SdfDistances	GetSdfDistances (Error &error) const =0
	Get SDF distances for contact sample points.
virtual SoftMaterialParams	GetSoftMaterialParams (Error &error) const =0
	Get the material parameters of a soft actor.
virtual MeshDataView	GetSurfaceMesh () const =0
	Get a view of the actor's reference surface mesh.
virtual Span< real const >	GetSurfaceMeshNodeNormalsLocal (Error &error) const =0
	Get the normal direction for each node of the surface mesh in the actor's local frame.
virtual Span< real const >	GetSurfaceMeshNodePositionsLocal (Error &error) const =0
	Get the current position of the nodes (reference + displacements) of the surface mesh in the actor's local frame.
virtual ActorType	GetType () const =0
	Get the type of the actor.
virtual void *	GetUserData () const =0
	Get application-specific user data for this actor.
virtual MeshDataView	GetVisualMesh () const =0
	Get a view of the actor's reference visual mesh.
virtual Span< real const >	GetVisualMeshNodeNormalsLocal (Error &error) const =0
	Get the normal direction to each node of the visual mesh in the actor's local frame.
virtual Span< real const >	GetVisualMeshNodePositionsLocal (Error &error) const =0
	Get the current position (reference + displacements) of the nodes of the visual mesh in the actor's local frame.
virtual bool	HasArticulatedPoseController (Error &error) const =0
	Check if the articulated actor has a pose controller.
virtual bool	HasRootTransform () const =0
	Check if the actor has a root transform.
virtual bool	IsNestedLinkActor () const =0
	Check if the actor is a rigid link within an articulated actor.
virtual bool	IsNestedSoftActor () const =0
	Check if the actor is a soft actor nested within a soft skinned articulated actor.
virtual bool	IsQuerySupported (QueryType type) const =0
	Check whether a query type is supported for this actor.
virtual bool	IsStatic () const =0
	Check whether the actor is static.
virtual void	QueryNodesInVolumeLocal (Aabb const &volume, bool boundaryOnly, std::function< void(int, Real3)> const &callback, Error &error) const =0
	Find the actor's nodes that are inside an axis-aligned bounding box (AABB).
virtual void	QueryNodesInVolumeLocal (Obb const &volume, bool boundaryOnly, std::function< void(int, Real3)> const &callback, Error &error) const =0
	Find the actor's nodes that are inside an oriented bounding box (OBB).
virtual void	QueryNodesInVolumeLocal (Sphere const &volume, bool boundaryOnly, std::function< void(int, Real3)> const &callback, Error &error) const =0
	Find the actor's nodes that are inside a sphere.
virtual QueryHandle	RegisterQuery (QueryType type, Error &error)=0
	Register a query to compute data for this actor.
virtual QueryHandle	RegisterQueryAndCompute (QueryType type, Error &error)=0
	Register a query for this actor and compute the result immediately.
virtual void	RemoveArticulatedPoseController (Error &error)=0
	Remove the pose controller.
virtual void	ResetArticulatedTargetLinkTransforms (Span< TransformRT const > worldFromTargets, Error &error)=0
	Reset the target pose of the controller expressed as link transforms.
virtual void	ResetArticulatedTargetPose (Span< real const > pose, Error &error)=0
	Reset the target pose of the controller expressed as joint DoFs.
virtual void	SetArticulatedJointFrictionParams (Span< ArticulatedJointFrictionParams const > friction, Error &error)=0
	Set the per-joint friction parameters of the articulated actor.
virtual void	SetArticulatedJointInertiaParams (Span< real const > inertia, Error &error)=0
	Set the per-joint inertia coefficients of the articulated actor.
virtual void	SetArticulatedJointVelocities (Span< real const > velocities, Error &error)=0
	Set time derivatives of the articulated actor DoFs.
virtual void	SetArticulatedPoseControllerParams (PoseControllerParams const &params, Error &error)=0
	Set the pose controller's tracking parameters.
virtual void	SetArticulatedPoseFromJoints (Span< real const > pose, Error &error)=0
	Set the pose of an articulated actor from joint DoFs.
virtual void	SetArticulatedPoseFromLinks (Span< TransformRT const > worldFromLinks, Error &error)=0
	Set the pose of an articulated actor from the world-from-local link transforms.
virtual void	SetArticulatedTargetLinkTransforms (Span< TransformRT const > worldFromTargets, Error &error)=0
	Set the target pose for the controller expressed as link transforms.
virtual void	SetArticulatedTargetPose (Span< real const > pose, Error &error)=0
	Set the target pose for the controller expressed as joint DoFs.
virtual void	SetArticulatedTargetVelocity (Span< real const > velocity, Error &error)=0
	Set the target velocity of the controller expressed as joint velocities for the next simulation step.
virtual void	SetCenterOfMassTransform (TransformRT const &worldFromCom, Error &error)=0
	Set the world-space transform of the actor expressed at the center of mass.
virtual void	SetContactLayer (std::string_view const &layer)=0
	Set the name of the contact layer of the actor.
virtual void	SetContactParams (ContactParams const &params, Error &error)=0
	Set the contact parameters of the actor.
virtual void	SetDensity (real density, Error &error)=0
	Set the density of the actor in the undeformed configuration.
virtual void	SetDisplacements (Span< real const > displacements, Error &error)=0
	Set the node displacements in the actor's local frame, relative to reference (rest) positions.
virtual void	SetExternalForcesOnDofs (Span< int const > dofIndices, Span< real const > forceValues, Error &error)=0
	Set external forces on specified DoFs.
virtual void	SetInertiaProperties (real mass, Real3 const &centerOfMass, Real6 const &momentOfInertia, Error &error)=0
	Set the mass properties of the actor.
virtual void	SetNodePositionsLocal (Span< real const > positionsLocal, Error &error)=0
	Set the current position of each node (reference + displacements) in the actor's local frame.
virtual void	SetNodeVelocitiesLocal (Span< real const > velocitiesLocal, Error &error)=0
	Set the current velocity of each node in the actor's local frame.
virtual void	SetRecenteringParams (RecenteringParams const &params, Error &error)=0
	Set the recentering parameters of the actor.
virtual void	SetRootTransform (TransformRT const &worldFromLocal, Error &error)=0
	Set the actor's world-from-local transform (root transform).
virtual void	SetSoftMaterialParams (SoftMaterialParams const &params, Error &error)=0
	Set the material parameters of a soft actor.
virtual void	SetUserData (void *userData)=0
	Set application-specific user data for this actor.
virtual void	SetVelocity (Real3 const &linearVel, Real3 const &angularVel, Error &error)=0
	Set the world-frame linear and angular velocity of the actor at the center of mass.
virtual void	SetZeroDisplacementsAndVelocities (Error &error)=0
	Set all local displacement and velocity DoFs to zero.

Protected Member Functions
virtual	~Actor ()=default

Detailed Description

Represents a simulated body (actor) in a scene.

Note

Every body in the simulation is an actor.

Actors always belong to exactly one scene.

Actors can be static or dynamic.

Warning

Concurrent access to the actor or its scene is illegal.

Definition at line 51 of file mochi_actor.h.

Constructor & Destructor Documentation

~Actor()

virtual superdex::Actor::~Actor ( )

protectedvirtualdefault

Member Function Documentation

AddArticulatedDeltaToPose()

virtual void superdex::Actor::AddArticulatedDeltaToPose ( Span< real const > pose, Span< real const > deltaDofs, Span< real > outPose, Error & error ) const

pure virtual

Add a pose delta to a pose using joint-aware composition.

Parameters

[in]	pose	Base pose as joint DoFs. Must be of size GetNumDofs.
[in]	deltaDofs	Pose delta to add. Must be of size GetNumDofs.
[out]	outPose	Output pose after adding deltaDofs. Must be of size GetNumDofs.
[in,out]	error	Error status. Check Error::IsOK for success.

Note

Only applicable to articulated actors.

Deltas cannot be simply added to poses. This function uses joint information to correctly add the delta.

Useful for adding time-stepped velocity to a reference pose.

For 3D rotations, delta values are interpreted as Lie-algebra rotation-vector increments.

For 3D rotations, angular velocity is not directly the time derivative of the rotation vector representation.

See also

ComputeArticulatedPoseDelta, GetArticulatedPose, GetArticulatedPoseDistance

AddArticulatedPoseController()

virtual void superdex::Actor::AddArticulatedPoseController ( PoseControllerParams const & params, Error & error )

pure virtual

Add a pose controller to an articulated actor.

Parameters

[in]	params	Parameters defining the pose controller.
[in,out]	error	Error status. Check Error::IsOK for success.

Note

Only applicable to articulated actors.

Only one pose controller is allowed per actor. Adding a second controller raises an error.

The initial target pose and target velocity are set to the actor's current pose and velocity.

Empty tracking arrays are allowed. Default zero-gain parameters are used for any empty array.

See also

RemoveArticulatedPoseController, HasArticulatedPoseController

AddBoundaryConditionConstrainedNodesAtRest()

virtual void superdex::Actor::AddBoundaryConditionConstrainedNodesAtRest ( Error & error )

pure virtual

Fix the "constrained nodes" at their world-space reference positions.

Parameters

[in,out]

error

Error status. Check Error::IsOK for success.

Note

Only supported for soft and shell actors, except nested soft actors (see GetNestedSoftActors).

Not supported in differentiable scenes (diffsim::MakeSceneDifferentiable) or for ROM actors.

Boundary conditions can be cleared with ClearBoundaryConditions.

Applies to constrained nodes specified by the actor's mesh. Has no effect if none are specified.

Each target position is computed by transforming the node's mesh reference coordinate by the actor's root transform.

This API adds to existing boundary conditions. See AddBoundaryConditionDofsWorld for behavior when a DoF has more than one entry.

Warning

If the actor's mesh has constrained nodes, calling this repeatedly without clearing re-adds the same boundary conditions and grows the per-step cost without bound. See AddBoundaryConditionDofsWorld.

See also

ClearBoundaryConditions, AddBoundaryConditionConstrainedNodesAtRestPermanent, AddBoundaryConditionDofsWorld

AddBoundaryConditionConstrainedNodesAtRestPermanent()

virtual void superdex::Actor::AddBoundaryConditionConstrainedNodesAtRestPermanent ( Error & error )

pure virtual

Permanently fix the "constrained nodes" at their world-space reference positions.

Parameters

[in,out]

error

Error status. Check Error::IsOK for success.

Note

Only supported for soft and shell actors, except nested soft actors (see GetNestedSoftActors).

Not supported in differentiable scenes (diffsim::MakeSceneDifferentiable) or for ROM actors.

Same as AddBoundaryConditionConstrainedNodesAtRest, except boundary conditions cannot be cleared.

See AddBoundaryConditionDofsWorldPermanent for interaction with clearable entries later added to the same DoF.

Warning

If the actor's mesh has constrained nodes, each call adds a permanent boundary condition for every constrained node. Call this at most once. Repeated calls create duplicates that cannot be removed and irreversibly grow the per-step cost. See AddBoundaryConditionDofsWorldPermanent.

See also

AddBoundaryConditionConstrainedNodesAtRest, AddBoundaryConditionDofsWorldPermanent

AddBoundaryConditionDofsWorld()

virtual void superdex::Actor::AddBoundaryConditionDofsWorld ( Span< int const > dofIndices, Span< real const > dofValuesWorld, Error & error )

pure virtual

Add boundary conditions to specified DoFs.

Parameters

[in]	dofIndices	DoF indices to constrain.
[in]	dofValuesWorld	Target values in the actor-specific representations described below. Length must equal dofIndices.
[in,out]	error	Error status. Check Error::IsOK for success.

Note

Not supported for nested soft actors (see GetNestedSoftActors).

Not supported in differentiable scenes (diffsim::MakeSceneDifferentiable) or for ROM actors.

For soft and shell actors, each node has 3 consecutive DoFs containing its target x, y, and z position [m] in the world frame. All 3 must be specified together. Consider AddBoundaryConditionNodesWorld as a more convenient alternative.

For rigid and articulated actors, the DoF indices within each call must be sorted in strictly increasing order (no duplicate indices).

Rigid actors have 6 DoFs: indices 0-2 are the target world-space center-of-mass position [m], and indices 3-5 are the target world-from-local orientation as a rotation vector (axis multiplied by angle [rad]). Either all or none of the 3 rotation DoFs must be specified.

Articulated actors have a number of DoFs that depends on the number of joints and the DoFs per joint. When setting boundary conditions on the rotation of a free or spherical joint, either all or none of the 3 DoFs must be specified.

Rod actors have 4 DoFs per node: the first 3 values are the target node x, y, and z position [m] in the world frame, followed by the next element's scalar twist angle [rad]. (For open rods, the last DoF, i.e., the final node's twist DoF, is included for padding only, does not affect the physics, and is automatically constrained to zero. This automatic constraint is not reported by GetBoundaryConditionDofIndices. For closed-loop rods, all twist DoFs are physical.) Boundary conditions on a rod node's position must specify all 3 consecutive displacement DoFs for that node. Only zero values are allowed for the scalar twist angle in this function, with the interpretation that the element's cross-section material axes rotate by only the minimal amount needed to remain orthogonal to the rod's centerline. More elaborate control over rod element rotations should use constraints instead of boundary conditions.

Boundary condition APIs add to existing boundary conditions; they do not replace existing entries. If a DoF has more than one entry, getter APIs return all entries in the order they were added, and the most recently added value is the effective value during the step.

Boundary conditions can be cleared with ClearBoundaryConditions.

Warning

Constrained 3D rotations may exhibit small numerical differences due to differences in the internal representation.

Adding a boundary condition to the same DoF more than once is legal — the most recently added value wins — but strongly discouraged. Each call adds an entry, so repeatedly re-adding without an intervening ClearBoundaryConditions grows the per-step cost without bound. To update a boundary condition, call ClearBoundaryConditions and add it again.

See also

ClearBoundaryConditions, AddBoundaryConditionNodesWorld, AddBoundaryConditionDofsWorldPermanent, GetBoundaryConditionDofIndices, GetBoundaryConditionDofValuesWorld

AddBoundaryConditionDofsWorldPermanent()

virtual void superdex::Actor::AddBoundaryConditionDofsWorldPermanent ( Span< int const > dofIndices, Span< real const > dofValuesWorld, Error & error )

pure virtual

Add permanent boundary conditions to specified DoFs.

Parameters

[in]	dofIndices	DoF indices to constrain.
[in]	dofValuesWorld	Target values in the actor-specific representations documented by AddBoundaryConditionDofsWorld. Length must equal dofIndices.
[in,out]	error	Error status. Check Error::IsOK for success.

Note

Not supported for nested soft actors (see GetNestedSoftActors).

Not supported in differentiable scenes (diffsim::MakeSceneDifferentiable) or for ROM actors.

Same as AddBoundaryConditionDofsWorld, except boundary conditions cannot be cleared.

If a clearable entry is later added for the same DoF, that clearable entry is the effective value until ClearBoundaryConditions removes it. The permanent entry is then the effective value again.

Warning

Permanent boundary conditions are retained for the lifetime of the actor and cannot be removed by ClearBoundaryConditions. Adding a permanent boundary condition to the same DoF more than once is legal but strongly discouraged. The duplicates can never be cleared and irreversibly grow the per-step cost. Add each permanent boundary condition only once.

See also

AddBoundaryConditionDofsWorld

AddBoundaryConditionNodesWorld()

virtual void superdex::Actor::AddBoundaryConditionNodesWorld ( Span< int const > nodeIndices, Span< real const > nodePositionsWorld, Error & error )

pure virtual

Add world-space boundary conditions for specified nodes.

Parameters

[in]	nodeIndices	Node indices to constrain.
[in]	nodePositionsWorld	Target positions [m] in world frame. Length must be 3 times the size of nodeIndices.
[in,out]	error	Error status. Check Error::IsOK for success.

Note

Only supported for soft and shell actors, except nested soft actors (see GetNestedSoftActors).

Not supported in differentiable scenes (diffsim::MakeSceneDifferentiable) or for ROM actors.

Boundary conditions can be cleared with ClearBoundaryConditions.

Equivalent to calling AddBoundaryConditionDofsWorld with DoF indices (3*i, 3*i+1, 3*i+2) for each node i.

This API adds to existing boundary conditions. See AddBoundaryConditionDofsWorld for behavior when a DoF has more than one entry.

Warning

Adding boundary conditions to the same nodes repeatedly without clearing grows the per-step cost without bound. See AddBoundaryConditionDofsWorld.

See also

ClearBoundaryConditions, AddBoundaryConditionDofsWorld, AddBoundaryConditionNodesWorldPermanent, GetBoundaryConditionDofIndices, GetBoundaryConditionDofValuesWorld

AddBoundaryConditionNodesWorldPermanent()

virtual void superdex::Actor::AddBoundaryConditionNodesWorldPermanent ( Span< int const > nodeIndices, Span< real const > nodePositionsWorld, Error & error )

pure virtual

Add permanent world-space boundary conditions for specified nodes.

Parameters

[in]	nodeIndices	Node indices to constrain.
[in]	nodePositionsWorld	Target positions [m] in world frame. Length must be 3 times the size of nodeIndices.
[in,out]	error	Error status. Check Error::IsOK for success.

Note

Only supported for soft and shell actors, except nested soft actors (see GetNestedSoftActors).

Not supported in differentiable scenes (diffsim::MakeSceneDifferentiable) or for ROM actors.

Same as AddBoundaryConditionNodesWorld, except boundary conditions cannot be cleared.

See AddBoundaryConditionDofsWorldPermanent for interaction with clearable entries later added to the same DoF.

Warning

Add each permanent boundary condition only once. Duplicates can never be cleared and irreversibly grow the per-step cost. See AddBoundaryConditionDofsWorldPermanent.

See also

AddBoundaryConditionNodesWorld, AddBoundaryConditionDofsWorldPermanent

CancelQuery()

virtual void superdex::Actor::CancelQuery ( QueryHandle handle )

pure virtual

Cancel a previously registered query.

Parameters

[in]

handle

QueryHandle from RegisterQuery or RegisterQueryAndCompute.

Note

Cancelling an invalid or already-cancelled handle has no effect.

Cancelling queries may improve memory usage and/or performance if the query is no longer needed.

See also

RegisterQuery, RegisterQueryAndCompute

ClearBoundaryConditions()

virtual void superdex::Actor::ClearBoundaryConditions ( )

pure virtual

Remove all clearable boundary conditions previously added.

Note

To replace existing clearable boundary conditions, call this before adding the new boundary-condition set.

May invalidate spans previously returned by GetBoundaryConditionDofIndices and GetBoundaryConditionDofValuesWorld. Do not retain them across this call.

Permanent entries are retained, but this call may change their positions in spans returned by GetBoundaryConditionDofIndices and GetBoundaryConditionDofValuesWorld. Do not cache those positions across this call.

See also

AddBoundaryConditionDofsWorld, AddBoundaryConditionNodesWorld, AddBoundaryConditionConstrainedNodesAtRest

ClearExternalForces()

virtual void superdex::Actor::ClearExternalForces ( )

pure virtual

Remove all the external forces previously added.

See also

SetExternalForcesOnDofs

ComputeArticulatedPoseDelta()

virtual void superdex::Actor::ComputeArticulatedPoseDelta ( Span< real const > poseBase, Span< real const > poseTarget, Span< real > outDeltaDofs, Error & error ) const

pure virtual

Compute the pose delta from a base pose to a target pose.

Parameters

[in]	poseBase	Base pose as joint DoFs. Must be of size GetNumDofs.
[in]	poseTarget	Target pose as joint DoFs. Must be of size GetNumDofs.
[out]	outDeltaDofs	Pose delta. Must be of size GetNumDofs.
[in,out]	error	Error status. Check Error::IsOK for success.

Note

Only applicable to articulated actors.

Deltas cannot be simply subtracted between poses. This function uses joint information to correctly subtract the delta.

See also

AddArticulatedDeltaToPose, GetArticulatedPose, GetArticulatedPoseDistance

GetAabbLocal()

virtual Aabb superdex::Actor::GetAabbLocal ( Error & error ) const

nodiscardpure virtual

Get an axis-aligned bounding box (AABB) that contains the full volume of the actor, in the actor's local frame.

Parameters

[in,out]

error

Error status. Check Error::IsOK for success.

Returns

AABB in the actor's local frame containing the full actor volume.

GetAabbWorld()

virtual Aabb superdex::Actor::GetAabbWorld ( Error & error ) const

nodiscardpure virtual

Get an axis-aligned bounding box (AABB) that contains the full volume of the actor, in world frame.

Parameters

[in,out]

error

Error status. Check Error::IsOK for success.

Returns

AABB in world frame containing the full actor volume.

GetAngularVelocity()

virtual Real3 superdex::Actor::GetAngularVelocity ( Error & error ) const

nodiscardpure virtual

Get the angular velocity of the actor in world frame.

Parameters

[in,out]

error

Error status. Check Error::IsOK for success.

Returns

Angular velocity in world frame [rad/s].

Note

Only supported for rigid and soft actors.

For rigid actors, it returns the actual angular velocity.

For soft actors, it returns an estimate of the angular velocity of the root transform. Requires recentering to be enabled for accurate results.

Not supported for ROM actors.

GetArticulatedActor()

virtual ActorHandle superdex::Actor::GetArticulatedActor ( Error & error ) const

nodiscardpure virtual

Get the owning articulated actor.

Parameters

[in,out]

error

Error status. Check Error::IsOK for success.

Returns

Handle to the owning articulated actor.

Note

Only applicable to nested link or nested soft actors within articulated actors.

See also

IsNestedLinkActor, GetNestedLinkActors, IsNestedSoftActor, GetNestedSoftActors

GetArticulatedControllerForce()

virtual Span< real const > superdex::Actor::GetArticulatedControllerForce ( Error & error ) const

nodiscardpure virtual

Get the generalized forces applied by the pose controller on each joint DoF.

Parameters

[in,out]

error

Error status. Check Error::IsOK for success.

Returns

Flattened generalized-force vector for each joint DoF. Size equals GetNumDofs. Units are [N] for translational DoFs and [N·m] for rotational DoFs.

Note

Only applicable to articulated actors with a pose controller.

Requires registering QueryType::ArticulatedControllerForce before the simulation step. Results are available after the simulation step completes.

Requires the actor to support QueryType::ArticulatedControllerForce.

Equivalent to using QueryType::ConstraintForce on each of the pose controller's constraints and projecting the constraint forces through the link Jacobians to joint DoF space (i.e., Σ Jᵢᵀ · fᵢ for each pose constraint i).

If the solver diverged in the last simulation step, the returned generalized forces may be stale.

See also

RegisterQuery, QueryType::ArticulatedControllerForce

GetArticulatedDofLimits()

virtual void superdex::Actor::GetArticulatedDofLimits ( Span< Real2 > outDofLimits, Error & error ) const

pure virtual

Get the limit values on all DoFs of the articulated actor.

Parameters

[out]	outDofLimits	Output span for DoF limits. Must be of size GetNumDofs.
[in,out]	error	Error status. Check Error::IsOK for success.

Note

Only applicable to articulated actors.

Each element contains [min, max] limits for the corresponding DoF: [m] for translational DoFs and [rad] for rotational DoFs.

Unconstrained DoFs have limits of ±infinity.

See also

GetArticulatedJointLimitConstraints

GetArticulatedJacobian()

virtual Span< real const > superdex::Actor::GetArticulatedJacobian ( Error & error ) const

nodiscardpure virtual

Get the Jacobian with respect to the articulated DoFs in world frame.

Parameters

[in,out]

error

Error status. Check Error::IsOK for success.

Returns

Jacobian matrix in row-major order with shape [6, numArticulatedDoFs], where 6 is the number of rigid DoFs of the link (3 translation + 3 rotation) and numArticulatedDoFs is GetNumDofs of the owning articulated actor.

Note

Only applicable to nested link actors within articulated actors.

To get the Jacobian in the articulation's root frame, left-multiply the Jacobian by the 6×6 block-diagonal of the root-from-world rotation:

[ R  0 ] · J
[ 0  R ]

where R is the 3×3 root-from-world rotation matrix (i.e., the transpose of the owning articulated actor's world-from-root rotation).

See also

IsNestedLinkActor

GetArticulatedJointFrictionParams()

virtual Span< ArticulatedJointFrictionParams const > superdex::Actor::GetArticulatedJointFrictionParams ( Error & error ) const

nodiscardpure virtual

Get the per-joint friction parameters of the articulated actor.

Parameters

[in,out]

error

Error status. Check Error::IsOK for success.

Returns

Span of friction parameters, one per joint.

Note

Only applicable to articulated actors.

See also

SetArticulatedJointFrictionParams, ArticulatedJointFrictionParams

GetArticulatedJointInertiaParams()

virtual Span< real const > superdex::Actor::GetArticulatedJointInertiaParams ( Error & error ) const

nodiscardpure virtual

Get the per-joint inertia coefficients of the articulated actor.

Parameters

[in,out]

error

Error status. Check Error::IsOK for success.

Returns

Span of inertia coefficients, one per joint.

Note

Only applicable to articulated actors.

See also

SetArticulatedJointInertiaParams

GetArticulatedJointLimitConstraints()

virtual Span< Constraint *const > superdex::Actor::GetArticulatedJointLimitConstraints ( Error & error ) const

nodiscardpure virtual

Get the joint-limit constraints of the articulated actor.

Parameters

[in,out]

error

Error status. Check Error::IsOK for success.

Returns

Span of pointers to joint limit constraints.

Note

Only applicable to articulated actors.

See also

GetArticulatedDofLimits

GetArticulatedJointVelocities()

virtual void superdex::Actor::GetArticulatedJointVelocities ( Span< real > outVelocities, Error & error ) const

pure virtual

Get time derivatives of the articulated actor DoFs.

Parameters

[out]	outVelocities	Output span for DoF velocities: [m/s] for translational DoFs and [rad/s] for rotational DoFs. Must be of size GetNumDofs.
[in,out]	error	Error status. Check Error::IsOK for success.

Note

Only applicable to articulated actors.

See also

SetArticulatedJointVelocities

GetArticulatedLinkTransforms()

virtual void superdex::Actor::GetArticulatedLinkTransforms ( Span< TransformRT > outWorldFromLinks, Error & error ) const

pure virtual

Get the pose of an articulated actor expressed as world-from-local link transforms.

Parameters

[out]	outWorldFromLinks	Output span for pose as world-from-local links transforms. Must be of size equal to the number of links.
[in,out]	error	Error status. Check Error::IsOK for success.

Note

Only applicable to articulated actors.

See also

SetArticulatedPoseFromLinks, GetArticulatedPose

GetArticulatedPose()

virtual void superdex::Actor::GetArticulatedPose ( Span< real > outPose, Error & error ) const

pure virtual

Get the pose of an articulated actor expressed as joint DoFs.

Parameters

[out]	outPose	Output span for pose as joint DoFs: position [m] for translational DoFs and angle [rad] for rotational DoFs. Must be of size GetNumDofs.
[in,out]	error	Error status. Check Error::IsOK for success.

Note

Only applicable to articulated actors.

See also

SetArticulatedPoseFromJoints

GetArticulatedPoseConstraints()

virtual Span< PoseConstraintInfo const > superdex::Actor::GetArticulatedPoseConstraints ( Error & error ) const

nodiscardpure virtual

Get the pose controller's constraints.

Parameters

[in,out]

error

Error status. Check Error::IsOK for success.

Returns

Span of pose constraint information.

Note

Only applicable to articulated actors with a pose controller.

See also

PoseConstraintInfo, GetArticulatedPoseControllerParams, SetArticulatedPoseControllerParams

GetArticulatedPoseControllerParams()

virtual void superdex::Actor::GetArticulatedPoseControllerParams ( PoseControllerParams & outParams, Error & error ) const

pure virtual

Get the pose controller's tracking parameters.

Parameters

[in,out]	outParams	Output tracking parameters grouped by constraint type (PoseControllerParams::linkPosTracking, PoseControllerParams::linkRotTracking, PoseControllerParams::jointTracking). All three arrays are link-indexed and must be pre-sized to numLinks; they are not resized. Entries in PoseControllerParams::jointTracking for links without a controllable joint are reported as zero gains.
[in,out]	error	Error status. Check Error::IsOK for success.

Note

Only applicable to articulated actors with a pose controller.

See also

GetArticulatedPoseConstraints, SetArticulatedPoseControllerParams

GetArticulatedPoseDistance()

virtual void superdex::Actor::GetArticulatedPoseDistance ( Span< real const > poseA, Span< real const > poseB, Span< real > outTransDistances, Span< real > outRotDistances, Error & error ) const

pure virtual

Compute per-joint distances between two poses.

Parameters

[in]	poseA	First pose as joint DoFs. Must be of size GetNumDofs.
[in]	poseB	Second pose as joint DoFs. Must be of size GetNumDofs.
[out]	outTransDistances	Translation distances [m] for each joint. Must be of size equal to the number of joints.
[out]	outRotDistances	Rotation distances [rad] for each joint. Must be of size equal to the number of joints.
[in,out]	error	Error status. Check Error::IsOK for success.

Note

Only applicable to articulated actors.

Uses joint-specific distance metrics (Euclidean for translation, angle for rotation).

See also

GetArticulatedPose, AddArticulatedDeltaToPose, ComputeArticulatedPoseDelta

GetArticulatedShapeInfo()

virtual ArticulatedShapeInfo superdex::Actor::GetArticulatedShapeInfo ( Error & error ) const

nodiscardpure virtual

Get articulated shape information about the articulated actor.

Parameters

[in,out]

error

Error status. Check Error::IsOK for success.

Returns

Articulated shape information.

Note

Only applicable to articulated actors. Sets error otherwise.

This information never changes throughout the actor's lifetime.

See also

ArticulatedShapeInfo, Context::GetArticulatedShapeInfo

GetArticulatedTargetLinkTransforms()

virtual void superdex::Actor::GetArticulatedTargetLinkTransforms ( Span< TransformRT > outWorldFromTargets, Error & error ) const

pure virtual

Get the last target pose set to the pose controller, expressed as link transforms.

Parameters

[out]	outWorldFromTargets	Output span for the target world-from-link transforms. Must be of size equal to the number of links.
[in,out]	error	Error status. Check Error::IsOK for success.

Note

Only applicable to articulated actors with a pose controller.

See also

SetArticulatedTargetPose, SetArticulatedTargetLinkTransforms, GetArticulatedTargetPose

GetArticulatedTargetPose()

virtual void superdex::Actor::GetArticulatedTargetPose ( Span< real > outPose, Error & error ) const

pure virtual

Get the last target pose set to the pose controller.

Parameters

[out]	outPose	Output span for the target pose as joint DoFs. Must be of size GetNumDofs.
[in,out]	error	Error status. Check Error::IsOK for success.

Note

Only applicable to articulated actors with a pose controller.

See also

SetArticulatedTargetPose, SetArticulatedTargetLinkTransforms, GetArticulatedTargetLinkTransforms

GetBoundaryConditionDofIndices()

virtual Span< int const > superdex::Actor::GetBoundaryConditionDofIndices ( ) const

nodiscardpure virtual

Get the DoF indices that are constrained by boundary conditions.

Returns

Span of DoF indices with boundary conditions applied.

Note

See AddBoundaryConditionDofsWorld for the DoF layout for each actor type.

The returned span contains every boundary-condition entry added through the public boundary-condition functions that has not been cleared, in the order the entries were added, including repeated DoF indices. Permanent and clearable entries are both included and are not distinguishable. Boundary conditions applied automatically by the engine are not included.

Adding boundary conditions or calling ClearBoundaryConditions may invalidate the returned span. Do not retain it across either operation. Permanent entries are retained when ClearBoundaryConditions is called, but their positions within subsequently returned spans may change. Do not cache those positions across a call to ClearBoundaryConditions.

See also

GetBoundaryConditionDofValuesWorld, AddBoundaryConditionDofsWorld

GetBoundaryConditionDofValuesWorld()

virtual Span< real const > superdex::Actor::GetBoundaryConditionDofValuesWorld ( ) const

nodiscardpure virtual

Get the target values of DoFs fixed by boundary conditions.

Returns

Span of DoF target values in the actor-specific representations documented by AddBoundaryConditionDofsWorld.

Note

1-to-1 correspondence with GetBoundaryConditionDofIndices.

Adding boundary conditions or calling ClearBoundaryConditions may invalidate the returned span. Do not retain it across either operation. Permanent entries are retained when ClearBoundaryConditions is called, but their positions within subsequently returned spans may change. Do not cache those positions across a call to ClearBoundaryConditions.

See also

GetBoundaryConditionDofIndices, AddBoundaryConditionDofsWorld

GetCenterOfMassTransform()

virtual TransformRT superdex::Actor::GetCenterOfMassTransform ( Error & error ) const

nodiscardpure virtual

Get the world-space transform of the actor expressed at the center of mass.

The rotation is the same as in GetRootTransform, but the translation accounts for the local position of the center of mass with respect to the root transform.

Parameters

[in,out]

error

Error status. Check Error::IsOK for success.

Returns

Transform of the actor at the center of mass.

Note

Only supported for dynamic rigid actors.

See also

SetCenterOfMassTransform, GetRootTransform

GetColliderType()

virtual ColliderType superdex::Actor::GetColliderType ( ) const

nodiscardpure virtual

Get the collider type of the actor.

Returns

Collider type of the actor.

Note

If ColliderType::Auto was specified when creating the actor, this method returns the collider type that was automatically selected based on the actor's shape, not Auto.

GetContactForceFromActorWorld()

virtual Real3 superdex::Actor::GetContactForceFromActorWorld ( Actor const * other, Error & error ) const

nodiscardpure virtual

Get the total contact force on the actor from another specified actor.

Parameters

[in]	other	Actor exerting the contact force on this actor.
[in,out]	error	Error status. Check Error::IsOK for success.

Returns

Total contact force [N] in world frame from the specified actor.

Note

Requires registering QueryType::TotalContactForce before the simulation step. Results are available after the simulation step completes.

Requires the actor to support QueryType::TotalContactForce.

If the solver diverged in the last simulation step, results may not be available or may be stale.

See also

RegisterQuery, GetContactForceWorld, QueryType::TotalContactForce

GetContactForceWorld()

virtual Real3 superdex::Actor::GetContactForceWorld ( Error & error ) const

nodiscardpure virtual

Get the total contact force on the actor.

Parameters

[in,out]

error

Error status. Check Error::IsOK for success.

Returns

Total contact force [N] in world frame.

Note

Requires registering QueryType::TotalContactForce before the simulation step. Results are available after the simulation step completes.

Requires the actor to support QueryType::TotalContactForce.

If the solver diverged in the last simulation step, results may not be available or may be stale.

See also

RegisterQuery, GetContactTorqueWorld, GetContactForceFromActorWorld, QueryType::TotalContactForce

GetContactLayer()

virtual std::string_view superdex::Actor::GetContactLayer ( ) const

nodiscardpure virtual

Get the name of the contact layer of the actor.

Returns

Contact layer name, or an empty string if the actor has no contact layer.

See also

SetContactLayer, Scene::EnableLayerContactAsymmetric, Scene::EnableLayerContactSymmetric

GetContactParams()

virtual ContactParams superdex::Actor::GetContactParams ( Error & error ) const

nodiscardpure virtual

Get the contact parameters of the actor.

Parameters

[in,out]

error

Error status. Check Error::IsOK for success.

Returns

Contact parameters of the actor.

GetContactPointsWorld()

virtual Span< ContactPoint const > superdex::Actor::GetContactPointsWorld ( Error & error ) const

nodiscardpure virtual

Get all the active contact points of the actor.

Parameters

[in,out]

error

Error status. Check Error::IsOK for success.

Returns

Span of active contact points.

Note

Requires registering QueryType::ContactPoints before the simulation step. Results are available after the simulation step completes.

Requires the actor to support QueryType::ContactPoints.

If the solver diverged in the last simulation step, results may not be available or may be stale.

See also

RegisterQuery, ContactPoint, QueryType::ContactPoints

GetContactTorqueWorld()

virtual Real3 superdex::Actor::GetContactTorqueWorld ( Error & error ) const

nodiscardpure virtual

Get the total contact torque about the center of mass.

Parameters

[in,out]

error

Error status. Check Error::IsOK for success.

Returns

Total contact torque [N·m] in world frame, about the center of mass.

Note

Requires registering QueryType::TotalContactForce before the simulation step. Results are available after the simulation step completes.

Only supported for rigid actors and articulated links that support QueryType::TotalContactForce.

If the solver diverged in the last simulation step, results may not be available or may be stale.

See also

RegisterQuery, GetContactForceWorld, QueryType::TotalContactForce

GetContext() [1/2]

virtual Context const * superdex::Actor::GetContext ( ) const

nodiscardpure virtual

Get read-only access to the Context that owns this actor.

Returns

Const pointer to the Context that owns this actor.

GetContext() [2/2]

virtual Context * superdex::Actor::GetContext ( )

nodiscardpure virtual

Get the Context that owns this actor.

Returns

Pointer to the Context that owns this actor.

GetConvergenceStatus()

virtual ConvergenceStatus superdex::Actor::GetConvergenceStatus ( ) const

nodiscardpure virtual

Get the convergence status of the actor in the most recent simulation step.

Returns

Convergence status of the actor in the most recent simulation step.

Note

Static actors do not participate in the solver and may return ConvergenceStatus::None.

See also

ConvergenceStatus, SolverStats::convergenceStatus

GetDensity()

virtual real superdex::Actor::GetDensity ( Error & error ) const

nodiscardpure virtual

Get the density of the actor in the undeformed configuration.

Parameters

[in,out]

error

Error status. Check Error::IsOK for success.

Returns

Density [kg/m³] of the actor.

Note

Only supported for rigid actors (except static rigid actors), articulated links and soft actors.

See also

SetDensity, GetSoftMaterialParams

GetDisplacements()

virtual Span< real const > superdex::Actor::GetDisplacements ( Error & error ) const

nodiscardpure virtual

Get the node displacements of the actor in the actor's local frame, relative to reference (rest) positions.

Parameters

[in,out]

error

Error status. Check Error::IsOK for success.

Returns

Node displacements in the actor's local frame. Length is 3 × the number of nodes for soft, shell, and soft-skinned actors, or 4 × the number of nodes for rod actors (3 displacement [m] + 1 twist [rad] per node). The number of nodes is available from GetMesh.

Note

Only supported for soft, soft-skinned, shell and rod actors.

For soft-skinned actors, it returns post-skinning displacements, which may differ from the pre-skinning elastic deformation component written by SetDisplacements.

See also

SetDisplacements, GetNodePositionsLocal

GetDofValues()

virtual void superdex::Actor::GetDofValues ( Span< int const > dofIndices, Span< real > outDofValues, Error & error ) const

pure virtual

Get the current value of the actor's degrees of freedom (DoFs) corresponding to the specified indices.

Parameters

[in]	dofIndices	DoF indices to query. Each index must be in the range [0, GetNumDofs). If empty, get the value of all DoFs.
[out]	outDofValues	Output buffer for the DoF values. Size must equal GetNumDofs when dofIndices is empty, or the size of dofIndices otherwise.
[in,out]	error	Error status. Check Error::IsOK for success.

Note

Not supported for static actors, even when both input and output spans are empty.

See also

GetNumDofs

GetElasticEnergy()

virtual real superdex::Actor::GetElasticEnergy ( Error & error ) const

nodiscardpure virtual

Get the elastic energy of the actor, measured as the difference with respect to the rest state.

Parameters

[in,out]

error

Error status. Check Error::IsOK for success.

Returns

Elastic energy [J] of the actor.

Note

Requires registering QueryType::ElasticEnergy before the simulation step. Results are available after the simulation step completes.

Requires the actor to support QueryType::ElasticEnergy.

See also

RegisterQuery, QueryType::ElasticEnergy

GetElementsDeformationGradient()

virtual Span< real const > superdex::Actor::GetElementsDeformationGradient ( Error & error ) const

nodiscardpure virtual

Get the deformation gradient of each element.

Parameters

[in,out]

error

Error status. Check Error::IsOK for success.

Returns

Span of deformation gradients. The deformation gradient F of element e is stored at index e*9 in row-major format: F_00, F_01, F_02, F_10, F_11, F_12, F_20, F_21, F_22.

Note

Requires registering QueryType::ElementsDeformationGradient before the simulation step. Results are available after the simulation step completes.

Requires the actor to support QueryType::ElementsDeformationGradient.

See also

RegisterQuery, QueryType::ElementsDeformationGradient

GetExternalForces()

virtual void superdex::Actor::GetExternalForces ( Span< real > outForces, Error & error )

pure virtual

Get the external forces currently set on this actor as a dense array over all DoFs.

Parameters

[out]	outForces	Dense output array of force values [N] for translation DoFs and torque values [N·m] for rotation DoFs. One entry per DoF. Size must equal GetNumDofs. DoFs with no external force set are filled with zero.
[in,out]	error	Error status. Check Error::IsOK for success.

Note

Returned values use the same frame convention as SetExternalForcesOnDofs.

See also

SetExternalForcesOnDofs, ClearExternalForces

GetHandle()

virtual ActorHandle superdex::Actor::GetHandle ( ) const

nodiscardpure virtual

Get the actor's handle.

Returns

Actor's handle.

Note

Handles are safe to store and remain valid throughout the actor lifespan.

Call Scene::GetActor to look up the actor's pointer from the actor's handle.

See also

Scene::GetActor

GetLinearVelocity()

virtual Real3 superdex::Actor::GetLinearVelocity ( Error & error ) const

nodiscardpure virtual

Get the linear velocity of the actor in world frame.

Parameters

[in,out]

error

Error status. Check Error::IsOK for success.

Returns

Linear velocity in world frame [m/s].

Note

Only supported for rigid and soft actors.

For rigid actors, it returns the velocity of the center of mass.

For soft actors, it returns an estimate of the linear velocity of the root transform. Requires recentering to be enabled for accurate results.

Not supported for ROM actors.

GetMass()

virtual real superdex::Actor::GetMass ( Error & error ) const

nodiscardpure virtual

Get the total mass of the actor.

Parameters

[in,out]

error

Error status. Check Error::IsOK for success.

Returns

Mass [kg] of the actor.

Note

Not supported for static actors.

GetMesh()

virtual MeshDataView superdex::Actor::GetMesh ( ) const

nodiscardpure virtual

Get a view of the actor's reference simulation mesh.

For soft actors, returns the tetrahedral mesh. For shell actors, returns the triangle mesh. For rod actors, returns the polyline mesh. For articulated actors with a skin mesh, returns the skin mesh. For articulated actors without a skin mesh, returns an empty view. For soft-skinned actors, returns the blended skin mesh when one is present and an empty view otherwise. For rigid actors whose shape is a tetrahedral or triangular mesh, returns their surface simulation mesh. For rigid actors with an implicit shape, such as spheres and planes, returns an empty view.

Returns

A non-owning view of the actor's reference simulation mesh, or an empty view if the actor has no simulation mesh.

Note

The returned coordinates are reference positions in the actor's local frame. They do not include deformation for deformable actors.

For rigid actors with tetrahedral or triangular mesh shapes, returns the same compact surface view as GetSurfaceMesh. For tetrahedral meshes this is the boundary surface. For triangular meshes, nodes not referenced by any surface triangle are omitted and remaining nodes may be reindexed. Use GetReferenceShape and Context::GetShapeMesh to retrieve the original authored shape mesh.

The returned view remains valid until the actor is destroyed.

See also

MeshDataView, GetSurfaceMesh, GetVisualMesh, Context::GetShapeMesh

GetName()

virtual char const * superdex::Actor::GetName ( ) const

nodiscardpure virtual

Get the name of the actor.

Returns

Name of the actor.

Note

Actor names are not guaranteed to be unique.

GetNestedLinkActors()

virtual Span< ActorHandle const > superdex::Actor::GetNestedLinkActors ( Error & error ) const

nodiscardpure virtual

Get the actor handles for the nested rigid link actors.

Parameters

[in,out]

error

Error status. Check Error::IsOK for success.

Returns

Span of actor handles for the nested rigid link actors.

Note

Only applicable to articulated actors.

See also

GetNestedSoftActors, IsNestedLinkActor, GetArticulatedActor

GetNestedSoftActors()

virtual Span< ActorHandle const > superdex::Actor::GetNestedSoftActors ( Error & error ) const

nodiscardpure virtual

Get the actor handles for the nested soft actors (if any).

Parameters

[in,out]

error

Error status. Check Error::IsOK for success.

Returns

Span of actor handles for the nested soft actors, or empty if there are none.

Note

Only applicable to articulated actors.

See also

GetNestedLinkActors, IsNestedSoftActor, GetArticulatedActor

GetNodeContactForcesWorld()

virtual Span< NodeContactForce const > superdex::Actor::GetNodeContactForcesWorld ( Error & error ) const

nodiscardpure virtual

Get contact forces on nodes.

Parameters

[in,out]

error

Error status. Check Error::IsOK for success.

Returns

Span of per-node contact forces [N] in world frame.

Note

Requires registering QueryType::NodeContactForces before the simulation step. Results are available after the simulation step completes.

Requires the actor to support QueryType::NodeContactForces.

If the solver diverged in the last simulation step, results may not be available or may be stale.

See also

RegisterQuery, NodeContactForce, QueryType::NodeContactForces

GetNodePositionsLocal()

virtual Span< real const > superdex::Actor::GetNodePositionsLocal ( Error & error ) const

nodiscardpure virtual

Get the current position (reference + displacements) of each node in the actor's local frame.

Parameters

[in,out]

error

Error status. Check Error::IsOK for success.

Returns

Flattened node positions [m] in the actor's local frame (3 values per node: x, y, z).

Note

Requires registering QueryType::NodePositions before the simulation step. Results are available after the simulation step completes.

Requires the actor to support QueryType::NodePositions.

See also

RegisterQuery, QueryType::NodePositions

GetNumDofs()

virtual int superdex::Actor::GetNumDofs ( ) const

nodiscardpure virtual

Get the number of degrees of freedom (DoFs) of the actor.

Returns

Number of degrees of freedom of the actor.

Note

Returns zero for actors without degrees of freedom (e.g., static actors).

GetPointsDistanceToSurface()

virtual void superdex::Actor::GetPointsDistanceToSurface ( Span< Real3 const > pointsWorld, Span< real > outDistances, Error & error ) const

pure virtual

Query the signed distance to the closest point on the actor's surface.

Parameters

[in]	pointsWorld	Point cloud in world frame.
[out]	outDistances	Output distances [m], in the same order as the input points. Must be the same size as the input points. Negative values indicate points inside the actor.
[in,out]	error	Error status. Check Error::IsOK for success.

Note

Requires the actor to have a collider.

For actors with SDF collider, the reported distance is only correct inside the actor's bounding box. Outside the bounding box, it is an upper bound based on the triangle inequality.

This function is not supported for soft actors or for the experimental ColliderType::PointCloud.

GetRecenteringParams()

virtual RecenteringParams superdex::Actor::GetRecenteringParams ( ) const

nodiscardpure virtual

Gets the recentering parameters of the actor.

Returns

Recentering parameters of the actor.

Note

Recentering is only supported for soft actors (not soft-skinned). For other actor types, returns default recentering parameters with RecenteringParams::useRecentering set to false.

See also

RecenteringParams, SetRecenteringParams

GetReferenceShape()

virtual ShapeHandle superdex::Actor::GetReferenceShape ( Error & error ) const

nodiscardpure virtual

Get a new ShapeHandle referencing the same shape data used to create this actor.

The returned handle is a new reference to the same underlying shape data. It will have a different numeric value from the ShapeHandle originally used to create the actor. The new handle represents a new request to keep the shape data in memory — the shape will remain valid as long as any handle, actor, or file cache entry references it.

Parameters

[in,out]

error

Error status. Check Error::IsOK for success.

Returns

A new ShapeHandle referencing the actor's shape data.

Note

In C++ and Python, the returned ShapeHandle is reference-counted and releases its reference automatically when destroyed. In the C API, you must call Context::ReleaseShape when done with the handle to avoid leaks.

See also

Context::ReleaseShape, Context::LoadShapeFromFile

GetRigidCenterOfMassLocal()

virtual Real3 superdex::Actor::GetRigidCenterOfMassLocal ( Error & error ) const

nodiscardpure virtual

Get the position of the center of mass in the actor's local coordinate frame (GetRootTransform).

Parameters

[in,out]

error

Error status. Check Error::IsOK for success.

Returns

Position vector of the center of mass in the actor's local coordinate frame.

Note

Only supported for dynamic rigid actors (including articulated links) and soft actors.

See also

GetRootTransform

GetRigidMomentOfInertiaLocal()

virtual Real6 superdex::Actor::GetRigidMomentOfInertiaLocal ( Error & error ) const

nodiscardpure virtual

Get the moment of inertia tensor of the actor at the center of mass, aligned with the actor's local reference system (root transform), and using negative tensor notation.

    [ixx, ixy, ixz]   [ +∫(y²+z²)dm, -∫(xy)dm,    -∫(xz)dm     ]
I = [ixy, iyy, iyz] = [ -∫(xy)dm,    +∫(x²+z²)dm, -∫(yz)dm     ]
    [ixz, iyz, izz]   [ -∫(xz)dm,    -∫(yz)dm,    +∫(x²+y²)dm  ]

Parameters

[in,out]

error

Error status. Check Error::IsOK for success.

Returns

Upper-right triangle in the form [ixx, ixy, ixz, iyy, iyz, izz]. Units: kg·m².

Note

Only supported for dynamic rigid actors.

GetRootTransform()

virtual TransformRT superdex::Actor::GetRootTransform ( ) const

nodiscardpure virtual

Get the actor's world-from-local transform (root transform).

Returns

The actor's world-from-local transform.

Note

Returns an identity transform when HasRootTransform returns false.

For a top-level articulated actor, the local frame is the articulation root frame, not the root link's frame. For a nested link actor, the local frame is that link's frame.

GetScene() [1/2]

virtual Scene const * superdex::Actor::GetScene ( ) const

nodiscardpure virtual

Get the Scene that this actor belongs to (read only).

Returns

Pointer to the scene that this actor belongs to.

GetScene() [2/2]

virtual Scene * superdex::Actor::GetScene ( )

nodiscardpure virtual

Get the Scene that this actor belongs to.

Returns

Pointer to the scene that this actor belongs to.

GetSdfDistances()

virtual SdfDistances superdex::Actor::GetSdfDistances ( Error & error ) const

nodiscardpure virtual

Get SDF distances for contact sample points.

Parameters

[in,out]

error

Error status. Check Error::IsOK for success.

Returns

SDF distance information for contact sample points.

Note

Requires registering QueryType::SdfDistances before the simulation step. Results are available after the simulation step completes.

Requires the actor to support QueryType::SdfDistances.

If the solver diverged in the last simulation step, results may not be available or may be stale.

See also

RegisterQuery, SdfDistances, QueryType::SdfDistances

GetSoftMaterialParams()

virtual SoftMaterialParams superdex::Actor::GetSoftMaterialParams ( Error & error ) const

nodiscardpure virtual

Get the material parameters of a soft actor.

Parameters

[in,out]

error

Error status. Check Error::IsOK for success.

Returns

Material parameters of the actor.

Note

Only supported for soft actors.

See also

SetSoftMaterialParams, experimental::GetSoftMaterialParamsField, GetDensity

GetSurfaceMesh()

virtual MeshDataView superdex::Actor::GetSurfaceMesh ( ) const

nodiscardpure virtual

Get a view of the actor's reference surface mesh.

Returns a compact triangle mesh for the actor's surface. For volumetric simulation meshes, the surface is the boundary triangles. For triangular simulation meshes, the surface has the same triangle elements as the simulation mesh, but nodes not referenced by any surface triangle are omitted and remaining nodes may be reindexed. Returns an empty view if the actor does not have a surface mesh.

Returns

A non-owning view of the actor's reference surface mesh, or an empty view if the actor has no surface mesh.

Note

The returned coordinates are reference surface-mesh positions in the actor's local frame. They do not include deformation for deformable actors.

The returned mesh uses compact surface-node ordering. Connectivity indices refer to this ordering, which may differ from the node ordering returned by GetMesh. Interior nodes and nodes not referenced by any surface triangle are excluded. Results from GetSurfaceMeshNodePositionsLocal and GetSurfaceMeshNodeNormalsLocal use this same surface ordering.

The returned view remains valid until the actor is destroyed.

See also

MeshDataView, GetMesh, GetVisualMesh, GetSurfaceMeshNodePositionsLocal, GetSurfaceMeshNodeNormalsLocal, Context::GetShapeSurfaceMesh

GetSurfaceMeshNodeNormalsLocal()

virtual Span< real const > superdex::Actor::GetSurfaceMeshNodeNormalsLocal ( Error & error ) const

nodiscardpure virtual

Get the normal direction for each node of the surface mesh in the actor's local frame.

Parameters

[in,out]

error

Error status. Check Error::IsOK for success.

Returns

Span of normals (3 values per node) in the actor's local frame, computed by normalizing the area-weighted sum of adjacent triangle normals. The returned node list contains exactly the nodes referenced by GetSurfaceMesh and is 1-to-1 with GetSurfaceMeshNodePositionsLocal.

Note

Requires registering QueryType::SurfaceNodeNormals before the simulation step. Results are available after the simulation step completes.

Requires the actor to support QueryType::SurfaceNodeNormals.

The node ordering corresponds to the mesh connectivity from GetSurfaceMesh.

See also

RegisterQuery, QueryType::SurfaceNodeNormals, GetSurfaceMesh, GetSurfaceMeshNodePositionsLocal

GetSurfaceMeshNodePositionsLocal()

virtual Span< real const > superdex::Actor::GetSurfaceMeshNodePositionsLocal ( Error & error ) const

nodiscardpure virtual

Get the current position of the nodes (reference + displacements) of the surface mesh in the actor's local frame.

Parameters

[in,out]

error

Error status. Check Error::IsOK for success.

Returns

Current node positions [m] of the surface mesh in the actor's local frame (3 values per node: x, y, z). The returned node list contains exactly the nodes referenced by GetSurfaceMesh and is 1-to-1 with GetSurfaceMeshNodeNormalsLocal.

Note

Requires registering QueryType::SurfaceNodePositions before the simulation step. Results are available after the simulation step completes.

Requires the actor to support QueryType::SurfaceNodePositions.

The node ordering corresponds to the mesh connectivity from GetSurfaceMesh.

See also

RegisterQuery, QueryType::SurfaceNodePositions, GetSurfaceMesh, GetSurfaceMeshNodeNormalsLocal

GetType()

virtual ActorType superdex::Actor::GetType ( ) const

nodiscardpure virtual

Get the type of the actor.

Returns

Type of the actor.

GetUserData()

virtual void * superdex::Actor::GetUserData ( ) const

pure virtual

Get application-specific user data for this actor.

Returns

Pointer to user data, or nullptr if none has been set.

See also

SetUserData

GetVisualMesh()

virtual MeshDataView superdex::Actor::GetVisualMesh ( ) const

nodiscardpure virtual

Get a view of the actor's reference visual mesh.

Returns a triangle mesh intended for visual rendering. The mesh may include linear visual-mesh skinning data when available. Returns an empty view if the actor does not have a visual mesh.

Returns

A non-owning view of the actor's reference visual mesh, or an empty view if the actor has no visual mesh.

Note

The returned coordinates are reference visual-mesh positions in the actor's local frame. They do not include deformation for deformable actors.

Includes visual mesh nodes not referenced by any visual triangle. Unlike surface mesh getters, visual mesh getters do not omit unreferenced nodes.

When linear visual-mesh skinning data is present, skinning indices refer to the node ordering returned by GetMesh, not to the compact surface-node ordering returned by GetSurfaceMesh. Rod visual mesh embeddings are nonlinear and are not exposed through this linear skinning field.

The returned view remains valid until the actor is destroyed.

See also

MeshDataView, GetMesh, GetSurfaceMesh, GetVisualMeshNodePositionsLocal, GetVisualMeshNodeNormalsLocal, Context::GetShapeVisualMesh

GetVisualMeshNodeNormalsLocal()

virtual Span< real const > superdex::Actor::GetVisualMeshNodeNormalsLocal ( Error & error ) const

nodiscardpure virtual

Get the normal direction to each node of the visual mesh in the actor's local frame.

Parameters

[in,out]

error

Error status. Check Error::IsOK for success.

Returns

Flattened normals (3 values per node: nx, ny, nz) in the actor's local frame. The number of nodes is available via GetVisualMesh. The order of the nodes is 1-to-1 with GetVisualMeshNodePositionsLocal. Normals for visual nodes not referenced by any visual triangle are zero.

Note

Includes visual mesh nodes not referenced by any visual triangle. Unlike surface mesh getters, visual mesh getters do not omit unreferenced nodes.

Requires registering QueryType::VisualNodeNormals before the simulation step. Results are available after the simulation step completes.

Requires the actor to support QueryType::VisualNodeNormals.

See also

RegisterQuery, QueryType::VisualNodeNormals, GetVisualMesh, GetVisualMeshNodePositionsLocal

GetVisualMeshNodePositionsLocal()

virtual Span< real const > superdex::Actor::GetVisualMeshNodePositionsLocal ( Error & error ) const

nodiscardpure virtual

Get the current position (reference + displacements) of the nodes of the visual mesh in the actor's local frame.

Parameters

[in,out]

error

Error status. Check Error::IsOK for success.

Returns

Current node positions [m] of the visual mesh in the actor's local frame (3 values per node: x, y, z). The number of nodes is available via GetVisualMesh. The order of the nodes is 1-to-1 with GetVisualMeshNodeNormalsLocal.

Note

Includes visual mesh nodes not referenced by any visual triangle. Unlike surface mesh getters, visual mesh getters do not omit unreferenced nodes.

Requires registering QueryType::VisualNodePositions before the simulation step. Results are available after the simulation step completes.

Requires the actor to support QueryType::VisualNodePositions.

See also

RegisterQuery, QueryType::VisualNodePositions, GetVisualMesh, GetVisualMeshNodeNormalsLocal

HasArticulatedPoseController()

virtual bool superdex::Actor::HasArticulatedPoseController ( Error & error ) const

nodiscardpure virtual

Check if the articulated actor has a pose controller.

Parameters

[in,out]

error

Error status. Check Error::IsOK for success.

Returns

True if a pose controller exists, false otherwise.

Note

Only applicable to articulated actors.

See also

AddArticulatedPoseController, RemoveArticulatedPoseController

HasRootTransform()

virtual bool superdex::Actor::HasRootTransform ( ) const

nodiscardpure virtual

Check if the actor has a root transform.

Returns

True if the actor has a root transform. False otherwise.

Note

Non-rendered actors may not have a root transform.

IsNestedLinkActor()

virtual bool superdex::Actor::IsNestedLinkActor ( ) const

nodiscardpure virtual

Check if the actor is a rigid link within an articulated actor.

Returns

True if the actor is a nested link actor, false otherwise.

See also

GetNestedLinkActors, GetArticulatedActor

IsNestedSoftActor()

virtual bool superdex::Actor::IsNestedSoftActor ( ) const

nodiscardpure virtual

Check if the actor is a soft actor nested within a soft skinned articulated actor.

Returns

True if the actor is a nested soft actor, false otherwise.

See also

GetNestedSoftActors, GetArticulatedActor

IsQuerySupported()

virtual bool superdex::Actor::IsQuerySupported ( QueryType type ) const

nodiscardpure virtual

Check whether a query type is supported for this actor.

Parameters

[in]

type

Type of query to check.

Returns

True if RegisterQuery would succeed for this query type, false otherwise.

See also

RegisterQuery

IsStatic()

virtual bool superdex::Actor::IsStatic ( ) const

nodiscardpure virtual

Check whether the actor is static.

Returns

True if the actor is static. False if it's dynamic.

QueryNodesInVolumeLocal() [1/3]

virtual void superdex::Actor::QueryNodesInVolumeLocal ( Aabb const & volume, bool boundaryOnly, std::function< void(int, Real3)> const & callback, Error & error ) const

pure virtual

Find the actor's nodes that are inside an axis-aligned bounding box (AABB).

Parameters

[in]	volume	Axis-aligned bounding box in the actor's local frame.
[in]	boundaryOnly	If true, only boundary nodes are considered.
[in]	callback	Callback called for each node found. The position is the current node position [m] in the actor's local frame. The node index uses GetMesh ordering, including when boundaryOnly is true.
[in,out]	error	Error status. Check Error::IsOK for success.

Note

When boundaryOnly is false, this function supports only soft and shell actors. When true, it also supports articulated actors with a skin mesh, soft-skinned actors with a blended skin mesh, and rigid actors (dynamic or static) with tetrahedral or triangular mesh shapes. Rod actors and actors without a simulation mesh are not supported.

Requires query registration before the simulation step. Register QueryType::NodePositions when boundaryOnly is false, or QueryType::SurfaceNodePositions when boundaryOnly is true. Results are available after the simulation step completes.

Warning

This is a synchronous call and may be expensive.

QueryNodesInVolumeLocal() [2/3]

virtual void superdex::Actor::QueryNodesInVolumeLocal ( Obb const & volume, bool boundaryOnly, std::function< void(int, Real3)> const & callback, Error & error ) const

pure virtual

Find the actor's nodes that are inside an oriented bounding box (OBB).

Parameters

[in]	volume	Oriented bounding box in the actor's local frame.
[in]	boundaryOnly	If true, only boundary nodes are considered.
[in]	callback	Callback called for each node found. The position is the current node position [m] in the actor's local frame. The node index uses GetMesh ordering, including when boundaryOnly is true.
[in,out]	error	Error status. Check Error::IsOK for success.

Note

When boundaryOnly is false, this function supports only soft and shell actors. When true, it also supports articulated actors with a skin mesh, soft-skinned actors with a blended skin mesh, and rigid actors (dynamic or static) with tetrahedral or triangular mesh shapes. Rod actors and actors without a simulation mesh are not supported.

Requires query registration before the simulation step. Register QueryType::NodePositions when boundaryOnly is false, or QueryType::SurfaceNodePositions when boundaryOnly is true. Results are available after the simulation step completes.

Warning

This is a synchronous call and may be expensive.

QueryNodesInVolumeLocal() [3/3]

virtual void superdex::Actor::QueryNodesInVolumeLocal ( Sphere const & volume, bool boundaryOnly, std::function< void(int, Real3)> const & callback, Error & error ) const

pure virtual

Find the actor's nodes that are inside a sphere.

Parameters

[in]	volume	Sphere in the actor's local frame.
[in]	boundaryOnly	If true, only boundary nodes are considered.
[in]	callback	Callback called for each node found. The position is the current node position [m] in the actor's local frame. The node index uses GetMesh ordering, including when boundaryOnly is true.
[in,out]	error	Error status. Check Error::IsOK for success.

Note

When boundaryOnly is false, this function supports only soft and shell actors. When true, it also supports articulated actors with a skin mesh, soft-skinned actors with a blended skin mesh, and rigid actors (dynamic or static) with tetrahedral or triangular mesh shapes. Rod actors and actors without a simulation mesh are not supported.

Requires query registration before the simulation step. Register QueryType::NodePositions when boundaryOnly is false, or QueryType::SurfaceNodePositions when boundaryOnly is true. Results are available after the simulation step completes.

Warning

This is a synchronous call and may be expensive.

RegisterQuery()

virtual QueryHandle superdex::Actor::RegisterQuery ( QueryType type, Error & error )

pure virtual

Register a query to compute data for this actor.

Parameters

[in]	type	Type of query to register.
[in,out]	error	Error status. Check Error::IsOK for success.

Returns

QueryHandle for the registered query, or an invalid handle if registration fails.

Note

Queries may add substantial computational overhead. Use only when necessary.

Data is available after the next simulation step, even if its time step is zero.

Call CancelQuery when the query is not needed again in the future.

Queries are reference counted internally, so they will be available as long as there is one outstanding QueryHandle.

Registration is all-or-nothing: if registration fails, no query is registered.

See also

CancelQuery, RegisterQueryAndCompute, IsQuerySupported, Constraint::RegisterQuery

RegisterQueryAndCompute()

virtual QueryHandle superdex::Actor::RegisterQueryAndCompute ( QueryType type, Error & error )

pure virtual

Register a query for this actor and compute the result immediately.

Parameters

[in]	type	Type of query to register.
[in,out]	error	Error status. Check Error::IsOK for success.

Returns

QueryHandle for the registered query.

Note

Same as RegisterQuery, except that the data is computed immediately (blocking) rather than at the next simulation step.

Immediate computation is not supported for all query types. For unsupported types, the query is still registered successfully, immediate computation is skipped, and data becomes available after the next simulation step. See QueryType documentation for which types support immediate computation.

Stepping the scene with zero time step is another way to force queries to update, without advancing the state of the simulation.

See also

RegisterQuery, CancelQuery

RemoveArticulatedPoseController()

virtual void superdex::Actor::RemoveArticulatedPoseController ( Error & error )

pure virtual

Remove the pose controller.

Parameters

[in,out]

error

Error status. Check Error::IsOK for success.

Note

Only applicable to articulated actors.

Returns an error if no pose controller exists.

See also

AddArticulatedPoseController, HasArticulatedPoseController

ResetArticulatedTargetLinkTransforms()

virtual void superdex::Actor::ResetArticulatedTargetLinkTransforms ( Span< TransformRT const > worldFromTargets, Error & error )

pure virtual

Reset the target pose of the controller expressed as link transforms.

Parameters

[in]	worldFromTargets	Target world-from-link transforms to reset to. Must be finite and of size equal to the number of links.
[in,out]	error	Error status. Check Error::IsOK for success.

Note

Only applicable to articulated actors with a pose controller.

Sets the target to the provided transforms and the target velocity to zero, so no velocity kick is introduced.

To use a non-zero target velocity, call SetArticulatedTargetVelocity after this function.

See also

SetArticulatedTargetLinkTransforms, ResetArticulatedTargetPose

ResetArticulatedTargetPose()

virtual void superdex::Actor::ResetArticulatedTargetPose ( Span< real const > pose, Error & error )

pure virtual

Reset the target pose of the controller expressed as joint DoFs.

Parameters

[in]	pose	Target pose as joint DoFs to reset to. Must be finite and of size GetNumDofs.
[in,out]	error	Error status. Check Error::IsOK for success.

Note

Only applicable to articulated actors with a pose controller.

Sets the target to the provided pose and the target velocity to zero, so no velocity kick is introduced.

To use a non-zero target velocity, call SetArticulatedTargetVelocity after this function.

See also

SetArticulatedTargetPose, ResetArticulatedTargetLinkTransforms

SetArticulatedJointFrictionParams()

virtual void superdex::Actor::SetArticulatedJointFrictionParams ( Span< ArticulatedJointFrictionParams const > friction, Error & error )

pure virtual

Set the per-joint friction parameters of the articulated actor.

Parameters

[in]	friction	Friction parameters, one per joint. Must be of size equal to the number of joints (matching GetArticulatedJointFrictionParams); all values must be finite and non-negative.
[in,out]	error	Error status. Check Error::IsOK for success.

Note

Only applicable to articulated actors.

See also

GetArticulatedJointFrictionParams, ArticulatedJointFrictionParams

SetArticulatedJointInertiaParams()

virtual void superdex::Actor::SetArticulatedJointInertiaParams ( Span< real const > inertia, Error & error )

pure virtual

Set the per-joint inertia coefficients of the articulated actor.

Parameters

[in]	inertia	Inertia coefficients, one per joint. Must be of size equal to the number of joints (matching GetArticulatedJointInertiaParams); all values must be finite and non-negative.
[in,out]	error	Error status. Check Error::IsOK for success.

Note

Only applicable to articulated actors.

See also

GetArticulatedJointInertiaParams

SetArticulatedJointVelocities()

virtual void superdex::Actor::SetArticulatedJointVelocities ( Span< real const > velocities, Error & error )

pure virtual

Set time derivatives of the articulated actor DoFs.

Parameters

[in]	velocities	Joint DoF velocities to set. Must be of size GetNumDofs.
[in,out]	error	Error status. Check Error::IsOK for success.

Note

Only applicable to articulated actors.

If the actor has a pose controller, target velocity is also set to the provided velocities.

Resets multi-step time integrators, e.g. BDF2 falls back to backward Euler in the first time step after this method is called.

See also

GetArticulatedJointVelocities

SetArticulatedPoseControllerParams()

virtual void superdex::Actor::SetArticulatedPoseControllerParams ( PoseControllerParams const & params, Error & error )

pure virtual

Set the pose controller's tracking parameters.

Parameters

[in]	params	Tracking parameters grouped by constraint type. Each array must be empty, size 1 (broadcast to all links), or size numLinks (per-link). An empty array will broadcast using a default-constructed PoseTrackingParams (zero gains) to all links.
[in,out]	error	Error status. Check Error::IsOK for success.

Note

Only applicable to articulated actors with a pose controller.

Setting zero stiffness and damping disables the constraint but does not destroy it.

See also

GetArticulatedPoseControllerParams, GetArticulatedPoseConstraints

SetArticulatedPoseFromJoints()

virtual void superdex::Actor::SetArticulatedPoseFromJoints ( Span< real const > pose, Error & error )

pure virtual

Set the pose of an articulated actor from joint DoFs.

Parameters

[in]	pose	Joint DoF values to set. Must be of size GetNumDofs.
[in,out]	error	Error status. Check Error::IsOK for success.

Note

Only applicable to articulated actors.

If the actor has a pose controller, its target pose is reset to the provided pose and its target velocity is set to zero. Call SetArticulatedTargetVelocity afterward to use a non-zero target velocity.

Does not affect the actor's velocities.

Resets multi-step time integrators, e.g. BDF2 falls back to backward Euler in the first time step after this method is called.

Warning

Round-trip error: SetArticulatedPoseFromJoints followed by GetArticulatedPose may not return identical values due to internal representation differences.

See also

GetArticulatedPose, SetArticulatedPoseFromLinks

SetArticulatedPoseFromLinks()

virtual void superdex::Actor::SetArticulatedPoseFromLinks ( Span< TransformRT const > worldFromLinks, Error & error )

pure virtual

Set the pose of an articulated actor from the world-from-local link transforms.

Parameters

[in]	worldFromLinks	World-from-local link transforms. Must be of size equal to the number of links.
[in,out]	error	Error status. Check Error::IsOK for success.

Note

Only applicable to articulated actors.

Transforms are automatically projected onto valid joint space.

If the actor has a pose controller, its target pose is reset to the provided transforms and its target velocity is set to zero. Call SetArticulatedTargetVelocity afterward to use a non-zero target velocity.

Does not affect the actor's velocities.

Resets multi-step time integrators, e.g. BDF2 falls back to backward Euler in the first time step after this method is called.

Warning

Round-trip error: SetArticulatedPoseFromLinks followed by GetArticulatedLinkTransforms may not return identical values due to internal representation differences.

See also

GetArticulatedLinkTransforms, SetArticulatedPoseFromJoints

SetArticulatedTargetLinkTransforms()

virtual void superdex::Actor::SetArticulatedTargetLinkTransforms ( Span< TransformRT const > worldFromTargets, Error & error )

pure virtual

Set the target pose for the controller expressed as link transforms.

Parameters

[in]	worldFromTargets	Target world-from-link transforms to set. Must be of size equal to the number of links.
[in,out]	error	Error status. Check Error::IsOK for success.

Note

Only supported for articulated actors with a pose controller.

Also affects target velocity, which depends on how the target changes between simulation steps.

See also

ResetArticulatedTargetLinkTransforms, SetArticulatedTargetPose

SetArticulatedTargetPose()

virtual void superdex::Actor::SetArticulatedTargetPose ( Span< real const > pose, Error & error )

pure virtual

Set the target pose for the controller expressed as joint DoFs.

Parameters

[in]	pose	Target pose as joint DoFs to set. Must be of size GetNumDofs.
[in,out]	error	Error status. Check Error::IsOK for success.

Note

Only applicable to articulated actors with a pose controller.

Also affects target velocity, which depends on how the target changes between simulation steps.

See also

ResetArticulatedTargetPose, SetArticulatedTargetLinkTransforms, GetArticulatedTargetPose, GetArticulatedTargetLinkTransforms, SetArticulatedTargetVelocity

SetArticulatedTargetVelocity()

virtual void superdex::Actor::SetArticulatedTargetVelocity ( Span< real const > velocity, Error & error )

pure virtual

Set the target velocity of the controller expressed as joint velocities for the next simulation step.

Parameters

[in]	velocity	Target DoF velocities to set. [m/s] for translational DoFs and [rad/s] for rotational DoFs. Must be finite and of size GetNumDofs.
[in,out]	error	Error status. Check Error::IsOK for success.

Note

Only applicable to articulated actors with a pose controller.

Does not change target pose.

The velocity override is applied once at the start of the next simulation step to compute damping, then cleared automatically. To maintain a constant target velocity, call this function before each step.

ResetArticulatedTargetPose and ResetArticulatedTargetLinkTransforms overwrite any pending target velocity with zero. Call this function after reset to use a non-zero target velocity.

See also

SetArticulatedTargetPose, ResetArticulatedTargetPose

SetCenterOfMassTransform()

virtual void superdex::Actor::SetCenterOfMassTransform ( TransformRT const & worldFromCom, Error & error )

pure virtual

Set the world-space transform of the actor expressed at the center of mass.

Parameters

[in]	worldFromCom	World-space transform at the center of mass to set.
[in,out]	error	Error status. Check Error::IsOK for success.

Note

Only supported for dynamic rigid actors.

Does not change velocity.

Resets multi-step time integrators, e.g. BDF2 falls back to backward Euler in the first time step after this method is called.

See also

GetCenterOfMassTransform, SetRootTransform

SetContactLayer()

virtual void superdex::Actor::SetContactLayer ( std::string_view const & layer )

pure virtual

Set the name of the contact layer of the actor.

Parameters

[in]

layer

Contact layer name to set.

See also

GetContactLayer, Scene::EnableLayerContactAsymmetric, Scene::EnableLayerContactSymmetric

SetContactParams()

virtual void superdex::Actor::SetContactParams ( ContactParams const & params, Error & error )

pure virtual

Set the contact parameters of the actor.

Parameters

[in]	params	Contact parameters to set.
[in,out]	error	Error status. Check Error::IsOK for success.

SetDensity()

virtual void superdex::Actor::SetDensity ( real density, Error & error )

pure virtual

Set the density of the actor in the undeformed configuration.

Parameters

[in]	density	Density [kg/m³] to set. Must be positive.
[in,out]	error	Error status. Check Error::IsOK for success.

Note

Only supported for rigid actors (except static rigid actors), articulated links and soft actors.

The moment of inertia is updated based on the new density. The center of mass is left unchanged.

See also

GetDensity, SetInertiaProperties, SetSoftMaterialParams

SetDisplacements()

virtual void superdex::Actor::SetDisplacements ( Span< real const > displacements, Error & error )

pure virtual

Set the node displacements in the actor's local frame, relative to reference (rest) positions.

Parameters

[in]	displacements	Node displacements [m] to set in the actor's local frame. Length must be 3 × the number of nodes. The number of nodes is available from GetMesh.
[in,out]	error	Error status. Check Error::IsOK for success.

Note

Only supported for soft, soft-skinned and shell actors.

For soft-skinned actors, displacements are the elastic deformation component only (before skinning is applied).

Does not change node velocities.

Resets multi-step time integrators, e.g. BDF2 falls back to backward Euler in the first time step after this method is called.

See also

GetDisplacements, SetNodePositionsLocal

SetExternalForcesOnDofs()

virtual void superdex::Actor::SetExternalForcesOnDofs ( Span< int const > dofIndices, Span< real const > forceValues, Error & error )

pure virtual

Set external forces on specified DoFs.

Parameters

[in]	dofIndices	DoF indices to apply forces to. Must be unique.
[in]	forceValues	Force values [N] for translation DoFs, torque values [N·m] for rotation DoFs. Length must equal the number of DoF indices.
[in,out]	error	Error status. Check Error::IsOK for success.

Note

Only supported for rigid, articulated, rod, and shell actors.

DoF indices use the same per-actor-type index layout documented by AddBoundaryConditionDofsWorld.

External forces can be cleared with ClearExternalForces.

Replaces all previously set external forces, including external forces on DoFs not included in dofIndices. Passing empty dofIndices and forceValues is equivalent to calling ClearExternalForces.

For rigid and shell actors, values are interpreted in the world frame.

For articulated actors, values are generalized forces in the actor's joint-DoF coordinate basis.

For rod actors, forces on displacement DoFs are specified in the world frame, while (generalized) forces (scalar torques) on element twist-angle DoFs are always oriented along the corresponding element's current orientation.

For open (non-closed-loop) rod actors, the last DoF is padding that does not participate in physics, so it is invalid to apply a torque to it. For closed-loop rods, the last DoF is a physical twist angle.

See also

ClearExternalForces, GetExternalForces, AddBoundaryConditionDofsWorld

SetInertiaProperties()

virtual void superdex::Actor::SetInertiaProperties ( real mass, Real3 const & centerOfMass, Real6 const & momentOfInertia, Error & error )

pure virtual

Set the mass properties of the actor.

Directly sets mass, center of mass position in local coordinates, and moment of inertia tensor at the center of mass. This bypasses density-based computation and allows specifying exact inertia from CAD data or external measurements.

Parameters

[in]	mass	Mass [kg] to set. Must be positive and finite.
[in]	centerOfMass	Position of center of mass [m] in actor's local coordinate frame (GetRootTransform).
[in]	momentOfInertia	Moment of inertia tensor at center of mass [kg·m²], upper-right triangle [ixx, ixy, ixz, iyy, iyz, izz] using negative tensor notation consistent with GetRigidMomentOfInertiaLocal. Must be finite.
[in,out]	error	Error status. Check Error::IsOK for success.

Note

Only supported for dynamic rigid actors. Not supported for static actors, soft actors, shell actors, or articulated links.

A finite but physically invalid moment of inertia tensor (negative principal moments or one violating the triangle inequality) is accepted with a warning, not rejected.

Re-anchors the density reference state. Subsequent SetDensity calls rescale mass and moment of inertia proportionally about the new values; center of mass is unchanged by SetDensity.

After this call, GetDensity returns bulk density mass / volume.

See also

GetMass, GetDensity, SetDensity, GetRigidCenterOfMassLocal, GetRigidMomentOfInertiaLocal

SetNodePositionsLocal()

virtual void superdex::Actor::SetNodePositionsLocal ( Span< real const > positionsLocal, Error & error )

pure virtual

Set the current position of each node (reference + displacements) in the actor's local frame.

Parameters

[in]	positionsLocal	Node positions [m] to set (3 values per node: x, y, z) in the actor's local frame.
[in,out]	error	Error status. Check Error::IsOK for success.

Note

Only supported for soft (not soft-skinned) and shell actors.

Does not change node velocities.

Resets multi-step time integrators, e.g. BDF2 falls back to backward Euler in the first time step after this method is called.

SetNodeVelocitiesLocal()

virtual void superdex::Actor::SetNodeVelocitiesLocal ( Span< real const > velocitiesLocal, Error & error )

pure virtual

Set the current velocity of each node in the actor's local frame.

Parameters

[in]	velocitiesLocal	Node velocities to set in the actor's local frame.
[in,out]	error	Error status. Check Error::IsOK for success.

Note

Only supported for soft (not soft-skinned), shell and rod actors.

For soft and shell actors: 3 values per node [m/s] — (vx, vy, vz).

For rod actors: 4 values per node — (vx, vy, vz) in [m/s] plus a twist rate [rad/s].

Resets multi-step time integrators, e.g. BDF2 falls back to backward Euler in the first time step after this method is called.

SetRecenteringParams()

virtual void superdex::Actor::SetRecenteringParams ( RecenteringParams const & params, Error & error )

pure virtual

Set the recentering parameters of the actor.

When enabled for a soft actor, the root transform automatically moves as the actor's "rigid pivot" (typically near the center of mass) moves.

Parameters

[in]	params	Recentering parameters to set.
[in,out]	error	Error status. Check Error::IsOK for success.

Note

Only supported for soft actors (not soft-skinned).

See also

RecenteringParams, GetRecenteringParams

SetRootTransform()

virtual void superdex::Actor::SetRootTransform ( TransformRT const & worldFromLocal, Error & error )

pure virtual

Set the actor's world-from-local transform (root transform).

Parameters

[in]	worldFromLocal	World-space transform to set.
[in,out]	error	Error status. Check Error::IsOK for success.

Note

Not allowed on articulated links.

For a top-level articulated actor, the local frame is the articulation root frame, not the root link's frame.

For dynamic actors, it does not change velocity. For static actors, however, it changes velocity, because it is implicitly defined by the root transform in consecutive time steps. To cancel the velocity of a static actor, use SetVelocity.

Resets multi-step time integrators, e.g. BDF2 falls back to backward Euler in the first time step after this method is called.

SetSoftMaterialParams()

virtual void superdex::Actor::SetSoftMaterialParams ( SoftMaterialParams const & params, Error & error )

pure virtual

Set the material parameters of a soft actor.

Parameters

[in]	params	Material parameters to set.
[in,out]	error	Error status. Check Error::IsOK for success.

Note

Only supported for soft actors.

If the QueryType::ElasticEnergy query is active, invalidates the elastic energy baseline. One simulation step must complete before GetElasticEnergy returns valid results.

See also

GetSoftMaterialParams, experimental::SetSoftMaterialParamsField, SetDensity

SetUserData()

virtual void superdex::Actor::SetUserData ( void * userData )

pure virtual

Set application-specific user data for this actor.

Parameters

[in]

userData

Pointer to user data, or nullptr to clear.

See also

GetUserData

SetVelocity()

virtual void superdex::Actor::SetVelocity ( Real3 const & linearVel, Real3 const & angularVel, Error & error )

pure virtual

Set the world-frame linear and angular velocity of the actor at the center of mass.

Parameters

[in]	linearVel	Linear velocity [m/s] of the center of mass in world frame.
[in]	angularVel	Angular velocity [rad/s] at the center of mass in world frame.
[in,out]	error	Error status. Check Error::IsOK for success.

Note

Only supported for rigid actors (except articulated links) and soft actors (except ROMs and soft-skinned actors).

For static actors, it only supports setting zero velocity.

For soft actors, the angular velocity must be zero.

Resets multi-step time integrators, e.g. BDF2 falls back to backward Euler in the first time step after this method is called.

SetZeroDisplacementsAndVelocities()

virtual void superdex::Actor::SetZeroDisplacementsAndVelocities ( Error & error )

pure virtual

Set all local displacement and velocity DoFs to zero.

Parameters

[in,out]

error

Error status. Check Error::IsOK for success.

Note

Only supported for soft, soft-skinned, shell and rod actors.

For soft-skinned actors, it zeroes the elastic deformation and velocity only. The skeleton-driven pose is unaffected.

For rod actors, it zeroes both the translational displacement DoFs and the twist-angle DoFs.

Resets multi-step time integrators, e.g. BDF2 falls back to backward Euler in the first time step after this method is called.

---

The documentation for this class was generated from the following files:

• mochi_actor.h
• mochi_physics.generated.dox