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

Functions for working with ecs_term_t and ecs_filter_t. More...

Classes

struct  ecs_filter_desc_t
 Used with ecs_filter_init. More...
 

Typedefs

typedef struct ecs_filter_desc_t ecs_filter_desc_t
 Used with ecs_filter_init.
 

Functions

ecs_iter_t ecs_term_iter (const ecs_world_t *world, ecs_term_t *term)
 Iterator for a single (component) id. More...
 
ecs_iter_t ecs_term_chain_iter (const ecs_iter_t *it, ecs_term_t *term)
 Return a chained term iterator. More...
 
bool ecs_term_next (ecs_iter_t *it)
 Progress a term iterator. More...
 
ecs_iter_t ecs_children (const ecs_world_t *world, ecs_entity_t parent)
 Iterator for a parent's children. More...
 
bool ecs_children_next (ecs_iter_t *it)
 Progress a children iterator. More...
 
bool ecs_term_id_is_set (const ecs_term_id_t *id)
 Test whether term id is set. More...
 
bool ecs_term_is_initialized (const ecs_term_t *term)
 Test whether a term is set. More...
 
bool ecs_term_match_this (const ecs_term_t *term)
 
bool ecs_term_match_0 (const ecs_term_t *term)
 
int ecs_term_finalize (const ecs_world_t *world, ecs_term_t *term)
 Finalize term. More...
 
ecs_term_t ecs_term_copy (const ecs_term_t *src)
 Copy resources of a term to another term. More...
 
ecs_term_t ecs_term_move (ecs_term_t *src)
 Move resources of a term to another term. More...
 
void ecs_term_fini (ecs_term_t *term)
 Free resources of term. More...
 
ecs_filter_tecs_filter_init (ecs_world_t *world, const ecs_filter_desc_t *desc)
 Initialize filter A filter is a lightweight object that can be used to query for entities in a world. More...
 
void ecs_filter_fini (ecs_filter_t *filter)
 Deinitialize filter. More...
 
int ecs_filter_finalize (const ecs_world_t *world, ecs_filter_t *filter)
 Finalize filter. More...
 
int32_t ecs_filter_find_this_var (const ecs_filter_t *filter)
 Find index for This variable. More...
 
char * ecs_term_str (const ecs_world_t *world, const ecs_term_t *term)
 Convert ter, to string expression. More...
 
char * ecs_filter_str (const ecs_world_t *world, const ecs_filter_t *filter)
 Convert filter to string expression. More...
 
ecs_iter_t ecs_filter_iter (const ecs_world_t *world, const ecs_filter_t *filter)
 Return a filter iterator. More...
 
ecs_iter_t ecs_filter_chain_iter (const ecs_iter_t *it, const ecs_filter_t *filter)
 Return a chained filter iterator. More...
 
int32_t ecs_filter_pivot_term (const ecs_world_t *world, const ecs_filter_t *filter)
 Get pivot term for filter. More...
 
bool ecs_filter_next (ecs_iter_t *it)
 Iterate tables matched by filter. More...
 
bool ecs_filter_next_instanced (ecs_iter_t *it)
 Same as ecs_filter_next, but always instanced. More...
 
void ecs_filter_move (ecs_filter_t *dst, ecs_filter_t *src)
 Move resources of one filter to another.
 
void ecs_filter_copy (ecs_filter_t *dst, const ecs_filter_t *src)
 Copy resources of one filter to another.
 

Detailed Description

Functions for working with ecs_term_t and ecs_filter_t.

Function Documentation

◆ ecs_children()

ecs_iter_t ecs_children ( const ecs_world_t world,
ecs_entity_t  parent 
)

Iterator for a parent's children.

This operation is equivalent to a term iterator for (ChildOf, parent). Iterate the result with ecs_children_next.

Parameters
worldThe world.
parentThe parent for which to iterate the children.
Returns
The iterator.

◆ ecs_children_next()

bool ecs_children_next ( ecs_iter_t *  it)

Progress a children iterator.

Equivalent to ecs_term_next.

Parameters
itThe iterator.
Returns
True if more data is available, false if not.

◆ ecs_filter_chain_iter()

ecs_iter_t ecs_filter_chain_iter ( const ecs_iter_t *  it,
const ecs_filter_t filter 
)

Return a chained filter iterator.

A chained iterator applies a filter to the results of the input iterator. The resulting iterator must be iterated with ecs_filter_next.

Parameters
itThe input iterator
filterThe filter to apply to the iterator.
Returns
The chained iterator.

◆ ecs_filter_finalize()

int ecs_filter_finalize ( const ecs_world_t world,
ecs_filter_t filter 
)

Finalize filter.

When manually assigning an array of terms to the filter struct (so not when using ecs_filter_init), this operation should be used to ensure that all terms are assigned properly and all (derived) fields have been set.

When ecs_filter_init is used to create the filter, this function should not be called. The purpose of this operation is to support creation of filters without allocating memory.

Parameters
filterThe filter to finalize.
Returns
Zero if filter is valid, non-zero if it contains errors. @

◆ ecs_filter_find_this_var()

int32_t ecs_filter_find_this_var ( const ecs_filter_t filter)

Find index for This variable.

This operation looks up the index of the This variable. This index can be used in operations like ecs_iter_set_var and ecs_iter_get_var.

The operation will return -1 if the variable was not found. This happens when a filter only has terms that are not matched on the This variable, like a filter that exclusively matches singleton components.

Parameters
filterThe rule.
Returns
The index of the This variable.

◆ ecs_filter_fini()

void ecs_filter_fini ( ecs_filter_t filter)

Deinitialize filter.

Free resources associated with filter.

Parameters
filterThe filter to deinitialize.

◆ ecs_filter_init()

ecs_filter_t * ecs_filter_init ( ecs_world_t world,
const ecs_filter_desc_t desc 
)

Initialize filter A filter is a lightweight object that can be used to query for entities in a world.

Filters, as opposed to queries, do not cache results. They are therefore slower to iterate, but are faster to create.

When a filter is copied by value, make sure to use "ecs_filter_move" to ensure that the terms pointer still points to the inline array:

ecs_filter_move(&dst_filter, &src_filter)

Alternatively, the ecs_filter_move function can be called with both arguments set to the same filter, to ensure the pointer is valid:

ecs_filter_move(&f, &f)

It is possible to create a filter without allocating any memory, by setting the .storage member in ecs_filter_desc_t. See the documentation for the member for more details.

Parameters
worldThe world.
descProperties for the filter to create.
Returns
The filter if successful, NULL if not successful.

◆ ecs_filter_iter()

ecs_iter_t ecs_filter_iter ( const ecs_world_t world,
const ecs_filter_t filter 
)

Return a filter iterator.

A filter iterator lets an application iterate over entities that match the specified filter. If NULL is provided for the filter, the iterator will iterate all tables in the world.

Parameters
worldThe world.
filterThe filter.
Returns
An iterator that can be used with ecs_filter_next.

◆ ecs_filter_next()

bool ecs_filter_next ( ecs_iter_t *  it)

Iterate tables matched by filter.

This operation progresses the filter iterator to the next table. The iterator must have been initialized with ecs_filter_iter. This operation must be invoked at least once before interpreting the contents of the iterator.

Parameters
itThe iterator
Returns
True if more data is available, false if not.

◆ ecs_filter_next_instanced()

bool ecs_filter_next_instanced ( ecs_iter_t *  it)

Same as ecs_filter_next, but always instanced.

See instanced property of ecs_filter_desc_t.

◆ ecs_filter_pivot_term()

int32_t ecs_filter_pivot_term ( const ecs_world_t world,
const ecs_filter_t filter 
)

Get pivot term for filter.

The pivot term is the term that matches the smallest set of tables, and is a good default starting point for a search.

The following conditions must be met for a term to be considered as pivot:

  • It must have a This subject
  • It must have the And operator

When a filter does not have any terms that match those conditions, it will return -1.

If one or more terms in the filter have no matching tables the filter won't yield any results. In this case the operation will return -2 which gives a search function the option to early out.

Parameters
worldThe world.
filterThe filter.
Returns
Index of the pivot term (use with filter->terms)

◆ ecs_filter_str()

char * ecs_filter_str ( const ecs_world_t world,
const ecs_filter_t filter 
)

Convert filter to string expression.

Convert filter terms to a string expression. The resulting expression can be parsed to create the same filter.

◆ ecs_term_chain_iter()

ecs_iter_t ecs_term_chain_iter ( const ecs_iter_t *  it,
ecs_term_t term 
)

Return a chained term iterator.

A chained iterator applies a filter to the results of the input iterator. The resulting iterator must be iterated with ecs_term_next.

Parameters
itThe input iterator
termThe term filter to apply to the iterator.
Returns
The chained iterator.

◆ ecs_term_copy()

ecs_term_t ecs_term_copy ( const ecs_term_t src)

Copy resources of a term to another term.

This operation copies one term to another term. If the source term contains allocated resources (such as identifiers), they will be duplicated so that no memory is shared between the terms.

Parameters
srcThe term to copy from.
Returns
The destination term.

◆ ecs_term_finalize()

int ecs_term_finalize ( const ecs_world_t world,
ecs_term_t term 
)

Finalize term.

Ensure that all fields of a term are consistent and filled out. This operation should be invoked before using and after assigning members to, or parsing a term. When a term contains unresolved identifiers, this operation will resolve and assign the identifiers. If the term contains any identifiers that cannot be resolved, the operation will fail.

An application generally does not need to invoke this operation as the APIs that use terms (such as filters, queries and triggers) will finalize terms when they are created.

The name and expr parameters are optional, and only used for giving more descriptive error messages.

Parameters
worldThe world.
termThe term to finalize.
Returns
Zero if success, nonzero if an error occurred.

◆ ecs_term_fini()

void ecs_term_fini ( ecs_term_t term)

Free resources of term.

This operation frees all resources (such as identifiers) of a term. The term itself is not freed.

Parameters
termThe term to free.

◆ ecs_term_id_is_set()

bool ecs_term_id_is_set ( const ecs_term_id_t id)

Test whether term id is set.

Parameters
idThe term id.
Returns
True when set, false when not set.

◆ ecs_term_is_initialized()

bool ecs_term_is_initialized ( const ecs_term_t term)

Test whether a term is set.

This operation can be used to test whether a term has been initialized with values or whether it is empty.

An application generally does not need to invoke this operation. It is useful when initializing a 0-initialized array of terms (like in ecs_term_desc_t) as this operation can be used to find the last initialized element.

Parameters
termThe term.
Returns
True when set, false when not set.

◆ ecs_term_iter()

ecs_iter_t ecs_term_iter ( const ecs_world_t world,
ecs_term_t term 
)

Iterator for a single (component) id.

A term iterator returns all entities (tables) that match a single (component) id. The search for the matching set of entities (tables) is performed in constant time.

Parameters
worldThe world.
termThe term.
Returns
The iterator.

◆ ecs_term_move()

ecs_term_t ecs_term_move ( ecs_term_t src)

Move resources of a term to another term.

Same as copy, but moves resources from src, if src->move is set to true. If src->move is not set to true, this operation will do a copy.

The conditional move reduces redundant allocations in scenarios where a list of terms is partially created with allocated resources.

Parameters
srcThe term to move from.
Returns
The destination term.

◆ ecs_term_next()

bool ecs_term_next ( ecs_iter_t *  it)

Progress a term iterator.

This operation progresses the term iterator to the next table. The iterator must have been initialized with ecs_term_iter. This operation must be invoked at least once before interpreting the contents of the iterator.

Parameters
itThe iterator.
Returns
True if more data is available, false if not.

◆ ecs_term_str()

char * ecs_term_str ( const ecs_world_t world,
const ecs_term_t term 
)

Convert ter, to string expression.

Convert term to a string expression. The resulting expression is equivalent to the same term, with the exception of And & Or operators.