Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

source: downloads/OgreMain/include/OgreImage.h @ 1

Last change on this file since 1 was 1, checked in by landauf, 17 years ago
File size: 15.9 KB
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-2006 Torus Knot Software Ltd
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
24You may alternatively use this source under the terms of a specific version of
25the OGRE Unrestricted License provided you have obtained such a license from
26Torus Knot Software Ltd.
27-----------------------------------------------------------------------------
28*/
29#ifndef _Image_H__
30#define _Image_H__
31
32#include "OgrePrerequisites.h"
33#include "OgreCommon.h"
34#include "OgrePixelFormat.h"
35#include "OgreDataStream.h"
36
37namespace Ogre {
38
39    enum ImageFlags
40    {
41        IF_COMPRESSED = 0x00000001,
42        IF_CUBEMAP    = 0x00000002,
43        IF_3D_TEXTURE = 0x00000004
44    };
45    /** Class representing an image file.
46        @remarks
47            The Image class usually holds uncompressed image data and is the
48            only object that can be loaded in a texture. Image  objects handle
49            image data decoding themselves by the means of locating the correct
50            Codec object for each data type.
51        @par
52            Typically, you would want to use an Image object to load a texture
53            when extra processing needs to be done on an image before it is
54            loaded or when you want to blit to an existing texture.
55    */
56    class _OgreExport Image
57    {
58    public:
59        typedef Ogre::Box Box;
60        typedef Ogre::Rect Rect;
61    public:
62        /** Standard constructor.
63        */
64        Image();
65        /** Copy-constructor - copies all the data from the target image.
66        */
67        Image( const Image &img );
68
69        /** Standard destructor.
70        */
71        virtual ~Image();
72
73        /** Assignment operator - copies all the data from the target image.
74        */
75        Image & operator = ( const Image & img );
76
77        /** Flips (mirrors) the image around the Y-axis.
78            @remarks
79                An example of an original and flipped image:
80                <pre>               
81                originalimg
82                00000000000
83                00000000000
84                00000000000
85                00000000000
86                00000000000
87                ------------> flip axis
88                00000000000
89                00000000000
90                00000000000
91                00000000000
92                00000000000
93                originalimg
94                </pre>
95        */
96        Image & flipAroundY();
97
98        /** Flips (mirrors) the image around the X-axis.
99            @remarks
100                An example of an original and flipped image:
101                <pre>
102                        flip axis
103                            |
104                originalimg|gmilanigiro
105                00000000000|00000000000
106                00000000000|00000000000
107                00000000000|00000000000
108                00000000000|00000000000
109                00000000000|00000000000
110                </pre>
111        */                 
112        Image & flipAroundX();
113
114        /** Stores a pointer to raw data in memory. The pixel format has to be specified.
115            @remarks
116                This method loads an image into memory held in the object. The
117                pixel format will be either greyscale or RGB with an optional
118                Alpha component.
119                The type can be determined by calling getFormat().             
120            @note
121                                Whilst typically your image is likely to be a simple 2D image,
122                                you can define complex images including cube maps, volume maps,
123                                and images including custom mip levels. The layout of the
124                                internal memory should be:
125                                <ul><li>face 0, mip 0 (top), width x height (x depth)</li>
126                                <li>face 0, mip 1, width/2 x height/2 (x depth/2)</li>
127                                <li>face 0, mip 2, width/4 x height/4 (x depth/4)</li>
128                                <li>.. remaining mips for face 0 .. </li>
129                                <li>face 1, mip 0 (top), width x height (x depth)</li
130                                <li>.. and so on. </li>
131                                </ul>
132                                Of course, you will never have multiple faces (cube map) and
133                                depth too.
134                        @param
135                The data pointer
136            @param
137                                Width of image
138            @param
139                                Height of image
140                        @param
141                Image Depth (in 3d images, numbers of layers, otherwhise 1)
142            @param
143                                Pixel Format
144            @param
145                if memory associated with this buffer is to be destroyed
146                with the Image object.
147                        @param
148                                the number of faces the image data has inside (6 for cubemaps, 1 otherwise)
149            @param
150                the number of mipmaps the image data has inside
151            @note
152                 The memory associated with this buffer is NOT destroyed with the
153                 Image object, unless autoDelete is set to true.
154                        @remarks
155                                The size of the buffer must be numFaces*PixelUtil::getMemorySize(width, height, depth, format)
156         */
157                Image& loadDynamicImage( uchar* pData, size_t uWidth, size_t uHeight, 
158                                                        size_t depth,
159                                                         PixelFormat eFormat, bool autoDelete = false, 
160                                                         size_t numFaces = 1, size_t numMipMaps = 0);
161               
162                /** Stores a pointer to raw data in memory. The pixel format has to be specified.
163            @remarks
164                This method loads an image into memory held in the object. The
165                pixel format will be either greyscale or RGB with an optional
166                Alpha component.
167                The type can be determined by calling getFormat().             
168            @note
169                                Whilst typically your image is likely to be a simple 2D image,
170                                you can define complex images including cube maps
171                                and images including custom mip levels. The layout of the
172                                internal memory should be:
173                                <ul><li>face 0, mip 0 (top), width x height</li>
174                                <li>face 0, mip 1, width/2 x height/2 </li>
175                                <li>face 0, mip 2, width/4 x height/4 </li>
176                                <li>.. remaining mips for face 0 .. </li>
177                                <li>face 1, mip 0 (top), width x height (x depth)</li
178                                <li>.. and so on. </li>
179                                </ul>
180                                Of course, you will never have multiple faces (cube map) and
181                                depth too.
182            @param
183                The data pointer
184            @param
185                                Width of image
186            @param
187                                Height of image
188            @param
189                                Pixel Format
190            @note
191                 The memory associated with this buffer is NOT destroyed with the
192                 Image object.
193                        @remarks This function is deprecated; one should really use the
194                                Image::loadDynamicImage(pData, width, height, depth, format, ...) to be compatible
195                                with future Ogre versions.
196         */
197                Image& loadDynamicImage( uchar* pData, size_t uWidth,
198                                                                 size_t uHeight, PixelFormat eFormat)
199                {
200                        return loadDynamicImage(pData, uWidth, uHeight, 1, eFormat);
201                }
202                /** Loads raw data from a stream. See the function
203                        loadDynamicImage for a description of the parameters.
204                        @remarks
205                                The size of the buffer must be numFaces*PixelUtil::getMemorySize(width, height, depth, format)
206            @note
207                                Whilst typically your image is likely to be a simple 2D image,
208                                you can define complex images including cube maps
209                                and images including custom mip levels. The layout of the
210                                internal memory should be:
211                                <ul><li>face 0, mip 0 (top), width x height (x depth)</li>
212                                <li>face 0, mip 1, width/2 x height/2 (x depth/2)</li>
213                                <li>face 0, mip 2, width/4 x height/4 (x depth/4)</li>
214                                <li>.. remaining mips for face 0 .. </li>
215                                <li>face 1, mip 0 (top), width x height (x depth)</li
216                                <li>.. and so on. </li>
217                                </ul>
218                                Of course, you will never have multiple faces (cube map) and
219                                depth too.
220        */
221        Image & loadRawData( 
222            DataStreamPtr& stream, 
223            size_t uWidth, size_t uHeight, size_t uDepth,
224            PixelFormat eFormat,
225                        size_t numFaces = 1, size_t numMipMaps = 0);
226        /** Loads raw data from a stream. The pixel format has to be specified.
227                        @remarks This function is deprecated; one should really use the
228                                Image::loadRawData(stream, width, height, depth, format, ...) to be compatible
229                                with future Ogre versions.
230            @note
231                                Whilst typically your image is likely to be a simple 2D image,
232                                you can define complex images including cube maps
233                                and images including custom mip levels. The layout of the
234                                internal memory should be:
235                                <ul><li>face 0, mip 0 (top), width x height</li>
236                                <li>face 0, mip 1, width/2 x height/2 </li>
237                                <li>face 0, mip 2, width/4 x height/4 </li>
238                                <li>.. remaining mips for face 0 .. </li>
239                                <li>face 1, mip 0 (top), width x height (x depth)</li
240                                <li>.. and so on. </li>
241                                </ul>
242                                Of course, you will never have multiple faces (cube map) and
243                                depth too.
244        */
245        Image & loadRawData( 
246            DataStreamPtr& stream, 
247            size_t uWidth, size_t uHeight, 
248            PixelFormat eFormat )
249                {
250                        return loadRawData(stream, uWidth, uHeight, 1, eFormat);
251                }
252
253        /** Loads an image file.
254            @remarks
255                This method loads an image into memory. Any format for which
256                                and associated ImageCodec is registered can be loaded.
257                                This can include complex formats like DDS with embedded custom
258                                mipmaps, cube faces and volume textures.
259                The type can be determined by calling getFormat().             
260            @param
261                strFileName Name of a file file to load.
262            @param
263                groupName Name of the resource group to search for the image
264            @note
265                The memory associated with this buffer is destroyed with the
266                Image object.
267        */
268        Image & load( const String& strFileName, const String& groupName );
269
270        /** Loads an image file from a stream.
271            @remarks
272                This method works in the same way as the filename-based load
273                method except it loads the image from a DataStream object.
274                                This DataStream is expected to contain the
275                encoded data as it would be held in a file.
276                Any format for which and associated ImageCodec is registered
277                                can be loaded.
278                                This can include complex formats like DDS with embedded custom
279                                mipmaps, cube faces and volume textures.
280                The type can be determined by calling getFormat().             
281            @param
282                stream The source data.
283            @param
284                type The type of the image. Used to decide what decompression
285                codec to use.
286            @see
287                Image::load( const String& strFileName )
288        */
289        Image & load(DataStreamPtr& stream, const String& type );
290       
291        /** Save the image as a file. */
292        void save(const String& filename);
293
294        /** Returns a pointer to the internal image buffer.
295                @remarks
296                        Be careful with this method. You will almost certainly
297                        prefer to use getPixelBox, especially with complex images
298                        which include many faces or custom mipmaps.
299        */
300        uchar* getData(void);
301
302        /** Returns a const pointer to the internal image buffer.
303                @remarks
304                        Be careful with this method. You will almost certainly
305                        prefer to use getPixelBox, especially with complex images
306                        which include many faces or custom mipmaps.
307        */
308        const uchar * getData() const;       
309
310        /** Returns the size of the data buffer.
311        */
312        size_t getSize() const;
313
314        /** Returns the number of mipmaps contained in the image.
315        */
316        size_t getNumMipmaps() const;
317
318        /** Returns true if the image has the appropriate flag set.
319        */
320        bool hasFlag(const ImageFlags imgFlag) const;
321
322        /** Gets the width of the image in pixels.
323        */
324        size_t getWidth(void) const;
325
326        /** Gets the height of the image in pixels.
327        */
328        size_t getHeight(void) const;
329
330        /** Gets the depth of the image.
331        */
332        size_t getDepth(void) const;
333               
334                /** Get the numer of faces of the image. This is usually 6 for a cubemap, and
335                    1 for a normal image.
336                */
337                size_t getNumFaces(void) const;
338
339        /** Gets the physical width in bytes of each row of pixels.
340        */
341        size_t getRowSpan(void) const;
342
343        /** Returns the image format.
344        */
345        PixelFormat getFormat() const;
346
347        /** Returns the number of bits per pixel.
348        */
349        uchar getBPP() const;
350
351        /** Returns true if the image has an alpha component.
352        */
353        bool getHasAlpha() const;
354               
355                /** Does gamma adjustment.
356            @note
357                Basic algo taken from Titan Engine, copyright (c) 2000 Ignacio
358                Castano Iguado
359        */
360        static void applyGamma( uchar *buffer, Real gamma, size_t size, uchar bpp );
361
362        /**
363         * Get colour value from a certain location in the image. The z coordinate
364         * is only valid for cubemaps and volume textures. This uses the first (largest)
365         * mipmap.
366         */
367        ColourValue getColourAt(int x, int y, int z);
368       
369        /**
370         * Get a PixelBox encapsulating the image data of a mipmap
371         */
372        PixelBox getPixelBox(size_t face = 0, size_t mipmap = 0) const;
373
374                enum Filter
375                {
376                        FILTER_NEAREST,
377                        FILTER_LINEAR,
378                        FILTER_BILINEAR,
379                        FILTER_BOX,
380                        FILTER_TRIANGLE,
381                        FILTER_BICUBIC
382                };
383                /** Scale a 1D, 2D or 3D image volume.
384                        @param  src                     PixelBox containing the source pointer, dimensions and format
385                        @param  dst                     PixelBox containing the destination pointer, dimensions and format
386                        @param  filter          Which filter to use
387                        @remarks        This function can do pixel format conversion in the process.
388                        @note   dst and src can point to the same PixelBox object without any problem
389                */
390                static void scale(const PixelBox &src, const PixelBox &dst, Filter filter = FILTER_BILINEAR);
391               
392                /** Resize a 2D image, applying the appropriate filter. */
393                void resize(ushort width, ushort height, Filter filter = FILTER_BILINEAR);
394               
395        // Static function to calculate size in bytes from the number of mipmaps, faces and the dimensions
396        static size_t calculateSize(size_t mipmaps, size_t faces, size_t width, size_t height, size_t depth, PixelFormat format);
397    private:
398        // The width of the image in pixels
399        size_t m_uWidth;
400        // The height of the image in pixels
401        size_t m_uHeight;
402        // The depth of the image
403        size_t m_uDepth;
404        // The size of the image buffer
405        size_t m_uSize;
406        // The number of mipmaps the image contains
407        size_t m_uNumMipmaps;
408        // Image specific flags.
409        int m_uFlags;
410
411        // The pixel format of the image
412        PixelFormat m_eFormat;
413
414        // The number of bytes per pixel
415        uchar m_ucPixelSize;
416        uchar* m_pBuffer;
417
418                // A bool to determine if we delete the buffer or the calling app does
419                bool m_bAutoDelete;
420    };
421
422        typedef std::vector<Image*> ImagePtrList;
423        typedef std::vector<const Image*> ConstImagePtrList;
424
425
426} // namespace
427
428#endif
Note: See TracBrowser for help on using the repository browser.