Class NarrowPhase

Namespace

Jitter2.Collision

Assembly

Jitter2.dll

Provides collision detection algorithms for convex shapes defined by support functions.

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

Implements GJK (Gilbert-Johnson-Keerthi) for distance queries, MPR (Minkowski Portal Refinement) for fast overlap detection, and EPA (Expanding Polytope Algorithm) for penetration depth.

All methods are thread-safe when used with thread-local solver state.

Methods

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

Determines whether two convex shapes overlap, providing detailed information for both overlapping and separated cases. Internally, the method employs the Expanding Polytope Algorithm (EPA) to gather collision information.

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 normalized collision normal pointing from pointB to pointA. This normal remains defined even if pointA and pointB coincide. It denotes the direction in which the shapes should be moved by the minimum distance (defined by the penetration depth) to either separate them in the overlapping case or bring them into contact in the separated case.

penetration float

The penetration depth.

Returns

bool

Returns true if the algorithm completes successfully, false otherwise. In case of algorithm convergence failure, collision information reverts to the type's default values.

Type Parameters

Ta

Tb

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

Determines whether two convex shapes overlap, providing detailed information for both overlapping and separated cases. It assumes that support shape A is at position zero and not rotated. Internally, the method employs the Expanding Polytope Algorithm (EPA) to gather collision information.

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 normalized collision normal pointing from pointB to pointA. This normal remains defined even if pointA and pointB coincide. It denotes the direction in which the shapes should be moved by the minimum distance (defined by the penetration depth) to either separate them in the overlapping case or bring them into contact in the separated case.

penetration float

The penetration depth.

Returns

bool

Returns true if the algorithm completes successfully, false otherwise. In case of algorithm convergence failure, collision information reverts to the type's default values.

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)

Provides the distance and closest points for non-overlapping shapes.

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)

Provides the distance and closest points for non-overlapping shapes. It assumes that support shape A is located at position zero and not rotated.

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 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

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

Detects whether two convex shapes overlap and provides detailed collision information for overlapping shapes. Internally, this method utilizes the Minkowski Portal Refinement (MPR) to obtain the collision information. Although MPR is not exact, it delivers a strict upper bound for the penetration depth. If the upper bound exceeds a predefined threshold, the results are further refined using the Expanding Polytope Algorithm (EPA).

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

The normalized collision normal pointing from pointB to pointA. This normal remains defined even if pointA and pointB coincide, representing the direction in which the shapes must be separated by the minimal distance (determined by the penetration depth) to avoid overlap.

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)

Detects whether two convex shapes overlap and provides detailed collision information for overlapping shapes. It assumes that support shape A is at position zero and not rotated. Internally, this method utilizes the Minkowski Portal Refinement (MPR) to obtain the collision information. Although MPR is not exact, it delivers a strict upper bound for the penetration depth. If the upper bound exceeds a predefined threshold, the results are further refined using the Expanding Polytope Algorithm (EPA).

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

The normalized collision normal pointing from pointB to pointA. This normal remains defined even if pointA and pointB coincide, representing the direction in which the shapes must be separated by the minimal distance (determined by the penetration depth) to avoid overlap.

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

Returns true of the shapes overlap, and false otherwise.

Type Parameters

Ta

Tb

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

Performs an overlap test. It assumes that support shape A is located at position zero and not rotated.

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 world space.

positionB JVector

The position of shape B in world space.

Returns

bool

Returns true of the shapes overlap, and false otherwise.

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 overlaps with 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 origin overlaps with 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 (TOI) and the collision points in world space for two shapes with linear velocities sweepA and sweepB and angular velocities sweepAngularA and sweepAngularB.

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

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.

sweepAngularA JVector

Angular velocity of shape A.

sweepAngularB JVector

Angular velocity of shape B.

extentA float

Bounding sphere radius of shape A. Used to bound the angular displacement contribution.

extentB float

Bounding sphere radius of shape B. Used to bound the angular displacement contribution.

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 at time of impact (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

Remarks

Uses conservative advancement for continuous collision detection. May fail to converge to the correct TOI and collision points in certain edge cases due to limitations in linear motion approximation and distance gradient estimation.

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