qd6joint.cpp

Go to the documentation of this file.

// Copyright (C) 2026 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GPL-3.0-only
 
#include "qd6joint_p.h"
 
#include "physxnode/qphysxactorbody_p.h"
#include "qabstractphysicsnode_p.h"
#include "qstaticphysxobjects_p.h"
 
#include <extensions/PxD6Joint.h>
#include <PxPhysics.h>
 
QT_BEGIN_NAMESPACE
 
 
/*!
    \qmltype D6Joint
    \inqmlmodule QtQuick3D.Physics
    \since 6.13
    \brief A configurable joint with up to 6 degrees of freedom (3 linear, 3 angular).
 
    The D6Joint allows custom configuration for each axis of movement and rotation.
    Each degree of freedom can be set to \c Locked, \c Limited, or \c Free using the \l Motion enum.
    Soft limits with spring stiffness and damping can be configured for linear and angular constraints.
 
    \sa {DistanceJoint}
    \sa {FixedJoint}
    \sa {PrismaticJoint}
    \sa {RevoluteJoint}
    \sa {SphericalJoint}
*/
 
/*!
    \qmlproperty enumeration D6Joint::xMotion
    \since 6.13
    \default D6Joint.Locked
 
    Available options:
 
    \value D6Joint.Locked
    The degree of freedom is completely restricted and cannot move.
    \value D6Joint.Limited
    The degree of freedom is constrained within specified lower and upper limits.
    \value D6Joint.Free
    The degree of freedom is unconstrained and moves freely.
 
    This property holds the motion constraint along the X axis.
*/
 
/*!
    \qmlproperty enumeration D6Joint::yMotion
    \since 6.13
    \default D6Joint.Locked
 
    Available options:
 
    \value D6Joint.Locked
    The degree of freedom is completely restricted and cannot move.
    \value D6Joint.Limited
    The degree of freedom is constrained within specified lower and upper limits.
    \value D6Joint.Free
    The degree of freedom is unconstrained and moves freely.
 
    This property holds the motion constraint along the Y axis.
*/
 
/*!
    \qmlproperty enumeration D6Joint::zMotion
    \since 6.13
    \default D6Joint.Locked
 
    Available options:
 
    \value D6Joint.Locked
    The degree of freedom is completely restricted and cannot move.
    \value D6Joint.Limited
    The degree of freedom is constrained within specified lower and upper limits.
    \value D6Joint.Free
    The degree of freedom is unconstrained and moves freely.
 
    This property holds the motion constraint along the Z axis.
*/
 
/*!
    \qmlproperty enumeration D6Joint::twistMotion
    \since 6.13
    \default D6Joint.Locked
 
    Available options:
 
    \value D6Joint.Locked
    The degree of freedom is completely restricted and cannot move.
    \value D6Joint.Limited
    The degree of freedom is constrained within specified lower and upper limits.
    \value D6Joint.Free
    The degree of freedom is unconstrained and moves freely.
 
    This property holds the rotational constraint around the X axis (twist).
*/
 
/*!
    \qmlproperty enumeration D6Joint::swingMotionY
    \since 6.13
    \default D6Joint.Locked
 
    Available options:
 
    \value D6Joint.Locked
    The degree of freedom is completely restricted and cannot move.
    \value D6Joint.Limited
    The degree of freedom is constrained within specified lower and upper limits.
    \value D6Joint.Free
    The degree of freedom is unconstrained and moves freely.
 
    This property holds the rotational constraint around the Y axis (swing Y).
*/
 
/*!
    \qmlproperty enumeration D6Joint::swingMotionZ
    \since 6.13
    \default D6Joint.Locked
 
    Available options:
 
    \value D6Joint.Locked
    The degree of freedom is completely restricted and cannot move.
    \value D6Joint.Limited
    The degree of freedom is constrained within specified lower and upper limits.
    \value D6Joint.Free
    The degree of freedom is unconstrained and moves freely.
 
    This property holds the rotational constraint around the Z axis (swing Z).
*/
 
/*!
    \qmlproperty real D6Joint::linearLimitXLower
    \since 6.13
    \default -1.0
 
    This property holds the lower limit of movement along the X axis.
    The value must be less than or equal to \l linearLimitXUpper.
 
    Range: \c{(-\inf, \inf)}
*/
 
/*!
    \qmlproperty real D6Joint::linearLimitXUpper
    \since 6.13
    \default 1.0
 
    This property holds the upper limit of movement along the X axis.
    The value must be greater than or equal to \l linearLimitXLower.
 
    Range: \c{(-\inf, \inf)}
*/
 
/*!
    \qmlproperty real D6Joint::linearLimitYLower
    \since 6.13
    \default -1.0
 
    This property holds the lower limit of movement along the Y axis.
    The value must be less than or equal to \l linearLimitYUpper.
 
    Range: \c{(-\inf, \inf)}
*/
 
/*!
    \qmlproperty real D6Joint::linearLimitYUpper
    \since 6.13
    \default 1.0
 
    This property holds the upper limit of movement along the Y axis.
    The value must be greater than or equal to \l linearLimitYLower.
 
    Range: \c{(-\inf, \inf)}
*/
 
/*!
    \qmlproperty real D6Joint::linearLimitZLower
    \since 6.13
    \default -1.0
 
    This property holds the lower limit of movement along the Z axis.
    The value must be less than or equal to \l linearLimitZUpper.
 
    Range: \c{(-\inf, \inf)}
*/
 
/*!
    \qmlproperty real D6Joint::linearLimitZUpper
    \since 6.13
    \default 1.0
 
    This property holds the upper limit of movement along the Z axis.
    The value must be greater than or equal to \l linearLimitZLower.
 
    Range: \c{(-\inf, \inf)}
*/
 
/*!
    \qmlproperty real D6Joint::twistLimitLower
    \since 6.13
    \default -pi/4
 
    This property holds the lower angular limit (in radians) around the X axis.
    The value must be less than or equal to \l twistLimitUpper.
 
    Range: \c{(-2pi, 2pi)}
*/
 
/*!
    \qmlproperty real D6Joint::twistLimitUpper
    \since 6.13
    \default pi/4
 
    This property holds the upper angular limit (in radians) around the X axis.
    The value must be greater than or equal to \l twistLimitLower.
 
    Range: \c{(-2pi, 2pi)}
*/
 
/*!
    \qmlproperty real D6Joint::swingLimitAngleY
    \since 6.13
    \default pi/4
 
    This property holds the maximum swing angle limit (in radians) around the Y axis.
 
    Range: \c{(0, pi)}
*/
 
/*!
    \qmlproperty real D6Joint::swingLimitAngleZ
    \since 6.13
    \default pi/4
 
    This property holds the maximum swing angle limit (in radians) around the Z axis.
 
    Range: \c{(0, pi)}
*/
 
/*!
    \qmlproperty real D6Joint::linearStiffness
    \since 6.13
    \default 0.0
 
    This property holds the spring stiffness for linear motion constraints.
    When set to a value greater than 0, linear limits act as soft constraints (springs).
 
    Range: \c{[0, \inf)}
*/
 
/*!
    \qmlproperty real D6Joint::linearDamping
    \since 6.13
    \default 0.0
 
    This property holds the spring damping for linear motion constraints.
 
    Range: \c{[0, \inf)}
*/
 
/*!
    \qmlproperty real D6Joint::angularStiffness
    \since 6.13
    \default 0.0
 
    This property holds the spring stiffness for angular motion constraints.
    When set to a value greater than 0, angular limits act as soft constraints (springs).
 
    Range: \c{[0, \inf)}
*/
 
/*!
    \qmlproperty real D6Joint::angularDamping
    \since 6.13
    \default 0.0
 
    This property holds the spring damping for angular motion constraints.
 
    Range: \c{[0, \inf)}
*/
 
namespace  {
physx::PxD6Motion::Enum toPxEnum(QD6Joint::Motion val)
{
    switch (val) {
    case QD6Joint::Motion::Locked: return physx::PxD6Motion::eLOCKED;
    case QD6Joint::Motion::Limited: return physx::PxD6Motion::eLIMITED;
    case QD6Joint::Motion::Free: return physx::PxD6Motion::eFREE;
    }
 
    Q_UNREACHABLE_RETURN(physx::PxD6Motion::eLOCKED);
}
}
 
QD6Joint::QD6Joint() = default;
 
QD6Joint::Motion QD6Joint::xMotion() const
{
    return m_xMotion;
}
 
void QD6Joint::setXMotion(Motion motion)
{
    if (m_xMotion == motion)
        return;
    m_xMotion = motion;
    m_dirtyProperties = true;
    emit xMotionChanged();
}
 
QD6Joint::Motion QD6Joint::yMotion() const
{
    return m_yMotion;
}
 
void QD6Joint::setYMotion(Motion motion)
{
    if (m_yMotion == motion)
        return;
    m_yMotion = motion;
    m_dirtyProperties = true;
    emit yMotionChanged();
}
 
QD6Joint::Motion QD6Joint::zMotion() const
{
    return m_zMotion;
}
 
void QD6Joint::setZMotion(Motion motion)
{
    if (m_zMotion == motion)
        return;
    m_zMotion = motion;
    m_dirtyProperties = true;
    emit zMotionChanged();
}
 
QD6Joint::Motion QD6Joint::twistMotion() const
{
    return m_twistMotion;
}
 
void QD6Joint::setTwistMotion(Motion motion)
{
    if (m_twistMotion == motion)
        return;
    m_twistMotion = motion;
    m_dirtyProperties = true;
    emit twistMotionChanged();
}
 
float QD6Joint::linearLimitXLower() const
{
    return m_linearLimitXLower;
}
 
void QD6Joint::setLinearLimitXLower(float limit)
{
    if (qFuzzyCompare(m_linearLimitXLower, limit))
        return;
    m_linearLimitXLower = limit;
    m_dirtyProperties = true;
    emit linearLimitXLowerChanged();
}
 
float QD6Joint::linearLimitXUpper() const
{
    return m_linearLimitXUpper;
}
 
void QD6Joint::setLinearLimitXUpper(float limit)
{
    if (qFuzzyCompare(m_linearLimitXUpper, limit))
        return;
    m_linearLimitXUpper = limit;
    m_dirtyProperties = true;
    emit linearLimitXUpperChanged();
}
 
float QD6Joint::linearLimitYLower() const
{
    return m_linearLimitYLower;
}
 
void QD6Joint::setLinearLimitYLower(float limit)
{
    if (qFuzzyCompare(m_linearLimitYLower, limit))
        return;
    m_linearLimitYLower = limit;
    m_dirtyProperties = true;
    emit linearLimitYLowerChanged();
}
 
float QD6Joint::linearLimitYUpper() const
{
    return m_linearLimitYUpper;
}
 
void QD6Joint::setLinearLimitYUpper(float limit)
{
    if (qFuzzyCompare(m_linearLimitYUpper, limit))
        return;
    m_linearLimitYUpper = limit;
    m_dirtyProperties = true;
    emit linearLimitYUpperChanged();
}
 
float QD6Joint::linearLimitZLower() const
{
    return m_linearLimitZLower;
}
 
void QD6Joint::setLinearLimitZLower(float limit)
{
    if (qFuzzyCompare(m_linearLimitZLower, limit))
        return;
    m_linearLimitZLower = limit;
    m_dirtyProperties = true;
    emit linearLimitZLowerChanged();
}
 
float QD6Joint::linearLimitZUpper() const
{
    return m_linearLimitZUpper;
}
 
void QD6Joint::setLinearLimitZUpper(float limit)
{
    if (qFuzzyCompare(m_linearLimitZUpper, limit))
        return;
    m_linearLimitZUpper = limit;
    m_dirtyProperties = true;
    emit linearLimitZUpperChanged();
}
 
float QD6Joint::twistLimitLower() const
{
    return m_twistLimitLower;
}
 
void QD6Joint::setTwistLimitLower(float limit)
{
    // PhysX requires the twist limit to be strictly within (-2*Pi, 2*Pi)
    limit = qBound(-float(M_PI * 2) + 0.0001f, limit, float(M_PI * 2) - 0.0001f);
 
    if (qFuzzyCompare(m_twistLimitLower, limit))
        return;
    m_twistLimitLower = limit;
    m_dirtyProperties = true;
    emit twistLimitLowerChanged();
}
 
float QD6Joint::twistLimitUpper() const
{
    return m_twistLimitUpper;
}
 
void QD6Joint::setTwistLimitUpper(float limit)
{
    // PhysX requires the twist limit to be strictly within (-2*Pi, 2*Pi)
    limit = qBound(-float(M_PI * 2) + 0.0001f, limit, float(M_PI * 2) - 0.0001f);
 
    if (qFuzzyCompare(m_twistLimitUpper, limit))
        return;
    m_twistLimitUpper = limit;
    m_dirtyProperties = true;
    emit twistLimitUpperChanged();
}
 
float QD6Joint::linearStiffness() const
{
    return m_linearStiffness;
}
 
void QD6Joint::setLinearStiffness(float stiffness)
{
    stiffness = qMax(0.f, stiffness);
 
    if (qFuzzyCompare(m_linearStiffness, stiffness))
        return;
    m_linearStiffness = stiffness;
    m_dirtyProperties = true;
    emit linearStiffnessChanged();
}
 
float QD6Joint::linearDamping() const
{
    return m_linearDamping;
}
 
void QD6Joint::setLinearDamping(float damping)
{
    damping = qMax(0.f, damping);
 
    if (qFuzzyCompare(m_linearDamping, damping))
        return;
    m_linearDamping = damping;
    m_dirtyProperties = true;
    emit linearDampingChanged();
}
 
float QD6Joint::angularStiffness() const
{
    return m_angularStiffness;
}
 
void QD6Joint::setAngularStiffness(float stiffness)
{
    stiffness = qMax(0.f, stiffness);
    if (qFuzzyCompare(m_angularStiffness, stiffness))
        return;
    m_angularStiffness = stiffness;
    m_dirtyProperties = true;
    emit angularStiffnessChanged();
}
 
float QD6Joint::angularDamping() const
{
    return m_angularDamping;
}
 
void QD6Joint::setAngularDamping(float damping)
{
    damping = qMax(0.f, damping);
    if (qFuzzyCompare(m_angularDamping, damping))
        return;
    m_angularDamping = damping;
    m_dirtyProperties = true;
    emit angularDampingChanged();
}
 
 
QD6Joint::Motion QD6Joint::swingMotionY() const
{
    return m_swingMotionY;
}
 
void QD6Joint::setSwingMotionY(Motion newSwingMotionY)
{
    if (m_swingMotionY == newSwingMotionY)
        return;
    m_swingMotionY = newSwingMotionY;
    m_dirtyProperties = true;
    emit swingMotionYChanged();
}
 
QD6Joint::Motion QD6Joint::swingMotionZ() const
{
    return m_swingMotionZ;
}
 
void QD6Joint::setSwingMotionZ(Motion newSwingMotionZ)
{
    if (m_swingMotionZ == newSwingMotionZ)
        return;
    m_swingMotionZ = newSwingMotionZ;
    m_dirtyProperties = true;
    emit swingMotionZChanged();
}
 
float QD6Joint::swingLimitAngleY() const
{
    return m_swingLimitAngleY;
}
 
void QD6Joint::setSwingLimitAngleY(float newSwingLimitAngleY)
{
    // Clamp swing angle between Math standard (0, Pi)
    newSwingLimitAngleY = qBound(0.0001f, newSwingLimitAngleY, float(M_PI) - 0.0001f);
 
    if (qFuzzyCompare(m_swingLimitAngleY, newSwingLimitAngleY))
        return;
    m_swingLimitAngleY = newSwingLimitAngleY;
    m_dirtyProperties = true;
    emit swingLimitAngleYChanged();
}
 
float QD6Joint::swingLimitAngleZ() const
{
    return m_swingLimitAngleZ;
}
 
void QD6Joint::setSwingLimitAngleZ(float newSwingLimitAngleZ)
{
    // Clamp swing angle between Math standard (0, Pi)
    newSwingLimitAngleZ = qBound(0.0001f, newSwingLimitAngleZ, float(M_PI) - 0.0001f);
 
    if (qFuzzyCompare(m_swingLimitAngleZ, newSwingLimitAngleZ))
        return;
    m_swingLimitAngleZ = newSwingLimitAngleZ;
    m_dirtyProperties = true;
    emit swingLimitAngleZChanged();
}
 
physx::PxJoint *QD6Joint::createPhysxJoint(physx::PxRigidActor *actorA,
                                           physx::PxRigidActor *actorB,
                                           const physx::PxTransform &trfA,
                                           const physx::PxTransform &trfB)
{
    return physx::PxD6JointCreate(*StaticPhysXObjects::getReference().physics,
                                  actorA, trfA, actorB, trfB);
}
 
void QD6Joint::setJointProperties()
{
    auto *d6Joint = static_cast<physx::PxD6Joint *>(m_joint);
    if (!d6Joint)
        return;
 
    const physx::PxTolerancesScale scale =
            StaticPhysXObjects::getReference().physics->getTolerancesScale();
 
    d6Joint->setMotion(physx::PxD6Axis::eX, toPxEnum(m_xMotion));
    d6Joint->setMotion(physx::PxD6Axis::eY, toPxEnum(m_yMotion));
    d6Joint->setMotion(physx::PxD6Axis::eZ, toPxEnum(m_zMotion));
    d6Joint->setMotion(physx::PxD6Axis::eTWIST, toPxEnum(m_twistMotion));
    d6Joint->setMotion(physx::PxD6Axis::eSWING1, toPxEnum(m_swingMotionY));
    d6Joint->setMotion(physx::PxD6Axis::eSWING2, toPxEnum(m_swingMotionZ));
 
    if (m_xMotion == Motion::Limited) {
        physx::PxJointLinearLimitPair limit(scale, qMin(m_linearLimitXLower, m_linearLimitXUpper),
                                            qMax(m_linearLimitXLower, m_linearLimitXUpper));
        limit.stiffness = m_linearStiffness; // Use linear stiffness for linear limits
        limit.damping = m_linearDamping;     // Use linear damping for linear limits
        d6Joint->setLinearLimit(physx::PxD6Axis::eX, limit);
    }
 
    if (m_yMotion == Motion::Limited) {
        physx::PxJointLinearLimitPair limit(scale, qMin(m_linearLimitYLower, m_linearLimitYUpper),
                                            qMax(m_linearLimitYLower, m_linearLimitYUpper));
        limit.stiffness = m_linearStiffness; // Use linear stiffness for linear limits
        limit.damping = m_linearDamping;     // Use linear damping for linear limits
        d6Joint->setLinearLimit(physx::PxD6Axis::eY, limit);
    }
 
    if (m_zMotion == Motion::Limited) {
        physx::PxJointLinearLimitPair limit(scale, qMin(m_linearLimitZLower, m_linearLimitZUpper),
                                            qMax(m_linearLimitZLower, m_linearLimitZUpper));
        limit.stiffness = m_linearStiffness; // Use linear stiffness for linear limits
        limit.damping = m_linearDamping;     // Use linear damping for linear limits
        d6Joint->setLinearLimit(physx::PxD6Axis::eZ, limit);
    }
 
    if (m_twistMotion == Motion::Limited) {
        physx::PxJointAngularLimitPair limit(qMin(m_twistLimitLower, m_twistLimitUpper),
                                             qMax(m_twistLimitLower, m_twistLimitUpper));
        limit.stiffness = m_angularStiffness; // Use angular stiffness for twist limit
        limit.damping = m_angularDamping;     // Use angular damping for twist limit
        d6Joint->setTwistLimit(limit);
    }
 
    if (m_swingMotionY == Motion::Limited || m_swingMotionZ == Motion::Limited) {
        // PhysX requires cone angles to be strictly within (0, Pi) range
        const float angleY = qBound(0.0001f, m_swingLimitAngleY, float(M_PI) - 0.0001f);
        const float angleZ = qBound(0.0001f, m_swingLimitAngleZ, float(M_PI) - 0.0001f);
 
        physx::PxJointLimitCone limit(angleY, angleZ);
        limit.stiffness = m_angularStiffness;
        limit.damping = m_angularDamping;
        d6Joint->setSwingLimit(limit);
    }
}
 
QT_END_NAMESPACE