class
ecs::SparseSet
Similar to an array, but saves memory by not allocating data if there are large gaps in the stored indices. i.e. while a regular array would require you to allocate an array of size 100 000 to store an entry at index 99 999, sparse set will only allocate a single page of data.
Internally the set works by allocating two arrays:
- Sparse: Stores lookup from the user-provided index to the internal packed array index. Uses pages to avoid allocating memory for unused index ranges.
- Packed: Stores all the data in one contiguous array.
Packed array can be iterated as efficiently as a regular array, while lookups based on index come with a cost of an additional layer of indirection (packed[sparse[index]]), as well as some arithmetic for page calculation.
Public
Constructors
SparseSet
Methods
~SparseSet
GetElementTypeHash
Returns a hash value that represents the element type stored in this set.
Add
Adds a new entity to the set and returns an iterator of the added entity.
Caller must ensure not to add an entity with an index that's already in the set.
Add
Adds all entities from the provided iterator range to the set, and returns a pointer to the last added entity.
Caller must ensure not to add an entity with an index that's already in the set.
Erase
Removes an entity from the set.
Caller must ensure that entity is actually part of the set.
Erase
Removes all entities from the provided iterator range from the set.
Caller must ensure that entity is actually part of the set.
EraseIfValid
Removes an entity from the set if it exists, otherwise does nothing.
Returns true if entity was removed.
EraseIfValid
Removes all existing entities from the provided iterator range from the set.
Ignores entities that are not part of the set. Returns number of entities that were removed.
Clear
Removes everything from the set and clears the internal arrays.
ClearInvalid
Removes all invalid entities from the set.
Only relevant for sets using in-place deletion policy.
Shrink
Shrinks the memory use of the set to accomodate the currently assigned entries, without any reserve for new entries.
Reserve
Reserves internal memory in order to fit entries.
Capacity
Returns how many entries can fit into the internal memory.
GetVersion
Returns the current version of the provided entity, or invalid version if entity is not part of this set.
UpdateVersion
Updates the version for the entity with identifier as specified by .
New version is taken from the provided parameter.
Find
Returns the iterator to an entity with the provided identifier and version.
Returns an iterator past the edge of the set if no entity is found.
Contains
Returns true if the set contains an entity with the provided identifier and version.
GetPackedIndex
Returns an index of an entity in the internal packed array.
If the entity is not part of the set, behaviour is undefined.
Size
Returns the number of entities in the set.
Note for in-place and swap-only deletion policies this will also count the number of invalid entries.
IsEmpty
Returns true if no entries are stored in the set.
Data
Returns raw pointer to the internal packed entity array.
Swap
Swaps the location of the provided entities in the packed array, as well as the relevant payload (data associated with the entities), if any.
GetDeletePolicy
Returns the current delete policy.
GetFirstFreeElementPackedIndex
When using in-place deletion policy returns the packed index to the first invalid element.
When using swap-only deletion policy returns the number of valid entities in the set. Not relevant if using swap-and-erase deletion policy.
Begin
Returns an iterator to the start of the internal packed entity array.
Cbegin
End
Returns an iterator to the past the end of the internal packed entity array.
Cend
Rbegin
Returns a reverse iterator to the last element of the internal packed entity array.
Crbegin
Rend
Returns a reverse iterator before the first element of the internal packed entity array.
Crend
begin
cbegin
end
cend
rbegin
crbegin
rend
crend
Fields
OnWasAdded
Triggers any time a new entity is added to the set.
OnWillRemove
Triggers right before an entity is removed from the set.
OnWasUpdated
Triggers when an existing component is updated or replaced.
Must be explicitly triggered by the caller.
Operators
operator[]
Protected
Methods
AddInternal
Adds a new entity to the set.
- entity
- Entity to add.
- forceAddAtEnd
- Only relevant when using in-place deletion policy. When true it will add an entity at the end of the packaged data array, rather than re-using the first available invalid entity entry.
Returns: Iterator to the added entity.
EraseInternal
Removed an entity from the sparse set.
Entity must be a part of the sparse set.
ClearInternal
Removes everything from the set and clears the internal arrays.
SwapEntities
Swaps the location of two entities.
- lhsPackedIndex
- Index within the packed array of the first element to swap.
- rhsPackedIndex
- Index within the packed array of the second element to swap.
GetOrCreateSparseEntryReference
Retrieves an existing entry from the sparse array, or adds a new entry if one doesn't already exist.
Note that returned entity is not a regular entity, but rather its identifier is an index into the packed array.
GetSparseEntryReference
Retrieves an existing entry from the sparse array.
Note that returned entity is not a regular entity, but rather its identifier is an index into the packed array. Caller must ensure the entity is part of the set before calling.
GetSparseEntryPointer
Attempts to retrieve an existing entry from the sparse array, or null if one cannot be found.
Note that returned entity is not a regular entity, but rather its identifier is an index into the packed array.
GetIterator
Returns an iterator to the provided entity.
Caller must ensure the entity is part of the set before calling.
FreeSparsePages
Frees any sparse pages that don't contain any entries.
staticGetPackedIndexAsEntryIdentifier
Converts an index into the packed array into an entity identifier.
staticGetSparseIndexWithinPage
Calculates an index within a page, for an entity with the provided identifier.
staticGetSparsePage
Calculates the page at which to store the entity with the provided identifier.
Fields
mSparseIndices
List of pages that map entity identifier into packed array indices.
mPackedEntities
Packed array of entities.