Flecs: Tables
Description: A fast entity component system (ECS) for C & C++

| Flecs v4.1 A fast entity component system (ECS) for C & C++

Loading...
Searching...
No Matches
Tables
C API » Core

Functions for working with ecs_table_t. More...

Collaboration diagram for Tables:

## Functions
const ecs_type_t * | ecs_table_get_type (const ecs_table_t *table)
| Get type for table.
int32_t | ecs_table_get_type_index (const ecs_world_t *world, const ecs_table_t *table, ecs_id_t component)
| Get type index for component.
int32_t | ecs_table_get_column_index (const ecs_world_t *world, const ecs_table_t *table, ecs_id_t component)
| Get column index for component.
int32_t | ecs_table_column_count (const ecs_table_t *table)
| Return number of columns in table.
int32_t | ecs_table_type_to_column_index (const ecs_table_t *table, int32_t index)
| Convert type index to column index.
int32_t | ecs_table_column_to_type_index (const ecs_table_t *table, int32_t index)
| Convert column index to type index.
void * | ecs_table_get_column (const ecs_table_t *table, int32_t index, int32_t offset)
| Get column from table by column index.
void * | ecs_table_get_id (const ecs_world_t *world, const ecs_table_t *table, ecs_id_t component, int32_t offset)
| Get column from table by component.
size_t | ecs_table_get_column_size (const ecs_table_t *table, int32_t index)
| Get column size from table.
int32_t | ecs_table_count (const ecs_table_t *table)
| Returns the number of entities in the table.
int32_t | ecs_table_size (const ecs_table_t *table)
| Returns allocated size of table.
const ecs_entity_t * | ecs_table_entities (const ecs_table_t *table)
| Returns array with entity ids for table.
bool | ecs_table_has_id (const ecs_world_t *world, const ecs_table_t *table, ecs_id_t component)
| Test if table has component.
ecs_entity_t | ecs_table_get_target (const ecs_world_t *world, const ecs_table_t *table, ecs_entity_t relationship, int32_t index)
| Get relationship target for table.
int32_t | ecs_table_get_depth (const ecs_world_t *world, const ecs_table_t *table, ecs_entity_t rel)
| Return depth for table in tree for relationship rel.
ecs_table_t * | ecs_table_add_id (ecs_world_t *world, ecs_table_t *table, ecs_id_t component)
| Get table that has all components of current table plus the specified id.
ecs_table_t * | ecs_table_find (ecs_world_t *world, const ecs_id_t *ids, int32_t id_count)
| Find table from id array.
ecs_table_t * | ecs_table_remove_id (ecs_world_t *world, ecs_table_t *table, ecs_id_t component)
| Get table that has all components of current table minus the specified component.
void | ecs_table_lock (ecs_world_t *world, ecs_table_t *table)
| Lock a table.
void | ecs_table_unlock (ecs_world_t *world, ecs_table_t *table)
| Unlock a table.
bool | ecs_table_has_flags (ecs_table_t *table, ecs_flags32_t flags)
| Test table for flags.
bool | ecs_table_has_traversable (const ecs_table_t *table)
| Check if table has traversable entities.
void | ecs_table_swap_rows (ecs_world_t *world, ecs_table_t *table, int32_t row_1, int32_t row_2)
| Swaps two elements inside the table.
bool | ecs_commit (ecs_world_t *world, ecs_entity_t entity, ecs_record_t *record, ecs_table_t *table, const ecs_type_t *added, const ecs_type_t *removed)
| Commit (move) entity to a table.
int32_t | ecs_search (const ecs_world_t *world, const ecs_table_t *table, ecs_id_t component, ecs_id_t *component_out)
| Search for component in table type.
int32_t | ecs_search_offset (const ecs_world_t *world, const ecs_table_t *table, int32_t offset, ecs_id_t component, ecs_id_t *component_out)
| Search for component in table type starting from an offset.
int32_t | ecs_search_relation (const ecs_world_t *world, const ecs_table_t *table, int32_t offset, ecs_id_t component, ecs_entity_t rel, ecs_flags64_t flags, ecs_entity_t *subject_out, ecs_id_t *component_out, struct ecs_table_record_t **tr_out)
| Search for component/relationship id in table type starting from an offset.
void | ecs_table_clear_entities (ecs_world_t *world, ecs_table_t *table)
| Remove all entities in a table.

## Detailed Description

Functions for working with ecs_table_t.

## Function Documentation

## ◆ ecs_commit()

bool ecs_commit | ( | ecs_world_t * | world,
|  | ecs_entity_t | entity,
|  | ecs_record_t * | record,
|  | ecs_table_t * | table,
|  | const ecs_type_t * | added,
|  | const ecs_type_t * | removed )

Commit (move) entity to a table.

This operation moves an entity from its current table to the specified table. This may cause the following actions:

- Ctor for each component in the target table
- Move for each overlapping component
- Dtor for each component in the source table.
- OnAdd triggers for non-overlapping components in the target table
- OnRemove triggers for non-overlapping components in the source table.

This operation is a faster than adding/removing components individually.

The application must explicitly provide the difference in components between tables as the added/removed parameters. This can usually be derived directly from the result of ecs_table_add_id() and ecs_table_remove_id(). These arrays are required to properly execute OnAdd/OnRemove triggers.

Parameters

  world | The world.
  entity | The entity to commit.
  record | The entity's record (optional, providing it saves a lookup).
  table | The table to commit the entity to.

Returns
  True if the entity got moved, false otherwise.

## ◆ ecs_search()

int32_t ecs_search | ( | const ecs_world_t * | world,
|  | const ecs_table_t * | table,
|  | ecs_id_t | component,
|  | ecs_id_t * | component_out )

Search for component in table type.

This operation returns the index of first occurrence of the component in the table type. The component may be a pair or wildcard.

When component_out is provided, the function will assign it with the found component. The found component may be different from the provided component if it is a wildcard.

This is a constant time operation.

Parameters

  world | The world.
  table | The table.
  component | The component to search for.
  component_out | If provided, it will be set to the found component (optional).

Returns
  The index of the id in the table type.

See also
  ecs_search_offset()
  ecs_search_relation()

## ◆ ecs_search_offset()

int32_t ecs_search_offset | ( | const ecs_world_t * | world,
|  | const ecs_table_t * | table,
|  | int32_t | offset,
|  | ecs_id_t | component,
|  | ecs_id_t * | component_out )

Search for component in table type starting from an offset.

This operation is the same as ecs_search(), but starts searching from an offset in the table type.

This operation is typically called in a loop where the resulting index is used in the next iteration as offset:

int32_t index = -1;
while ((index = ecs_search_offset(world, table, offset, id, NULL))) {
// do stuff
}
ecs_search_offset
int32_t ecs_search_offset(const ecs_world_t *world, const ecs_table_t *table, int32_t offset, ecs_id_t component, ecs_id_t *component_out)
Search for component in table type starting from an offset.

Depending on how the operation is used it is either linear or constant time. When the id has the form (id) or (rel, *) and the operation is invoked as in the above example, it is guaranteed to be constant time.

If the provided component has the form (*, tgt) the operation takes linear time. The reason for this is that ids for an target are not packed together, as they are sorted relationship first.

If the component at the offset does not match the provided id, the operation will do a linear search to find a matching id.

Parameters

  world | The world.
  table | The table.
  offset | Offset from where to start searching.
  component | The component to search for.
  component_out | If provided, it will be set to the found component (optional).

Returns
  The index of the id in the table type.

See also
  ecs_search()
  ecs_search_relation()

## ◆ ecs_search_relation()

int32_t ecs_search_relation | ( | const ecs_world_t * | world,
|  | const ecs_table_t * | table,
|  | int32_t | offset,
|  | ecs_id_t | component,
|  | ecs_entity_t | rel,
|  | ecs_flags64_t | flags,
|  | ecs_entity_t * | subject_out,
|  | ecs_id_t * | component_out,
|  | struct ecs_table_record_t ** | tr_out )

Search for component/relationship id in table type starting from an offset.

This operation is the same as ecs_search_offset(), but has the additional capability of traversing relationships to find a component. For example, if an application wants to find a component for either the provided table or a prefab (using the IsA relationship) of that table, it could use the operation like this:

int32_t index = ecs_search_relation(
world, // the world
table, // the table
0, // offset 0
ecs_id(Position), // the component id
EcsIsA, // the relationship to traverse
0, // start at depth 0 (the table itself)
0, // no depth limit
NULL, // (optional) entity on which component was found
NULL, // see above
NULL); // internal type with information about matched id
EcsIsA
const ecs_entity_t EcsIsA
Used to express inheritance relationships.
ecs_id
FLECS_API const ecs_entity_t ecs_id(EcsDocDescription)
Component id for EcsDocDescription.
ecs_search_relation
int32_t ecs_search_relation(const ecs_world_t *world, const ecs_table_t *table, int32_t offset, ecs_id_t component, ecs_entity_t rel, ecs_flags64_t flags, ecs_entity_t *subject_out, ecs_id_t *component_out, struct ecs_table_record_t **tr_out)
Search for component/relationship id in table type starting from an offset.

The operation searches depth first. If a table type has 2 IsA relationships, the operation will first search the IsA tree of the first relationship.

When choosing between ecs_search(), ecs_search_offset() and ecs_search_relation(), the simpler the function the better its performance.

Parameters

  world | The world.
  table | The table.
  offset | Offset from where to start searching.
  component | The component to search for.
  rel | The relationship to traverse (optional).
  flags | Whether to search EcsSelf and/or EcsUp.
  subject_out | If provided, it will be set to the matched entity.
  component_out | If provided, it will be set to the found component (optional).
  tr_out | Internal datatype.

Returns
  The index of the component in the table type.

See also
  ecs_search()
  ecs_search_offset()

## ◆ ecs_table_add_id()

ecs_table_t * ecs_table_add_id | ( | ecs_world_t * | world,
|  | ecs_table_t * | table,
|  | ecs_id_t | component )

Get table that has all components of current table plus the specified id.

If the provided table already has the provided id, the operation will return the provided table.

Parameters

  world | The world.
  table | The table.
  component | The component to add.

Returns
  The resulting table.

## ◆ ecs_table_clear_entities()

void ecs_table_clear_entities | ( | ecs_world_t * | world,
|  | ecs_table_t * | table )

Remove all entities in a table.

Does not deallocate table memory. Retaining table memory can be efficient when planning to refill the table with operations like ecs_bulk_init

Parameters

  world | The world.
  table | The table to clear.

## ◆ ecs_table_column_count()

int32_t ecs_table_column_count | ( | const ecs_table_t * | table | ) |

Return number of columns in table.

Similar to ecs_table_get_type(table)->count, except that the column count only counts the number of components in a table.

Parameters

  table | The table.

Returns
  The number of columns in the table.

## ◆ ecs_table_column_to_type_index()

int32_t ecs_table_column_to_type_index | ( | const ecs_table_t * | table,
|  | int32_t | index )

Convert column index to type index.

Same as ecs_table_type_to_column_index(), but converts from an index in the column array to an index in the table type.

Parameters

  table | The table.
  index | The column index.

Returns
  The index in the table type.

## ◆ ecs_table_count()

int32_t ecs_table_count | ( | const ecs_table_t * | table | ) |

Returns the number of entities in the table.

This operation returns the number of entities in the table.

Parameters

  table | The table.

Returns
  The number of entities in the table.

## ◆ ecs_table_entities()

const ecs_entity_t * ecs_table_entities | ( | const ecs_table_t * | table | ) |

Returns array with entity ids for table.

The size of the returned array is the result of ecs_table_count().

Parameters

  table | The table.

Returns
  Array with entity ids for table.

## ◆ ecs_table_find()

ecs_table_t * ecs_table_find | ( | ecs_world_t * | world,
|  | const ecs_id_t * | ids,
|  | int32_t | id_count )

Find table from id array.

This operation finds or creates a table with the specified array of (component) ids. The ids in the array must be sorted, and it may not contain duplicate elements.

Parameters

  world | The world.
  ids | The id array.
  id_count | The number of elements in the id array.

Returns
  The table with the specified (component) ids.

## ◆ ecs_table_get_column()

void * ecs_table_get_column | ( | const ecs_table_t * | table,
|  | int32_t | index,
|  | int32_t | offset )

Get column from table by column index.

This operation returns the component array for the provided index.

Parameters

  table | The table.
  index | The column index.
  offset | The index of the first row to return (0 for entire column).

Returns
  The component array, or NULL if the index is not a component.

## ◆ ecs_table_get_column_index()

int32_t ecs_table_get_column_index | ( | const ecs_world_t * | world,
|  | const ecs_table_t * | table,
|  | ecs_id_t | component )

Get column index for component.

This operation returns the column index for a component in the table's type. If the component doesn't have data (it is a tag), the function will return -1.

Parameters

  world | The world.
  table | The table.
  component | The component.

Returns
  The column index of the id, or -1 if not found/not a component.

## ◆ ecs_table_get_column_size()

size_t ecs_table_get_column_size | ( | const ecs_table_t * | table,
|  | int32_t | index )

Get column size from table.

This operation returns the component size for the provided index.

Parameters

  table | The table.
  index | The column index.

Returns
  The component size, or 0 if the index is not a component.

## ◆ ecs_table_get_depth()

int32_t ecs_table_get_depth | ( | const ecs_world_t * | world,
|  | const ecs_table_t * | table,
|  | ecs_entity_t | rel )

Return depth for table in tree for relationship rel.

Depth is determined by counting the number of targets encountered while traversing up the relationship tree for rel. Only acyclic relationships are supported.

Parameters

  world | The world.
  table | The table.
  rel | The relationship.

Returns
  The depth of the table in the tree.

## ◆ ecs_table_get_id()

void * ecs_table_get_id | ( | const ecs_world_t * | world,
|  | const ecs_table_t * | table,
|  | ecs_id_t | component,
|  | int32_t | offset )

Get column from table by component.

This operation returns the component array for the provided component.

Parameters

  world | The world.
  table | The table.
  component | The component for the column.
  offset | The index of the first row to return (0 for entire column).

Returns
  The component array, or NULL if the index is not a component.

## ◆ ecs_table_get_target()

ecs_entity_t ecs_table_get_target | ( | const ecs_world_t * | world,
|  | const ecs_table_t * | table,
|  | ecs_entity_t | relationship,
|  | int32_t | index )

Get relationship target for table.

Parameters

  world | The world.
  table | The table.
  relationship | The relationship for which to obtain the target.
  index | The index, in case the table has multiple instances of the relationship.

Returns
  The requested relationship target.

See also
  ecs_get_target()

## ◆ ecs_table_get_type()

const ecs_type_t * ecs_table_get_type | ( | const ecs_table_t * | table | ) |

Get type for table.

The table type is a vector that contains all component, tag and pair ids.

Parameters

  table | The table.

Returns
  The type of the table.

## ◆ ecs_table_get_type_index()

int32_t ecs_table_get_type_index | ( | const ecs_world_t * | world,
|  | const ecs_table_t * | table,
|  | ecs_id_t | component )

Get type index for component.

This operation returns the index for a component in the table's type.

Parameters

  world | The world.
  table | The table.
  component | The component.

Returns
  The index of the component in the table type, or -1 if not found.

See also
  ecs_table_has_id()

## ◆ ecs_table_has_flags()

bool ecs_table_has_flags | ( | ecs_table_t * | table,
|  | ecs_flags32_t | flags )

Test table for flags.

Test if table has all of the provided flags. See include/flecs/private/api_flags.h for a list of table flags that can be used with this function.

Parameters

  table | The table.
  flags | The flags to test for.

Returns
  Whether the specified flags are set for the table.

## ◆ ecs_table_has_id()

bool ecs_table_has_id | ( | const ecs_world_t * | world,
|  | const ecs_table_t * | table,
|  | ecs_id_t | component )

Test if table has component.

Same as ecs_table_get_type_index(world, table, component) != -1.

Parameters

  world | The world.
  table | The table.
  component | The component.

Returns
  True if the table has the id, false if the table doesn't.

See also
  ecs_table_get_type_index()

## ◆ ecs_table_has_traversable()

bool ecs_table_has_traversable | ( | const ecs_table_t * | table | ) |

Check if table has traversable entities.

Traversable entities are entities that are used as target in a pair with a relationship that has the Traversable trait.

Parameters

  table | The table.

Returns
  Whether the table has traversable entities.

## ◆ ecs_table_lock()

void ecs_table_lock | ( | ecs_world_t * | world,
|  | ecs_table_t * | table )

Lock a table.

When a table is locked, modifications to it will throw an assert. When the table is locked recursively, it will take an equal amount of unlock operations to actually unlock the table.

Table locks can be used to build safe iterators where it is guaranteed that the contents of a table are not modified while it is being iterated.

The operation only works when called on the world, and has no side effects when called on a stage. The assumption is that when called on a stage, operations are deferred already.

Parameters

  world | The world.
  table | The table to lock.

## ◆ ecs_table_remove_id()

ecs_table_t * ecs_table_remove_id | ( | ecs_world_t * | world,
|  | ecs_table_t * | table,
|  | ecs_id_t | component )

Get table that has all components of current table minus the specified component.

If the provided table doesn't have the provided component, the operation will return the provided table.

Parameters

  world | The world.
  table | The table.
  component | The component to remove.

Returns
  The resulting table.

## ◆ ecs_table_size()

int32_t ecs_table_size | ( | const ecs_table_t * | table | ) |

Returns allocated size of table.

This operation returns the number of elements allocated in the table per column.

Parameters

  table | The table.

Returns
  The number of allocated elements in the table.

## ◆ ecs_table_swap_rows()

void ecs_table_swap_rows | ( | ecs_world_t * | world,
|  | ecs_table_t * | table,
|  | int32_t | row_1,
|  | int32_t | row_2 )

Swaps two elements inside the table.

This is useful for implementing custom table sorting algorithms.

Parameters

  world | The world
  table | The table to swap elements in
  row_1 | Table element to swap with row_2
  row_2 | Table element to swap with row_1

## ◆ ecs_table_type_to_column_index()

int32_t ecs_table_type_to_column_index | ( | const ecs_table_t * | table,
|  | int32_t | index )

Convert type index to column index.

Tables have an array of columns for each component in the table. This array does not include elements for tags, which means that the index for a component in the table type is not necessarily the same as the index in the column array. This operation converts from an index in the table type to an index in the column array.

Parameters

  table | The table.
  index | The index in the table type.

Returns
  The index in the table column array.

See also
  ecs_table_column_to_type_index()

## ◆ ecs_table_unlock()

void ecs_table_unlock | ( | ecs_world_t * | world,
|  | ecs_table_t * | table )

Unlock a table.

Must be called after calling ecs_table_lock().

Parameters

  world | The world.
  table | The table to unlock.