Filters

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

Collaboration diagram for Filters:

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.
ecs_iter_t	ecs_term_chain_iter (const ecs_iter_t *it, ecs_term_t *term)
	Return a chained term iterator.
bool	ecs_term_next (ecs_iter_t *it)
	Progress a term iterator.
ecs_iter_t	ecs_children (const ecs_world_t *world, ecs_entity_t parent)
	Iterator for a parent's children.
bool	ecs_children_next (ecs_iter_t *it)
	Progress a children iterator.
bool	ecs_term_id_is_set (const ecs_term_id_t *id)
	Test whether term id is set.
bool	ecs_term_is_initialized (const ecs_term_t *term)
	Test whether a term is set.
bool	ecs_term_match_this (const ecs_term_t *term)
	Is term matched on $this variable.
bool	ecs_term_match_0 (const ecs_term_t *term)
	Is term matched on 0 source.
int	ecs_term_finalize (const ecs_world_t *world, ecs_term_t *term)
	Finalize term.
ecs_term_t	ecs_term_copy (const ecs_term_t *src)
	Copy resources of a term to another term.
ecs_term_t	ecs_term_move (ecs_term_t *src)
	Move resources of a term to another term.
void	ecs_term_fini (ecs_term_t *term)
	Free resources of term.
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.
void	ecs_filter_fini (ecs_filter_t *filter)
	Deinitialize filter.
int	ecs_filter_finalize (const ecs_world_t *world, ecs_filter_t *filter)
	Finalize filter.
int32_t	ecs_filter_find_this_var (const ecs_filter_t *filter)
	Find index for $this variable.
char *	ecs_term_str (const ecs_world_t *world, const ecs_term_t *term)
	Convert term to string expression.
char *	ecs_filter_str (const ecs_world_t *world, const ecs_filter_t *filter)
	Convert filter to string expression.
ecs_iter_t	ecs_filter_iter (const ecs_world_t *world, const ecs_filter_t *filter)
	Return a filter iterator.
ecs_iter_t	ecs_filter_chain_iter (const ecs_iter_t *it, const ecs_filter_t *filter)
	Return a chained filter iterator.
int32_t	ecs_filter_pivot_term (const ecs_world_t *world, const ecs_filter_t *filter)
	Get pivot term for filter.
bool	ecs_filter_next (ecs_iter_t *it)
	Iterate tables matched by filter.
bool	ecs_filter_next_instanced (ecs_iter_t *it)
	Same as ecs_filter_next, but always instanced.
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

world	The world.
parent	The 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

it	The 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

it	The input iterator
filter	The filter to apply to the iterator.

Returns

The chained iterator.

ecs_filter_copy()

void ecs_filter_copy	(	ecs_filter_t *	dst,
		const ecs_filter_t *	src )

Copy resources of one filter to another.

Parameters

dst	The destination filter.
src	The source filter.

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

filter

The 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

filter

The 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

filter

The 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

world	The world.
desc	Properties 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.

Parameters

world	The world.
filter	The filter.

Returns

An iterator that can be used with ecs_filter_next().

ecs_filter_move()

void ecs_filter_move	(	ecs_filter_t *	dst,
		ecs_filter_t *	src )

Move resources of one filter to another.

Parameters

dst	The destination filter.
src	The source filter.

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

it	The 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.

Parameters

it	The iterator

Returns

True if more data is available, false if not.

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

world	The world.
filter	The 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.

Parameters

world	The world.
filter	The filter.

Returns

The filter converted to a string.

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

it	The input iterator
term	The 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

src	The 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

world	The world.
term	The 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

term	The 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

id	The 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

term

The 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

world	The world.
term	The term.

Returns

The iterator.

ecs_term_match_0()

bool ecs_term_match_0

(

const ecs_term_t *

term

)

Is term matched on 0 source.

This operation checks whether a term is matched on a 0 source. A 0 source is a term that isn't matched against anything, and can be used just to pass (component) ids to a query iterator.

A term has a 0 source when:

• ecs_term_t::src::id is 0
• ecs_term_t::src::flags has EcsIsEntity set

Parameters

term

The term.

Returns

True if term has 0 source, false if not.

ecs_term_match_this()

bool ecs_term_match_this

(

const ecs_term_t *

term

)

Is term matched on $this variable.

This operation checks whether a term is matched on the $this variable, which is the default source for queries.

A term has a $this source when:

• ecs_term_t::src::id is EcsThis
• ecs_term_t::src::flags is EcsIsVariable

If ecs_term_t::src is not populated, it will be automatically initialized to the $this source for the created query.

Parameters

term

The term.

Returns

True if term matches $this, false if not.

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

src	The 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

it	The 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 term 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.

Parameters

world	The world.
term	The term.

Returns

The term converted to a string.