gePath

Source file: …\genesis3d\OpenSource\Source\Actor\bodyinst.h

Functions: Create, CreateCopy, CreateFromFile, CreateRef, Destroy, DeleteKeyframe, GetKeyframe, GetKeyframeCount, GetKeyframeIndex, GetTimeExtents, InsertKeyframe, ModifyKeyframe, OffsetTimes, Sample, SampleChannels, WriteToBinaryFile, WriteToFile

Types: gePath, gePath_Interpolator

Constants: view

Additions for Genesis3D v1.6: None

Constants:

#define GE_PATH_ROTATION_CHANNEL    1
#define GE_PATH_TRANSLATION_CHANNEL 2
#define GE_PATH_ALL_CHANNELS (GE_PATH_ROTATION_CHANNEL | GE_PATH_TRANSLATION_CHANNEL)

Return to Contents

Types:

typedef struct _gePath gePath;

NOTE: The contents of this structure have been intentionally left out of the interface, by the designers of this module. Think of this as a handle only. 

Return to Contents

gePath_Interpolator

typedef enum{
    GE_PATH_INTERPOLATE_LINEAR  = 0, // linear blend for translation or rotation channel
    GE_PATH_INTERPOLATE_HERMITE,  // hermite cubic spline for translation channel
    GE_PATH_INTERPOLATE_SLERP,   // spherical-linear blend for rotation channel
    GE_PATH_INTERPOLATE_SQUAD,   // higher order blend for rotation channel 'G1' continuity
    //GE_PATH_INTEROPLATE_TRIPOD,   // not supported yet.
    GE_PATH_INTERPOLATE_HERMITE_ZERO_DERIV = 7 // hermite cubic with zero derivative at keyframes ('easing' curve)
}gePath_Interpolator;

Return to Contents

Functions:

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

This function creates a new gePath with the specified gePath_Interpolators for TranslationInterpolation and RotationInterpolation.  If Looped is GE_TRUE then the path is a looped path in which case the first and last points of the path should be identical.

Returns: the newly created gePath.

Notes:
    from PATH.H: creates new gePath. A looping path should have the same first & last point.  The path generator will choose arbitrarily between these points for a sample exactly at the end of the loop.

Return to Contents

GENESISAPI gePath* GENESISCC gePath_CreateCopy(const gePath* P);

This function creates a new gePath as a copy of the specified gePath.

Returns: the newly created gePath.

Return to Contents

GENESISAPI gePath* GENESISCC gePath_CreateFromFile(geVFile* F);

This function creates a new gePath from the specifed geVFile which may be either a binary or ascii path file.

Returns: the newly created gePath.

Notes:
    from PATH.H: loads a file  (binary or ascii)

Return to Contents

GENESISAPI void GENESISCC gePath_CreateRef(gePath* P);

This function increases the reference count for the specifed gePath object by one.

Return to Contents

GENESISAPI void GENESISCC gePath_Destroy(gePath** PP);

This function decreases the reference count for the specified gePath by one.  If the reference count reaches zero then all resources for the gePath are released.

Return: nothing.

Notes:
    from PATH.H: destroys path* PP

Return to Contents

GENESISAPI geBoolean GENESISCC gePath_DeleteKeyframe(gePath* P, int Index, int ChannelMask);

This function deletes the channels specifed by the ChannelMask from the Index indexed keyframe of gePath P.

Returns: GE_TRUE on success, GE_FALSE otherwise.

Notes:
    from PATH.H: deletes the nth keyframe

Return to Contents

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

This function returns a transformation matrix in Matrix for specified index Index and channel mask Channel of the gePath P.  The time for the specified index is also return in Time.

Returns: nothing.

Notes:
    from PATH.H: retrieves keyframe[index], and it's time

Return to Contents

GENESISAPI int GENESISCC gePath_GetKeyframeCount(const gePath* P, int Channel);

This function returns the number of keyframes of type Channel defined in gePath P.

Returns: the result.

Notes:
    from PATH.H: retrieves count of keyframes for a specific channel

Return to Contents

GENESISAPI int GENESISCC gePath_GetKeyframeIndex(const gePath* P, int Channel, geFloat Time);

This function returns the index for the keyframe of type Channel at time Time of gePath P.  If no keyframe exists for the specifed time and channel, -1 is returned.  Note that Channel must be either GE_PATH_ROTATION_CHANNEL or GE_PATH_TRANSLATION_CHANNEL.

Returns: the index, or -1 if specifed keyframe does not exist.

Notes:
    from PATH.H: retrieves the index of the keyframe at a specific time for a specific channel.

Return to Contents

GENESISAPI geBoolean GENESISCC gePath_GetTimeExtents(const gePath* P, geFloat* StartTime, geFloat* EndTime);

This function gets the start and end times for the given gePath P.

Returns: GE_TRUE if keys are defined in P, GE_FALSE and no times if there are no keys defined in the path.

Notes:
    from PATH.H: gets the time for the first and last keys in the path (ignoring looping). if there are no keys, return GE_FALSE and times are not set. returns GE_TRUE if there are keys.

Questions:
    I said start and end time above, PATH.H says time of first and last frame; are these equivalent?  In other words, is there easing before the first frame or after the last frame or does the path simply end?

Return to Contents

GENESISAPI geBoolean GENESISCC gePath_InsertKeyframe(gePath* P, int ChannelMask, geFloat Time, const geXForm3d* Matrix);

This function creates a new keyframe in path P at time T for the channel(s) specified Time as defined by the transform Matrix.

Returns: GE_TRUE on success, GE_FALSE otherwise.

Notes:
    from PATH.H: inserts a keyframe at a specific time.

Return to Contents

GENESISAPI geBoolean GENESISCC gePath_ModifyKeyframe(gePath* P, int Index, int ChannelMask, const geXForm3d* Matrix);

This function updates the keyframe in path P at index Index for the specified channel(s) as defined by the transform Matrix.

Returns: GE_TRUE on success, GE_FALSE otherwise.

Return to Contents

GENESISAPI geBoolean GENESISCC gePath_OffsetTimes(gePath* P, int StartingIndex, int ChannelMask, geFloat TimeOffset);

This function adjusts the time of all keyframes in path P of type ChannelMask starting with StartingIndex to the last frame by TimeOffset.

Returns: GE_TRUE on success, GE_FALSE otherwise.

Notes:
    from PATH.H: slides all samples in path starting with StartingIndex down by TimeOffset

Questions:
    Can TimeOffset be negative (in which case it would move the time up)?  What affect would it have to move a keyframes time so that it occurs earlier than the previous indexed frame?  Are keyframes assigned assumed to be sorted by time?

Return to Contents

GENESISAPI void GENESISCC gePath_Sample(const gePath* P, geFloat Time, geXForm3d* Matrix);

This function returns the transformation Matrix for the path P at time Time.

Returns: nothing.

Notes:
    from PATH.H: returns a transform matrix sampled at 'Time'. p is not const because information is cached in p for next sample

Return to Contents

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

This function returns the Rotation and Translation for the path P at time Time.

Returns: nothing.

Notes:
    from PATH.H: returns a rotation and a translation for the path at 'Time' p is not const because information is cached in p for next sample

Return to Contents

GENESISAPI geBoolean GENESISCC gePath_WriteToBinaryFile(const gePath* P, geVFile* F);

This function writes gePath P out to geVFile F in binary format.

Returns: GE_TRUE on success, GE_FALSE otherwise.

Notes:
    from PATH.H: dumps a minimal binary image for fastest reading

Return to Contents

GENESISAPI geBoolean GENESISCC gePath_WriteToFile(const gePath* P, geVFile* F);

This function writes gePath P out to geVFile in ascii format.

Returns: GE_TRUE on success, GE_FALSE otherwise.

Notes:
    from PATH.H: dumps formatted ascii to the file.

Return to Contents