Class NarrowPhase

Namespace

Jitter2.Collision

Assembly

Jitter2.dll

Tests convex shapes for overlap, distance, ray hits, and swept collisions.

public static class NarrowPhase

Inheritance

object

NarrowPhase

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Remarks

Shapes are supplied through ISupportMappable. Queries may run on separate threads if the supplied shapes can be read concurrently and are not modified during the queries.

Methods

Collision<Ta, Tb>(in Ta, in Tb, in JQuaternion, in JQuaternion, in JVector, in JVector, out JVector, out JVector, out JVector, out float)

Calculates contact points and signed penetration for two convex shapes, including separated shapes. All output coordinates are in world space.

public static bool Collision<Ta, Tb>(in Ta supportA, in Tb supportB, in JQuaternion orientationA, in JQuaternion orientationB, in JVector positionA, in JVector positionB, out JVector pointA, out JVector pointB, out JVector normal, out float penetration) where Ta : ISupportMappable where Tb : ISupportMappable

Parameters

supportA Ta

The support function of shape A.

supportB Tb

The support function of shape B.

orientationA JQuaternion

The orientation of shape A in world space.

orientationB JQuaternion

The orientation of shape B in world space.

positionA JVector

The position of shape A in world space.

positionB JVector

The position of shape B in world space.

pointA JVector

For the overlapping case: the deepest point on shape A inside shape B; for the separated case: the closest point on shape A to shape B.

pointB JVector

For the overlapping case: the deepest point on shape B inside shape A; for the separated case: the closest point on shape B to shape A.

normal JVector

The unit collision normal, pointing from shape A toward shape B. The signed penetration is its dot product with pointA - pointB. Moving shape B by penetration times the normal makes the shapes touch, both when they overlap and when they are separated. It remains defined when the points coincide.

penetration float

Signed penetration depth: positive for overlap, negative for separation.

Returns

bool

true if collision information was calculated, including for separated shapes; false if the search failed. Only use the outputs when the result is true.

Type Parameters

Ta

Tb

Collision<Ta, Tb>(in Ta, in Tb, in JQuaternion, in JVector, out JVector, out JVector, out JVector, out float)

Calculates contact points and signed penetration for two convex shapes, including separated shapes. Shape A is at the origin with identity orientation; all coordinates use its local frame.

public static bool Collision<Ta, Tb>(in Ta supportA, in Tb supportB, in JQuaternion orientationB, in JVector positionB, out JVector pointA, out JVector pointB, out JVector normal, out float penetration) where Ta : ISupportMappable where Tb : ISupportMappable

Parameters

supportA Ta

The support function of shape A.

supportB Tb

The support function of shape B.

orientationB JQuaternion

The orientation of shape B.

positionB JVector

The position of shape B.

pointA JVector

For the overlapping case: the deepest point on shape A inside shape B; for the separated case: the closest point on shape A to shape B.

pointB JVector

For the overlapping case: the deepest point on shape B inside shape A; for the separated case: the closest point on shape B to shape A.

normal JVector

The unit collision normal, pointing from shape A toward shape B. The signed penetration is its dot product with pointA - pointB. Moving shape B by penetration times the normal makes the shapes touch, both when they overlap and when they are separated. It remains defined when the points coincide.

penetration float

Signed penetration depth: positive for overlap, negative for separation.

Returns

bool

true if collision information was calculated, including for separated shapes; false if the search failed. Only use the outputs when the result is true.

Type Parameters

Ta

Tb

Distance<Ta, Tb>(in Ta, in Tb, in JQuaternion, in JQuaternion, in JVector, in JVector, out JVector, out JVector, out JVector, out float)

Calculates the distance and closest points between separated shapes in world space.

public static bool Distance<Ta, Tb>(in Ta supportA, in Tb supportB, in JQuaternion orientationA, in JQuaternion orientationB, in JVector positionA, in JVector positionB, out JVector pointA, out JVector pointB, out JVector normal, out float distance) where Ta : ISupportMappable where Tb : ISupportMappable

Parameters

supportA Ta

The support function of shape A.

supportB Tb

The support function of shape B.

orientationA JQuaternion

The orientation of shape A in world space.

orientationB JQuaternion

The orientation of shape B in world space.

positionA JVector

The position of shape A in world space.

positionB JVector

The position of shape B in world space.

pointA JVector

Closest point on shape A. Undefined for the overlapping case.

pointB JVector

Closest point on shape B. Undefined for the overlapping case.

normal JVector

Unit direction from shape A toward shape B. Undefined for the overlapping case.

distance float

The distance between the separating shapes. Zero if shapes overlap.

Returns

bool

Returns true if the shapes do not overlap and distance information can be provided.

Type Parameters

Ta

Tb

Distance<Ta, Tb>(in Ta, in Tb, in JQuaternion, in JVector, out JVector, out JVector, out JVector, out float)

Calculates the distance and closest points between separated shapes. Shape A is at the origin with identity orientation; all coordinates use its local frame.

public static bool Distance<Ta, Tb>(in Ta supportA, in Tb supportB, in JQuaternion orientationB, in JVector positionB, out JVector pointA, out JVector pointB, out JVector normal, out float distance) where Ta : ISupportMappable where Tb : ISupportMappable

Parameters

supportA Ta

The support function of shape A.

supportB Tb

The support function of shape B.

orientationB JQuaternion

The orientation of shape B in shape A's local frame.

positionB JVector

The position of shape B in shape A's local frame.

pointA JVector

Closest point on shape A. Undefined for the overlapping case.

pointB JVector

Closest point on shape B. Undefined for the overlapping case.

normal JVector

Unit direction from shape A toward shape B. Undefined for the overlapping case.

distance float

The distance between the separating shapes. Zero if shapes overlap.

Returns

bool

Returns true if the shapes do not overlap and distance information can be provided.

Type Parameters

Ta

Tb

MprEpa<Ta, Tb>(in Ta, in Tb, in JQuaternion, in JQuaternion, in JVector, in JVector, out JVector, out JVector, out JVector, out float, float)

Tests overlap and returns contact points, a normal, and estimated penetration in world space. Uses MPR, with EPA refinement for penetrations exceeding epaThreshold.

public static bool MprEpa<Ta, Tb>(in Ta supportA, in Tb supportB, in JQuaternion orientationA, in JQuaternion orientationB, in JVector positionA, in JVector positionB, out JVector pointA, out JVector pointB, out JVector normal, out float penetration, float epaThreshold = 0.02) where Ta : ISupportMappable where Tb : ISupportMappable

Parameters

supportA Ta

The support function of shape A.

supportB Tb

The support function of shape B.

orientationA JQuaternion

The orientation of shape A in world space.

orientationB JQuaternion

The orientation of shape B in world space.

positionA JVector

The position of shape A in world space.

positionB JVector

The position of shape B in world space.

pointA JVector

The deepest point on shape A that is inside shape B.

pointB JVector

The deepest point on shape B that is inside shape A.

normal JVector

Unit normal pointing from shape A toward shape B. Moving shape B along it separates the shapes. Remains defined when the points coincide.

penetration float

The penetration depth.

epaThreshold float

Penetration depth threshold above which MPR results are refined with EPA.

Returns

bool

Returns true if the shapes overlap (collide), and false otherwise.

Type Parameters

Ta

Tb

MprEpa<Ta, Tb>(in Ta, in Tb, in JQuaternion, in JVector, out JVector, out JVector, out JVector, out float, float)

Tests overlap and returns contact points, a normal, and estimated penetration. Shape A is at the origin with identity orientation; all coordinates use its local frame. Uses MPR, with EPA refinement for penetrations exceeding epaThreshold.

public static bool MprEpa<Ta, Tb>(in Ta supportA, in Tb supportB, in JQuaternion orientationB, in JVector positionB, out JVector pointA, out JVector pointB, out JVector normal, out float penetration, float epaThreshold = 0.02) where Ta : ISupportMappable where Tb : ISupportMappable

Parameters

supportA Ta

The support function of shape A.

supportB Tb

The support function of shape B.

orientationB JQuaternion

The orientation of shape B.

positionB JVector

The position of shape B.

pointA JVector

The deepest point on shape A that is inside shape B.

pointB JVector

The deepest point on shape B that is inside shape A.

normal JVector

Unit normal pointing from shape A toward shape B. Moving shape B along it separates the shapes. Remains defined when the points coincide.

penetration float

The penetration depth.

epaThreshold float

Penetration depth threshold above which MPR results are refined with EPA.

Returns

bool

Returns true if the shapes overlap (collide), and false otherwise.

Type Parameters

Ta

Tb

Overlap<Ta, Tb>(in Ta, in Tb, in JQuaternion, in JQuaternion, in JVector, in JVector)

Performs an overlap test.

public static bool Overlap<Ta, Tb>(in Ta supportA, in Tb supportB, in JQuaternion orientationA, in JQuaternion orientationB, in JVector positionA, in JVector positionB) where Ta : ISupportMappable where Tb : ISupportMappable

Parameters

supportA Ta

The support function of shape A.

supportB Tb

The support function of shape B.

orientationA JQuaternion

The orientation of shape A in world space.

orientationB JQuaternion

The orientation of shape B in world space.

positionA JVector

The position of shape A in world space.

positionB JVector

The position of shape B in world space.

Returns

bool

true if the shapes overlap; otherwise, false.

Type Parameters

Ta

Tb

Overlap<Ta, Tb>(in Ta, in Tb, in JQuaternion, in JVector)

Tests whether two convex shapes overlap. Shape A is at the origin with identity orientation.

public static bool Overlap<Ta, Tb>(in Ta supportA, in Tb supportB, in JQuaternion orientationB, in JVector positionB) where Ta : ISupportMappable where Tb : ISupportMappable

Parameters

supportA Ta

The support function of shape A.

supportB Tb

The support function of shape B.

orientationB JQuaternion

The orientation of shape B in shape A's local frame.

positionB JVector

The position of shape B in shape A's local frame.

Returns

bool

true if the shapes overlap; otherwise, false.

Type Parameters

Ta

Tb

PointTest<Ta>(in Ta, in JMatrix, in JVector, in JVector)

Check if a point is inside a shape.

public static bool PointTest<Ta>(in Ta support, in JMatrix orientation, in JVector position, in JVector point) where Ta : ISupportMappable

Parameters

support Ta

Support map representing the shape.

orientation JMatrix

Orientation of the shape.

position JVector

Position of the shape.

point JVector

Point to check.

Returns

bool

Returns true if the point is contained within the shape, false otherwise.

Type Parameters

Ta

PointTest<Ta>(in Ta, in JVector)

Check if a point is inside a shape.

public static bool PointTest<Ta>(in Ta support, in JVector point) where Ta : ISupportMappable

Parameters

support Ta

Support map representing the shape.

point JVector

Point to check.

Returns

bool

Returns true if the point is contained within the shape, false otherwise.

Type Parameters

Ta

RayCast<Ta>(in Ta, in JQuaternion, in JVector, in JVector, in JVector, out float, out JVector)

Performs a ray cast against a shape.

public static bool RayCast<Ta>(in Ta support, in JQuaternion orientation, in JVector position, in JVector origin, in JVector direction, out float lambda, out JVector normal) where Ta : ISupportMappable

Parameters

support Ta

The support function of the shape.

orientation JQuaternion

The orientation of the shape in world space.

position JVector

The position of the shape in world space.

origin JVector

The origin of the ray.

direction JVector

The direction of the ray; normalization is not necessary.

lambda float

Specifies the hit point of the ray, calculated as 'origin + lambda * direction'. Zero if the origin is inside the shape, PositiveInfinity if the ray does not hit.

normal JVector

The normalized normal vector perpendicular to the surface, pointing outwards. Zero if the ray does not hit or the ray origin is inside the shape.

Returns

bool

Returns true if the ray intersects with the shape; otherwise, false.

Type Parameters

Ta

RayCast<Ta>(in Ta, in JVector, in JVector, out float, out JVector)

Performs a ray cast against a shape.

public static bool RayCast<Ta>(in Ta support, in JVector origin, in JVector direction, out float lambda, out JVector normal) where Ta : ISupportMappable

Parameters

support Ta

The support function of the shape.

origin JVector

The origin of the ray.

direction JVector

The direction of the ray; normalization is not necessary.

lambda float

Specifies the hit point of the ray, calculated as 'origin + lambda * direction'. Zero if the origin is inside the shape, PositiveInfinity if the ray does not hit.

normal JVector

The normalized normal vector perpendicular to the surface, pointing outwards. Zero if the ray does not hit or the ray origin is inside the shape.

Returns

bool

Returns true if the ray intersects with the shape; otherwise, false.

Type Parameters

Ta

Sweep<Ta, Tb>(in Ta, in Tb, in JQuaternion, in JQuaternion, in JVector, in JVector, in JVector, in JVector, out JVector, out JVector, out JVector, out float)

Calculates the time of impact and the collision points in world space for two shapes with linear velocities sweepA and sweepB.

public static bool Sweep<Ta, Tb>(in Ta supportA, in Tb supportB, in JQuaternion orientationA, in JQuaternion orientationB, in JVector positionA, in JVector positionB, in JVector sweepA, in JVector sweepB, out JVector pointA, out JVector pointB, out JVector normal, out float lambda) where Ta : ISupportMappable where Tb : ISupportMappable

Parameters

supportA Ta

Shape A.

supportB Tb

Shape B.

orientationA JQuaternion

Orientation of shape A in world space.

orientationB JQuaternion

Orientation of shape B in world space.

positionA JVector

Position of shape A in world space.

positionB JVector

Position of shape B in world space.

sweepA JVector

Linear velocity of shape A.

sweepB JVector

Linear velocity of shape B.

pointA JVector

Collision point on shape A in world space at the sweep origin.

pointB JVector

Collision point on shape B in world space at the sweep origin.

normal JVector

Normalized collision normal in world space (points from A to B). Zero if the shapes already overlap or do not hit.

lambda float

Time of impact. PositiveInfinity if no hit is detected, zero if shapes overlap.

Returns

bool

True if the shapes will hit or already overlap, false otherwise.

Type Parameters

Ta

Tb

Sweep<Ta, Tb>(in Ta, in Tb, in JQuaternion, in JQuaternion, in JVector, in JVector, in JVector, in JVector, in JVector, in JVector, in float, in float, out JVector, out JVector, out JVector, out float)

Calculates the time of impact for two translating and rotating convex shapes.

public static bool Sweep<Ta, Tb>(in Ta supportA, in Tb supportB, in JQuaternion orientationA, in JQuaternion orientationB, in JVector positionA, in JVector positionB, in JVector sweepA, in JVector sweepB, in JVector sweepAngularA, in JVector sweepAngularB, in float extentA, in float extentB, out JVector pointA, out JVector pointB, out JVector normal, out float lambda) where Ta : ISupportMappable where Tb : ISupportMappable

Parameters

supportA Ta

Shape A.

supportB Tb

Shape B.

orientationA JQuaternion

Initial orientation of shape A in world space.

orientationB JQuaternion

Initial orientation of shape B in world space.

positionA JVector

Initial position of shape A in world space.

positionB JVector

Initial position of shape B in world space.

sweepA JVector

Linear velocity of shape A.

sweepB JVector

Linear velocity of shape B.

sweepAngularA JVector

World-space angular velocity of shape A.

sweepAngularB JVector

World-space angular velocity of shape B.

extentA float

Radius enclosing shape A about its rotation origin, including any local offset.

extentB float

Radius enclosing shape B about its rotation origin, including any local offset.

pointA JVector

Collision point on shape A in world space at the sweep origin.

pointB JVector

Collision point on shape B in world space at the sweep origin.

normal JVector

Unit normal from A to B at impact. Zero for initial overlap or an unsuccessful search.

lambda float

Time of impact in seconds; zero for initial overlap, infinity for an unsuccessful search.

Returns

bool

True if an impact is found. False if the shapes miss or the search fails.

Type Parameters

Ta

Tb

Remarks

Prefer the overload with a maximum time and a NarrowPhase.SweepStatus result when sweeping a simulation step. An unbounded search may fail to finish, especially when both shapes rotate without relative translation.

Sweep<Ta, Tb>(in Ta, in Tb, in JQuaternion, in JQuaternion, in JVector, in JVector, in JVector, in JVector, in JVector, in JVector, in float, in float, float, out JVector, out JVector, out JVector, out float)

Searches for the first impact of two translating and rotating convex shapes between zero and maximumTime seconds, including both endpoints.

public static NarrowPhase.SweepStatus Sweep<Ta, Tb>(in Ta supportA, in Tb supportB, in JQuaternion orientationA, in JQuaternion orientationB, in JVector positionA, in JVector positionB, in JVector sweepA, in JVector sweepB, in JVector sweepAngularA, in JVector sweepAngularB, in float extentA, in float extentB, float maximumTime, out JVector pointA, out JVector pointB, out JVector normal, out float lambda) where Ta : ISupportMappable where Tb : ISupportMappable

Parameters

supportA Ta

Shape A.

supportB Tb

Shape B.

orientationA JQuaternion

Initial orientation of shape A in world space.

orientationB JQuaternion

Initial orientation of shape B in world space.

positionA JVector

Initial position of shape A in world space.

positionB JVector

Initial position of shape B in world space.

sweepA JVector

Linear velocity of shape A.

sweepB JVector

Linear velocity of shape B.

sweepAngularA JVector

World-space angular velocity of shape A.

sweepAngularB JVector

World-space angular velocity of shape B.

extentA float

Radius enclosing shape A about its rotation origin, including any local offset.

extentB float

Radius enclosing shape B about its rotation origin, including any local offset.

maximumTime float

Nonnegative last time to search. Positive infinity requests an unbounded search.

pointA JVector

Collision point on shape A in world space at the sweep origin. Zero unless a hit is found.

pointB JVector

Collision point on shape B in world space at the sweep origin. Zero unless a hit is found.

normal JVector

Unit normal from A to B at impact. Zero for initial overlap or an unsuccessful search.

lambda float

Time of impact in seconds; zero for initial overlap, infinity unless a hit is found.

Returns

NarrowPhase.SweepStatus

Whether an impact was found, separation was proven, or the search could not finish.

Type Parameters

Ta

Tb

Remarks

Includes impacts occurring between separated endpoint poses. A hit is reported within a distance tolerance of 0.0001. Iteration exhaustion is reported as Failed rather than a collision or a proven miss.

Sweep<Ta, Tb>(in Ta, in Tb, in JQuaternion, in JVector, in JVector, out JVector, out JVector, out JVector, out float)

Performs a sweep test where shape A is fixed at the origin with identity orientation and zero velocity.

public static bool Sweep<Ta, Tb>(in Ta supportA, in Tb supportB, in JQuaternion orientationB, in JVector positionB, in JVector sweepB, out JVector pointA, out JVector pointB, out JVector normal, out float lambda) where Ta : ISupportMappable where Tb : ISupportMappable

Parameters

supportA Ta

Shape A (fixed at the origin, identity orientation).

supportB Tb

Shape B.

orientationB JQuaternion

Orientation of shape B in world space.

positionB JVector

Position of shape B in world space.

sweepB JVector

Linear velocity of shape B.

pointA JVector

Collision point on shape A in world space at the sweep origin.

pointB JVector

Collision point on shape B in world space at the sweep origin.

normal JVector

Normalized collision normal in world space (points from A to B). Zero if the shapes already overlap or do not hit.

lambda float

Time of impact. PositiveInfinity if no hit is detected, zero if shapes overlap.

Returns

bool

True if the shapes hit or already overlap, false otherwise.

Type Parameters

Ta

Tb