---

RpSkin
[Skinning]

Modules
D3D9
Data Structures
struct	RpSkin
struct	RwMatrixWeights
Enumerations
enum	RpSkinType {   rpNASKINTYPE = 0, rpSKINTYPEGENERIC = 1, rpSKINTYPEMATFX = 2, rpSKINTYPETOON = 3,   rpSKINTYPEFORCEENUMSIZEINT = RWFORCEENUMSIZEINT }
Functions
RpDMorphType	RpDMorphAtomicGetType (RpAtomic *atomic)
void	RpSkinSetFreeListCreateParams (RwInt32 blockSize, RwInt32 numBlocksToPrealloc)
RwBool	RpSkinPluginAttach (void)
RpAtomic *	RpSkinAtomicSetHAnimHierarchy (RpAtomic *atomic, RpHAnimHierarchy *hierarchy)
RpHAnimHierarchy *	RpSkinAtomicGetHAnimHierarchy (const RpAtomic *atomic)
RpSkin *	RpSkinGeometryGetSkin (RpGeometry *geometry)
RpGeometry *	RpSkinGeometrySetSkin (RpGeometry *geometry, RpSkin *skin)
RpSkin *	RpSkinCreate (RwUInt32 numVertices, RwUInt32 numBones, RwMatrixWeights *vertexWeights, RwUInt32 *vertexIndices, RwMatrix *inverseMatrices)
RpSkin *	RpSkinDestroy (RpSkin *skin)
RwUInt32	RpSkinGetNumBones (RpSkin *skin)
const RwMatrixWeights *	RpSkinGetVertexBoneWeights (RpSkin *skin)
const RwUInt32 *	RpSkinGetVertexBoneIndices (RpSkin *skin)
const RwMatrix *	RpSkinGetSkinToBoneMatrices (RpSkin *skin)
RwBool	RpSkinIsSplit (RpSkin *skin)
RpAtomic *	RpSkinAtomicSetType (RpAtomic *atomic, RpSkinType type)
RpSkinType	RpSkinAtomicGetType (RpAtomic *atomic)

---

Detailed Description

Skin Plugin for RenderWare Graphics.

RpSkin Plugin Overview

Requirements

There are two versions of the RpSkin libraries in the RenderWare Graphics SDK. They are both fully featured versions on the RpSkin plugin, and they contain identical APIs. However, because the rendering pipelines are large we have taken the step to compile different versions of the plugin so that the user can select precisely the pipelines they will be using.

Requirements for rpskin library

The rpskin.lib library only contains the rpSKINTYPEGENERIC pipeline.

• Headers: rwcore.h, rpworld.h, rphanim.h, rtanim.h, rpskin.h
• Libraries: rwcore, rpworld, rtquat, rphanim, rtanim, rpskin
• Plugin attachments: RpWorldPluginAttach, RpHAnimPluginAttach, RtAnimInitialize, RpSkinPluginAttach

Requirements for rpskinmatfx library

The rpskinmatfx.lib library contains both the rpSKINTYPEGENERIC and rpSKINTYPEMATFX pipelines.

• Headers: rwcore.h, rpworld.h, rphanim.h, rtanim.h, rpmatfx.h, rpskin.h
• Libraries: rwcore, rpworld, rtquat, rphanim, rpmatfx, rpskinmatfx
• Plugin attachments: RpWorldPluginAttach, RpHAnimPluginAttach, RtAnimInitialize, RpMatFXPluginAttach, RpSkinPluginAttach

Restrictions

Each platform has a restriction on the number of bones that can be used with a skin. Please refer to the platform specific section of the skin documentation for information on this subject, Bone limit.

If a model requires more bones than this limit, it needs to be 'split' into smaller groups such that each group requires less bones than this limit. See the toolkit, RtSkinSplit, for more detail on splitting a model to fit onto a target platform.

Note:

Only one of the skinning libraries should be used in an application at once.

Overview

The skin plugin provides a means to animate a model while reducing the 'folding' and 'creasing' of polygons as the model animates. A bone hierarchy is defined in a model and it is linked to the model's mesh, so that animating the bone hierarchy animates the mesh's vertices. The custom skinning rendering pipes allow up to four bones to affect each vertex in the mesh.

The skinning definition and rendering is defined in this plugin, whereas the animation and hierarchy is defined in the RpHAnim plugin.

Before any of the skinning functions can be used the plugin must be registered with RenderWare with:

• RpSkinPluginAttach

The RpSkin defines the relationship between the vertices and bones. The following functions create and destroy a skin:

• RpSkinCreate Creates and initialized the skin for a RpGeometry or a RpPatchMesh.
• RpSkinDestroy Destroys the skin.

Information about a skin can be queried with the following functions:

• RpSkinGetNumBones Returns the number of bones in the skin.
• RpSkinGetVertexBoneWeights Returns the vertex bone weights.
• RpSkinGetVertexBoneIndices Returns the vertex bone indices.
• RpSkinGetSkinToBoneMatrices Returns the skin-space to bone-space transformation matrices.
• RpSkinIsSplit Returns whether the skin has been split.

Once the skin has been created and setup, it can be attached to a RpGeometry or RpPatchMesh with:

• RpSkinGeometrySetSkin Attaches a skin on to a geometry.
• RpSkinGeometryGetSkin Queries a skin attached on a geometry.
• RpPatchMeshSetSkin Attaches a skin on to a patch mesh.
• RpPatchMeshGetSkin Queries a skin attached to a patch mesh.

The RpHAnimHierarchy used to animate the skin needs to be attached to the RpAtomic. This allows a number of atomics to reference the same geometry, hence the same skin, and animate it in different ways. The following functions control the setting of the hierarchy:

• RpSkinAtomicSetHAnimHierarchy Attach a hierarchy to the atomic to use positioning the bones.
• RpSkinAtomicGetHAnimHierarchy Query the hierarchy attached to an atomic.

The atomic still needs it's rendering pipeline overloaded with a custom skinning rendering pipeline. These pipelines are defined by RpSkinType. The skinned atomic should have their pipelines overloaded with:

• RpSkinAtomicSetType Set the pipeline on to the atomic.
• RpSkinAtomicGetType Query the type of the pipeline attached to the atomic.

If the atomic has a patch mesh attached instead of a geometry. Then a patch mesh skinning rendering pipeline should be attached instead. These are defined by RpPatchType and the pipeline is overloaded with:

• RpPatchAtomicSetType Set the pipeline on to a patch atomic.
• RpPatchAtomicGetType Query the type of a patch pipeline attached to the atomic.

---

Enumeration Type Documentation

enum RpSkinType

RpSkinType defines the different ways a skinned atomic can be rendered. Once a skinned RpGeometry has been attached to an RpAtomic the atomic must be setup with the correct skin rendering pipeline with RpSkinAtomicSetType. Enumeration values: rpNASKINTYPE  Invalid skin pipeline. rpSKINTYPEGENERIC  Generic skin rendering. rpSKINTYPEMATFX  Material effects skin rendering. rpSKINTYPETOON  Toon skin rendering. To use this flag the RpToon plugin (part of the FX Pack) needs to be installed.

---

Function Documentation

RpDMorphType RpDMorphAtomicGetType (  RpAtomic *    atomic )

RpDMorphAtomicGetType Gets the delta morph type attached to the atomic. Parameters: atomic  Pointer to the atomic. Returns: The RpDMorphType of the pipeline attached to the atomic, or rpNADMORPHTYPE otherwise. See also: RpDMorphAtomicSetType

RpHAnimHierarchy* RpSkinAtomicGetHAnimHierarchy (  const RpAtomic *    atomic )

RpSkinAtomicGetHAnimHierarchy returns the RpHAnimHierarchy attached to the RpAtomic. Parameters: atomic  A pointer to the skinned atomic to query the hierarchy. Returns: A pointer to the attached hierarchy, or NULL otherwise. See also: RpSkinAtomicSetHAnimHierarchy

RpSkinType RpSkinAtomicGetType (  RpAtomic *    atomic )

RpSkinAtomicGetType Returns the RpSkinType of the rendering pipeline attached to the atomic. The skin plugin must be attached before using this function. Parameters: atomic  Pointer to the atomic. Returns: The RpSkinType of the pipeline attached to the atomic, or rpNASKINTYPE otherwise. See also: RpSkinAtomicSetType

RpAtomic* RpSkinAtomicSetHAnimHierarchy (  RpAtomic *    atomic, RpHAnimHierarchy *    hierarchy )

RpSkinAtomicSetHAnimHierarchy attaches an RpHAnimHierarchy to the RpAtomic. The hierarchy is used to define the positions and orientation of the RpSkin's bones. A hierarchy should be initialized and attached to the atomic before rendering. The hierarchy information is attached to the atomic, this allows atomics to animate a single skinned RpGeometry. Parameters: atomic  A pointer to the skinned atomic to attach the hierarchy to. hierarchy  A pointer to the RpHAnimHierarchy use to animate the skinned geometry. Returns: A pointer to the atomic if successful, or NULL otherwise. See also: RpSkinAtomicGetHAnimHierarchy

RpAtomic* RpSkinAtomicSetType (  RpAtomic *    atomic, RpSkinType    type )

RpSkinAtomicSetType Set up the skinned RpAtomic with the correct rendering pipeline. The skin plugin must be attached before using this function. Parameters: atomic  Pointer to the atomic. type  Atomic rendering type. Returns: A pointer to the RpAtomic if successful, or NULL otherwise. See also: RpSkinAtomicGetType

RpSkin* RpSkinCreate (  RwUInt32    numVertices, RwUInt32    numBones, RwMatrixWeights *    vertexWeights, RwUInt32 *    vertexIndices, RwMatrix *    inverseMatrices )

RpSkinCreate creates an RpSkin which defines the skinning data for a RpGeometry. The skin can then be attached to the geometry with RpSkinGeometrySetSkin. A skin maps a geometry's vertices to a set of bones that can be animated. The bones are defined by an RpHAnimHierarchy, and the animations are normally defined by an RtAnimAnimation. The skin mapping can assign up to four "weights" per vertex to allow subtle blending between bones. Skins use the RwMatrix structures of the RpHAnimHierarchy to define the initial bone transformations. Parameters: numVertices  The number of vertices in the skin. This be equal to the number of vertices in the geometry. numBones  The number of bones in the skin (the maximum number is platform specific). This is used to define the array of inverse bones matrices. vertexWeights  An array of weights, one per vertex. Each bone weight should be in the range 0.0f to 1.0f. The total weight for a vertex should always sum to 1.0f. Process of the weights will stop when the weight of a bone is 0.0f. The vertex indices must reflect any reordering of the weights. vertexIndices  A pointer to an array of bone indices, one per vertex. The 4 8-bit indices are packed into each RwUInt32 value, with the least significant mapping to w0 in the vertex weight array. inverseMatrices  A pointer to an array of RwMatrix's, one per bone. The matrices are often known as inverse bone matrices, and define the transformation from object-space (or skin-space) to bone-space for that bone. The inverse bone matrices are used to transform the vertices from their object-space into their bone-space. The key-frame based animation for the bone in the hierarchy then transforms the vertex position back into object-space in it's animated pose. The model is then rendered. Note: A skin should be generated in exactly the same way for a RpPatchMesh. The number of vertices is replaced by the number of control points. Instead of attaching the skin to a geometry the skin is attached to the patch mesh with RpPatchMeshSetSkin. Returns: Returns a pointer to the skin that is generated if successful, or NULL if there is an error. See also: RpSkinDestroy

RpSkin* RpSkinDestroy (  RpSkin *    skin )

RpSkinDestroy destroys the RpSkin releasing all it's allocated memory. Destroying a RpGeometry which has a skin attached, will automatically destroy the skin. Any RpHAnimHierarchy used to animate the skin is unaffected. Parameters: skin  Pointer to the skin to destroy. Returns: NULL if the skin was successfully destroyed. See also: RpSkinCreate

RpSkin* RpSkinGeometryGetSkin (  RpGeometry *    geometry )

RpSkinGeometryGetSkin returns the RpSkin attached to the RpGeometry. Parameters: geometry  A pointer to the geometry to query the skin. Returns: A pointer to the attached skin, or NULL otherwise. See also: RpSkinGeometrySetSkin

RpGeometry* RpSkinGeometrySetSkin (  RpGeometry *    geometry, RpSkin *    skin )

RpSkinGeometrySetSkin attaches the RpSkin to the RpGeometry. This extends the geometry to contain the skinning data. Attaching the skin to the geometry isn't sufficient to render the geometry as a skinned geometry. The RpAtomic that the geometry is attached to must also have a RpHAnimHierarchy attached to it with RpSkinAtomicSetHAnimHierarchy. Then the atomic should have it's rendering pipeline overloaded with a custom skinning pipeline. The custom skinning can be automatically attached with RpSkinAtomicSetType. Note: The skin can also be attached to a RpPatchMesh with RpPatchMeshSetSkin. The patch mesh should be attached to an atomic and then have the rendering pipeline overload with RpPatchAtomicSetType selecting a patch skinning rendering pipeline. Parameters: geometry  A pointer to the geometry to attach the skin. skin  A pointer to the skin to attach. Returns: A pointer to the geometry, or NULL otherwise. See also: RpSkinGeometryGetSkin

RwUInt32 RpSkinGetNumBones (  RpSkin *    skin )

RpSkinGetNumBones returns the number of bones in the RpSkin. Parameters: skin  Pointer to skin to query. Returns: Number of bones. See also: RpSkinGetVertexBoneWeights , RpSkinGetVertexBoneIndices , RpSkinGetSkinToBoneMatrices

const RwMatrix* RpSkinGetSkinToBoneMatrices (  RpSkin *    skin )

RpSkinGetSkinToBoneMatrices returns read-only access to the RpSkin's per-bone array of skin to bone space transform matrices. Parameters: skin  Pointer to skin to query. Returns: Read-only per-bone array of skin to bone space transform matrices. See also: RpSkinGetNumBones , RpSkinGetVertexBoneWeights , RpSkinGetVertexBoneIndices

const RwUInt32* RpSkinGetVertexBoneIndices (  RpSkin *    skin )

RpSkinGetVertexBoneIndices returns read-only access to the RpSkin's per-vertex array of bone indices. Parameters: skin  Pointer to skin to query. Returns: Read-only per-vertex array of bone indices. See also: RpSkinGetNumBones , RpSkinGetVertexBoneWeights , RpSkinGetSkinToBoneMatrices

const RwMatrixWeights* RpSkinGetVertexBoneWeights (  RpSkin *    skin )

RpSkinGetVertexBoneWeights returns read-only access to the RpSkin's per-vertex array of bone weights. Parameters: skin  Pointer to skin to query. Returns: Read-only per-vertex array of bone weights. See also: RpSkinGetNumBones , RpSkinGetVertexBoneIndices , RpSkinGetSkinToBoneMatrices

RwBool RpSkinIsSplit (  RpSkin *    skin )

RpSkinIsSplit allows the application to query if the skin has been 'split' to support large bone count models. Parameters: skin  Pointer to the skin to query. Returns: TRUE if the skin has been split, FALSE otherwise. See also: RpSkinGetNumBones , RtSkinSplitAtomicSplitGeometry

RwBool RpSkinPluginAttach (  void    )

RpSkinPluginAttach is used to attach the skin plugin to the RenderWare system to enable the manipulation of skinned geometries and atomics. The plugin must be attached between initializing the system with RwEngineInit and opening it with RwEngineOpen. Note: The skin plugin requires the world plugin to be attached. The include file rpskin.h is also required and must be included by an application wishing to use this plugin. Returns: TRUE if successful, FALSE if an error occurs.

void RpSkinSetFreeListCreateParams (  RwInt32    blockSize, RwInt32    numBlocksToPrealloc )

RpSkinSetFreeListCreateParams allows the developer to specify how many RpSkin 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

---