public interface ISpatialPartition<T> : ICollection<T>, 
	IEnumerable<T>, IEnumerable

Public Interface ISpatialPartition(Of T)
	Inherits ICollection(Of T), IEnumerable(Of T), IEnumerable

generic<typename T>
public interface class ISpatialPartition : ICollection<T>, 
	IEnumerable<T>, IEnumerable

type ISpatialPartition<'T> =  
    interface
        interface ICollection<'T>
        interface IEnumerable<'T>
        interface IEnumerable
    end

Type Parameters

T

The type of the items.

A spatial partition is a ICollectionT of items of a model or in a space. Spatial partitioning structures items according to their position and extents in space. This is usually used to manage the objects of a 3D model (using bounding box trees or other methods) or objects in a 3D space (using grids, octrees, etc.). Spatial partitions allow fast queries on the items. For example: "Give me all items that touch a given axis aligned bounding box." Or: "Give me all pairs of touching items."

The items in the spatial partitions (see type parameter T) can be of any kind: integer values that define triangle indices of a triangle mesh, or CollisionObject in a space, ...

Creating Spatial Partitions: A ISpatialPartitionT is a ICollectionT, so items can be added and removed. The internal structure will be built when Update(Boolean) is called. When items move or change their shape, the spatial partition must be informed using Invalidate(T) (for a single item) or Invalidate (if more or all items have changed). Then Update(Boolean) must be called to rebuild the internal structure.

Calling Add/Remove/Invalidate methods are fast operations. The internal work is done when Update(Boolean) is called. If Update(Boolean) is not called by the owner of the spatial partition, then it will be automatically called when GetOverlaps (or one of its overloads) is called.

Querying Spatial Partitions: A ISpatialPartitionT has several GetOverlaps methods that allow to get all the items that touch a specific item or region. These queries are more efficient than enumerating and testing all contained items manually. Some queries return PairTs which describe pairs of touching objects.

Spatial partitions use approximate representations of the managed items - usually bounding volumes instead of the actual geometry. For example, when using a AabbTreeT items are represented using their axis-aligned bounding box (AABB). The GetOverlaps methods only test the bounding volumes against each other to check for potential intersections. When a GetOverlaps method returns an item or an item pair, it is not guaranteed that the items are actually touching - for returned items the spatial partition computed that it is very likely that they are touching. For example: When managing triangles with the help of an AabbTreeT the method GetOverlaps returns all triangles where the bounding boxes overlap. Overlapping bounding volumes do not guarantee that the contained items are actually intersecting - the triangles could still be separated.

A spatial partition does not replace a detailed collision detection. It only helps to efficiently sort out items that do not intersect.

AABB Computation of Items: When creating an instance of an ISpatialPartitionT a callback that computes the Aabb for a given item must be specified. The spatial partition does not know how to compute the positions and extents of the items. The GetAabbForItem delegate is used to compute an Aabbs for each item. The computed Aabb is used to define the spatial properties of an item. For a single item the method must always return the same Aabb. If the AABB of an item has changed (e.g. the item has moved or changed shape), Invalidate must be called.

Self Overlaps: A self-overlap is an overlap of two items where both items are contained in the spatial partition. Self-overlaps are only computed if EnableSelfOverlaps is set. Self-overlaps can be queried using GetOverlaps. Overlaps of a single item with itself are never returned.

Filtering: Per default, no filter is set and GetOverlaps methods return all found overlaps. A Filter can be set. Then, whenever a pair of items is tested the overlap will only be accepted if Filter(PairT) returns . The filter is not used if an item is tested against an Aabb or a Ray.

Rebuild versus Refit: The spatial partitioning is performed when Update(Boolean) is called. The spatial partition will build a new internal structure if many or all items are new or were invalidated (see Invalidate(T)). If only a few items were changed, the spatial partition will perform a faster "refit" operation that changes only the relevant parts of the internal structure. Depending on the type of spatial partitioning, refit operations can lead to less optimal internal structures. The Update(Boolean) method has a forceRebuild parameter with which a complete rebuild can be demanded.

Cloning: Spatial partitions are cloneable. Cloning creates a deep copy of the spatial partition. All properties and internal data structures are duplicated. However, the items contained in the spatial partitions are not copied. The clone will be an empty spatial partition that can be used independently from the original spatial partitions.

Reference