Represents a constraint that restricts the degrees of freedom of one or more actors. More...

#include <mochi_constraint.h>

Public Member Functions
virtual void	CancelQuery (QueryHandle handle)=0
	Cancel a previously registered query.
virtual Actor const *	GetActor (int actorIndex) const =0
	Get read-only access to one of the actors affected by this constraint.
virtual Actor *	GetActor (int actorIndex)=0
	Get one of the actors affected by this constraint.
virtual real	GetDamping () const =0
	Get the constraint's damping parameter.
virtual DynamicArray< real >	GetDeviation () const =0
	Compute the constraint's current deviation from its target, limits, or coupling condition.
virtual Span< int const >	GetDofIndicesForActor (int actorIndex) const =0
	Get the degrees of freedom (DoF) indices affected by this constraint on a specific actor.
virtual Span< real const >	GetForce (Error &error) const =0
	Get the force/torque applied by the constraint.
virtual ConstraintHandle	GetHandle () const =0
	Get the handle associated with this constraint.
virtual Span< real const >	GetLimitMaxValues (Error &error) const =0
	Get the constraint's maximum limit values.
virtual Span< real const >	GetLimitMinValues (Error &error) const =0
	Get the constraint's minimum limit values.
virtual int	GetNumActors () const =0
	Get the number of actors affected by the constraint.
virtual real	GetSaturation () const =0
	Get the constraint's saturation parameter.
virtual real	GetStiffness () const =0
	Get the constraint's stiffness parameter.
virtual ConstraintType	GetType () const =0
	Get the type of the constraint.
virtual bool	IsQuerySupported (QueryType type) const =0
	Check whether a query type is supported for this constraint.
virtual QueryHandle	RegisterQuery (QueryType type, Error &error)=0
	Register a query to compute data for this constraint.
virtual void	SetDamping (real damping, Error &error)=0
	Set the constraint's damping parameter.
virtual void	SetRefRelativeRotation (Quaternion const &rotationA, Quaternion const &rotationB, Error &error)=0
	Set a relative-rotation target from two rotations expressed in a common frame.
virtual void	SetSaturation (real saturation, Error &error)=0
	Set the constraint's saturation parameter.
virtual void	SetStiffness (real stiffness, Error &error)=0
	Set the constraint's stiffness parameter.
virtual void	SetTargetDof (real target, Error &error)=0
	Set the constraint's target DoF.
virtual void	SetTargetPosition (Real3 const &position, Error &error)=0
	Set the constraint's target position in world frame.
virtual void	SetTargetRotation (Quaternion const &rotation, Error &error)=0
	Set the constraint's target rotation.
virtual void	UpdateOldTarget (Error &error)=0
	Update the old target to match the current target.

Protected Member Functions
virtual	~Constraint ()=default

Detailed Description

Represents a constraint that restricts the degrees of freedom of one or more actors.

Constraints enforce relationships between actor degrees of freedom (DoFs), such as fixing positions, limiting joint angles, or tracking target poses. They apply forces to maintain desired configurations using spring-damper mechanics controlled by stiffness and damping parameters.

Note: Each constraint belongs to exactly one scene.; Each constraint acts on the degrees of freedom of one or more actors.; The type of constraint determines which methods are applicable.

Warning: Concurrent access to a constraint is illegal.

Definition at line 39 of file mochi_constraint.h.

Constructor & Destructor Documentation

◆ ~Constraint()

virtual superdex::Constraint::~Constraint ( )

protectedvirtualdefault

Member Function Documentation

◆ CancelQuery()

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

pure virtual

Cancel a previously registered query.

Parameters

[in] handle QueryHandle from a previous RegisterQuery call.

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

See also: RegisterQuery, Actor::CancelQuery

◆ GetActor() [1/2]

virtual Actor const * superdex::Constraint::GetActor ( int actorIndex ) const

nodiscardpure virtual

Get read-only access to one of the actors affected by this constraint.

Parameters

[in] actorIndex Actor index in the range [0, GetNumActors).

Returns: Const pointer to the actor.

See also: GetNumActors

◆ GetActor() [2/2]

virtual Actor * superdex::Constraint::GetActor ( int actorIndex )

nodiscardpure virtual

Get one of the actors affected by this constraint.

Parameters

[in] actorIndex Actor index in the range [0, GetNumActors).

Returns: Pointer to the actor.

See also: GetNumActors

◆ GetDamping()

virtual real superdex::Constraint::GetDamping ( ) const

nodiscardpure virtual

Get the constraint's damping parameter.

Returns: Damping value. [N·s/m] for translation constraints, [N·m·s/rad] for rotation constraints.

See also: SetDamping, GetStiffness, GetSaturation

◆ GetDeviation()

virtual DynamicArray< real > superdex::Constraint::GetDeviation ( ) const

nodiscardpure virtual

Compute the constraint's current deviation from its target, limits, or coupling condition.

Returns: Vector of constraint deviation values, one per constraint dimension. Units: [m] for translation constraints or [rad] for rotation constraints. Size equals the number of scalar constraint equations (e.g., 3 for position/rotation pivots and joints, 1 for single-DoF range/target constraints).

Note: For constraints with targets: deviation is the distance/angle error from target.; For constraints with range limits: deviation indicates how far the current value is from the valid range.; For coupling constraints without a target or range: deviation is the constraint violation, i.e. how far the coupling is from being satisfied (zero when exactly satisfied).

◆ GetDofIndicesForActor()

virtual Span< int const > superdex::Constraint::GetDofIndicesForActor ( int actorIndex ) const

nodiscardpure virtual

Get the degrees of freedom (DoF) indices affected by this constraint on a specific actor.

Parameters

[in] actorIndex Actor index in the range [0, GetNumActors).

Returns: Span of DoF indices for the specified actor.

See also: GetNumActors, GetActor

◆ GetForce()

virtual Span< real const > superdex::Constraint::GetForce ( Error & error ) const

nodiscardpure virtual

Get the force/torque applied by the constraint.

Values are ordered first by actor (in the order returned by GetActor), then by DoF within each actor (in the order returned by GetDofIndicesForActor). Each entry has units conjugate to its DoF: [N] for translational DoFs and [N·m] for rotational DoFs (so a single returned vector may mix both, e.g. for ConstraintType::RigidPivotPosition the 6 entries are 3 force [N] followed by 3 torque [N·m] components on the rigid actor).

Parameters

[in,out] error Error status. Check Error::IsOK for success.

Returns: Flattened generalized-force vector. One entry per constrained DoF.

Note: Requires registering QueryType::ConstraintForce before the simulation step. Results are available after the simulation step completes.; If the solver diverged in the last simulation step, the returned force may be inaccurate.

See also: RegisterQuery, QueryType::ConstraintForce, GetDofIndicesForActor

◆ GetHandle()

virtual ConstraintHandle superdex::Constraint::GetHandle ( ) const

nodiscardpure virtual

Get the handle associated with this constraint.

Returns: Handle to this constraint.

Note: Handles are safe to store and remain valid throughout the constraint lifespan.; Call Scene::GetConstraint to look up the constraint's pointer from the constraint's handle.

See also: Scene::GetConstraint

◆ GetLimitMaxValues()

virtual Span< real const > superdex::Constraint::GetLimitMaxValues ( Error & error ) const

nodiscardpure virtual

Get the constraint's maximum limit values.

Parameters

[in,out] error Error status. Check Error::IsOK for success.

Returns: Span of maximum values for each constrained DoF. Units: [m] for translation DoFs, [rad] for rotation DoFs.

Note: Only applicable to range-based constraints (ConstraintType::ArticulatedSingleDofRange, ConstraintType::Articulated3dRotationRange, ConstraintType::JointRotationRange).

See also: GetLimitMinValues

◆ GetLimitMinValues()

virtual Span< real const > superdex::Constraint::GetLimitMinValues ( Error & error ) const

nodiscardpure virtual

Get the constraint's minimum limit values.

Parameters

[in,out] error Error status. Check Error::IsOK for success.

Returns: Span of minimum values for each constrained DoF. Units: [m] for translation DoFs, [rad] for rotation DoFs.

Note: Only applicable to range-based constraints (ConstraintType::ArticulatedSingleDofRange, ConstraintType::Articulated3dRotationRange, ConstraintType::JointRotationRange).

See also: GetLimitMaxValues

◆ GetNumActors()

virtual int superdex::Constraint::GetNumActors ( ) const

nodiscardpure virtual

Get the number of actors affected by the constraint.

Returns: Number of actors affected by the constraint.

◆ GetSaturation()

virtual real superdex::Constraint::GetSaturation ( ) const

nodiscardpure virtual

Get the constraint's saturation parameter.

Returns: Saturation distance [m] for translation constraints or angle [rad] for rotation constraints, or a negative value if saturation is disabled.

Note: A positive value smoothly limits the magnitude of the elastic (stiffness) contribution to stiffness * saturation. The damping contribution is separate and is not limited by saturation.

See also: SetSaturation, GetStiffness, GetDamping

◆ GetStiffness()

virtual real superdex::Constraint::GetStiffness ( ) const

nodiscardpure virtual

Get the constraint's stiffness parameter.

Returns: Stiffness value. [N/m] for translation constraints, [N·m/rad] for rotation constraints.

Note: Higher stiffness results in stronger constraint forces/torques.

See also: SetStiffness, GetDamping, GetSaturation

◆ GetType()

virtual ConstraintType superdex::Constraint::GetType ( ) const

nodiscardpure virtual

Get the type of the constraint.

Returns: Type of the constraint.

Note: Some methods are only valid for certain constraint types.

See also: ConstraintType

◆ IsQuerySupported()

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

nodiscardpure virtual

Check whether a query type is supported for this constraint.

Parameters

[in] type Type of query to check.

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

See also: RegisterQuery

◆ RegisterQuery()

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

pure virtual

Register a query to compute data for this constraint.

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: Queries may add substantial computational overhead. Use only when necessary.; Data becomes available after the next simulation step (even if the 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.

See also: CancelQuery, IsQuerySupported, Actor::RegisterQuery

◆ SetDamping()

virtual void superdex::Constraint::SetDamping	(	real	damping,
		Error &	error )

pure virtual

Set the constraint's damping parameter.

Parameters

[in]	damping	Damping value. [N·s/m] for translation constraints, [N·m·s/rad] for rotation constraints. Must be non-negative and finite.
[in,out]	error	Error status. Check Error::IsOK for success.

See also: GetDamping, SetStiffness, SetSaturation

◆ SetRefRelativeRotation()

virtual void superdex::Constraint::SetRefRelativeRotation	(	Quaternion const &	rotationA,
		Quaternion const &	rotationB,
		Error &	error )

pure virtual

Set a relative-rotation target from two rotations expressed in a common frame.

Sets the target to inverse(rotationA) * rotationB.

Parameters

[in]	rotationA	First rotation. Represents JointRotationTrackingConstraintParams::actorA for ConstraintType::JointRotationTracking and the rigid actor for ConstraintType::RodElementRotationToRigid. Must be finite and non-zero. Normalized before use.
[in]	rotationB	Second rotation. Represents JointRotationTrackingConstraintParams::actorB for ConstraintType::JointRotationTracking and the selected rod element for ConstraintType::RodElementRotationToRigid. Must be finite and non-zero. Normalized before use.
[in,out]	error	Error status. Check Error::IsOK for success.

Note: Only applicable to ConstraintType::JointRotationTracking and ConstraintType::RodElementRotationToRigid.; Also affects target velocity, which depends on the difference between current and old target relative rotation.

See also: SetTargetRotation, UpdateOldTarget

◆ SetSaturation()

virtual void superdex::Constraint::SetSaturation	(	real	saturation,
		Error &	error )

pure virtual

Set the constraint's saturation parameter.

Parameters

[in]	saturation	Saturation distance [m] for translation constraints or angle [rad] for rotation constraints, or any negative value to disable saturation. Must be finite and non-zero.
[in,out]	error	Error status. Check Error::IsOK for success.

Note: A positive value smoothly limits the magnitude of the elastic (stiffness) contribution to stiffness * saturation. The damping contribution is separate and is not limited by saturation.

See also: GetSaturation, SetStiffness, SetDamping

◆ SetStiffness()

virtual void superdex::Constraint::SetStiffness	(	real	stiffness,
		Error &	error )

pure virtual

Set the constraint's stiffness parameter.

Parameters

[in]	stiffness	Stiffness value. [N/m] for translation constraints, [N·m/rad] for rotation constraints. Must be non-negative and finite.
[in,out]	error	Error status. Check Error::IsOK for success.

See also: GetStiffness, SetDamping, SetSaturation

◆ SetTargetDof()

virtual void superdex::Constraint::SetTargetDof	(	real	target,
		Error &	error )

pure virtual

Set the constraint's target DoF.

Parameters

[in]	target	Target DoF value. Units: [m] for translation DoFs, [rad] for rotation DoFs.
[in,out]	error	Error status. Check Error::IsOK for success.

Note: Only applicable to ConstraintType::ArticulatedSingleDofTarget.; Also affects target velocity, which depends on the difference between current and old target DoF.

See also: SetTargetPosition, SetTargetRotation

◆ SetTargetPosition()

virtual void superdex::Constraint::SetTargetPosition	(	Real3 const &	position,
		Error &	error )

pure virtual

Set the constraint's target position in world frame.

Parameters

[in]	position	Target position [m] in world frame. Must be finite.
[in,out]	error	Error status. Check Error::IsOK for success.

Note: Only applicable to position-target constraints: ConstraintType::RigidPivotPosition, ConstraintType::DeformableNodePosition, and ConstraintType::RigidPivotToRigidTarget. For ConstraintType::RigidPivotToRigidTarget, this updates only the translation of the target center-of-mass transform.; Also affects target velocity, which depends on the difference between current and old target position.

See also: SetTargetRotation, SetTargetDof

◆ SetTargetRotation()

virtual void superdex::Constraint::SetTargetRotation	(	Quaternion const &	rotation,
		Error &	error )

pure virtual

Set the constraint's target rotation.

The target is interpreted according to the constraint type. For ConstraintType::RigidPivotRotation, it is the target pivot-frame rotation in world coordinates. For ConstraintType::RigidPivotToRigidTarget, it is the rotation of the target center-of-mass transform in world coordinates. For ConstraintType::Articulated3dRotationTarget, it is the target joint-local rotation. For ConstraintType::JointRotationTracking, it is the target rotation of JointRotationTrackingConstraintParams::actorB relative to JointRotationTrackingConstraintParams::actorA. For ConstraintType::RodElementRotationToRigid, it is the target rotation of the constrained rod element relative to the rigid actor.

Parameters

[in]	rotation	Target rotation quaternion [x, y, z, w]. Must be finite and non-zero. Normalized before use.
[in,out]	error	Error status. Check Error::IsOK for success.

Note: Also affects target velocity, which depends on the difference between current and old target rotation.

See also: SetTargetPosition, SetTargetDof, SetRefRelativeRotation

◆ UpdateOldTarget()

virtual void superdex::Constraint::UpdateOldTarget ( Error & error )

pure virtual

Update the old target to match the current target.

Call this method after changing a target discontinuously, and before stepping the scene, to prevent that change from contributing to damping during the next simulation step.

Parameters

[in,out] error Error status. Check Error::IsOK for success.

Note: Only applicable to constraints with a target.

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

Public Member Functions

Protected Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ ~Constraint()

Member Function Documentation

◆ CancelQuery()

◆ GetActor() [1/2]

◆ GetActor() [2/2]

◆ GetDamping()

◆ GetDeviation()

◆ GetDofIndicesForActor()

◆ GetForce()

◆ GetHandle()

◆ GetLimitMaxValues()

◆ GetLimitMinValues()

◆ GetNumActors()

◆ GetSaturation()

◆ GetStiffness()

◆ GetType()

◆ IsQuerySupported()

◆ RegisterQuery()

◆ SetDamping()

◆ SetRefRelativeRotation()

◆ SetSaturation()

◆ SetStiffness()

◆ SetTargetDof()

◆ SetTargetPosition()

◆ SetTargetRotation()

◆ UpdateOldTarget()