Main Page Namespace List Class Hierarchy Alphabetical List Compound List File List Namespace Members Compound Members File Members Related Pages

# Ogre::VertexDeclaration Class Reference

This class declares the format of a set of vertex inputs, which can be issued to the rendering API through a RenderOperation. More...

`#include <OgreHardwareVertexBuffer.h>`

Inheritance diagram for Ogre::VertexDeclaration:

[legend]
List of all members.

## Public Types

typedef std::list< VertexElement > | VertexElementList
| Defines the list of vertex elements that makes up this declaration.

## Public Methods

| VertexDeclaration ()
| Standard constructor, not you should use HardwareBufferManager::createVertexDeclaration.
virtual | ~VertexDeclaration ()
size_t | getElementCount (void)
| Get the number of elements in the declaration.
const VertexElementList & | getElements (void) const
| Gets read-only access to the list of vertex elements.
const VertexElement * | getElement (unsigned short index)
| Get a single element.
void | sort (void)
| Sorts the elements in this list to be compatible with the maximum number of rendering APIs / graphics cards.
void | closeGapsInSource (void)
| Remove any gaps in the source buffer list used by this declaration.
VertexDeclaration * | getAutoOrganisedDeclaration (bool animated)
| Generates a new VertexDeclaration for optimal usage based on the current vertex declaration, which can be used with VertexData::reorganiseBuffers later if you wish, or simply used as a template.
unsigned short | getMaxSource (void) const
| Gets the indeex of the highest source value referenced by this declaration.
virtual const VertexElement & | addElement (unsigned short source, size_t offset, VertexElementType theType, VertexElementSemantic semantic, unsigned short index=0)
| Adds a new VertexElement to this declaration.
virtual const VertexElement & | insertElement (unsigned short atPosition, unsigned short source, size_t offset, VertexElementType theType, VertexElementSemantic semantic, unsigned short index=0)
| Inserts a new VertexElement at a given position in this declaration.
virtual void | removeElement (unsigned short elem_index)
| Remove the element at the given index from this declaration.
virtual void | removeElement (VertexElementSemantic semantic, unsigned short index=0)
| Remove the element with the given semantic and usage index.
virtual void | modifyElement (unsigned short elem_index, unsigned short source, size_t offset, VertexElementType theType, VertexElementSemantic semantic, unsigned short index=0)
| Modify an element in-place, params as addElement.
virtual const VertexElement * | findElementBySemantic (VertexElementSemantic sem, unsigned short index=0)
| Finds a VertexElement with the given semantic, and index if there is more than one element with the same semantic.
virtual VertexElementList | findElementsBySource (unsigned short source)
| Gets a list of elements which use a given source.
virtual size_t | getVertexSize (unsigned short source)
| Gets the vertex size defined by this declaration for a given source.
virtual VertexDeclaration * | clone (void)
| Clones this declaration.
bool | operator== (const VertexDeclaration &rhs) const
bool | operator!= (const VertexDeclaration &rhs) const

## Static Public Methods

bool | vertexElementLess (const VertexElement &e1, const VertexElement &e2)
| Sort routine for vertex elements.

## Protected Attributes

VertexElementList | mElementList

## Detailed Description

This class declares the format of a set of vertex inputs, which can be issued to the rendering API through a RenderOperation.

Remarks:
  You should be aware that the ordering and structure of the VertexDeclaration can be very important on DirectX with older cards,so if you want to maintain maximum compatibility with all render systems and all cards you should be careful to follow these rules:
  1. VertexElements should be added in the following order, and the order of the elements within a shared buffer should be as follows: position, blending weights, normals, diffuse colours, specular colours, texture coordinates (in order, with no gaps)
  2. You must not have unused gaps in your buffers which are not referenced by any VertexElement
  3. You must not cause the buffer & offset settings of 2 VertexElements to overlap
  Whilst GL and more modern graphics cards in D3D will allow you to defy these rules, sticking to them will ensure that your buffers have the maximum compatibility.

  Like the other classes in this functional area, these declarations should be created and destroyed using the HardwareBufferManager.

Definition at line 262 of file OgreHardwareVertexBuffer.h.

## Member Typedef Documentation

typedef std::list<VertexElement> Ogre::VertexDeclaration::VertexElementList

| Defines the list of vertex elements that makes up this declaration. Definition at line 266 of file OgreHardwareVertexBuffer.h. Referenced by findElementsBySource().

## Constructor & Destructor Documentation

Ogre::VertexDeclaration::VertexDeclaration | ( |  | ) |

| Standard constructor, not you should use HardwareBufferManager::createVertexDeclaration. Definition at line 197 of file OgreHardwareVertexBuffer.cpp.

Ogre::VertexDeclaration::~VertexDeclaration | ( |  | ) | `[virtual]`

| Definition at line 201 of file OgreHardwareVertexBuffer.cpp.

## Member Function Documentation

const VertexElement & Ogre::VertexDeclaration::addElement | ( | unsigned short | source,
|  | size_t | offset,
|  | VertexElementType | theType,
|  | VertexElementSemantic | semantic,
|  | unsigned short | index = 0
| ) | `[virtual]`

Adds a new VertexElement to this declaration.

Remarks:
  This method adds a single element (positions, normals etc) to the end of the vertex declaration. Please read the information in VertexDeclaration about the importance of ordering and structure for compatibility with older D3D drivers.

Parameters:

  source | The binding index of HardwareVertexBuffer which will provide the source for this element. See VertexBufferBindingState for full information.
  offset | The offset in bytes where this element is located in the buffer
  theType | The data format of the element (3 floats, a colour etc)
  semantic | The meaning of the data (position, normal, diffuse colour etc)
  index | Optional index for multi-input elements like texture coordinates

Returns:
  A reference to the VertexElement added.

Reimplemented in Ogre::D3D9VertexDeclaration.

Definition at line 210 of file OgreHardwareVertexBuffer.cpp.

References mElementList, Ogre::VertexElementSemantic, and Ogre::VertexElementType.

Referenced by Ogre::BillboardSet::_createBuffers(), Ogre::VertexData::clone(), clone(), Ogre::Mesh::compileBoneAssignments(), Ogre::MeshManager::createCurvedIllusionPlane(), Ogre::MeshManager::createCurvedPlane(), Ogre::MeshManager::createPlane(), Ogre::MeshManager::createPrefabPlane(), Ogre::Entity::EntityShadowRenderable::EntityShadowRenderable(), Ogre::Frustum::Frustum(), Ogre::TTYGuiElement::initialise(), Ogre::TextAreaGuiElement::initialise(), Ogre::TerrainRenderable::initialise(), Ogre::PanelGuiElement::initialise(), Ogre::BorderPanelGuiElement::initialise(), insertElement(), Ogre::BspLevel::loadQuake3Level(), Ogre::Mesh::organiseTangentsBuffer(), Ogre::MeshSerializerImpl_v1_2::readGeometryColours(), Ogre::MeshSerializerImpl_v1_2::readGeometryNormals(), Ogre::MeshSerializerImpl_v1_2::readGeometryPositions(), Ogre::MeshSerializerImpl_v1_1::readGeometryTexCoords(), Ogre::MeshSerializerImpl_v1_2::readGeometryTexCoords(), Ogre::MeshSerializerImpl::readGeometryVertexElement(), Ogre::Rectangle2D::Rectangle2D(), Ogre::PanelGuiElement::updateTextureGeometry(), and Ogre::WireBoundingBox::WireBoundingBox().

VertexDeclaration * Ogre::VertexDeclaration::clone | ( | void |  | ) | `[virtual]`

| Clones this declaration. Definition at line 337 of file OgreHardwareVertexBuffer.cpp. References addElement(), and mElementList. Referenced by getAutoOrganisedDeclaration(), and Ogre::PatchMesh::PatchMesh().

void Ogre::VertexDeclaration::closeGapsInSource | ( | void |  | ) |

Remove any gaps in the source buffer list used by this declaration.

Remarks:
  This is useful if you've modified a declaration and want to remove any gaps in the list of buffers being used. Note, however, that if this declaration is already being used with a VertexBufferBinding, you will need to alter that too. This method is mainly useful when reorganising buffers based on an altered declaration.

Note:
  This will cause the vertex declaration to be re-sorted.

Definition at line 381 of file OgreHardwareVertexBuffer.cpp.

References getElement(), Ogre::VertexElement::getIndex(), Ogre::VertexElement::getOffset(), Ogre::VertexElement::getSemantic(), Ogre::VertexElement::getSource(), Ogre::VertexElement::getType(), mElementList, modifyElement(), and sort().

Referenced by Ogre::VertexData::reorganiseBuffers().

const VertexElement * Ogre::VertexDeclaration::findElementBySemantic | ( | VertexElementSemantic | sem,
|  | unsigned short | index = 0
| ) | `[virtual]`

Finds a VertexElement with the given semantic, and index if there is more than one element with the same semantic.

Remarks:
  If the element is not found, this method returns null.

Definition at line 284 of file OgreHardwareVertexBuffer.cpp.

References mElementList, and Ogre::VertexElementSemantic.

Referenced by Ogre::TerrainRenderable::_calculateNormals(), Ogre::TerrainRenderable::_generateVertexLighting(), Ogre::ProgressiveMesh::addWorkingData(), Ogre::Mesh::buildTangentVectors(), Ogre::EdgeListBuilder::buildTrianglesEdges(), Ogre::Entity::cloneVertexDataRemoveBlendInfo(), Ogre::Mesh::compileBoneAssignments(), Ogre::PatchSurface::defineSurface(), Ogre::PatchSurface::distributeControlPoints(), Ogre::Entity::EntityShadowRenderable::EntityShadowRenderable(), Ogre::Entity::extractTempBufferInfo(), Ogre::TerrainRenderable::initialise(), Ogre::PatchSurface::interpolateVertexData(), Ogre::EdgeListBuilder::log(), Ogre::Mesh::organiseTangentsBuffer(), Ogre::VertexData::prepareForShadowVolume(), Ogre::VertexData::reorganiseBuffers(), Ogre::Mesh::softwareVertexBlend(), and Ogre::Mesh::suggestTangentVectorBuildParams().

VertexDeclaration::VertexElementList Ogre::VertexDeclaration::findElementsBySource | ( | unsigned short | source | ) | `[virtual]`

Gets a list of elements which use a given source.

Remarks:
  Note that the list of elements is returned by value therefore is separate from the declaration as soon as this method returns.

Definition at line 302 of file OgreHardwareVertexBuffer.cpp.

References mElementList, and VertexElementList.

Referenced by Ogre::MeshSerializerImpl::readGeometryVertexBuffer(), Ogre::VertexData::reorganiseBuffers(), and Ogre::MeshSerializerImpl::writeGeometry().

VertexDeclaration * Ogre::VertexDeclaration::getAutoOrganisedDeclaration | ( | bool | animated | ) |

Generates a new VertexDeclaration for optimal usage based on the current vertex declaration, which can be used with VertexData::reorganiseBuffers later if you wish, or simply used as a template.

Parameters:

  animated | Whether this vertex data is going to be animated; this affects the choice of both usage and buffer splits.

Definition at line 412 of file OgreHardwareVertexBuffer.cpp.

References clone(), getElements(), Ogre::VertexElement::getIndex(), Ogre::VertexElement::getSemantic(), Ogre::VertexElement::getSize(), Ogre::VertexElement::getType(), modifyElement(), sort(), Ogre::VES_NORMAL, and Ogre::VES_POSITION.

const VertexElement * Ogre::VertexDeclaration::getElement | ( | unsigned short | index | ) |

| Get a single element. Definition at line 239 of file OgreHardwareVertexBuffer.cpp. References mElementList. Referenced by closeGapsInSource(), and Ogre::Mesh::compileBoneAssignments().

size_t Ogre::VertexDeclaration::getElementCount | ( | void |  | ) |

| Get the number of elements in the declaration. Definition at line 277 of file OgreHardwareVertexBuffer.h. Referenced by Ogre::Mesh::compileBoneAssignments().

const VertexDeclaration::VertexElementList & Ogre::VertexDeclaration::getElements | ( | void |  | ) | const

Gets read-only access to the list of vertex elements.

Definition at line 205 of file OgreHardwareVertexBuffer.cpp.

References mElementList.

Referenced by Ogre::GLRenderSystem::_render(), Ogre::D3DRenderSystem::_render(), Ogre::MeshSerializerImpl::calcGeometrySize(), Ogre::VertexData::clone(), getAutoOrganisedDeclaration(), Ogre::VertexData::prepareForShadowVolume(), Ogre::VertexData::reorganiseBuffers(), and Ogre::MeshSerializerImpl::writeGeometry().

unsigned short Ogre::VertexDeclaration::getMaxSource | ( | void |  | ) | const

| Gets the indeex of the highest source value referenced by this declaration. Definition at line 452 of file OgreHardwareVertexBuffer.cpp. References mElementList. Referenced by Ogre::VertexData::reorganiseBuffers().

size_t Ogre::VertexDeclaration::getVertexSize | ( | unsigned short | source | ) | `[virtual]`

Gets the vertex size defined by this declaration for a given source.

Definition at line 320 of file OgreHardwareVertexBuffer.cpp.

References mElementList.

Referenced by Ogre::BillboardSet::_createBuffers(), Ogre::D3DRenderSystem::_render(), Ogre::PatchSurface::build(), Ogre::TTYGuiElement::checkMemoryAllocation(), Ogre::TextAreaGuiElement::checkMemoryAllocation(), Ogre::MeshManager::createCurvedIllusionPlane(), Ogre::MeshManager::createPlane(), Ogre::PatchSurface::defineSurface(), Ogre::PatchSurface::distributeControlPoints(), Ogre::TerrainRenderable::initialise(), Ogre::PanelGuiElement::initialise(), Ogre::BorderPanelGuiElement::initialise(), Ogre::PatchSurface::interpolateVertexData(), Ogre::PatchMesh::load(), Ogre::MeshSerializerImpl_v1_2::readGeometryColours(), Ogre::MeshSerializerImpl_v1_2::readGeometryNormals(), Ogre::MeshSerializerImpl_v1_2::readGeometryPositions(), Ogre::MeshSerializerImpl_v1_1::readGeometryTexCoords(), Ogre::MeshSerializerImpl_v1_2::readGeometryTexCoords(), Ogre::MeshSerializerImpl::readGeometryVertexBuffer(), Ogre::Rectangle2D::Rectangle2D(), Ogre::VertexData::reorganiseBuffers(), Ogre::PanelGuiElement::updateTextureGeometry(), and Ogre::WireBoundingBox::WireBoundingBox().

const VertexElement & Ogre::VertexDeclaration::insertElement | ( | unsigned short | atPosition,
|  | unsigned short | source,
|  | size_t | offset,
|  | VertexElementType | theType,
|  | VertexElementSemantic | semantic,
|  | unsigned short | index = 0
| ) | `[virtual]`

Inserts a new VertexElement at a given position in this declaration.

Remarks:
  This method adds a single element (positions, normals etc) at a given position in this vertex declaration. Please read the information in VertexDeclaration about the importance of ordering and structure for compatibility with older D3D drivers.

Parameters:

  source | The binding index of HardwareVertexBuffer which will provide the source for this element. See VertexBufferBindingState for full information.
  offset | The offset in bytes where this element is located in the buffer
  theType | The data format of the element (3 floats, a colour etc)
  semantic | The meaning of the data (position, normal, diffuse colour etc)
  index | Optional index for multi-input elements like texture coordinates

Returns:
  A reference to the VertexElement added.

Reimplemented in Ogre::D3D9VertexDeclaration.

Definition at line 220 of file OgreHardwareVertexBuffer.cpp.

References addElement(), mElementList, Ogre::VertexElementSemantic, and Ogre::VertexElementType.

Referenced by Ogre::Mesh::compileBoneAssignments().

void Ogre::VertexDeclaration::modifyElement | ( | unsigned short | elem_index,
|  | unsigned short | source,
|  | size_t | offset,
|  | VertexElementType | theType,
|  | VertexElementSemantic | semantic,
|  | unsigned short | index = 0
| ) | `[virtual]`

Modify an element in-place, params as addElement.

Remarks:
  Please read the information in VertexDeclaration about the importance of ordering and structure for compatibility with older D3D drivers.

Reimplemented in Ogre::D3D9VertexDeclaration.

Definition at line 274 of file OgreHardwareVertexBuffer.cpp.

References mElementList, Ogre::VertexElementSemantic, and Ogre::VertexElementType.

Referenced by closeGapsInSource(), getAutoOrganisedDeclaration(), and Ogre::VertexData::prepareForShadowVolume().

bool Ogre::VertexDeclaration::operator!= | ( | const VertexDeclaration & | rhs | ) | const

| Definition at line 409 of file OgreHardwareVertexBuffer.h.

bool Ogre::VertexDeclaration::operator== | ( | const VertexDeclaration & | rhs | ) | const

| Definition at line 392 of file OgreHardwareVertexBuffer.h. References mElementList.

void Ogre::VertexDeclaration::removeElement | ( | VertexElementSemantic | semantic,
|  | unsigned short | index = 0
| ) | `[virtual]`

Remove the element with the given semantic and usage index.

Remarks:
  In this case 'index' means the usage index for repeating elements such as texture coordinates. For other elements this will always be 0 and does not refer to the index in the vector.

Definition at line 260 of file OgreHardwareVertexBuffer.cpp.

References mElementList, and Ogre::VertexElementSemantic.

void Ogre::VertexDeclaration::removeElement | ( | unsigned short | elem_index | ) | `[virtual]`

| Remove the element at the given index from this declaration. Reimplemented in Ogre::D3D9VertexDeclaration. Definition at line 251 of file OgreHardwareVertexBuffer.cpp. References mElementList. Referenced by Ogre::Entity::cloneVertexDataRemoveBlendInfo(), Ogre::Mesh::compileBoneAssignments(), and Ogre::PanelGuiElement::updateTextureGeometry().

void Ogre::VertexDeclaration::sort | ( | void |  | ) |

Sorts the elements in this list to be compatible with the maximum number of rendering APIs / graphics cards.

Remarks:
  Older graphics cards require vertex data to be presented in a more rigid way, as defined in the main documentation for this class. As well as the ordering being important, where shared source buffers are used, the declaration must list all the elements for each source in turn.

Definition at line 376 of file OgreHardwareVertexBuffer.cpp.

References mElementList.

Referenced by closeGapsInSource(), and getAutoOrganisedDeclaration().

bool Ogre::VertexDeclaration::vertexElementLess | ( | const VertexElement & | e1,
|  | const VertexElement & | e2
| ) | `[static]`

| Sort routine for vertex elements. Definition at line 351 of file OgreHardwareVertexBuffer.cpp. References Ogre::VertexElement::getIndex(), Ogre::VertexElement::getSemantic(), and Ogre::VertexElement::getSource().

## Member Data Documentation

VertexElementList Ogre::VertexDeclaration::mElementList`[protected]`

| Definition at line 270 of file OgreHardwareVertexBuffer.h. Referenced by addElement(), clone(), closeGapsInSource(), findElementBySemantic(), findElementsBySource(), Ogre::D3D9VertexDeclaration::getD3DVertexDeclaration(), getElement(), getElements(), getMaxSource(), getVertexSize(), insertElement(), modifyElement(), operator==(), removeElement(), and sort().

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

- OgreHardwareVertexBuffer.h
- OgreHardwareVertexBuffer.cpp

Copyright © 2002-2003 by The OGRE Team
Last modified Sun Nov 28 19:51:46 2004