diff options
Diffstat (limited to 'sdk/rwsdk/include/d3d8/rtanim.h')
| -rw-r--r-- | sdk/rwsdk/include/d3d8/rtanim.h | 638 |
1 files changed, 638 insertions, 0 deletions
diff --git a/sdk/rwsdk/include/d3d8/rtanim.h b/sdk/rwsdk/include/d3d8/rtanim.h new file mode 100644 index 00000000..4def7f1f --- /dev/null +++ b/sdk/rwsdk/include/d3d8/rtanim.h @@ -0,0 +1,638 @@ +#ifndef RTANIM_H +#define RTANIM_H + +#include <rtanim.rpe> /* automatically generated header file */ + +#define rtANIMSTREAMCURRENTVERSION 0x100 + +/* Doxygen plugin groups. */ + +/** + * \defgroup rtanim RtAnim + * \ingroup animtools + * + * Animation Toolkit for RenderWare Graphics. + */ + +/** + * \ingroup rtanim + * Typedef for struct \ref RtAnimAnimation. + */ +typedef struct RtAnimAnimation RtAnimAnimation; + +/* + * The following CallBacks are needed for each interpolation scheme. + * See RtAnimInterpolatorInfo. + */ + +/** + * \ingroup rtanim + * \ref RtAnimKeyFrameApplyCallBack + * defines a callback function for converting + * an interpolated animation keyframe into the required result. + * + * \param result Void pointer to store the output of the conversion. + * \param voidIFrame Void pointer to the keyframe and should be cast + * to the interpolated keyframe type this callback + * is for. + */ +typedef void (*RtAnimKeyFrameApplyCallBack) (void *result, void *voidIFrame); + +/** + * \ingroup rtanim + * \ref RtAnimKeyFrameBlendCallBack + * defines a callback function for blending between two + * interpolated keyframes by the given blend factor. This is used for + * blending the states of two different \ref RtAnimInterpolator objects. + * The \ref RtAnimKeyFrameInterpolateCallBack is used for interpolating + * actual animation keyframes into an interpolated frame. + * + * \param voidOut Void pointer to store the output of the blend. + * \param voidIn1 Void pointer containing the first input + * interpolated keyframe. + * \param voidIn2 Void pointer containing the second input + * interpolated keyframe. + * \param alpha \ref RwReal containing the blend factor. + */ +typedef void (*RtAnimKeyFrameBlendCallBack) (void *voidOut, void *voidIn1, + void *voidIn2, RwReal alpha); + +/** + * \ingroup rtanim + * \ref RtAnimKeyFrameInterpolateCallBack + * defines a callback function for interpolating between two + * animation keyframes according to the given time. The output is + * an interpolated frame object residing in an \ref RtAnimInterpolator + * and will usually have the same structure as the keyframe apart from + * the header data (\ref RtAnimInterpFrameHeader). + * + * \param voidOut Void pointer for the output of the interpolation. + * \param voidIn1 Void pointer containing the first input keyframe. + * \param voidIn2 Void pointer containing the second input keyframe. + * \param time \ref RwReal containing the time at which to interpolate. + */ +typedef void (*RtAnimKeyFrameInterpolateCallBack) (void *voidOut, void *voidIn1, + void *voidIn2, RwReal time); + +/** + * \ingroup rtanim + * \ref RtAnimKeyFrameAddCallBack + * defines a callback function for adding two interpolated + * keyframes together. This is used when adding the states of two + * \ref RtAnimInterpolator objects, such as when adding a delta animation + * to a base animation. + * + * \param voidOut Void pointer for the output interpolated frame. + * \param voidIn1 Void pointer containing the first input + * interpoalted keyframe. + * \param voidIn2 Void pointer containing the second input + * interpolated keyframe. + */ +typedef void (*RtAnimKeyFrameAddCallBack) (void *voidOut, void *voidIn1, + void *voidIn2); + +/** + * \ingroup rtanim + * \ref RtAnimKeyFrameMulRecipCallBack + * defines a callback function for multiplying a keyframe + * by the inverse of another keyframe. This is used for creating delta + * animations. + * + * \param voidFrame Void pointer for the keyframe to be modified. + * \param voidStart Void pointer for the start keyframe to take the reciprocal of. + */ +typedef void (*RtAnimKeyFrameMulRecipCallBack) + (void *voidFrame, void *voidStart); + +/** + * \ingroup rtanim + * \ref RtAnimKeyFrameStreamReadCallBack + * defines a callback function for reading in keyframes + * from an \ref RwStream for the given animation. + * + * \param stream Pointer to the \ref RwStream to read the keyframes from. + * \param animation Pointer to the \ref RtAnimAnimation to read the keyframes into. + * + * \return Pointer to the \ref RtAnimAnimation. + */ +typedef RtAnimAnimation * (*RtAnimKeyFrameStreamReadCallBack) + (RwStream *stream, RtAnimAnimation *animation); + +/** + * \ingroup rtanim + * \ref RtAnimKeyFrameStreamWriteCallBack + * defines a callback function for writing keyframes from the + * given animation to an \ref RwStream. + * + * \param animation Pointer to the \ref RtAnimAnimation to write out from. + * \param stream Pointer to the \ref RwStream to write the keyframes to. + * + * \return \ref RwBool, TRUE if successful. + */ +typedef RwBool (*RtAnimKeyFrameStreamWriteCallBack) + (RtAnimAnimation *animation, RwStream *stream); + +/** + * \ingroup rtanim + * \ref RtAnimKeyFrameStreamGetSizeCallBack + * defines a callback function for calculating the binary stream + * size of keyframe data within an animation. + * + * \param animation Pointer to the \ref RtAnimAnimation to calculate sizes from. + * + * \return \ref RwInt32 containing the size, in bytes, of the keyframe data. + */ +typedef RwInt32 (*RtAnimKeyFrameStreamGetSizeCallBack) + (RtAnimAnimation *animation); + +/** + * \ingroup rtanim + * \ref RtAnimInterpolatorInfo + * Typedef for struct \ref RtAnimInterpolatorInfo + */ +typedef struct RtAnimInterpolatorInfo RtAnimInterpolatorInfo; + +/** + * \ingroup rtanim + * \struct RtAnimInterpolatorInfo + * This structure is used to hold information for a keyframe interpolation scheme. + * + * \see RtAnimRegisterInterpolationScheme + * \see RtAnimGetInterpolatorInfo + */ +struct RtAnimInterpolatorInfo +{ + RwInt32 typeID; + /**< The ID of the interpolation scheme. */ + RwInt32 keyFrameSize; + /**< Size, in bytes, of the keyframe structure. */ + RtAnimKeyFrameApplyCallBack keyFrameApplyCB; + /**< Pointer to a function that converts a keyframe to the needed + * format. This function is never called from the \ref rtanim + * toolkit (as the toolit doesn't know the data layout of the + * results) but is stored to ease the creation of overloaded + * interpolators. */ + RtAnimKeyFrameBlendCallBack keyFrameBlendCB; + /**< Pointer to a function that blends between two + * interpolated keyframes, for the purpose of blending + * between the states of two \ref RtAnimInterpolator objects. */ + RtAnimKeyFrameInterpolateCallBack keyFrameInterpolateCB; + /**< Pointer to a function that interpolates between two keyframes + * for a given time in between. */ + RtAnimKeyFrameAddCallBack keyFrameAddCB; + /**< Pointer to a function that adds two interpolated keyframes + * for the purpose of adding the states of two + * \ref RtAnimInterpolator objects. */ + RtAnimKeyFrameMulRecipCallBack keyFrameMulRecipCB; + /**< Pointer to a function that multiplies a keyframe by the + * reciprocal of another. */ + RtAnimKeyFrameStreamReadCallBack keyFrameStreamReadCB; + /**< Pointer to a function that reads the keyframes from a stream + * for a given animation. */ + RtAnimKeyFrameStreamWriteCallBack keyFrameStreamWriteCB; + /**< Pointer to a function that writes the keyframes to a stream for + * a given animation. */ + RtAnimKeyFrameStreamGetSizeCallBack keyFrameStreamGetSizeCB; + /**< Pointer to a function that returns the binary stream size of + * the keyframes for a given animation. */ +}; + + +/** + * \ingroup rtanim + * \struct RtAnimAnimation + * A keyframed animation consists of an array of keyframe structures, + * along with some flags and a duration. + * + * The keyframes should be presented in the order they are needed + * to animate forwards through time. That is, the next keyframe + * at some point in the sequence should correspond to the node whose + * previous two keyframes are next to expire as an interpolation + * pair. + * + * Put another way, the correct ordering can be achieved by sorting + * an unordered keyframe array using the following primary and secondary + * sort keys:- + * + * - time of previous keyframe for node + * - node index + * + * An example is shown in the following diagram, where each vertical bar + * indicates a keyframe point in time. The position of the keyframe + * within the animation sequence is shown by an index to the left of + * each bar. + * + * \verbatim + + t=0 t=duration + node 0 kf0..| kf3.......| kf8....| kf10....| + node 1 kf1..| kf4...| kf6........| kf11....| + node 2 kf2..| kf5.....| kf7..| kf9.........| + + \endverbatim + * + * Each node MUST have an initial keyframe at time = 0.0, and a terminal + * keyframe at time = duration of the animation. + * + * Pointers link all of the keyframes for a particular node backwards + * through time in a list. + * + * \see RtAnimAnimationCreate + */ +struct RtAnimAnimation +{ + RtAnimInterpolatorInfo *interpInfo; + /**< Pointer to interpolation scheme information */ + RwInt32 numFrames; + /**< Number of keyframes in the animation */ + RwInt32 flags; + /**< Specifies details about animation, + * relative translation modes etc. */ + RwReal duration; + /**< Duration of animation in seconds */ + void *pFrames; + /**< Pointer to the animation keyframes */ +}; + +/** + * \ingroup rtanim + * \ref RtAnimKeyFrameHeader + * Typedef for struct RtAnimKeyFrameHeader + */ +typedef struct RtAnimKeyFrameHeader RtAnimKeyFrameHeader; + +/** + * \ingroup rtanim + * \struct RtAnimKeyFrameHeader + * holds header information for a keyframe. All keyframe structures used with + * the overloadable interpolation system should start with this data. + * + * \see RtAnimRegisterInterpolationScheme + */ +struct RtAnimKeyFrameHeader +{ + void *prevFrame; + /**< Previous keyframe for particular hierarchy node */ + RwReal time; + /**< Time at keyframe */ +}; + +/** + * \ingroup rtanim + * \ref RtAnimInterpFrameHeader + * Typedef for struct RtAnimInterpFrameHeader + */ +typedef struct RtAnimInterpFrameHeader RtAnimInterpFrameHeader; + +/** + * \ingroup rtanim + * \struct RtAnimInterpFrameHeader + * is the header for an interpolated animation frame, intermediate + * between a keyframe pair. This structure is intentionally the same size as an + * \ref RtAnimKeyFrameHeader, so that an interpolated frame and key frame data + * block can be otherwise identical. It relies on the + * fact that the prevFrame and time fields of a keyframe header are not + * relevant to an interpolated frame. These fields should therefore not be + * be modified by a custom keyframe interpolator. + * + * \see RtAnimRegisterInterpolationScheme + */ +struct RtAnimInterpFrameHeader +{ + RtAnimKeyFrameHeader *keyFrame1; + /**< Pointer to the first of the current pair of keyframes in + the associated \ref RtAnimAnimation */ + RtAnimKeyFrameHeader *keyFrame2; + /**< Pointer to the second of the current pair of keyframes in + the associated \ref RtAnimAnimation */ +}; + +/** + * \ingroup rtanim + * \ref RtAnimInterpolator + * Typedef for struct \ref RtAnimInterpolator + */ +typedef struct RtAnimInterpolator RtAnimInterpolator; + +/** + * \ingroup rtanim + * \ref RtAnimCallBack + * defines a callback function for use with the + * \ref RtAnimInterpolatorSetAnimCallBack and + * \ref RtAnimInterpolatorSetAnimLoopCallBack functions. + * + * \param animInstance + * A pointer to the \ref RtAnimInterpolator structure. + * + * \param data Void pointer for user-defined data. + * You can use this to pass your own data + * structure(s) to the callback function. + * + * \see RtAnimInterpolatorSetAnimCallBack + * \see RtAnimInterpolatorSetAnimLoopCallBack + * + */ + +typedef RtAnimInterpolator * (*RtAnimCallBack) + (RtAnimInterpolator *animInstance, + void *data); + +/** + * \ingroup rtanim + * \struct RtAnimInterpolator + * holds the current state for a particular instance of an animation, + * corresponding to a specific point in time. + * + * The current interpolated keyframes are stored in an array after the + * end of this structure. For advanced use, these may be accessed + * using the macro rtANIMGETINTERPFRAME(interpolator, nodeIndex) + * which takes a pointer to the interpolator and the node index + * for the interpolated keyframe required. + * + * \see \ref RtAnimInterpolatorCreate + * \see \ref RtAnimInterpolatorDestroy + * \see \ref RtAnimInterpolatorSetCurrentAnim + * \see \ref RtAnimInterpolatorGetCurrentAnim + * \see \ref RtAnimInterpolatorSetKeyFrameCallBacks + * \see \ref RtAnimInterpolatorSetAnimLoopCallBack + * \see \ref RtAnimInterpolatorSetAnimCallBack + * \see \ref RtAnimInterpolatorCopy + * \see \ref RtAnimInterpolatorSubAnimTime + * \see \ref RtAnimInterpolatorAddAnimTime + * \see \ref RtAnimInterpolatorSetCurrentTime + * \see \ref RtAnimCallBack + */ +struct RtAnimInterpolator +{ + RtAnimAnimation *pCurrentAnim; + /**< Current \ref RtAnimAnimation applied */ + RwReal currentTime; + /**< Current animation time */ + void *pNextFrame; + /**< Next animation keyframe to be played */ + RtAnimCallBack pAnimCallBack; + /**< Animation callback function pointer */ + void *pAnimCallBackData; + /**< Animation callback function user data */ + RwReal animCallBackTime; + /**< Trigger time for callback function */ + RtAnimCallBack pAnimLoopCallBack; + /**< Animation loop callback function pointer */ + void *pAnimLoopCallBackData; + /**< Animation loop callback function data */ + RwInt32 maxKeyFrameSize; + /**< Maximum size of keyframes usable on + * this animation (set at creation time) */ + RwInt32 currentKeyFrameSize; + /**< Size of keyframes in the current + * animation */ + RwInt32 numNodes; + /**< Number of nodes driven by the animation */ + RwBool isSubInterpolator; + /**< Internal use */ + RwInt32 offsetInParent; + /**< Internal use */ + RtAnimInterpolator *parentAnimation; + /**< Internal use */ + + RtAnimKeyFrameApplyCallBack keyFrameApplyCB; + /**< Internal use */ + RtAnimKeyFrameBlendCallBack keyFrameBlendCB; + /**< Internal use */ + RtAnimKeyFrameInterpolateCallBack keyFrameInterpolateCB; + /**< Internal use */ + RtAnimKeyFrameAddCallBack keyFrameAddCB; + /**< Internal use */ +}; + +/* Access to array of interpolated frames occupying a block of memory + * after the end of the RtAnimInterpolator structure. + */ +#define rtANIMGETINTERPFRAME( anim, nodeIndex ) \ + ( (void *)( ( (RwUInt8 *)&(anim[1]) + \ + ((nodeIndex) * \ + anim->currentKeyFrameSize) ) ) ) + +#ifdef __cplusplus +extern "C" +{ +#endif /* __cplusplus */ + + +/* Engine functions */ +extern void +RtAnimAnimationFreeListCreateParams( RwInt32 blockSize, RwInt32 numBlocksToPrealloc ); + +extern RwBool +RtAnimInitialize(void); + +extern RwBool +RtAnimRegisterInterpolationScheme(RtAnimInterpolatorInfo *interpolatorInfo); + +extern RtAnimInterpolatorInfo * +RtAnimGetInterpolatorInfo(RwInt32 typeID); + +/* RtAnimAnimation */ +extern RtAnimAnimation * +RtAnimAnimationCreate(RwInt32 typeID, + RwInt32 numFrames, + RwInt32 flags, + RwReal duration); + +extern RtAnimAnimation * +RtAnimAnimationDestroy(RtAnimAnimation *animation); + +extern RtAnimAnimation * +RtAnimAnimationRead(const RwChar * filename); + +extern RwBool +RtAnimAnimationWrite(RtAnimAnimation *animation, + const RwChar * filename); + +extern RtAnimAnimation * +RtAnimAnimationStreamRead(RwStream *stream); + +extern RwBool +RtAnimAnimationStreamWrite(RtAnimAnimation *animation, + RwStream *stream); + +extern RwInt32 +RtAnimAnimationStreamGetSize(RtAnimAnimation *animation); + +extern RwUInt32 +RtAnimAnimationGetNumNodes(RtAnimAnimation *animation); + +#ifdef RWDEBUG + +extern RwInt32 +RtAnimAnimationGetTypeID(RtAnimAnimation *animation); + +#else /* RWDEBUG */ + +#define RtAnimAnimationGetTypeID(animation) \ + (animation->interpInfo->typeID) + +#endif /* RWDEBUG */ + +/* RtAnimInterpolator */ +extern RtAnimInterpolator * +RtAnimInterpolatorCreate(RwInt32 numNodes, + RwInt32 maxKeyFrameSize); + +extern void +RtAnimInterpolatorDestroy(RtAnimInterpolator *anim); + +extern RwBool +RtAnimInterpolatorSetCurrentAnim(RtAnimInterpolator *animI, + RtAnimAnimation *anim); + + +#ifdef RWDEBUG + +extern RtAnimAnimation * +RtAnimInterpolatorGetCurrentAnim(RtAnimInterpolator *animI); + +#else /* RWDEBUG */ + +#define RtAnimInterpolatorGetCurrentAnim(animI) \ + (animI->pCurrentAnim) + +#endif /* RWDEBUG */ + + +extern RwBool +RtAnimInterpolatorSetKeyFrameCallBacks(RtAnimInterpolator *anim, + RwInt32 keyFrameTypeID); + + +extern void +RtAnimInterpolatorSetAnimLoopCallBack(RtAnimInterpolator *anim, + RtAnimCallBack callBack, + void *data ); + +extern void +RtAnimInterpolatorSetAnimCallBack(RtAnimInterpolator *anim, + RtAnimCallBack callBack, + RwReal time, + void *data ); + +extern RwBool +RtAnimInterpolatorCopy(RtAnimInterpolator *outAnim, + RtAnimInterpolator *inAnim); + +extern RwBool +RtAnimInterpolatorSubAnimTime(RtAnimInterpolator *anim, + RwReal time); + +extern RwBool +RtAnimInterpolatorAddAnimTime(RtAnimInterpolator *anim, + RwReal time); + +extern RwBool +RtAnimInterpolatorSetCurrentTime(RtAnimInterpolator *anim, + RwReal time); + +extern RwBool +RtAnimAnimationMakeDelta(RtAnimAnimation *animation, + RwInt32 numNodes, + RwReal time); + + +extern RwBool +RtAnimInterpolatorBlend(RtAnimInterpolator *outAnim, + RtAnimInterpolator *inAnim1, + RtAnimInterpolator *inAnim2, + RwReal alpha); + +extern RwBool +RtAnimInterpolatorAddTogether(RtAnimInterpolator *outAnim, + RtAnimInterpolator *inAnim1, + RtAnimInterpolator *inAnim2); + +#define RtAnimKeyFrameApplyMacro(animation, out, in) \ +MACRO_START \ +{ \ + (anim)->keyFrameApplyCB((out), (in1), (in2), (time)); \ +} \ +MACRO_STOP + + +#define RtAnimKeyFrameInterpolateMacro(anim, out, in1, in2, time) \ +MACRO_START \ +{ \ + (anim)->keyFrameInterpolateCB((out), (in1), (in2), (time)); \ +} \ +MACRO_STOP + +#define RtAnimKeyFrameBlendMacro(anim, out, in1, in2, fAlpha) \ +MACRO_START \ +{ \ + (anim)->keyFrameBlendCB((out), (in1), (in2), (fAlpha)); \ +} \ +MACRO_STOP + +#define RtAnimKeyFrameAddTogetherMacro(anim, out, in1, in2) \ +MACRO_START \ +{ \ + (anim)->keyFrameAddCB((out), (in1), (in2)); \ +} \ +MACRO_STOP + +#ifdef RWDEBUG +extern void +RtAnimKeyFrameApply(RtAnimInterpolator *animation, + void *result, void *iFrame); + +extern void +RtAnimKeyFrameInterpolate(RtAnimInterpolator *animation, + void *out, void *in1, + void *in2, RwReal time); + +extern void +RtAnimKeyFrameBlend(RtAnimInterpolator *animation, + void *out, + void *in1, + void *in2, + RwReal alpha); + +extern void +RtAnimKeyFrameAddTogether(RtAnimInterpolator *animation, + void *out, void *in1, void *in2); + +#else /* RWDEBUG */ +#define RtAnimKeyFrameApply(animation, out, in) \ + RtAnimKeyFrameApplyMacro(animation, out, in) + +#define RtAnimKeyFrameInterpolate(animation, out, in1, in2, time) \ + RtAnimKeyFrameInterpolateMacro(animation, out, in1, in2, time) + +#define RtAnimKeyFrameBlend(animation, out, in1, in2, alpha) \ + RtAnimKeyFrameBlendMacro(animation, out, in1, in2, alpha) + +#define RtAnimKeyFrameAddTogether(animation, out, in1, in2) \ + RtAnimKeyFrameAddTogetherMacro(animation, out, in1, in2) +#endif /* RWDEBUG */ + +extern RtAnimInterpolator * +RtAnimInterpolatorCreateSubInterpolator( + RtAnimInterpolator *parentAnim, + RwInt32 startNode, + RwInt32 numNodes, + RwInt32 maxKeyFrameSize); + +extern RwBool +RtAnimInterpolatorBlendSubInterpolator(RtAnimInterpolator *outAnim, + RtAnimInterpolator *inAnim1, + RtAnimInterpolator *inAnim2, + RwReal alpha); + +extern RwBool +RtAnimInterpolatorAddSubInterpolator(RtAnimInterpolator *outAnim, + RtAnimInterpolator *mainAnim, + RtAnimInterpolator *subAnim); + +#ifdef __cplusplus +} +#endif /* __cplusplus */ + +#endif /* RTANIM_H */ |