actor.h

3D游戏场景编辑器

GENESISAPI geBoolean GENESISCC geActor_GetBoneTransform(const geActor *A, const char *BoneName, geXForm3d *Transform);
	
	// 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_GetBoneExtBox(const geActor *A,
										 const char *BoneName,geExtBox *ExtBox);

	// 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 geBoolean GENESISCC geActor_GetBoneBoundingBox(const geActor *A,
														 const char *BoneName,
														 geVec3d *Corner,
														 geVec3d *DX,
														 geVec3d *DY,
														 geVec3d *DZ);

	// Gets the current axial-aligned bounding box for an actor's bone configuration
	// takes all bones into account
GENESISAPI geBoolean GENESISCC geActor_GetDynamicExtBox( const geActor *A, geExtBox *ExtBox);
	
	// Gets an assigned general non changing bounding box from the actor
GENESISAPI geBoolean GENESISCC geActor_GetExtBox(const geActor *A, geExtBox *ExtBox);

	// Sets an assigned general non changing bounding box from the actor
GENESISAPI geBoolean GENESISCC geActor_SetExtBox(geActor *A, const geExtBox *ExtBox,
					const char *CenterBoxOnThisNamedBone);		// NULL uses root position of actor

	// 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_GetRenderHintExtBox(const geActor *A, geExtBox *Box, geBoolean *Enabled);

	// 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_SetRenderHintExtBox(geActor *A, const geExtBox *Box,
												const char *CenterBoxOnThisNamedBone );


	// Returns the pointer which was set with geActor_SetUserData.  NULL if not set.
GENESISAPI void *GENESISCC geActor_GetUserData(const geActor *A);

	// Sets the actors user data pointer to the given value.  For clients only.
GENESISAPI void GENESISCC geActor_SetUserData(geActor *A, void *UserData);


//--------------------------------------------------------------------------------
//   Posing and Rendering
//--------------------------------------------------------------------------------

// GENESIS_PRIVATE_APIS

#ifdef GE_WORLD_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_RenderPrep( geActor *A, geWorld *World);

	// Draws the geActor.  (RenderPrep must be called first)
geBoolean GENESISCC geActor_RenderThroughFrustum(const geActor *A, geEngine *Engine, geWorld *World, geCamera *Camera, Frustum_Info *FInfo);
geBoolean GENESISCC geActor_Render(const geActor *A, geEngine *Engine, geWorld *World, geCamera *Camera);
#endif

// GENESIS_PUBLIC_APIS

	// 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 void GENESISCC geActor_ClearPose(geActor *A, const geXForm3d *Transform);

	// 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 is NULL, the root for the pose is assumed to be the root of the actor.
GENESISAPI void GENESISCC geActor_SetPose(geActor *A, const geMotion *Motion, geFloat Time, const geXForm3d *Transform);

	// 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_BlendPose(geActor *A, const geMotion *Motion, geFloat Time,
						const geXForm3d *Transform, geFloat BlendAmount);


GENESISAPI geBoolean GENESISCC geActor_GetBoneAttachment(const geActor *A, const char *BoneName, geXForm3d *Transform);
GENESISAPI geBoolean GENESISCC geActor_SetBoneAttachment(geActor *A, const char *BoneName, geXForm3d *Transform);

// GENESIS_PRIVATE_APIS

GENESISAPI geBoolean GENESISCC geActor_Attach( geActor *Slave,  const char *SlaveBoneName,
						const geActor *Master, const char *MasterBoneName, 
						const geXForm3d *Attachment);

GENESISAPI void GENESISCC geActor_Detach(geActor *Slave);


// GENESIS_PUBLIC_APIS
GENESISAPI geBoolean GENESISCC geActor_SetLightingOptions(geActor *A,
									geBoolean UseFillLight,				// GE_TRUE or GE_FALSE
									const geVec3d *FillLightNormal,		// normalized vector
									geFloat FillLightRed,				// 0 .. 255
									geFloat FillLightGreen,				// 0 .. 255
									geFloat FillLightBlue,				// 0 .. 255
									geFloat AmbientLightRed,			// 0 .. 255
									geFloat AmbientLightGreen,			// 0 .. 255
									geFloat AmbientLightBlue,			// 0 .. 255
									geBoolean AmbientLightFromFloor,	// GE_TRUE or GE_FALSE
									int MaximumDynamicLightsToUse,		// 0 for none
									const char *LightReferenceBoneName, //NULL for root
									geBoolean PerBoneLighting);			
									// if GE_TRUE, then dynamic lighting attenuation and direction is computed
									// for each bone.  if GE_FALSE, then the computations are relative to the 
									// single bone named by the LightReferenceBoneName

GENESISAPI geBoolean GENESISCC geActor_GetLightingOptions(const geActor *A,
									geBoolean *UseFillLight,			// GE_TRUE or GE_FALSE
									geVec3d *FillLightNormal,			// normalized vector
									geFloat *FillLightRed,				// 0 .. 255
									geFloat *FillLightGreen,			// 0 .. 255
									geFloat *FillLightBlue,				// 0 .. 255
									geFloat *AmbientLightRed,			// 0 .. 255
									geFloat *AmbientLightGreen,			// 0 .. 255
									geFloat *AmbientLightBlue,			// 0 .. 255
									geBoolean *UseAmbientLightFromFloor,// GE_TRUE or GE_FALSE
									int *MaximumDynamicLightsToUse,		
									const char **LightReferenceBoneName,
									geBoolean *PerBoneLighting);		// NULL for root


GENESISAPI void GENESISCC geActor_SetScale(geActor *A, geFloat ScaleX,geFloat ScaleY,geFloat ScaleZ);

GENESISAPI geBoolean GENESISCC geActor_SetShadow(geActor *A, 
						geBoolean DoShadow, 
						geFloat Radius,
						const geBitmap *ShadowMap,
						const char * BoneName);

//  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_AnimationCue( 
		geActor *A,						// actor to apply animation to
		geMotion *Motion,				// motion to Cue
		geFloat TimeScaleFactor,		// time scale to apply to cued motion
		geFloat TimeIntoMotion,			// time offset to begin motion with (Not TimeScaled)
		geFloat BlendTime,				// time to apply a blend. 
		geFloat BlendFromAmount,		// blend value at current time
		geFloat BlendToAmount,			// blend value after BlendTime time has elapsed
		const geXForm3d *MotionTransform);	// local transform to adjust motion by (NULL implies NO transform)

	// 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_AnimationRemoveLastCue( geActor *A );

	// 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_AnimationStep(geActor *A, geFloat DeltaTime );

	// applies a 'temporary' time step to actor A.  re-poses the actor according to all 
	// currently appliciable cues.  (failure implies Actor is incompletely initialized)
	// DeltaTime is always relative to the the last AnimationStep()
GENESISAPI geBoolean GENESISCC geActor_AnimationTestStep(geActor *A, geFloat DeltaTime);

	// 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 usefull 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_AnimationStepBoneOptimized(geActor *A, geFloat DeltaTime, const char *BoneName );

	// 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 usefull 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_AnimationTestStepBoneOptimized(geActor *A, geFloat DeltaTime, const char *BoneName);


	// applies an 'immediate' offset to the animated actor
GENESISAPI geBoolean GENESISCC geActor_AnimationNudge(geActor *A, geXForm3d *Offset);


GENESISAPI geBoolean GENESISCC geActor_GetAnimationEvent(geActor *A,						
	const char **ppEventString);		// Return data, if return value is GE_TRUE


// GENESIS_PRIVATE_APIS
	// call setscale and setshadow after preparing the actor for rendering (renderprep)


#ifdef __cplusplus
}
#endif


#endif