Module org.dyn4j

Package org.dyn4j.collision.broadphase

Class Sap<T extends CollisionBody<E>,E extends Fixture>

Object

AbstractBroadphaseDetector<T,E>

Sap<T,E>

Type Parameters:

T - the CollisionBody type

E - the Fixture type

All Implemented Interfaces:

BroadphaseDetector<T,E>, Shiftable

public final class Sap<T extends CollisionBody<E>,E extends Fixture>
extends AbstractBroadphaseDetector<T,E>
implements BroadphaseDetector<T,E>

Implementation of the Sweep and Prune broad-phase collision detection algorithm.

This implementation maintains a red-black tree of CollisionBody Fixtures where each update will reposition the respective CollisionBody Fixture in the tree.

Projects all CollisionBody Fixtures on both the x and y axes and performs overlap checks on all the projections to test for possible collisions (AABB tests).

This algorithm is O(n) for all AbstractBroadphaseDetector.detect(AABB) and AbstractBroadphaseDetector.raycast(Ray, double) methods.

Since:

1.0.0

Version:

4.0.0

Author:

William Bittle

Field Summary

Fields inherited from interface BroadphaseDetector

DEFAULT_AABB_EXPANSION, DEFAULT_INITIAL_CAPACITY

Constructor Summary

Constructors

Constructor	Description
Sap()	Default constructor.
Sap(int initialCapacity)	Full constructor.

Method Summary

Modifier and Type	Method	Description
void	add(T body, E fixture)	Adds a new Fixture for the given CollisionBody to the broad-phase.
void	clear()	Clears all the CollisionBody Fixtures from this broad-phase and any state held by this broadphase.
void	clearUpdates()	Clears any internal state that tracks what CollisionBody Fixtures have been updated.
boolean	contains(CollisionItem<T,E> item)	Returns true if the given Fixture on the given CollisionBody has been added to this broadphase.
boolean	contains(T body, E fixture)	Returns true if the given Fixture on the given CollisionBody has been added to this broadphase.
Iterator<CollisionPair<T,E>>	detectIterator(boolean forceFullDetection)	Performs collision detection on all CollisionBody Fixtures that have been added to this BroadphaseDetector and returns the list of potential pairs.
Iterator<CollisionItem<T,E>>	detectIterator(AABB aabb)	Performs a broad-phase collision test using the given AABB and returns the items that overlap.
AABB	getAABB(CollisionItem<T,E> item)	Returns the AABB for the given CollisionBody Fixture.
boolean	isUpdated(CollisionItem<T,E> item)	Returns true if the given Fixture is included in the updated list.
boolean	isUpdated(T body, E fixture)	Returns true if the given Fixture is included in the updated list.
void	optimize()	Attempts to optimize the broadphase based on the current state.
Iterator<CollisionItem<T,E>>	raycastIterator(Ray ray, double length)	Performs a raycast over all the bodies in the broad-phase and returns the items that intersect.
boolean	remove(CollisionItem<T,E> item)	Removes the given Fixture for the given CollisionBody from the broad-phase and returns true if it was found.
boolean	remove(T body, E fixture)	Removes the given Fixture for the given CollisionBody from the broad-phase and returns true if it was found.
void	setUpdated(T body, E fixture)	The BroadphaseDetector.update(CollisionBody, Fixture) method will only mark the Fixture as updated if the Fixture has moved enough to change the internally stored AABB.
void	setUpdateTrackingEnabled(boolean flag)	Sets the update tracking to the given flag.
void	shift(Vector2 shift)	Translates the object to match the given coordinate shift.
int	size()	Returns the number of CollisionBody Fixtures that are being managed in this broad-phase.
void	update(T body, E fixture)	Updates the given CollisionBody's Fixture.

Methods inherited from class AbstractBroadphaseDetector

add, contains, detect, detect, detect, detect, detect, detect, detect, getAABB, getAABB, getAABBExpansion, isAABBExpansionSupported, isUpdated, isUpdateTrackingEnabled, isUpdateTrackingSupported, raycast, raycast, remove, setAABBExpansion, setUpdated, supportsAABBExpansion, update

Methods inherited from class Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface BroadphaseDetector

add, contains, detect, detect, detect, detect, detect, detect, detect, getAABB, getAABB, getAABBExpansion, isAABBExpansionSupported, isUpdated, isUpdateTrackingEnabled, isUpdateTrackingSupported, raycast, raycast, remove, setAABBExpansion, setUpdated, supportsAABBExpansion, update

Constructor Detail

Sap

public Sap()

Default constructor.

Sap

public Sap(int initialCapacity)

Full constructor.

Allows fine tuning of the initial capacity of local storage for faster running times.

Parameters:

initialCapacity - the initial capacity of local storage

Throws:

IllegalArgumentException - if initialCapacity is less than zero

Since:

3.1.1

Method Detail

add

public void add(T body,
                E fixture)

Description copied from interface: BroadphaseDetector

Adds a new Fixture for the given CollisionBody to the broad-phase.

Specified by:

add in interface BroadphaseDetector<T extends CollisionBody<E>,E extends Fixture>

Parameters:

body - the body

fixture - the fixture to add

remove

public boolean remove(T body,
                      E fixture)

Description copied from interface: BroadphaseDetector

Removes the given Fixture for the given CollisionBody from the broad-phase and returns true if it was found.

Specified by:

remove in interface BroadphaseDetector<T extends CollisionBody<E>,E extends Fixture>

Parameters:

body - the body

fixture - the fixture to remove

Returns:

boolean true if the fixture was found and removed

remove

public boolean remove(CollisionItem<T,E> item)

Description copied from interface: BroadphaseDetector

Removes the given Fixture for the given CollisionBody from the broad-phase and returns true if it was found.

Specified by:

remove in interface BroadphaseDetector<T extends CollisionBody<E>,E extends Fixture>

Parameters:

item - the collision item

Returns:

boolean true if the fixture was found and removed

update

public void update(T body,
                   E fixture)

Description copied from interface: BroadphaseDetector

Updates the given CollisionBody's Fixture.

Used when a fixture on a CollisionBody has moved or rotated.

This method will add the Fixture if it doesn't currently exist in this broad-phase.

Specified by:

update in interface BroadphaseDetector<T extends CollisionBody<E>,E extends Fixture>

Parameters:

body - the CollisionBody

fixture - the Fixture that has moved

isUpdated

public boolean isUpdated(T body,
                         E fixture)

Description copied from interface: BroadphaseDetector

Returns true if the given Fixture is included in the updated list.

If BroadphaseDetector.isUpdateTrackingEnabled() is false, this method will always return true.

Returns false if the given body-fixture pair is not part of this broadphase.

Specified by:

isUpdated in interface BroadphaseDetector<T extends CollisionBody<E>,E extends Fixture>

Parameters:

body - the CollisionBody

fixture - the Fixture

Returns:

boolean

isUpdated

public boolean isUpdated(CollisionItem<T,E> item)

Description copied from interface: BroadphaseDetector

Returns true if the given Fixture is included in the updated list.

If BroadphaseDetector.isUpdateTrackingEnabled() is false, this method will always return true.

Returns false if the given body-fixture pair is not part of this broadphase.

Specified by:

isUpdated in interface BroadphaseDetector<T extends CollisionBody<E>,E extends Fixture>

Parameters:

item - the collision item

Returns:

boolean

setUpdated

public void setUpdated(T body,
                       E fixture)

Description copied from interface: BroadphaseDetector

The BroadphaseDetector.update(CollisionBody, Fixture) method will only mark the Fixture as updated if the Fixture has moved enough to change the internally stored AABB.

This method is intended to force the broadphase to include the Fixture in the updated list to ensure they are checked in the updated-only detection routine.

Specified by:

setUpdated in interface BroadphaseDetector<T extends CollisionBody<E>,E extends Fixture>

Parameters:

body - the CollisionBody

fixture - the Fixture

clearUpdates

public void clearUpdates()

Description copied from interface: BroadphaseDetector

Clears any internal state that tracks what CollisionBody Fixtures have been updated.

Typically this method would be called from a pipeline after a broadphase collision detection method has been called to clear the state before starting to track new updates.

Specified by:

clearUpdates in interface BroadphaseDetector<T extends CollisionBody<E>,E extends Fixture>

getAABB

public AABB getAABB(CollisionItem<T,E> item)

Description copied from interface: BroadphaseDetector

Returns the AABB for the given CollisionBody Fixture.

If the body and its fixture have not been added to this broad-phase, a new AABB is created and returned (but not added to broad-phase).

In all cases this method returns the expanded AABB in the case this detector supports it.

NOTE: The AABB returned from this method should not be modified. Instead use the AABB.copy() method to create a new instance to modify.

Specified by:

getAABB in interface BroadphaseDetector<T extends CollisionBody<E>,E extends Fixture>

Parameters:

item - the collision item

Returns:

AABB

contains

public boolean contains(T body,
                        E fixture)

Description copied from interface: BroadphaseDetector

Returns true if the given Fixture on the given CollisionBody has been added to this broadphase.

Specified by:

contains in interface BroadphaseDetector<T extends CollisionBody<E>,E extends Fixture>

Parameters:

body - the CollisionBody

fixture - the Fixture

Returns:

boolean

contains

public boolean contains(CollisionItem<T,E> item)

Description copied from interface: BroadphaseDetector

Returns true if the given Fixture on the given CollisionBody has been added to this broadphase.

Specified by:

contains in interface BroadphaseDetector<T extends CollisionBody<E>,E extends Fixture>

Parameters:

item - the collision item

Returns:

boolean

clear

public void clear()

Description copied from interface: BroadphaseDetector

Clears all the CollisionBody Fixtures from this broad-phase and any state held by this broadphase.

Specified by:

clear in interface BroadphaseDetector<T extends CollisionBody<E>,E extends Fixture>

size

public int size()

Description copied from interface: BroadphaseDetector

Returns the number of CollisionBody Fixtures that are being managed in this broad-phase.

Specified by:

size in interface BroadphaseDetector<T extends CollisionBody<E>,E extends Fixture>

Returns:

int

setUpdateTrackingEnabled

public void setUpdateTrackingEnabled(boolean flag)

Description copied from interface: BroadphaseDetector

Sets the update tracking to the given flag.

Tracking updates to the broadphase can have huge performance gains if the majority of objects are stationary or moving slowly enough.

Disabling this feature will clear the set of tracked updates (the updates themselves are not cleared). In addition, when enabling this feature (after disabling it), the user is expected to re-update all items in the broadphase manually to ensure the updates set is non-empty. Typically this will self heal in the next iteration though.

NOTE: Some broadphase detectors may not support this feature.

Specified by:

setUpdateTrackingEnabled in interface BroadphaseDetector<T extends CollisionBody<E>,E extends Fixture>

Overrides:

setUpdateTrackingEnabled in class AbstractBroadphaseDetector<T extends CollisionBody<E>,E extends Fixture>

Parameters:

flag - true to turn on update tracking

See Also:

BroadphaseDetector.isUpdateTrackingSupported()

detectIterator

public Iterator<CollisionPair<T,E>> detectIterator(boolean forceFullDetection)

Description copied from interface: BroadphaseDetector

Performs collision detection on all CollisionBody Fixtures that have been added to this BroadphaseDetector and returns the list of potential pairs.

The returned pairs from this method will depend on the BroadphaseDetector.isUpdateTrackingEnabled() flag. If the flag is true, then only updated pairs will be emitted, otherwise all pairs are emitted.

Use the forceFullDetection parameter to override this behavior for this call.

NOTE: This method returns CollisionPairs that are mutable internally. If you need to store the pairs outside of the iteration, be sure to call the Copyable.copy() method to create a copy of the pair data.

Specified by:

detectIterator in interface BroadphaseDetector<T extends CollisionBody<E>,E extends Fixture>

Parameters:

forceFullDetection - true if a full detection should be performed

Returns:

Iterator<CollisionPair>

detectIterator

public Iterator<CollisionItem<T,E>> detectIterator(AABB aabb)

Description copied from interface: BroadphaseDetector

Performs a broad-phase collision test using the given AABB and returns the items that overlap.

Specified by:

detectIterator in interface BroadphaseDetector<T extends CollisionBody<E>,E extends Fixture>

Parameters:

aabb - the AABB to test

Returns:

Iterator<CollisionItem>

raycastIterator

public Iterator<CollisionItem<T,E>> raycastIterator(Ray ray,
                                                          double length)

Description copied from interface: BroadphaseDetector

Performs a raycast over all the bodies in the broad-phase and returns the items that intersect.

Specified by:

raycastIterator in interface BroadphaseDetector<T extends CollisionBody<E>,E extends Fixture>

Parameters:

ray - the Ray

length - the length of the ray; 0.0 for infinite length

Returns:

Iterator<CollisionItem>

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

optimize

public void optimize()

Description copied from interface: BroadphaseDetector

Attempts to optimize the broadphase based on the current state.

This method could be very intensive so should only be called if there's a clear benefit.

Specified by:

optimize in interface BroadphaseDetector<T extends CollisionBody<E>,E extends Fixture>