All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Macros Pages
PVRTexture.h
Go to the documentation of this file.
1 /*!***********************************************************************
2 
3  @file PVRTexture.h
4  @copyright Copyright (c) Imagination Technologies Limited.
5  @brief Contains methods concerning basic CPVRTexture creation, saving
6  and data duplication. This is the main class for PVRTexLib.
7 
8 *************************************************************************/
9 
10 /*****************************************************************************/
44 #ifndef _PVRTEXTURE_H
45 #define _PVRTEXTURE_H
46 
47 #include "PVRTextureDefines.h"
48 #include "PVRTextureHeader.h"
49 #include "PVRTString.h"
50 
51 namespace pvrtexture
52 {
53  /*!***********************************************************************
54  @class CPVRTexture
55  @brief A full public texture container format, with support for custom
56  meta-data, and complete, optimised, resource loading code into PVRTools.
57  *************************************************************************/
59  {
60  public:
61  // Construction methods for a texture.
62 
63  /*!***********************************************************************
64  @brief Creates a new empty texture
65  @return A new CPVRTexture.
66  *************************************************************************/
67  CPVRTexture();
68 
69  /*!***********************************************************************
70  @brief Creates a new texture based on a texture header,
71  pre-allocating the correct amount of memory. If data is
72  supplied, it will be copied into memory.
73  @param[in] sHeader Texture header
74  @param[in] pData Texture data
75  @return A new CPVRTexture.
76  *************************************************************************/
77  CPVRTexture(const CPVRTextureHeader& sHeader, const void* pData=NULL);
78 
79  /*!***********************************************************************
80  @brief Creates a new texture from a filepath.
81  @param[in] szFilePath File path to existing texture
82  @return A new CPVRTexture.
83  *************************************************************************/
84  CPVRTexture(const char* szFilePath);
85 
86  /*!***********************************************************************
87  @brief Creates a new texture from a pointer that includes a header
88  structure, meta data and texture data as laid out in a file.
89  This functionality is primarily for user-defined file loading.
90  Header may be any version of pvr.
91  @param[in] pTexture Pointer to texture data
92  @return A new CPVRTexture.
93  *************************************************************************/
94  CPVRTexture( const void* pTexture );
95 
96  /*!***********************************************************************
97  @brief Creates a new texture as a copy of another.
98  @param[in] texture Texture to copy
99  @return A new CPVRTexture
100  *************************************************************************/
101  CPVRTexture(const CPVRTexture& texture);
102 
103  /*!***********************************************************************
104  @brief Deconstructor for CPVRTextures.
105  *************************************************************************/
106  ~CPVRTexture();
107 
108  /*!***********************************************************************
109  @brief Will copy the contents and information of another texture into this one.
110  @param[in] rhs Texture to copy
111  @return This texture.
112  *************************************************************************/
113  CPVRTexture& operator=(const CPVRTexture& rhs);
114 
115  // Texture accessor functions - others are inherited from CPVRTextureHeader.
116 
117  /*!***********************************************************************
118  @brief Returns a pointer into the texture's data.
119  @details It is possible to specify an offset to specific array members,
120  faces and MIP Map levels.
121  @param[in] uiMIPLevel Offset to MIP Map levels
122  @param[in] uiArrayMember Offset to array members
123  @param[in] uiFaceNumber Offset to face numbers
124  @return Pointer to a location in the texture.
125  *************************************************************************/
126  void* getDataPtr(uint32 uiMIPLevel = 0, uint32 uiArrayMember = 0, uint32 uiFaceNumber = 0) const;
127 
128  /*!***********************************************************************
129  @brief Gets the header for this texture, allowing you to create a new
130  texture based on this one with some changes. Useful for passing
131  information about a texture without passing all of its data.
132  @return Returns the header only for this texture.
133  *************************************************************************/
134  const CPVRTextureHeader& getHeader() const;
135 
136  // File io.
137 
138  /*!***********************************************************************
139  @brief When writing the texture out to a PVR file, it is often
140  desirable to pad the meta data so that the start of the
141  texture data aligns to a given boundary.
142  @details This function pads to a boundary value equal to "uiPadding".
143  For example setting uiPadding=8 will align the start of the
144  texture data to an 8 byte boundary.
145  Note - this should be called immediately before saving as
146  the value is worked out based on the current meta data size.
147  @param[in] uiPadding Padding boundary value
148  *************************************************************************/
149  void addPaddingMetaData( uint32 uiPadding );
150 
151  /*!***********************************************************************
152  @brief Writes out to a file, given a filename and path.
153  @details File type will be determined by the extension present in the string.
154  If no extension is present, PVR format will be selected.
155  Unsupported formats will result in failure.
156  @param[in] filepath File path to write to
157  @return True if the method succeeds.
158  *************************************************************************/
159  bool saveFile(const CPVRTString& filepath) const;
160 
161  /*!***********************************************************************
162  @brief Writes out to a file, stripping any extensions specified
163  and appending .pvr. This function is for legacy support only
164  and saves out to PVR Version 2 file. The target api must be
165  specified in order to save to this format.
166  @param[in] filepath File path to write to
167  @param[in] eApi Target API
168  @return True if the method succeeds.
169  *************************************************************************/
170  bool saveFileLegacyPVR(const CPVRTString& filepath, ELegacyApi eApi) const;
171 
172  private:
173  size_t m_stDataSize;
174  uint8* m_pTextureData;
175 
176  // Private IO functions
177 
178  /*!***********************************************************************
179  @brief Loads a PVR file.
180  @param[in] pTextureFile PVR texture file
181  @return True if the method succeeds.
182  *************************************************************************/
183  bool privateLoadPVRFile(FILE* pTextureFile);
184 
185  /*!***********************************************************************
186  @brief Saves a PVR File.
187  @param[in] pTextureFile PVR texture file
188  @return True if the method succeeds.
189  *************************************************************************/
190  bool privateSavePVRFile(FILE* pTextureFile) const;
191 
192  /*!***********************************************************************
193  @brief Loads a KTX file.
194  @param[in] pTextureFile PVR texture file
195  @return True if the method succeeds.
196  *************************************************************************/
197  bool privateLoadKTXFile(FILE* pTextureFile);
198 
199  /*!***********************************************************************
200  @brief Saves a KTX File.
201  @param[in] pTextureFile PVR texture file
202  @return True if the method succeeds.
203  *************************************************************************/
204  bool privateSaveKTXFile(FILE* pTextureFile) const;
205 
206  /*!***********************************************************************
207  @brief Loads a DDS file.
208  @param[in] pTextureFile PVR texture file
209  @return True if the method succeeds.
210  *************************************************************************/
211  bool privateLoadDDSFile(FILE* pTextureFile);
212 
213  /*!***********************************************************************
214  @brief Saves a DDS File.
215  @param[in] pTextureFile PVR texture file
216  @return True if the method succeeds.
217  *************************************************************************/
218  bool privateSaveDDSFile(FILE* pTextureFile) const;
219 
220  //Legacy IO
221 
222  /*!***********************************************************************
223  @brief Saves a .h File. Legacy operator
224  @param[in] pTextureFile PVR texture file
225  @param[in] filename File path to write to
226  @return True if the method succeeds.
227  *************************************************************************/
228  bool privateSaveCHeaderFile(FILE* pTextureFile, CPVRTString filename) const;
229 
230  /*!***********************************************************************
231  @brief Saves a legacy PVR File - Uses version 2 file format.
232  @param[in] pTextureFile PVR texture file
233  @param[in] eApi Target API
234  @return True if the method succeeds.
235  *************************************************************************/
236  bool privateSaveLegacyPVRFile(FILE* pTextureFile, ELegacyApi eApi) const;
237  };
238 };
239 
240 #endif //_PVRTEXTURE_H
241