Flecs: Frame functions
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
Frame functions
C API » Core » World
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()