All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Macros Pages
PVRTextureUtilities.h
Go to the documentation of this file.
1 /*!***********************************************************************
2 
3  @file PVRTextureUtilities.h
4  @copyright Copyright (c) Imagination Technologies Limited.
5  @brief This is the main PVRTexLib header file. This header contains
6  a utility function for transcoding textures, as well as
7  pre-processor utilities such as; resizing, rotating, channel
8  copying and MIPMap manipulation.
9 
10 *************************************************************************/
11 
12 #ifndef _PVRTEXTURE_UTILITIES_H
13 #define _PVRTEXTURE_UTILITIES_H
14 
15 #include "PVRTextureFormat.h"
16 #include "PVRTexture.h"
17 
18 namespace pvrtexture
19 {
20  /*!***********************************************************************
21  @brief Resizes the texture to new specified dimensions. Filtering
22  mode is specified with "eResizeMode".
23  @param[in] sTexture Texture to resize
24  @param[in] u32NewWidth New width
25  @param[in] u32NewHeight New height
26  @param[in] u32NewDepth New depth
27  @param[in] eResizeMode Filtering mode
28  @return True if the method succeeds.
29  *************************************************************************/
30  bool PVR_DLL Resize(CPVRTexture& sTexture, const uint32& u32NewWidth, const uint32& u32NewHeight, const uint32& u32NewDepth, const EResizeMode eResizeMode);
31 
32  /*!***********************************************************************
33  @brief Resizes the canvas of a texture to new specified dimensions. Filtering
34  mode is specified with "eResizeMode".
35  @details Offset area is filled with transparent black colour.
36  @param[in] sTexture Texture
37  @param[in] u32NewWidth New width
38  @param[in] u32NewHeight New height
39  @param[in] u32NewDepth New depth
40  @param[in] i32XOffset X Offset value from the top left corner
41  @param[in] i32YOffset Y Offset value from the top left corner
42  @param[in] i32ZOffset Z Offset value from the top left corner
43  @return True if the method succeeds.
44  *************************************************************************/
45  bool PVR_DLL ResizeCanvas(CPVRTexture& sTexture, const uint32& u32NewWidth, const uint32& u32NewHeight, const uint32& u32NewDepth, const int32& i32XOffset, const int32& i32YOffset, const int32& i32ZOffset);
46 
47  /*!***********************************************************************
48  @brief Rotates a texture by 90 degrees around the given axis. bForward controls direction of rotation.
49  @param[in] sTexture Texture to rotate
50  @param[in] eRotationAxis Rotation axis
51  @param[in] bForward Direction of rotation; 1 = clockwise, 0 = anti-clockwise
52  @return True if the method succeeds or not.
53  *************************************************************************/
54  bool PVR_DLL Rotate90(CPVRTexture& sTexture, const EPVRTAxis eRotationAxis, const bool bForward);
55 
56  /*!***********************************************************************
57  @brief Flips a texture in a given direction.
58  @param[in] sTexture Texture to flip
59  @param[in] eFlipDirection Flip direction
60  @return True if the method succeeds.
61  *************************************************************************/
62  bool PVR_DLL Flip(CPVRTexture& sTexture, const EPVRTAxis eFlipDirection);
63 
64  /*!***********************************************************************
65  @brief Adds a user specified border to the texture.
66  @param[in] sTexture Texture
67  @param[in] uiBorderX X border
68  @param[in] uiBorderY Y border
69  @param[in] uiBorderZ Z border
70  @return True if the method succeeds.
71  *************************************************************************/
72  bool PVR_DLL Border(CPVRTexture& sTexture, uint32 uiBorderX, uint32 uiBorderY, uint32 uiBorderZ);
73 
74  /*!***********************************************************************
75  @brief Pre-multiplies a texture's colours by its alpha values.
76  @param[in] sTexture Texture to premultiply
77  @return True if the method succeeds.
78  *************************************************************************/
79  bool PVR_DLL PreMultiplyAlpha(CPVRTexture& sTexture);
80 
81  /*!***********************************************************************
82  @brief Allows a texture's colours to run into any fully transparent areas.
83  @param[in] sTexture Texture
84  @return True if the method succeeds.
85  *************************************************************************/
86  bool PVR_DLL Bleed(CPVRTexture& sTexture);
87 
88  /*!***********************************************************************
89  @brief Sets the specified number of channels to values specified in pValues.
90  @param[in] sTexture Texture
91  @param[in] uiNumChannelSets Number of channels to set
92  @param[in] eChannels Channels to set
93  @param[in] pValues uint32 values to set channels to
94  @return True if the method succeeds.
95  *************************************************************************/
96  bool PVR_DLL SetChannels(CPVRTexture& sTexture, uint32 uiNumChannelSets, EChannelName *eChannels, uint32 *pValues);
97 
98  /*!***********************************************************************
99  @brief Sets the specified number of channels to values specified in float pValues.
100  @param[in] sTexture Texture
101  @param[in] uiNumChannelSets Number of channels to set
102  @param[in] eChannels Channels to set
103  @param[in] pValues float values to set channels to
104  @return True if the method succeeds.
105  *************************************************************************/
106  bool PVR_DLL SetChannelsFloat(CPVRTexture& sTexture, uint32 uiNumChannelSets, EChannelName *eChannels, float *pValues);
107 
108  /*!***********************************************************************
109  @brief Copies the specified channels from sTextureSource into sTexture.
110  @details sTextureSource is not modified so it is possible to use the
111  same texture as both input and output. When using the same
112  texture as source and destination, channels are preserved
113  between swaps (e.g. copying Red to Green and then Green to Red
114  will result in the two channels trading places correctly).
115  Channels in eChannels are set to the value of the channels
116  in eChannelSource.
117  @param[in] sTexture Destination texture to copy channels to
118  @param[in] sTextureSource Source texture to copy channels from
119  @param[in] uiNumChannelCopies Number of channels to copy
120  @param[in] eChannels Channels to set
121  @param[in] eChannelsSource Source channels to copy from
122  @return True if the method succeeds.
123  *************************************************************************/
124  bool PVR_DLL CopyChannels(CPVRTexture& sTexture, const CPVRTexture& sTextureSource, uint32 uiNumChannelCopies, EChannelName *eChannels, EChannelName *eChannelsSource);
125 
126  /*!***********************************************************************
127  @brief Generates a Normal Map from a given height map.
128  @details Assumes the red channel has the height values.
129  By default outputs to red/green/blue = x/y/z,
130  this can be overridden by specifying a channel
131  order in sChannelOrder. The channels specified
132  will output to red/green/blue/alpha in that order.
133  So "xyzh" maps x to red, y to green, z to blue
134  and h to alpha. 'h' is used to specify that the
135  original height map data should be preserved in
136  the given channel.
137  @param[in] sTexture Texture
138  @param[in] fScale Scale factor
139  @param[in] sChannelOrder Channel order
140  @return True if the method succeeds.
141  *************************************************************************/
142  bool PVR_DLL GenerateNormalMap(CPVRTexture& sTexture, const float fScale, CPVRTString sChannelOrder);
143 
144  /*!***********************************************************************
145  @brief Generates MIPMaps for a source texture. Default is to
146  create a complete MIPMap chain, however this can be
147  overridden with uiMIPMapsToDo.
148  @param[in] sTexture Texture
149  @param[in] eFilterMode Filter mode
150  @param[in] uiMIPMapsToDo Level of MIPMap chain to create
151  @return True if the method succeeds.
152  *************************************************************************/
153  bool PVR_DLL GenerateMIPMaps(CPVRTexture& sTexture, const EResizeMode eFilterMode, const uint32 uiMIPMapsToDo=PVRTEX_ALLMIPLEVELS);
154 
155  /*!***********************************************************************
156  @brief Colours a texture's MIPMap levels with artificial colours
157  for debugging. MIP levels are coloured in the following order:
158  Red, Green, Blue, Cyan, Magenta and Yellow
159  in a repeating pattern.
160  @param[in] sTexture Texture
161  @return True if the method succeeds.
162  *************************************************************************/
163  bool PVR_DLL ColourMIPMaps(CPVRTexture& sTexture);
164 
165  /*!***********************************************************************
166  @brief Transcodes a texture from its original format into a newly specified format.
167  Will either quantise or dither to lower precisions based on bDoDither.
168  uiQuality specifies the quality for PVRTC and ETC compression.
169  @param[in] sTexture Texture
170  @param[in] ptFormat Pixel format type
171  @param[in] eChannelType Channel type
172  @param[in] eColourspace Colour space
173  @param[in] eQuality Quality for PVRTC and ETC compression
174  @param[in] bDoDither Dither the texture to lower precisions
175  @return True if the method succeeds.
176  *************************************************************************/
177  bool PVR_DLL Transcode(CPVRTexture& sTexture, const PixelType ptFormat, const EPVRTVariableType eChannelType, const EPVRTColourSpace eColourspace, const ECompressorQuality eQuality=ePVRTCNormal, const bool bDoDither=false);
178 };
179 #endif //_PVRTEXTURE_UTILTIES_H
180