Frame functions

Collaboration diagram for Frame functions:

Functions
float	ecs_frame_begin (ecs_world_t *world, float delta_time)
	Begin frame.
void	ecs_frame_end (ecs_world_t *world)
	End frame.
void	ecs_run_post_frame (ecs_world_t *world, ecs_fini_action_t action, void *ctx)
	Register action to be executed once after frame.
void	ecs_quit (ecs_world_t *world)
	Signal exit This operation signals that the application should quit.
bool	ecs_should_quit (const ecs_world_t *world)
	Return whether a quit has been requested.
void	ecs_measure_frame_time (ecs_world_t *world, bool enable)
	Measure frame time.
void	ecs_measure_system_time (ecs_world_t *world, bool enable)
	Measure system time.
void	ecs_set_target_fps (ecs_world_t *world, float fps)
	Set target frames per second (FPS) for application.
void	ecs_set_default_query_flags (ecs_world_t *world, ecs_flags32_t flags)
	Set default query flags.

Detailed Description

Function Documentation

ecs_frame_begin()

float ecs_frame_begin	(	ecs_world_t *	world,
		float	delta_time )

Begin frame.

When an application does not use ecs_progress() to control the main loop, it can still use Flecs features such as FPS limiting and time measurements. This operation needs to be invoked whenever a new frame is about to get processed.

Calls to ecs_frame_begin() must always be followed by ecs_frame_end().

The function accepts a delta_time parameter, which will get passed to systems. This value is also used to compute the amount of time the function needs to sleep to ensure it does not exceed the target_fps, when it is set. When 0 is provided for delta_time, the time will be measured.

This function should only be ran from the main thread.

Parameters

world	The world.
delta_time	Time elapsed since the last frame.

Returns

The provided delta_time, or measured time if 0 was provided.

ecs_frame_end()

void ecs_frame_end

(

ecs_world_t *

world

)

End frame.

This operation must be called at the end of the frame, and always after ecs_frame_begin().

Parameters

world

The world.

ecs_measure_frame_time()

void ecs_measure_frame_time	(	ecs_world_t *	world,
		bool	enable )

Measure frame time.

Frame time measurements measure the total time passed in a single frame, and how much of that time was spent on systems and on merging.

Frame time measurements add a small constant-time overhead to an application. When an application sets a target FPS, frame time measurements are enabled by default.

Parameters

world	The world.
enable	Whether to enable or disable frame time measuring.

ecs_measure_system_time()

void ecs_measure_system_time	(	ecs_world_t *	world,
		bool	enable )

Measure system time.

System time measurements measure the time spent in each system.

System time measurements add overhead to every system invocation and therefore have a small but measurable impact on application performance. System time measurements must be enabled before obtaining system statistics.

Parameters

world	The world.
enable	Whether to enable or disable system time measuring.

ecs_quit()

void ecs_quit

(

ecs_world_t *

world

)

Signal exit This operation signals that the application should quit.

It will cause ecs_progress() to return false.

Parameters

world

The world to quit.

ecs_run_post_frame()

void ecs_run_post_frame	(	ecs_world_t *	world,
		ecs_fini_action_t	action,
		void *	ctx )

Register action to be executed once after frame.

Post frame actions are typically used for calling operations that cannot be invoked during iteration, such as changing the number of threads.

Parameters

world	The world.
action	The function to execute.
ctx	Userdata to pass to the function

ecs_set_default_query_flags()

void ecs_set_default_query_flags	(	ecs_world_t *	world,
		ecs_flags32_t	flags )

Set default query flags.

Set a default value for the ecs_filter_desc_t::flags field. Default flags are applied in addition to the flags provided in the descriptor. For a list of available flags, see include/flecs/private/api_flags.h. Typical flags to use are:

• EcsQueryMatchEmptyTables
• EcsQueryMatchDisabled
• EcsQueryMatchPrefab

Parameters

world	The world.
flags	The query flags.

ecs_set_target_fps()

void ecs_set_target_fps	(	ecs_world_t *	world,
		float	fps )

Set target frames per second (FPS) for application.

Setting the target FPS ensures that ecs_progress() is not invoked faster than the specified FPS. When enabled, ecs_progress() tracks the time passed since the last invocation, and sleeps the remaining time of the frame (if any).

This feature ensures systems are ran at a consistent interval, as well as conserving CPU time by not running systems more often than required.

Note that ecs_progress() only sleeps if there is time left in the frame. Both time spent in flecs as time spent outside of flecs are taken into account.

Parameters

world	The world.
fps	The target FPS.

ecs_should_quit()

bool ecs_should_quit

(

const ecs_world_t *

world

)

Return whether a quit has been requested.

Parameters

world

The world.

Returns

Whether a quit has been requested.

See also

ecs_quit()