#include <IGameControl.h>

Class Description

A simple access class for controllers.

IGameControl provides a simplified access to the various key frame controllers used throughout 3ds Max. In 3ds Max a controller needs to be queried for the key interface and then its class ID checked before casting to the appropriate Key class. This class provide the developer with all the keys based on the key type being asked for. As the game engine may only support certain type of max controllers it is far more efficient for a developer to ask IGame for all the Bezier Postion keys then to check with 3ds Max for the controller type. This class also provides direct support for Euler Rotation controllers. The developer can use IGameControl::GetControlType to see if the rotation is Euler and can then can use IGameControlType::IGAME_EULER_X in the appropriate control access type to retrieve the keys.
In 3ds Max some controllers such as TCB, Linear, and Bezier support direct access to their keys. Other controllers are more private and usually base them selves on a float or Point3 controller. If there is no direct access then sampling is the easiest choice. IGame supports two types - Full and Quick. Full samples across the full animation range, whilst Quick only samples where keys are found. The limitation of Quick, is that it does not support IGameControlType::IGAME_TM or controllers that do not set keys.

See also: GMatrix; IGameProperty

Inheritance diagram for IGameControl:

Public Types
enum	MaxControlType { IGAME_UNKNOWN, IGAME_MAXSTD, IGAME_BIPED, IGAME_EULER, IGAME_ROT_CONSTRAINT, IGAME_POS_CONSTRAINT, IGAME_LINK_CONSTRAINT, IGAME_LIST, IGAME_INDEPENDENT_POS, IGAME_MASTER }
	Various 3ds Max controller types. More...

enum	EulerOrder { XYZ, XZY, YZX, YXZ, ZXY, ZYX, XYX, YZY, ZXZ, BAD }
	Euler Orderings. More...

Public Member Functions
virtual	~IGameControl ()
	Destructor. More...

virtual bool	GetBezierKeys (IGameKeyTab &gameKeyTab, IGameControlType Type)=0
	Return the Bezier Keys. More...

virtual bool	GetLinearKeys (IGameKeyTab &gameKeyTab, IGameControlType Type)=0
	Return the Linear Keys. More...

virtual bool	GetTCBKeys (IGameKeyTab &gameKeyTab, IGameControlType Type)=0
	Return the TCB Keys. More...

virtual bool	GetFullSampledKeys (IGameKeyTab &sample, int frameRate, IGameControlType Type, bool Relative=true)=0
	Return the Sampled Keys. More...

virtual bool	GetQuickSampledKeys (IGameKeyTab &sample, IGameControlType Type)=0
	Return the Sampled Keys. More...

virtual bool	GetBezierIGameKey (IGameControlType Type, IGameKey &bezKey, int index)=0
	Return an individual IGameKey. More...

virtual bool	GetTCBIGameKey (IGameControlType Type, IGameKey &tcbKey, int index)=0
	Return an individual IGameKey. More...

virtual bool	GetLinearIGameKey (IGameControlType Type, IGameKey &linearKey, int index)=0
	Return an individual IGameKey. More...

virtual int	GetIGameKeyCount (IGameControlType Type)=0
	Get the total number of keys for this controller. More...

virtual MaxControlType	GetControlType (IGameControlType Type)=0
	Get the controller type. More...

virtual void	GetClassName (IGameControlType Type, MSTR &className)=0
	Get the name of the controller class. More...

virtual bool	IsAnimated (IGameControlType Type)=0
	Access to actual animation. More...

virtual bool	IsLeaf (IGameControlType Type)=0
	Check for sub-controllers. More...

virtual IGameConstraint *	GetConstraint (IGameControlType Type)=0
	Access to the Constraints. More...

virtual EulerOrder	GetEulerOrder ()=0
	Get the order of Rotation. More...

virtual Control *	GetMaxControl (IGameControlType Type)=0
	Get access to the actual max controller. More...

virtual IGameControl *	GetListSubControl (int index, IGameControlType Type)=0
	Access the list controller. More...

virtual int	GetNumOfListSubControls (IGameControlType Type)=0
	Get the number of controllers maintained by the list controller. More...

virtual int	GetNumOfVertControls ()=0
	Get the number of subcontroller tracks maintained by the Master Point controller. More...

virtual IGameControl *	GetVertexControl (int index)=0
	Access the Master Point subcontroller. More...

Additional Inherited Members
Static Public Member Functions inherited from MaxHeapOperators
static UtilExport void *	operator new (size_t size)
	Standard new operator used to allocate objects If there is insufficient memory, an exception will be thrown. More...

static UtilExport void *	operator new (size_t size, const std::nothrow_t &e)
	Standard new operator used to allocate objects if there is insufficient memory, NULL will be returned. More...

static UtilExport void *	operator new (size_t size, const char *filename, int line)
	New operator used to allocate objects that takes the filename and line number where the new was called If there is insufficient memory, an exception will be thrown. More...

static UtilExport void *	operator new (size_t size, int block_type, const char *filename, int line)
	New operator used to allocate objects that takes the type of memory, filename and line number where the new was called If there is insufficient memory, an exception will be thrown. More...

static UtilExport void *	operator new (size_t size, const std::nothrow_t &e, const char *filename, int line)
	New operator used to allocate objects that takes the filename and line number where the new was called If there is insufficient memory, NULL will be returned. More...

static UtilExport void *	operator new (size_t size, unsigned long flags)
	New operator used to allocate objects that takes extra flags to specify special operations If there is insufficient memory, an exception will be thrown. More...

static UtilExport void *	operator new (size_t size, const std::nothrow_t &e, unsigned long flags)
	New operator used to allocate objects that takes extra flags to specify special operations If there is insufficient memory, NULL will be returned. More...

static UtilExport void *	operator new[] (size_t size)
	New operator used to allocate arrays of objects If there is insufficient memory, an exception will be thrown. More...

static UtilExport void *	operator new[] (size_t size, const std::nothrow_t &e)
	New operator used to allocate arrays of objects If there is insufficient memory, NULL will be returned. More...

static UtilExport void *	operator new[] (size_t size, const char *filename, int line)
	New operator used to allocate arrays of objects If there is insufficient memory, an exception will be thrown. More...

static UtilExport void *	operator new[] (size_t size, int block_type, const char *filename, int line)
	New operator used to allocate arrays of objects. More...

static UtilExport void *	operator new[] (size_t size, const std::nothrow_t &e, const char *filename, int line)
	New operator used to allocate arrays of objects If there is insufficient memory, NULL will be returned. More...

static UtilExport void *	operator new[] (size_t size, unsigned long flags)
	New operator used to allocate arrays of objects If there is insufficient memory, an exception will be thrown. More...

static UtilExport void *	operator new[] (size_t size, const std::nothrow_t &e, unsigned long flags)
	New operator used to allocate arrays of objects If there is insufficient memory, NULL will be returned. More...

static UtilExport void	operator delete (void *ptr)
	Standard delete operator used to deallocate an object If the pointer is invalid, an exception will be thrown. More...

static UtilExport void	operator delete (void *ptr, const std::nothrow_t &e)
	Standard delete operator used to deallocate an object If the pointer is invalid, nothing will happen. More...

static UtilExport void	operator delete (void ptr, const char filename, int line)
	Delete operator used to deallocate an object that takes the filename and line number where the delete was called If the pointer is invalid, an exception will be thrown. More...

static UtilExport void	operator delete (void ptr, int block_type, const char filename, int line)
	Delete operator used to deallocate an object that takes the type of memory, filename and line number where the delete was called If the pointer is invalid, an exception will be thrown. More...

static UtilExport void	operator delete (void ptr, const std::nothrow_t &e, const char filename, int line)
	Delete operator used to deallocate an object that takes the filename and line number where the delete was called If the pointer is invalid, nothing will happen. More...

static UtilExport void	operator delete (void *ptr, unsigned long flags)
	Delete operator used to deallocate an object that takes extra flags to specify special operations If the pointer is invalid, an exception will be thrown. More...

static UtilExport void	operator delete (void *ptr, const std::nothrow_t &e, unsigned long flags)
	Delete operator used to deallocate an object that takes extra flags to specify special operations If the pointer is invalid, nothing will happen. More...

static UtilExport void	operator delete[] (void *ptr)
	Standard delete operator used to deallocate an array of objects If the pointer is invalid, an exception will be thrown. More...

static UtilExport void	operator delete[] (void *ptr, const std::nothrow_t &e)
	Standard delete operator used to deallocate an array of objects If the pointer is invalid, nothing will happen. More...

static UtilExport void	operator delete[] (void ptr, const char filename, int line)
	Delete operator used to deallocate an array of objects that takes the filename and line number where the delete was called If the pointer is invalid, an exception will be thrown. More...

static UtilExport void	operator delete[] (void ptr, int block_type, const char filename, int line)
	Delete operator used to deallocate an array of objects that takes the type of memory, filename and line number where the delete was called If the pointer is invalid, an exception will be thrown. More...

static UtilExport void	operator delete[] (void ptr, const std::nothrow_t &e, const char filename, int line)
	Delete operator used to deallocate an array of objects that takes the filename and line number where the delete was called If the pointer is invalid, nothing will happen. More...

static UtilExport void	operator delete[] (void *ptr, unsigned long flags)
	Delete operator used to deallocate an array of objects that takes extra flags to specify special operations If the pointer is invalid, an exception will be thrown. More...

static UtilExport void	operator delete[] (void *ptr, const std::nothrow_t &e, unsigned long flags)
	Delete operator used to deallocate an array of objects that takes extra flags to specify special operations If the pointer is invalid, an exception will be thrown. More...

static UtilExport void *	operator new (size_t size, void *placement_ptr)
	Placement new operator. More...

static UtilExport void	operator delete (void ptr, void placement_ptr)
	Placement delete operator. More...

static UtilExport void *	aligned_malloc (size_t size, size_t alignment)
	Allocates memory on a specified alignment boundary. More...

static UtilExport void *	aligned_realloc (void *ptr, size_t size, size_t alignment)
	Reallocates memory on a specified alignment boundary. More...

static UtilExport void	aligned_free (void *ptr)
	Frees a block of memory that was allocated with aligned_malloc/aligned_realloc. More...

Member Enumeration Documentation

enum MaxControlType

Various 3ds Max controller types.

Enumerator
IGAME_UNKNOWN	An unknown controller type.
IGAME_MAXSTD	A Standard 3ds Max key frame controller.
IGAME_BIPED	A Biped Controller.
IGAME_EULER	An Euler Controller.
IGAME_ROT_CONSTRAINT	A Rotation constraint.
IGAME_POS_CONSTRAINT	A Position constraint.
IGAME_LINK_CONSTRAINT	A Link Constraint.
IGAME_LIST	A List Controller.
IGAME_INDEPENDENT_POS	An Independent Position Controller.
IGAME_MASTER	Master Point Controller.

                            {
             IGAME_UNKNOWN,                  
             IGAME_MAXSTD,                   
             IGAME_BIPED,                    
             IGAME_EULER,                    
             IGAME_ROT_CONSTRAINT,           
             IGAME_POS_CONSTRAINT,           
             IGAME_LINK_CONSTRAINT,          
             IGAME_LIST,                     
             IGAME_INDEPENDENT_POS,          
             IGAME_MASTER,                  
         };

enum EulerOrder

Euler Orderings.

These are the rotation orders for an Euler Controller

Enumerator
XYZ	XYZ Ordering.
XZY	XZY Ordering.
YZX	YZX Ordering.
YXZ	YXZ Ordering.
ZXY	ZXY Ordering.
ZYX	ZYX Ordering.
XYX	XYX Ordering.
YZY	YZY Ordering.
ZXZ	ZXZ Ordering.
BAD	If this is not a Euler Controller.

Constructor & Destructor Documentation

virtual ~IGameControl ( )

inlinevirtual

Destructor.

292 {;}

Member Function Documentation

virtual bool GetBezierKeys	(	IGameKeyTab &	gameKeyTab,
		IGameControlType	Type
	)

pure virtual

Return the Bezier Keys.

IGameControl will check the appropriate control and fill the IGameKeyTab with the Key data. The keys should be accessed in Tab maintained by IGameKey::bezierKey.

Parameters

&gameKeyTab	The Tab to receive the data
Type	The controller type (based on Transform style) to query. This can be one of the following IGAME_POS IGAME_ROT IGAME_SCALE IGAME_FLOAT IGAME_POINT3 IGAME_EULER_X IGAME_EULER_Y IGAME_EULER_Z

Returns: TRUE is the controller was accessed successfully.

virtual bool GetLinearKeys	(	IGameKeyTab &	gameKeyTab,
		IGameControlType	Type
	)

pure virtual

Return the Linear Keys.

IGameControl will check the appropriate control and fill the IGameKeyTab with data

Parameters

&gameKeyTab	The tab to receive the data
Type	The controller type to query. See IGameControl::GetBezierKeys for more info

Returns: TRUE is the controller was accessed successfully.

virtual bool GetTCBKeys	(	IGameKeyTab &	gameKeyTab,
		IGameControlType	Type
	)

pure virtual

Return the TCB Keys.

IGameControl will check the appropriate control and fill the IGameKeyTab with data

Parameters

&gameKeyTab	The tab to receive the data
Type	The controller type to query. See IGameControl::GetBezierKeys for more info

Returns: TRUE is the controller was accessed successfully.

virtual bool GetFullSampledKeys	(	IGameKeyTab &	sample,
		int	frameRate,
		IGameControlType	Type,
		bool	Relative = `true`
	)

pure virtual

Return the Sampled Keys.

IGameControl will sample the control based on the type supplied. It will sample the node TM , float or point3 controllers. The TM sample will be in the Coord System that defined when initialising IGame. This method will sample the controller across the complete animation range. The method of access can be provided (absolute and relative) It is important to read the 3ds Max sdk docs on Control::GetValue to understand the usage when used with non IGameControlType::IGAME_TM controllers. IGame will still however fill out the respective structures even when the 3ds Max sdk docs mention Matrix3 access It is set to Relative as default, as this was the default for IGameControlType::IGAME_TM usage before the method changed. If you are sampling anything else than IGameControlType::IGAME_TM this should be set to false to behave like the 3ds Max default and IGame before this change.

Parameters

&sample	The tab to receive the data
frameRate	This is the number frames that the controller will be sampled at. It will be converted to Ticks internally
Type	The controller type to query. This can be any of the standard type but also include IGAME_TM
Relative	This defines whether the controller is sampled for relative or absolute values. It defaults to relative true. Please read the max sdk section on Control::GetValue for details on the internal usage.

Returns: TRUE if the controller was accessed successfully.

virtual bool GetQuickSampledKeys	(	IGameKeyTab &	sample,
		IGameControlType	Type
	)

pure virtual

Return the Sampled Keys.

IGameControl will sample the control based on the type supplied. It will sample float or point3 controllers. The TM sample will be in the Coord System that you defined when initialising IGame. This method only samples the controller where a key is Set, so it will not support the IGameControlType::IGAME_TM type. If the controller does not support setting of keys, it will return false. This method will only sample the controller at times where keys exist. This is useful to limit the data where controller can not be accessed directly

Parameters

&sample	The tab to receive the data
Type	The controller type to query. This can be any of the standard type but also include IGAME_TM

Returns: TRUE if the controller was accessed successfully.

virtual bool GetBezierIGameKey	(	IGameControlType	Type,
		IGameKey &	bezKey,
		int	index
	)

pure virtual

Return an individual IGameKey.

Fills out the supplied IGameKey with the bezier data for the key index supplied

Parameters

Type	The controller type to query. See IGameControl::GetBezierKeys for more info
&bezKey
index	The key to retrieve

Returns: TRUE if successful

virtual bool GetTCBIGameKey	(	IGameControlType	Type,
		IGameKey &	tcbKey,
		int	index
	)

pure virtual

Return an individual IGameKey.

Fills out the supplied IGameKey with the TCB data for the key index supplied

Parameters

Type	The controller type to query. See IGameControl::GetBezierKeys for more info
&tcbKey
index	The key to retrieve

Returns: TRUE if successful

virtual bool GetLinearIGameKey	(	IGameControlType	Type,
		IGameKey &	linearKey,
		int	index
	)

pure virtual

Return an individual IGameKey.

Fills out the supplied IGameKey with the Linear data for the key index supplied

Parameters

Type	The controller type to query. See IGameControl::GetBezierKeys for more info
&linearKey
index	The key to retrieve

Returns: TRUE if successful

virtual int GetIGameKeyCount ( IGameControlType Type )

pure virtual

Get the total number of keys for this controller.

This return the total number of keys for the controller supplied, WARNING: support leaf controllers only

Parameters

Type	The controller type to query. See IGameControl::GetBezierKeys for more info

Returns: The total number of keys

virtual MaxControlType GetControlType ( IGameControlType Type )

pure virtual

Get the controller type.

Retrieves what type of IGame Controller it is (based on transformation style)

Parameters

Type	The controller to query. See IGameControl::GetBezierKeys for more info

Returns: The type of controller, It can be one of the following
IGAME_UNKNOWN
IGAME_MAXSTD
IGAME_BIPED
IGAME_ROT_CONSTRAINT
IGAME_POS_CONSTRAINT
IGAME_LINK_CONSTRAINT
IGAME_LIST
IGAME_INDEPENDENT_POS
IGAME_MASTER

virtual void GetClassName	(	IGameControlType	Type,
		MSTR &	className
	)

pure virtual

Get the name of the controller class.

Retrieves the controller class name based on the type

Parameters

Type	The controller to query. See IGameControl::GetBezierKeys for more info
&className	The class name string

virtual bool IsAnimated ( IGameControlType Type )

pure virtual

Access to actual animation.

Indicates whether the IGame Controller actually has animation (based on transformation style)

Parameters

Type	The controller to query. See IGameControl::GetBezierKeys for more info

Returns: TRUE if controller actually has animation; otherwise FALSE

virtual bool IsLeaf ( IGameControlType Type )

pure virtual

Check for sub-controllers.

Indicates whether the IGame Controller is a leaf (has no any sub-controllers or references) controller (based on transformation style)

Parameters

Type	The controller to query. See IGameControl::GetBezierKeys for more info

Returns: TRUE if controller has no any sub-controllers or references; otherwise FALSE

virtual IGameConstraint* GetConstraint ( IGameControlType Type )

pure virtual

Access to the Constraints.

If a controller has a constraint system, then this will provide access to it

Parameters

Type	The controller to check. This can be either of IGAME_POS IGAME_ROT IGAME_TM

Returns: A Pointer to IGameConstraint, or NULL if not available

virtual EulerOrder GetEulerOrder ( )

pure virtual

Get the order of Rotation.

This provides a way of determining the order of rotation for Euler controllers. This is important so that the rotation can be rebuilt correctly on import.
This data is also important when accessing the controller keys. You still access the Euler data bsed on X,Y and Z - but you would use the ordering to work out the meaning of each controller. So if EulerOrder was ZXZ, then controller access would mean x=z, y=x, z=z.

Returns: The order of Rotation. This can be a value from the EulerOrder

virtual Control* GetMaxControl ( IGameControlType Type )

pure virtual

Get access to the actual max controller.

Parameters

Type	This can be either of IGameControlType

Returns: The 3ds Max controller

virtual IGameControl* GetListSubControl	(	int	index,
		IGameControlType	Type
	)

pure virtual

Access the list controller.

Access the n'th controller from the List controller.

Parameters

index	The index into the list controller
Type	The Control type to access

Returns: An IGameControl interface

virtual int GetNumOfListSubControls ( IGameControlType Type )

pure virtual

Get the number of controllers maintained by the list controller.

The number of controllers maintained by the list controller for the Controller type being queried

Parameters

Type	The controller to type

Returns: The number of controllers in the list controller

virtual int GetNumOfVertControls ( )

pure virtual

Get the number of subcontroller tracks maintained by the Master Point controller.

The number of subcontroller tracks maintained by the Master Point controller. This is NOT actual number of subcontrollers, but total number of vertices

Returns: The number of subcontroller tracks in the Master point controller, zero if no vertex animation

virtual IGameControl* GetVertexControl ( int index )

pure virtual

Access the Master Point subcontroller.

Access the n'th subcontroller from the Master Point controller.

Parameters

index The index into the Master Point controller, the actual vertex index

Returns: An IGameControl interface, if vertex is not animated return NULL

IGameControl Class Reference

Class Description

Public Types

Public Member Functions

Additional Inherited Members

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation