Frame

Frame management. More...

Collaboration diagram for Frame:

Functions
FLECS_API ecs_ftime_t	ecs_frame_begin (ecs_world_t *world, ecs_ftime_t delta_time)
	Begin frame.
FLECS_API void	ecs_frame_end (ecs_world_t *world)
	End frame.
FLECS_API void	ecs_run_post_frame (ecs_world_t *world, ecs_fini_action_t action, void *ctx)
	Register an action to be executed once after the frame.
FLECS_API void	ecs_quit (ecs_world_t *world)
	Signal exit.
FLECS_API bool	ecs_should_quit (const ecs_world_t *world)
	Return whether a quit has been requested.
FLECS_API void	ecs_measure_frame_time (ecs_world_t *world, bool enable)
	Measure frame time.
FLECS_API void	ecs_measure_system_time (ecs_world_t *world, bool enable)
	Measure system time.
FLECS_API void	ecs_set_target_fps (ecs_world_t *world, ecs_ftime_t fps)
	Set target frames per second (FPS) for an application.
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.

Detailed Description

Frame management.

Function Documentation

ecs_frame_begin()

FLECS_API ecs_ftime_t ecs_frame_begin	(	ecs_world_t *	world,
		ecs_ftime_t	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 run 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()

FLECS_API 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()

FLECS_API 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()

FLECS_API 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()

FLECS_API 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_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_post_frame()

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

Register an action to be executed once after the 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_target_fps()

FLECS_API void ecs_set_target_fps	(	ecs_world_t *	world,
		ecs_ftime_t	fps )

Set target frames per second (FPS) for an 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 run 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 and time spent outside of Flecs are taken into account.

Parameters

world	The world.
fps	The target FPS.

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_should_quit()

FLECS_API 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()