OGRE-Next  4.0.0unstable
Object-Oriented Graphics Rendering Engine
Ogre::v1::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::v1::VertexDeclaration:

Public Types

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

Public Member Functions

 VertexDeclaration (HardwareBufferManagerBase *creator)
 Standard constructor, not you should use HardwareBufferManager::createVertexDeclaration. More...
 
virtual ~VertexDeclaration ()
 
uint16 _getInputLayoutId (HlmsManager *hlmsManager, OperationType opType)
 VertexDeclaration do not store OperationType, which is why we cache just the base 10 bits. More...
 
virtual const VertexElementaddElement (unsigned short source, size_t offset, VertexElementType theType, VertexElementSemantic semantic, unsigned short index=0)
 Adds a new VertexElement to this declaration. More...
 
virtual VertexDeclarationclone (HardwareBufferManagerBase *mgr=0) const
 Clones this declaration. More...
 
void closeGapsInSource ()
 Remove any gaps in the source buffer list used by this declaration. More...
 
void convertFromV2 (const VertexElement2Vec &v2Decl)
 
void convertFromV2 (const VertexElement2VecVec &v2Decl)
 
VertexElement2VecVec convertToV2 ()
 
virtual const VertexElementfindElementBySemantic (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...
 
VertexDeclarationgetAutoOrganisedDeclaration (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 VertexElementgetElement (unsigned short index) const
 Get a single element. More...
 
size_t getElementCount () const
 Get the number of elements in the declaration. More...
 
const VertexElementListgetElements () const
 Gets read-only access to the list of vertex elements. More...
 
unsigned short getMaxSource () 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 VertexElementinsertElement (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...
 
bool isSortedForV2 () const
 
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...
 
bool operator!= (const VertexDeclaration &rhs) const
 
bool operator== (const VertexDeclaration &rhs) const
 
virtual void removeAllElements ()
 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 ()
 Sorts the elements in this list to be compatible with the maximum number of rendering APIs / graphics cards. More...
 
void sortForV2 ()
 

Static Public Member Functions

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

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.

Member Typedef Documentation

◆ VertexElementList

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

Constructor & Destructor Documentation

◆ VertexDeclaration()

Ogre::v1::VertexDeclaration::VertexDeclaration ( HardwareBufferManagerBase creator)

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

◆ ~VertexDeclaration()

virtual Ogre::v1::VertexDeclaration::~VertexDeclaration ( )
virtual

Member Function Documentation

◆ _getInputLayoutId()

uint16 Ogre::v1::VertexDeclaration::_getInputLayoutId ( HlmsManager hlmsManager,
OperationType  opType 
)

VertexDeclaration do not store OperationType, which is why we cache just the base 10 bits.

This function is not const as it will modify mBaseInputLayoutId if the layout is dirty

See also
HlmsManager::_getInputLayoutId
VertexDeclaration::mBaseInputLayoutId
Parameters
hlmsManager
opType
Returns

◆ addElement()

virtual const VertexElement& Ogre::v1::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
sourceThe binding index of HardwareVertexBuffer which will provide the source for this element. See VertexBufferBinding for full information.
offsetThe offset in bytes where this element is located in the buffer
theTypeThe data format of the element (3 floats, a colour etc)
semanticThe meaning of the data (position, normal, diffuse colour etc)
indexOptional index for multi-input elements like texture coordinates
Returns
A reference to the VertexElement added.

◆ clone()

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

Clones this declaration.

Parameters
mgrOptional HardwareBufferManager to use for creating the clone (if null, use the current default).

◆ closeGapsInSource()

void Ogre::v1::VertexDeclaration::closeGapsInSource ( )

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.

◆ convertFromV2() [1/2]

void Ogre::v1::VertexDeclaration::convertFromV2 ( const VertexElement2Vec v2Decl)

◆ convertFromV2() [2/2]

void Ogre::v1::VertexDeclaration::convertFromV2 ( const VertexElement2VecVec v2Decl)

◆ convertToV2()

VertexElement2VecVec Ogre::v1::VertexDeclaration::convertToV2 ( )

◆ findElementBySemantic()

virtual const VertexElement* Ogre::v1::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::v1::VertexDeclaration::findElementsBySource ( unsigned short  source) const
virtual

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

Parameters
sourceThe 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::v1::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
skeletalAnimationWhether this vertex data is going to be skeletally animated
vertexAnimationWhether this vertex data is going to be vertex animated
vertexAnimationNormalsWhether vertex data animation is going to include normals animation

◆ getElement()

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

Get a single element.

◆ getElementCount()

size_t Ogre::v1::VertexDeclaration::getElementCount ( ) const
inline

Get the number of elements in the declaration.

◆ getElements()

const VertexElementList& Ogre::v1::VertexDeclaration::getElements ( ) const

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

◆ getMaxSource()

unsigned short Ogre::v1::VertexDeclaration::getMaxSource ( ) const

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

◆ getNextFreeTextureCoordinate()

virtual unsigned short Ogre::v1::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::v1::VertexDeclaration::getVertexSize ( unsigned short  source) const
virtual

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

◆ insertElement()

virtual const VertexElement& Ogre::v1::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
sourceThe binding index of HardwareVertexBuffer which will provide the source for this element. See VertexBufferBinding for full information.
offsetThe offset in bytes where this element is located in the buffer
theTypeThe data format of the element (3 floats, a colour etc)
semanticThe meaning of the data (position, normal, diffuse colour etc)
indexOptional index for multi-input elements like texture coordinates
Returns
A reference to the VertexElement added.

◆ isSortedForV2()

bool Ogre::v1::VertexDeclaration::isSortedForV2 ( ) const

◆ modifyElement()

virtual void Ogre::v1::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!=()

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

◆ operator==()

bool Ogre::v1::VertexDeclaration::operator== ( const VertexDeclaration rhs) const
inline

◆ removeAllElements()

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

Remove all elements.

◆ removeElement() [1/2]

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

Remove the element at the given index from this declaration.

◆ removeElement() [2/2]

virtual void Ogre::v1::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::v1::VertexDeclaration::sort ( )

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.

◆ sortForV2()

void Ogre::v1::VertexDeclaration::sortForV2 ( )

◆ vertexElementLess()

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

Sort routine for vertex elements.

◆ vertexElementLessForV2()

static bool Ogre::v1::VertexDeclaration::vertexElementLessForV2 ( const VertexElement e1,
const VertexElement e2 
)
static

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