org.odejava
Class JointHinge2

java.lang.Object
  extended by org.odejava.Joint
      extended by org.odejava.JointHinge2

public class JointHinge2
extends Joint

A joint that allows movement along two separate axis, with the calculations implemented as the joints connected in series. There is also a suspension setting allowing the use of this joint in places like a wheel of a car.

A Hinge-2 joint has two axes located around a common anchor point. Axis 1 is specified relative to the first body and axis 2 is specified relative to the second body. Axis 1 can have limits and a motor, axis 2 can only have a motor.

Created 20.12.2003 (dd.mm.yyyy)

Author:
Jani Laakso E-mail: jani.laakso@itmill.com see http://odejava.dev.java.net

Field Summary
 
Fields inherited from class org.odejava.Joint
body1, body2, BOUNCE_RANGE_MSG, deleted, feedback, group, jointGroupId, jointId, name
 
Constructor Summary
JointHinge2(String name, World world)
          Create a new Hinge2 joint that belongs to the given world and has a name.
JointHinge2(String name, World world, JointGroup jointGroup)
          Create a new Hinge-2 joint that belongs to the given world.
JointHinge2(World world)
          Create a new Hinge2 joint that belongs to the given world and does not belong to any group.
JointHinge2(World world, JointGroup jointGroup)
          Create a new Hinge-2 joint that belongs to the given world.
 
Method Summary
 org.openmali.vecmath2.Vector3f getAnchor()
          Get the anchor location of the joint, relative to body 1.
 void getAnchor(float[] result)
          Get the anchor location the joint, relative to body 1 and place it in the user-provided array.
<T extends org.openmali.vecmath2.Tuple3f>
T
getAnchor(T result)
          Get the anchor location of the joint, relative to body 1, and place it in the user-provided data structure.
 org.openmali.vecmath2.Vector3f getAnchor2()
          Get the anchor location of the joint, relative to body 2.
 void getAnchor2(float[] result)
          Get the anchor location the joint, relative to body 2 and place it in the user-provided array.
<T extends org.openmali.vecmath2.Tuple3f>
T
getAnchor2(T result)
          Get the anchor location of the joint, relative to body 2, and place it in the user-provided data structure.
 float getAngle1()
           
 float getAngle1Rate()
           
 float getAngle2Rate()
           
 org.openmali.vecmath2.Vector3f getAxis1()
          Get the axis 1 direction vector.
 void getAxis1(float[] result)
          Get the axis 1 direction vector and place it in the user-provided array.
 org.openmali.vecmath2.Vector3f getAxis1(org.openmali.vecmath2.Vector3f result)
          Get the axis 1 direction vector, and place it in the user-provided data structure.
 org.openmali.vecmath2.Vector3f getAxis2()
          Get the axis 2 direction vector.
 void getAxis2(float[] result)
          Get the axis 2 direction vector and place it in the user-provided array.
 org.openmali.vecmath2.Vector3f getAxis2(org.openmali.vecmath2.Vector3f result)
          Get the axis 2 direction vector, and place it in the user-provided data structure.
 float getConstantForceMix()
          Get the amount of the constant force mix parameter currently set for axis 1 positions between the two stops.
 float getConstantForceMix2()
          Get the amount of the constant force mix parameter currently set for axis 2 positions between the two stops.
 float getDesiredAngularVelocity1()
          Get the requested angular speed currently set axis 1.
 float getDesiredAngularVelocity2()
          Get the requested angular speed currently set axis 2.
 float getMaxAngleStop()
          Fetch the currently set maximum angle stop for axis 1 from this joint.
 float getMaxTorque1()
          Get the amount of the torque currently set for the motor on axis 1.
 float getMaxTorque2()
          Get the amount of the torque currently set for the motor on axis 2.
 float getMinAngleStop()
          Fetch the currently set maximum angle stop for axis 1from this joint.
 float getParam(int parameter)
          Get an unchecked parameter value directly from this joint.
 float getStopBounce()
          Fetch the current bounce factor for the stop on axis 1.
 float getStopCFM()
          Get the amount of the stop constant force mix parameter currently set.
 float getStopERP()
          Get the amount of the stop error reduction parameter currently set.
 float getSuspensionCFM()
          Get the amount of the suspension constant force mix parameter currently set.
 float getSuspensionERP()
          Get the amount of the suspension error reduction parameter currently set.
 void setAnchor(float x, float y, float z)
          Set the anchor location to a new value, using individual values.
 void setAnchor(org.openmali.vecmath2.Vector3f position)
          Set the anchor location, relative to body 1 to a new value, using a vector.
 void setAxis1(float x, float y, float z)
          Set the axis 1 vector to a new value, using individual values.
 void setAxis2(float x, float y, float z)
          Set the axis 2 vector to a new value, using individual values.
 void setConstantForceMix(float force)
          Set the amount of constant force to mix into the system on axis 1 when the bodies are not at a stop.
 void setConstantForceMix2(float force)
          Set the amount of constant force to mix into the system on axis 2 when the bodies are not at a stop.
 void setDesiredAngularVelocity1(float speed)
          Set the angular speed that you would like axis 1 to achieve.
 void setDesiredAngularVelocity2(float speed)
          Set the angular speed that you would like axis 2 to achieve.
 void setMaxAngleStop(float angle)
          Set the maximum angle that this joint is permitted to rotate to around axis 1.
 void setMaxTorque1(float torque)
          Set the amount of torque on axis 1 that can be applied by the motor, in order to reach the desired angular velocity.
 void setMaxTorque2(float torque)
          Set the amount of torque on axis 2 that can be applied by the motor, in order to reach the desired angular velocity.
 void setMinAngleStop(float angle)
          Set the minimum angle that this joint is permitted to rotate to around axis 1.
 void setParam(int parameter, float value)
          Set a generic, unchecked, parameter directly for this joint.
 void setStopBounce(float bounce)
          Set the bounciness of the stops for axis 1.
 void setStopCFM(float force)
          Set the amount of stop constant force to mix into the system when the bodies reach a stop.
 void setStopERP(float erp)
          Set the amount of stop bounce error reduction.
 void setSuspensionCFM(float force)
          Set the amount of suspension constant force to mix into the system when the bodies are travelling between the stops on axis 1.
 void setSuspensionERP(float erp)
          Set the amount of suspension error reduction.
 
Methods inherited from class org.odejava.Joint
attach, delete, enableFeedbackTracking, enableFeedbackTracking, getBody1, getBody2, getFeedback, getGroup, getName, isFeedbackTrackingEnabled, setName
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

JointHinge2

public JointHinge2(World world)
Create a new Hinge2 joint that belongs to the given world and does not belong to any group. The name is set to the null string.

Parameters:
world - The world that this belongs to

JointHinge2

public JointHinge2(String name,
                   World world)
Create a new Hinge2 joint that belongs to the given world and has a name. The name parameter is optional. The joint is attached to the global environment.

Parameters:
name - A label string to associate with this joint
world - The world that this belongs to

JointHinge2

public JointHinge2(World world,
                   JointGroup jointGroup)
Create a new Hinge-2 joint that belongs to the given world. The JointGroup is optional and the name is set to the null string. If no group is provided, the joint is attached to the global environment.

Parameters:
world - The world that this belongs to
jointGroup - An optional group to associate this joint with

JointHinge2

public JointHinge2(String name,
                   World world,
                   JointGroup jointGroup)
Create a new Hinge-2 joint that belongs to the given world. The JointGroup and name parameters are optional. If no group is provided, the joint is attached to the global environment.

Parameters:
name - A label string to associate with this joint
world - The world that this belongs to
jointGroup - An optional group to associate this joint with
Method Detail

setAnchor

public void setAnchor(float x,
                      float y,
                      float z)
Set the anchor location to a new value, using individual values.

Parameters:
x - The x component of the the anchor location
y - The y component of the the anchor location
z - The z component of the the anchor location

setAnchor

public final void setAnchor(org.openmali.vecmath2.Vector3f position)
Set the anchor location, relative to body 1 to a new value, using a vector.

Parameters:
position - A vector holding the anchor location

getAnchor

public org.openmali.vecmath2.Vector3f getAnchor()
Get the anchor location of the joint, relative to body 1. A new Vector3f instance will be created for each request. This is identical to calling getAnchor(null).

Returns:
A new vector object containing the location

getAnchor

public <T extends org.openmali.vecmath2.Tuple3f> T getAnchor(T result)
Get the anchor location of the joint, relative to body 1, and place it in the user-provided data structure. If the user-provided data structure is null, then a new instance is created and returned, otherwise the user provided structure is used as the return value.

Parameters:
result - An object to place the values into or null
Returns:
Either the result parameter or a new object

getAnchor

public void getAnchor(float[] result)
Get the anchor location the joint, relative to body 1 and place it in the user-provided array.

Parameters:
result - An object to place the values into

getAnchor2

public org.openmali.vecmath2.Vector3f getAnchor2()
Get the anchor location of the joint, relative to body 2. A new Vector3f instance will be created for each request. This is identical to calling getAnchor2(null).

Returns:
A new vector object containing the location

getAnchor2

public <T extends org.openmali.vecmath2.Tuple3f> T getAnchor2(T result)
Get the anchor location of the joint, relative to body 2, and place it in the user-provided data structure. If the user-provided data structure is null, then a new instance is created and returned, otherwise the user provided structure is used as the return value.

Parameters:
result - An object to place the values into or null
Returns:
Either the result parameter or a new object

getAnchor2

public void getAnchor2(float[] result)
Get the anchor location the joint, relative to body 2 and place it in the user-provided array.

Parameters:
result - An object to place the values into

setAxis1

public void setAxis1(float x,
                     float y,
                     float z)
Set the axis 1 vector to a new value, using individual values.

Overrides:
setAxis1 in class Joint
Parameters:
x - The x component of the the axis vector
y - The y component of the the axis vector
z - The z component of the the axis vector

getAxis1

public org.openmali.vecmath2.Vector3f getAxis1()
Get the axis 1 direction vector. A new Vector3f instance will be created for each request. This is identical to calling getAxis1(null).

Returns:
A new vector object containing the location

getAxis1

public org.openmali.vecmath2.Vector3f getAxis1(org.openmali.vecmath2.Vector3f result)
Get the axis 1 direction vector, and place it in the user-provided data structure. If the user-provided data structure is null, then a new instance is created and returned, otherwise the user provided structure is used as the return value.

Parameters:
result - An object to place the values into or null
Returns:
Either the result parameter or a new object

getAxis1

public void getAxis1(float[] result)
Get the axis 1 direction vector and place it in the user-provided array.

Parameters:
result - An object to place the values into

setAxis2

public void setAxis2(float x,
                     float y,
                     float z)
Set the axis 2 vector to a new value, using individual values.

Overrides:
setAxis2 in class Joint
Parameters:
x - The x component of the the axis vector
y - The y component of the the axis vector
z - The z component of the the axis vector

getAxis2

public org.openmali.vecmath2.Vector3f getAxis2()
Get the axis 2 direction vector. A new Vector3f instance will be created for each request. This is identical to calling getAxis2(null).

Returns:
A new vector object containing the location

getAxis2

public org.openmali.vecmath2.Vector3f getAxis2(org.openmali.vecmath2.Vector3f result)
Get the axis 2 direction vector, and place it in the user-provided data structure. If the user-provided data structure is null, then a new instance is created and returned, otherwise the user provided structure is used as the return value.

Parameters:
result - An object to place the values into or null
Returns:
Either the result parameter or a new object

getAxis2

public void getAxis2(float[] result)
Get the axis 2 direction vector and place it in the user-provided array.

Parameters:
result - An object to place the values into

getAngle1

public float getAngle1()

getAngle1Rate

public float getAngle1Rate()

getAngle2Rate

public float getAngle2Rate()

setDesiredAngularVelocity1

public void setDesiredAngularVelocity1(float speed)
Set the angular speed that you would like axis 1 to achieve. This is not an instantaneous change, it is just a request that the system attempt to achieve this. Typically the torque of the motor on this axis will be used, but other factors, such as external forces will come into play.

Parameters:
speed - The speed that should be achieved

getDesiredAngularVelocity1

public float getDesiredAngularVelocity1()
Get the requested angular speed currently set axis 1. This requests the desired speed, not the actual speed currently calculated by the physics model.

Returns:
The current speed requested

setDesiredAngularVelocity2

public void setDesiredAngularVelocity2(float speed)
Set the angular speed that you would like axis 2 to achieve. This is not an instantaneous change, it is just a request that the system attempt to achieve this. Typically the torque of the motor on this axis will be used, but other factors, such as external forces will come into play.

Parameters:
speed - The speed that should be achieved

getDesiredAngularVelocity2

public float getDesiredAngularVelocity2()
Get the requested angular speed currently set axis 2. This requests the desired speed, not the actual speed currently calculated by the physics model.

Returns:
The current speed requested

setMaxTorque1

public void setMaxTorque1(float torque)
                   throws IllegalArgumentException
Set the amount of torque on axis 1 that can be applied by the motor, in order to reach the desired angular velocity. Value must always be greater than zero for it to have an effect. A value of zero disables this motor. Torque is defined in Newton-metres.

Parameters:
torque - The amount of torque to use in Nm
Throws:
IllegalArgumentException - The torque value is negative

getMaxTorque1

public float getMaxTorque1()
Get the amount of the torque currently set for the motor on axis 1.

Returns:
The current torque in Nm

setMaxTorque2

public void setMaxTorque2(float torque)
                   throws IllegalArgumentException
Set the amount of torque on axis 2 that can be applied by the motor, in order to reach the desired angular velocity. Value must always be greater than zero for it to have an effect. A value of zero disables this motor. Torque is defined in Newton-metres.

Parameters:
torque - The amount of torque to use in Nm
Throws:
IllegalArgumentException - The torque value is negative

getMaxTorque2

public float getMaxTorque2()
Get the amount of the torque currently set for the motor on axis 2.

Returns:
The current torque in Nm

setConstantForceMix

public void setConstantForceMix(float force)
Set the amount of constant force to mix into the system on axis 1 when the bodies are not at a stop. This value has no effect when the bodies are at one of the two stops for this axis.

Parameters:
force - The amount of force to use

getConstantForceMix

public float getConstantForceMix()
Get the amount of the constant force mix parameter currently set for axis 1 positions between the two stops.

Returns:
The current constant force mix

setConstantForceMix2

public void setConstantForceMix2(float force)
Set the amount of constant force to mix into the system on axis 2 when the bodies are not at a stop. This value has no effect when the bodies are at one of the two stops for this axis.

Parameters:
force - The amount of force to use

getConstantForceMix2

public float getConstantForceMix2()
Get the amount of the constant force mix parameter currently set for axis 2 positions between the two stops.

Returns:
The current constant force mix

setSuspensionERP

public void setSuspensionERP(float erp)
Set the amount of suspension error reduction. This value should be between 0 and 1. 0 is no reduction at all, 1 is full correction in a single step. Suspension values only apply to axis 1.

Parameters:
erp - The amount of error reduction to use

getSuspensionERP

public float getSuspensionERP()
Get the amount of the suspension error reduction parameter currently set. This value will be between 0 and 1. 0 is no correction at all, 1 is full correction in a single step.Suspension values only apply to axis 1.

Returns:
A value between 0 and 1

setSuspensionCFM

public void setSuspensionCFM(float force)
Set the amount of suspension constant force to mix into the system when the bodies are travelling between the stops on axis 1. This value has no effect when the bodies are at stops. Suspension values only apply to axis 1.

Parameters:
force - The amount of force to use

getSuspensionCFM

public float getSuspensionCFM()
Get the amount of the suspension constant force mix parameter currently set. Suspension values only apply to axis 1.

Returns:
The current constant force mix at the stops

setMinAngleStop

public void setMinAngleStop(float angle)
                     throws IllegalArgumentException
Set the minimum angle that this joint is permitted to rotate to around axis 1. Angles are specified relative to the initial position that the joint was created in. The angle value is limited to the range +/- π. If the the provided angle is out of this range, an exception is thrown.

Note that if the maximum angle provided is less than the minimum angle at the point of evaluation, ODE ignores all limits.

A value of Float.NEGATIVE_INFINITY can be used to disable the minimum stop.

Parameters:
angle - The minimum stop angle in radians [-π,+π] or Float.NEGATIVE_INFINITY
Throws:
IllegalArgumentException - The provided angle is out of the valid range

getMinAngleStop

public float getMinAngleStop()
Fetch the currently set maximum angle stop for axis 1from this joint.

Returns:
A angle in radians in the range [-π,+π] or Float.NEGATIVE_INFINITY

setMaxAngleStop

public void setMaxAngleStop(float angle)
                     throws IllegalArgumentException
Set the maximum angle that this joint is permitted to rotate to around axis 1. Angles are specified relative to the initial position that the joint was created in. The angle value is limited to the range +/- π. If the the provided angle is out of this range, an exception is thrown.

Note that if the maximum angle provided is less than the minimum angle at the point of evaluation, ODE ignores all limits.

A value of Float.POSITIVE_INFINITY can be used to disable the maximum stop.

Parameters:
angle - The maximum stop angle in radians [-π,+π] or Float.POSITIVE_INFINITY
Throws:
IllegalArgumentException - The provided angle is out of the valid range

getMaxAngleStop

public float getMaxAngleStop()
Fetch the currently set maximum angle stop for axis 1 from this joint.

Returns:
A angle in radians in the range [-π,+π] or Float.POSITIVE_INFINITY

setStopBounce

public void setStopBounce(float bounce)
                   throws IllegalArgumentException
Set the bounciness of the stops for axis 1. This is a value in the range [0,1] defining how hitting the stop will effect the return travel of the two bodies. A value of 0 means there is no bounce and the bodies will not bounce back. A value of 1 means the full contact velocity at the stop will be reflected back in the opposite direction.

Parameters:
bounce - The bounciness factor in the range [0,1]
Throws:
IllegalArgumentException - The bounce factor is out of range

getStopBounce

public float getStopBounce()
Fetch the current bounce factor for the stop on axis 1.

Returns:
The bounce factor as a value in the range [0,1]

setStopERP

public void setStopERP(float erp)
Set the amount of stop bounce error reduction. This value should be between 0 and 1. 0 is no reduction at all, 1 is full correction in a single step.

Parameters:
erp - The amount of error reduction to use

getStopERP

public float getStopERP()
Get the amount of the stop error reduction parameter currently set. This value will be between 0 and 1. 0 is no bounce at all, 1 is full bounce.

Returns:
A value between 0 and 1

setStopCFM

public void setStopCFM(float force)
Set the amount of stop constant force to mix into the system when the bodies reach a stop. This value has no effect when the bodies are not at the stops. Together with the ERP value, this can be used to get spongy or soft stops. Note that this is inteded for unpowered joints, it does not work as expected on powered joints.

Parameters:
force - The amount of force to use

getStopCFM

public float getStopCFM()
Get the amount of the stop constant force mix parameter currently set.

Returns:
The current constant force mix at the stops

setParam

public void setParam(int parameter,
                     float value)
Set a generic, unchecked, parameter directly for this joint. The parameter types that are permissable for the joint are defined by the individual joint classes and the definitions can be found in OdeConstants.

Overrides:
setParam in class Joint
Parameters:
parameter - A parameter constant from OdeConstants
value - The new value to associate with the parameter

getParam

public float getParam(int parameter)
Get an unchecked parameter value directly from this joint. The parameter types that are permissable for the joint are defined by the individual joint classes and the definitions can be found in OdeConstants.

Overrides:
getParam in class Joint
Parameters:
parameter - A constant describing the parameter to fetch
Returns:
The value of that parameter