Interface BroadphaseDetector<T extends CollisionBody<E>,E extends Fixture>
-
- Type Parameters:
T
- theCollisionBody
typeE
- theFixture
type
- All Superinterfaces:
Shiftable
- All Known Subinterfaces:
BatchBroadphaseDetector<T,E>
- All Known Implementing Classes:
AbstractBroadphaseDetector
,BruteForceBroadphase
,DynamicAABBTree
,LazyAABBTree
,Sap
public interface BroadphaseDetector<T extends CollisionBody<E>,E extends Fixture> extends Shiftable
Represents a broad-phase collision detection algorithm.A
BroadphaseDetector
should quickly determine the pairs ofCollisionBody
s andFixture
s that possibly intersect. These algorithms are used to filter out collision pairs in the interest of sending less pairs to theNarrowphaseDetector
which is generally much more expensive.BroadphaseDetector
s require that the bodies are updated via theupdate(CollisionBody)
orupdate(CollisionBody, Fixture)
methods when the bodies move, rotate, or have their shape changed in anyway.NOTE: Special care must be taken when removing fixtures from a body. Be sure to call the
remove(CollisionBody, Fixture)
method to make sure its removed from the broad-phase.Some
BroadphaseDetector
s use a expansion value to expand a body's AABB width and height. ThegetAABB(CollisionBody)
returns the expandedAABB
. This expansion is used to reduce the number of updates to the broad-phase. See thesetAABBExpansion(double)
for more details on this value.The
detect()
,detect(AABB)
,raycast(Ray, double)
methods and their Iterator counterpart methods use the current state of all the bodies and fixtures that have been added. Make sure that all changes have been reflected to the broad-phase using theupdate(CollisionBody)
andupdate(CollisionBody, Fixture)
methods before calling these.The
detect(Convex, Transform, Convex, Transform)
method does not use the current state of the broad-phase, but thedetect(CollisionBody, CollisionBody)
does.- Since:
- 1.0.0
- Version:
- 4.0.0
- Author:
- William Bittle
-
-
Field Summary
Fields Modifier and Type Field Description static double
DEFAULT_AABB_EXPANSION
The defaultAABB
expansion valuestatic int
DEFAULT_INITIAL_CAPACITY
The default initial capacity of fixtures
-
Method Summary
All Methods Instance Methods Abstract Methods Deprecated Methods Modifier and Type Method Description void
add(T body)
Adds a newCollisionBody
to the broad-phase.void
add(T body, E fixture)
Adds a newFixture
for the givenCollisionBody
to the broad-phase.void
clear()
Clears all theCollisionBody
Fixture
s from this broad-phase and any state held by this broadphase.void
clearUpdates()
Clears any internal state that tracks whatCollisionBody
Fixture
s have been updated.boolean
contains(CollisionItem<T,E> item)
Returns true if the givenFixture
on the givenCollisionBody
has been added to this broadphase.boolean
contains(T body)
Returns true if all theFixture
s on the givenCollisionBody
have been added to this broad-phase.boolean
contains(T body, E fixture)
Returns true if the givenFixture
on the givenCollisionBody
has been added to this broadphase.List<CollisionPair<T,E>>
detect()
Performs collision detection on allCollisionBody
Fixture
s that have been added to thisBroadphaseDetector
and returns the list of potential pairs.List<CollisionPair<T,E>>
detect(boolean forceFullDetection)
Performs collision detection onCollisionBody
Fixture
s that have been added to thisBroadphaseDetector
and returns the list of potential pairs.List<CollisionPair<T,E>>
detect(BroadphaseFilter<T,E> filter)
Deprecated.Deprecated in 4.0.0.List<CollisionItem<T,E>>
detect(AABB aabb)
Performs a broad-phase collision test using the givenAABB
and returns the items that overlap.List<CollisionItem<T,E>>
detect(AABB aabb, BroadphaseFilter<T,E> filter)
Deprecated.Deprecated in 4.0.0.boolean
detect(Convex convex1, Transform transform1, Convex convex2, Transform transform2)
boolean
detect(T a, T b)
Returns true if this broad-phase detector considers the given bodies to be in collision.Iterator<CollisionPair<T,E>>
detectIterator(boolean forceFullDetection)
Performs collision detection on allCollisionBody
Fixture
s that have been added to thisBroadphaseDetector
and returns the list of potential pairs.Iterator<CollisionItem<T,E>>
detectIterator(AABB aabb)
Performs a broad-phase collision test using the givenAABB
and returns the items that overlap.AABB
getAABB(CollisionItem<T,E> item)
Returns the AABB for the givenCollisionBody
Fixture
.AABB
getAABB(T body)
Returns the AABB for the givenCollisionBody
.AABB
getAABB(T body, E fixture)
Returns the AABB for the givenCollisionBody
Fixture
.double
getAABBExpansion()
Returns theAABB
expansion value used to improve performance of broad-phase updates.boolean
isAABBExpansionSupported()
Returns whether this particularBroadphaseDetector
supports expanding AABBs.boolean
isUpdated(CollisionItem<T,E> item)
Returns true if the givenFixture
is included in the updated list.boolean
isUpdated(T body)
Returns true if any of theFixture
s on the givenCollisionBody
are included in the updated list.boolean
isUpdated(T body, E fixture)
Returns true if the givenFixture
is included in the updated list.boolean
isUpdateTrackingEnabled()
Returns true if this broadphase is tracking updated items.boolean
isUpdateTrackingSupported()
Returns whether this particularBroadphaseDetector
supports update tracking.void
optimize()
Attempts to optimize the broadphase based on the current state.List<CollisionItem<T,E>>
raycast(Ray ray, double length)
Performs a raycast over all the bodies in the broad-phase and returns the items that intersect.List<CollisionItem<T,E>>
raycast(Ray ray, double length, BroadphaseFilter<T,E> filter)
Deprecated.Deprecated in 4.0.0.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 givenFixture
for the givenCollisionBody
from the broad-phase and returns true if it was found.void
remove(T body)
Removes the givenCollisionBody
from the broad-phase.boolean
remove(T body, E fixture)
Removes the givenFixture
for the givenCollisionBody
from the broad-phase and returns true if it was found.void
setAABBExpansion(double expansion)
Sets theAABB
expansion value used to improve performance of broad-phase updates.void
setUpdated(T body)
Theupdate(CollisionBody)
method will only mark aCollisionBody
as updated if it's fixtures have moved enough to change the internally stored AABB.void
setUpdated(T body, E fixture)
Theupdate(CollisionBody, Fixture)
method will only mark theFixture
as updated if theFixture
has moved enough to change the internally stored AABB.void
setUpdateTrackingEnabled(boolean flag)
Sets the update tracking to the given flag.int
size()
Returns the number ofCollisionBody
Fixture
s that are being managed in this broad-phase.boolean
supportsAABBExpansion()
Deprecated.Deprecated in 4.0.0.void
update(T body)
Updates all theFixture
s on the givenCollisionBody
.void
update(T body, E fixture)
Updates the givenCollisionBody
'sFixture
.
-
-
-
Field Detail
-
DEFAULT_AABB_EXPANSION
static final double DEFAULT_AABB_EXPANSION
The defaultAABB
expansion value- See Also:
- Constant Field Values
-
DEFAULT_INITIAL_CAPACITY
static final int DEFAULT_INITIAL_CAPACITY
The default initial capacity of fixtures- See Also:
- Constant Field Values
-
-
Method Detail
-
add
void add(T body)
Adds a newCollisionBody
to the broad-phase.This will add all the given
CollisionBody
'sFixture
s to the broad-phase.If the body has no fixtures, nothing will be added to this broad-phase.
If the
CollisionBody
'sFixture
s have already been added to this broad-phase they will instead be updated.If a
Fixture
has been added to theCollisionBody
and theCollisionBody
has already been added to this broadphase, any newFixture
s will be added, and the existing ones will be updated.If a fixture is removed from a
CollisionBody
, the calling code must call theremove(CollisionBody, Fixture)
method for that fixture to be removed from the broad-phase. This method makes no effort to remove fixtures no longer attached to the given body.- Parameters:
body
- theCollisionBody
- Since:
- 3.0.0
-
add
void add(T body, E fixture)
Adds a newFixture
for the givenCollisionBody
to the broad-phase.- Parameters:
body
- the bodyfixture
- the fixture to add- Since:
- 3.2.0
-
remove
void remove(T body)
Removes the givenCollisionBody
from the broad-phase.This method removes all the
Fixture
s attached to the givenCollisionBody
from the broad-phase.If a fixture is removed from a
CollisionBody
, the calling code must call theremove(CollisionBody, Fixture)
method for that fixture to be removed from the broad-phase. This method makes no effort to remove fixtures no longer attached to the given body.- Parameters:
body
- theCollisionBody
- Since:
- 3.0.0
-
remove
boolean remove(T body, E fixture)
Removes the givenFixture
for the givenCollisionBody
from the broad-phase and returns true if it was found.- Parameters:
body
- the bodyfixture
- the fixture to remove- Returns:
- boolean true if the fixture was found and removed
- Since:
- 3.2.0
-
remove
boolean remove(CollisionItem<T,E> item)
Removes the givenFixture
for the givenCollisionBody
from the broad-phase and returns true if it was found.- Parameters:
item
- the collision item- Returns:
- boolean true if the fixture was found and removed
- Since:
- 4.0.0
-
update
void update(T body)
Updates all theFixture
s on the givenCollisionBody
.Used when the body or its fixtures have moved or rotated.
This method updates all the
Fixture
s attached to the givenCollisionBody
from the broad-phase, if they exist. If the fixtures on the given body do not exist in the broad-phase, they are added.If a fixture is removed from a
CollisionBody
, the calling code must call theremove(CollisionBody, Fixture)
method for that fixture to be removed from the broad-phase. This method makes no effort to remove fixtures no longer attached to the given body.- Parameters:
body
- theCollisionBody
- Since:
- 3.2.0
-
update
void update(T body, E fixture)
Updates the givenCollisionBody
'sFixture
.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.- Parameters:
body
- theCollisionBody
fixture
- theFixture
that has moved- Since:
- 3.2.0
-
setUpdated
void setUpdated(T body)
Theupdate(CollisionBody)
method will only mark aCollisionBody
as updated if it's fixtures have moved enough to change the internally stored AABB.This method is intended to force the broadphase to include this
CollisionBody
'sFixture
s in the updated list to ensure they are checked in the updated-only detection routine.- Parameters:
body
- theCollisionBody
- Since:
- 4.0.0
-
setUpdated
void setUpdated(T body, E fixture)
Theupdate(CollisionBody, Fixture)
method will only mark theFixture
as updated if theFixture
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.- Parameters:
body
- theCollisionBody
fixture
- theFixture
- Since:
- 4.0.0
-
isUpdated
boolean isUpdated(T body)
Returns true if any of theFixture
s on the givenCollisionBody
are included in the updated list.If
isUpdateTrackingEnabled()
is false, this method will always return true.Returns false if the given body is not part of this broadphase.
- Parameters:
body
- theCollisionBody
- Returns:
- boolean
- Since:
- 4.0.0
-
isUpdated
boolean isUpdated(T body, E fixture)
Returns true if the givenFixture
is included in the updated list.If
isUpdateTrackingEnabled()
is false, this method will always return true.Returns false if the given body-fixture pair is not part of this broadphase.
- Parameters:
body
- theCollisionBody
fixture
- theFixture
- Returns:
- boolean
- Since:
- 4.0.0
-
isUpdated
boolean isUpdated(CollisionItem<T,E> item)
Returns true if the givenFixture
is included in the updated list.If
isUpdateTrackingEnabled()
is false, this method will always return true.Returns false if the given body-fixture pair is not part of this broadphase.
- Parameters:
item
- the collision item- Returns:
- boolean
- Since:
- 4.0.0
-
clearUpdates
void clearUpdates()
Clears any internal state that tracks whatCollisionBody
Fixture
s 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.
- Since:
- 4.0.0
-
getAABB
AABB getAABB(T body)
Returns the AABB for the givenCollisionBody
.The AABB returned is an AABB encompasing all fixtures on the given
CollisionBody
. When possible, AABBs from the broad-phase will be used to create this, otherwise new AABBs will be created and unioned.In all cases this method returns the expanded AABB in the case this detector supports it.
If the body doesn't have any fixtures a degenerate AABB is returned.
- Parameters:
body
- theCollisionBody
- Returns:
AABB
- Since:
- 3.2.0
-
getAABB
AABB getAABB(T body, E fixture)
Returns the AABB for the givenCollisionBody
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 theAABB.copy()
method to create a new instance to modify.- Parameters:
body
- theCollisionBody
fixture
- theFixture
- Returns:
AABB
- Since:
- 3.2.0
-
getAABB
AABB getAABB(CollisionItem<T,E> item)
Returns the AABB for the givenCollisionBody
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 theAABB.copy()
method to create a new instance to modify.- Parameters:
item
- the collision item- Returns:
AABB
- Since:
- 4.0.0
-
contains
boolean contains(T body)
Returns true if all theFixture
s on the givenCollisionBody
have been added to this broad-phase.If a body is added without any fixtures, this method will return false, since the fixtures, not the body, are added to the broad-phase.
- Parameters:
body
- theCollisionBody
- Returns:
- boolean
- Since:
- 3.2.0
-
contains
boolean contains(T body, E fixture)
Returns true if the givenFixture
on the givenCollisionBody
has been added to this broadphase.- Parameters:
body
- theCollisionBody
fixture
- theFixture
- Returns:
- boolean
- Since:
- 3.2.0
-
contains
boolean contains(CollisionItem<T,E> item)
Returns true if the givenFixture
on the givenCollisionBody
has been added to this broadphase.- Parameters:
item
- the collision item- Returns:
- boolean
- Since:
- 4.0.0
-
clear
void clear()
Clears all theCollisionBody
Fixture
s from this broad-phase and any state held by this broadphase.- Since:
- 3.0.0
-
size
int size()
Returns the number ofCollisionBody
Fixture
s that are being managed in this broad-phase.- Returns:
- int
-
detect
List<CollisionPair<T,E>> detect()
Performs collision detection on allCollisionBody
Fixture
s that have been added to thisBroadphaseDetector
and returns the list of potential pairs.- Returns:
- List<
BroadphasePair
> - Since:
- 3.0.0
-
detect
List<CollisionPair<T,E>> detect(boolean forceFullDetection)
Performs collision detection onCollisionBody
Fixture
s that have been added to thisBroadphaseDetector
and returns the list of potential pairs.The returned pairs from this method will depend on the
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.
- Parameters:
forceFullDetection
- true if a full detection should be performed- Returns:
- List<
BroadphasePair
> - Since:
- 3.0.0
-
detect
@Deprecated List<CollisionPair<T,E>> detect(BroadphaseFilter<T,E> filter)
Deprecated.Deprecated in 4.0.0. Use thedetect()
method instead.Performs collision detection on allCollisionBody
Fixture
s that have been added to thisBroadphaseDetector
and returns the list of potential pairs.Use the
filter
parameter to further reduce the number of potential pairs.- Parameters:
filter
- the broad-phase filter- Returns:
- List<
BroadphasePair
> - Since:
- 3.2.0
- See Also:
detect()
-
detectIterator
Iterator<CollisionPair<T,E>> detectIterator(boolean forceFullDetection)
Performs collision detection on allCollisionBody
Fixture
s that have been added to thisBroadphaseDetector
and returns the list of potential pairs.The returned pairs from this method will depend on the
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
CollisionPair
s that are mutable internally. If you need to store the pairs outside of the iteration, be sure to call theCopyable.copy()
method to create a copy of the pair data.- Parameters:
forceFullDetection
- true if a full detection should be performed- Returns:
- Iterator<
CollisionPair
> - Since:
- 4.0.0
-
detect
List<CollisionItem<T,E>> detect(AABB aabb)
Performs a broad-phase collision test using the givenAABB
and returns the items that overlap.- Parameters:
aabb
- theAABB
to test- Returns:
- List<
CollisionItem
> - Since:
- 3.0.0
-
detectIterator
Iterator<CollisionItem<T,E>> detectIterator(AABB aabb)
Performs a broad-phase collision test using the givenAABB
and returns the items that overlap.- Parameters:
aabb
- theAABB
to test- Returns:
- Iterator<
CollisionItem
> - Since:
- 4.0.0
-
detect
@Deprecated List<CollisionItem<T,E>> detect(AABB aabb, BroadphaseFilter<T,E> filter)
Deprecated.Deprecated in 4.0.0. Use thedetect(AABB)
method insteadPerforms a broad-phase collision test using the givenAABB
and returns the items that overlap.Use the
filter
parameter to further reduce the number of items returned.- Parameters:
aabb
- theAABB
to testfilter
- the broad-phase filter- Returns:
- List<
CollisionItem
> - Since:
- 3.2.0
- See Also:
detect(AABB)
-
raycast
List<CollisionItem<T,E>> raycast(Ray ray, double length)
Performs a raycast over all the bodies in the broad-phase and returns the items that intersect.- Parameters:
ray
- theRay
length
- the length of the ray; 0.0 for infinite length- Returns:
- List<
CollisionItem
> - Since:
- 3.0.0
-
raycastIterator
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.- Parameters:
ray
- theRay
length
- the length of the ray; 0.0 for infinite length- Returns:
- Iterator<
CollisionItem
> - Since:
- 4.0.0
-
raycast
@Deprecated List<CollisionItem<T,E>> raycast(Ray ray, double length, BroadphaseFilter<T,E> filter)
Deprecated.Deprecated in 4.0.0. Use theraycast(Ray, double)
method insteadPerforms a preliminary raycast over all the bodies in the broad-phase and returns the items that intersect.Use the
filter
parameter to further reduce the number of items returned.- Parameters:
ray
- theRay
length
- the length of the ray; 0.0 for infinite lengthfilter
- the broad-phase filter- Returns:
- List<
BroadphaseItem
> - Since:
- 3.2.0
- See Also:
raycast(Ray, double)
-
detect
boolean detect(T a, T b)
Returns true if this broad-phase detector considers the given bodies to be in collision.- Parameters:
a
- the firstCollisionBody
b
- the secondCollisionBody
- Returns:
- boolean
-
supportsAABBExpansion
@Deprecated boolean supportsAABBExpansion()
Deprecated.Deprecated in 4.0.0. Use theisAABBExpansionSupported()
method instead.Returns whether this particularBroadphaseDetector
supports expanding AABBs.- Returns:
- boolean
-
isAABBExpansionSupported
boolean isAABBExpansionSupported()
Returns whether this particularBroadphaseDetector
supports expanding AABBs.- Returns:
- boolean
-
isUpdateTrackingSupported
boolean isUpdateTrackingSupported()
Returns whether this particularBroadphaseDetector
supports update tracking.- Returns:
- boolean
-
getAABBExpansion
double getAABBExpansion()
Returns theAABB
expansion value used to improve performance of broad-phase updates.If supportsAABBExpansion() returns false the value returned is unspecified and should not be taken into account.
- Returns:
- double
- See Also:
setAABBExpansion(double)
-
setAABBExpansion
void setAABBExpansion(double expansion)
Sets theAABB
expansion value used to improve performance of broad-phase updates.Increasing this value will cause less updates to the broad-phase but will cause more pairs to be sent to the narrow-phase.
Note that a broadphase implementation may ignore this value, if supportsAABBExpansion() returns false.
- Parameters:
expansion
- the expansion
-
isUpdateTrackingEnabled
boolean isUpdateTrackingEnabled()
Returns true if this broadphase is tracking updated items.Tracking updates to the broadphase can have huge performance gains if the majority of objects are stationary or moving slowly enough.
- Returns:
- boolean
- Since:
- 4.0.0
-
setUpdateTrackingEnabled
void setUpdateTrackingEnabled(boolean flag)
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.
- Parameters:
flag
- true to turn on update tracking- Since:
- 4.0.0
- See Also:
isUpdateTrackingSupported()
-
optimize
void optimize()
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.
- Since:
- 4.0.0
-
-