geMotion

Source file: …\genesis3d\include\motion.h
(in Genesis3D v1.6 this is located in ..\G3D\Actor\motion.h)

Functions: Create, DeleteEvent, Destroy, GetEventExtents, GetName, GetNextEvent, GetPath, GetPathCount, GetTimeExtents, InsertEvent, SetName, SetupEventIterator

Private API Functions (available in API, but best reserved for advanced applications): AddPath, AddSubMotion, CreateFromFile, GetBaseTransform, GetBlendAmount, GetBlendPath, GetSubMotion, GetSubMotionCount, GetSubMotionNamed, GetNameChecksum, GetNameOfPath, GetPathNamed, GetTimeOffset, GetTransform, GetTimeScale, HasNames, IsValid, RemoveNames, RemoveSubMotion, SampleChannels, SampleChannelsNamed, Sample, SampleNamed, SetBaseTransform, SetBlendPath, SetTimeOffset, SetTimeScale, WriteToBinaryFile, WriteToFile

Types: geMotion

Overview: view 

Additions to Genesis3D v1.6: None

(From the official Genesis3D documentation)

Summary

The Motion module provides support for creating and maintaining lists of named Paths and associated time-indexed events, and methods to sample the animation paths at any arbitrary time.

Overview

A Motion is a set of Paths and an associated list of time-indexed events. The most common use of Motions is to hold Actor animation. See documentation for gePath for more information on individual paths. See documentation for geActor for more information about Actor animations.

Motions are reference counted.

A number of functions return pointers to the Paths or sub motions that are maintained by the Motion object. Clients should not destroy these objects, as they are owned by the Motion. If you want to own a Path that's maintained by a Motion, call gePath_CreateRef to increase the Path's reference count.

Creating and Maintaining Motions

To create a Motion, call geMotion_Create. This will create an initially-empty Motion with with no Paths, Events, or sub motions. The Motion's type (simple or compound) is not set until the first Path or sub motion is added to the Motion. Once a motion's type is set, it cannot be changed.

To add a Path to the Motion, call geMotion_AddPath. There is no way to remove a path from the Motion.

To add a sub motion, call geMotion_AddSubMotion. To remove a sub motion, call geMotion_RemoveSubMotion. See the discussion of compound motions below for more information on sub motions.

To add an event, call geMotion_InsertEvent. To remove an event, call geMotion_DeleteEvent. See the discussion of Events below for more information.

Compound Motions

Instead of individual paths, a motion may contain other motions. This type of motion is called a compound motion and the motions that it contains are called sub motions. Motions that contain other motions are also known as branch motions, and motions that contain path information are called leaf motions. Just like in a tree, a branch may have other branches subordinate to it, and it may also have leaves on it. But leaves are the end of the line.

A sub motion's time offset is its starting time, relative to the parent motion's starting time. So a sub motion that starts when the parent motion starts has a time offset of 0.0f.

Compound motions own their sub motions, and destroy them if the compound motion is destroyed. However, if you remove a sub motion from a compound motion, a pointer to the sub motion is returned and it is the caller's responsibility to destroy it.

Return to Contents

typedef struct geMotion geMotion;

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

Note: The following structures are PRIVATE (not included in the interface). I have included it here only to help me understand the geMotion data structures.

typedef enum {
     MOTION_NODE_UNDECIDED,
     MOTION_NODE_BRANCH,
     MOTION_NODE_LEAF
} geMotion_NodeType;

Return to Contents

typedef struct geMotion_Leaf {
     int                      PathCount;
     int32                  NameChecksum; // checksum based on names and list order
     geTKEvents*     Events;
     geStrBlock *     NameArray;
     gePath**           PathArray;
} geMotion_Leaf;

Return to Contents

typedef struct geMotion_Mixer {
     geFloat           TimeScale; // multipler for time
     geFloat           TimeOffset; // already scaled.
     gePath*          Blend; // path used to interpolate blending amounts.
     geXForm3d    Transform; // base transform for this motion (if TransformUsed==GE_TRUE)
     geBoolean      TransformUsed; // GE_FALSE if there is no base transform.
     geMotion*      Motion;
} geMotion_Mixer;

Return to Contents

geMotion_Branch

typedef struct geMotion_Branch {
     int                          MixerCount;
     int                          CurrentEventIterator;
     geMotion_Mixer*  MixerArray;
} geMotion_Branch;

Return to Contents

typedef struct geMotion {
     char*                          Name;
     int                               CloneCount;
     geBoolean                   MaintainNames;
     geMotion_NodeType  NodeType;
     union {
          geMotion_Leaf       Leaf;
          geMotion_Branch   Branch;
     };
     geMotion*                   SanityCheck;
} geMotion;

Return to Contents

Functions:

GENESISAPI geBoolean GENESISCC geMotion_AddPath(geMotion* M, gePath* P, const char * Name, int * Index);

This function adds the specified gePath P to geMotion M at the specified index naming the path Name. If no name is desired, NULL may be specified.

Returns: GE_TRUE on success, GE_FALSE otherwise.

Notes:
    from MOTION.H: AddPath adds a reference of P to the motion M.  Ownership is shared - The caller must destroy P.

Return to Contents

GENESISAPI geBoolean GENESISCC geMotion_AddSubMotion(geMotion* ParentMotion, geFloat TimeScale, geFloat TimeOffset, geMotion* SubMotion, geFloat StartTime, geFloat StartMagnitude, geFloat EndTime, geFloat EndMagnitude, const geXForm3d* Transform, int * Index);

This function adds geMotion SubMotion to the compound geMotion ParentMotion at time TimeOffset relative the start of ParentMotion.  The time of SubMotion is scaled by TimeScale.  Blending times and magnitudes are specifed by StartTime, StartMagnitude, EndTime, and EndMagnitude. Transform is a transformation matrix which can be used to specify the relative positioning of the SubMotion within the ParentMotion.  The index of SubMotion within ParentMotion is returned in Index.

Returns: GE_TRUE on success, GE_FALSE otherwise

Questions:
    The official Genesis3D documentation states that TimeScale must be between 0 and 1.  I don't think this is correct, TimeScale can definitely not be 0, but I don't see any reason that it can't be greater than 1.  Can it be negative?

Return to Contents

GENESISAPI geMotion* GENESISCC geMotion_Create(geBoolean ManageNames);

This function creates a new geMotion object and returns it.  If ManageNames is GE_TRUE resources are allocated to provide naming of paths, if it is GE_FALSE the resources are not allocated and paths may not be named.

Returns: the newly created geMotion.

Return to Contents

GENESISAPI geMotion* GENESISCC geMotion_CreateFromFile(geVFile* f);

This function creates a new geMotion object from the data in the specified geVFile f.

Returns: the newly created geMotion.

Return to Contents

GENESISAPI geBoolean GENESISCC geMotion_DeleteEvent(geMotion* M, geFloat tKey);

This function deletes the event at at time tKey from geMotion M.

Returns: GE_TRUE on success, GE_FALSE otherwise.

Notes:
    from MOTION.H: Deletes the event

Return to Contents

GENESISAPI void GENESISCC geMotion_Destroy(geMotion* *PM);

This function deletes one from the reference count for geMotion PM.  If the reference count goes to 0 then the resources of PM are all freed.

Return to Contents

GENESISAPI const geXForm3d* GENESISCC geMotion_GetBaseTransform(const geMotion* M, int SubMotionIndex);

This function returns the base transformation  for the submotion of geMotion M at index SubMotionIndex.

Return to Contents

GENESISAPI geFloat GENESISCC geMotion_GetBlendAmount(const geMotion* M, int SubMotionIndex, geFloat Time);

This function returns the blend amount for the submotion of geMotion M specifed by SubMotionIndex at the time Time relative to M.

Returns: the blend amount.

Notes:
    from MOTION.H: Get blending amount for a particular submotion.  The Time parameter is parent-relative.

Return to Contents

GENESISAPI gePath* GENESISCC geMotion_GetBlendPath(const geMotion* M, int SubMotionIndex);

This function returns the blending path for the submotion of geMotion M specified by SubMotionIndex.  The times in the blending path are relative to the submotion start time.

Returns: the blending path.

Notes:
    from MOTION.H: Get blending path.  The keyframe times in the blend path are relative to the submotion.

Return to Contents

GENESISAPI geBoolean GENESISCC geMotion_GetEventExtents(const geMotion* M, geFloat* FirstEventTime, geFloat* LastEventTime);

This function returns the times of the first and last events in geMotion M.

Returns: GE_TRUE if there is at least one event in M, GE_FALSE otherwise.

Notes:
    from MOTION.H: returns the time associated with the first and last events. returns GE_FALSE if there are no events (and Times are not set)

Return to Contents

GENESISAPI const char * GENESISCC geMotion_GetName(const geMotion* M);

This function returns the name associated with geMotion M.

Returns: the name or NULL if there is no name.

Return to Contents

GENESISAPI int32 GENESISCC geMotion_GetNameChecksum(const geMotion* M);

This function returns the checksom of geMotion M's name pool.  This only seems to have any internal use.

Return to Contents

GENESISAPI const char * GENESISCC geMotion_GetNameOfPath(const geMotion* M, int Index);

This function returns the name of the gePath at index Index of geMotion M.  If M is a compound motion, NULL is returned.

Returns: the name of the gePath or NULL.

Return to Contents

GENESISAPI geBoolean GENESISCC geMotion_GetNextEvent(geMotion* M, geFloat* pTime, const char * *ppEventString);

This function iterates over the list of events of geMotion M returning the time of the event in pTime and the event string ppEventString.

Returns: GE_TRUE if an event is returned, GE_FALSE if there are no more events to return.

Notes:
    from MOTION.H: Iterates from StartTime to EndTime as setup in geMotion_SetupEventIterator() and for each event between these times [StartTime,EndTime) this function will return Time and EventString returned for that event and the iterator will be positioned for the next search.  When there are no more events in the range, this function will return GE_FALSE (Time will be 0 and ppEventString will be empty).

Return to Contents

GENESISAPI gePath* GENESISCC geMotion_GetPath(const geMotion* M, int Index);

This function returns the gePath at index Index of geMotion M.  This function does not increase the reference count of the gePath and so the returned gePath must not be destroyed unless the caller increases the reference count.

Returns: the gePath.

Return to Contents

GENESISAPI int GENESISCC geMotion_GetPathCount(const geMotion* M);

This function returns the number of gePath objects contained by geMotion M.

Return to Contents

GENESISAPI gePath* GENESISCC geMotion_GetPathNamed(const geMotion* M, const char * Name);

This function returns the gePath named Name in geMotion M.    This function does not increase the reference count of the gePath and so the returned gePath must not be destroyed unless the caller increases the reference count.

Returns: the gePath.

Notes:
    from MOTION.H: the returned Paths from _Get functions should not be destroyed. if ownership is desired, call gePath_CreateRef() to create another owner. an 'owner' has access to the object regardless of the number of other owners, and an owner must call the object's destroy method to relinquish ownership

Return to Contents

GENESISAPI geMotion* GENESISCC geMotion_GetSubMotion(const geMotion* M, int Index);

This function returns the sub motion at index Index of geMotion M.  This function does not increase the reference count of the geMotion and so the returned geMotion must not be destroyed unless the caller increase the reference count.

Returns: the sub motion.

Notes:
    from MOTION.H: the returned motions from these _Get functions should not be destroyed. if ownership is desired, call geMotion_CreateRef() to create another owner. an 'owner' has access to the object regardless of the number of other owners, and an owner must call the object's destroy method to relinquish ownership.

Return to Contents

GENESISAPI int GENESISCC geMotion_GetSubMotionCount(const geMotion*M);

This function returns the number of sub motions of geMotion M.

Returns: the number of sub motions, or 0 if M is not a compound motion.

Notes:
    from MOTION.H: support for compound motions.  A motion can either have sub-motions, or be single motion. these functions support motions that have sub-motions.

Return to Contents

GENESISAPI geMotion* GENESISCC geMotion_GetSubMotionNamed(const geMotion* M, const char * Name);

This function returns the sub motion of geMotion M named Name.  This function does not increase the reference count of the geMotion and so the returned geMotion must not be destroyed unless the caller increase the reference count.

Return to Contents

GENESISAPI geBoolean GENESISCC geMotion_GetTimeExtents(const geMotion* M, geFloat* StartTime, geFloat* EndTime);

This function returns the start and end times of the geMotion M.  If M is a compound motion, the start time of the first motion and end time of the last motion with scaling applied are returned.  If M is not a compound motion then the start time of the earliest path and the end time of the latest path are returned.

Returns: GE_TRUE if there are paths or sub motions in the motion, GE_FALSE otherwise.

Notes:
    from MOTION.H: gets time of first key and time of last key (as if motion did not loop) if there are no paths in the motion: returns GE_FALSE and times are not set otherwise returns GE_TRUE. For a compound motion, GetTimeExtents will return the extents of the scaled submotions. For a single motion, no scaling is applied.

Return to Contents

GENESISAPI geFloat GENESISCC geMotion_GetTimeOffset(const geMotion* M, int SubMotionIndex);

This function returns the originally set TimeOffset of the sub motion at SubMotionIndex of the geMotion M.

Returns: the time offset.

Notes:
    from MOTION.H: Get/Set submotion time offset.  The time offset is the offset into the compound (parent) motion at which the submotion should start.

Return to Contents

GENESISAPI geFloat GENESISCC geMotion_GetTimeScale(const geMotion* M, int SubMotionIndex);

This function returns the original set TimeScale of the sub motion at SubMotionIndex of the geMotion M.

Returns: the time scale.

Notes:
    from MOTION.H: Get/Set submotion time scale.  Time scaling is applied to the submotion after the TimeOffset is applied.  The formula is:  (CurrentTime - TimeOffset)* TimeScale

Return to Contents

GENESISAPI geBoolean GENESISCC geMotion_GetTransform(const geMotion* M, geFloat Time, geXForm3d* Transform);

This function returns the blending of the base transforms of all sub motions of the geMotion M at time Time.

Return to Contents

GENESISAPI geBoolean GENESISCC geMotion_HasNames(const geMotion* M);

This function checks whether the geMotion M supports names.

Returns: GE_TRUE if M supports names, GE_FALSE otherwise.

Return to Contents

GENESISAPI geBoolean GENESISCC geMotion_InsertEvent(geMotion* M, geFloat tKey, const char * String);

This function inserts an event string String at time tKey into the geMotion M.

Returns: GE_TRUE on success, GE_FALSE otherwise.

Notes:
    from MOTION.H: Inserts the new event and corresponding string. Only one event is allowed per time key.

Return to Contents

GENESISAPI geBoolean GENESISCC geMotion_IsValid(const geMotion* M);

This function checks to see if M is a valid geMotion.  This doesn't seem to be of all that much use externally.

Returns: GE_TRUE if the motion is valid, GE_FALSE otherwise.

Return to Contents

GENESISAPI geBoolean GENESISCC geMotion_RemoveNames(geMotion* M);

This function deletes all names from the paths in geMotion M.  M will no longer support named paths after this function is called and this is not reversible.  M must be a simple motion.

Returns: GE_TRUE if successful, GE_FALSE otherwise.

Return to Contents

GENESISAPI geMotion* GENESISCC geMotion_RemoveSubMotion(geMotion* ParentMotion, int SubMotionIndex);

This function removes the sub motion of geMotion ParentMotion indicated by SubMotionIndex and returns it.

Returns: the sub motion removed or NULL if unsuccessful.

Return to Contents

GENESISAPI void GENESISCC geMotion_Sample(const geMotion* M, int PathIndex, geFloat Time, geXForm3d* Transform);

This function returns the transform of the specified path PathIndex of M at time Time.  If M is a compound motion then the indexed path of all sub motions are blended using the leaf motions blending and scaling values and the blended transform is returned.  The function will fail if the specifed path does not exist in all leafs of the motion.

Return to Contents

GENESISAPI void GENESISCC geMotion_SampleChannels(const geMotion* M, int PathIndex, geFloat Time, geQuaternion* Rotation, geVec3d* Translation);

This function returns the positional transformation in Translation and rotational transformation in geQuaternion Rotation of the specified path PathIndex of M at time Time.  If M is a compound motion then the indexed path of all sub motions are blended using the leaf motions blending and scaling values and the blended transform is returned.  The function will fail if the specifed path does not exist in all leafs of the motion.

Return to Contents

GENESISAPI geBoolean GENESISCC geMotion_SampleChannelsNamed(const geMotion* M, const char * PathName, geFloat Time, geQuaternion* Rotation, geVec3d* Translation);

GENESISAPI geBoolean GENESISCC geMotion_SampleNamed(const geMotion* M, const char * PathName, geFloat Time, geXForm3d* Transform);

This function returns the transform of the named path PathName of M at time Time.  If M is a compound motion then the named path of all sub motions are blended using the leaf motions blending and scaling values and the blended transform is returned.

Returns: GE_TRUE if the named path exists in all leafs, GE_FALSE otherwise.

Return to Contents

GENESISAPI geBoolean GENESISCC geMotion_SetBaseTransform(geMotion* M, int SubMotionIndex, geXForm3d* BaseTransform);

This function sets the base transform of the sub motion specified by index SubMotionIndex of M to BaseTransform.

Returns: GE_TRUE on success, GE_FALSE otherwise.

Return to Contents

GENESISAPI geBoolean GENESISCC geMotion_SetBlendPath(geMotion* M, int SubMotionIndex, gePath* Blend);

This function sets the blend path of the sub motion specified by index SubMotionIndex of M to Blend.

Returns: GE_TRUE on success, GE_FALSE otherwise.

Return to Contents

GENESISAPI geBoolean GENESISCC geMotion_SetName(geMotion* M, const char * Name);

This function sets the name of geMotion M to Name.

Returns: GE_TRUE on success, GE_FALSE otherwise.

Return to Contents

GENESISAPI geBoolean GENESISCC geMotion_SetTimeOffset(geMotion* M, int SubMotionIndex, geFloat TimeOffset);

This function sets the time offset of the sub motion specified by index SubMotionIndex of geMotion M to TimeOffset.

Returns: GE_TRUE on success, GE_FALSE otherwise.

Return to Contents

GENESISAPI geBoolean GENESISCC geMotion_SetTimeScale(geMotion* M, int SubMotionIndex, geFloat TimeScale);

This function sets the time scale of the sub motion specified by index SubMotionIndex of geMotion M to TimeScale.

Returns: GE_TRUE on success, GE_FALSE otherwise.

Return to Contents

GENESISAPI void GENESISCC geMotion_SetupEventIterator(geMotion* M, geFloat StartTime, geFloat EndTime);

This function initializes the event iterator of geMotion M to start at StartTime and stop before EndTime.

Returns: nothing.

Notes:
    from MOTION.H: For searching or querying the array for events between two times times are compaired [StartTime,EndTime), '[' is inclusive, ')' is non-inclusive.  This prepares the geMotion_GetNextEvent() function.

Return to Contents

GENESISAPI geBoolean GENESISCC geMotion_WriteToBinaryFile(const geMotion* M, geVFile* pFile);

This function writes the data of geMotion M to geVFile pFile in binary format.

Returns: GE_TRUE on success, GE_FALSE otherwise.

Return to Contents

GENESISAPI geBoolean GENESISCC geMotion_WriteToFile(const geMotion* M, geVFile* f);

This function writes the data of geMotion M to geVFile f in ascii format.

Returns: GE_TRUE on success, GE_FALSE otherwise.

Return to Contents