source: OGRE/trunk/ogrenew/OgreMain/include/OgreImage.h @ 692

Revision 692, 12.5 KB checked in by mattausch, 19 years ago (diff)

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