actor.h

3D游戏场景编辑器

/****************************************************************************************/
/*  ACTOR.H                                                                             */
/*                                                                                      */
/*  Author: Mike Sandige	                                                            */
/*  Description:  Actor interface		                                                */
/*                                                                                      */
/*  The contents of this file are subject to the Genesis3D Public License               */
/*  Version 1.01 (the "License"); you may not use this file except in                   */
/*  compliance with the License. You may obtain a copy of the License at                */
/*  http://www.genesis3d.com                                                            */
/*                                                                                      */
/*  Software distributed under the License is distributed on an "AS IS"                 */
/*  basis, WITHOUT WARRANTY OF ANY KIND, either express or implied.  See                */
/*  the License for the specific language governing rights and limitations              */
/*  under the License.                                                                  */
/*                                                                                      */
/*  The Original Code is Genesis3D, released March 25, 1999.                            */
/*  Genesis3D Version 1.1 released November 15, 1999                                 */
/*  Copyright (C) 1999 WildTangent, Inc. All Rights Reserved           */
/*                                                                                      */
/****************************************************************************************/
/*   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 geMotion for only a left arm, it can be applied and it will only affect
	the left arm of the Actor, and consequently its left hand and fingers, but no other 
	bones that are not children of the affected bones will be changed.

	 	
*/
#ifndef GE_ACTOR_H
#define GE_ACTOR_H

#include "genesis.h"				
#include "basetype.h"
#include "extbox.h"
#include "bitmap.h"

#include "Motion.h"

#ifdef GE_WORLD_H
#include "camera.h"
#include "Frustum.h"
#endif

#include "Body.h"

#ifdef __cplusplus
extern "C" {
#endif

// GENESIS_PUBLIC_APIS

#ifndef GE_ACTOR_ENUMS
#define GE_ACTOR_ENUMS
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;

#endif

typedef struct geActor geActor;			// an instance of an actor
typedef struct geActor_Def geActor_Def;		// the deinition of an actor's geometry/bone structure


// GENESIS_PRIVATE_APIS

//---------------------------------------------------------------------------------
//   Creation/Destruction functions
//---------------------------------------------------------------------------------
	// Create an 'empty' Actor Definition.
GENESISAPI geActor_Def *GENESISCC geActor_DefCreate(void);

	// Create an Actor Definition from a file image.
GENESISAPI geActor_Def *GENESISCC geActor_DefCreateFromFile(geVFile *pFile);

	// Create an additional reference (owner) for the Actor_Definition
GENESISAPI void GENESISCC geActor_DefCreateRef(geActor_Def *pActorDefinition);

	// Destroy a geActor_Def (its geBody and its geMotions)  Actors that rely on this definition become invalid.
	// can fail if there are actors still referencing this definition.
GENESISAPI geBoolean GENESISCC geActor_DefDestroy(geActor_Def **pActorDefinition);

	// Create an Actor instance associated with the given Actor Definition 
GENESISAPI geActor *GENESISCC geActor_Create(geActor_Def *ActorDefinition);

	// Create an additional reference (owner) for the Actor
GENESISAPI void GENESISCC geActor_CreateRef(geActor *Actor);

	// 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_SetBody( geActor_Def *ActorDefinition, geBody *geBodyGeometry);

	// 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_AddMotion(geActor_Def *ActorDefinition, geMotion *M, int *Index);

	// Destroy an Actor.  
GENESISAPI void GENESISCC geActor_Destroy(geActor **pA);

GENESISAPI geBoolean GENESISCC geActor_DefIsValid(const geActor_Def *A);
GENESISAPI geBoolean GENESISCC geActor_IsValid(const geActor *A);

// GENESIS_PUBLIC_APIS
//---------------------------------------------------------------------------------
//   Queries 
//---------------------------------------------------------------------------------
// GENESIS_PRIVATE_APIS

	// In general: Objects retuned from Get functions should not not be destroyed. 
	// if ownership is desired, call the objects _CreateRef() function 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() function to relinquish ownership )

	// Returns the Actor Definition associated with Actor A
GENESISAPI geActor_Def *GENESISCC geActor_GetActorDef(const geActor *A);

	// Writes an existing geActor to a file image.  Returns GE_TRUE on success, GE_FALSE on failure.
GENESISAPI geBoolean GENESISCC geActor_DefWriteToFile(const geActor_Def *A, geVFile *pFile);
	
	// Returns a geBody pointer from the geActor 
GENESISAPI geBody *GENESISCC geActor_GetBody(const geActor_Def *ActorDefinition);

	// Returns GE_TRUE if the actor definition has a bone named 'Name'
GENESISAPI geBoolean GENESISCC geActor_DefHasBoneNamed(const geActor_Def *Ad, const char *Name );

	// Selects a blending type.  BlendingType only affects the meaning of the 
	// BlendAmount parameter for the blend functions.  Can be changed anytime.
GENESISAPI void GENESISCC geActor_SetBlendingType( geActor *A, geActor_BlendingType BlendingType );

// GENESIS_PUBLIC_APIS

	// Returns the number of geMotions in the geActors geMotion library.
GENESISAPI int GENESISCC geActor_GetMotionCount(const geActor_Def *ActorDefinition);

	// 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_GetMotionByIndex(const geActor_Def *ActorDefinition, int Index );

	// 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 geMotion *GENESISCC geActor_GetMotionByName(const geActor_Def *ActorDefinition, const char *Name );

	// Returns a motion name given an ActorDef and a motion index.
GENESISAPI const char *GENESISCC geActor_GetMotionName(const geActor_Def *ActorDefinition, int Index );

	// Returns the number of materials for an instance of an actor.
GENESISAPI int GENESISCC geActor_GetMaterialCount(const geActor *A);

	// Returns the current material for an instance of an actor
GENESISAPI geBoolean GENESISCC geActor_GetMaterial(const geActor *Actor, int MaterialIndex,
										geBitmap **Bitmap, geFloat *Red, geFloat *Green, geFloat *Blue);

	// Allows a material to be overriden in an actor instance
GENESISAPI geBoolean GENESISCC geActor_SetMaterial(geActor *Actor, int MaterialIndex,
										geBitmap *Bitmap,  geFloat Red,  geFloat Green,  geFloat Blue);



	// 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