 |
Flecs v3.2
A fast entity component system (ECS) for C & C++
|
|
Flecs v3.2
A fast entity component system (ECS) for C & C++
|
Functions | |
| bool | ecs_readonly_begin (ecs_world_t *world) |
| Begin readonly mode. More... | |
| void | ecs_readonly_end (ecs_world_t *world) |
| End readonly mode. More... | |
| void | ecs_merge (ecs_world_t *world) |
| Merge world or stage. More... | |
| bool | ecs_defer_begin (ecs_world_t *world) |
| Defer operations until end of frame. More... | |
| bool | ecs_is_deferred (const ecs_world_t *world) |
| Test if deferring is enabled for current stage. More... | |
| bool | ecs_defer_end (ecs_world_t *world) |
| End block of operations to defer. More... | |
| void | ecs_defer_suspend (ecs_world_t *world) |
| Suspend deferring but do not flush queue. More... | |
| void | ecs_defer_resume (ecs_world_t *world) |
| Resume deferring. More... | |
| void | ecs_set_automerge (ecs_world_t *world, bool automerge) |
| Enable/disable automerging for world or stage. More... | |
| void | ecs_set_stage_count (ecs_world_t *world, int32_t stages) |
| Configure world to have N stages. More... | |
| int32_t | ecs_get_stage_count (const ecs_world_t *world) |
| Get number of configured stages. More... | |
| int32_t | ecs_get_stage_id (const ecs_world_t *world) |
| Get current stage id. More... | |
| ecs_world_t * | ecs_get_stage (const ecs_world_t *world, int32_t stage_id) |
| Get stage-specific world pointer. More... | |
| bool | ecs_stage_is_readonly (const ecs_world_t *world) |
| Test whether the current world is readonly. More... | |
| ecs_world_t * | ecs_async_stage_new (ecs_world_t *world) |
| Create asynchronous stage. More... | |
| void | ecs_async_stage_free (ecs_world_t *stage) |
| Free asynchronous stage. More... | |
| bool | ecs_stage_is_async (ecs_world_t *stage) |
| Test whether provided stage is asynchronous. More... | |
| void ecs_async_stage_free | ( | ecs_world_t * | stage | ) |
Free asynchronous stage.
The provided stage must be an asynchronous stage. If a non-asynchronous stage is provided, the operation will fail.
| stage | The stage to free. |
| ecs_world_t * ecs_async_stage_new | ( | ecs_world_t * | world | ) |
Create asynchronous stage.
An asynchronous stage can be used to asynchronously queue operations for later merging with the world. An asynchronous stage is similar to a regular stage, except that it does not allow reading from the world.
Asynchronous stages are never merged automatically, and must therefore be manually merged with the ecs_merge function. It is not necessary to call defer_begin or defer_end before and after enqueuing commands, as an asynchronous stage unconditionally defers operations.
The application must ensure that no commands are added to the stage while the stage is being merged.
An asynchronous stage must be cleaned up by ecs_async_stage_free.
| world | The world. |
| bool ecs_defer_begin | ( | ecs_world_t * | world | ) |
Defer operations until end of frame.
When this operation is invoked while iterating, operations inbetween the defer_begin and defer_end operations are executed at the end of the frame.
This operation is thread safe.
| world | The world. |
| bool ecs_defer_end | ( | ecs_world_t * | world | ) |
End block of operations to defer.
See defer_begin.
This operation is thread safe.
| world | The world. |
| void ecs_defer_resume | ( | ecs_world_t * | world | ) |
Resume deferring.
See ecs_defer_suspend.
| world | The world. |
| void ecs_defer_suspend | ( | ecs_world_t * | world | ) |
Suspend deferring but do not flush queue.
This operation can be used to do an undeferred operation while not flushing the operations in the queue.
An application should invoke ecs_defer_resume before ecs_defer_end is called. The operation may only be called when deferring is enabled.
| world | The world. |
| ecs_world_t * ecs_get_stage | ( | const ecs_world_t * | world, |
| int32_t | stage_id | ||
| ) |
Get stage-specific world pointer.
Flecs threads can safely invoke the API as long as they have a private context to write to, also referred to as the stage. This function returns a pointer to a stage, disguised as a world pointer.
Note that this function does not(!) create a new world. It simply wraps the existing world in a thread-specific context, which the API knows how to unwrap. The reason the stage is returned as an ecs_world_t is so that it can be passed transparently to the existing API functions, vs. having to create a dediated API for threading.
| world | The world. |
| stage_id | The index of the stage to retrieve. |
| int32_t ecs_get_stage_count | ( | const ecs_world_t * | world | ) |
Get number of configured stages.
Return number of stages set by ecs_set_stage_count.
| world | The world. |
| int32_t ecs_get_stage_id | ( | const ecs_world_t * | world | ) |
Get current stage id.
The stage id can be used by an application to learn about which stage it is using, which typically corresponds with the worker thread id.
| world | The world. |
| bool ecs_is_deferred | ( | const ecs_world_t * | world | ) |
Test if deferring is enabled for current stage.
| world | The world. |
| void ecs_merge | ( | ecs_world_t * | world | ) |
Merge world or stage.
When automatic merging is disabled, an application can call this operation on either an individual stage, or on the world which will merge all stages. This operation may only be called when staging is not enabled (either after progress() or after readonly_end()).
This operation may be called on an already merged stage or world.
| world | The world. |
| bool ecs_readonly_begin | ( | ecs_world_t * | world | ) |
Begin readonly mode.
Readonly mode guarantees that no mutations will occur on the world, which makes the world safe to access from multiple threads. While the world is in readonly mode, operations are deferred.
Note that while similar to ecs_defer_begin, deferring only does not guarantee the world is not mutated. Operations that are not deferred (like creating a query) update data structures on the world and are allowed when deferring is enabled, but not when the world is in readonly mode.
A call to ecs_readonly_begin must be followed up with ecs_readonly_end.
The ecs_progress() function automatically enables readonly mode while systems are executed.
When a world has more than one stage, the specific stage must be provided to mutating ECS operations. Failing to do so will throw a readonly assert. A world typically has more than one stage when using threads. An example:
ecs_set_stage_count(world, 2); ecs_stage_t *stage = ecs_get_stage(world, 1);
ecs_readonly_begin(world); ecs_add(world, e, Tag); // readonly assert ecs_add(stage, e, Tag); // OK
| world | The world |
| void ecs_readonly_end | ( | ecs_world_t * | world | ) |
End readonly mode.
This operation ends readonly mode, and must be called after ecs_readonly_begin. Operations that were deferred while the world was in readonly mode will be flushed.
| world | The world |
| void ecs_set_automerge | ( | ecs_world_t * | world, |
| bool | automerge | ||
| ) |
Enable/disable automerging for world or stage.
When automerging is enabled, staged data will automatically be merged with the world when staging ends. This happens at the end of progress(), at a sync point or when readonly_end() is called.
Applications can exercise more control over when data from a stage is merged by disabling automerging. This requires an application to explicitly call merge() on the stage.
When this function is invoked on the world, it sets all current stages to the provided value and sets the default for new stages. When this function is invoked on a stage, automerging is only set for that specific stage.
| world | The world. |
| automerge | Whether to enable or disable automerging. |
| void ecs_set_stage_count | ( | ecs_world_t * | world, |
| int32_t | stages | ||
| ) |
Configure world to have N stages.
This initializes N stages, which allows applications to defer operations to multiple isolated defer queues. This is typically used for applications with multiple threads, where each thread gets its own queue, and commands are merged when threads are synchronized.
Note that the ecs_set_threads function already creates the appropriate number of stages. The set_stage_count() operation is useful for applications that want to manage their own stages and/or threads.
| world | The world. |
| stages | The number of stages. |
| bool ecs_stage_is_async | ( | ecs_world_t * | stage | ) |
Test whether provided stage is asynchronous.
| stage | The stage. |
| bool ecs_stage_is_readonly | ( | const ecs_world_t * | world | ) |
Test whether the current world is readonly.
This function allows the code to test whether the currently used world is readonly or whether it allows for writing.
| world | A pointer to a stage or the world. |