Main Page Modules Alphabetical List Data Structures Data Fields

RwFrame
[Objects, Frames & Hierarchies]


Data Structures
struct	RwFrame
Typedefs
typedef RwFrame (	RwFrameCallBack )(RwFrame frame, void data)
Functions
RwInt32	RwFrameRegisterPluginStream (RwUInt32 pluginID, RwPluginDataChunkReadCallBack readCB, RwPluginDataChunkWriteCallBack writeCB, RwPluginDataChunkGetSizeCallBack getSizeCB)
RwInt32	RwFrameSetStreamAlwaysCallBack (RwUInt32 pluginID, RwPluginDataChunkAlwaysCallBack alwaysCB)
void	RwFrameSetFreeListCreateParams (RwInt32 blockSize, RwInt32 numBlocksToPrealloc)
RwFrame *	RwFrameCloneHierarchy (RwFrame *root)
RwFrame *	RwFrameGetParent (const RwFrame *frame)
RwBool	RwFrameDirty (const RwFrame *frame)
RwFrame *	RwFrameCreate (void)
RwBool	RwFrameInit (RwFrame *frame)
RwBool	RwFrameDestroy (RwFrame *frame)
RwBool	RwFrameDeInit (RwFrame *frame)
RwBool	RwFrameDestroyHierarchy (RwFrame *frame)
RwFrame *	RwFrameUpdateObjects (RwFrame *frame)
RwMatrix *	RwFrameGetMatrix (RwFrame *frame)
RwMatrix *	RwFrameGetLTM (RwFrame *frame)
RwFrame *	RwFrameGetRoot (const RwFrame *frame)
RwFrame *	RwFrameAddChild (RwFrame parent, RwFrame child)
RwFrame *	RwFrameRemoveChild (RwFrame *child)
RwFrame *	RwFrameForAllChildren (RwFrame frame, RwFrameCallBack callBack, void data)
RwInt32	RwFrameCount (RwFrame *frame)
RwFrame *	RwFrameTranslate (RwFrame frame, const RwV3d translation, RwOpCombineType combineOp)
RwFrame *	RwFrameScale (RwFrame frame, const RwV3d scale, RwOpCombineType combineOp)
RwFrame *	RwFrameTransform (RwFrame frame, const RwMatrix transform, RwOpCombineType combineOp)
RwFrame *	RwFrameRotate (RwFrame frame, const RwV3d axis, RwReal angle, RwOpCombineType combineOp)
RwFrame *	RwFrameSetIdentity (RwFrame *frame)
RwFrame *	RwFrameOrthoNormalize (RwFrame *frame)
RwFrame *	RwFrameForAllObjects (RwFrame frame, RwObjectCallBack callBack, void data)
RwBool	RwFrameSetStaticPluginsSize (RwInt32 size)
RwInt32	RwFrameRegisterPlugin (RwInt32 size, RwUInt32 pluginID, RwPluginObjectConstructor constructCB, RwPluginObjectDestructor destructCB, RwPluginObjectCopy copyCB)
RwInt32	RwFrameGetPluginOffset (RwUInt32 pluginID)
RwBool	RwFrameValidatePlugins (const RwFrame *frame)

Detailed Description

Frames define relationships between objects and the world

RwFrame Overview

Requirements

Headers: rwcore.h
Libraries: rwcore.lib

This object provides a frame of reference for other objects, allowing them to be positioned relative to each other in world space. In addition, a frame object can also be linked to parent and/or child frames in a hierarchical manner. Combined, these features make the frame among the most important RenderWare Graphics objects. It is used primarily in conjunction with RenderWare Graphics' Retained Mode API, exposed by the RpWorld Plugin.

More information can be found in the Fundamentals chapter of the User Guide.

Typedef Documentation

typedef RwFrame*(* RwFrameCallBack)(RwFrame *frame, void *data)

RwFrameCallBack type represents the function called from RwFrameForAllChildren for all child frames linked to a given frame. This function should return a pointer to the current frame to indicate success. The callback may return NULL to terminate further callbacks on the child frames.

Parameters:

frame	Pointer to the current frame, supplied by iterator.
data	Pointer to developer-defined data structure.

Returns:

See also:: RwFrameForAllChildren

Function Documentation

RwFrame* RwFrameAddChild	(	RwFrame *	parent,
		RwFrame *	child
	)

RwFrameAddChild adds the specified child frame to the hierarchy containing the given parent frame. The child is attached to the frame hierarchy directly beneath the parent and therefore inherits movements resulting from changes made to its parent. Frame loops within a given hierarchy are not permitted, therefore, the child must not already exist within the hierarchy it is being added to.

This function should be used to construct hierarchies of objects that can be transformed via joints. Whenever the child's frame is processed its Local Transform Matrix (LTM) is the concatenation of all the modeling matrices up to the root frame. (Note that the root frame has identical LT and modeling matrices.)

Parameters:

parent	A pointer to the parent frame.
child	A pointer to the child frame.

Returns:: Returns a pointer to the parent frame.

See also:: RwFrameRemoveChild , RwFrameCreate , RwFrameDestroy , RwFrameDestroyHierarchy

RwFrame* RwFrameCloneHierarchy

(

RwFrame *

root

)

RwFrameCloneHierarchy makes a copy of a frame hierarchy whose root is specified by the given frame. All frames below and including the given frame are copied together with their modeling matrices. This function also marks the frame, hence the whole hierarchy, as dirty so that all LT matrices will be recalculated at the next synchronization stage.

Parameters:

root

A pointer to the root of frame hierarchy to clone.

Returns:: Returns a pointer to the new frame hierarchy if successful or NULL if there is error.

See also:: RwFrameGetRoot , RwFrameDestroyHierarchy , RwFrameCount

RwInt32 RwFrameCount

(

RwFrame *

frame

)

RwFrameCount determines the number of frames in a hierarchy starting at the specified frame. The specified frame is included in the count.

Parameters:

frame

A pointer to the first frame in the hierarchy.

Returns:: Returns an RwInt32 that equals the number of frames in the hierarchy.

See also:: RwFrameGetRoot , RwFrameDestroyHierarchy

RwFrame* RwFrameCreate

(

void

)

RwFrameCreate creates a new frame. Frames define the spatial relationships between the objects to which they are attached. The newly created frame has no parent and is its own root. To be of any use the frame should be attached to an object; frames can be added to cameras and lights. In addition, frames may be used in a plugin attached to geometry.

Frames contain position and orientation information. They define object hierarchies. The frame contains two matrices: the local transformation matrix (LTM) and the modeling matrix. The modeling matrix describes how the frame (and hence the object attached to it) is transformed relative to its local origin while the LTM describes the absolute transformation from local to world coordinates. If the frame is not part of a hierarchy, or forms the hierarchy's root, the modeling and LT matrices are identical. Otherwise, the modeling matrix is taken to be relative to the frame's parent and the LTM becomes the concatenation of all the modeling matrices up to the root frame. This ensures that any change in the parent's position or orientation will transfer through to the child frames.

Returns:: Returns a pointer to the new frame if successful or NULL if there is an error.

See also:: RwFrameDestroy , RwFrameRotate , RwFrameTranslate , RwFrameSetIdentity , RwFrameAddChild , RwFrameRemoveChild , RwCameraSetFrame , RpLightSetFrame , RpAtomicSetFrame , RpClumpSetFrame

RwBool RwFrameDeInit

(

RwFrame *

frame

)

RwFrameDeInit de-initializes the specified frame. If the frame is a member of a hierarchy it will be removed from the hierarchy and all frames below it will be lost. It is recommended that all objects should be detached from the frame prior to destruction.

Parameters:

frame

A pointer to the frame to destroy.

Returns:: Returns TRUE if successful, FALSE if there is an error.

See also:: RwFrameInit , RwFrameDestroyHierarchy , RwFrameRemoveChild

RwBool RwFrameDestroy

(

RwFrame *

frame

)

RwFrameDestroy destroys the specified frame. If the frame is a member of a hierarchy it will be removed from the hierarchy and all frames below it will be lost. It is recommended that all objects should be detached from the frame prior to destruction.

Parameters:

frame

A pointer to the frame to destroy

Returns:: Returns TRUE or false if there is an error

See also:: RwFrameCreate , RwFrameDestroyHierarchy , RwFrameRemoveChild

RwBool RwFrameDestroyHierarchy

(

RwFrame *

frame

)

RwFrameDestroyHierarchy destroys or de-inits the hierarchy of frames below and including the specified frame. All previously attached types (e.g. lights, atomics) should either be detached from the frames that are about to be destroyed or attached to new frames. All frames above the specified one will survive.

Parameters:

frame

A pointer to the first frame in the hierarchy

Returns:: Returns TRUE on success or FALSE if there is an error

See also:: RwFrameCreate , RwFrameDestroy , RwFrameRemoveChild , RwFrameAddChild

RwBool RwFrameDirty

(

const RwFrame *

frame

)

RwFrameDirty checks the specified frame and returns TRUE if it is dirty.

Parameters:

frame

A pointer to the frame to check.

Returns:: Returns TRUE if frame is dirty, or FALSE if it's clean.

See also:: RwFrameRegisterPlugin

RwFrame* RwFrameForAllChildren	(	RwFrame *	frame,
		RwFrameCallBack	callBack,
		void *	data
	)

RwFrameForAllChildren applies the given callback function to a frame's immediate children (the next level down). The format of the callback function is:

   RwFrame * (*RwFrameCallBack)(RwFrame *frame, void *data)

where data is a user-supplied data pointer to pass to the callback function.

Note that if any invocation of the callback function returns a failure status the iteration is terminated. However, RwFrameForAllChildren will still return successfully.

Parameters:

frame	A pointer to the frame with children to enumerate.
callBack	A pointer to the callback function to apply to each frame.
data	A pointer to user-supplied data to pass to callback function.

Returns:: Returns pointer to the frame.

See also:: RwFrameForAllChildren , RwFrameGetRoot , RwFrameGetParent , RwObjectGetType

RwFrame* RwFrameForAllObjects	(	RwFrame *	frame,
		RwObjectCallBack	callBack,
		void *	data
	)

RwFrameForAllObjects is used applies the given callback function to all objects attached to the specified frame. The format of the callback function is:

   RwObject * (*RwObjectCallBack)(RwObject *object, void *data)

where data is a user-supplied data pointer to pass to the callback function.

Note that if any invocation of the callback function returns a failure status the iteration is terminated. However, RwFrameForAllObjects will still return successfully.

Parameters:

frame	A pointer to the frame with objects attached
callBack	A pointer to the callback function to apply to each object.
data	A pointer to user-supplied data to pass to callback function.

Returns:: Returns pointer to the frame.

RwMatrix* RwFrameGetLTM

(

RwFrame *

frame

)

RwFrameGetLTM retrieves the specified frame's local transformation matrix (LTM).

Parameters:

frame

A pointer to the frame to query.

Returns:: Returns a pointer to the frame's LTM.

See also:: RwFrameGetMatrix , RwFrameGetParent , RwFrameTranslate , RwFrameRotate , RwFrameOrthoNormalize , RwFrameSetIdentity , RwFrameUpdateObjects , RwFrameCreate , RwFrameScale , RwFrameTransform

RwMatrix* RwFrameGetMatrix

(

RwFrame *

frame

)

RwFrameGetMatrix retrieves the specified frame's modeling matrix.

Parameters:

frame

A pointer to the frame to query.

Returns:: Returns a pointer to the frame's modeling matrix.

See also:: RwFrameGetLTM , RwFrameGetParent , RwFrameTranslate , RwFrameRotate , RwFrameOrthoNormalize , RwFrameSetIdentity , RwFrameUpdateObjects , RwFrameCreate , RwFrameScale , RwFrameTransform

RwFrame* RwFrameGetParent

(

const RwFrame *

frame

)

RwFrameGetParent determines the immediate parent of the specified frame. If the frame is not part of a hierarchy or is the root frame of a hierarchy then its parent is undefined.

Parameters:

frame

A pointer to the frame.

Returns:: Returns a pointer to parent frame if successful or NULL there is an error or if the frame has no parent.

See also:: RwFrameCreate , RwFrameForAllObjects , RwFrameAddChild , RwFrameForAllChildren

RwInt32 RwFrameGetPluginOffset

(

RwUInt32

pluginID

)

RwFrameGetPluginOffset is used to get the offset of a previously registered plugin.

Parameters:

pluginID

The plugin ID for which to get the data offset.

Returns:: Returns an RwInt32 that equals the data block offset or -1 if the plugin is not registered.

See also:: RwFrameRegisterPlugin , RwFrameRegisterPluginStream , RwFrameValidatePlugins

RwFrame* RwFrameGetRoot

(

const RwFrame *

frame

)

RwFrameGetRoot retrieves the root frame of the hierarchy that the specified frame belongs to. If the frame is not part of any hierarchy the frame is its own root.

Parameters:

frame

A pointer to the frame.

Returns:: Returns a pointer to the root frame.

See also:: RwFrameCount , RwFrameDestroyHierarchy , RwFrameGetParent , RwFrameAddChild , RwFrameCreate

RwBool RwFrameInit

(

RwFrame *

frame

)

RwFrameInit initializes a static frame. Frames define the spatial relationships between the objects to which they are attached. The newly initialized frame has no parent and is its own root. To be of any use the frame should be attached to an object; frames can be added to cameras and lights. In addition, frames may be used in a plugin attached to geometry.

Do not call this if RwFrameCreate has been called to create the frame as the frame has already been initialized and this may result in the frame not being freed properly.

Parameters:

frame

A pointer to the RwFrame to initialize.

Returns:: Returns TRUE if successful or FALSE if the static plugin data size has not been set by RwFrameSetStaticPluginsSize.

See also:: RwFrameSetStaticPluginsSize , RwFrameDestroy , RwFrameRotate , RwFrameTranslate , RwFrameSetIdentity , RwFrameAddChild , RwFrameRemoveChild , RwCameraSetFrame , RpLightSetFrame , RpAtomicSetFrame , RpClumpSetFrame

RwFrame* RwFrameOrthoNormalize

(

RwFrame *

frame

)

RwFrameOrthoNormalize orthonormalizes the modeling matrix of the specified frame. Orthonormalization is required if the frame is rotated often, as small errors in the calculation will accumulate. This will cause the frame to acquire unwanted scale or shear factors. To prevent the significant build-up of such factors RwFrameOrthoNormalize should be periodically applied to ensure the frame's modeling matrix remains orthonormal. The minimal satisfactory frequency of orthonormalzation will depend on the nature of the application. Typically, a frequency of once every 128 updates is adequate. This function also marks the frame as dirty so that it's LTM will be recalculated at the next synchronization stage.

Parameters:

frame

A pointer to the frame.

Returns:: Returns a pointer to the frame.

See also:: RwFrameRotate , RwFrameTranslate , RwFrameSetIdentity , RwFrameUpdateObjects , RwFrameScale , RwFrameTransform

RwInt32 RwFrameRegisterPlugin	(	RwInt32	size,
		RwUInt32	pluginID,
		RwPluginObjectConstructor	constructCB,
		RwPluginObjectDestructor	destructCB,
		RwPluginObjectCopy	copyCB
	)

RwFrameRegisterPlugin registers a plugin and reserve some space within a frame. This must happen after the engine has been initialized, but before the engine is opened.

Parameters:

size	The size of the memory block to reserve in the frame
pluginID	The 32 bit unique ID for the plugin (used to identify binary chunks)
constructCB	The constructor for the plugin data block
destructCB	The destructor for the plugin data block
copyCB	The copy constructor for the plugin data block

Returns:

Returns one of the following values:

positive - Byte offset within the frame of memory reserved for this plugin
negative - On failure

See also:: RwFrameRegisterPluginStream , RwFrameGetPluginOffset , RwFrameValidatePlugins

RwInt32 RwFrameRegisterPluginStream	(	RwUInt32	pluginID,
		RwPluginDataChunkReadCallBack	readCB,
		RwPluginDataChunkWriteCallBack	writeCB,
		RwPluginDataChunkGetSizeCallBack	getSizeCB
	)

RwFrameRegisterPluginStream associates a set of binary stream functionality with a previously registered plugin.

Parameters:

pluginID	The 32 bit unique ID for the plugin (used to identify binary chunks)
readCB	The callback used when a chunk is read that is identified as being for this plugin.
writeCB	The callback used when a chunk should be written out for this plugin
getSizeCB	The callback used to determine the binary stream size required for this plugin (return negative to suppress chunk writing)

Returns:

Returns a value:

positive : the byte offset within the frame of memory reserved for this plugin
negative : on failure

See also:: RwFrameSetStreamAlwaysCallBack , RwFrameRegisterPlugin , RwFrameGetPluginOffset , RwFrameValidatePlugins

RwFrame* RwFrameRemoveChild

(

RwFrame *

child

)

RwFrameRemoveChild removes the specified frame from the hierarchy it is a member of. Once removed the frame becomes the root of a new hierarchy comprising itself and all of its descendents.

Parameters:

child

A pointer to the frame to detach from the hierarchy.

Returns:: Returns a pointer to the frame.

See also:: RwFrameAddChild , RwFrameCreate , RwFrameDestroy , RwFrameDestroyHierarchy

RwFrame* RwFrameRotate	(	RwFrame *	frame,
		const RwV3d *	axis,
		RwReal	angle,
		RwOpCombineType	combineOp
	)

RwFrameRotate is used to build a rotation matrix from the given axis and angle of rotation and apply it to the modeling matrix of the specified frame. The combine operation may be pre-concatenation, post-concatenation or replacement. This function also marks the frame as dirty so that it's LTM will be recalculated at the next synchronization stage.

Parameters:

frame	A pointer to the frame to rotate.
axis	A pointer to a 3D vector specifying the axis of rotation.
angle	An RwReal value equal to the angle of rotation (in degrees).
combineOp	A combination operator specifying how the rotation is applied: rwCOMBINEPRECONCAT - Pre-concatenation. rwCOMBINEPOSTCONCAT - Post-concatenation. rwCOMBINEREPLACE - Replacement.

Returns:: Returns pointer to the frame.

See also:: RwFrameTranslate , RwFrameSetIdentity , RwFrameOrthoNormalize , RwFrameUpdateObjects , RwFrameTransform , RwFrameScale , RwFrameTransform

RwFrame* RwFrameScale	(	RwFrame *	frame,
		const RwV3d *	scale,
		RwOpCombineType	combineOp
	)

RwFrameScale applies the given scale to the modeling matrix of the specified frame. The combine operation may be pre-concatenation, post-concatenation or replacement. This function also marks the frame as dirty so that it's LTM will be recalculated at the next synchronization stage.

Parameters:

frame	A pointer to the frame to translate.
scale	Pointer to a 3D vector specifying the scale.
combineOp	A combination operator specifying how the scale is applied: rwCOMBINEPRECONCAT - Pre-concatenation. rwCOMBINEPOSTCONCAT - Post-concatenation. rwCOMBINEREPLACE - Replacement.

Returns:: Returns pointer to the frame.

See also:: RwFrameRotate , RwFrameTranslate , RwFrameSetIdentity , RwFrameOrthoNormalize , RwFrameUpdateObjects , RwFrameTransform

void RwFrameSetFreeListCreateParams	(	RwInt32	blockSize,
		RwInt32	numBlocksToPrealloc
	)

RwFrameSetFreeListCreateParams allows the developer to specify how many RwFrame s to preallocate space for. Call before RwEngineInit.

Parameters:

blockSize	number of entries per freelist block.
numBlocksToPrealloc	number of blocks to allocate on RwFreeListCreateAndPreallocateSpace.

See also:: RwFreeList

RwFrame* RwFrameSetIdentity

(

RwFrame *

frame

)

RwFrameSetIdentity resets the modeling matrix of the specified frame to the identity matrix. This will remove any transformations previously applied to the frame. This function also marks the frame as dirty so that it's LTM will be recalculated at the next synchronization stage.

Parameters:

frame

A pointer to the frame.

Returns:: Returns a pointer to the frame.

See also:: RwFrameRotate , RwFrameTranslate , RwFrameOrthoNormalize , RwFrameUpdateObjects , RwFrameScale , RwFrameTransform

RwBool RwFrameSetStaticPluginsSize

(

RwInt32

size

)

RwFrameSetStaticPluginsSize tells RenderWare Graphics how much memory is statically allocated for plugins. This must happen after the engine has been initialized, but before the engine is opened.

Parameters:

size

The size of the memory block to reserve in the frame

Returns:: Returns TRUE if successful, FALSE if there is an error

RwInt32 RwFrameSetStreamAlwaysCallBack	(	RwUInt32	pluginID,
		RwPluginDataChunkAlwaysCallBack	alwaysCB
	)

RwFrameSetStreamAlwaysCallBack associates a binary stream callback with a previously registered frame plugin. This callback is called for all plugins after stream data reading has completed.

Parameters:

pluginID	The 32 bit unique ID for the plugin (used to identify binary chunks)
alwaysCB	The callback used when the object base and plugin data reading is complete.

Returns:

Returns an RwInt32 equal to one of the following values:

positive - Byte offset within the frame of memory reserved for this plugin
negative - On failure

See also:: RwFrameRegisterPluginStream , RwFrameRegisterPlugin , RwFrameGetPluginOffset , RwFrameValidatePlugins

RwFrame* RwFrameTransform	(	RwFrame *	frame,
		const RwMatrix *	transform,
		RwOpCombineType	combineOp
	)

RwFrameTransform applies the given general transformation matrix to the modeling matrix of the specified frame. The combine operation may be pre-concatenation, post-concatenation or replacement. This function also marks the frame as dirty so that it's LTM will be recalculated at the next synchronization stage.

Parameters:

frame	A pointer to the frame to translate.
transform	A pointer to a matrix specifying the transformation.
combineOp	A combination operator specifying how the transformation is applied: rwCOMBINEPRECONCAT - Pre-concatenation. rwCOMBINEPOSTCONCAT - Post-concatenation. rwCOMBINEREPLACE - Replacement.

Returns:: Returns a pointer to the frame.

See also:: RwFrameRotate , RwFrameTranslate , RwFrameSetIdentity , RwFrameOrthoNormalize , RwFrameUpdateObjects

RwFrame* RwFrameTranslate	(	RwFrame *	frame,
		const RwV3d *	translation,
		RwOpCombineType	combineOp
	)

RwFrameTranslate applies the given translation vector to the modeling matrix of the specified frame. The combine operation may be pre-concatenation, post-concatenation or replacement. This function also marks the frame as dirty so that it's LTM will be recalculated at the next synchronization stage.

Parameters:

frame	A pointer to the frame to translate.
translation	A pointer to a 3D vector that specifies the translation.
combineOp	A combination operator specifying how the translation is applied: rwCOMBINEPRECONCAT - Pre-concatenation. rwCOMBINEPOSTCONCAT - Post-concatenation. rwCOMBINEREPLACE - Replacement.

Returns:: Returns a pointer to the frame.

See also:: RwFrameRotate , RwFrameSetIdentity , RwFrameOrthoNormalize , RwFrameUpdateObjects

RwFrame* RwFrameUpdateObjects

(

RwFrame *

frame

)

RwFrameUpdateObjects marks the specified frame as dirty following a modeling matrix transformation. This will cause the frame's LTM to be recalculated, and all objects attached to the frame to be updated, at the next synchronization stage (for example, during a call to RwCameraBeginUpdate). If the frame resides within a hierarchy the entire hierarchy is marked as dirty, hence all LTMs and objects will be updated.

Parameters:

frame

A pointer to the frame to mark as dirty.

Returns:: Returns a pointer to the frame.

See also:: RwFrameCreate , RwFrameGetMatrix , RwFrameGetLTM

RwBool RwFrameValidatePlugins

(

const RwFrame *

frame

)

RwFrameValidatePlugins validates the plugin memory allocated within the specified frame. This function is useful to help determine where memory stomping may be occurring within an application. This function only returns a meaningful response under a debug library.

Parameters:

frame

The frame for which to validate the plugin memory.

Returns:

Returns one of the following values:

TRUE - Frame data is valid
FALSE - Frame data has become corrupt, or an error has occurred.

See also:: RwFrameRegisterPlugin , RwFrameRegisterPluginStream , RwFrameGetPluginOffset

Converted from CHM to HTML with chm2web Pro 2.85 (unicode)

RwFrame [Objects, Frames & Hierarchies]

Data Structures

Typedefs

Functions

Detailed Description

RwFrame Overview

Overview

Typedef Documentation

Function Documentation

RwFrame
[Objects, Frames & Hierarchies]