All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Macros Pages
PVRTextureHeader.h
Go to the documentation of this file.
1 /*!***********************************************************************
2 
3  @file PVRTextureHeader.h
4  @copyright Copyright (c) Imagination Technologies Limited.
5  @brief Texture header methods.
6  @details Includes pixel and channel type methods, size retrieval and
7  dimension manipulation. As well as set and get methods for
8  BumpMaps, Meta Data and cube map order.
9 
10 *************************************************************************/
11 
12 #ifndef _PVRTEXTURE_HEADER_H
13 #define _PVRTEXTURE_HEADER_H
14 
15 #include "PVRTextureDefines.h"
16 #include "PVRTextureFormat.h"
17 #include "PVRTString.h"
18 #include "PVRTMap.h"
19 
20 namespace pvrtexture
21 {
22  /*!***********************************************************************
23  @class CPVRTextureHeader
24  @brief Wrapper class for PVRTextureHeaderV3, adds 'smart' accessor functions.
25  *************************************************************************/
27  {
28  protected:
29  PVRTextureHeaderV3 m_sHeader;
30  CPVRTMap<uint32, CPVRTMap<uint32,MetaDataBlock> > m_MetaData;
31 
32  public:
33  // Construction methods for a texture header.
34  /*!***********************************************************************
35  @brief Default constructor for a CPVRTextureHeader. Returns an empty header.
36  @return A new texture header.
37  *************************************************************************/
39 
40  /*!***********************************************************************
41  @brief Creates a new texture header from a PVRTextureHeaderV3,
42  and appends Meta data if any is supplied.
43  @param[in] fileHeader PVRTextureHeaderV3
44  @param[in] metaDataCount Number of Meta data blocks to add
45  @param[in] metaData Pointer to meta data block
46  @return A new texture header.
47  *************************************************************************/
48  CPVRTextureHeader( PVRTextureHeaderV3 fileHeader,
49  uint32 metaDataCount=0,
50  MetaDataBlock* metaData=NULL);
51 
52  /*!***********************************************************************
53  @brief Creates a new texture header based on individual header
54  variables.
55  @param[in] u64PixelFormat PixelFormat
56  @param[in] u32Height Texture height
57  @param[in] u32Width Texture width
58  @param[in] u32Depth Texture depth
59  @param[in] u32NumMipMaps Number of MIP Maps
60  @param[in] u32NumArrayMembers Number of array members
61  @param[in] u32NumFaces Number of faces
62  @param[in] eColourSpace Colour space
63  @param[in] eChannelType Channel type
64  @param[in] bPreMultiplied Whether or not the texture's colour has been
65  pre-multiplied by the alpha values
66  @return A new texture header.
67  *************************************************************************/
68  CPVRTextureHeader( uint64 u64PixelFormat,
69  uint32 u32Height=1,
70  uint32 u32Width=1,
71  uint32 u32Depth=1,
72  uint32 u32NumMipMaps=1,
73  uint32 u32NumArrayMembers=1,
74  uint32 u32NumFaces=1,
75  EPVRTColourSpace eColourSpace=ePVRTCSpacelRGB,
76  EPVRTVariableType eChannelType=ePVRTVarTypeUnsignedByteNorm,
77  bool bPreMultiplied=false);
78 
79  /*!***********************************************************************
80  @brief Will copy the contents and information of another header into this one.
81  @param[in] rhs Header to copy.
82  @return This header.
83  *************************************************************************/
84  CPVRTextureHeader& operator=(const CPVRTextureHeader& rhs);
85 
86  // Accessor Methods for a texture's properties - getters.
87 
88  /*!***********************************************************************
89  @brief Gets the file header structure.
90  @return The file header.
91  *************************************************************************/
92  PVRTextureHeaderV3 getFileHeader() const;
93 
94  /*!***********************************************************************
95  @brief Gets the 64-bit pixel type ID of the texture.
96  @return 64-bit pixel type ID.
97  *************************************************************************/
98  PixelType getPixelType() const;
99 
100  /*!***********************************************************************
101  @brief Gets the bits per pixel of the texture format.
102  @return Number of bits per pixel.
103  *************************************************************************/
104  uint32 getBitsPerPixel() const;
105 
106  /*!***********************************************************************
107  @brief Returns the colour space of the texture.
108  @return enum representing colour space.
109  *************************************************************************/
110  EPVRTColourSpace getColourSpace() const;
111 
112  /*!***********************************************************************
113  @brief Returns the variable type that the texture's data is stored in.
114  @return enum representing the type of the texture.
115  *************************************************************************/
116  EPVRTVariableType getChannelType() const;
117 
118  /*!***********************************************************************
119  @brief Gets the width of the user specified MIP-Map
120  level for the texture
121  @param[in] uiMipLevel MIP level that user is interested in.
122  @return Width of the specified MIP-Map level.
123  *************************************************************************/
124  uint32 getWidth(uint32 uiMipLevel=PVRTEX_TOPMIPLEVEL) const;
125 
126  /*!***********************************************************************
127  @brief Gets the height of the user specified MIP-Map
128  level for the texture
129  @param[in] uiMipLevel MIP level that user is interested in.
130  @return Height of the specified MIP-Map level.
131  *************************************************************************/
132  uint32 getHeight(uint32 uiMipLevel=PVRTEX_TOPMIPLEVEL) const;
133 
134  /*!***********************************************************************
135  @brief Gets the depth of the user specified MIP-Map
136  level for the texture
137  @param[in] uiMipLevel MIP level that user is interested in.
138  @return Depth of the specified MIP-Map level.
139  *************************************************************************/
140  uint32 getDepth(uint32 uiMipLevel=PVRTEX_TOPMIPLEVEL) const;
141 
142  /*!***********************************************************************
143  @brief Gets the size in PIXELS of the texture, given various input
144  parameters. User can retrieve the total size of either all
145  surfaces or a single surface, all faces or a single face and
146  all MIP-Maps or a single specified MIP level. All of these
147  @param[in] iMipLevel Specifies a MIP level to check,
148  'PVRTEX_ALLMIPLEVELS' can be passed to get
149  the size of all MIP levels.
150  @param[in] bAllSurfaces Size of all surfaces is calculated if true,
151  only a single surface if false.
152  @param[in] bAllFaces Size of all faces is calculated if true,
153  only a single face if false.
154  @return Size in PIXELS of the specified texture area.
155  *************************************************************************/
156  uint32 getTextureSize(int32 iMipLevel=PVRTEX_ALLMIPLEVELS, bool bAllSurfaces = true, bool bAllFaces = true) const;
157 
158  /*!***********************************************************************
159  @brief Gets the size in BYTES of the texture, given various input
160  parameters. User can retrieve the size of either all
161  surfaces or a single surface, all faces or a single face
162  and all MIP-Maps or a single specified MIP level.
163  @param[in] iMipLevel Specifies a mip level to check,
164  'PVRTEX_ALLMIPLEVELS' can be passed to get
165  the size of all MIP levels.
166  @param[in] bAllSurfaces Size of all surfaces is calculated if true,
167  only a single surface if false.
168  @param[in] bAllFaces Size of all faces is calculated if true,
169  only a single face if false.
170  @return Size in BYTES of the specified texture area.
171  *************************************************************************/
172  uint32 getDataSize(int32 iMipLevel=PVRTEX_ALLMIPLEVELS, bool bAllSurfaces = true, bool bAllFaces = true) const;
173 
174  /*!***********************************************************************
175  @brief Gets the number of array members stored in this texture.
176  @return Number of array members in this texture.
177  *************************************************************************/
178  uint32 getNumArrayMembers() const;
179 
180  /*!***********************************************************************
181  @brief Gets the number of MIP-Map levels stored in this texture.
182  @return Number of MIP-Map levels in this texture.
183  *************************************************************************/
184  uint32 getNumMIPLevels() const;
185 
186  /*!***********************************************************************
187  @brief Gets the number of faces stored in this texture.
188  @return Number of faces in this texture.
189  *************************************************************************/
190  uint32 getNumFaces() const;
191 
192  /*!***********************************************************************
193  @brief Gets the data orientation for this texture.
194  @param[in] axis EPVRTAxis type specifying the axis to examine.
195  @return Enum orientation of the axis.
196  *************************************************************************/
197  EPVRTOrientation getOrientation(EPVRTAxis axis) const;
198 
199  /*!***********************************************************************
200  @brief Returns whether or not the texture is compressed using
201  PVRTexLib's FILE compression - this is independent of
202  any texture compression.
203  @return True if it is file compressed.
204  *************************************************************************/
205  bool isFileCompressed() const;
206 
207  /*!***********************************************************************
208  @brief Returns whether or not the texture's colour has been
209  pre-multiplied by the alpha values.
210  @return True if texture is premultiplied.
211  *************************************************************************/
212  bool isPreMultiplied() const;
213 
214  /*!***********************************************************************
215  @brief Returns the total size of the meta data stored in the header.
216  This includes the size of all information stored in all MetaDataBlocks.
217  @return Size, in bytes, of the meta data stored in the header.
218  *************************************************************************/
219  uint32 getMetaDataSize() const;
220 
221  /*!***********************************************************************
222  @brief Gets the OpenGL equivalent values of internal format, format
223  and type for this texture. This will return any supported
224  OpenGL texture values, it is up to the user to decide if
225  these are valid for their current platform.
226  @param[in,out] internalformat Internal format
227  @param[in,out] format Format
228  @param[in,out] type Type
229  *************************************************************************/
230  void getOGLFormat(uint32& internalformat, uint32& format, uint32& type) const;
231 
232  /*!***********************************************************************
233  @brief Gets the OpenGLES equivalent values of internal format,
234  format and type for this texture. This will return any
235  supported OpenGLES texture values, it is up to the user
236  to decide if these are valid for their current platform.
237  @param[in,out] internalformat Internal format
238  @param[in,out] format Format
239  @param[in,out] type Type
240  *************************************************************************/
241  void getOGLESFormat(uint32& internalformat, uint32& format, uint32& type) const;
242 
243  /*!***********************************************************************
244  @brief Gets the D3DFormat (up to DirectX 9 and Direct 3D Mobile)
245  equivalent values for this texture. This will return any
246  supported D3D texture formats, it is up to the user to
247  decide if this is valid for their current platform.
248  @return D3D format, represented by an uint32.
249  *************************************************************************/
250  uint32 getD3DFormat() const;
251 
252  /*!***********************************************************************
253  @brief Gets the DXGIFormat (DirectX 10 onward) equivalent values
254  for this texture. This will return any supported DX texture
255  formats, it is up to the user to decide if this is valid
256  for their current platform.
257  @return GXGIFormat, represented by a uint32.
258  *************************************************************************/
259  uint32 getDXGIFormat() const;
260 
261  // Accessor Methods for a texture's properties - setters.
262 
263  /*!***********************************************************************
264  @brief Sets the pixel format for this texture.
265  @param[in] uPixelFormat The format of the pixel.
266  *************************************************************************/
267  void setPixelFormat(PixelType uPixelFormat);
268 
269  /*!***********************************************************************
270  @brief Sets the colour space for this texture. Default is lRGB.
271  @param[in] eColourSpace A colour space enum.
272  *************************************************************************/
273  void setColourSpace(EPVRTColourSpace eColourSpace);
274 
275  /*!***********************************************************************
276  @brief Sets the variable type for the channels in this texture.
277  @param[in] eVarType A variable type enum.
278  *************************************************************************/
279  void setChannelType(EPVRTVariableType eVarType);
280 
281  /*!***********************************************************************
282  @brief Sets the format of the texture to PVRTexLib's internal
283  representation of the OGL format.
284  @param[in,out] internalformat Internal format
285  @param[in,out] format Format
286  @param[in,out] type Type
287  @return True if successful.
288  *************************************************************************/
289  bool setOGLFormat(const uint32& internalformat, const uint32& format, const uint32& type);
290 
291  /*!***********************************************************************
292  @brief Sets the format of the texture to PVRTexLib's internal
293  representation of the OGLES format.
294  @param[in,out] internalformat Internal format
295  @param[in,out] format Format
296  @param[in,out] type Type
297  @return True if successful.
298  *************************************************************************/
299  bool setOGLESFormat(const uint32& internalformat, const uint32& format, const uint32& type);
300 
301  /*!***********************************************************************
302  @brief Sets the format of the texture to PVRTexLib's internal
303  representation of the D3D format.
304  @return True if successful.
305  *************************************************************************/
306  bool setD3DFormat(const uint32& DWORD_D3D_FORMAT);
307 
308  /*!***********************************************************************
309  @brief Sets the format of the texture to PVRTexLib's internal
310  representation of the DXGI format.
311  @return True if successful.
312  *************************************************************************/
313  bool setDXGIFormat(const uint32& DWORD_DXGI_FORMAT);
314 
315  /*!***********************************************************************
316  @brief Sets the width.
317  @param[in] newWidth The new width.
318  *************************************************************************/
319  void setWidth(uint32 newWidth);
320 
321  /*!***********************************************************************
322  @brief Sets the height.
323  @param[in] newHeight The new height.
324  *************************************************************************/
325  void setHeight(uint32 newHeight);
326 
327  /*!***********************************************************************
328  @brief Sets the depth.
329  @param[in] newDepth The new depth.
330  *************************************************************************/
331  void setDepth(uint32 newDepth);
332 
333  /*!***********************************************************************
334  @brief Sets the depth.
335  @param[in] newNumMembers The new number of members in this array.
336  *************************************************************************/
337  void setNumArrayMembers(uint32 newNumMembers);
338 
339  /*!***********************************************************************
340  @brief Sets the number of MIP-Map levels in this texture.
341  @param[in] newNumMIPLevels New number of MIP-Map levels.
342  *************************************************************************/
343  void setNumMIPLevels(uint32 newNumMIPLevels);
344 
345  /*!***********************************************************************
346  @brief Sets the number of faces stored in this texture.
347  @param[in] newNumFaces New number of faces for this texture.
348  *************************************************************************/
349  void setNumFaces(uint32 newNumFaces);
350 
351  /*!***********************************************************************
352  @brief Sets the data orientation for a given axis in this texture.
353  @param[in] eAxisOrientation Enum specifying axis and orientation.
354  *************************************************************************/
355  void setOrientation(EPVRTOrientation eAxisOrientation);
356 
357  /*!***********************************************************************
358  @brief Sets whether or not the texture is compressed using
359  PVRTexLib's FILE compression - this is independent of
360  any texture compression. Currently unsupported.
361  @param[in] isFileCompressed Sets file compression to true/false.
362  *************************************************************************/
363  void setIsFileCompressed(bool isFileCompressed);
364 
365  /*!***********************************************************************
366  @brief Sets whether or not the texture's colour has been
367  pre-multiplied by the alpha values.
368  @return isPreMultiplied Sets if texture is premultiplied.
369  *************************************************************************/
370  void setIsPreMultiplied(bool isPreMultiplied);
371 
372  // Meta Data functions - Getters.
373 
374  /*!***********************************************************************
375  @brief Returns whether the texture is a bump map or not.
376  @return True if the texture is a bump map.
377  *************************************************************************/
378  bool isBumpMap() const;
379 
380  /*!***********************************************************************
381  @brief Gets the bump map scaling value for this texture.
382  @details If the texture is not a bump map, 0.0f is returned. If the
383  texture is a bump map but no meta data is stored to
384  specify its scale, then 1.0f is returned.
385  @return Returns the bump map scale value as a float.
386  *************************************************************************/
387  float getBumpMapScale() const;
388 
389  /*!***********************************************************************
390  @brief Gets the bump map channel order relative to rgba.
391  @details For example, an RGB texture with bumps mapped to XYZ returns
392  'xyz'. A BGR texture with bumps in the order ZYX will also
393  return 'xyz' as the mapping is the same: R=X, G=Y, B=Z.
394  If the letter 'h' is present in the string, it means that
395  the height map has been stored here.
396  Other characters are possible if the bump map was created
397  manually, but PVRTexLib will ignore these characters. They
398  are returned simply for completeness.
399  @return Bump map order relative to rgba.
400  *************************************************************************/
401  CPVRTString getBumpMapOrder() const;
402 
403  /*!***********************************************************************
404  @brief Works out the number of possible texture atlas members in
405  the texture based on the w/h/d and the data size.
406  @return The number of sub textures defined by meta data.
407  *************************************************************************/
408  int getNumTextureAtlasMembers() const;
409 
410  /*!***********************************************************************
411  @brief Returns a pointer to the texture atlas data.
412  @return A pointer directly to the texture atlas data.
413  *************************************************************************/
414  const float* getTextureAtlasData() const;
415 
416  /*!***********************************************************************
417  @brief Gets the cube map face order.
418  @details Returned string will be in the form "ZzXxYy" with capitals
419  representing positive and small letters representing
420  negative. I.e. Z=Z-Positive, z=Z-Negative.
421  @return Cube map order string.
422  *************************************************************************/
423  CPVRTString getCubeMapOrder() const;
424 
425  /*!***********************************************************************
426  @brief Obtains the border size in each dimension for this texture.
427  @param[in] uiBorderWidth Border width
428  @param[in] uiBorderHeight Border height
429  @param[in] uiBorderDepth Border depth
430  *************************************************************************/
431  void getBorder(uint32& uiBorderWidth, uint32& uiBorderHeight, uint32& uiBorderDepth) const;
432 
433  /*!***********************************************************************
434  @brief Returns a block of meta data from the texture. If the meta
435  data doesn't exist, a block with data size 0 will be returned.
436  @param[in] DevFOURCC Four character descriptor representing the
437  creator of the meta data
438  @param[in] u32Key Key value representing the type of meta
439  data stored
440  @return A copy of the meta data from the texture.
441  *************************************************************************/
442  MetaDataBlock getMetaData(uint32 DevFOURCC, uint32 u32Key) const;
443 
444  /*!***********************************************************************
445  @brief Returns whether or not the specified meta data exists as
446  part of this texture header.
447  @param[in] DevFOURCC Four character descriptor representing the
448  creator of the meta data
449  @param[in] u32Key Key value representing the type of meta
450  data stored
451  @return True if the specified meta data bock exists
452  *************************************************************************/
453  bool hasMetaData(uint32 DevFOURCC, uint32 u32Key) const;
454 
455  /*!***********************************************************************
456  @brief A pointer directly to the Meta Data Map, to allow users to read out data.
457  @return A direct pointer to the MetaData map.
458  *************************************************************************/
459  const MetaDataMap* getMetaDataMap() const;
460 
461  // Meta Data functions - Setters.
462 
463  /*!***********************************************************************
464  @brief Sets a texture's bump map data.
465  @param[in] bumpScale Floating point "height" value to scale the bump map.
466  @param[in] bumpOrder Up to 4 character string, with values x,y,z,h in
467  some combination. Not all values need to be present.
468  Denotes channel order; x,y,z refer to the
469  corresponding axes, h indicates presence of the
470  original height map. It is possible to have only some
471  of these values rather than all. For example if 'h'
472  is present alone it will be considered a height map.
473  The values should be presented in RGBA order, regardless
474  of the texture format, so a zyxh order in a bgra texture
475  should still be passed as 'xyzh'. Capitals are allowed.
476  Any character stored here that is not one of x,y,z,h
477  or a NULL character will be ignored when PVRTexLib
478  reads the data, but will be preserved. This is useful
479  if you wish to define a custom data channel for instance.
480  In these instances PVRTexLib will assume it is simply
481  colour data.
482  *************************************************************************/
483  void setBumpMap(float bumpScale, CPVRTString bumpOrder="xyz");
484 
485  /*!***********************************************************************
486  @brief Sets the texture atlas coordinate meta data for later display.
487  It is up to the user to make sure that this texture atlas
488  data actually makes sense in the context of the header. It is
489  suggested that the "generateTextureAtlas" method in the tools
490  is used to create a texture atlas, manually setting one up is
491  possible but should be done with care.
492  @param[in] pAtlasData Pointer to an array of atlas data.
493  @param[in] dataSize Number of floats that the data pointer contains.
494  *************************************************************************/
495  void setTextureAtlas(float* pAtlasData, uint32 dataSize);
496 
497  /*!***********************************************************************
498  @brief Sets a texture's bump map data.
499  @param[in] cubeMapOrder Up to 6 character string, with values
500  x,X,y,Y,z,Z in some combination. Not all
501  values need to be present. Denotes face
502  order; Capitals refer to positive axis
503  positions and small letters refer to
504  negative axis positions. E.g. x=X-Negative,
505  X=X-Positive. It is possible to have only
506  some of these values rather than all, as
507  long as they are NULL terminated.
508  NB: Values past the 6th character are not read.
509  *************************************************************************/
510  void setCubeMapOrder(CPVRTString cubeMapOrder="XxYyZz");
511 
512  /*!***********************************************************************
513  @brief Sets a texture's border size data. This value is subtracted
514  from the current texture height/width/depth to get the valid
515  texture data.
516  @param[in] uiBorderWidth Border width
517  @param[in] uiBorderHeight Border height
518  @param[in] uiBorderDepth Border depth
519  *************************************************************************/
520  void setBorder(uint32 uiBorderWidth, uint32 uiBorderHeight, uint32 uiBorderDepth);
521 
522  /*!***********************************************************************
523  @brief Adds an arbitrary piece of meta data.
524  @param[in] MetaBlock Meta data block to be added.
525  *************************************************************************/
526  void addMetaData(const MetaDataBlock& MetaBlock);
527 
528  /*!***********************************************************************
529  @brief Removes a specified piece of meta data, if it exists.
530  @param[in] DevFOURCC Four character descriptor representing the
531  creator of the meta data
532  @param[in] u32Key Key value representing the type of meta
533  data stored
534  *************************************************************************/
535  void removeMetaData(const uint32& DevFOURCC, const uint32& u32Key);
536  };
537 };
538 
539 #endif