OGRE: Ogre::VertexDeclaration Class Reference

| OGRE 14.5 Object-Oriented Graphics Rendering Engine

Loading...
Searching...
No Matches
Ogre::VertexDeclaration Class Reference
Core » RenderSystem

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]

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

## Public Member Functions
| VertexDeclaration ()
| Standard constructor, not you should use HardwareBufferManager::createVertexDeclaration.
virtual | ~VertexDeclaration ()
const VertexElement & | addElement (unsigned short source, size_t offset, VertexElementType theType, VertexElementSemantic semantic, unsigned short index=0)
| Adds a new VertexElement to this declaration.
VertexDeclaration * | clone (HardwareBufferManagerBase *mgr=0) const
| Clones this declaration.
void | closeGapsInSource (void)
| Remove any gaps in the source buffer list used by this declaration.
const VertexElement * | findElementBySemantic (VertexElementSemantic sem, unsigned short index=0) const
| Finds a VertexElement with the given semantic and index.
VertexElementList | findElementsBySource (unsigned short source) const
| Based on the current elements, gets the size of the vertex for a given buffer source.
VertexDeclaration * | getAutoOrganisedDeclaration (bool skeletalAnimation, bool vertexAnimation, bool vertexAnimationNormals) const
| 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.
const VertexElement * | getElement (unsigned short index) const
| Get a single element.
size_t | getElementCount (void) const
| Get the number of elements in the declaration.
const VertexElementList & | getElements (void) const
| Gets read-only access to the list of vertex elements.
unsigned short | getMaxSource (void) const
| Gets the index of the highest source value referenced by this declaration.
unsigned short | getNextFreeTextureCoordinate () const
| Return the index of the next free texture coordinate set which may be added to this declaration.
size_t | getVertexSize (unsigned short source) const
| Gets the vertex size defined by this declaration for a given source.
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.
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.
bool | operator!= (const VertexDeclaration &rhs) const
bool | operator== (const VertexDeclaration &rhs) const
void | removeAllElements (void)
| Remove all elements.
void | removeElement (unsigned short elem_index)
| Remove the element at the given index from this declaration.
void | removeElement (VertexElementSemantic semantic, unsigned short index=0)
| Remove the element with the given semantic and usage index.
void | sort (void)
| Sorts the elements in this list to be compatible with D3D7 graphics cards.

## Detailed Description

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

The ordering is important on Direct3D9 with Direct3D 7 grade cards. Calling closeGapsInSource() will format this VertexDeclaration accordingly.

Whilst GL and more modern graphics cards in D3D will allow you to defy these rules, sticking to them will reduce state changes and improve performance on modern APIs as well.

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

## Member Typedef Documentation

## ◆ VertexElementList

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

Defines the list of vertex elements that makes up this declaration.

## Constructor & Destructor Documentation

## ◆ VertexDeclaration()

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

Standard constructor, not you should use HardwareBufferManager::createVertexDeclaration.

Referenced by clone(), getAutoOrganisedDeclaration(), operator!=(), and operator==().

## ◆ ~VertexDeclaration()

virtual Ogre::VertexDeclaration::~VertexDeclaration | ( |  | ) |
| virtual

## Member Function Documentation

## ◆ getElementCount()

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

Get the number of elements in the declaration.

## ◆ getElements()

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

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

## ◆ getElement()

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

Get a single element.

## ◆ sort()

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

Sorts the elements in this list to be compatible with D3D7 graphics cards.

the order is as follows: position, blending weights, normals, diffuse colours, specular colours, texture coordinates

## ◆ closeGapsInSource()

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

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

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.

Whilst in theory you have completely full reign over the format of you vertices, in reality there are some restrictions. D3D7 grade hardware imposes a fixed ordering on the elements which are pulled from each buffer:

- VertexElements should be added in the following order, and the order of the elements within any shared buffer should be as follows:
  1. Positions
  2. Blending weights
  3. Normals
  4. Diffuse colours
  5. Specular colours
  6. Texture coordinates (starting at 0, listed in order, with no gaps)
- You must not have unused gaps in your buffers which are not referenced by any VertexElement
- You must not cause the buffer & offset settings of 2 VertexElements to overlap

OpenGL and D3D9 compatible hardware are not required to follow these strict limitations, so you might find, for example that if you broke these rules your application would run under OpenGL and under DirectX on recent cards, but it is not guaranteed to run on older hardware under DirectX unless you stick to the above rules.

Note
  This will also call sort()

## ◆ getAutoOrganisedDeclaration()

VertexDeclaration * Ogre::VertexDeclaration::getAutoOrganisedDeclaration | ( | bool | skeletalAnimation,
|  | bool | vertexAnimation,
|  | bool | vertexAnimationNormals ) const

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.

Different buffer organisations and buffer usages will be returned depending on the parameters passed to this method.

Parameters

  skeletalAnimation | Whether this vertex data is going to be skeletally animated
  vertexAnimation | Whether this vertex data is going to be vertex animated
  vertexAnimationNormals | Whether vertex data animation is going to include normals animation

References VertexDeclaration().

## ◆ getMaxSource()

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

Gets the index of the highest source value referenced by this declaration.

## ◆ addElement()

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

Adds a new VertexElement to this declaration.

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 VertexBufferBinding 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.

## ◆ insertElement()

const VertexElement & Ogre::VertexDeclaration::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.

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

  atPosition | Position where the new element is inserted
  source | The binding index of HardwareVertexBuffer which will provide the source for this element. See VertexBufferBinding 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.

## ◆ removeElement() [1/2]

void Ogre::VertexDeclaration::removeElement | ( | unsigned short | elem_index | ) |

Remove the element at the given index from this declaration.

## ◆ removeElement() [2/2]

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

Remove the element with the given semantic and usage index.

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.

## ◆ removeAllElements()

void Ogre::VertexDeclaration::removeAllElements | ( | void |  | ) |

Remove all elements.

## ◆ modifyElement()

void Ogre::VertexDeclaration::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.

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

## ◆ findElementBySemantic()

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

Finds a VertexElement with the given semantic and index.

Returns
  The VertexElement or null, if the element is not found

## ◆ findElementsBySource()

VertexElementList Ogre::VertexDeclaration::findElementsBySource | ( | unsigned short | source | ) | const

Based on the current elements, gets the size of the vertex for a given buffer source.

Parameters

  source | The buffer binding index for which to get the vertex size. Gets a list of elements which use a given source.

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

## ◆ getVertexSize()

size_t Ogre::VertexDeclaration::getVertexSize | ( | unsigned short | source | ) | const

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

## ◆ getNextFreeTextureCoordinate()

unsigned short Ogre::VertexDeclaration::getNextFreeTextureCoordinate | ( |  | ) | const

Return the index of the next free texture coordinate set which may be added to this declaration.

## ◆ clone()

VertexDeclaration * Ogre::VertexDeclaration::clone | ( | HardwareBufferManagerBase * | mgr = 0 | ) | const

Clones this declaration.

Parameters

  mgr | Optional HardwareBufferManager to use for creating the clone (if null, use the current default).

References VertexDeclaration(), and OGRE_NODISCARD.

## ◆ operator==()

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

References VertexDeclaration().

## ◆ operator!=()

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

References VertexDeclaration().

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

- OgreHardwareVertexBuffer.h