Type Parameters:

T - the object type

All Superinterfaces:

Shiftable

All Known Subinterfaces:

BroadphaseDetectorDecorator<T>, CollisionItemBroadphaseDetector<T,E>

All Known Implementing Classes:

AbstractBroadphaseDetector, BroadphaseDetectorDecoratorAdapter, BruteForceBroadphase, CollisionItemBroadphaseDetectorAdapter, DynamicAABBTree, Sap
```
public interface BroadphaseDetector<T>
extends Shiftable
```
Represents a broad-phase collision detection algorithm.
A BroadphaseDetector should quickly determine the pairs of objects that possibly intersect. These algorithms are used to filter out collision pairs in the interest of sending less pairs to the NarrowphaseDetector which is generally much more expensive.
BroadphaseDetectors require that the objects are updated via the update(Object) method when translated, rotated, or have their shape changed in anyway.
A AABBProducer is used to produce an AABB from a given object. AABBs are used by the BroadphaseDetectors to accelerate the initial detection of collision pairs.
Some BroadphaseDetectors may use a expansion method to expand an object's AABB size. The getAABB(Object) method returns the expanded AABB in this scenario. This expansion is used to reduce the number of updates to the broad-phase acceleration structure. See also the AABBExpansionMethod interface for more detail.
The detect(), detect(AABB), raycast(Ray, double) methods, and their Iterator counterparts, use the current state of the acceleration structure housed by the BroadphaseDetector. Make sure that all changes have been reflected to the broad-phase (via update(Object), remove(Object), etc) before using these methods.
The detect(Convex, Transform, Convex, Transform) method does not use the current state of the broad-phase, but the detect(Object, Object) does.
There are two main operation modes for BroadphaseDetectors: Full or Incremental. Full is the classic way where every call to the detect() or detectIterator() methods return all overlapping pairs. This has the advantage of always getting a fresh list of pairs. The down side, even with acceleration structures in place, is that it's a lot of extra work, especially for scenes where most objects don't move between frames. Incremental is the new way where every call to the detect() or detectIterator() methods returns only the pairs where one of the objects had their AABB updated (see above regarding the expansion method). In this mode, callers would need to manage the list of pairs overtime and check for those no longer overlapping. While this is more work on the caller, it's far more efficient.
NOTE: The objects added to a BroadphaseDetector may be used in data structures that rely on the Object.hashCode() and Object.equals(Object) methods and the == operator. In general, when using subclasses of CollisionBody, avoid overriding these methods. When using subclasses of CollisionItem, avoid reusing those object as the hashcode and equals method depends upon the content.

Since:

1.0.0

Version:

4.1.0

Author:

William Bittle

Field Summary

Fields
Modifier and Type Field Description

static int DEFAULT_INITIAL_CAPACITY
The default initial capacity of fixtures

Method Summary

All Methods Instance Methods Abstract Methods
Modifier and Type	Method	Description
`void`	`add(T object)`	Adds a new object to this broad-phase.
`void`	`clear()`	Clear all the internal state of this broad-phase.
`void`	`clearUpdates()`	Clears internal state that tracks what objects have been updated.
`boolean`	`contains(T object)`	Returns true if the given object exists in this broad-phase.
`List<CollisionPair<T>>`	`detect()`	Performs collision detection on all objects that have been added to this `BroadphaseDetector` and returns the list of potential collision pairs (i.e.
`List<CollisionPair<T>>`	`detect(boolean forceFullDetection)`	Performs collision detection on all objects that have been added to this `BroadphaseDetector` and returns the list of potential collision pairs (i.e.
`List<T>`	`detect(AABB aabb)`	Performs a broad-phase collision test using the given `AABB` and returns the items that overlap.
`boolean`	`detect(Convex convex1, Transform transform1, Convex convex2, Transform transform2)`	Returns true if this broad-phase detector considers the given `Convex` `Shape`s to be in collision.
`boolean`	`detect(T a, T b)`	Returns true if this broad-phase detector considers the given objects to be in collision.
`Iterator<CollisionPair<T>>`	`detectIterator()`	Performs collision detection on all objects that have been added to this `BroadphaseDetector` and returns an iterator of potential collision pairs (i.e.
`Iterator<CollisionPair<T>>`	`detectIterator(boolean forceFullDetection)`	Performs collision detection on all objects that have been added to this `BroadphaseDetector` and returns an iterator of potential collision pairs (i.e.
`Iterator<T>`	`detectIterator(AABB aabb)`	Performs a broad-phase collision test using the given `AABB` and returns the items that overlap.
`AABB`	`getAABB(T object)`	Returns the AABB for the given object.
`AABBExpansionMethod<T>`	`getAABBExpansionMethod()`	Returns the `AABBExpansionMethod` used by this broad-phase detector.
`AABBProducer<T>`	`getAABBProducer()`	Returns the `AABBProducer` used by this broad-phase detector.
`BroadphaseFilter<T>`	`getBroadphaseFilter()`	Returns the `BroadphaseFilter` used by this broad-phase detector.
`boolean`	`isUpdated(T object)`	Returns true if the given object is marked as updated in this broad-phase.
`boolean`	`isUpdateTrackingEnabled()`	Returns true if this broad-phase is tracking updated items.
`boolean`	`isUpdateTrackingSupported()`	Returns whether this particular `BroadphaseDetector` supports update tracking.
`void`	`optimize()`	Attempts to optimize the broad-phase based on the current state.
`List<T>`	`raycast(Ray ray, double length)`	Performs a raycast over all the objects in this broad-phase and returns the items that intersect.
`Iterator<T>`	`raycastIterator(Ray ray, double length)`	Performs a raycast over all the objects in the broad-phase and returns the items that intersect.
`boolean`	`remove(T object)`	Removes the given object from this broad-phase.
`void`	`setUpdated(T object)`	This method forces this broad-phase to include the given object in the updated list to ensure they are checked in the updated-only detection routine.
`void`	`setUpdateTrackingEnabled(boolean flag)`	Sets the update tracking to the given flag.
`int`	`size()`	Returns the number of objects managed in this broad-phase.
`void`	`update()`	Updates all the currently stored objects AABBs based on their current state, the `AABBProducer`, and the `AABBExpansionMethod`.
`void`	`update(T object)`	Updates the broad-phase representation of the given object.

Methods inherited from interface Shiftable
shift

- Field Detail
  - 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 object)
```
    Adds a new object to this broad-phase.
    If the given object has already been added, the object is updated (update(Object)).
    
    Parameters:
    
    object - the object to add
    
    Since:
    
    3.0.0
  - remove
```
boolean remove(T object)
```
    Removes the given object from this broad-phase.
    
    Parameters:
    
    object - the object to remove
    
    Returns:
    
    boolean true if the object was removed
    
    Since:
    
    3.0.0
  - update
```
void update()
```
    Updates all the currently stored objects AABBs based on their current state, the AABBProducer, and the AABBExpansionMethod.
    
    Since:
    
    4.1.0
  - update
```
void update(T object)
```
    Updates the broad-phase representation of the given object.
    This should be called when the object's location, rotation, or shape has changed.
    
    Parameters:
    
    object - the object
    
    Since:
    
    3.2.0
  - setUpdated
```
void setUpdated(T object)
```
    This method forces this broad-phase to include the given object in the updated list to ensure they are checked in the updated-only detection routine.
    The update(Object) method will only mark an object as updated if it's fixtures have moved enough to change the internally stored AABB.
    
    Parameters:
    
    object - the object
    
    Since:
    
    4.0.0
  - isUpdated
```
boolean isUpdated(T object)
```
    Returns true if the given object is marked as updated in this broad-phase.
    If isUpdateTrackingEnabled() is false, this method will always return true.
    Returns false if the given object is not part of this broad-phase.
    
    Parameters:
    
    object - the object
    
    Returns:
    
    boolean
    
    Since:
    
    4.0.0
  - clearUpdates
```
void clearUpdates()
```
    Clears internal state that tracks what objects have been updated.
    Typically this method would be called from a pipeline after a broad-phase collision detection method has been called to clear the state before starting to track new updates.
    
    Since:
    
    4.0.0
  - getAABB
```
AABB getAABB(T object)
```
    Returns the AABB for the given object.
    NOTE: Some BroadphaseDetectors use modified (expanded for example) AABBs rather than tight fitting AABBs as a performance enhancement. This method returns the AABB used by this detector, and therefore, the modified AABB.
    NOTE: The AABB returned from this method should not be modified. Instead use the AABB.copy() method to create a new instance to modify.
    If the given object does not exist in this BroadphaseDetector a new AABB is created based on the object's shape, the getAABBProducer() and getAABBExpansionMethod().
    
    Parameters:
    
    object - the object
    
    Returns:
    
    AABB
    
    Since:
    
    3.2.0
  - contains
```
boolean contains(T object)
```
    Returns true if the given object exists in this broad-phase.
    
    Parameters:
    
    object - the object
    
    Returns:
    
    boolean
    
    Since:
    
    3.2.0
  - clear
```
void clear()
```
    Clear all the internal state of this broad-phase.
    
    Since:
    
    3.0.0
  - size
```
int size()
```
    Returns the number of objects managed in this broad-phase.
    
    Returns:
    
    int
  - detect
```
List<CollisionPair<T>> detect()
```
    Performs collision detection on all objects that have been added to this BroadphaseDetector and returns the list of potential collision pairs (i.e. those pairs whose AABBs overlap).
    The pairs returned from this method will depend on the value of the isUpdateTrackingEnabled() flag. When false, the returned list will report all pairs, every invocation. When true, the returned list will only contain pairs whose objects moved significantly enough to generate new AABBs. As a result, this mode would not report those pairs who ARE NOT overlapping, nor would it report those pairs who ARE overlapping, but the objects didn't move enough.
    
    Returns:
    
    List<BroadphasePair>
    
    Since:
    
    3.0.0
  - detect
```
List<CollisionPair<T>> detect(boolean forceFullDetection)
```
    Performs collision detection on all objects that have been added to this BroadphaseDetector and returns the list of potential collision pairs (i.e. those pairs whose AABBs overlap).
    The pairs returned from this method will depend on the value of the isUpdateTrackingEnabled() flag. When false, the returned list will report all pairs, every invocation. When true, the returned list will only contain pairs whose objects moved significantly enough to generate new AABBs. As a result, this mode would not report those pairs who ARE NOT overlapping, nor would it report those pairs who ARE overlapping, but the objects didn't move enough.
    Use the forceFullDetection parameter to override the isUpdateTrackingEnabled() flag for this invocation.
    
    Parameters:
    
    forceFullDetection - true if a full detection should be performed
    
    Returns:
    
    List<BroadphasePair>
    
    Since:
    
    3.0.0
  - detectIterator
```
Iterator<CollisionPair<T>> detectIterator()
```
    Performs collision detection on all objects that have been added to this BroadphaseDetector and returns an iterator of potential collision pairs (i.e. those pairs whose AABBs overlap).
    The pairs returned from this method will depend on the value of the isUpdateTrackingEnabled() flag. When false, the returned iterator will report all pairs, every invocation. When true, the returned iterator will only contain pairs whose objects moved significantly enough to generate new AABBs. As a result, this mode would not report those pairs who ARE NOT overlapping, nor would it report those pairs who ARE overlapping, but the objects didn't move enough.
    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.
    
    Returns:
    
    Iterator<CollisionPair>
    
    Since:
    
    4.1.0
  - detectIterator
```
Iterator<CollisionPair<T>> detectIterator(boolean forceFullDetection)
```
    Performs collision detection on all objects that have been added to this BroadphaseDetector and returns an iterator of potential collision pairs (i.e. those pairs whose AABBs overlap).
    The pairs returned from this method will depend on the value of the isUpdateTrackingEnabled() flag. When false, the returned iterator will report all pairs, every invocation. When true, the returned iterator will only contain pairs whose objects moved significantly enough to generate new AABBs. As a result, this mode would not report those pairs who ARE NOT overlapping, nor would it report those pairs who ARE overlapping, but the objects didn't move enough.
    Use the forceFullDetection parameter to override this behavior for a single 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.
    
    Parameters:
    
    forceFullDetection - true if a full detection should be performed
    
    Returns:
    
    Iterator<CollisionPair>
    
    Since:
    
    4.0.0
  - detect
```
List<T> detect(AABB aabb)
```
    Performs a broad-phase collision test using the given AABB and returns the items that overlap.
    
    Parameters:
    
    aabb - the AABB to test
    
    Returns:
    
    List<T>
    
    Since:
    
    3.0.0
  - detectIterator
```
Iterator<T> detectIterator(AABB aabb)
```
    Performs a broad-phase collision test using the given AABB and returns the items that overlap.
    
    Parameters:
    
    aabb - the AABB to test
    
    Returns:
    
    Iterator<T>
    
    Since:
    
    4.0.0
  - raycast
```
List<T> raycast(Ray ray,
                double length)
```
    Performs a raycast over all the objects in this broad-phase and returns the items that intersect.
    
    Parameters:
    
    ray - the Ray
    
    length - the length of the ray; 0.0 for infinite length
    
    Returns:
    
    List<T>
    
    Since:
    
    3.0.0
  - raycastIterator
```
Iterator<T> raycastIterator(Ray ray,
                            double length)
```
    Performs a raycast over all the objects in the broad-phase and returns the items that intersect.
    
    Parameters:
    
    ray - the Ray
    
    length - the length of the ray; 0.0 for infinite length
    
    Returns:
    
    Iterator<T>
    
    Since:
    
    4.0.0
  - detect
```
boolean detect(T a,
               T b)
```
    Returns true if this broad-phase detector considers the given objects to be in collision.
    
    Parameters:
    
    a - the first object
    
    b - the second object
    
    Returns:
    
    boolean
  - detect
```
boolean detect(Convex convex1,
               Transform transform1,
               Convex convex2,
               Transform transform2)
```
    Returns true if this broad-phase detector considers the given Convex Shapes to be in collision.
    This method does not use the expansion value.
    
    Parameters:
    
    convex1 - the first Convex Shape
    
    transform1 - the first Convex Shape's Transform
    
    convex2 - the second Convex Shape
    
    transform2 - the second Convex Shape's Transform
    
    Returns:
    
    boolean
  - getAABBProducer
```
AABBProducer<T> getAABBProducer()
```
    Returns the AABBProducer used by this broad-phase detector.
    
    Returns:
    
    AABBProducer
    
    Since:
    
    4.1.0
  - getAABBExpansionMethod
```
AABBExpansionMethod<T> getAABBExpansionMethod()
```
    Returns the AABBExpansionMethod used by this broad-phase detector.
    
    Returns:
    
    AABBExpansionMethod
    
    Since:
    
    4.1.0
  - getBroadphaseFilter
```
BroadphaseFilter<T> getBroadphaseFilter()
```
    Returns the BroadphaseFilter used by this broad-phase detector.
    
    Returns:
    
    BroadphaseFilter
    
    Since:
    
    4.1.0
  - isUpdateTrackingSupported
```
boolean isUpdateTrackingSupported()
```
    Returns whether this particular BroadphaseDetector supports update tracking.
    
    Returns:
    
    boolean
  - isUpdateTrackingEnabled
```
boolean isUpdateTrackingEnabled()
```
    Returns true if this broad-phase is tracking updated items.
    Tracking updates to the broad-phase 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 broad-phase 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 broad-phase manually to ensure the updates set is non-empty. Typically this will self heal in the next iteration though.
    
    Parameters:
    
    flag - true to turn on update tracking
    
    Since:
    
    4.0.0
    
    See Also:
    
    isUpdateTrackingSupported()
  - optimize
```
void optimize()
```
    Attempts to optimize the broad-phase 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

Interface BroadphaseDetector<T>

Field Summary

Method Summary

Methods inherited from interface Shiftable

Field Detail

DEFAULT_INITIAL_CAPACITY

Method Detail

add

remove

update

update

setUpdated

isUpdated

clearUpdates

getAABB

contains

clear

size

detect

detect

detectIterator

detectIterator

detect

detectIterator

raycast

raycastIterator

detect

detect

getAABBProducer

getAABBExpansionMethod

getBroadphaseFilter

isUpdateTrackingSupported

isUpdateTrackingEnabled

setUpdateTrackingEnabled

optimize