gfxVertexFormat.h

Public Functions

getGFXVertexFormat()

Helper template function which returns the correct GFXVertexFormat object for a vertex structure.

  1
  2//-----------------------------------------------------------------------------
  3// Copyright (c) 2012 GarageGames, LLC
  4//
  5// Permission is hereby granted, free of charge, to any person obtaining a copy
  6// of this software and associated documentation files (the "Software"), to
  7// deal in the Software without restriction, including without limitation the
  8// rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
  9// sell copies of the Software, and to permit persons to whom the Software is
 10// furnished to do so, subject to the following conditions:
 11//
 12// The above copyright notice and this permission notice shall be included in
 13// all copies or substantial portions of the Software.
 14//
 15// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 16// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 17// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 18// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 19// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
 20// FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
 21// IN THE SOFTWARE.
 22//-----------------------------------------------------------------------------
 23
 24#ifndef _GFXVERTEXFORMAT_H_
 25#define _GFXVERTEXFORMAT_H_
 26
 27#ifndef _TVECTOR_H_
 28#include "core/util/tVector.h"
 29#endif
 30#ifndef _GFXENUMS_H_
 31#include "gfx/gfxEnums.h"
 32#endif
 33
 34
 35/// The known Torque vertex element semantics.  You can use
 36/// other semantic strings, but they will be interpreted as
 37/// a TEXCOORD.
 38/// @see GFXVertexElement
 39/// @see GFXVertexFormat
 40namespace GFXSemantic
 41{
 42   extern const String POSITION;
 43   extern const String NORMAL;
 44   extern const String BINORMAL;
 45   extern const String TANGENT;
 46   extern const String TANGENTW;
 47   extern const String COLOR;
 48   extern const String TEXCOORD;
 49   extern const String BLENDWEIGHT;
 50   extern const String BLENDINDICES;
 51   extern const String PADDING;
 52}
 53
 54
 55/// This is a simple wrapper for the platform specific
 56/// vertex declaration data which is held by the vertex
 57/// format.  
 58///
 59/// If your using it... you probably shouldn't be.
 60///
 61/// @see GFXVertexFormat
 62class GFXVertexDecl
 63{
 64public:
 65   virtual ~GFXVertexDecl() {}
 66};
 67
 68
 69/// The element structure helps define the data layout 
 70/// for GFXVertexFormat.
 71///
 72/// @see GFXVertexFormat
 73///
 74class GFXVertexElement
 75{
 76   friend class GFXVertexFormat;
 77
 78protected:
 79
 80   /// The stream index when rendering from multiple
 81   /// vertex streams.  In most cases this is 0.
 82   U32 mStreamIndex;
 83
 84   /// A valid Torque shader symantic.
 85   /// @see GFXSemantic   
 86   String mSemantic;
 87
 88   /// The semantic index is used where there are
 89   /// multiple semantics of the same type.  For 
 90   /// instance with texcoords.
 91   U32 mSemanticIndex;
 92
 93   /// The element type.
 94   GFXDeclType mType;
 95
 96public:
 97
 98   /// Default constructor.
 99   GFXVertexElement()
100      :  mStreamIndex( 0 ),
101         mSemanticIndex( 0 ),         
102         mType( GFXDeclType_Float4 )
103   {
104   }
105
106   /// Copy constructor.
107   GFXVertexElement( const GFXVertexElement &elem )
108      :  mStreamIndex( elem.mStreamIndex ),
109         mSemantic( elem.mSemantic ),
110         mSemanticIndex( elem.mSemanticIndex ),         
111         mType( elem.mType )
112   {
113   }
114
115   /// Returns the stream index.
116   U32 getStreamIndex() const { return mStreamIndex; }
117
118   /// Returns the semantic name which is usually a
119   /// valid Torque semantic.
120   /// @see GFXSemantic
121   const String& getSemantic() const { return mSemantic; }
122
123   /// Returns the semantic index which is used where there
124   /// are multiple semantics of the same type.  For instance
125   /// with texcoords.
126   U32 getSemanticIndex() const { return mSemanticIndex; }
127
128   /// Returns the type for the semantic.
129   GFXDeclType getType() const { return mType; }
130
131   /// Returns true of the semantic matches.
132   bool isSemantic( const String& str ) const { return ( mSemantic == str ); }
133
134   /// Returns the size in bytes of the semantic type.
135   U32 getSizeInBytes() const;
136};
137
138
139/// The vertex format structure usually created via the declare and 
140/// implement macros.
141///
142/// You can use this class directly to create a vertex format, but
143/// note that it is expected to live as long as the VB that uses it 
144/// exists.
145///
146/// @see GFXDeclareVertexFormat
147/// @see GFXImplementVertexFormat
148/// @see GFXVertexElement
149///
150class GFXVertexFormat
151{
152public:
153
154   /// Default constructor for an empty format.
155   GFXVertexFormat();
156
157   /// The copy constructor.
158   GFXVertexFormat( const GFXVertexFormat &format ) { copy( format ); }
159
160   /// Tell this format it has instancing
161   void enableInstancing();
162
163   /// Copy the other vertex format.
164   void copy( const GFXVertexFormat &format );
165
166   /// Used to append a vertex format to the end of this one.
167   void append( const GFXVertexFormat &format, U32 streamIndex = -1 );
168
169   /// Returns a unique description string for this vertex format.
170   const String& getDescription() const;
171
172   /// Clears all the vertex elements.
173   void clear();   
174
175   /// Adds a vertex element to the format.
176   ///
177   /// @param semantic A valid Torque semantic string.
178   /// @param type The element type.
179   /// @param index The semantic index which is typically only used for texcoords.
180   ///
181   void addElement( const String& semantic, GFXDeclType type, U32 index = 0, U32 stream = 0 );
182   
183   /// Returns true if there is a NORMAL semantic in this vertex format.
184   bool hasNormal() const;
185
186   /// Returns true if there is a TANGENT semantic in this vertex format.
187   bool hasTangent() const;
188
189   /// Returns true if there is a COLOR semantic in this vertex format.
190   bool hasColor() const;
191   
192   /// Returns true if there is a BLENDWEIGHT or BLENDINDICES semantic in this vertex format.
193   bool hasBlendIndices() const;
194
195   /// Return true if instancing is used with this vertex format.
196   bool hasInstancing() const;
197
198   /// Returns number of blend indices
199   U32 getNumBlendIndices() const;
200
201   /// Returns the texture coordinate count by 
202   /// counting the number of TEXCOORD semantics.
203   U32 getTexCoordCount() const;
204
205   /// Returns true if these two formats are equal.
206   inline bool isEqual( const GFXVertexFormat &format ) const;
207
208   /// Returns the total elements in this format.
209   U32 getElementCount() const { return mElements.size(); }
210
211   /// Returns the vertex element by index.
212   const GFXVertexElement& getElement( U32 index ) const { return mElements[index]; }
213
214   /// Returns the size in bytes of the format as described.
215   U32 getSizeInBytes() const;
216
217   /// Returns the hardware specific vertex declaration for this format.
218   GFXVertexDecl* getDecl() const;
219
220protected:
221
222   /// We disable the copy operator.
223   GFXVertexFormat& operator=( const GFXVertexFormat& ) { return *this; }
224
225   /// Recreates the description and state when 
226   /// the format has been modified.
227   void _updateDirty();
228
229   /// Requests the vertex declaration from the GFX device.
230   void _updateDecl();
231
232   /// Set when the element list is changed.
233   bool mDirty;
234
235   /// Is set if there is a NORMAL semantic in this vertex format.   
236   bool mHasNormal;
237
238   /// Is true if there is a TANGENT semantic in this vertex format.
239   bool mHasTangent;
240
241   /// Is true if there is a COLOR semantic in this vertex format.
242   bool mHasColor;
243   
244   /// Is true if there is a BLENDWEIGHT or BLENDINDICES semantic in this vertex format.
245   bool mHasBlendIndices;
246
247   /// Is instaning used with this vertex format.
248   bool mHasInstancing;
249
250   /// The texture coordinate count by counting the 
251   /// number of "TEXCOORD" semantics.
252   U32 mTexCoordCount;
253
254   /// The size in bytes of the vertex format as described.
255   U32 mSizeInBytes;
256
257   /// An interned string which uniquely identifies the format.
258   String mDescription;
259   
260   /// The elements of the vertex format.
261   Vector<GFXVertexElement> mElements;
262
263   /// The hardware specific vertex declaration.
264   GFXVertexDecl *mDecl;
265};
266
267
268inline bool GFXVertexFormat::isEqual( const GFXVertexFormat &format ) const 
269{
270   // Comparing the strings works because we know both 
271   // these are interned strings.  This saves one comparison
272   // over the string equality operator.
273   return getDescription().c_str() == format.getDescription().c_str(); 
274}
275
276
277/// This template class is usused to initialize the format in 
278/// the GFXImplement/DeclareVertexFormat macros.  You shouldn't
279/// need to use it directly in your code.
280///
281/// @see GFXVertexFormat
282/// @see GFXImplementVertexFormat
283///
284template<class T>
285class _GFXVertexFormatConstructor : public GFXVertexFormat
286{
287protected:
288
289   void _construct();
290
291public:
292
293   _GFXVertexFormatConstructor() { _construct(); }
294};
295
296
297/// Helper template function which returns the correct 
298/// GFXVertexFormat object for a vertex structure.
299/// @see GFXVertexFormat
300template<class T> inline const GFXVertexFormat* getGFXVertexFormat();
301
302#define GFX_VERTEX_STRUCT struct
303
304
305/// The vertex format declaration which is usally placed in your header 
306/// file.  It should be used in conjunction with the implementation macro.
307/// 
308/// @param name The name for the vertex structure.
309///
310/// @code
311///   
312///   // A simple vertex format declaration.
313///   GFXDeclareVertexFormat( GFXVertexPCT )
314///   {
315///      Point3F pos;
316///      GFXVertexColor color;
317///      Point2F texCoord;
318///   }
319///
320/// @endcode
321///
322/// @see GFXImplementVertexFormat
323///
324#define GFXDeclareVertexFormat( name ) \
325   GFX_VERTEX_STRUCT name; \
326   extern const GFXVertexFormat _gfxVertexFormat##name; \
327   template<> inline const GFXVertexFormat* getGFXVertexFormat<name>() { static _GFXVertexFormatConstructor<name> vertexFormat; return &vertexFormat; } \
328   GFX_VERTEX_STRUCT name \
329
330
331/// The vertex format implementation which is usally placed in your source 
332/// file.  It should be used in conjunction with the declaration macro.
333/// 
334/// @param name The name of the vertex structure.
335///
336/// @code
337///   
338///   // A simple vertex format implementation.
339///   GFXImplementVertexFormat( GFXVertexPCT )
340///   {
341///      addElement( "POSITION", GFXDeclType_Float3 );
342///      addElement( "COLOR", GFXDeclType_Color );
343///      addElement( "TEXCOORD", GFXDeclType_Float2, 0 );
344///   }
345///
346/// @endcode
347///
348/// @see GFXDeclareVertexFormat
349///
350#define GFXImplementVertexFormat( name ) \
351   template<>   void _GFXVertexFormatConstructor<name>::_construct() \
352
353#endif // _GFXVERTEXFORMAT_H_
354