animate.h

Go to the documentation of this file.

/**
 * @file animate.h
 * @brief Provides utility functions for animating numerical values using various easing effects.
 *
 * This file contains a collection of inline functions designed to smoothly
 * transition a `double` `value` towards a `target` value over time,
 * using different animation curves (easing functions). These are commonly
 * used for UI transitions, movement, and other visual effects.
 *
 * General notes on animation functions:
 * - `value`:  A pointer to the variable to be animated. This variable is modified directly.
 * - `target`: The target value that `value` will animate towards.
 * - `t`:      The approximate time constant for the animation (in seconds).
 *             A smaller `t` generally results in a faster or more "springy" animation.
 */
#pragma once
 
#include "_math.h"
#include "gapi.h"
#include <stdlib.h>
 
/**
 * @brief Animates a value towards a target with a smooth, ease-out effect.
 *
 * This function creates a spring-like motion that quickly moves towards the
 * target and then gradually settles. The `t` parameter controls the speed
 * and "stiffness" of the spring.
 *
 * @param value A pointer to the double value to animate. This value is updated in place.
 * @param target The target value to animate towards.
 * @param t The animation's approximate duration (time constant). A smaller 't' results in a
 *        faster, more immediate animation.
 */
void gm_anim_spring(double *value, double target, double t) {
  if (value == NULL || t <= 0)
    return;
  double difference = target - *value;
  double move = (gm_dt() * difference) / t;
  if (fabs(move) >= fabs(difference)) {
    *value = target;
  } else {
    *value += move;
  }
}
 
/**
 * @brief Animates a value towards a target with a quadratic ease-out effect.
 *
 * The animation starts fast and decelerates quadratically as it approaches
 * the target.
 *
 * @param value A pointer to the double value to animate.
 * @param target The target value to animate towards.
 * @param t The animation's approximate duration (time constant).
 */
void gm_anim_ease_out_quad(double *value, const double target, double t) {
  if (value == NULL || t <= 0)
    return;
  double difference = target - *value;
  double speed_factor = 1.0 + sqrt(fabs(difference));
  double move = (gm_dt() * difference * speed_factor) / t;
 
  if (fabs(move) >= fabs(difference)) {
    *value = target;
  } else {
    *value += move;
  }
}
 
/**
 * @brief Animates a value towards a target with a cubic ease-out effect.
 *
 * The animation starts very fast and decelerates cubically as it approaches
 * the target, providing a more pronounced ease-out than `gm_anim_ease_out_quad`.
 *
 * @param value A pointer to the double value to animate.
 * @param target The target value to animate towards.
 * @param t The animation's approximate duration (time constant).
 */
void gm_anim_ease_out_cubic(double *value, double target, double t) {
  if (value == NULL || t <= 0)
    return;
  double difference = target - *value;
  double speed_factor = 1.0 + fabs(difference);
  double move = (gm_dt() * difference * speed_factor) / t;
 
  if (fabs(move) >= fabs(difference)) {
    *value = target;
  } else {
    *value += move;
  }
}
 
/**
 * @brief Animates a value towards a target with a quadratic ease-in effect.
 *
 * The animation starts slow and accelerates quadratically as it approaches
 * the target.
 *
 * @param value A pointer to the double value to animate.
 * @param target The target value to animate towards.
 * @param t The animation's approximate duration (time constant).
 */
void gm_anim_ease_in_quad(double *value, double target, double t) {
  if (value == NULL || t <= 0)
    return;
  double difference = target - *value;
  if (fabs(difference) < 0.0001) {
    *value = target;
    return;
  }
  double speed_factor = 1.0 / (1.0 + sqrt(fabs(difference)));
  double move = (gm_dt() * difference * speed_factor) / t;
 
  // For ease-in, it's possible for the calculated move to be tiny, so we ensure
  // minimum progress.
  if (fabs(move) < 0.0001) {
    move = 0.0001 * (difference > 0 ? 1 : -1);
  }
 
  if (fabs(move) >= fabs(difference)) {
    *value = target;
  } else {
    *value += move;
  }
}
 
/**
 * @brief Returns a sinusoidal animation value based on the global engine time (`gm_t()`).
 * @param center The center value around which the animation oscillates.
 * @param radius The amplitude of the oscillation.
 * @param speed The speed of the oscillation.
 * @param offset The phase offset for the oscillation.
 * @return The current animated value based on a sine wave.
 */
static inline double gm_anim_sin(double center, double radius, double speed,
                                 double offset) {
  return center + (radius * sin(speed * (gm_t() + offset) * M_PI * 2));
}
 
/**
 * @brief Returns a cosine animation value based on the global engine time (`gm_t()`).
 * @param center The center value around which the animation oscillates.
 * @param radius The amplitude of the oscillation.
 * @param speed The speed of the oscillation.
 * @param offset The phase offset for the oscillation.
 * @return The current animated value based on a cosine wave.
 */
static inline double gm_anim_cos(double center, double radius, double speed,
                                 double offset) {
  return center + (radius * cos(speed * (gm_t() + offset) * M_PI * 2));
}