Structure that contains multiple control points (aka. Keyframe) that are generally interpolated over time. Each segment can be either manually or procedurally generated and customized based on the way you want them to behave during playback.

Curves are used by a vast range of resources; they can be used to animate a character, predefine a camera path or generate procedurally a gradient texture or to control variables. They can be created manually, recorded or directly imported from a COLLADA file.

See Also

Texture

Static Variables

Name	Description
`keyframe_count`	Amount of Keyframe the Curve contains.
Declaration unsigned int keyframe_count
`texture`	Reference to an existing Texture controlled by the active Curve.
Declaration Texture *texture

Variables

Name Description

speed Controls the playback speed of the current Curve.

Declaration

float speed

Range

0.01 to 5x

flags Bit mask used to control the Curve options.

Declaration

int flags

Cap	Value	Description
`CRV_FLAG_VISIBLE`	`bit.lshift(1,0)`	Toggle the Curve visibility in the editor.
`CRV_FLAG_REVERSE`	`bit.lshift(1,1)`	Force the Curve to play backward.
`CRV_FLAG_NORMALIZE`	`bit.lshift(1,2)`	Normalize the Keyframe values to be in the range of `-1` to `1`.
`CRV_FLAG_MANUAL`	`bit.lshift(1,3)`	Indicate the that Channel time will be updated manually for the active Curve.

visible Toggle on/off the Curve visibility in the editor.

Declaration

bool visible

reverse Force the Curve playback time be be inverted.

Declaration

bool reverse

normalize Normalize the Keyframe values.

Declaration

bool normalize

manual Indicate that the Curve playback time will be updated through its associated Channel manually by the user.

Declaration

bool manual

Functions

Name	Description
`AddKeyframe`	Add a new Keyframe.
Declaration unsigned int AddKeyframe( unsigned int uid, const InterpolationType interpolation_type, const HandleType handle_type, const bez3 key, float tension, float bias, int state ) Parameters `uid`: The unique id or 0 to let the system generate one for you (recommended). `interpolation_type`: Determine how the Keyframe should be interpolated. `handle_type`: The HandleType to use (not all types of InterpolationType apply). `key`: Bezier tripple that determine the key and handles values. `tension`: Tension factor used to tighten up the curvature (`kHermite` only). `bias`: Bias value used to twist the curvature (`kHermite` only). `state`: The bit mask KeyframeState to apply to the key. Return Value The index of the newly created Keyframe.
`GetKeyframe`	Retrieve a specific Keyframe using its unique id as key.
Declaration Keyframe GetKeyframe( unsigned int uid ) Parameters* `uid`: The unique id of the Keyframe to retrieve. Return Value A reference to the Keyframe matching the `uid`; else return `nil`.
`GetKeyframeAt`	Get an existing Keyframe using its index as key.
Declaration Keyframe GetKeyframeAt( const unsigned int index ) Parameters* `index`: Index of the Keyframe to retrieve. Return Value A reference to the Keyframe at the `index` location; else return `nil` if the `index` is invalid.
`GetKeyframeAtLocation`	Use the key playback time of a Keyframe as key to retrieve it.
Declaration Keyframe GetKeyframeAtLocation( float playback_time, float threshold ) Parameters* `playback_time`: The key `x` value. `threshold`: Maximum distance around the `playback_time` to consider to return the Keyframe. Return Value A reference to the Keyframe that matches the `playback_time` around the `threshold` specified; else return `nil` if no match is found. Note The function does not consider any CycleMode that might have been applied on the Curve by a higher level class.
`GetKeyframeIndex`	Retrieve the internal index of Keyframe from the stack.
Declaration int GetKeyframeIndex( const Keyframe keyframe ) Parameters* `keyframe`: A valid Keyframe reference. Return Value The index of the `keyframe`; else return `-1` if the `keyframe` reference is invalid.
`RemoveKeyframe`	Remove a specific Keyframe from the stack.
Declaration bool RemoveKeyframe( Keyframe keyframe ) Parameters* `keyframe`: A valid Keyframe reference. Return Value `true` if the `keyframe` is removed successfully; return `false` if the `keyframe` is invalid. Note If the value of the `keyframe` parameter is `nil` all Keyframe will be removed.
`RemoveKeyframeAt`	Remove a Keyframe at a specific index.
Declaration bool RemoveKeyframeAt( const int index ) Parameters `index`: The index of the Keyframe to remove. Return Value `true` if the Keyframe have been removed; return `false` if the `index` is out of bounds. Note If the `index` is negative all Keyframe will be removed.
`AdjustKeyframeHandleLeft`	Automatically adjust the position of the left handle of a Keyframe using its index as key.
Declaration bool AdjustKeyframeHandleLeft( const unsigned int index ) Parameters `index`: A valid Keyframe index. Return Value `true` if the adjustments were applied successfully on the Keyframe pointed by `index`; return `false` if the index is invalid or the HandleType of the Keyframe does not support adjustments.
`AdjustKeyframeHandleRight`	Automatically adjust the position of the left handle of a Keyframe using its index as key.
Declaration bool AdjustKeyframeHandleRight( const unsigned int index ) Parameters `index`: A valid Keyframe index. Return Value `true` if the adjustments were applied successfully on the Keyframe pointed by `index`; return `false` if the index is invalid or the HandleType of the Keyframe does not support adjustments.
`ShiftSelection`	Apply a specific transformation matrix to all subsequent keyframes found after the current Keyframe selection.
Declaration bool ShiftSelection( const mat4 m ) Parameters `m`: A 4x4 matrix to transform the keyframe(s). Return Value `true` upon a successful shift; else return `false` if there was not Keyframe selection.
`TransformSelection`	Apply a specific transformation to all selected keyframes.
Declaration bool TransformSelection( const mat4 m ) Parameters `m`: A 4x4 matrix to transform the keyframe(s). Return Value `true` if at least one Keyframe have been transformed; else `false`. Note Transformation will also be apply on the keyframe(s) handles.
`SortKeyframes`	Sort all keyframes in chronological order.
Declaration void SortKeyframes( void ) Warning Always sort Keyframe before playback. The evaluation routine assume that all keyframes are already ordered. If your keyframes are not sorted interpolation will not work properly.
`Cleanup`	Remove all duplicated keyframes using a custom threshold.
Declaration float Cleanup( bool clean_value, float threshold ) Parameters `clean_value`: Determine if the clean should operate on the key values or the key playback time. `threshold`: The maximum difference between two subsequent keys to allow removal. Return Value The cleanup ratio the function have performed; ranging from `0` to `1`.
`GetMin`	Return the minimum value of evaluated by the Curve.
Declaration float GetMin( unsigned short samples ) Parameters `samples`: The amount of samples the Curve should evaluate to find the lowest value. Return Value The lowest value found while evaluating the amount of `samples`.
`GetMax`	Return the maximum value of evaluated by the Curve.
Declaration float GetMax( unsigned short samples ) Parameters `samples`: The amount of samples the Curve should evaluate to find the highest value. Return Value The highest value found while evaluating the `samples`.
`GetStartTime`	Retrieve the start time of the Curve.
Declaration float GetStartTime( void ) Return Value The start time of the Curve.
`GetEndTime`	Retrieve the ending time of the Curve.
Declaration float GetEndTime( void ) Return Value The end time of the Curve.
`GetDuration`	Return the total duration of an active Curve.
Declaration float GetDuration( void ) Return Value The total duration of the Curve.
`GetCycleTime`	Return the Curve playback time for a specific CycleMode.
Declaration float GetCycleTime( float playback_time, const CycleMode cycle_mode ) Parameters `playback_time`: An arbitrary time to evaluate. `cycle_mode`: The CycleMode to used to extrapolate the Curve. Return Value The playback time of the Curve after cycling.
`Evaluate`	Manually evaluate the value of the Curve at a specific time and CycleMode.
Declaration float Evaluate( float playback_time, const CycleMode cycle_mode, bool normalize ) Parameters `playback_time`: An arbitrary time to evaluate. `cycle_mode`: The CycleMode to use. `normalize`: Force the Keyframe values to be normalized. Return Value The value evaluate by the Curve.
`EvaluateKeyframe`	Retrieve the current Curve Keyframe after evaluation.
Declaration int EvaluateKeyframe( float playback_time, const CycleMode cycle_mode ) Parameters `playback_time`: An arbitrary time to evaluate. `cycle_mode`: The CycleMode to use while extrapolating the Curve. Return Value The Keyframe index after evaluation.
`MirrorX`	Mirror all keyframes on the `X` axis (by time).
Declaration void MirrorX( void )
`MirrorY`	Mirror all keyframes on the `Y` axis (by value).
Declaration void MirrorY( void )
`SetTexture`	Allow you to generate the content of a Texture using the Curve data.
Declaration bool SetTexture( Texture texture ) Parameters* `texture`: An existing Texture asset; pass `nil` to disconnect. Return Value `true` if the Texture have been connected/disconnected; `false` if the TextureType is `kFont` or `kVideo` or if the target is set to 3d.
`ToTexture`	Use the active Keyframe content of the Curve to generate a Texture.
Declaration bool ToTexture( void ) Return Value `true` if a Texture is connected to the Curve and was updated successfully; else return `false`.
`ToTexture`	Use the active Keyframe content of the Curve to generate a Texture
Declaration bool ToTexture( bool normalize ) Parameters `normalize`: Force the Curve values to be normalized. Return Value `true` if a Texture is connected to the Curve and was updated successfully; else return `false`.
`Update`	Force the Curve to be updated.
Declaration void Update( void )

InterpolationType

List of all interpolation types. It is generally used to tell the system how to to interpolate from one Keyframe to another. But it is also used at other locations to dictate other type of data interpolation.

kConstant: The value stay constant until the next entry.
kLerp: Linear interpolation; values are joined by a straight line segment.
kCosine: Cosine interpolation, which provides a smooth transition between adjacent segments.
kCubic: Cubic interpolation which provides true continuity between two segments.
kBezier: Provides a four points Bezier interpolation where the tangent at the end points can be controlled and by two handles.
kCatmull: Catmull-Rom splines; which uses the slope between the previous point and the next as the derivative at the current point.
kHermite: Four points cubic interpolation that provides a higher degree on continuity and optionally allow you to tighten up the curvature by settings its tension. In addition a bias can be specified to twist the curve about the two known points.
kParametric: Parametric curve which provides a low cost smooth interpolation.
kBend: Similar to cosine but smoother.

HandleType

Type of handle to use with four points interpolation such as: kBezier and kHermite.

kSmooth: Keep both left and right handles in sync. for smooth interpolation.
kAligned: Align both the left and the right handle while they are being transformed.
kFree: Allows you to manipulate the left and right handles independently.
kAuto: Adjust both left and right handle to keep the transition between keyframes as smooth as possible. Consequently the left and right handles are moving in sync. and cannot be manipulated independently like when using kFree type.

KeyframeState

Bit flags used to represent the different level of selection of a Keyframe.

fSmooth: Neither the key or the left and right handle is selected.
fKeySelected: Key selection.
fLeftHandleSelected: Left handle selection.
fRightHandleSelected: Right handle selection.

Keyframe

Control point that represents a single key on a Curve.