timer.h

Go to the documentation of this file.

/**
 * @file addons/timer.h
 * @brief Timer module.
 *
 * Timers can be used to trigger actions at periodic or one-shot intervals. They
 * are typically used together with systems and pipelines.
 */
 
#ifdef FLECS_TIMER
 
/**
 * @defgroup c_addons_timer Timer
 * @ingroup c_addons
 * Run systems at a time interval.
 *
 * @{
 */
 
#ifndef FLECS_MODULE
#define FLECS_MODULE
#endif
 
#ifndef FLECS_PIPELINE
#define FLECS_PIPELINE
#endif
 
#ifndef FLECS_TIMER_H
#define FLECS_TIMER_H
 
#ifdef __cplusplus
extern "C" {
#endif
 
/** Component used for one-shot and interval timer functionality. */
typedef struct EcsTimer {
    ecs_ftime_t timeout;         /**< Timer timeout period. */
    ecs_ftime_t time;            /**< Incrementing time value. */
    ecs_ftime_t overshoot;       /**< Used to correct returned interval time. */
    int32_t fired_count;         /**< Number of times ticked. */
    bool active;                 /**< Is the timer active or not. */
    bool single_shot;            /**< Is this a single-shot timer. */
} EcsTimer;
 
/** Apply a rate filter to a tick source. */
typedef struct EcsRateFilter {
    ecs_entity_t src;            /**< Source of the rate filter. */
    int32_t rate;                /**< Rate of the rate filter. */
    int32_t tick_count;          /**< Number of times the rate filter ticked. */
    ecs_ftime_t time_elapsed;    /**< Time elapsed since last tick. */
} EcsRateFilter;
 
 
/** Set timer timeout.
 * This operation executes any systems associated with the timer after the
 * specified timeout value. If the entity contains an existing timer, the
 * timeout value will be reset. The timer can be started and stopped with
 * ecs_start_timer() and ecs_stop_timer().
 *
 * The timer is synchronous, and is incremented each frame by delta_time.
 *
 * The tick_source entity will be a tick source after this operation. Tick
 * sources can be read by getting the EcsTickSource component. If the tick
 * source ticked this frame, the 'tick' member will be true. When the tick
 * source is a system, the system will tick when the timer ticks.
 *
 * @param world The world.
 * @param tick_source The timer for which to set the timeout (0 to create one).
 * @param timeout The timeout value.
 * @return The timer entity.
 */
FLECS_API
ecs_entity_t ecs_set_timeout(
    ecs_world_t *world,
    ecs_entity_t tick_source,
    ecs_ftime_t timeout);
 
/** Get current timeout value for the specified timer.
 * This operation returns the value set by ecs_set_timeout(). If no timer is
 * active for this entity, the operation returns 0.
 *
 * After the timeout expires the EcsTimer component is removed from the entity.
 * This means that if ecs_get_timeout() is invoked after the timer is expired, the
 * operation will return 0.
 *
 * @param world The world.
 * @param tick_source The timer.
 * @return The current timeout value, or 0 if no timer is active.
 */
FLECS_API
ecs_ftime_t ecs_get_timeout(
    const ecs_world_t *world,
    ecs_entity_t tick_source);
 
/** Set timer interval.
 * This operation will continuously invoke systems associated with the timer
 * after the interval period expires. If the entity contains an existing timer,
 * the interval value will be reset.
 *
 * The timer is synchronous, and is incremented each frame by delta_time.
 *
 * The tick_source entity will be a tick source after this operation. Tick
 * sources can be read by getting the EcsTickSource component. If the tick
 * source ticked this frame, the 'tick' member will be true. When the tick
 * source is a system, the system will tick when the timer ticks.
 *
 * @param world The world.
 * @param tick_source The timer for which to set the interval (0 to create one).
 * @param interval The interval value.
 * @return The timer entity.
 */
FLECS_API
ecs_entity_t ecs_set_interval(
    ecs_world_t *world,
    ecs_entity_t tick_source,
    ecs_ftime_t interval);
 
/** Get current interval value for the specified timer.
 * This operation returns the value set by ecs_set_interval(). If the entity is
 * not a timer, the operation will return 0.
 *
 * @param world The world.
 * @param tick_source The timer for which to get the interval.
 * @return The current interval value, or 0 if no timer is active.
 */
FLECS_API
ecs_ftime_t ecs_get_interval(
    const ecs_world_t *world,
    ecs_entity_t tick_source);
 
/** Start timer.
 * This operation resets the timer and starts it with the specified timeout.
 *
 * @param world The world.
 * @param tick_source The timer to start.
 */
FLECS_API
void ecs_start_timer(
    ecs_world_t *world,
    ecs_entity_t tick_source);
 
/** Stop timer.
 * This operation stops a timer from triggering.
 *
 * @param world The world.
 * @param tick_source The timer to stop.
 */
FLECS_API
void ecs_stop_timer(
    ecs_world_t *world,
    ecs_entity_t tick_source);
 
/** Reset time value of timer to 0.
 * This operation resets the timer value to 0.
 *
 * @param world The world.
 * @param tick_source The timer to reset.
 */
FLECS_API
void ecs_reset_timer(
    ecs_world_t *world,
    ecs_entity_t tick_source);
 
/** Enable randomizing initial time value of timers.
 * Initializes timers with a random time value, which can improve scheduling as
 * systems/timers for the same interval don't all happen on the same tick.
 *
 * @param world The world.
 */
FLECS_API
void ecs_randomize_timers(
    ecs_world_t *world);
 
/** Set rate filter.
 * This operation initializes a rate filter. Rate filters sample tick sources
 * and tick at a configurable multiple. A rate filter is a tick source itself,
 * which means that rate filters can be chained.
 *
 * Rate filters enable deterministic system execution which cannot be achieved
 * with interval timers alone. For example, if timer A has interval 2.0 and
 * timer B has interval 4.0, it is not guaranteed that B will tick at exactly
 * twice the multiple of A. This is partly due to the nondeterministic nature of
 * timers, and partly due to floating-point rounding errors.
 *
 * Rate filters can be combined with timers (or other rate filters) to ensure
 * that a system ticks at an exact multiple of a tick source (which can be
 * another system). If a rate filter is created with a rate of 1, it will tick
 * at the exact same time as its source.
 *
 * If no tick source is provided, the rate filter will use the frame tick as
 * source, which corresponds with the number of times ecs_progress() is called.
 *
 * The tick_source entity will be a tick source after this operation. Tick
 * sources can be read by getting the EcsTickSource component. If the tick
 * source ticked this frame, the 'tick' member will be true. When the tick
 * source is a system, the system will tick when the timer ticks.
 *
 * @param world The world.
 * @param tick_source The rate filter entity (0 to create one).
 * @param rate The rate to apply.
 * @param source The tick source (0 to use frames).
 * @return The rate filter entity.
 */
FLECS_API
ecs_entity_t ecs_set_rate(
    ecs_world_t *world,
    ecs_entity_t tick_source,
    int32_t rate,
    ecs_entity_t source);
 
/** Assign tick source to system.
 * Systems can be their own tick source, which can be any of the tick sources
 * (one-shot timers, interval timers, and rate filters). However, in some cases it
 * must be guaranteed that different systems tick on the exact same frame.
 *
 * This cannot be guaranteed by giving two systems the same interval/rate filter
 * as it is possible that one system is (for example) disabled, which would
 * cause the systems to go out of sync. To provide these guarantees, systems
 * must use the same tick source, which is what this operation enables.
 *
 * When two systems share the same tick source, it is guaranteed that they tick
 * in the same frame. The provided tick source can be any entity that is a tick
 * source, including another system. If the provided entity is not a tick source
 * the system will not be run.
 *
 * To disassociate a tick source from a system, use 0 for the tick_source
 * parameter.
 *
 * @param world The world.
 * @param system The system to associate with the timer.
 * @param tick_source The tick source to associate with the system.
 */
FLECS_API
void ecs_set_tick_source(
    ecs_world_t *world,
    ecs_entity_t system,
    ecs_entity_t tick_source);
 
 
////////////////////////////////////////////////////////////////////////////////
//// Module
////////////////////////////////////////////////////////////////////////////////
 
/** Timer module import function.
 * Usage:
 * @code
 * ECS_IMPORT(world, FlecsTimer)
 * @endcode
 * 
 * @param world The world.
 */
FLECS_API
void FlecsTimerImport(
    ecs_world_t *world);
 
#ifdef __cplusplus
}
#endif
 
#endif
 
/** @} */
 
#endif