playcanvas/build/playcanvas/src/core/math/curve.d.ts

Open-source WebGL/WebGPU 3D engine for the web

/**
 * A curve is a collection of keys (time/value pairs). The shape of the curve is defined by its
 * type that specifies an interpolation scheme for the keys.
 *
 * @category Math
 */
export class Curve {
    /**
     * Creates a new Curve instance.
     *
     * @param {number[]} [data] - An array of keys (pairs of numbers with the time first and value
     * second).
     * @example
     * const curve = new pc.Curve([
     *     0, 0,        // At 0 time, value of 0
     *     0.33, 2,     // At 0.33 time, value of 2
     *     0.66, 2.6,   // At 0.66 time, value of 2.6
     *     1, 3         // At 1 time, value of 3
     * ]);
     */
    constructor(data?: number[]);
    /**
     * The keys that define the curve. Each key is an array of two numbers with the time first and
     * the value second.
     *
     * @type {number[][]}
     */
    keys: number[][];
    /**
     * The curve interpolation scheme. Can be:
     *
     * - {@link CURVE_LINEAR}
     * - {@link CURVE_SMOOTHSTEP}
     * - {@link CURVE_SPLINE}
     * - {@link CURVE_STEP}
     *
     * Defaults to {@link CURVE_SMOOTHSTEP}.
     *
     * @type {number}
     */
    type: number;
    /**
     * Controls how {@link CURVE_SPLINE} tangents are calculated. Valid range is between 0 and 1
     * where 0 results in a non-smooth curve (equivalent to linear interpolation) and 1 results in
     * a very smooth curve. Use 0.5 for a Catmull-Rom spline.
     *
     * @type {number}
     */
    tension: number;
    /**
     * @type {CurveEvaluator}
     * @private
     */
    private _eval;
    /**
     * Gets the number of keys in the curve.
     *
     * @type {number}
     */
    get length(): number;
    /**
     * Adds a new key to the curve.
     *
     * @param {number} time - Time to add new key.
     * @param {number} value - Value of new key.
     * @returns {number[]} The newly created `[time, value]` pair.
     * @example
     * const curve = new pc.Curve();
     * curve.add(0, 1);   // add key at time 0 with value 1
     * curve.add(1, 2);   // add key at time 1 with value 2
     */
    add(time: number, value: number): number[];
    /**
     * Gets the `[time, value]` pair at the specified index.
     *
     * @param {number} index - The index of key to return.
     * @returns {number[]} The `[time, value]` pair at the specified index.
     * @example
     * const curve = new pc.Curve([0, 1, 1, 2]);
     * const key = curve.get(0); // returns [0, 1]
     */
    get(index: number): number[];
    /**
     * Sorts keys by time.
     */
    sort(): void;
    /**
     * Returns the interpolated value of the curve at specified time.
     *
     * @param {number} time - The time at which to calculate the value.
     * @returns {number} The interpolated value.
     * @example
     * const curve = new pc.Curve([0, 0, 1, 10]);
     * const value = curve.value(0.5); // returns interpolated value at time 0.5
     */
    value(time: number): number;
    /**
     * Returns the key closest to the specified time.
     *
     * @param {number} time - The time to find the closest key to.
     * @returns {number[]|null} The `[time, value]` pair closest to the specified time, or null if
     * no keys exist.
     * @example
     * const curve = new pc.Curve([0, 1, 0.5, 2, 1, 3]);
     * const key = curve.closest(0.6); // returns [0.5, 2]
     */
    closest(time: number): number[] | null;
    /**
     * Returns a clone of the specified curve object.
     *
     * @returns {this} A clone of the specified curve.
     * @example
     * const curve = new pc.Curve([0, 0, 1, 10]);
     * const clonedCurve = curve.clone();
     */
    clone(): this;
    /**
     * Sample the curve at regular intervals over the range [0..1].
     *
     * @param {number} precision - The number of samples to return.
     * @returns {Float32Array} The set of quantized values.
     * @ignore
     */
    quantize(precision: number): Float32Array;
    /**
     * Sample the curve at regular intervals over the range [0..1] and clamp the resulting samples
     * to [min..max].
     *
     * @param {number} precision - The number of samples to return.
     * @param {number} min - The minimum output value.
     * @param {number} max - The maximum output value.
     * @returns {Float32Array} The set of quantized values.
     * @ignore
     */
    quantizeClamped(precision: number, min: number, max: number): Float32Array;
}