Function ecs_query_init

Synopsis

#include <include/flecs.h>

FLECS_API ecs_query_t * ecs_query_init(ecs_world_t *world, const ecs_query_desc_t *desc)

Description

Create a query. This operation creates a query. Queries are used to iterate over entities that match a filter and are the fastest way to find and iterate over entities and their components.

Queries should be created once, and reused multiple times. While iterating a query is a cheap operation, creating and deleting a query is expensive. The reason for this is that queries are "prematched", which means that a query stores state about which entities (or rather, tables) match with the query. Building up this state happens during query creation.

Once a query is created, matching only happens when new tables are created. In most applications this is an infrequent process, since it only occurs when a new combination of components is introduced. While matching is expensive, it is importent to note that matching does not happen on a per-entity basis, but on a per-table basis. This means that the average time spent on matching per frame should rapidly approach zero over the lifetime of an application.

A query provides direct access to the component arrays. When an application creates/deletes entities or adds/removes components, these arrays can shift component values around, or may grow in size. This can cause unexpected or undefined behavior to occur if these operations are performed while iterating. To prevent this from happening an application should either not perform these operations while iterating, or use deferred operations (see ecs_defer_begin and ecs_defer_end).

Queries can be created and deleted dynamically. If a query was not deleted (using ecs_query_fini) before the world is deleted, it will be deleted automatically.

Parameters

world - The world.

desc - A structure describing the query properties.

Returns
The new query.

Mentioned in

Source

Line 2640 in include/flecs.h.