Module org.dyn4j
Package org.dyn4j.dynamics.joint

Class DistanceJoint<T extends PhysicsBody>

  • Type Parameters:
    T - the PhysicsBody type
    All Implemented Interfaces:
    DataContainer, Shiftable, Ownable
    public class DistanceJoint<T extends PhysicsBody>
extends Joint<T>
implements Shiftable, DataContainer
    Implementation of a fixed length distance joint.

    Given the two world space anchor points a distance is computed and used to constrain the attached PhysicsBodys at that distance. The bodies can rotate freely about the anchor points and the whole system can move and rotate freely, but the distance between the two anchor points is fixed.

    This joint doubles as a spring/damper distance joint where the length can change but is constantly approaching the target distance. Enable the spring/damper by setting the frequency and damping ratio to values greater than zero. A good starting point is a frequency of 8.0 and damping ratio of 0.3 then adjust as necessary.

    Since:
    1.0.0
    Version:
    4.2.0
    Author:
    William Bittle
    See Also:
    Documentation, Distance Constraint

    • Field Detail

      • localAnchor1

        protected final Vector2 localAnchor1
        The local anchor point on the first PhysicsBody

      • localAnchor2

        protected final Vector2 localAnchor2
        The local anchor point on the second PhysicsBody

      • distance

        @Deprecated
protected double distance
        Deprecated.
        Deprecated in 4.2.0. Use restDistance instead.
        The rest distance

      • restDistance

        protected double restDistance
        The rest distance

      • frequency

        protected double frequency
        The oscillation frequency in hz

      • dampingRatio

        protected double dampingRatio
        The damping ratio

      • upperLimit

        protected double upperLimit
        The maximum distance between the two world space anchor points

      • lowerLimit

        protected double lowerLimit
        The minimum distance between the two world space anchor points

      • upperLimitEnabled

        protected boolean upperLimitEnabled
        Whether the maximum distance is enabled

      • lowerLimitEnabled

        protected boolean lowerLimitEnabled
        Whether the minimum distance is enabled

      • currentDistance

        protected double currentDistance
        The current distance as of constraint initialization

    • Constructor Detail

      • DistanceJoint

        public DistanceJoint​(T body1,
                     T body2,
                     Vector2 anchor1,
                     Vector2 anchor2)
        Minimal constructor.

        Creates a fixed distance Joint where the joined PhysicsBodys do not participate in collision detection and resolution.

        Parameters:
        body1 - the first PhysicsBody
        body2 - the second PhysicsBody
        anchor1 - in world coordinates
        anchor2 - in world coordinates
        Throws:
        NullPointerException - if body1, body2, anchor1, or anchor2 is null
        IllegalArgumentException - if body1 == body2

    • Method Detail

      • initializeConstraints

        public void initializeConstraints​(TimeStep step,
                                  Settings settings)
        Description copied from class: Joint
        Performs any initialization of the velocity and position constraints.
        Specified by:
        initializeConstraints in class Joint<T extends PhysicsBody>
        Parameters:
        step - the time step information
        settings - the current world settings

      • solveVelocityConstraints

        public void solveVelocityConstraints​(TimeStep step,
                                     Settings settings)
        Description copied from class: Joint
        Solves the velocity constraints.
        Specified by:
        solveVelocityConstraints in class Joint<T extends PhysicsBody>
        Parameters:
        step - the time step information
        settings - the current world settings

      • solvePositionConstraints

        public boolean solvePositionConstraints​(TimeStep step,
                                        Settings settings)
        Description copied from class: Joint
        Solves the position constraints.
        Specified by:
        solvePositionConstraints in class Joint<T extends PhysicsBody>
        Parameters:
        step - the time step information
        settings - the current world settings
        Returns:
        boolean true if the position constraints were solved

      • getReactionForce

        public Vector2 getReactionForce​(double invdt)
        Description copied from class: Joint
        Returns the force applied to the PhysicsBodys in order to satisfy the constraint in newtons.
        Specified by:
        getReactionForce in class Joint<T extends PhysicsBody>
        Parameters:
        invdt - the inverse delta time
        Returns:
        Vector2

      • getReactionTorque

        public double getReactionTorque​(double invdt)
        Returns the torque applied to the PhysicsBodys in order to satisfy the constraint in newton-meters.

        Not applicable to this joint. Always returns zero.

        Specified by:
        getReactionTorque in class Joint<T extends PhysicsBody>
        Parameters:
        invdt - the inverse delta time
        Returns:
        double

      • shift

        public void shift​(Vector2 shift)
        Description copied from interface: Shiftable
        Translates the object to match the given coordinate shift.
        Specified by:
        shift in interface Shiftable
        Parameters:
        shift - the amount to shift along the x and y axes

      • isSpringEnabled

        public boolean isSpringEnabled()
        Returns true if this distance joint is a spring distance joint.
        Returns:
        boolean
        Since:
        4.0.0

      • isSpringDamperEnabled

        public boolean isSpringDamperEnabled()
        Returns true if this distance joint is a spring distance joint with damping.
        Returns:
        boolean
        Since:
        4.0.0

      • getDistance

        @Deprecated
public double getDistance()
        Deprecated.
        Deprecated in 4.2.0. Use getRestDistance() instead.
        Returns the rest distance between the two constrained PhysicsBodys in meters.
        Returns:
        double

      • getRestDistance

        public double getRestDistance()
        Returns the rest distance between the two constrained PhysicsBodys in meters.
        Returns:
        double
        Since:
        4.2.0

      • setRestDistance

        public void setRestDistance​(double distance)
        Sets the rest distance between the two constrained PhysicsBodys in meters.
        Parameters:
        distance - the distance in meters
        Throws:
        IllegalArgumentException - if distance is less than zero
        Since:
        4.2.0

      • getCurrentDistance

        public double getCurrentDistance()
        Returns the current distance between the anchor points.
        Returns:
        double
        Since:
        4.2.0

      • getDampingRatio

        public double getDampingRatio()
        Returns the damping ratio.
        Returns:
        double

      • setDampingRatio

        public void setDampingRatio​(double dampingRatio)
        Sets the damping ratio.

        Larger values reduce the oscillation of the spring.

        Parameters:
        dampingRatio - the damping ratio; in the range [0, 1]
        Throws:
        IllegalArgumentException - if damping ration is less than zero or greater than 1

      • getFrequency

        public double getFrequency()
        Returns the spring frequency.
        Returns:
        double

      • setFrequency

        public void setFrequency​(double frequency)
        Sets the spring frequency.

        Larger values increase the stiffness of the spring.

        Parameters:
        frequency - the spring frequency in hz; must be greater than or equal to zero
        Throws:
        IllegalArgumentException - if frequency is less than zero

      • getUpperLimit

        public double getUpperLimit()
        Returns the upper limit in meters.
        Returns:
        double
        Since:
        4.2.0

      • setUpperLimit

        public void setUpperLimit​(double upperLimit)
        Sets the upper limit in meters.
        Parameters:
        upperLimit - the upper limit in meters; must be greater than or equal to zero
        Throws:
        IllegalArgumentException - if upperLimit is less than zero or less than the current lower limit
        Since:
        4.2.0

      • setUpperLimitEnabled

        public void setUpperLimitEnabled​(boolean flag)
        Sets whether the upper limit is enabled.
        Parameters:
        flag - true if the upper limit should be enabled
        Since:
        4.2.0

      • isUpperLimitEnabled

        public boolean isUpperLimitEnabled()
        Returns true if the upper limit is enabled.
        Returns:
        boolean true if the upper limit is enabled
        Since:
        4.2.0

      • getLowerLimit

        public double getLowerLimit()
        Returns the lower limit in meters.
        Returns:
        double
        Since:
        4.2.0

      • setLowerLimit

        public void setLowerLimit​(double lowerLimit)
        Sets the lower limit in meters.
        Parameters:
        lowerLimit - the lower limit in meters; must be greater than or equal to zero
        Throws:
        IllegalArgumentException - if lowerLimit is less than zero or greater than the current upper limit
        Since:
        4.2.0

      • setLowerLimitEnabled

        public void setLowerLimitEnabled​(boolean flag)
        Sets whether the lower limit is enabled.
        Parameters:
        flag - true if the lower limit should be enabled
        Since:
        4.2.0

      • isLowerLimitEnabled

        public boolean isLowerLimitEnabled()
        Returns true if the lower limit is enabled.
        Returns:
        boolean true if the lower limit is enabled
        Since:
        4.2.0

      • setLimits

        public void setLimits​(double lowerLimit,
                      double upperLimit)
        Sets both the lower and upper limits.
        Parameters:
        lowerLimit - the lower limit in meters; must be greater than or equal to zero
        upperLimit - the upper limit in meters; must be greater than or equal to zero
        Throws:
        IllegalArgumentException - if lowerLimit is less than zero, upperLimit is less than zero, or lowerLimit is greater than upperLimit
        Since:
        4.2.0

      • setLimitsEnabled

        public void setLimitsEnabled​(double lowerLimit,
                             double upperLimit)
        Sets both the lower and upper limits and enables both.
        Parameters:
        lowerLimit - the lower limit in meters; must be greater than or equal to zero
        upperLimit - the upper limit in meters; must be greater than or equal to zero
        Throws:
        IllegalArgumentException - if lowerLimit is less than zero, upperLimit is less than zero, or lowerLimit is greater than upperLimit
        Since:
        4.2.0

      • setLimitsEnabled

        public void setLimitsEnabled​(boolean flag)
        Enables or disables both the lower and upper limits.
        Parameters:
        flag - true if both limits should be enabled
        Since:
        4.2.0

      • setLimits

        public void setLimits​(double limit)
        Sets both the lower and upper limits to the given limit.

        This makes the joint a fixed length joint.

        Parameters:
        limit - the desired limit
        Throws:
        IllegalArgumentException - if limit is less than zero
        Since:
        4.2.0

      • setLimitsEnabled

        public void setLimitsEnabled​(double limit)
        Sets both the lower and upper limits to the given limit and enables both.

        This makes the joint a fixed length joint.

        Parameters:
        limit - the desired limit
        Throws:
        IllegalArgumentException - if limit is less than zero
        Since:
        4.2.0