Revision control
++ // Copyright (c) 2001-2004 NovodeX AG. All rights reserved.
++ // Copyright (c) 2004-2008 AGEIA Technologies, Inc. All rights reserved.
++ // SPDX-FileCopyrightText: Copyright (c) 2008-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
++ // SPDX-License-Identifier: Apache-2.0
++
++
++ #ifndef PX_ARTICULATION_TENDON_H
++ #define PX_ARTICULATION_TENDON_H
++
++ #include "PxPhysXConfig.h"
++ #include "common/PxBase.h"
++ #include "solver/PxSolverDefs.h"
++
++ #if !PX_DOXYGEN
++ namespace physx
++ {
++ #endif
++ class PxArticulationSpatialTendon;
++ class PxArticulationFixedTendon;
++ class PxArticulationLink;
++ /**
++ \brief Defines the low/high limits of the length of a tendon.
++ */
++ class PxArticulationTendonLimit
++ {
++ public:
++ PxReal lowLimit;
++ PxReal highLimit;
++ };
++
++ /**
++ \brief Defines a spatial tendon attachment point on a link.
++ */
++ class PxArticulationAttachment : public PxBase
++ {
++
++ public:
++
++ virtual ~PxArticulationAttachment() {}
++ /**
++ \brief Sets the spring rest length for the sub-tendon from the root to this leaf attachment.
++
++ Setting this on non-leaf attachments has no effect.
++
++ \param[in] restLength The rest length of the spring.
++ <b>Default:</b> 0
++
++ \note This method should not be used after the direct GPU API has been enabled and initialized. See #PxDirectGPUAPI for the details.
++
++ \see getRestLength(), isLeaf()
++ */
++ virtual void setRestLength(const PxReal restLength) = 0;
++
++ /**
++ \brief Gets the spring rest length for the sub-tendon from the root to this leaf attachment.
++
++ \return The rest length.
++
++ \note This method should not be used after the direct GPU API has been enabled and initialized. See #PxDirectGPUAPI for the details.
++
++ \see setRestLength()
++ */
++ virtual PxReal getRestLength() const = 0;
++
++ /**
++ \brief Sets the low and high limit on the length of the sub-tendon from the root to this leaf attachment.
++
++ Setting this on non-leaf attachments has no effect.
++
++ \param[in] parameters Struct with the low and high limit.
++ <b>Default:</b> (PX_MAX_F32, -PX_MAX_F32) (i.e. an invalid configuration that can only work if stiffness is zero)
++
++ \note This method should not be used after the direct GPU API has been enabled and initialized. See #PxDirectGPUAPI for the details.
++
++ \see PxArticulationTendonLimit, getLimitParameters(), isLeaf()
++ */
++ virtual void setLimitParameters(const PxArticulationTendonLimit& parameters) = 0;
++
++ /**
++ \brief Gets the low and high limit on the length of the sub-tendon from the root to this leaf attachment.
++
++ \return Struct with the low and high limit.
++
++ \note This method should not be used after the direct GPU API has been enabled and initialized. See #PxDirectGPUAPI for the details.
++
++ \see PxArticulationTendonLimit, setLimitParameters()
++ */
++ virtual PxArticulationTendonLimit getLimitParameters() const = 0;
++
++ /**
++ \brief Sets the attachment's relative offset in the link actor frame.
++
++ \param[in] offset The relative offset in the link actor frame.
++
++ \note This method should not be used after the direct GPU API has been enabled and initialized. See #PxDirectGPUAPI for the details.
++
++ \see getRelativeOffset()
++ */
++ virtual void setRelativeOffset(const PxVec3& offset) = 0;
++
++ /**
++ \brief Gets the attachment's relative offset in the link actor frame.
++
++ \return The relative offset in the link actor frame.
++
++ \note This method should not be used after the direct GPU API has been enabled and initialized. See #PxDirectGPUAPI for the details.
++
++ \see setRelativeOffset()
++ */
++ virtual PxVec3 getRelativeOffset() const = 0;
++
++ /**
++ \brief Sets the attachment coefficient.
++
++ \param[in] coefficient The scale that the distance between this attachment and its parent is multiplied by when summing up the spatial tendon's length.
++
++ \note This method should not be used after the direct GPU API has been enabled and initialized. See #PxDirectGPUAPI for the details.
++
++ \see getCoefficient()
++ */
++ virtual void setCoefficient(const PxReal coefficient) = 0;
++
++ /**
++ \brief Gets the attachment coefficient.
++
++ \return The scale that the distance between this attachment and its parent is multiplied by when summing up the spatial tendon's length.
++
++ \note This method should not be used after the direct GPU API has been enabled and initialized. See #PxDirectGPUAPI for the details.
++
++ \see setCoefficient()
++ */
++ virtual PxReal getCoefficient() const = 0;
++
++ /**
++ \brief Gets the articulation link.
++
++ \return The articulation link that this attachment is attached to.
++ */
++ virtual PxArticulationLink* getLink() const = 0;
++
++ /**
++ \brief Gets the parent attachment.
++
++ \return The parent attachment.
++ */
++ virtual PxArticulationAttachment* getParent() const = 0;
++
++ /**
++ \brief Indicates that this attachment is a leaf, and thus defines a sub-tendon from the root to this attachment.
++
++ \return True: This attachment is a leaf and has zero children; False: Not a leaf.
++ */
++ virtual bool isLeaf() const = 0;
++
++ /**
++ \brief Gets the spatial tendon that the attachment is a part of.
++
++ \return The tendon.
++
++ \see PxArticulationSpatialTendon
++ */
++ virtual PxArticulationSpatialTendon* getTendon() const = 0;
++
++ /**
++ \brief Releases the attachment.
++
++ \note Releasing the attachment is not allowed while the articulation is in a scene. In order to
++ release the attachment, remove and then re-add the articulation to the scene.
++
++ \see PxArticulationSpatialTendon::createAttachment()
++ */
++ virtual void release() PX_OVERRIDE = 0;
++
++ void* userData; //!< user can assign this to whatever, usually to create a 1:1 relationship with a user object.
++
++ /**
++ \brief Returns the string name of the dynamic type.
++
++ \return The string name.
++ */
++ virtual const char* getConcreteTypeName() const PX_OVERRIDE PX_FINAL { return "PxArticulationAttachment"; }
++
++ protected:
++
++ PX_INLINE PxArticulationAttachment(PxType concreteType, PxBaseFlags baseFlags) : PxBase(concreteType, baseFlags), userData(NULL) {}
++ PX_INLINE PxArticulationAttachment(PxBaseFlags baseFlags) : PxBase(baseFlags) {}
++ };
++
++
++ /**
++ \brief Defines a fixed-tendon joint on an articulation joint degree of freedom.
++ */
++ class PxArticulationTendonJoint : public PxBase
++ {
++
++ public:
++
++ virtual ~PxArticulationTendonJoint() {}
++
++ /**
++ \brief Sets the tendon joint coefficient.
++
++ \param[in] axis The degree of freedom that the tendon joint operates on (must correspond to a degree of freedom of the associated link's incoming joint).
++ \param[in] coefficient The scale that the axis' joint position is multiplied by when summing up the fixed tendon's length.
++ \param[in] recipCoefficient The scale that the tendon's response is multiplied by when applying to this tendon joint.
++
++ \note RecipCoefficient is commonly expected to be 1/coefficient, but it can be set to different values to tune behavior; for example, zero can be used to
++ have a joint axis only participate in the length computation of the tendon, but not have any tendon force applied to it.
++
++ \note This method should not be used after the direct GPU API has been enabled and initialized. See #PxDirectGPUAPI for the details.
++
++ \see getCoefficient()
++ */
++ virtual void setCoefficient(const PxArticulationAxis::Enum axis, const PxReal coefficient, const PxReal recipCoefficient) = 0;
++
++ /**
++ \brief Gets the tendon joint coefficient.
++
++ \param[out] axis The degree of freedom that the tendon joint operates on.
++ \param[out] coefficient The scale that the axis' joint position is multiplied by when summing up the fixed tendon's length.
++ \param[in] recipCoefficient The scale that the tendon's response is multiplied by when applying to this tendon joint.
++
++ \note This method should not be used after the direct GPU API has been enabled and initialized. See #PxDirectGPUAPI for the details.
++
++ \see setCoefficient()
++ */
++ virtual void getCoefficient(PxArticulationAxis::Enum& axis, PxReal& coefficient, PxReal& recipCoefficient) const = 0;
++
++ /**
++ \brief Gets the articulation link.
++
++ \return The articulation link (and its incoming joint in particular) that this tendon joint is associated with.
++ */
++ virtual PxArticulationLink* getLink() const = 0;
++
++ /**
++ \brief Gets the parent tendon joint.
++
++ \return The parent tendon joint.
++ */
++ virtual PxArticulationTendonJoint* getParent() const = 0;
++
++ /**
++ \brief Gets the tendon that the joint is a part of.
++
++ \return The tendon.
++
++ \see PxArticulationFixedTendon
++ */
++ virtual PxArticulationFixedTendon* getTendon() const = 0;
++
++ /**
++ \brief Releases a tendon joint.
++
++ \note Releasing a tendon joint is not allowed while the articulation is in a scene. In order to
++ release the joint, remove and then re-add the articulation to the scene.
++
++ \see PxArticulationFixedTendon::createTendonJoint()
++ */
++ virtual void release() PX_OVERRIDE = 0;
++
++ void* userData; //!< user can assign this to whatever, usually to create a 1:1 relationship with a user object.
++
++ /**
++ \brief Returns the string name of the dynamic type.
++
++ \return The string name.
++ */
++ virtual const char* getConcreteTypeName() const PX_OVERRIDE PX_FINAL { return "PxArticulationTendonJoint"; }
++
++ protected:
++
++ PX_INLINE PxArticulationTendonJoint(PxType concreteType, PxBaseFlags baseFlags) : PxBase(concreteType, baseFlags), userData(NULL) {}
++ PX_INLINE PxArticulationTendonJoint(PxBaseFlags baseFlags) : PxBase(baseFlags) {}
++ };
++
++
++ /**
++ \brief Common API base class shared by PxArticulationSpatialTendon and PxArticulationFixedTendon.
++ */
++ class PxArticulationTendon : public PxBase
++ {
++ public:
++ /**
++ \brief Sets the spring stiffness term acting on the tendon length.
++
++ \param[in] stiffness The spring stiffness.
++ <b>Default:</b> 0
++
++ \note This method should not be used after the direct GPU API has been enabled and initialized. See #PxDirectGPUAPI for the details.
++
++ \see getStiffness()
++ */
++ virtual void setStiffness(const PxReal stiffness) = 0;
++
++ /**
++ \brief Gets the spring stiffness of the tendon.
++
++ \return The spring stiffness.
++
++ \note This method should not be used after the direct GPU API has been enabled and initialized. See #PxDirectGPUAPI for the details.
++
++ \see setStiffness()
++ */
++ virtual PxReal getStiffness() const = 0;
++
++ /**
++ \brief Sets the damping term acting both on the tendon length and tendon-length limits.
++
++ \param[in] damping The damping term.
++ <b>Default:</b> 0
++
++ \note This method should not be used after the direct GPU API has been enabled and initialized. See #PxDirectGPUAPI for the details.
++
++ \see getDamping()
++ */
++ virtual void setDamping(const PxReal damping) = 0;
++
++ /**
++ \brief Gets the damping term acting both on the tendon length and tendon-length limits.
++
++ \return The damping term.
++
++ \note This method should not be used after the direct GPU API has been enabled and initialized. See #PxDirectGPUAPI for the details.
++
++ \see setDamping()
++ */
++ virtual PxReal getDamping() const = 0;
++
++ /**
++ \brief Sets the limit stiffness term acting on the tendon's length limits.
++
++ For spatial tendons, this parameter applies to all its leaf attachments / sub-tendons.
++
++ \param[in] stiffness The limit stiffness term.
++ <b>Default:</b> 0
++
++ \note This method should not be used after the direct GPU API has been enabled and initialized. See #PxDirectGPUAPI for the details.
++
++ \see getLimitStiffness()
++ */
++ virtual void setLimitStiffness(const PxReal stiffness) = 0;
++
++ /**
++ \brief Gets the limit stiffness term acting on the tendon's length limits.
++
++ For spatial tendons, this parameter applies to all its leaf attachments / sub-tendons.
++
++ \return The limit stiffness term.
++
++ \note This method should not be used after the direct GPU API has been enabled and initialized. See #PxDirectGPUAPI for the details.
++
++ \see setLimitStiffness()
++ */
++ virtual PxReal getLimitStiffness() const = 0;
++
++ /**
++ \brief Sets the length offset term for the tendon.
++
++ An offset defines an amount to be added to the accumulated length computed for the tendon. It allows the
++ application to actuate the tendon by shortening or lengthening it.
++
++ \param[in] offset The offset term. <b>Default:</b> 0
++ \param[in] autowake If true and the articulation is in a scene, the call wakes up the articulation and increases the wake counter
++ to #PxSceneDesc::wakeCounterResetValue if the counter value is below the reset value.
++
++ \note This method should not be used after the direct GPU API has been enabled and initialized. See #PxDirectGPUAPI for the details.
++
++ \see getOffset()
++ */
++ virtual void setOffset(const PxReal offset, bool autowake = true) = 0;
++
++ /**
++ \brief Gets the length offset term for the tendon.
++
++ \return The offset term.
++
++ \note This method should not be used after the direct GPU API has been enabled and initialized. See #PxDirectGPUAPI for the details.
++
++ \see setOffset()
++ */
++ virtual PxReal getOffset() const = 0;
++
++ /**
++ \brief Gets the articulation that the tendon is a part of.
++
++ \return The articulation.
++
++ \see PxArticulationReducedCoordinate
++ */
++ virtual PxArticulationReducedCoordinate* getArticulation() const = 0;
++
++ /**
++ \brief Releases a tendon to remove it from the articulation and free its associated memory.
++
++ When an articulation is released, its attached tendons are automatically released.
++
++ \note Releasing a tendon is not allowed while the articulation is in a scene. In order to
++ release the tendon, remove and then re-add the articulation to the scene.
++ */
++
++ virtual void release() PX_OVERRIDE = 0;
++
++ virtual ~PxArticulationTendon() {}
++
++ void* userData; //!< user can assign this to whatever, usually to create a 1:1 relationship with a user object.
++
++ protected:
++ PX_INLINE PxArticulationTendon(PxType concreteType, PxBaseFlags baseFlags) : PxBase(concreteType, baseFlags), userData(NULL) {}
++ PX_INLINE PxArticulationTendon(PxBaseFlags baseFlags) : PxBase(baseFlags) {}
++ };
++
++ /**
++ \brief A spatial tendon that attaches to an articulation.
++
++ A spatial tendon attaches to multiple links in an articulation using a set of PxArticulationAttachments.
++ The tendon is defined as a tree of attachment points, where each attachment can have an arbitrary number of children.
++ Each leaf of the attachment tree defines a subtendon between itself and the root attachment. The subtendon then
++ applies forces at the leaf, and an equal but opposing force at the root, in order to satisfy the spring-damper and limit
++ constraints that the user sets up. Attachments in between the root and leaf do not exert any force on the articulation,
++ but define the geometry of the tendon from which the length is computed together with the attachment coefficients.
++ */
++ class PxArticulationSpatialTendon : public PxArticulationTendon
++ {
++ public:
++ /**
++ \brief Creates an articulation attachment and adds it to the list of children in the parent attachment.
++
++ Creating an attachment is not allowed while the articulation is in a scene. In order to
++ add the attachment, remove and then re-add the articulation to the scene.
++
++ \param[in] parent The parent attachment. Can be NULL for the root attachment of a tendon.
++ \param[in] coefficient A user-defined scale that the accumulated length is scaled by.
++ \param[in] relativeOffset An offset vector in the link's actor frame to the point where the tendon attachment is attached to the link.
++ \param[in] link The link that this attachment is associated with.
++
++ \return The newly-created attachment if creation was successful, otherwise a null pointer.
++
++ \see releaseAttachment()
++ */
++ virtual PxArticulationAttachment* createAttachment(PxArticulationAttachment* parent, const PxReal coefficient, const PxVec3 relativeOffset, PxArticulationLink* link) = 0;
++
++ /**
++ \brief Fills a user-provided buffer of attachment pointers with the set of attachments.
++
++ \param[in] userBuffer The user-provided buffer.
++ \param[in] bufferSize The size of the buffer. If this is not large enough to contain all the pointers to attachments,
++ only as many as can fit are written. Use getNbAttachments to size for all attachments.
++ \param[in] startIndex Index of first attachment pointer to be retrieved.
++
++ \return The number of attachments that were filled into the user buffer.
++
++ \see getNbAttachments
++ */
++ virtual PxU32 getAttachments(PxArticulationAttachment** userBuffer, PxU32 bufferSize, PxU32 startIndex = 0) const = 0;
++
++ /**
++ \brief Returns the number of attachments in the tendon.
++
++ \return The number of attachments.
++ */
++ virtual PxU32 getNbAttachments() const = 0;
++
++ /**
++ \brief Returns the string name of the dynamic type.
++
++ \return The string name.
++ */
++ virtual const char* getConcreteTypeName() const PX_OVERRIDE PX_FINAL { return "PxArticulationSpatialTendon"; }
++
++ virtual ~PxArticulationSpatialTendon() {}
++
++ protected:
++ PX_INLINE PxArticulationSpatialTendon(PxType concreteType, PxBaseFlags baseFlags) : PxArticulationTendon(concreteType, baseFlags) {}
++ PX_INLINE PxArticulationSpatialTendon(PxBaseFlags baseFlags) : PxArticulationTendon(baseFlags) {}
++
++ };
++
++ /**
++ \brief A fixed tendon that can be used to link multiple degrees of freedom of multiple articulation joints via length and limit constraints.
++
++ Fixed tendons allow the simulation of coupled relationships between joint degrees of freedom in an articulation. Fixed tendons do not allow
++ linking arbitrary joint axes of the articulation: The respective joints must all be directly connected to each other in the articulation structure,
++ i.e. each of the joints in the tendon must be connected by a single articulation link to another joint in the same tendon. This implies both that
++ 1) fixed tendons can branch along a branching articulation; and 2) they cannot be used to create relationships between axes in a spherical joint with
++ more than one degree of freedom. Locked joint axes or fixed joints are currently not supported.
++ */
++ class PxArticulationFixedTendon : public PxArticulationTendon
++ {
++ public:
++ /**
++ \brief Creates an articulation tendon joint and adds it to the list of children in the parent tendon joint.
++
++ Creating a tendon joint is not allowed while the articulation is in a scene. In order to
++ add the joint, remove and then re-add the articulation to the scene.
++
++ \param[in] parent The parent tendon joint. Can be NULL for the root tendon joint of a tendon.
++ \param[in] axis The degree of freedom that this tendon joint is associated with.
++ \param[in] coefficient A user-defined scale that the accumulated tendon length is scaled by.
++ \param[in] recipCoefficient The scale that the tendon's response is multiplied by when applying to this tendon joint.
++ \param[in] link The link (and the link's incoming joint in particular) that this tendon joint is associated with.
++
++ \return The newly-created tendon joint if creation was successful, otherwise a null pointer.
++
++ \note
++ - The axis motion must not be configured as PxArticulationMotion::eLOCKED.
++ - The axis cannot be part of a fixed joint, i.e. joint configured as PxArticulationJointType::eFIX.
++
++ \see PxArticulationTendonJoint PxArticulationAxis
++ */
++ virtual PxArticulationTendonJoint* createTendonJoint(PxArticulationTendonJoint* parent, PxArticulationAxis::Enum axis, const PxReal coefficient, const PxReal recipCoefficient, PxArticulationLink* link) = 0;
++
++ /**
++ \brief Fills a user-provided buffer of tendon-joint pointers with the set of tendon joints.
++
++ \param[in] userBuffer The user-provided buffer.
++ \param[in] bufferSize The size of the buffer. If this is not large enough to contain all the pointers to tendon joints,
++ only as many as can fit are written. Use getNbTendonJoints to size for all tendon joints.
++ \param[in] startIndex Index of first tendon joint pointer to be retrieved.
++
++ \return The number of tendon joints filled into the user buffer.
++
++ \see getNbTendonJoints
++ */
++ virtual PxU32 getTendonJoints(PxArticulationTendonJoint** userBuffer, PxU32 bufferSize, PxU32 startIndex = 0) const = 0;
++
++ /**
++ \brief Returns the number of tendon joints in the tendon.
++
++ \return The number of tendon joints.
++ */
++ virtual PxU32 getNbTendonJoints() const = 0;
++
++ /**
++ \brief Sets the spring rest length of the tendon.
++
++ The accumulated "length" of a fixed tendon is a linear combination of the joint axis positions that the tendon is
++ associated with, scaled by the respective tendon joints' coefficients. As such, when the joint positions of all
++ joints are zero, the accumulated length of a fixed tendon is zero.
++
++ The spring of the tendon is not exerting any force on the articulation when the rest length is equal to the
++ tendon's accumulated length plus the tendon offset.
++
++ \param[in] restLength The spring rest length of the tendon.
++
++ \note This method should not be used after the direct GPU API has been enabled and initialized. See #PxDirectGPUAPI for the details.
++
++ \see getRestLength()
++ */
++ virtual void setRestLength(const PxReal restLength) = 0;
++
++ /**
++ \brief Gets the spring rest length of the tendon.
++
++ \return The spring rest length of the tendon.
++
++ \note This method should not be used after the direct GPU API has been enabled and initialized. See #PxDirectGPUAPI for the details.
++
++ \see setRestLength()
++ */
++ virtual PxReal getRestLength() const = 0;
++
++ /**
++ \brief Sets the low and high limit on the length of the tendon.
++
++ \param[in] parameter Struct with the low and high limit.
++
++ The limits, together with the damping and limit stiffness parameters, act on the accumulated length of the tendon.
++
++ \note This method should not be used after the direct GPU API has been enabled and initialized. See #PxDirectGPUAPI for the details.
++
++ \see PxArticulationTendonLimit getLimitParameters() setRestLength()
++ */
++ virtual void setLimitParameters(const PxArticulationTendonLimit& parameter) = 0;
++
++
++ /**
++ \brief Gets the low and high limit on the length of the tendon.
++
++ \return Struct with the low and high limit.
++
++ \note This method should not be used after the direct GPU API has been enabled and initialized. See #PxDirectGPUAPI for the details.
++
++ \see PxArticulationTendonLimit setLimitParameters()
++ */
++ virtual PxArticulationTendonLimit getLimitParameters() const = 0;
++
++ /**
++ \brief Returns the string name of the dynamic type.
++
++ \return The string name.
++ */
++ virtual const char* getConcreteTypeName() const PX_OVERRIDE PX_FINAL { return "PxArticulationFixedTendon"; }
++
++ virtual ~PxArticulationFixedTendon() {}
++
++ protected:
++ PX_INLINE PxArticulationFixedTendon(PxType concreteType, PxBaseFlags baseFlags) : PxArticulationTendon(concreteType, baseFlags) {}
++ PX_INLINE PxArticulationFixedTendon(PxBaseFlags baseFlags) : PxArticulationTendon(baseFlags) {}
++ };
++
++ #if !PX_DOXYGEN
++ } // namespace physx
++ #endif
++
++ #endif
++