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

Revision 1809, 14.7 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 _TextureManager_H__
26#define _TextureManager_H__
27
28
29#include "OgrePrerequisites.h"
30
31#include "OgreResourceManager.h"
32#include "OgreTexture.h"
33#include "OgreSingleton.h"
34
35
36namespace Ogre {
37
38    /** Class for loading & managing textures.
39        @remarks
40            Note that this class is abstract - the particular
41            RenderSystem that is in use at the time will create
42            a concrete subclass of this. Note that the concrete
43            class will be available via the abstract singleton
44            obtained from TextureManager::getSingleton(), but
45            you should not assume that it is available until you
46            have a) initialised Ogre (after selecting a RenderSystem
47            and calling initialise from the Root object), and b)
48            created at least one window - this may be done at the
49            same time as part a if you allow Ogre to autocreate one.
50     */
51    class _OgreExport TextureManager : public ResourceManager, public Singleton<TextureManager>
52    {
53    public:
54
55        TextureManager(bool enable32Bit = true);
56        virtual ~TextureManager();
57
58        /** Loads a texture from a file.
59            @param
60                name The file to load, or a String identifier in some cases
61            @param
62                group The name of the resource group to assign the texture to
63            @param
64                texType The type of texture to load/create, defaults to normal 2D textures
65            @param
66                numMipmaps The number of pre-filtered mipmaps to generate. If left to default (-1) then
67                the TextureManager's default number of mipmaps will be used (see setDefaultNumMipmaps())
68                                If set to MIP_UNLIMITED mipmaps will be generated until the lowest possible
69                                level, 1x1x1.
70            @param
71                gamma The gamma adjustment factor to apply to this texture (brightening/darkening)
72        */
73        virtual TexturePtr load(
74            const String& name, const String& group,
75            TextureType texType = TEX_TYPE_2D, int numMipmaps = -1,
76            Real gamma = 1.0f, bool isAlpha = false);
77
78        /** Loads a texture from an Image object.
79            @note
80                The texture will create as manual texture without loader.
81            @param
82                name The name to give the resulting texture
83            @param
84                group The name of the resource group to assign the texture to
85            @param
86                img The Image object which contains the data to load
87            @param
88                texType The type of texture to load/create, defaults to normal 2D textures
89            @param
90                numMipmaps The number of pre-filtered mipmaps to generate. If left to default (-1) then
91                the TextureManager's default number of mipmaps will be used (see setDefaultNumMipmaps())
92                                If set to MIP_UNLIMITED mipmaps will be generated until the lowest possible
93                                level, 1x1x1.
94            @param
95                gamma The gamma adjustment factor to apply to this texture (brightening/darkening)
96        */
97        virtual TexturePtr loadImage(
98            const String &name, const String& group, const Image &img,
99            TextureType texType = TEX_TYPE_2D,
100            int iNumMipmaps = -1, Real gamma = 1.0f, bool isAlpha = false);
101                       
102        /** Loads a texture from a raw data stream.
103            @note
104                The texture will create as manual texture without loader.
105            @param
106                name The name to give the resulting texture
107            @param
108                group The name of the resource group to assign the texture to
109            @param
110                stream Incoming data stream
111            @param
112                width, height The dimensions of the texture
113            @param
114                format The format of the data being passed in; the manager reserves
115                the right to create a different format for the texture if the
116                original format is not available in this context.
117            @param
118                texType The type of texture to load/create, defaults to normal 2D textures
119            @param
120                numMipmaps The number of pre-filtered mipmaps to generate. If left to default (-1) then
121                the TextureManager's default number of mipmaps will be used (see setDefaultNumMipmaps())
122                                If set to MIP_UNLIMITED mipmaps will be generated until the lowest possible
123                                level, 1x1x1.
124            @param
125                gamma The gamma adjustment factor to apply to this texture (brightening/darkening)
126        */
127        virtual TexturePtr loadRawData(const String &name, const String& group,
128            DataStreamPtr& stream, ushort uWidth, ushort uHeight,
129            PixelFormat format, TextureType texType = TEX_TYPE_2D,
130            int iNumMipmaps = -1, Real gamma = 1.0f);
131
132                /** Create a manual texture with specified width, height and depth (not loaded from a file).
133            @param
134                name The name to give the resulting texture
135            @param
136                group The name of the resource group to assign the texture to
137            @param
138                texType The type of texture to load/create, defaults to normal 2D textures
139            @param
140                width, height, depth The dimensions of the texture
141            @param
142                numMipmaps The number of pre-filtered mipmaps to generate. If left to default (-1) then
143                the TextureManager's default number of mipmaps will be used (see setDefaultNumMipmaps())
144                                If set to MIP_UNLIMITED mipmaps will be generated until the lowest possible
145                                level, 1x1x1.
146            @param
147                format The internal format you wish to request; the manager reserves
148                the right to create a different format if the one you select is
149                not available in this context.
150                        @param
151                                usage The kind of usage this texture is intended for. It
152                                is a combination of TU_STATIC, TU_DYNAMIC, TU_WRITE_ONLY,
153                                TU_AUTOMIPMAP and TU_RENDERTARGET (see TextureUsage enum). You are
154                strongly advised to use HBU_STATIC_WRITE_ONLY wherever possible, if you need to
155                update regularly, consider HBU_DYNAMIC_WRITE_ONLY.
156            @param
157                loader If you intend the contents of the manual texture to be
158                regularly updated, to the extent that you don't need to recover
159                the contents if the texture content is lost somehow, you can leave
160                this parameter as 0. However, if you intend to populate the
161                texture only once, then you should implement ManualResourceLoader
162                and pass a pointer to it in this parameter; this means that if the
163                manual texture ever needs to be reloaded, the ManualResourceLoader
164                will be called to do it.
165        */
166        virtual TexturePtr createManual(const String & name, const String& group,
167            TextureType texType, uint width, uint height, uint depth,
168                        int num_mips, PixelFormat format, int usage = TU_DEFAULT, ManualResourceLoader* loader = 0 );
169                       
170        /** Create a manual texture with a depth of 1 (not loaded from a file).
171            @param
172                name The name to give the resulting texture
173            @param
174                group The name of the resource group to assign the texture to
175            @param
176                texType The type of texture to load/create, defaults to normal 2D textures
177            @param
178                width, height The dimensions of the texture
179            @param
180                numMipmaps The number of pre-filtered mipmaps to generate. If left to default (-1) then
181                the TextureManager's default number of mipmaps will be used (see setDefaultNumMipmaps()).
182                                If set to MIP_UNLIMITED mipmaps will be generated until the lowest possible
183                                level, 1x1x1.
184            @param
185                format The internal format you wish to request; the manager reserves
186                the right to create a different format if the one you select is
187                not available in this context.
188                        @param
189                                usage The kind of usage this texture is intended for. It
190                                is a combination of TU_STATIC, TU_DYNAMIC, TU_WRITE_ONLY,
191                                TU_AUTOMIPMAP and TU_RENDERTARGET (see TextureUsage enum). You are
192                strongly advised to use HBU_STATIC_WRITE_ONLY wherever possible, if you need to
193                update regularly, consider HBU_DYNAMIC_WRITE_ONLY.
194            @param
195                loader If you intend the contents of the manual texture to be
196                regularly updated, to the extent that you don't need to recover
197                the contents if the texture content is lost somehow, you can leave
198                this parameter as 0. However, if you intend to populate the
199                texture only once, then you should implement ManualResourceLoader
200                and pass a pointer to it in this parameter; this means that if the
201                manual texture ever needs to be reloaded, the ManualResourceLoader
202                will be called to do it.
203        */
204        TexturePtr createManual(const String & name, const String& group,
205            TextureType texType, uint width, uint height, int num_mips,
206            PixelFormat format, int usage = TU_DEFAULT, ManualResourceLoader* loader = 0 )
207                {
208                        return createManual(name, group, texType, width, height, 1,
209                                num_mips, format, usage, loader);
210                }
211
212        /** Enables / disables 32-bit textures.
213        */
214        virtual void enable32BitTextures(bool setting = true);
215
216        /** Checks 32-bit textures enable setting.
217        */
218        virtual bool isEnable32BitTextures(void)
219        {
220            return mIs32Bit;
221        }
222
223                /** Returns whether this render system can natively support the precise texture
224                        format requested with the given usage options.
225                @remarks
226                        You can still create textures with this format even if this method returns
227                        false; the texture format will just be altered to one which the device does
228                        support.
229                @note
230                        Sometimes the device may just slightly change the format, such as reordering the
231                        channels or packing the channels differently, without it making and qualitative
232                        differences to the texture. If you want to just detect whether the quality of a
233                        given texture will be reduced, use isEquivalentFormatSupport instead.
234                @param format The pixel format requested
235                @param usage The kind of usage this texture is intended for, a combination of
236                        the TextureUsage flags.
237                @returns true if the format is natively supported, false if a fallback would be used.
238                */
239                virtual bool isFormatSupported(TextureType ttype, PixelFormat format, int usage);
240
241                /** Returns whether this render system can support the texture format requested
242                        with the given usage options, or another format with no quality reduction.
243                */
244                virtual bool isEquivalentFormatSupported(TextureType ttype, PixelFormat format, int usage);
245
246                /** Gets the format which will be natively used for a requested format given the
247                        contraints of the current device.
248                */
249                virtual PixelFormat getNativeFormat(TextureType ttype, PixelFormat format, int usage) = 0;
250
251        /** Sets the default number of mipmaps to be used for loaded textures, for when textures are
252            loaded automatically (e.g. by Material class) or when 'load' is called with the default
253            parameters by the application.
254                        If set to MIP_UNLIMITED mipmaps will be generated until the lowest possible
255                                level, 1x1x1.
256            @note
257                The default value is 0.
258        */
259        virtual void setDefaultNumMipmaps(size_t num);
260
261        /** Gets the default number of mipmaps to be used for loaded textures.
262        */
263        virtual size_t getDefaultNumMipmaps()
264        {
265            return mDefaultNumMipmaps;
266        }
267
268        /** Override standard Singleton retrieval.
269        @remarks
270        Why do we do this? Well, it's because the Singleton
271        implementation is in a .h file, which means it gets compiled
272        into anybody who includes it. This is needed for the
273        Singleton template to work, but we actually only want it
274        compiled into the implementation of the class based on the
275        Singleton, not all of them. If we don't change this, we get
276        link errors when trying to use the Singleton-based class from
277        an outside dll.
278        @par
279        This method just delegates to the template version anyway,
280        but the implementation stays in this single compilation unit,
281        preventing link errors.
282        */
283        static TextureManager& getSingleton(void);
284        /** Override standard Singleton retrieval.
285        @remarks
286        Why do we do this? Well, it's because the Singleton
287        implementation is in a .h file, which means it gets compiled
288        into anybody who includes it. This is needed for the
289        Singleton template to work, but we actually only want it
290        compiled into the implementation of the class based on the
291        Singleton, not all of them. If we don't change this, we get
292        link errors when trying to use the Singleton-based class from
293        an outside dll.
294        @par
295        This method just delegates to the template version anyway,
296        but the implementation stays in this single compilation unit,
297        preventing link errors.
298        */
299        static TextureManager* getSingletonPtr(void);
300
301    protected:
302
303        bool mIs32Bit;
304        size_t mDefaultNumMipmaps;
305    };
306}// Namespace
307
308#endif
Note: See TracBrowser for help on using the repository browser.