Summary

The Path module provides support for creating and maintaining time indexed keyframe data, and sampling the path at arbitrary times.

Overview

A Path is a set of time indexed keyframes, each of which contains a transformation. A common use of Paths is to hold animation keyframe data for individual bones. An Actor's animation (called a Motion) consists of a Path for each of the Actor's bones. See the documentation for geActor and geMotion for more information on creating and using Motions.

Each Path contains two channels: Translation and Rotation. The Translation channel maintains positional information and the Rotation channel maintains orientation information. When creating the path, you can specify the method to be used for Translation and Rotation interpolation. The interpolation method affects the way that the sampling functions provide "in between" transformations when a path is sampled between keyframes.

Paths are reference counted. See the Engine API Overview for a detailed discussion of reference counting.

Creating and Maintaining Paths

To create a Path, call gePath_Create. This will create an empty Path with no keyframes. To add a keyframe to the Path, set the Path's transform and call gePath_InsertKeyframe. To modify a keyframe's transform, call gePath_ModifyKeyframe. To modify a keyframe's time, remove the keyframe and insert it at the new time. To delete a keyframe, call gePath_DeleteKeyframe.

Keyframes are referenced by index. To obtain the keyframe index for a channel at a particular time, call gePath_GetKeyframeIndex.

You may insert keyframes in both channels at one time by specifying GE_PATH_ALL_CHANNELS. You may also modify and delete keyframes in multiple channels concurrently. However, if you add keyframes to individual channels at different times, specifying multiple keyframes in a call to gePath_DeleteKeyframe or gePath_ModifyKeyframe will produce unexpected results.

A Path's time extents is the time period between the first and last keyframes.

When creating a Path, you have the choice to create a looping or non-looping Path. The difference is in how the path generator handles sampling beyond the Path's time extents.

Sampling

To obtain the transform for the path at a particular time, call gePath_Sample. To obtain the rotation (quaternion) and/or translation (vector) portion of the transform at a particular time, call gePath_SampleChannels.

For a non-looping Path, sampling before the first keyframe time will produce the first keyframe's transform, and sampling beyond the last keyframe time will produce the last keyframe's transform. When sampling a looped Path, the sample time is "wrapped around" the time extents. Sampling before the first keyframe will cause wrapping in reverse.

Input and Output

Currently, Paths can be output in text or binary format. Text format is supported for historical reasons and will be removed in a later version. Binary format results in faster input and output, and smaller files. To output a binary file, call gePath_WriteToBinaryFile. To output a text format file, call gePath_WriteToFile.

Reference

gePath * gePath_Create(gePath_Interpolator TranslationInterpolation, gePath_Interpolator RotationInterpolation, geBoolean Looped);

Description: Creates a gePath object.

Returns: If the function succeeds, the return value is a valid gePath object with no keyframes. If the function fails, it returns NULL.

Remarks: When creating a looping motion, the first and last keyframes in both channels should be identical. The path generator will choose arbitrarily between these two keyframes when sampling exactly at the end of the loop.

gePath * gePath_CreateCopy(const gePath *Path);

Description: Creates a copy of a gePath object.

Returns: If the function succeeds, the return value is a valid gePath object that is an exact copy of the passed-in Path. If the function fails, it returns NULL.

Remarks: The returned Path is not a reference, but an entierly new Path object. To create a reference, call gePath_CreateRef.

gePath* gePath_CreateFromFile(geVFile *F);

Description: Reads information from the specified file and creates a Path.

Returns: If the function succeeds, the return value is a valid gePath object. If the function fails, it returns NULL.

Remarks: When the function returns, the file will be positioned after the last byte read. The passed-in file may not be a directory.

void gePath_CreateRef(gePath *Path);

Description: Increases the reference count of the specified path.

Returns: void.

Remarks: See the Engine API Overview for more information on reference counting.

Description: Deletes the indexed keyframe in the specified channels.

Returns: Returns GE_TRUE if the specified keyframe is deleted from all specified channels. Returns GE_FALSE if any error occurs.

Remarks: The function will fail if the specified keyframe does not exist. If multiple channels are specified and the keyframe exists in one channel but not the other, the keyframe will be deleted from the channel that contains it, and the function will return GE_FALSE. Note that deleting a keyframe from multiple channels may produce unexpected results if the keyframes were added to individual channels at different times by separate calls to gePath_InsertKeyframe.

void gePath_Destroy(gePath **pPath);

Description: Destroys the path pointed to by the specified path pointer.

Returns: void.

Remarks: The reference count of the specified path is decreased. If the reference count goes to zero, then the path information is deallocated and the path pointer is set to NULL.

void gePath_GetKeyframe(const gePath *Path, int Index, int Channel, geFloat *Time, geXForm3d *Matrix);

Description: Obtains the transform and the time of the indexed keyframe in a specified channel.

Returns: void.

Remarks: The function will fail if the specified keyframe does not exist in the channels specified. If multiple channels are specified, the keyframe must exist in both channels. If a channel is not specified, then the poirtion of the matrix corresponding to that channel will be set to identity.

Description: Returns a count of the number of keyframes in the specified channel.

Returns: The count of keyframes in the specified channel.

Remarks: This function will only return the count of keyframes in a single channel. If the channel parameter contains a mask, the return result is undefined.

int gePath_GetKeyframeIndex(const gePath *Path, int Channel, geFloat Time)

Description: Obtains the index of a keyframe at the specified time.

Returns: If a keyframe exists at the specified time, the index of the keyframe is returned. If no keyframe exists in the specified channel at the specified time, the return value is -1.

Remarks: If the channel parameter contains a mask of more than one channel, the return value is undefined. The channel must contain a keyframe at the exact time specified, or the function will return -1.

geBoolean gePath_GetTimeExtents(const gePath *Path, geFloat *StartTime, geFloat *EndTime)

Description: Obtains the time extents of the given path.

Returns: If the path has no keyframes, the return value is GE_FALSE, and the time extent variables are not changed. If the path contains one or more keyframes, the return value is GE_TRUE and the StartTime and EndTime variables are set.

Remarks: If the path contains one or more keyframes, then the earliest keyframe time (from both channels) is placed in StartTime, and the latest keyframe time (again, from both channels) is placed in EndTime. On successful return, EndTime will always be greater than or equal to StartTime.

geBoolean gePath_InsertKeyframe(gePath *Path, int ChannelMask, geFloat Time, const geXForm3d *Matrix);

Description: Inserts a keyframe into the specified channels.

Returns: If the keyframe is inserted successfully, the return value is GE_TRUE. If the function is unable to insert the keyframe in all of the specified channels, the return value is GE_FALSE and no keyframes are added to any channels.

Remarks: If GE_PATH_ROTATION_CHANNEL is specified, the rotation part of the passed matrix is stored as the keyframe transform for the rotation channel. If GE_PATH_TRANSLATION_CHANNEL is specified, the translation part of the passed matrix is stored as the keyframe transform for the translation channel. The function will fail if a keyframe already exists at the specified time.

geBoolean gePath_ModifyKeyframe(gePath *Path, int Index, int ChannelMask, const geXForm3d *Matrix);

Description: Change the transformation for an existing keyframe.

Returns: If the keyframe is modified successfully, the return value is GE_TRUE.

Remarks: If the specified keyframe index does not exist in one of the channels, the function will fail. If GE_PATH_ROTATION_CHANNEL is specified, the rotation part of the passed matrix is stored as the keyframe transform for the rotation channel. If GE_PATH_TRANSLATION_CHANNEL is specified, the translation part of the passed matrix is stored as the keyframe transform for the translation channel. Note that modifying a keyframe in multiple channels may produce unexpected results if the keyframes were added to individual channels at different times by separate calls to gePath_InsertKeyframe.

geBoolean gePath_OffsetTimes(gePath *Path, int StartingIndex, int ChannelMask, geFloat TimeOffset);

This function is not currently implemented. 

void gePath_Sample(const gePath *Path, geFloat Time, geXForm3d *Matrix);

Description: Sample the path at the specified time to obtain the transform.

Returns: void.

Remarks: All channels are sampled using the individual channel interpolation types. The resulting components (rotation and translation) are combined and placed in the matrix.

For a non-looping Path, sampling before the first keyframe time will produce the first keyframe's transform, and sampling beyond the last keyframe time will produce the last keyframe's transform. When sampling a looped Path, the sample time is "wrapped around" the time extents. Sampling before the first keyframe will cause wrapping in reverse.

void gePath_SampleChannels(const gePath *Path, geFloat Time, geQuaternion *Rotation, geVec3d *Translation);

Description: Sample the path at the specified time to obtain the individual transform components.

Returns: void.

Remarks: All channels are sampled using the individual channel interpolation types. The resulting rotation component is returned as a quaternion, and the resulting translation is returned as a vector.

For a non-looping Path, sampling before the first keyframe time will produce the first keyframe's transform, and sampling beyond the last keyframe time will produce the last keyframe's transform. When sampling a looped Path, the sample time is "wrapped around" the time extents. Sampling before the first keyframe will cause wrapping in reverse.

geBoolean gePath_WriteToBinaryFile(const gePath *Path, geVFile *F);

Description: Write the path information, in binary format, to a file.

Returns: GE_TRUE if the output operation is successful. If any error occurs, GE_FALSE is returned.

Remarks: The file must be opened before calling this function. All path information is output to the file. This is the recommended method of writing path information to a file.

geBoolean gePath_WriteToFile(const gePath *Path, geVFile *F);

Description: Write the path information, in text format, to a file.

Returns: GE_TRUE if the output operation is successful. If any error occurs, GE_FALSE is returned.

Remarks: The file must be opened before calling this function. All path information is output to the file.

This function is obsolete and should be used for backward compatibility only. Text format will be removed in a future version. Text format requires more space to store and more time to save and load than does binary format. New programs should use gePath_WriteToBinaryFile.