.. _stdlib_curve:

============
Curve module
============

This module defines a function that calculates the value of a piecewise linear curve at a given point.
It iterates through the curve points to find the segment that contains the input point and performs cubic interpolation to calculate the value at that point. If the curve has fewer than 1 chunk, it returns 0.0.

To use this module, include the following line in your project file::

    require engine.math.curve // or require engine.core

++++++++++
Structures
++++++++++

.. _struct-curve-CurveKey:

.. das:attribute:: CurveKey

A keyframe for a curve.

:Fields: * **time** : float - the time of the keyframe.

         * **value** : float - the Y value of the keyframe.

         * **inTangent** : float - the in slope of the keyframe in radians.

         * **outTangent** : float - the out slope of the keyframe in radians.


.. _struct-curve-Curve:

.. das:attribute:: Curve

The cubic interpolation curve.

:Fields: * **points** : array<tuple<time_range:float2;cubic_coef:float4>> - The curve points.


.. _function-curve_Curve_array_ls_CurveKey_gr_:

.. das:function:: Curve(keys: array<CurveKey>) : Curve

Create a curve from a list of keyframes.

:Arguments: * **keys** : array< :ref:`CurveKey <struct-curve-CurveKey>` >

+++++++++
Functions
+++++++++

  *  :ref:`evaluate (curve: Curve; t: float) : float <function-curve_evaluate_Curve_float>` 

.. _function-curve_evaluate_Curve_float:

.. das:function:: evaluate(curve: Curve; t: float) : float

Evaluate the curve at a timestamp `t`.
Returns the Y value of the curve at a timestamp `t`. If `t` is outside the range of the curve, 0 is returned.

:Arguments: * **curve** :  :ref:`Curve <struct-curve-Curve>` 

            * **t** : float