source: GTP/trunk/Lib/Geom/OgreStuff/include/OgrePixelFormat.h @ 1809

Revision 1809, 19.4 KB checked in by gumbau, 18 years ago (diff)
Line 
1/*
2-----------------------------------------------------------------------------
3This source file is part of OGRE
4    (Object-oriented Graphics Rendering Engine)
5For the latest info, see http://www.ogre3d.org/
6
7Copyright (c) 2000-2005 The OGRE Team
8Also see acknowledgements in Readme.html
9
10This program is free software; you can redistribute it and/or modify it under
11the terms of the GNU Lesser General Public License as published by the Free Software
12Foundation; either version 2 of the License, or (at your option) any later
13version.
14
15This program is distributed in the hope that it will be useful, but WITHOUT
16ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
17FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
18
19You should have received a copy of the GNU Lesser General Public License along with
20this program; if not, write to the Free Software Foundation, Inc., 59 Temple
21Place - Suite 330, Boston, MA 02111-1307, USA, or go to
22http://www.gnu.org/copyleft/lesser.txt.
23-----------------------------------------------------------------------------
24*/
25#ifndef _PixelFormat_H__
26#define _PixelFormat_H__
27
28#include "OgrePrerequisites.h"
29#include "OgreCommon.h"
30
31namespace Ogre {
32    /** The pixel format used for images, textures, and render surfaces */
33    enum PixelFormat
34    {
35        /// Unknown pixel format.
36        PF_UNKNOWN = 0,
37        /// 8-bit pixel format, all bits luminace.
38        PF_L8 = 1,
39                PF_BYTE_L = PF_L8,
40        /// 16-bit pixel format, all bits luminace.
41        PF_L16 = 2,
42                PF_SHORT_L = PF_L16,
43        /// 8-bit pixel format, all bits alpha.
44        PF_A8 = 3,
45                PF_BYTE_A = PF_A8,
46        /// 8-bit pixel format, 4 bits alpha, 4 bits luminace.
47        PF_A4L4 = 4,
48                /// 2 byte pixel format, 1 byte luminance, 1 byte alpha
49                PF_BYTE_LA = 5,
50        /// 16-bit pixel format, 5 bits red, 6 bits green, 5 bits blue.
51        PF_R5G6B5 = 6,
52                /// 16-bit pixel format, 5 bits red, 6 bits green, 5 bits blue.
53        PF_B5G6R5 = 7,
54        /// 8-bit pixel format, 2 bits blue, 3 bits green, 3 bits red.
55        PF_R3G3B2 = 31,
56        /// 16-bit pixel format, 4 bits for alpha, red, green and blue.
57        PF_A4R4G4B4 = 8,
58        /// 16-bit pixel format, 5 bits for blue, green, red and 1 for alpha.
59        PF_A1R5G5B5 = 9,
60        /// 24-bit pixel format, 8 bits for red, green and blue.
61        PF_R8G8B8 = 10,
62        /// 24-bit pixel format, 8 bits for blue, green and red.
63        PF_B8G8R8 = 11,
64        /// 32-bit pixel format, 8 bits for alpha, red, green and blue.
65        PF_A8R8G8B8 = 12,
66        /// 32-bit pixel format, 8 bits for blue, green, red and alpha.
67        PF_A8B8G8R8 = 13,
68        /// 32-bit pixel format, 8 bits for blue, green, red and alpha.
69        PF_B8G8R8A8 = 14,
70                /// 32-bit pixel format, 8 bits for red, green, blue and alpha.
71                PF_R8G8B8A8 = 28,
72        /// 32-bit pixel format, 8 bits for red, 8 bits for green, 8 bits for blue
73        /// like PF_A8R8G8B8, but alpha will get discarded
74        PF_X8R8G8B8 = 26,
75        /// 32-bit pixel format, 8 bits for blue, 8 bits for green, 8 bits for red
76        /// like PF_A8B8G8R8, but alpha will get discarded
77        PF_X8B8G8R8 = 27,
78#if OGRE_ENDIAN == OGRE_ENDIAN_BIG
79                /// 3 byte pixel format, 1 byte for red, 1 byte for green, 1 byte for blue
80                PF_BYTE_RGB = PF_R8G8B8,
81                /// 3 byte pixel format, 1 byte for blue, 1 byte for green, 1 byte for red
82                PF_BYTE_BGR = PF_B8G8R8,
83                /// 4 byte pixel format, 1 byte for blue, 1 byte for green, 1 byte for red and one byte for alpha
84                PF_BYTE_BGRA = PF_B8G8R8A8,
85                /// 4 byte pixel format, 1 byte for red, 1 byte for green, 1 byte for blue, and one byte for alpha
86                PF_BYTE_RGBA = PF_R8G8B8A8,
87#else
88                /// 3 byte pixel format, 1 byte for red, 1 byte for green, 1 byte for blue
89                PF_BYTE_RGB = PF_B8G8R8,
90                /// 3 byte pixel format, 1 byte for blue, 1 byte for green, 1 byte for red
91                PF_BYTE_BGR = PF_R8G8B8,
92                /// 4 byte pixel format, 1 byte for blue, 1 byte for green, 1 byte for red and one byte for alpha
93                PF_BYTE_BGRA = PF_A8R8G8B8,
94                /// 4 byte pixel format, 1 byte for red, 1 byte for green, 1 byte for blue, and one byte for alpha
95                PF_BYTE_RGBA = PF_A8B8G8R8,
96#endif       
97        /// 32-bit pixel format, 2 bits for alpha, 10 bits for red, green and blue.
98        PF_A2R10G10B10 = 15,
99        /// 32-bit pixel format, 10 bits for blue, green and red, 2 bits for alpha.
100        PF_A2B10G10R10 = 16,
101        /// DDS (DirectDraw Surface) DXT1 format
102        PF_DXT1 = 17,
103        /// DDS (DirectDraw Surface) DXT2 format
104        PF_DXT2 = 18,
105        /// DDS (DirectDraw Surface) DXT3 format
106        PF_DXT3 = 19,
107        /// DDS (DirectDraw Surface) DXT4 format
108        PF_DXT4 = 20,
109        /// DDS (DirectDraw Surface) DXT5 format
110        PF_DXT5 = 21,
111                // 16-bit pixel format, 16 bits (float) for red
112        PF_FLOAT16_R = 32,
113        // 48-bit pixel format, 16 bits (float) for red, 16 bits (float) for green, 16 bits (float) for blue
114        PF_FLOAT16_RGB = 22,
115        // 64-bit pixel format, 16 bits (float) for red, 16 bits (float) for green, 16 bits (float) for blue, 16 bits (float) for alpha
116        PF_FLOAT16_RGBA = 23,
117                // 16-bit pixel format, 16 bits (float) for red
118        PF_FLOAT32_R = 33,
119       // 96-bit pixel format, 32 bits (float) for red, 32 bits (float) for green, 32 bits (float) for blue
120        PF_FLOAT32_RGB = 24,
121        // 128-bit pixel format, 32 bits (float) for red, 32 bits (float) for green, 32 bits (float) for blue, 32 bits (float) for alpha
122        PF_FLOAT32_RGBA = 25,
123                // Depth texture format
124                PF_DEPTH = 29,
125                // 64-bit pixel format, 16 bits for red, green, blue and alpha
126                PF_SHORT_RGBA = 30,
127                // Number of pixel formats currently defined
128        PF_COUNT = 34
129    };
130
131    /**
132     * Flags defining some on/off properties of pixel formats
133     */
134    enum PixelFormatFlags {
135        // This format has an alpha channel
136        PFF_HASALPHA        = 0x00000001,     
137        // This format is compressed. This invalidates the values in elemBytes,
138        // elemBits and the bit counts as these might not be fixed in a compressed format.
139        PFF_COMPRESSED    = 0x00000002,
140        // This is a floating point format
141        PFF_FLOAT           = 0x00000004,         
142        // This is a depth format (for depth textures)
143        PFF_DEPTH           = 0x00000008,
144        // Format is in native endian. Generally true for the 16, 24 and 32 bits
145        // formats which can be represented as machine integers.
146        PFF_NATIVEENDIAN    = 0x00000010,
147        // This is an intensity format instead of a RGB one. The luminance
148        // replaces R,G and B. (but not A)
149        PFF_LUMINANCE       = 0x00000020
150    };
151   
152    /** Pixel component format */
153    enum PixelComponentType
154    {
155        PCT_BYTE = 0,    /// Byte per component (8 bit fixed 0.0..1.0)
156        PCT_SHORT = 1,   /// Short per component (16 bit fixed 0.0..1.0))
157        PCT_FLOAT16 = 2, /// 16 bit float per component
158        PCT_FLOAT32 = 3, /// 32 bit float per component
159        PCT_COUNT = 4    /// Number of pixel types
160    };
161   
162        /** A primitive describing a volume (3D), image (2D) or line (1D) of pixels in memory.
163        In case of a rectangle, depth must be 1.
164        Pixels are stored as a succession of "depth" slices, each containing "height" rows of
165        "width" pixels.
166    */
167    class _OgreExport PixelBox: public Box {
168    public:
169        /// Parameter constructor for setting the members manually
170        PixelBox() {}
171                /** Constructor providing extents in the form of a Box object. This constructor
172                assumes the pixel data is laid out consecutively in memory. (this
173                means row after row, slice after slice, with no space in between)
174                @param extents      Extents of the region defined by data
175                @param pixelFormat      Format of this buffer
176                @param pixelData        Pointer to the actual data
177        */
178                PixelBox(const Box &extents, PixelFormat pixelFormat, void *pixelData=0):
179                        Box(extents), data(pixelData), format(pixelFormat)
180                {
181                        setConsecutive();
182                }
183        /** Constructor providing width, height and depth. This constructor
184                assumes the pixel data is laid out consecutively in memory. (this
185                means row after row, slice after slice, with no space in between)
186                @param width        Width of the region
187                @param height       Height of the region
188                @param depth        Depth of the region
189                @param pixelFormat      Format of this buffer
190                @param pixelData    Pointer to the actual data
191        */
192        PixelBox(size_t width, size_t height, size_t depth, PixelFormat pixelFormat, void *pixelData=0):
193                Box(0, 0, 0, width, height, depth),
194                data(pixelData), format(pixelFormat)
195        {
196                setConsecutive();
197        }
198       
199        /// The data pointer
200        void *data;
201        /// The pixel format
202        PixelFormat format;
203        /** Number of elements between the leftmost pixel of one row and the left
204                pixel of the next. This value must always be equal to getWidth() (consecutive)
205                        for compressed formats.
206        */
207        size_t rowPitch;
208        /** Number of elements between the top left pixel of one (depth) slice and
209                the top left pixel of the next. This can be a negative value. Must be a multiple of
210                rowPitch. This value must always be equal to getWidth()*getHeight() (consecutive)
211                        for compressed formats.
212        */
213        size_t slicePitch;
214       
215        /** Set the rowPitch and slicePitch so that the buffer is laid out consecutive
216                in memory.
217        */       
218        void setConsecutive()
219        {
220            rowPitch = getWidth();
221            slicePitch = getWidth()*getHeight();
222        }
223        /**     Get the number of elements between one past the rightmost pixel of
224                one row and the leftmost pixel of the next row. (IE this is zero if rows
225                are consecutive).
226        */
227        size_t getRowSkip() const { return rowPitch - getWidth(); }
228        /** Get the number of elements between one past the right bottom pixel of
229                one slice and the left top pixel of the next slice. (IE this is zero if slices
230                are consecutive).
231        */
232        size_t getSliceSkip() const { return slicePitch - (getHeight() * rowPitch); }
233
234        /** Return whether this buffer is laid out consecutive in memory (ie the pitches
235                are equal to the dimensions)
236        */       
237        bool isConsecutive() const
238                {
239                        return rowPitch == getWidth() && slicePitch == getWidth()*getHeight();
240                }
241        /** Return the size (in bytes) this image would take if it was
242                laid out consecutive in memory
243        */
244        size_t getConsecutiveSize() const;
245        /** Return a subvolume of this PixelBox.
246                @param def      Defines the bounds of the subregion to return
247                @returns        A pixel box describing the region and the data in it
248                @remarks        This function does not copy any data, it just returns
249                        a PixelBox object with a data pointer pointing somewhere inside
250                        the data of object.
251                @throws Exception(ERR_INVALIDPARAMS) if def is not fully contained
252        */
253        PixelBox getSubVolume(const Box &def) const;
254    };
255   
256
257    /**
258     * Some utility functions for packing and unpacking pixel data
259     */
260    class _OgreExport PixelUtil {
261    public:
262        /** Returns the size in bytes of an element of the given pixel format.
263         @returns
264               The size in bytes of an element. See Remarks.
265         @remarks
266               Passing PF_UNKNOWN will result in returning a size of 0 bytes.
267        */
268        static size_t getNumElemBytes( PixelFormat format );
269
270        /** Returns the size in bits of an element of the given pixel format.
271          @returns
272               The size in bits of an element. See Remarks.
273           @remarks
274               Passing PF_UNKNOWN will result in returning a size of 0 bits.
275        */
276        static size_t getNumElemBits( PixelFormat format );
277
278                /** Returns the size in memory of a region with the given extents and pixel
279                        format with consecutive memory layout.
280                        @param width
281                                The width of the area
282                        @param height
283                                The height of the area
284                        @param depth
285                                The depth of the area
286                        @param format
287                                The format of the area
288                        @returns
289                                The size in bytes
290                        @remarks
291                                In case that the format is non-compressed, this simply returns
292                                width*height*depth*PixelUtil::getNumElemBytes(format). In the compressed
293                                case, this does serious magic.
294                */
295                static size_t getMemorySize(size_t width, size_t height, size_t depth, PixelFormat format);
296               
297        /** Returns the property flags for this pixel format
298          @returns
299               A bitfield combination of PFF_HASALPHA, PFF_ISCOMPRESSED,
300               PFF_FLOAT, PFF_DEPTH, PFF_NATIVEENDIAN, PFF_LUMINANCE
301          @remarks
302               This replaces the seperate functions for formatHasAlpha, formatIsFloat, ...
303        */
304        static unsigned int getFlags( PixelFormat format );
305
306        /** Shortcut method to determine if the format has an alpha component */
307        static bool hasAlpha(PixelFormat format);
308        /** Shortcut method to determine if the format is floating point */
309        static bool isFloatingPoint(PixelFormat format);
310        /** Shortcut method to determine if the format is compressed */
311        static bool isCompressed(PixelFormat format);
312        /** Shortcut method to determine if the format is a depth format. */
313        static bool isDepth(PixelFormat format);
314        /** Shortcut method to determine if the format is in native endian format. */
315        static bool isNativeEndian(PixelFormat format);
316        /** Shortcut method to determine if the format is a luminance format. */
317        static bool isLuminance(PixelFormat format);
318               
319                /** Return wether a certain image extent is valid for this image format.
320                        @param width
321                                The width of the area
322                        @param height
323                                The height of the area
324                        @param depth
325                                The depth of the area
326                        @param format
327                                The format of the area
328                        @remarks For non-compressed formats, this is always true. For DXT formats,
329                        only sizes with a width and height multiple of 4 and depth 1 are allowed.
330                */
331                static bool isValidExtent(size_t width, size_t height, size_t depth, PixelFormat format);
332
333        /** Gives the number of bits (RGBA) for a format. See remarks.         
334          @remarks      For non-colour formats (dxt, depth) this returns [0,0,0,0].
335        */
336        static void getBitDepths(PixelFormat format, int rgba[4]);
337
338                /** Gives the masks for the R, G, B and A component
339                  @note                 Only valid for native endian formats
340        */
341        static void getBitMasks(PixelFormat format, uint32 rgba[4]);
342
343        /** Gets the name of an image format
344        */
345        static String getFormatName(PixelFormat srcformat);
346
347        /** Returns wether the format can be packed or unpacked with the packColour()
348        and unpackColour() functions. This is generally not true for compressed and
349        depth formats as they are special. It can only be true for formats with a
350        fixed element size.
351          @returns
352               true if yes, otherwise false
353        */
354        static bool isAccessible(PixelFormat srcformat);
355       
356        /** Returns the component type for a certain pixel format. Returns PCT_BYTE
357            in case there is no clear component type like with compressed formats.
358            This is one of PCT_BYTE, PCT_SHORT, PCT_FLOAT16, PCT_FLOAT32.
359        */
360        static PixelComponentType getComponentType(PixelFormat fmt);
361       
362        /** Returns the component count for a certain pixel format. Returns 3(no alpha) or
363            4 (has alpha) in case there is no clear component type like with compressed formats.
364         */
365        static size_t getComponentCount(PixelFormat fmt);
366       
367        /** Pack a colour value to memory
368                @param colour   The colour
369                @param pf               Pixelformat in which to write the colour
370                @param dest             Destination memory location
371        */
372        static void packColour(const ColourValue &colour, const PixelFormat pf,  const void* dest);
373        /** Pack a colour value to memory
374                @param r,g,b,a  The four colour components, range 0x00 to 0xFF
375                @param pf               Pixelformat in which to write the colour
376                @param dest             Destination memory location
377        */
378        static void packColour(const uint8 r, const uint8 g, const uint8 b, const uint8 a, const PixelFormat pf,  const void* dest);
379         /** Pack a colour value to memory
380                @param r,g,b,a  The four colour components, range 0.0f to 1.0f
381                                                (an exception to this case exists for floating point pixel
382                                                formats, which don't clamp to 0.0f..1.0f)
383                @param pf               Pixelformat in which to write the colour
384                @param dest             Destination memory location
385        */
386        static void packColour(const float r, const float g, const float b, const float a, const PixelFormat pf,  const void* dest);
387
388        /** Unpack a colour value from memory
389                @param colour   The colour is returned here
390                @param pf               Pixelformat in which to read the colour
391                @param src              Source memory location
392        */
393        static void unpackColour(ColourValue *colour, PixelFormat pf,  const void* src);
394        /** Unpack a colour value from memory
395                @param r,g,b,a  The colour is returned here (as byte)
396                @param pf               Pixelformat in which to read the colour
397                @param src              Source memory location
398                @remarks        This function returns the colour components in 8 bit precision,
399                        this will lose precision when coming from PF_A2R10G10B10 or floating
400                        point formats. 
401        */
402        static void unpackColour(uint8 *r, uint8 *g, uint8 *b, uint8 *a, PixelFormat pf,  const void* src);
403        /** Unpack a colour value from memory
404                @param r,g,b,a  The colour is returned here (as float)
405                @param pf               Pixelformat in which to read the colour
406                @param src              Source memory location
407        */
408        static void unpackColour(float *r, float *g, float *b, float *a, PixelFormat pf,  const void* src);
409       
410        /** Convert consecutive pixels from one format to another. No dithering or filtering is being done.
411                Converting from RGB to luminance takes the R channel.  In case the source and destination format match,
412                just a copy is done.
413                @param  src                     Pointer to source region
414                @param  srcFormat       Pixel format of source region
415                @param   dst                    Pointer to destination region
416                @param  dstFormat       Pixel format of destination region
417         */
418        static void bulkPixelConversion(void *src, PixelFormat srcFormat, void *dest, PixelFormat dstFormat, unsigned int count);
419
420        /** Convert pixels from one format to another. No dithering or filtering is being done. Converting
421                from RGB to luminance takes the R channel.
422                        @param  src                     PixelBox containing the source pixels, pitches and format
423                        @param  dst                     PixelBox containing the destination pixels, pitches and format
424                        @remarks The source and destination boxes must have the same
425                dimensions. In case the source and destination format match, a plain copy is done.
426        */
427        static void bulkPixelConversion(const PixelBox &src, const PixelBox &dst);
428    };
429
430}
431
432#endif
Note: See TracBrowser for help on using the repository browser.