Flecs v3.1
A fast entity component system (ECS) for C & C++
Loading...
Searching...
No Matches
Tables

Functions for working with ecs_table_t. More...

Functions

const ecs_type_tecs_table_get_type (const ecs_table_t *table)
 Get type for table. More...
 
void * ecs_table_get_column (const ecs_table_t *table, int32_t index, int32_t offset)
 Get column from table. More...
 
int32_t ecs_table_get_index (const ecs_world_t *world, const ecs_table_t *table, ecs_id_t id)
 Get column index for id. More...
 
void * ecs_table_get_id (const ecs_world_t *world, const ecs_table_t *table, ecs_id_t id, int32_t offset)
 Get column from table by component id. More...
 
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. More...
 
ecs_table_tecs_table_get_storage_table (const ecs_table_t *table)
 Get storage type for table. More...
 
int32_t ecs_table_type_to_storage_index (const ecs_table_t *table, int32_t index)
 Convert index in table type to index in table storage type.
 
int32_t ecs_table_storage_to_type_index (const ecs_table_t *table, int32_t index)
 Convert index in table storage type to index in table type.
 
int32_t ecs_table_count (const ecs_table_t *table)
 Returns the number of records in the table. More...
 
ecs_table_tecs_table_add_id (ecs_world_t *world, ecs_table_t *table, ecs_id_t id)
 Get table that has all components of current table plus the specified id. More...
 
ecs_table_tecs_table_remove_id (ecs_world_t *world, ecs_table_t *table, ecs_id_t id)
 Get table that has all components of current table minus the specified id. More...
 
void ecs_table_lock (ecs_world_t *world, ecs_table_t *table)
 Lock or unlock table. More...
 
void ecs_table_unlock (ecs_world_t *world, ecs_table_t *table)
 Unlock a table. More...
 
bool ecs_table_has_module (ecs_table_t *table)
 Returns whether table is a module or contains module contents Returns true for tables that have module contents. More...
 
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. More...
 
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. More...
 
ecs_record_t * ecs_record_find (const ecs_world_t *world, ecs_entity_t entity)
 Find record for entity.
 
void * ecs_record_get_column (const ecs_record_t *r, int32_t column, size_t c_size)
 Get component pointer from column/record.
 
int32_t ecs_search (const ecs_world_t *world, const ecs_table_t *table, ecs_id_t id, ecs_id_t *id_out)
 Search for component id in table type. More...
 
int32_t ecs_search_offset (const ecs_world_t *world, const ecs_table_t *table, int32_t offset, ecs_id_t id, ecs_id_t *id_out)
 Search for component id in table type starting from an offset. More...
 
int32_t ecs_search_relation (const ecs_world_t *world, const ecs_table_t *table, int32_t offset, ecs_id_t id, ecs_entity_t rel, ecs_flags32_t flags, ecs_entity_t *subject_out, ecs_id_t *id_out, struct ecs_table_record_t **tr_out)
 Search for component/relationship id in table type starting from an offset. More...
 

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 esc_table_remove_id. These arrays are required to properly execute OnAdd/OnRemove triggers.

Parameters
worldThe world.
entityThe entity to commit.
recordThe entity's record (optional, providing it saves a lookup).
tableThe 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  id,
ecs_id_t id_out 
)

Search for component id in table type.

This operation returns the index of first occurrance of the id in the table type. The id may be a wildcard.

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

This is a constant time operation.

Parameters
worldThe world.
tableThe table.
idThe id to search for.
id_outIf provided, it will be set to the found id (optional).
Returns
The index of the id in the table type.

◆ ecs_search_offset()

int32_t ecs_search_offset ( const ecs_world_t world,
const ecs_table_t table,
int32_t  offset,
ecs_id_t  id,
ecs_id_t id_out 
)

Search for component id 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 }

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 id 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 id at the offset does not match the provided id, the operation will do a linear search to find a matching id.

Parameters
worldThe world.
tableThe table.
offsetOffset from where to start searching.
idThe id to search for.
id_outIf provided, it will be set to the found id (optional).
Returns
The index of the id in the table type.

◆ ecs_search_relation()

int32_t ecs_search_relation ( const ecs_world_t world,
const ecs_table_t table,
int32_t  offset,
ecs_id_t  id,
ecs_entity_t  rel,
ecs_flags32_t  flags,
ecs_entity_t subject_out,
ecs_id_t id_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

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 betwen ecs_search, ecs_search_offset and ecs_search_relation, the simpler the function the better its performance.

Parameters
worldThe world.
tableThe table.
offsetOffset from where to start searching.
idThe id to search for.
relThe relationship to traverse (optional).
flagsWhether to search EcsSelf and/or EcsUp.
subject_outIf provided, it will be set to the matched entity.
id_outIf provided, it will be set to the found id (optional).
tr_outInternal datatype.
Returns
The index of the id in the table type.

◆ ecs_table_add_id()

ecs_table_t * ecs_table_add_id ( ecs_world_t world,
ecs_table_t table,
ecs_id_t  id 
)

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
worldThe world.
tableThe table.
idThe id to add.
Returns
The resulting table.

◆ ecs_table_count()

int32_t ecs_table_count ( const ecs_table_t table)

Returns the number of records in the table.

This operation returns the number of records that have been populated through the regular (entity) API as well as the number of records that have been inserted using the direct access API.

Parameters
tableThe table.
Returns
The number of records in a table.

◆ ecs_table_get_column()

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

Get column from table.

This operation returns the component array for the provided index.

Parameters
tableThe table.
indexThe index of the column (corresponds with element in type).
offsetThe 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_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
worldThe world.
tableThe table.
relThe 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  id,
int32_t  offset 
)

Get column from table by component id.

This operation returns the component array for the provided component id.

Parameters
tableThe table.
idThe component id for the column.
offsetThe 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_index()

int32_t ecs_table_get_index ( const ecs_world_t world,
const ecs_table_t table,
ecs_id_t  id 
)

Get column index for id.

This operation returns the index for an id in the table's type.

Parameters
worldThe world.
tableThe table.
idThe id.
Returns
The index of the id in the table type, or -1 if not found.

◆ ecs_table_get_storage_table()

ecs_table_t * ecs_table_get_storage_table ( const ecs_table_t table)

Get storage type for table.

Parameters
tableThe table.
Returns
The storage type of the table (components only).

◆ ecs_table_get_type()

const ecs_type_t * ecs_table_get_type ( const ecs_table_t table)

Get type for table.

Parameters
tableThe table.
Returns
The type of the table.

◆ ecs_table_has_module()

bool ecs_table_has_module ( ecs_table_t table)

Returns whether table is a module or contains module contents Returns true for tables that have module contents.

Can be used to filter out tables that do not contain application data.

Parameters
tableThe table.
Returns
true if table contains module contents, false if not.

◆ ecs_table_lock()

void ecs_table_lock ( ecs_world_t world,
ecs_table_t table 
)

Lock or unlock 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
worldThe world.
tableThe 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  id 
)

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

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

Parameters
worldThe world.
tableThe table.
idThe id to remove.
Returns
The resulting 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
worldThe world
tableThe table to swap elements in
row_1Table element to swap with row_2
row_2Table element to swap with row_1

◆ 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
worldThe world.
tableThe table to unlock.