Pipeline

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 forward-declared pipeline.
#define	ECS_PIPELINE(world, id, ...)
	Convenience macro to create a pipeline.
#define	ecs_pipeline(world, ...)    ecs_pipeline_init(world, &(ecs_pipeline_desc_t) __VA_ARGS__ )
	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)
	Return true if task thread use has 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);

Convenience macro to create a pipeline.

Usage:

ECS_PIPELINE(world, MyPipeline, Update || Physics || Render)

Definition at line 74 of file pipeline.h.

ecs_pipeline

#define ecs_pipeline	(		world,
			... )    ecs_pipeline_init(world, &(ecs_pipeline_desc_t) __VA_ARGS__ )

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");

Convenience macro to create a forward-declared pipeline.

Usage:

ECS_ENTITY_DECLARE(MyPipeline);
ECS_PIPELINE_DEFINE(world, MyPipeline, Update || Physics || Render)

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 use 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 run (this is either the built-in pipeline or the pipeline set with ecs_set_pipeline()).

When using ecs_progress(), this operation will be invoked automatically for the default pipeline (either the built-in pipeline or the pipeline set with ecs_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 task APIs rather than 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 or pipeline. Calling ecs_set_task_threads() will also end the use of threads set up 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 that 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 or pipeline. Calling ecs_set_threads() will also end the use of task threads set up 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

)

Return true if task thread use has 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)

Parameters

world

The world.