Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

source: downloads/OgreMain/include/OgreTextureManager.h @ 5

Last change on this file since 5 was 5, checked in by anonymous, 17 years ago

=hoffentlich gehts jetzt

File size: 19.7 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 _TextureManager_H__
30#define _TextureManager_H__
31
32
33#include "OgrePrerequisites.h"
34
35#include "OgreResourceManager.h"
36#include "OgreTexture.h"
37#include "OgreSingleton.h"
38
39
40namespace Ogre {
41
42    /** Class for loading & managing textures.
43        @remarks
44            Note that this class is abstract - the particular
45            RenderSystem that is in use at the time will create
46            a concrete subclass of this. Note that the concrete
47            class will be available via the abstract singleton
48            obtained from TextureManager::getSingleton(), but
49            you should not assume that it is available until you
50            have a) initialised Ogre (after selecting a RenderSystem
51            and calling initialise from the Root object), and b)
52            created at least one window - this may be done at the
53            same time as part a if you allow Ogre to autocreate one.
54     */
55    class _OgreExport TextureManager : public ResourceManager, public Singleton<TextureManager>
56    {
57    public:
58
59        TextureManager(void);
60        virtual ~TextureManager();
61
62        /** Loads a texture from a file.
63            @param
64                name The file to load, or a String identifier in some cases
65            @param
66                group The name of the resource group to assign the texture to
67            @param
68                texType The type of texture to load/create, defaults to normal 2D textures
69            @param
70                numMipmaps The number of pre-filtered mipmaps to generate. If left to MIP_DEFAULT then
71                the TextureManager's default number of mipmaps will be used (see setDefaultNumMipmaps())
72                                If set to MIP_UNLIMITED mipmaps will be generated until the lowest possible
73                                level, 1x1x1.
74            @param
75                gamma The gamma adjustment factor to apply to this texture (brightening/darkening)
76                        @param
77                                isAlpha Only applicable to greyscale images. If true, specifies that
78                                the image should be loaded into an alpha texture rather than a
79                                single channel colour texture - useful for fixed-function systems.
80                        @param
81                                desiredFormat The format you would like to have used instead of
82                                the format being based on the contents of the texture
83        */
84        virtual TexturePtr load( 
85            const String& name, const String& group, 
86            TextureType texType = TEX_TYPE_2D, int numMipmaps = MIP_DEFAULT, 
87            Real gamma = 1.0f, bool isAlpha = false,
88            PixelFormat desiredFormat = PF_UNKNOWN);
89
90        /** Loads a texture from an Image object.
91            @note
92                The texture will create as manual texture without loader.
93            @param
94                name The name to give the resulting texture
95            @param
96                group The name of the resource group to assign the texture to
97            @param
98                img The Image object which contains the data to load
99            @param
100                texType The type of texture to load/create, defaults to normal 2D textures
101            @param
102                numMipmaps The number of pre-filtered mipmaps to generate. If left to MIP_DEFAULT then
103                the TextureManager's default number of mipmaps will be used (see setDefaultNumMipmaps())
104                                If set to MIP_UNLIMITED mipmaps will be generated until the lowest possible
105                                level, 1x1x1.
106            @param
107                gamma The gamma adjustment factor to apply to this texture (brightening/darkening)
108                        @param
109                                isAlpha Only applicable to greyscale images. If true, specifies that
110                                the image should be loaded into an alpha texture rather than a
111                                single channel colour texture - useful for fixed-function systems.
112                        @param
113                                desiredFormat The format you would like to have used instead of
114                                the format being based on the contents of the texture
115        */
116        virtual TexturePtr loadImage( 
117            const String &name, const String& group, const Image &img, 
118            TextureType texType = TEX_TYPE_2D,
119            int iNumMipmaps = MIP_DEFAULT, Real gamma = 1.0f, bool isAlpha = false,
120            PixelFormat desiredFormat = PF_UNKNOWN);
121                       
122        /** Loads a texture from a raw data stream.
123            @note
124                The texture will create as manual texture without loader.
125            @param
126                name The name to give the resulting texture
127            @param
128                group The name of the resource group to assign the texture to
129            @param
130                stream Incoming data stream
131            @param
132                width, height The dimensions of the texture
133            @param
134                format The format of the data being passed in; the manager reserves
135                the right to create a different format for the texture if the
136                original format is not available in this context.
137            @param
138                texType The type of texture to load/create, defaults to normal 2D textures
139            @param
140                numMipmaps The number of pre-filtered mipmaps to generate. If left to MIP_DEFAULT then
141                the TextureManager's default number of mipmaps will be used (see setDefaultNumMipmaps())
142                                If set to MIP_UNLIMITED mipmaps will be generated until the lowest possible
143                                level, 1x1x1.
144            @param
145                gamma The gamma adjustment factor to apply to this texture (brightening/darkening)
146        */
147        virtual TexturePtr loadRawData(const String &name, const String& group,
148            DataStreamPtr& stream, ushort uWidth, ushort uHeight, 
149            PixelFormat format, TextureType texType = TEX_TYPE_2D, 
150            int iNumMipmaps = MIP_DEFAULT, Real gamma = 1.0f);
151
152                /** Create a manual texture with specified width, height and depth (not loaded from a file).
153            @param
154                name The name to give the resulting texture
155            @param
156                group The name of the resource group to assign the texture to
157            @param
158                texType The type of texture to load/create, defaults to normal 2D textures
159            @param
160                width, height, depth The dimensions of the texture
161            @param
162                numMipmaps The number of pre-filtered mipmaps to generate. If left to MIP_DEFAULT then
163                the TextureManager's default number of mipmaps will be used (see setDefaultNumMipmaps())
164                                If set to MIP_UNLIMITED mipmaps will be generated until the lowest possible
165                                level, 1x1x1.
166            @param
167                format The internal format you wish to request; the manager reserves
168                the right to create a different format if the one you select is
169                not available in this context.
170                        @param
171                                usage The kind of usage this texture is intended for. It
172                                is a combination of TU_STATIC, TU_DYNAMIC, TU_WRITE_ONLY,
173                                TU_AUTOMIPMAP and TU_RENDERTARGET (see TextureUsage enum). You are
174                strongly advised to use HBU_STATIC_WRITE_ONLY wherever possible, if you need to
175                update regularly, consider HBU_DYNAMIC_WRITE_ONLY.
176            @param
177                loader If you intend the contents of the manual texture to be
178                regularly updated, to the extent that you don't need to recover
179                the contents if the texture content is lost somehow, you can leave
180                this parameter as 0. However, if you intend to populate the
181                texture only once, then you should implement ManualResourceLoader
182                and pass a pointer to it in this parameter; this means that if the
183                manual texture ever needs to be reloaded, the ManualResourceLoader
184                will be called to do it.
185        */
186        virtual TexturePtr createManual(const String & name, const String& group,
187            TextureType texType, uint width, uint height, uint depth, 
188                        int num_mips, PixelFormat format, int usage = TU_DEFAULT, ManualResourceLoader* loader = 0 );
189                       
190        /** Create a manual texture with a depth of 1 (not loaded from a file).
191            @param
192                name The name to give the resulting texture
193            @param
194                group The name of the resource group to assign the texture to
195            @param
196                texType The type of texture to load/create, defaults to normal 2D textures
197            @param
198                width, height The dimensions of the texture
199            @param
200                numMipmaps The number of pre-filtered mipmaps to generate. If left to MIP_DEFAULT then
201                the TextureManager's default number of mipmaps will be used (see setDefaultNumMipmaps()).
202                                If set to MIP_UNLIMITED mipmaps will be generated until the lowest possible
203                                level, 1x1x1.
204            @param
205                format The internal format you wish to request; the manager reserves
206                the right to create a different format if the one you select is
207                not available in this context.
208                        @param
209                                usage The kind of usage this texture is intended for. It
210                                is a combination of TU_STATIC, TU_DYNAMIC, TU_WRITE_ONLY,
211                                TU_AUTOMIPMAP and TU_RENDERTARGET (see TextureUsage enum). You are
212                strongly advised to use HBU_STATIC_WRITE_ONLY wherever possible, if you need to
213                update regularly, consider HBU_DYNAMIC_WRITE_ONLY.
214            @param
215                loader If you intend the contents of the manual texture to be
216                regularly updated, to the extent that you don't need to recover
217                the contents if the texture content is lost somehow, you can leave
218                this parameter as 0. However, if you intend to populate the
219                texture only once, then you should implement ManualResourceLoader
220                and pass a pointer to it in this parameter; this means that if the
221                manual texture ever needs to be reloaded, the ManualResourceLoader
222                will be called to do it.
223        */
224        TexturePtr createManual(const String & name, const String& group,
225            TextureType texType, uint width, uint height, int num_mips,
226            PixelFormat format, int usage = TU_DEFAULT, ManualResourceLoader* loader = 0 )
227                {
228                        return createManual(name, group, texType, width, height, 1, 
229                                num_mips, format, usage, loader);
230                }
231
232        /** Sets preferred bit depth for integer pixel format textures.
233        @param
234            bits Number of bits. Available values: 0, 16 and 32, where 0 (the default) means keep
235            original format as it is. This value is number of bits for the pixel.
236        @param
237            reloadTextures If true (the default), will reloading all reloadable textures.
238        */
239        virtual void setPreferredIntegerBitDepth(ushort bits, bool reloadTextures = true);
240
241        /** gets preferred bit depth for integer pixel format textures.
242        */
243        virtual ushort getPreferredIntegerBitDepth(void) const;
244
245        /** Sets preferred bit depth for float pixel format textures.
246        @param
247            bits Number of bits. Available values: 0, 16 and 32, where 0 (the default) means keep
248            original format as it is. This value is number of bits for a channel of the pixel.
249        @param
250            reloadTextures If true (the default), will reloading all reloadable textures.
251        */
252        virtual void setPreferredFloatBitDepth(ushort bits, bool reloadTextures = true);
253
254        /** gets preferred bit depth for float pixel format textures.
255        */
256        virtual ushort getPreferredFloatBitDepth(void) const;
257
258        /** Sets preferred bit depth for integer and float pixel format.
259        @param
260            integerBits Number of bits. Available values: 0, 16 and 32, where 0 (the default) means keep
261            original format as it is. This value is number of bits for the pixel.
262        @param
263            floatBits Number of bits. Available values: 0, 16 and 32, where 0 (the default) means keep
264            original format as it is. This value is number of bits for a channel of the pixel.
265        @param
266            reloadTextures If true (the default), will reloading all reloadable textures.
267        */
268        virtual void setPreferredBitDepths(ushort integerBits, ushort floatBits, bool reloadTextures = true);
269
270                /** Returns whether this render system can natively support the precise texture
271                        format requested with the given usage options.
272                @remarks
273                        You can still create textures with this format even if this method returns
274                        false; the texture format will just be altered to one which the device does
275                        support.
276                @note
277                        Sometimes the device may just slightly change the format, such as reordering the
278                        channels or packing the channels differently, without it making and qualitative
279                        differences to the texture. If you want to just detect whether the quality of a
280                        given texture will be reduced, use isEquivalentFormatSupport instead.
281                @param format The pixel format requested
282                @param usage The kind of usage this texture is intended for, a combination of
283                        the TextureUsage flags.
284                @returns true if the format is natively supported, false if a fallback would be used.
285                */
286                virtual bool isFormatSupported(TextureType ttype, PixelFormat format, int usage);
287
288                /** Returns whether this render system can support the texture format requested
289                        with the given usage options, or another format with no quality reduction.
290                */
291                virtual bool isEquivalentFormatSupported(TextureType ttype, PixelFormat format, int usage);
292
293                /** Gets the format which will be natively used for a requested format given the
294                        contraints of the current device.
295                */
296                virtual PixelFormat getNativeFormat(TextureType ttype, PixelFormat format, int usage) = 0;
297
298        /** Returns whether this render system has hardware filtering supported for the
299            texture format requested with the given usage options.
300        @remarks
301            Not all texture format are supports filtering by the hardware, i.e. some
302            cards support floating point format, but it doesn't supports filtering on
303            the floating point texture at all, or only a subset floating point formats
304            have flitering supported.
305        @par
306            In the case you want to write shader to work with floating point texture, and
307            you want to produce better visual quality, it's necessary to flitering the
308            texture manually in shader (potential requires four or more texture fetch
309            instructions, plus several arithmetic instructions) if filtering doesn't
310            supported by hardware. But in case on the hardware that supports floating
311            point filtering natively, it had better to adopt this capability for
312            performance (because only one texture fetch instruction are required) and
313            doesn't loss visual quality.
314        @par
315            This method allow you queries hardware texture filtering capability to deciding
316            which verion of the shader to be used. Note it's up to you to write multi-version
317            shaders for support various hardware, internal engine can't do that for you
318            automatically.
319        @note
320            Under GL, texture filtering are always supported by driver, but if it's not
321            supported by hardware natively, software simulation will be used, and you
322            will end up with very slow speed (less than 0.1 fps for example). To slove
323            this performance problem, you must disable filtering manually (by use
324            <b>filtering none</b> in the material script's texture_unit section, or
325            call TextureUnitState::setTextureFiltering with TFO_NONE if populate
326            material in code).
327                @param ttype The texture type requested
328                @param format The pixel format requested
329                @param usage The kind of usage this texture is intended for, a combination of
330                        the TextureUsage flags.
331        @param preciseFormatOnly Whether precise or fallback format mode is used to detecting.
332            In case the pixel format doesn't supported by device, false will be returned
333            if in precise mode, and natively used pixel format will be actually use to
334            check if in fallback mode.
335                @returns true if the texture filtering is supported.
336        */
337        virtual bool isHardwareFilteringSupported(TextureType ttype, PixelFormat format, int usage,
338            bool preciseFormatOnly = false) = 0;
339
340        /** Sets the default number of mipmaps to be used for loaded textures, for when textures are
341            loaded automatically (e.g. by Material class) or when 'load' is called with the default
342            parameters by the application.
343                        If set to MIP_UNLIMITED mipmaps will be generated until the lowest possible
344                                level, 1x1x1.
345            @note
346                The default value is 0.
347        */
348        virtual void setDefaultNumMipmaps(size_t num);
349
350        /** Gets the default number of mipmaps to be used for loaded textures.
351        */
352        virtual size_t getDefaultNumMipmaps()
353        {
354            return mDefaultNumMipmaps;
355        }
356
357        /** Override standard Singleton retrieval.
358        @remarks
359        Why do we do this? Well, it's because the Singleton
360        implementation is in a .h file, which means it gets compiled
361        into anybody who includes it. This is needed for the
362        Singleton template to work, but we actually only want it
363        compiled into the implementation of the class based on the
364        Singleton, not all of them. If we don't change this, we get
365        link errors when trying to use the Singleton-based class from
366        an outside dll.
367        @par
368        This method just delegates to the template version anyway,
369        but the implementation stays in this single compilation unit,
370        preventing link errors.
371        */
372        static TextureManager& getSingleton(void);
373        /** Override standard Singleton retrieval.
374        @remarks
375        Why do we do this? Well, it's because the Singleton
376        implementation is in a .h file, which means it gets compiled
377        into anybody who includes it. This is needed for the
378        Singleton template to work, but we actually only want it
379        compiled into the implementation of the class based on the
380        Singleton, not all of them. If we don't change this, we get
381        link errors when trying to use the Singleton-based class from
382        an outside dll.
383        @par
384        This method just delegates to the template version anyway,
385        but the implementation stays in this single compilation unit,
386        preventing link errors.
387        */
388        static TextureManager* getSingletonPtr(void);
389
390    protected:
391
392        ushort mPreferredIntegerBitDepth;
393        ushort mPreferredFloatBitDepth;
394        size_t mDefaultNumMipmaps;
395    };
396}// Namespace
397
398#endif
Note: See TracBrowser for help on using the repository browser.