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 list< VertexElement >::type | VertexElementList
| Defines the list of vertex elements that makes up this declaration. More...

## Public Member Functions

| VertexDeclaration ()
| Standard constructor, not you should use HardwareBufferManager::createVertexDeclaration. More...
virtual | ~VertexDeclaration ()
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. More...
virtual VertexDeclaration * | clone (HardwareBufferManagerBase *mgr=0) const
| Clones this declaration. More...
void | closeGapsInSource (void)
| Remove any gaps in the source buffer list used by this declaration. More...
virtual const VertexElement * | findElementBySemantic (VertexElementSemantic sem, unsigned short index=0) const
| Finds a VertexElement with the given semantic, and index if there is more than one element with the same semantic. More...
virtual VertexElementList | findElementsBySource (unsigned short source) const
| Based on the current elements, gets the size of the vertex for a given buffer source. More...
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. More...
const VertexElement * | getElement (unsigned short index) const
| Get a single element. More...
size_t | getElementCount (void) const
| Get the number of elements in the declaration. More...
const VertexElementList & | getElements (void) const
| Gets read-only access to the list of vertex elements. More...
unsigned short | getMaxSource (void) const
| Gets the index of the highest source value referenced by this declaration. More...
virtual unsigned short | getNextFreeTextureCoordinate () const
| Return the index of the next free texture coordinate set which may be added to this declaration. More...
virtual size_t | getVertexSize (unsigned short source) const
| Gets the vertex size defined by this declaration for a given source. More...
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. More...
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. More...
void | operator delete (void *ptr)
void | operator delete (void *ptr, void *)
void | operator delete (void *ptr, const char *, int, const char *)
void | operator delete[] (void *ptr)
void | operator delete[] (void *ptr, const char *, int, const char *)
void * | operator new (size_t sz, const char *file, int line, const char *func)
| operator new, with debug line info More...
void * | operator new (size_t sz)
void * | operator new (size_t sz, void *ptr)
| placement operator new More...
void * | operator new[] (size_t sz, const char *file, int line, const char *func)
| array operator new, with debug line info More...
void * | operator new[] (size_t sz)
bool | operator!= (const VertexDeclaration &rhs) const
bool | operator== (const VertexDeclaration &rhs) const
virtual void | removeAllElements (void)
| Remove all elements. More...
virtual void | removeElement (unsigned short elem_index)
| Remove the element at the given index from this declaration. More...
virtual void | removeElement (VertexElementSemantic semantic, unsigned short index=0)
| Remove the element with the given semantic and usage index. More...
void | sort (void)
| Sorts the elements in this list to be compatible with the maximum number of rendering APIs / graphics cards. More...

## Static Public Member Functions

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

## 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 337 of file OgreHardwareVertexBuffer.h.

## Member Typedef Documentation

## VertexElementList

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

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

Definition at line 341 of file OgreHardwareVertexBuffer.h.

## Constructor & Destructor Documentation

## VertexDeclaration()

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

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

## ~VertexDeclaration()

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

virtual

## Member Function Documentation

## addElement()

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

## clone()

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

virtual

Clones this declaration.

Parameters

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

## closeGapsInSource()

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.

## findElementBySemantic()

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

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.

## findElementsBySource()

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

virtual

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.

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

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

Remarks
  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

## getElement()

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

Get a single element.

## getElementCount()

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

Get the number of elements in the declaration.

Definition at line 352 of file OgreHardwareVertexBuffer.h.

## getElements()

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

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

## getMaxSource()

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

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

## getNextFreeTextureCoordinate()

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

virtual

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

## getVertexSize()

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

virtual

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

## insertElement()

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

## modifyElement()

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

## operator delete() [1/3]

template<class Alloc >

void Ogre::AllocatedObject< Alloc >::operator delete | ( | void * | ptr | ) |

inherited

Definition at line 96 of file OgreMemoryAllocatedObject.h.

## operator delete() [2/3]

template<class Alloc >

void Ogre::AllocatedObject< Alloc >::operator delete | ( | void * | ptr,
|  | void * |
| ) |  |

inherited

Definition at line 102 of file OgreMemoryAllocatedObject.h.

## operator delete() [3/3]

template<class Alloc >

void Ogre::AllocatedObject< Alloc >::operator delete | ( | void * | ptr,
|  | const char * | ,
|  | int | ,
|  | const char * |
| ) |  |

inherited

Definition at line 108 of file OgreMemoryAllocatedObject.h.

## operator delete[]() [1/2]

template<class Alloc >

void Ogre::AllocatedObject< Alloc >::operator delete[] | ( | void * | ptr | ) |

inherited

Definition at line 113 of file OgreMemoryAllocatedObject.h.

## operator delete[]() [2/2]

template<class Alloc >

void Ogre::AllocatedObject< Alloc >::operator delete[] | ( | void * | ptr,
|  | const char * | ,
|  | int | ,
|  | const char * |
| ) |  |

inherited

Definition at line 119 of file OgreMemoryAllocatedObject.h.

## operator new() [1/3]

template<class Alloc >

void* Ogre::AllocatedObject< Alloc >::operator new | ( | size_t | sz,
|  | const char * | file,
|  | int | line,
|  | const char * | func
| ) |  |

inherited

operator new, with debug line info

Definition at line 68 of file OgreMemoryAllocatedObject.h.

## operator new() [2/3]

template<class Alloc >

void* Ogre::AllocatedObject< Alloc >::operator new | ( | size_t | sz | ) |

inherited

Definition at line 73 of file OgreMemoryAllocatedObject.h.

## operator new() [3/3]

template<class Alloc >

void* Ogre::AllocatedObject< Alloc >::operator new | ( | size_t | sz,
|  | void * | ptr
| ) |  |

inherited

placement operator new

Definition at line 79 of file OgreMemoryAllocatedObject.h.

## operator new[]() [1/2]

template<class Alloc >

void* Ogre::AllocatedObject< Alloc >::operator new[] | ( | size_t | sz,
|  | const char * | file,
|  | int | line,
|  | const char * | func
| ) |  |

inherited

array operator new, with debug line info

Definition at line 86 of file OgreMemoryAllocatedObject.h.

## operator new[]() [2/2]

template<class Alloc >

void* Ogre::AllocatedObject< Alloc >::operator new[] | ( | size_t | sz | ) |

inherited

Definition at line 91 of file OgreMemoryAllocatedObject.h.

## operator!=()

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

Definition at line 501 of file OgreHardwareVertexBuffer.h.

## operator==()

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

Definition at line 484 of file OgreHardwareVertexBuffer.h.

References mElementList.

## removeAllElements()

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

virtual

Remove all elements.

## removeElement() [1/2]

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

virtual

Remove the element at the given index from this declaration.

## removeElement() [2/2]

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

## sort()

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.

## vertexElementLess()

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

static

Sort routine for vertex elements.

## Member Data Documentation

## mElementList

VertexElementList Ogre::VertexDeclaration::mElementList

protected

Definition at line 345 of file OgreHardwareVertexBuffer.h.

Referenced by operator==().

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

- OgreHardwareVertexBuffer.h

Copyright © 2012 Torus Knot Software Ltd
This work is licensed under a Creative Commons Attribution-ShareAlike 3.0 Unported License.