geActor
Description: Actor interface
Source file: …\genesis3d\OpenSource\Source\Actor\actor.h
Functions: AnimationCue, AnimationNudge, AnimationRemoveLastCue, AnimationStep, AnimationStepBoneOptimized, AnimationTestStep, AnimationTestStepBoneOptimized, BlendPose, ClearPose, GetAnimationEvent, GetBoneAttachment, GetBoneBoundingBox, GetBoneExtBox, GetBoneTransform, GetCount, GetDynamicExtBox, GetExtBox, GetLightingOptions, GetMaterial, GetMaterialCount, GetMotionByIndex, GetMotionByName, GetMotionCount, GetMotionName, GetRenderHintExtBox, GetUserData, SetBoneAttachment, SetScale, SetExtBox, SetLightingOptions, SetMaterial, SetPose, SetRenderHintExtBox, SetShadow, SetUserData
Private API Functions (available in API, but best reserved for advanced applications): AddMotion, Attach, Create, CreateRef, DefCreate, DefCreateFromFile, DefCreateRef, DefDestroy, DefHasBoneNamed, DefIsValid, DefWriteToFile, Destroy, Detach, GetActorDef, GetBody, IsValid, Render, RenderPrep, RenderThroughFrustum, SetBlendingType, SetBody,
Types: geActor, geActor_Def, geActor_BlendingType
Addition for Genesis3D v1.6: GetAlpha, GetBoneCount GetBoneExtBoxByIndex, GetBoneTransformByIndex, GeEnvironOptions, GetNonWorldExtBox, GetPosition, GetStaticLightingOptions, SetAlpha, SetEnvironOptions, SetStaticLightingOptions
Genesis3D v1.6 Private API Functions (available in API, but best reserved for advanced applications): DestroyDirect, GetEnvironOptions, SetEnvironOptions,
Notes: view
Types:
A geActor is created from a geActor_Def. Before the actor and can rendered or posed, geActor_RenderPrep must be called on it. There are two way to use an Actor. The first method involves controlling the Actor directly with SetPose and and BlendPose. The second method is to use the animation cuing API to add time based animation cues.
Notes:
from ACTOR.H: A geActor is an instance of an actor definition. The definition is used for the geometry, but all additional settings, such as the bone pose, lighting information, and cuing information is unique for a geActor.
For the curious, the following is private and not part of the API.
A geActor_Def can either be loaded from a file or created from scratch by setting the geBody of the geActor_Def and adding geMotions to it. The geBody and geMotions of the geActor_Def are owned by the geActor_Def after this and will be destroyed when the actor definition is destroyed.]
Notes:
from ACTOR.H: A geActor_Def embodies the geometry (polygon, and bone information), and a library of motions that can be applied to that geometry.
For the curious, the following is private and not part of the API.
typedef enum{
GE_ACTOR_BLEND_LINEAR, // Treats the blending amount as a linear value
GE_ACTOR_BLEND_HERMITE // Applies a parametric smoothing curve to the blending amount
// so that a linear change in BlendAmount parameters will
// result in a smooth (non-linear) change in blending.
} geActor_BlendingType;
typedef struct {
geBoolean UseEnvironmentMapping;
geBoolean Supercede;
geFloat PercentEnvironment;
geFloat PercentMaterial;
geFloat PercentPuppet;
} geEnvironmentOptions;See notes in geActor_SetEnvironOptions for description.
Functions:
GENESISAPI geBoolean GENESISCC geActor_AddMotion(geActor_Def* ActorDefinition, geMotion* M, int * Index);
This function adds geMotion M to geActor_Def ActorDefinition and returns the newly created motion library index Index.
Notes:
from ACTOR.H: Adds a geMotion to the Actor Definition's library. The ActorDefinition becomes responsible for its destruction. returns the library index to the new geMotion.
GENESISAPI geBoolean GENESISCC geActor_AnimationCue(geActor* A, geMotion* Motion, geFloat TimeScaleFactor, geFloat TimeIntoMotion, geFloat BlendTime, geFloat BlendFromAmount, geFloat BlendToAmount, const geXForm3d* MotionTransform);
This function cues up geMotion Motion for geActor A. The cued motion starts playing at offset TimeIntoMotion from the start of the motion and plays out at a time scale of TimeScaleFactor. The motion is blended with other active motions over BlendTime starting from BlendFromAmount and finishing with BlendToAmount. The geXForm3d MotionTransform is applied to the geMotion as a local transform and maybe NULL for no transform.
Returns: GE_TRUE on success, GE_FALSE otherwise. GE_FALSE indicates incomplete initialization of the geActor.
Notes:
from ACTOR.H: Animation Cuing API: high level Actor animation: The principle is that motions can be applied to an actor and the actor will keep track of which motions are currently appropriate. Call _AnimationStep() to compute a new pose for an elapsed time interval. The new pose will take into account all motions that are 'currently' cued up to be set or blended. cue up a new motion. The motion begins at the current time. The motion can be blended in or out over time and time scaled. If the return value is GE_FALSE, the animation was not cued up (failure implies Actor is incompletely initialized).
GENESISAPI geBoolean GENESISCC geActor_AnimationNudge(geActor* A, geXForm3d* Offset);
This function applies the geXForm3d Offset as an offset to geActor A.
Notes:
from ACTOR.H: applies an 'immediate' offset to the animated actor
GENESISAPI geBoolean GENESISCC geActor_AnimationRemoveLastCue(geActor* A);
This function removes the last applied AnimationCue from geActor A. Subsequent application removes earlier cues.
Returns: GE_TRUE if a cue is removed, GE_FALSE if there are no more cues to be removed.
Notes:
from ACTOR.H: removes the last animation cue that was cued up. Can be called repeatedly to successively remove older and older cues. Returns GE_TRUE when a cue was removed, GE_FALSE if there are no cues to remove.
GENESISAPI geBoolean GENESISCC geActor_AnimationStep(geActor* A, geFloat DeltaTime);
This function "steps" the time for geActor A by DeltaTime and reposes the actor in response to all applicable animation cues.
Returns: GE_TRUE on success, GE_FALSE if the Actor is incompletely initialized.
Notes:
from ACTOR.H: applies a time step to actor A. re-poses the actor according to all currently applicable Animation Cues. (failure implies Actor is incompletely initialized)
GENESISAPI geBoolean GENESISCC geActor_AnimationStepBoneOptimized(geActor* A, geFloat DeltaTime, const char * BoneName);
This function steps the time for geActor A by DeltaTime only for the bone indicated by BoneName and its parents and reposes the actor appropriately. If NULL is passed for* BoneName then only the "root" bone is affected.
Notes:
from ACTOR.H: optimized version of geActor_AnimationStep. Limits calculations to the bone named BoneName, and it's parents. BoneName will be correctly computed, but the other bones will be wrong. This is useful for moving and animating an actor that is not actually visible. Rendering and queries will be 'optimized' until the actor is given any pose or animation that doesn't go through geActor_AnimationStepBoneOptimized() or geActor_AnimationTestStepBoneOptimized(). BoneName can be NULL to compute only 'root' bone.
GENESISAPI geBoolean GENESISCC geActor_AnimationTestStep(geActor* A, geFloat DeltaTime);
This function steps the time for geActor A by DeltaTime and reposes the actor in response to all applicable animation cues; but, the time step is only temporary and future geActor_Animation*Step* calls will not take any* Test* calls into account. This is primarily used as a means to check for collision prior to committing to the new pose.
Notes:
from ACTOR.H: applies a 'temporary' time step to actor A. re-poses the actor according to all currently applicable cues. (failure implies Actor is incompletely initialized) DeltaTime is always relative to the the last AnimationStep()
GENESISAPI geBoolean GENESISCC geActor_AnimationTestStepBoneOptimized(geActor* A, geFloat DeltaTime, const char * BoneName);
This function steps the time for geActor A by DeltaTime only for the bone indicated by BoneName and its parents and reposes the actor appropriately. If NULL is passed for* BoneName then only the "root" bone is affected; but, the time step is only temporary and future geActor_Animation*Step* calls will not take any* Test* calls into account. This is primarily used as a means to check for collision prior to committing to the new pose.
Notes:
from ACTOR.H: optimized version of geActor_AnimationTestStep. Limits calculations to the bone named BoneName, and it's/ parents. BoneName will be correctly computed, but the other bones will be wrong. This is useful for moving and animating an actor that is not actually visible. Rendering and queries will be 'optimized' until the actor is given any pose or animation that doesn't go through geActor_AnimationStepBoneOptimized() or geActor_AnimationTestStepBoneOptimized(). BoneName can be NULL to compute only 'root' bone.
GENESISAPI geBoolean GENESISCC geActor_Attach(geActor* Slave, const char *
SlaveBoneName, const geActor* Master, const char * MasterBoneName, const geXForm3d* Attachment);
This function attaches geActor Slave to geActor Master from bone SlaveBoneName on Slave to bone MasterBoneName on Master and orients Slave by transform Attachment relative to master (I think...).
GENESISAPI void GENESISCC geActor_BlendPose(geActor* A, const geMotion* Motion, geFloat Time, const geXForm3d* Transform, geFloat BlendAmount);
This function combines the geMotion Motion with the current pose for geActor A in the amount specified by BlendAmount at a time offset of Time. Transform is used to position the root of A; if it is null then the current position is used.
Returns: nothing.
Notes:
from ACTOR.H: Blends the current pose of the geActor with a new pose using motion M at a time offset of Time. A BlendAmount of 0 will result in the existing pose, A BlendAmount of 1 will result in the new pose from M. The BlendingType set by _SetBlendingType() determines the blending function between 0 and 1. Transform is where to position the root for this pose. if Transform is NULL, the root for the pose is assumed to be the root of the actor.
GENESISAPI void GENESISCC geActor_ClearPose(geActor* A, const geXForm3d* Transform);
This function sets the pose for geActor A back to its default pose and positions the actor at Transform. If Transform is null then the actor is not moved.
Returns: nothing.
Notes:
from ACTOR.H: Poses the actor in its default pose. Transform is where to position the root for this pose. if Transform is NULL, the root for the pose is assumed to be the root of the actor.
GENESISAPI geActor* GENESISCC geActor_Create(geActor_Def* ActorDefinition);
This function creates a new geActor object from geActor_Def ActorDefinition and returns it.
Returns: the newly created geActor.
Notes:
from ACTOR.H: Create an Actor instance associated with the given Actor DefinitionNote from Jeff: The geActor_Create() function increases the reference count of the geActor_Def and returns a pointer to a geActor structure. This structure has a copy of the geActor_Def structure and other values for keeping track of this actor's properties.
GENESISAPI void GENESISCC geActor_CreateRef(geActor* Actor);
This function increments the reference count for geActor Actor by one.
Returns: nothing.
Notes:
from ACTOR.H: Create an additional reference (owner) for the Actor
GENESISAPI geActor_Def* GENESISCC geActor_DefCreate(void);
This function creates a new empty geActor_Def and returns it.
Returns: the newly created geActor_Def.
Notes:
from ACTOR.H: Create an 'empty' Actor Definition.
GENESISAPI geActor_Def* GENESISCC geActor_DefCreateFromFile(geVFile* pFile);
This function creates a new geActor_Def objects from the specified geVFile pFile.
Returns: the newly created geActor_Def.
Notes:
from ACTOR.H: Create an Actor Definition from a file image.Note from Jeff: The geActor_DefCreateFromFile() function loads an actor's body, materials, and motions in to memory and return a pointer to the geActor_Def structure. The geActor_Def structure is basically just a bunch of pointers to the actor's body, materials, and motions.
GENESISAPI void GENESISCC geActor_DefCreateRef(geActor_Def* pActorDefinition);
This function increases the reference count for geActor_Def pActorDefinition by one.
Returns: nothing.
Notes:
from ACTOR.H: Create an additional reference (owner) for the Actor_Definition
GENESISAPI geBoolean GENESISCC geActor_DestroyDirect (geActor** pA);
Added for Genesis3D v1.6
GENESISAPI void GENESISCC geActor_Destroy(geActor**pA);
This function decreases the reference count for geActor pA by one. If the reference count goes to 0 then all resources for pA are freed.
Returns: nothing.
Notes:
from ACTOR.H: Destroy an Actor.Note from Jeff: The geActor_Destroy() function will check to see if there are multiple references to the geActor, if so then it decreases the reference count and returns. If there is only one reference then it destroys the geActor and decreases the geActor_Def reference count. This does not remove the actor's body, materials or motions from memory.
GENESISAPI geBoolean GENESISCC geActor_DefDestroy(geActor_Def** pActorDefinition);
This function decreases the reference count for geActor_Def pActorDefinition by one. If the reference count goes to 0 then all resources for pActorDefinition are freed.
Returns: GE_TRUE if the reference count dropped to 0, GE_FALSE if the reference count, after being reduced by 1, is still greater than 0.
Notes:
from ACTOR.H: Function destroys a geActor_Def (its geBody and its geMotions). Actors that rely on this definition become invalid. Function can fail if there are actors still referencing this definition.Note from Jeff: The geActor_DefDestroy() function will check to see if there are multiple references to the geActor_Def, if so it decreases the reference count and returns GE_FALSE. If there is only one reference then it removes the actor's body, materials, and motions from memory and returns GE_TRUE.
GENESISAPI geBoolean GENESISCC geActor_DefHasBoneNamed(const geActor_Def* Ad, const char * Name);
This function checks to see if geActor_Def contains a bone with the name Name.
Returns: GE_TRUE if the named bone exists, GE_FALSE otherwise.
Notes:
from ACTOR.H: Returns GE_TRUE if the actor definition has a bone named 'Name'
GENESISAPI geBoolean GENESISCC geActor_DefIsValid(const geActor_Def* A);
This function checks that geActor_Def A is a valid, non-NULL object.
GENESISAPI geBoolean GENESISCC geActor_DefWriteToFile(const geActor_Def* A, geVFile* pFile);
This function outputs the geActor_Def A to the geVFile pFile.
Notes:
from ACTOR.H: Writes an existing geActor to a file image. Returns GE_TRUE on success, GE_FALSE on failure.
GENESISAPI void GENESISCC geActor_Detach(geActor* Slave);
This function removes the specified geActor Slave from the attachment specified by an earlier call to geActor_Attach.
Returns: nothing.
GENESISAPI geActor_Def* GENESISCC geActor_GetActorDef(const geActor* A);
This function returns the geActor_Def object associated by geActor A.
Returns: the geActor_Def object.
Notes:
from ACTOR.H: Returns the Actor Definition associated with Actor A
GENESISAPI geFloat GENESISCC geActor_GetAlpha(const geActor* A) ;
Added for Genesis3D v1.6
// LWM_ACTOR_RENDERING:
GENESISAPI geBoolean GENESISCC geActor_GetAnimationEvent(geActor* A, const char **ppEventString);
This function returns the current animation event string for geActor A in ppEventString.
Returns: GE_TRUE if an event string is returned, GE_FALSE otherwise.
Notes:
from ACTOR.H: Return data, if return value is GE_TRUE
GENESISAPI geBody* GENESISCC geActor_GetBody(const geActor_Def* ActorDefinition);
This function returns the geBody associated by geActor_Def ActorDefinition.
Returns: the geBody.
Notes:
from ACTOR.H: Returns a geBody pointer from the geActor
GENESISAPI geBoolean GENESISCC geActor_GetBoneAttachment(const geActor* A, const char * BoneName, geXForm3d* Transform);
This function returns the position and orientation of attachment for the bone indicated by BoneName of geActor A in Transform. (I think...)
GENESISAPI geBoolean GENESISCC geActor_GetBoneBoundingBox(const geActor* A, const char * BoneName, geVec3d* Corner, geVec3d* DX, geVec3d* DY, geVec3d* DZ);
This function returns the current non-axial-aligned bounding box for the bone indicated by BoneName of geActor A. The bounding box is returned as a corner (Corner) and an orientation transform (DX, DY, DZ).
Notes:
from ACTOR.H: Gets the non-axial-aligned bounding box for a given bone (for the current pose). The box is specified by a corner, and a non-normalized orientation transform. Add DX,DY,DZ components of the orientation to get other corners of the box if BoneName is NULL, gets the a general bounding box from the body of the actor if it has been set.
GENESISAPI int geActor_GetBoneCount(const geActor* A);
Added for Genesis3D v1.6
Mod for detailed collision detection
GENESISAPI geBoolean GENESISCC geActor_GetBoneExtBox(const geActor* A, const char * BoneName, geExtBox* ExtBox);
This function returns the current axial-aligned bounding box for the bone indicated by BoneName of geActor A in ExtBox. If BoneName is NULL, the bounding box for the entire actor is returned, if set.
Notes:
from ACTOR.H: Gets the extent box (axial-aligned bounding box) for a given bone (for the current pose) if BoneName is NULL, gets the a general bounding box from the body of the actor if it has been set.
GENESISAPI geBoolean GENESISCC geActor_GetBoneExtBoxByIndex(const geActor* A,
int BoneIndex,
geExtBox* ExtBox);
Added for Genesis3D v1.6
Mod for detailed collision detection
GENESISAPI geBoolean GENESISCC geActor_GetBoneTransform(const geActor* A, const char * BoneName, geXForm3d* Transform);
This function returns the current actor-space to world-space transform for the bone indicated by BoneName of geActor A in Transform. If BoneName is NULL, then it returns the actor's current root transform.
Notes:
from ACTOR.H: Gets the current transform for a single bone in A. (actor space-world space transform) with a NULL BoneName, this returns the current 'root' transform
GENESISAPI geBoolean GENESISCC geActor_GetBoneTransformByIndex(const geActor* A,
int BoneIndex,
geXForm3d*Transform);
Added for Genesis3D v1.6
Mod for detailed collision detection
GENESISAPI int GENESISCC geActor_GetCount(void);
This function returns the number of geActor objects currently existing.
Returns: the result.
Notes:
from ACTOR.H: returns number of actors that are currently created.
GENESISAPI geBoolean GENESISCC geActor_GetDynamicExtBox(const geActor* A, geExtBox* ExtBox);
This function returns the current axial-aligned bounding box for geActor A taking all bones into account and returning the result in ExtBox.
ExtBox is returned with world space coordinates for the bounding box, not values relative to the actor (actor space). I.e. (753, 32, 2450) not (+20, +20, -20). Note: this different from GetExtBox and SetExtBox.
Notes:
from ACTOR.H: Gets the current axial-aligned bounding box for an actor's bone configuration takes all bones into account
GENESISAPI geEnvironmentOptions
GENESISCC geActor_GetEnvironOptions(geActor* A);
Added for Genesis3D v1.6
Gets current environmental mapping options. See discussion in geActor_SetEnvironOptions.
GENESISAPI geBoolean GENESISCC geActor_GetExtBox(const geActor* A, geExtBox* ExtBox);
This function returns the originally assigned axial-aligned non-changing bounding box for geActor A in ExtBox.
ExtBox is returned with actor space values, not world space values. I.e. (+20, +20, -20) not (753, 32, 2450). Note: this different from GetDynamicExtBox. To convert between the two systems, use: WorldSpaceValue - ActorWorldSpacePosition = ActorSpaceValue.
For notes on the engine's use of the Extbox, see SetExtBox.
Notes:
from ACTOR.H: Gets an assigned general non changing bounding box from the actor
GENESISAPI geBoolean GENESISCC geActor_GetLightingOptions(const geActor* A, geBoolean* UseFillLight, geVec3d* FillLightNormal, geFloat* FillLightRed, geFloat* FillLightGreen, geFloat* FillLightBlue, geFloat* AmbientLightRed, geFloat* AmbientLightGreen, geFloat* AmbientLightBlue, geBoolean* UseAmbientLightFromFloor, int * MaximumDynamicLightsToUse, const char ** LightReferenceBoneName, geBoolean* PerBoneLighting);
This function returns the current lighting options for geActor A. The rest of the arguments represent the return values. See geActor_SetLightingOptions for further explanation.
GENESISAPI geBoolean GENESISCC geActor_GetMaterial(const geActor* Actor, int MaterialIndex, geBitmap** Bitmap, geFloat* Red, geFloat* Green, geFloat* Blue);
This function returns the current geBitmap and color settings for geActor Actor at index MaterialIndex.
Notes:
from ACTOR.H: Returns the current material for an instance of an actor
GENESISAPI int GENESISCC geActor_GetMaterialCount(const geActor* A);
This function returns the number of material for geActor A.
Returns: the result.
Notes:
from ACTOR.H: Returns the number of materials for an instance of an actor.
GENESISAPI geMotion* GENESISCC geActor_GetMotionByIndex(const geActor_Def* ActorDefinition, int Index);
This function returns a pointer to the geMotion of geActor_Def ActorDefinition indicated by index Index.
Returns: the geMotion* .
Notes:
from ACTOR.H: Returns a geMotion pointer from the geActors geMotion library. This is an aliased pointer - Not a copy. Changes to this motion will be reflected in the actor. Destroying this return motion will confuse the actor.Index must be in range [0..geActor_GetMotionCount-1]
GENESISAPI geMotion* GENESISCC geActor_GetMotionByName(const geActor_Def* ActorDefinition, const char * Name);
This function returns a pointer to the geMotion of geActor_Def ActorDefinition named Name.
Notes:
from ACTOR.H: Returns a geMotion pointer from the geActors geMotion library. This is an aliased pointer - Not a copy. Changes to this motion will be reflected in the actor. Destroying this return motion will confuse the actor. If there is no motion that matches the given name, the return value will be NULL
GENESISAPI int GENESISCC geActor_GetMotionCount(const geActor_Def* ActorDefinition);
This function returns the number of geMotion objects in the geActor_Def ActorDefinition's geMotion library.
Returns: the result.
Notes:
from ACTOR.H: Returns the number of geMotions in the geActors geMotion library.
GENESISAPI const char * GENESISCC geActor_GetMotionName(const geActor_Def* ActorDefinition, int Index);
This function returns the name of the geMotion object at index Index of geActor_Def ActorDefinition.
Returns: the result.
Notes:
from ACTOR.H: Returns a motion name given an ActorDef and a motion index.
GENESISAPI void GENESISCC geActor_GetNonWorldExtBox(const geActor* A,
geExtBox* ExtBox);
Added for Genesis3D v1.6
// Unlike geActor_GetExtBox, this gets the bounding box in non-world coordinates.
// Whatever you put in with geActor_SetExtBox, you get out with this function.
GENESISAPI void GENESISCC geActor_GetPosition(const geActor* A,
geVec3d *Pos);
Added for Genesis3D v1.6
// Unlike geActor_GetExtBox, this gets the bounding box in non-world coordinates.
// Whatever you put in with geActor_SetExtBox, you get out with this function.
GENESISAPI geBoolean GENESISCC geActor_GetRenderHintExtBox(const geActor* A, geExtBox* Box, geBoolean* Enabled);
This function returns axial-aligned rendering hint bound box for geActor A. If the RenderHintExtBox option is enabled the Enabled is GE_TRUE, otherwise Enabled is false and the geExtBox returned is centered at the actor's root and has 0 dimensions. See _SetRenderHintExtBox for more information.
Notes:
from ACTOR.H: Gets the rendering hint bounding box from the actor. If the RenderHintExtBox is disabled, Enabled is GE_FALSE, and the box returned has zero dimensions, centered at the root position of the actor. If the RenderHintExtBox is enabled, Enabled is GE_TRUE, and the box returned is the one set with _SetRenderHintExtBox, offset by the bone position of the bone named in _SetRenderHintExtBox().
GENESISAPI geBoolean GENESISCC geActor_GetStaticLightingOptions(const geActor* A,
geBoolean* UseAmbientLightFromStaticLights, geBoolean* TestRayCollision, int* MaxStaticLightsToUse);
Added for Genesis3D v1.6
GENESISAPI void * GENESISCC geActor_GetUserData(const geActor* A);
This function returns the pointer previously set with geActor_SetUserData for geActor A.
Returns: the pointer or NULL if no pointer set.
Notes:
from ACTOR.H: Returns the pointer which was set with geActor_SetUserData. NULL if not set.
GENESISAPI geBoolean GENESISCC geActor_IsValid(const geActor* A);
This function checks that geActor A is a valid geActor object.
geBoolean GENESISCC geActor_Render(const geActor* A, geEngine* Engine, geWorld* World, geCamera* Camera);
This function renders the geActor A using geEngine Engine, geWorld World, and geCamera Camera. This function is only available if WORLD.H is included. _RenderPrep must have been called on A previous to any call to _Render.
Notes:
This is NOT a GENESISAPI function.
from ACTOR.H: Draws the geActor. (RenderPrep must be called first)
geBoolean GENESISCC geActor_RenderPrep(geActor* A, geWorld* World);
This function is used to setup the geActor A for rendering under geWorld World. This must be called before any calls to rendering, posing, or world-transform functions.
Notes:
This is NOT a GENESISAPI function.
from ACTOR.H: Prepares the geActor for rendering and posing. Call Once once the actor is fully created. Must be called prior to render/pose/setworldtransform
geBoolean GENESISCC geActor_RenderThroughFrustum(const geActor* A, geEngine* Engine, geWorld* World, geCamera* Camera, Frustum_Info* FInfo);
This function renders the geActor A using geEngine Engine, geWorld World, and geCamera Camera if it intersects the frustrum defined by Frustrum_Info. _RenderPrep must have been called on A previous to any calls to _RenderThroughFrustrum.
Notes:
This is NOT a GENESISAPI function.
from ACTOR.H: Draws the geActor. (RenderPrep must be called first)
GENESISAPI void GENESISCC geActor_SetAlpha(geActor* A,
geFloat Alpha) ;
Added for Genesis3D v1.6
// LWM_ACTOR_RENDERING:
GENESISAPI void GENESISCC geActor_SetBlendingType(geActor* A, geActor_BlendingType BlendingType);
This function sets the geActor_BlendingType for geActor A to BlendingType. geActor_BlendingType sets the blending type used for blending poses and motions.
Returns: nothing.
Notes:
from ACTOR.H: Selects a blending type. BlendingType only affects the meaning of the BlendAmount parameter for the blend functions. Can be changed anytime.
GENESISAPI geBoolean GENESISCC geActor_SetBody(geActor_Def* ActorDefinition, geBody*
geBodyGeometry);
This function sets the geBody for geActor_Def ActorDefinition to geBodyGeometry. Once set the ownership of geBodyGeometry is transferred to ActorDefinition and it must not be destroyed.
Notes:
from ACTOR.H: Give the Actor Definition a Body. geActor becomes responsible for its destruction. Sets up default materials as referenced by the Body.
GENESISAPI geBoolean GENESISCC geActor_SetBoneAttachment(geActor* A, const char * BoneName, geXForm3d* Transform);
This function sets the position and orientation of bone indicated by the name BoneName on geActor A in geXForm3d Transform. (I assume the bone has to already exist, or can a bone be added this way? Also it would seem that the transform must relate to the root point of the bone.)
GENESISAPI void GENESISCC geActor_SetScale(geActor* A, geFloat ScaleX, geFloat ScaleY, geFloat ScaleZ);
This function scales the geActor A by (ScaleX, ScaleY, ScaleZ).
Returns: nothing.
GENESISAPI void GENESISCC geActor_SetEnvironOptions(geActor* A,
geEnvironmentOptions* opts );
Added for Genesis3D v1.6
This function enables pseudo-environmental mapping for an actor. This pseudo-environmental mapping takes a texture and applies it to the surface of the actor in a manner that makes it look like a reflection, making the actor look shiny.
Parameters:
A: The actor to modify
opts->UseEnvironmentMapping: //Set to GE_TRUE for actor-level environmental-mapping
opts->Supercede: See Table. //Toggle for material-level. The material for use with the mapping must be contained in the actor (i.e. included during modeling and compilation). The material name must begin with "env_".
opts->PercentEnvironment: (See Table below)
opts->PercentMaterial: (See Table below).
opts->PercentPuppet: (See Table blow)
Supercede value: "env_" material found: Mapping Coordinates Determined By: True True PercentPuppet and PercentMaterial True False Regular mapping False (doesn't matter) PercentPuppet and PercentEnvironment
To get current settings, use geActor_GetEnvironOptions.
GENESISAPI geBoolean GENESISCC geActor_SetExtBox(geActor* A, const geExtBox* ExtBox, const char * CenterBoxOnThisNamedBone);
This function sets the immutable basic bounding box of geActor A to ExtBox and centers it on the bone indicated by CenterBoxOnThisNamedBone. If* CenterBoxOnThisNameBone is NULL then the root is used.
ExtBox is expected to be actor space values, not world space values. I.e. (+20, +20, -20) not (753, 32, 2450). Note: this different from GetDynamicExtBox. To convert between the two systems, use: WorldSpaceValue - ActorWorldSpacePosition = ActorSpaceValue.
An actors ExtBox is the bounding box that is used in collision detection. Genesis3D does not check for collisions based on the polygon mesh that defines the actor. Instead it checks for a intersection between this extbox and the world geometry. It keeps engine speed up. Users can use the bounding boxes for individual bones (see GetBoxBoundingBox) for higher resolution collision detection--though these box intersections would need to be hand calculated with some other function.
Also, the ExtBox is aligned to world coordinates ("axial alignment"). This means that the box does not rotate with the actor. For example, imagine that one had a long slender box to sized to contain a missle when the actor's transform is at identity (i.e. reset to no rotation's etc.).
If the missle then rotates by 90 degrees, the ends of the missle will stick out of the sides of the box unless the box is resized.
It is not currently possible to have the sides of the box to be other than parallel to the principle axises of the world. So in our example, if the missle were rotated to 45 degrees, we would need to enlarge the bounding box size to contain the entire actor.
Notes:
from ACTOR.H: Sets an assigned general non changing bounding box from the actor
GENESISAPI geBoolean GENESISCC geActor_SetLightingOptions(geActor* A, geBoolean UseFillLight, const geVec3d* FillLightNormal, geFloat FillLightRed, geFloat FillLightGreen, geFloat FillLightBlue, geFloat AmbientLightRed, geFloat AmbientLightGreen, geFloat AmbientLightBlue, geBoolean AmbientLightFromFloor, int
MaximumDynamicLightsToUse, const char * LightReferenceBoneName, geBoolean PerBoneLighting);
Purpose: Sets lighting options for an actor
A: The geActor that is to have lighting options set.
UseFillLight: If GE_TRUE then use a directional fill light to shine onto actor.
FillLightNormal: A vector specifying the direction of a directional fill light.
FillLightRed: Directional fill light's red color (R of RGB) [0 .. 255]
FillLightGreen: Directional fill light's green color (G of RGB) [0 .. 255]
FillLightBlue: Directional fill light's blue color (B of RGB) [0 .. 255]
AmbientLightRed: Overall ambient light's red color (R of RGB) [0 .. 255]
AmbientLightGreen: Overall ambient light's green color (G of RGB) [0 .. 255]
AmbientLightBlue: Overall ambient light's blue color (B of RGB) [0 .. 255]
AmbientLightFromFloor: If GE_TRUE, then the actor lighting value is taken from the lighting of the floor directly beneath the actor, instead of from AmbientLightRed/Green/Blue. If a dynamic light lights the floor, the actor will brighten accordingly - but uniformly. This is a way to approximate the local 'ambient' lighting situation for that actor (i.e. it allows the actor to look dark when standing in shadows.)
MaximumDynamicLightsToUse: Sets the maximum number of dynamic lights to use for the lighting calculations for this actor. Use 0 for none. I assume that lowering this number would improve the rendering time for the geActor. I would guess that the lights that are used are picked based on distance from the geActor.
LightReferenceBoneName: If PerBoneLighting is GE_FALSE, this indicates a bone which will be used to calculate this for the geActor as a whole.
PerBoneLighting: If is GE_TRUE then the lighting attenuation and direction is computed for each bone individually.Notes from Mike Sandige: "If you are using AmbientLightFromFloor option, make sure the reference bone is good. Also be aware that there is a bug with this option: A ray is fired down from the reference bone to the floor, and the light from that point is used... If that bit of floor isn't currently visible, this can result in improper lighting including unexpected blackness." And "The actor will check the lighting on the floor directly beneath it, since you have 'AmbientLightFromFloor' enabled. It uses the light value from the floor instead of the AmbientLight colors you gave. If a dynamic light lights the floor, the actor will brighten accordingly - but uniformly. This is a way to approximate the local 'ambient' lighting situation for that actor."
GENESISAPI geBoolean GENESISCC geActor_SetMaterial(geActor* Actor, int MaterialIndex, geBitmap* Bitmap, geFloat Red, geFloat Green, geFloat Blue);
This function can be used to apply a geBitmap Bitmap and color (Red, Green, Blue) to an individual geActor instance Actor.
Notes:
from ACTOR.H: Allows a material to be overriden in an actor instance
GENESISAPI void GENESISCC geActor_SetPose(geActor* A, const geMotion* Motion, geFloat Time, const geXForm3d* Transform);
This function sets the pose of geActor A to geMotion Motion at time offset Time positioned at Transform. If Transform is NULL, the root of the geActor is used as the position.
Returns: nothing.
Notes:
from ACTOR.H: Poses the actor using given motion M at a time offset of Time. Transform is where to position the root for this pose. If Transform isNULL, the root for the pose is assumed to be the root of the actor.
GENESISAPI geBoolean GENESISCC geActor_SetRenderHintExtBox(geActor* A, const geExtBox* Box, const char * CenterBoxOnThisNamedBone);
This function sets an axial-aligned RenderHintBox for geActor A to Box and centers it about CenterBoxOnThisNameBone. If* CenterBoxOnThisNamedBone is NULL then the root bone is used to center the geExtBox. A RenderHintBox is used to optimize the decision of whether the geActor needs to be rendered. A simple extent-box test can be used rather than a more complex bone-by-bone test if this is set. If any portion of the geActor extends outside of Box and only that portion of the geActor would be visible then it will not be drawn. To disable the RenderHintBox call this with a zeroed geExtBox.
Notes:
from ACTOR.H: Sets a rendering hint bounding box from the actor. Increases performance by enabling the rendering of the actor to occur only if the box is visible. If the box is not visible, a detailed analysis of the actor's current geometry is avoided. This does allow errors to occur: If the actor has a bit of geometry that extends outside this box for some animation, that extended geometry may not be drawn, if the box if off-screen. If the render hint box is not set, the engine will make no conservative assumptions about the visibility of an actor - it will always be drawn if any portion of it is visible. To attach the box to the 'root' bone, pass NULL for CenterBoxOnThisNamedBone. For disabling the hint box: (disabled is default) pass Box with zero mins and maxs
GENESISAPI geBoolean GENESISCC geActor_SetShadow(geActor* A, geBoolean DoShadow, geFloat Radius, const geBitmap* ShadowMap, const char * BoneName);
This function sets the shadowmap option for geActor A. If DoShadow is GE_TRUE then geBitmap ShadowMap is used to create a cylindrical shadowmap about geActor A centered on the bone indicated by BoneName with radius Radius. (I'm just guessing about the cylindrical stuff, maybe I'm totally off. I guess it could be a sphere that would make more sense probably.)
GENESISAPI geBoolean GENESISCC geActor_SetStaticLightingOptions(geActor* A,
geBoolean AmbientLightFromStaticLights, geBoolean TestRayCollision, int MaxStaticLightsToUse);
Added for Genesis3D v1.6
GENESISAPI void GENESISCC geActor_SetUserData(geActorgeActor* A, void * UserData);
This function adds a pointer to userdata to geActor A that can be used to store non-Genesis3D information about an actor.
Returns: nothing.
Notes:
from ACTOR.H: Sets the actors user data
pointer to the given value. For clients only.
Notes from Genesis3d forum (author Jeff):
The geActor_DefCreateFromFile() function loads an actor's body, materials, and motions in to memory and return a pointer to the geActor_Def structure. The geActor_Def structure is basically just a bunch of pointers to the actor's body, materials, and motions.
The geActor_Create() function increases the reference count of the geActor_Def and returns a pointer to a geActor structure. This structure has a copy of the geActor_Def structure and other values for keeping track of this actor's properties.
The geWorld_AddActor() function will increase the reference count of the geActor and copy a reference to the world's actor array. This array is used to keep track of all the actors in the world.
The geWorld_RemoveActor() function will decrease the reference to the geActor and remove it from the world's actor array.
The geActor_Destroy() function will check to see if there are multiple references to the geActor, if so then it decreases the reference count and returns. If there is only one reference then it destroys the geActor and decreases the geActor_Def reference count. This does not remove the actor's body, materials or motions from memory.
The geActor_DefDestroy() function will check to see if there are multiple references to the geActor_Def, if so it decreases the reference count and returns GE_FALSE. If there is only one reference then it removes the actor's body, materials, and motions from memory and returns GE_TRUE.
-------------------------------------------------------------------
Notes from actor.h:
Actor
This object is designed to support character animation.
There are two basic objects to deal with.
Actor Definition (geActor_Def)
A geActor_Def embodies the geometry (polygon, and bone
information),
and a library of motions that can be applied to that geometry.
Actor
A geActor is an instance of an actor definition. The
definition is used for
the geometry, but all additional settings, such as the bone pose,
lighting information,
and cuing information is unique for a geActor.
// GENESIS_PRIVATE_API
An Actor Definition is created either from an existing Actor
Definition file, or from scratch by
first creating a geBody and geMotions and selecting these into an
Actor. If the Actor Definition
is constructed from scratch, the objects selected into it (via
SetBody and AddMotion) are
then 'owned' by the actor and will be destroyed along with the
Actor when it is destroyed.
Of course, when the Actor is loaded from a file, the Body and
Motion it creates as it is
loaded are cleaned up when the Actor is destroyed.
Once an Actor is created, prepare it for rendering and animating
by calling
Actor_RenderPrep(). This must be called (and it must succeed)
before any render or
pose setting functions can be called.
// GENESIS_PUBLIC_API
There are two ways to use an Actor.
Direct Control
One method is to directly control the skeleton configuration.
Use _SetPose() to set its
skeleton using a geMotion animation. The pose is positioned in
world space relative to the
transform given in SetPose(). Whenever a new skeleton pose is
required, call _SetPose()
to reposition the skeleton for a new point in time.
More complex positioning can be achieved by blending more than
one animation. Use
_BlendPose() after a _SetPose() to blend the second geMotion into
the first. Additional
blends can be applied by additional _BlendPose() calls. Each
blend is performed on the
the existing skeleton (the results of any previous blends).
Cuing
Another method is to 'cue' up motions that are applied with
parameterized blending over time.
A cued motion takes effect 'now' in time. The Actor advances in
time and repositions itself
according to its currently cued motions with a call to
_AnimationStep(). AnimationStep()
redefines what the actor thinks 'now' is. This causes historical
cues to be forgotten, and
motions that are no longer valid are cleaned up.
AnimationTestStep() can be used to position
the actor for potential queries with its currently cued motions
at some arbitrary future time
- relative to the last AnimationTestStep() call. AnimationNudge()
applies a given transform
'instantly' to the current actor's cue list. This is usefull for
moving the actor as a
result of a collision with another object.
If a motion contains joint information that does not exactly
match the Actor's skeleton
joints, only the joints that match by name are applied. So a
geMotion can be applied to
a portion of the Actor, or a geMotion that has more joint
information than the skeleton can
be applied and the extra joint information is ignored.
Examples of this: If the Actor is a biped and has no tail, but
the motion is for a
biped with a tail, the geMotion can be applied, but the tail
information will be ignored.
Also if there is a geMot
