Flecs: Pipeline
Description: A fast entity component system (ECS) for C & C++

| Flecs v4.0 A fast entity component system (ECS) for C & C++

Loading...
Searching...
No Matches
Classes | Macros | Typedefs | Functions
Pipeline
C API » Addons

Pipelines order and schedule systems for execution. More...

Collaboration diagram for Pipeline:

## Classes
struct | ecs_pipeline_desc_t
| Pipeline descriptor, used with ecs_pipeline_init(). More...

## Macros
#define | FLECS_PIPELINE_H
#define | ECS_PIPELINE_DEFINE(world, id_, ...)
| Convenience macro to create a predeclared pipeline.
#define | ECS_PIPELINE(world, id, ...)
| Convenience macro to create a pipeline.
#define | ecs_pipeline(world, ...)
| Convenience macro to create a pipeline.

## Typedefs
typedef struct ecs_pipeline_desc_t | ecs_pipeline_desc_t
| Pipeline descriptor, used with ecs_pipeline_init().

## Functions
FLECS_API ecs_entity_t | ecs_pipeline_init (ecs_world_t *world, const ecs_pipeline_desc_t *desc)
| Create a custom pipeline.
FLECS_API void | ecs_set_pipeline (ecs_world_t *world, ecs_entity_t pipeline)
| Set a custom pipeline.
FLECS_API ecs_entity_t | ecs_get_pipeline (const ecs_world_t *world)
| Get the current pipeline.
FLECS_API bool | ecs_progress (ecs_world_t *world, ecs_ftime_t delta_time)
| Progress a world.
FLECS_API void | ecs_set_time_scale (ecs_world_t *world, ecs_ftime_t scale)
| Set time scale.
FLECS_API void | ecs_reset_clock (ecs_world_t *world)
| Reset world clock.
FLECS_API void | ecs_run_pipeline (ecs_world_t *world, ecs_entity_t pipeline, ecs_ftime_t delta_time)
| Run pipeline.
FLECS_API void | ecs_set_threads (ecs_world_t *world, int32_t threads)
| Set number of worker threads.
FLECS_API void | ecs_set_task_threads (ecs_world_t *world, int32_t task_threads)
| Set number of worker task threads.
FLECS_API bool | ecs_using_task_threads (ecs_world_t *world)
| Returns true if task thread use have been requested.
FLECS_API void | FlecsPipelineImport (ecs_world_t *world)
| Pipeline module import function.

## Detailed Description

Pipelines order and schedule systems for execution.

## Macro Definition Documentation

## ◆ ECS_PIPELINE

#define ECS_PIPELINE | ( |  | world,
|  |  | id,
|  |  | ... )

Value:
ecs_entity_t id = 0, ecs_id(id) = 0; ECS_PIPELINE_DEFINE(world, id, __VA_ARGS__);\
(void)id;\
(void)ecs_id(id);
ecs_id
FLECS_API const ecs_entity_t ecs_id(EcsDocDescription)
Component id for EcsDocDescription.
ECS_PIPELINE_DEFINE
#define ECS_PIPELINE_DEFINE(world, id_,...)
Convenience macro to create a predeclared pipeline.
Definition pipeline.h:54
ecs_entity_t
ecs_id_t ecs_entity_t
An entity identifier.
Definition flecs.h:347

Convenience macro to create a pipeline.

Usage:

ECS_PIPELINE(world, MyPipeline, Update || Physics || Render)
ECS_PIPELINE
#define ECS_PIPELINE(world, id,...)
Convenience macro to create a pipeline.
Definition pipeline.h:74

Definition at line 74 of file pipeline.h.

## ◆ ecs_pipeline

#define ecs_pipeline | ( |  | world,
|  |  | ... )

Value:
ecs_pipeline_init(world, &(ecs_pipeline_desc_t) __VA_ARGS__ )
ecs_pipeline_init
FLECS_API ecs_entity_t ecs_pipeline_init(ecs_world_t *world, const ecs_pipeline_desc_t *desc)
Create a custom pipeline.
ecs_pipeline_desc_t
Pipeline descriptor, used with ecs_pipeline_init().
Definition pipeline.h:88

Convenience macro to create a pipeline.

See ecs_pipeline_init().

Definition at line 82 of file pipeline.h.

## ◆ ECS_PIPELINE_DEFINE

#define ECS_PIPELINE_DEFINE | ( |  | world,
|  |  | id_,
|  |  | ... )

Value:
{ \
ecs_pipeline_desc_t desc = {0}; \
ecs_entity_desc_t edesc = {0}; \
edesc.id = id_;\
edesc.name = #id_;\
desc.entity = ecs_entity_init(world, &edesc);\
desc.query.expr = #__VA_ARGS__; \
id_ = ecs_pipeline_init(world, &desc); \
ecs_id(id_) = id_;\
} \
ecs_assert(id_ != 0, ECS_INVALID_PARAMETER, "failed to create pipeline");
ecs_entity_init
ecs_entity_t ecs_entity_init(ecs_world_t *world, const ecs_entity_desc_t *desc)
Find or create an entity.
ecs_entity_desc_t
Used with ecs_entity_init().
Definition flecs.h:938
ecs_entity_desc_t::name
const char * name
Name of the entity.
Definition flecs.h:945
ecs_entity_desc_t::id
ecs_entity_t id
Set to modify existing entity (optional)
Definition flecs.h:941
ecs_pipeline_desc_t::entity
ecs_entity_t entity
Existing entity to associate with pipeline (optional).
Definition pipeline.h:90
ecs_pipeline_desc_t::query
ecs_query_desc_t query
The pipeline query.
Definition pipeline.h:115
ecs_query_desc_t::expr
const char * expr
Query DSL expression (optional)
Definition flecs.h:1170

Convenience macro to create a predeclared pipeline.

Usage:

ECS_ENTITY_DECLARE(MyPipeline);
ECS_PIPELINE_DEFINE(world, MyPipeline, Update || Physics || Render)
ECS_ENTITY_DECLARE
#define ECS_ENTITY_DECLARE
Forward declare an entity.
Definition flecs_c.h:29

Definition at line 54 of file pipeline.h.

## ◆ FLECS_PIPELINE_H

#define FLECS_PIPELINE_H

Definition at line 39 of file pipeline.h.

## Function Documentation

## ◆ ecs_get_pipeline()

FLECS_API ecs_entity_t ecs_get_pipeline | ( | const ecs_world_t * | world | ) |

Get the current pipeline.

This operation gets the current pipeline.

Parameters

  world | The world.

Returns
  The current pipeline.

## ◆ ecs_pipeline_init()

FLECS_API ecs_entity_t ecs_pipeline_init | ( | ecs_world_t * | world,
|  | const ecs_pipeline_desc_t * | desc )

Create a custom pipeline.

Parameters

  world | The world.
  desc | The pipeline descriptor.

Returns
  The pipeline, 0 if failed.

## ◆ ecs_progress()

FLECS_API bool ecs_progress | ( | ecs_world_t * | world,
|  | ecs_ftime_t | delta_time )

Progress a world.

This operation progresses the world by running all systems that are both enabled and periodic on their matching entities.

An application can pass a delta_time into the function, which is the time passed since the last frame. This value is passed to systems so they can update entity values proportional to the elapsed time since their last invocation.

When an application passes 0 to delta_time, ecs_progress() will automatically measure the time passed since the last frame. If an application does not uses time management, it should pass a non-zero value for delta_time (1.0 is recommended). That way, no time will be wasted measuring the time.

Parameters

  world | The world to progress.
  delta_time | The time passed since the last frame.

Returns
  false if ecs_quit() has been called, true otherwise.

## ◆ ecs_reset_clock()

FLECS_API void ecs_reset_clock | ( | ecs_world_t * | world | ) |

Reset world clock.

Reset the clock that keeps track of the total time passed in the simulation.

Parameters

  world | The world.

## ◆ ecs_run_pipeline()

FLECS_API void ecs_run_pipeline | ( | ecs_world_t * | world,
|  | ecs_entity_t | pipeline,
|  | ecs_ftime_t | delta_time )

Run pipeline.

This will run all systems in the provided pipeline. This operation may be invoked from multiple threads, and only when staging is disabled, as the pipeline manages staging and, if necessary, synchronization between threads.

If 0 is provided for the pipeline id, the default pipeline will be ran (this is either the builtin pipeline or the pipeline set with set_pipeline()).

When using progress() this operation will be invoked automatically for the default pipeline (either the builtin pipeline or the pipeline set with set_pipeline()). An application may run additional pipelines.

Parameters

  world | The world.
  pipeline | The pipeline to run.
  delta_time | The delta_time to pass to systems.

## ◆ ecs_set_pipeline()

FLECS_API void ecs_set_pipeline | ( | ecs_world_t * | world,
|  | ecs_entity_t | pipeline )

Set a custom pipeline.

This operation sets the pipeline to run when ecs_progress() is invoked.

Parameters

  world | The world.
  pipeline | The pipeline to set.

## ◆ ecs_set_task_threads()

FLECS_API void ecs_set_task_threads | ( | ecs_world_t * | world,
|  | int32_t | task_threads )

Set number of worker task threads.

ecs_set_task_threads() is similar to ecs_set_threads(), except threads are treated as short-lived tasks and will be created and joined around each update of the world. Creation and joining of these tasks will use the os_api_t tasks APIs rather than the the standard thread API functions, although they may be the same if desired. This function is useful for multithreading world updates using an external asynchronous job system rather than long running threads by providing the APIs to create tasks for your job system and then wait on their conclusion. The operation may be called multiple times to reconfigure the number of task threads used, but never while running a system / pipeline. Calling ecs_set_task_threads() will also end the use of threads setup with ecs_set_threads() and vice-versa

Parameters

  world | The world.
  task_threads | The number of task threads to create.

## ◆ ecs_set_threads()

FLECS_API void ecs_set_threads | ( | ecs_world_t * | world,
|  | int32_t | threads )

Set number of worker threads.

Setting this value to a value higher than 1 will start as many threads and will cause systems to evenly distribute matched entities across threads. The operation may be called multiple times to reconfigure the number of threads used, but never while running a system / pipeline. Calling ecs_set_threads() will also end the use of task threads setup with ecs_set_task_threads() and vice-versa.

Parameters

  world | The world.
  threads | The number of threads to create.

## ◆ ecs_set_time_scale()

FLECS_API void ecs_set_time_scale | ( | ecs_world_t * | world,
|  | ecs_ftime_t | scale )

Set time scale.

Increase or decrease simulation speed by the provided multiplier.

Parameters

  world | The world.
  scale | The scale to apply (default = 1).

## ◆ ecs_using_task_threads()

FLECS_API bool ecs_using_task_threads | ( | ecs_world_t * | world | ) |

Returns true if task thread use have been requested.

Parameters

  world | The world.

Returns
  Whether the world is using task threads.

## ◆ FlecsPipelineImport()

FLECS_API void FlecsPipelineImport | ( | ecs_world_t * | world | ) |

Pipeline module import function.

Usage:

ECS_IMPORT(world, FlecsPipeline)
ECS_IMPORT
#define ECS_IMPORT(world, id)
Wrapper around ecs_import().
Definition module.h:119

Parameters

  world | The world.