OGRE-Next: Ogre::SubMesh Class Reference

| OGRE-Next 3.0.0 Object-Oriented Graphics Rendering Engine

Loading...
Searching...
No Matches
Ogre::SubMesh Class Reference
Core » Resources

Defines a part of a complete mesh. More...

`#include <OgreSubMesh2.h>`

Inheritance diagram for Ogre::SubMesh:
[legend]

## Classes
struct | SourceData

## Public Types
typedef FastArray< unsigned short > | IndexMap
typedef FastArray< SourceData > | SourceDataArray
typedef vector< VertexBoneAssignment >::type | VertexBoneAssignmentVec

## Public Member Functions
| SubMesh ()
| ~SubMesh ()
void | _buildBoneAssignmentsFromVertexData ()
| Populates mBoneAssignments by reading the vertex data.
void | _buildBoneAssignmentsFromVertexData (uint8 const *vertexData)
| Populates mBoneAssignments by reading the vertex data.
void | _buildBoneIndexMap ()
| Builds mBlendIndexToBoneIndexMap based on mBoneAssignments.
void | _compileBoneAssignments ()
| Call this function if you've manually called addBoneAssignment to setup bones for vertices.
void | _prepareForShadowMapping (bool forceSameBuffers)
void | addBoneAssignment (const VertexBoneAssignment &vertBoneAssign)
| Assigns a vertex to a bone with a given weight, for skeletal animation.
void | arrangeEfficient (bool halfPos, bool halfTexCoords, bool qTangents)
| Converts this SubMesh to an efficient arrangement.
void | clearBoneAssignments ()
| Removes all bone assignments for this mesh.
SubMesh * | clone (Mesh *parentMesh=0, int vertexBufferType=-1, int indexBufferType=-1)
| Makes a copy of this submesh object and gives it a new name.
void | createPoses (const float **positionData, const float **normalData, size_t numPoses, size_t numVertices, const String *names=0, bool halfPrecision=true)
| Fills the pose animation buffer with the given poseData.
void | dearrangeToInefficient ()
| Reverts the effects from arrangeEfficient by converting all 16-bit half float back to 32-bit float; and QTangents to Normal, Tangent + Reflection representation, which are more compatible for doing certain operations vertex operations in the CPU.
const VertexBoneAssignmentVec & | getBoneAssignments ()
| Gets a const reference to the list of bone assignments.
String | getMaterialName () const
uint16 | getNumPoses ()
bool | getPoseHalfPrecision ()
size_t | getPoseIndex (const Ogre::String &name)
bool | getPoseNormals ()
TexBufferPacked * | getPoseTexBuffer ()
void | importFromV1 (v1::SubMesh *subMesh, bool halfPos, bool halfTexCoords, bool qTangents, bool halfPose)
| Imports a v1 SubMesh.
void | setMaterialName (const String &name)

## Static Public Member Functions
static char * | _arrangeEfficient (SourceDataArray srcData, const VertexElement2Vec &vertexElements, size_t vertexCount)
| Generic form that does the actual job for both v1 and v2 objects.
static char * | _arrangeEfficient (v1::SubMesh *subMesh, bool halfPos, bool halfTexCoords, bool qTangents, VertexElement2Vec *outVertexElements, size_t vaoPassIdx)
| Rearranges the buffers to be efficiently rendered in Ogre 2.1 with Hlms Takes a v1 SubMesh and returns a pointer with the data interleaved, and a VertexElement2Vec with the new vertex format.
static char * | _dearrangeEfficient (char const *RESTRICT_ALIAS srcData, size_t numElements, const VertexElement2Vec &vertexElements, VertexElement2Vec *outVertexElements)
| Generic form that does the actual job for both v1 and v2 objects.
static void | destroyVaos (VertexArrayObjectArray &vaos, VaoManager *vaoManager, bool destroyIndexBuffer=true)

## Public Attributes
IndexMap | mBlendIndexToBoneIndexMap
| Dedicated index map for translate blend index to bone index.
String | mMaterialName
| Name of the material this SubMesh uses.
Mesh * | mParent
| Reference to parent Mesh (not a smart pointer so child does not keep parent alive).
VertexArrayObjectArray | mVao [NumVertexPass]
| VAO to render the submesh.

## Detailed Description

Defines a part of a complete mesh.

Remarks
  Meshes which make up the definition of a discrete 3D object are made up of potentially multiple parts. This is because different parts of the mesh may use different materials or use different vertex formats, such that a rendering state change is required between them.

  Like the Mesh class, instantiations of 3D objects in the scene share the SubMesh instances, and have the option of overriding their material differences on a per-object basis if required. See the SubEntity class for more information.

## Member Typedef Documentation

## ◆ IndexMap

typedef FastArray<unsigned short> Ogre::SubMesh::IndexMap

## ◆ SourceDataArray

typedef FastArray<SourceData> Ogre::SubMesh::SourceDataArray

## ◆ VertexBoneAssignmentVec

typedef vector<VertexBoneAssignment>::type Ogre::SubMesh::VertexBoneAssignmentVec

## Constructor & Destructor Documentation

## ◆ SubMesh()

Ogre::SubMesh::SubMesh | ( |  | ) |

Referenced by clone().

## ◆ ~SubMesh()

Ogre::SubMesh::~SubMesh | ( |  | ) |

## Member Function Documentation

## ◆ _arrangeEfficient() [1/2]

char * Ogre::SubMesh::_arrangeEfficient | ( | SourceDataArray | srcData,
|  | const VertexElement2Vec & | vertexElements,
|  | size_t | vertexCount )
| static

Generic form that does the actual job for both v1 and v2 objects.

Takes an array of pointers to source each vertex element, and returns a pointer with the valid data.

Parameters

  srcData | Array that points to the source data for every vertex element. VES_TANGENT and VES_BINORMAL must be at the end if converting to QTangents. The pointer in SourceData::data must already be offsetted.
  vertexElements | The vertex format we're converting to.
  vertexCount | Number of vertices

Returns
  Buffer pointer with reorganized data. static char* _arrangeEfficient( SourceDataArray srcData, Caller MUST free the pointer with OGRE_FREE_SIMD( MEMCATEGORY_GEOMETRY ).

## ◆ _arrangeEfficient() [2/2]

char * Ogre::SubMesh::_arrangeEfficient | ( | v1::SubMesh * | subMesh,
|  | bool | halfPos,
|  | bool | halfTexCoords,
|  | bool | qTangents,
|  | VertexElement2Vec * | outVertexElements,
|  | size_t | vaoPassIdx )
| static

Rearranges the buffers to be efficiently rendered in Ogre 2.1 with Hlms Takes a v1 SubMesh and returns a pointer with the data interleaved, and a VertexElement2Vec with the new vertex format.

Remarks
  Final work is delegated to the generic overload.

Parameters

  halfPos |

See also
  Mesh::importV1

Parameters

  halfTexCoords |

See also
  Mesh::importV1

Parameters

  qTangents |

See also
  Mesh::importV1

Parameters

  outVertexElements | [out] Description of the buffer in the new v2 system.

Returns
  Buffer pointer with reorganized data. Caller MUST free the pointer with OGRE_FREE_SIMD( MEMCATEGORY_GEOMETRY ).

## ◆ _buildBoneAssignmentsFromVertexData() [1/2]

void Ogre::SubMesh::_buildBoneAssignmentsFromVertexData | ( |  | ) |

Populates mBoneAssignments by reading the vertex data.

See the other overload.

## ◆ _buildBoneAssignmentsFromVertexData() [2/2]

void Ogre::SubMesh::_buildBoneAssignmentsFromVertexData | ( | uint8 const * | vertexData | ) |

Populates mBoneAssignments by reading the vertex data.

This version accepts an external buffer in case you already have the vertex data on CPU (instead of having to bring it back from GPU)

Remarks
  mBlendIndexToBoneIndexMap MUST be up to date. OTHERWISE IT MAY CRASH. Despite accepting external vertexData, mVao must be correctly populated with information about vertexData

Parameters

  vertexData | Vertex data with blend indices and weights.

## ◆ _buildBoneIndexMap()

void Ogre::SubMesh::_buildBoneIndexMap | ( |  | ) |

Builds mBlendIndexToBoneIndexMap based on mBoneAssignments.

mBlendIndexToBoneIndexMap is necessary for enabling skeletal animation.

## ◆ _compileBoneAssignments()

void Ogre::SubMesh::_compileBoneAssignments | ( |  | ) |

Call this function if you've manually called addBoneAssignment to setup bones for vertices.

WARNING: Will destroy LODs.

## ◆ _dearrangeEfficient()

char * Ogre::SubMesh::_dearrangeEfficient | ( | char const *RESTRICT_ALIAS | srcData,
|  | size_t | numElements,
|  | const VertexElement2Vec & | vertexElements,
|  | VertexElement2Vec * | outVertexElements )
| static

Generic form that does the actual job for both v1 and v2 objects.

See also
  dearrangeEfficientToInefficient.

Parameters

  srcData | Single pointer with interleaved data.
  numElements | Number of vertices.
  vertexElements | Vertex format of the original vertex buffer.
  outVertexElements | [out] Vertex format of the new converted vertex buffer.

Returns
  Pointer to the decompressed/dearranged data, interleaved in a single buffer.

References RESTRICT_ALIAS.

## ◆ _prepareForShadowMapping()

void Ogre::SubMesh::_prepareForShadowMapping | ( | bool | forceSameBuffers | ) |

## ◆ addBoneAssignment()

void Ogre::SubMesh::addBoneAssignment | ( | const VertexBoneAssignment & | vertBoneAssign | ) |

Assigns a vertex to a bone with a given weight, for skeletal animation.

Remarks
  This method is only valid after calling setSkeletonName. Since this is a one-off process there exists only 'addBoneAssignment' and 'clearBoneAssignments' methods, no 'editBoneAssignment'. You should not need to modify bone assignments during rendering (only the positions of bones) and OGRE reserves the right to do some internal data reformatting of this information, depending on render system requirements.

  This method is for assigning weights to the dedicated geometry of the SubMesh. To assign weights to the shared Mesh geometry, see the equivalent methods on Mesh.

## ◆ arrangeEfficient()

void Ogre::SubMesh::arrangeEfficient | ( | bool | halfPos,
|  | bool | halfTexCoords,
|  | bool | qTangents )

Converts this SubMesh to an efficient arrangement.

See Mesh::importV1 for an explanation on the parameters.

See also
  dearrangeEfficientToInefficient to perform the opposite operation.

Referenced by createPoses().

## ◆ clearBoneAssignments()

void Ogre::SubMesh::clearBoneAssignments | ( |  | ) |

Removes all bone assignments for this mesh.

  This method is for assigning weights to the dedicated geometry of the SubMesh. To assign weights to the shared Mesh geometry, see the equivalent methods on Mesh.

## ◆ clone()

SubMesh * Ogre::SubMesh::clone | ( | Mesh * | parentMesh = 0,
|  | int | vertexBufferType = -1,
|  | int | indexBufferType = -1 )

Makes a copy of this submesh object and gives it a new name.

Parameters

  newName | The name to give the clone.
  parentMesh | Optional mesh to make the parent of the newly created clone. If you leave this blank, the clone will be parented to the same Mesh as the original.
  vertexBufferType | See BufferType. Must be set to a valid BufferType. Pass a negative value to keep the same type of the original buffer being cloned.
  indexBufferType | See BufferType. Must be set to a valid BufferType. Pass a negative value to keep the same type of the original buffer being cloned.

References SubMesh(), and Mesh.

## ◆ createPoses()

void Ogre::SubMesh::createPoses | ( | const float ** | positionData,
|  | const float ** | normalData,
|  | size_t | numPoses,
|  | size_t | numVertices,
|  | const String * | names = 0,
|  | bool | halfPrecision = true )

Fills the pose animation buffer with the given poseData.

Parameters

  positionData | Array with a pointer to a block of data for each pose, and each pose should contain (x,y,z) offsets for each vertex in sequence. The size of each block of data must be equals to numVertices * 3 * sizeof(float) or else a buffer overrun shall occur.
  normalData | Similar to positionData however should contain normal offsets and can be nullptr if morphing normals is not desired and it will also save memory.
  numPoses | Number of poses.
  numVertices | Number of vertices
  names | Array containing the name of each pose or null. If not null must contain numPoses elements.
  halfPrecision | True if you want the pose buffer to have pixel format PF_FLOAT16_RGBA which uses significantly less memory. Otherwise it is created with pixel format PF_FLOAT32_RGBA. Rarely the extra precision is needed.

References arrangeEfficient(), and importFromV1().

## ◆ dearrangeToInefficient()

void Ogre::SubMesh::dearrangeToInefficient | ( |  | ) |

Reverts the effects from arrangeEfficient by converting all 16-bit half float back to 32-bit float; and QTangents to Normal, Tangent + Reflection representation, which are more compatible for doing certain operations vertex operations in the CPU.

## ◆ destroyVaos()

void Ogre::SubMesh::destroyVaos | ( | VertexArrayObjectArray & | vaos,
|  | VaoManager * | vaoManager,
|  | bool | destroyIndexBuffer = true )
| static

## ◆ getBoneAssignments()

const VertexBoneAssignmentVec & Ogre::SubMesh::getBoneAssignments | ( |  | ) |
| inline

Gets a const reference to the list of bone assignments.

## ◆ getMaterialName()

String Ogre::SubMesh::getMaterialName | ( |  | ) | const
| inline

References mMaterialName.

## ◆ getNumPoses()

uint16 Ogre::SubMesh::getNumPoses | ( |  | ) |
| inline

## ◆ getPoseHalfPrecision()

bool Ogre::SubMesh::getPoseHalfPrecision | ( |  | ) |
| inline

## ◆ getPoseIndex()

size_t Ogre::SubMesh::getPoseIndex | ( | const Ogre::String & | name | ) |
| inline

## ◆ getPoseNormals()

bool Ogre::SubMesh::getPoseNormals | ( |  | ) |
| inline

## ◆ getPoseTexBuffer()

TexBufferPacked * Ogre::SubMesh::getPoseTexBuffer | ( |  | ) |
| inline

## ◆ importFromV1()

void Ogre::SubMesh::importFromV1 | ( | v1::SubMesh * | subMesh,
|  | bool | halfPos,
|  | bool | halfTexCoords,
|  | bool | qTangents,
|  | bool | halfPose )

Imports a v1 SubMesh.

See also
  Mesh::importV1. Automatically performs what arrangeEfficient does.

Referenced by createPoses().

## ◆ setMaterialName()

void Ogre::SubMesh::setMaterialName | ( | const String & | name | ) |
| inline

References mMaterialName.

## Member Data Documentation

## ◆ mBlendIndexToBoneIndexMap

IndexMap Ogre::SubMesh::mBlendIndexToBoneIndexMap

Dedicated index map for translate blend index to bone index.

  We collect actually used bones of all bone assignments, and build the blend index in 'packed' form, then the range of the blend index in vertex data VES_BLEND_INDICES element is continuous, with no gaps. Thus, by minimising the world matrix array constants passing to GPU, we can support more bones for a mesh when hardware skinning is used. The hardware skinning support limit is applied to each set of vertex data in the mesh, in other words, the hardware skinning support limit is applied only to the actually used bones of each SubMeshes, not all bones across the entire Mesh.

  Because the blend index is different to the bone index, therefore, we use the index map to translate the blend index to bone index.

  The use of shared or non-shared index map is determined when model data is converted to the OGRE .mesh format.

## ◆ mMaterialName

String Ogre::SubMesh::mMaterialName

Name of the material this SubMesh uses.

Referenced by getMaterialName(), and setMaterialName().

## ◆ mParent

Mesh* Ogre::SubMesh::mParent

Reference to parent Mesh (not a smart pointer so child does not keep parent alive).

## ◆ mVao

VertexArrayObjectArray Ogre::SubMesh::mVao[NumVertexPass]

VAO to render the submesh.

One per LOD level. Each LOD may or may not share the vertex and index buffers the other levels [0] = Used for regular rendering [1] = Used for shadow map caster passes Note that mVao[1] = mVao[0] is valid. But if they're not exactly the same VertexArrayObject pointers, then they won't share any pointer.

The documentation for this class was generated from the following file:

- OgreSubMesh2.h