Module com.github.stephengold.joltjni

Package com.github.stephengold.joltjni

Class MotionProperties

java.lang.Object

com.github.stephengold.joltjni.JoltPhysicsObject

com.github.stephengold.joltjni.MotionProperties

All Implemented Interfaces:

ConstJoltPhysicsObject, ConstMotionProperties, AutoCloseable, Comparable<JoltPhysicsObject>

Direct Known Subclasses:

SoftBodyMotionProperties

public class MotionProperties
extends JoltPhysicsObject
implements ConstMotionProperties

Additional state for a Body that moves.

Constructor Summary

Constructors

Constructor	Description
MotionProperties()	Instantiate default properties.
MotionProperties(ConstMotionProperties original)	Instantiate a copy of the specified properties.

Method Summary

Modifier and Type	Method	Description
Vec3	getAccumulatedForce()	Copy the net force acting on the body.
void	getAccumulatedForce(Vec3 storeResult)	Copy the net force acting on the body.
Vec3	getAccumulatedTorque()	Copy the net torque acting on the body.
void	getAccumulatedTorque(Vec3 storeResult)	Copy the net torque acting on the body.
int	getAllowedDofs()	Return the allowed degrees of freedom.
boolean	getAllowSleeping()	Test whether the body is allowed to fall asleep.
float	getAngularDamping()	Return the angular damping coefficient.
UVec4	getAngularDofsMask()	Generate a vector in which the disabled angular components are set to zero and enabled ones are set to -1.
Vec3	getAngularVelocity()	Copy the angular velocity.
void	getAngularVelocity(Vec3 storeResult)	Copy the angular velocity.
float	getGravityFactor()	Return the gravity factor.
Quat	getInertiaRotation()	Copy the rotation that takes the inverse-inertia diagonal to local coordinates.
void	getInertiaRotation(Quat storeResult)	Copy the rotation that takes the inverse-inertia diagonal to local coordinates.
Vec3	getInverseInertiaDiagonal()	Copy the diagonal components of the inverse inertia matrix, assuming a dynamic body.
void	getInverseInertiaDiagonal(Vec3 storeResult)	Copy the diagonal components of the inverse inertia matrix, assuming a dynamic body.
float	getInverseMass()	Return the body's inverse mass.
float	getInverseMassUnchecked()	Return the body's inverse mass.
float	getLinearDamping()	Return the linear damping coefficient.
Vec3	getLinearVelocity()	Copy the linear velocity.
void	getLinearVelocity(Vec3 storeResult)	Copy the linear velocity.
Mat44	getLocalSpaceInverseInertia()	Copy the inverse-inertia matrix.
float	getMaxAngularVelocity()	Return the maximum angular speed that the body can achieve.
float	getMaxLinearVelocity()	Return the maximum linear speed that the body can achieve.
EMotionQuality	getMotionQuality()	Return the motion quality.
int	getNumPositionStepsOverride()	Return the number of position iterations used in the solver.
int	getNumVelocityStepsOverride()	Return the number of velocity iterations used in the solver.
void	moveKinematic(Vec3Arg offset, QuatArg rotation, float deltaTime)	Reposition the body, assuming it's kinematic.
void	resetForce()	Zero out the accumulated force.
void	resetTorque()	Zero out the accumulated torque.
void	set(ConstMotionProperties source)	Copy the argument to the current properties.
void	setAngularDamping(float damping)	Alter the angular damping.
void	setAngularVelocity(float wx, float wy, float wz)	Directly alter the angular velocity.
void	setAngularVelocity(Vec3Arg omega)	Directly alter the angular velocity.
void	setGravityFactor(float factor)	Alter the gravity factor.
void	setInverseInertia(float dx, float dy, float dz, float rx, float ry, float rz, float rw)	Alter the diagonal components of the inverse inertia matrix of the body.
void	setInverseInertia(Vec3Arg diagonal, QuatArg rotation)	Alter the diagonal components of the inverse inertia matrix of the body.
void	setInverseMass(float inverseMass)	Alter the inverse mass.
void	setLinearDamping(float damping)	Alter the linear damping.
void	setLinearVelocity(float vx, float vy, float vz)	Directly alter the linear velocity.
void	setLinearVelocity(Vec3Arg velocity)	Directly alter the linear velocity.
void	setMassProperties(int allowedDofs, ConstMassProperties massProperties)	Alter the mass properties.
void	setMaxAngularVelocity(float maxSpeed)	Return the maximum angular speed that the body can achieve.
void	setMaxLinearVelocity(float maxSpeed)	Return the maximum linear speed that the body can achieve.
void	setNumPositionStepsOverride(int numIterations)	Alter the number of position iterations to use in the solver
void	setNumVelocityStepsOverride(int numIterations)	Alter the number of velocity iterations to use in the solver

Methods inherited from class com.github.stephengold.joltjni.JoltPhysicsObject

close, compareTo, equals, getContainingObject, hasAssignedNativeObject, hashCode, isCleanerStarted, ownsNativeObject, setVirtualAddress, setVirtualAddress, startCleaner, targetVa, targetVaOrZero, toString, va

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface java.lang.Comparable

compareTo

Methods inherited from interface com.github.stephengold.joltjni.readonly.ConstJoltPhysicsObject

close, hasAssignedNativeObject, ownsNativeObject, targetVa, targetVaOrZero

Constructor Details

MotionProperties

public MotionProperties()

Instantiate default properties.

MotionProperties

public MotionProperties(ConstMotionProperties original)

Instantiate a copy of the specified properties.

Parameters:

original - the settings to copy (not null, unaffected)

Method Details

moveKinematic

public void moveKinematic(Vec3Arg offset,
 QuatArg rotation,
 float deltaTime)

Reposition the body, assuming it's kinematic. It is illegal to reposition a sleeping body without activating it.

Parameters:

offset - the desired offset (from the current location, not null, unaffected)

rotation - the desired rotation (relative to the current orientation, not null, unaffected)

deltaTime - time until the desired position is reached (in seconds, >0)

resetForce

public void resetForce()

Zero out the accumulated force.

resetTorque

public void resetTorque()

Zero out the accumulated torque.

set

public void set(ConstMotionProperties source)

Copy the argument to the current properties.

Parameters:

source - the properties to copy (not null, unaffected)

setAngularDamping

public void setAngularDamping(float damping)

Alter the angular damping.

Parameters:

damping - the desired coefficient value (in units of per second, ≥0, ≤1, default=0)

setAngularVelocity

public void setAngularVelocity(float wx,
 float wy,
 float wz)

Directly alter the angular velocity. It is illegal to set a non-zero velocity on a sleeping body without activating it.

Parameters:

wx - the X component of the desired angular velocity (radians per second in system coordinates, default=0)

wy - the Y component of the desired angular velocity (radians per second in system coordinates, default=0)

wz - the Z component of the desired angular velocity (radians per second in system coordinates, default=0)

setAngularVelocity

public void setAngularVelocity(Vec3Arg omega)

Directly alter the angular velocity. It is illegal to set a non-zero velocity on a sleeping body without activating it.

Parameters:

omega - the desired velocity (meters per second in system coordinates, not null, unaffected, default=(0,0,0))

setGravityFactor

public void setGravityFactor(float factor)

Alter the gravity factor.

Parameters:

factor - the desired factor (default=0)

setInverseInertia

public void setInverseInertia(float dx,
 float dy,
 float dz,
 float rx,
 float ry,
 float rz,
 float rw)

Alter the diagonal components of the inverse inertia matrix of the body. If inertia changes, mass should probably change as well.

Parameters:

dx - the desired X element of the diagonal

dy - the desired Y element of the diagonal

dz - the desired Z element of the diagonal

rx - the X component of the orientation of the principal axes

ry - the Y component of the orientation of the principal axes

rz - the Z component of the orientation of the principal axes

rw - the W component of the orientation of the principal axes

setInverseInertia

public void setInverseInertia(Vec3Arg diagonal,
 QuatArg rotation)

Alter the diagonal components of the inverse inertia matrix of the body. If inertia changes, mass should probably change as well.

Parameters:

diagonal - the desired diagonal elements (not null, unaffected)

rotation - the desired orientation of the principal axes (not null, unaffected)

setInverseMass

public void setInverseMass(float inverseMass)

Alter the inverse mass. If mass changes, inertia should probably change as well.

Parameters:

inverseMass - the desired value (in units of 1/mass)

setLinearDamping

public void setLinearDamping(float damping)

Alter the linear damping.

Parameters:

damping - the desired value (in units of per second, ≥0, ≤1, default=0)

setLinearVelocity

public void setLinearVelocity(float vx,
 float vy,
 float vz)

Directly alter the linear velocity. It is illegal to set a non-zero velocity on a sleeping body without activating it.

Parameters:

vx - the X component of the desired velocity (meters per second in system coordinates, default=0)

vy - the Y component of the desired velocity (meters per second in system coordinates, default=0)

vz - the Z component of the desired velocity (meters per second in system coordinates, default=0)

setLinearVelocity

public void setLinearVelocity(Vec3Arg velocity)

Directly alter the linear velocity. It is illegal to set a non-zero velocity on a sleeping body without activating it.

Parameters:

velocity - the desired velocity (meters per second in system coordinates, not null, unaffected, default=(0,0,0))

setMassProperties

public void setMassProperties(int allowedDofs,
 ConstMassProperties massProperties)

Alter the mass properties.

Parameters:

allowedDofs - logical OR of values defined in EAllowedDofs (default=All)

massProperties - the desired mass properties (not null, unaffected)

setMaxAngularVelocity

public void setMaxAngularVelocity(float maxSpeed)

Return the maximum angular speed that the body can achieve.

Parameters:

maxSpeed - the speed limit (in radians per second, default=0)

setMaxLinearVelocity

public void setMaxLinearVelocity(float maxSpeed)

Return the maximum linear speed that the body can achieve.

Parameters:

maxSpeed - the speed limit (in meters per second, default=0)

setNumPositionStepsOverride

public void setNumPositionStepsOverride(int numIterations)

Alter the number of position iterations to use in the solver

Parameters:

numIterations - the desired count (>0) or 0 to use the number specified in the PhysicsSettings

setNumVelocityStepsOverride

public void setNumVelocityStepsOverride(int numIterations)

Alter the number of velocity iterations to use in the solver

Parameters:

numIterations - the desired count (>0) or 0 to use the number specified in the PhysicsSettings

getAccumulatedForce

public Vec3 getAccumulatedForce()

Copy the net force acting on the body. The properties are unaffected.

Specified by:

getAccumulatedForce in interface ConstMotionProperties

Returns:

a new force vector (Newtons in system coordinates)

getAccumulatedForce

public void getAccumulatedForce(Vec3 storeResult)

Copy the net force acting on the body. The properties are unaffected.

Specified by:

getAccumulatedForce in interface ConstMotionProperties

Parameters:

storeResult - storage for the force (Newtons in system coordinates, not null, modified)

getAccumulatedTorque

public Vec3 getAccumulatedTorque()

Copy the net torque acting on the body. The properties are unaffected.

Specified by:

getAccumulatedTorque in interface ConstMotionProperties

Returns:

a new torque vector (Newton meters in system coordinates)

getAccumulatedTorque

public void getAccumulatedTorque(Vec3 storeResult)

Copy the net torque acting on the body. The properties are unaffected.

Specified by:

getAccumulatedTorque in interface ConstMotionProperties

Parameters:

storeResult - storage for the torque (Newton meters in system coordinates, not null, modified)

getAllowedDofs

public int getAllowedDofs()

Return the allowed degrees of freedom. The properties are unaffected.

Specified by:

getAllowedDofs in interface ConstMotionProperties

Returns:

logical OR of values defined in EAllowedDofs

getAllowSleeping

public boolean getAllowSleeping()

Test whether the body is allowed to fall asleep. The properties are unaffected.

Specified by:

getAllowSleeping in interface ConstMotionProperties

Returns:

true if allowed, otherwise false

getAngularDamping

public float getAngularDamping()

Return the angular damping coefficient. The properties are unaffected.

Specified by:

getAngularDamping in interface ConstMotionProperties

Returns:

the coefficient value (in units of per second, ≥0)

getAngularDofsMask

public UVec4 getAngularDofsMask()

Generate a vector in which the disabled angular components are set to zero and enabled ones are set to -1. The properties are unaffected.

Specified by:

getAngularDofsMask in interface ConstMotionProperties

Returns:

a new vector

getAngularVelocity

public Vec3 getAngularVelocity()

Copy the angular velocity. The properties are unaffected.

Specified by:

getAngularVelocity in interface ConstMotionProperties

Returns:

a new velocity vector (radians per second in system coordinates)

getAngularVelocity

public void getAngularVelocity(Vec3 storeResult)

Copy the angular velocity. The properties are unaffected.

Specified by:

getAngularVelocity in interface ConstMotionProperties

Parameters:

storeResult - storage for the velocity (radians per second in system coordinates, not null, modified)

getGravityFactor

public float getGravityFactor()

Return the gravity factor. The properties are unaffected.

Specified by:

getGravityFactor in interface ConstMotionProperties

Returns:

the factor

getInertiaRotation

public Quat getInertiaRotation()

Copy the rotation that takes the inverse-inertia diagonal to local coordinates. The properties are unaffected.

Specified by:

getInertiaRotation in interface ConstMotionProperties

Returns:

a new object

getInertiaRotation

public void getInertiaRotation(Quat storeResult)

Copy the rotation that takes the inverse-inertia diagonal to local coordinates. The properties are unaffected.

Specified by:

getInertiaRotation in interface ConstMotionProperties

Parameters:

storeResult - storage for the rotation (not null, modified)

getInverseInertiaDiagonal

public Vec3 getInverseInertiaDiagonal()

Copy the diagonal components of the inverse inertia matrix, assuming a dynamic body. The properties are unaffected.

Specified by:

getInverseInertiaDiagonal in interface ConstMotionProperties

Returns:

a new vector (all components ≥0)

getInverseInertiaDiagonal

public void getInverseInertiaDiagonal(Vec3 storeResult)

Copy the diagonal components of the inverse inertia matrix, assuming a dynamic body. The properties are unaffected.

Specified by:

getInverseInertiaDiagonal in interface ConstMotionProperties

Parameters:

storeResult - storage for the diagonal (all components ≥0, not null, modified)

getInverseMass

public float getInverseMass()

Return the body's inverse mass. The properties are unaffected.

Specified by:

getInverseMass in interface ConstMotionProperties

Returns:

the value (≥0)

getInverseMassUnchecked

public float getInverseMassUnchecked()

Return the body's inverse mass. The properties are unaffected.

Specified by:

getInverseMassUnchecked in interface ConstMotionProperties

Returns:

the value (≥0)

getLinearDamping

public float getLinearDamping()

Return the linear damping coefficient. The properties are unaffected.

Specified by:

getLinearDamping in interface ConstMotionProperties

Returns:

the coefficient value (in units of per second, ≥0)

getLinearVelocity

public Vec3 getLinearVelocity()

Copy the linear velocity. The properties are unaffected.

Specified by:

getLinearVelocity in interface ConstMotionProperties

Returns:

a new velocity vector (meters per second in system coordinates)

getLinearVelocity

public void getLinearVelocity(Vec3 storeResult)

Copy the linear velocity. The properties are unaffected.

Specified by:

getLinearVelocity in interface ConstMotionProperties

Parameters:

storeResult - storage for the velocity (meters per second in system coordinates, not null, modified)

getLocalSpaceInverseInertia

public Mat44 getLocalSpaceInverseInertia()

Copy the inverse-inertia matrix. The properties are unaffected.

Specified by:

getLocalSpaceInverseInertia in interface ConstMotionProperties

Returns:

a new object

getMaxAngularVelocity

public float getMaxAngularVelocity()

Return the maximum angular speed that the body can achieve. The properties are unaffected.

Specified by:

getMaxAngularVelocity in interface ConstMotionProperties

Returns:

the speed limit (in radians per second)

getMaxLinearVelocity

public float getMaxLinearVelocity()

Return the maximum linear speed that the body can achieve. The properties are unaffected.

Specified by:

getMaxLinearVelocity in interface ConstMotionProperties

Returns:

the speed limit (in meters per second)

getMotionQuality

public EMotionQuality getMotionQuality()

Return the motion quality. The properties are unaffected.

Specified by:

getMotionQuality in interface ConstMotionProperties

Returns:

an enum value (not null)

getNumPositionStepsOverride

public int getNumPositionStepsOverride()

Return the number of position iterations used in the solver. The properties are unaffected.

Specified by:

getNumPositionStepsOverride in interface ConstMotionProperties

Returns:

the count (>0) or 0 to use number specified in the PhysicsSettings

getNumVelocityStepsOverride

public int getNumVelocityStepsOverride()

Return the number of velocity iterations used in the solver. The properties are unaffected.

Specified by:

getNumVelocityStepsOverride in interface ConstMotionProperties

Returns:

the count (>0) or 0 to use number specified in the PhysicsSettings