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

Revision 1809, 13.3 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 _Texture_H__
26#define _Texture_H__
27
28#include "OgrePrerequisites.h"
29#include "OgreHardwareBuffer.h"
30#include "OgreResource.h"
31#include "OgreImage.h"
32
33namespace Ogre {
34
35    /** Enum identifying the texture usage
36    */
37    enum TextureUsage
38    {
39                /// @copydoc HardwareBuffer::Usage
40                TU_STATIC = HardwareBuffer::HBU_STATIC,
41                TU_DYNAMIC = HardwareBuffer::HBU_DYNAMIC,
42                TU_WRITE_ONLY = HardwareBuffer::HBU_WRITE_ONLY,
43                TU_STATIC_WRITE_ONLY = HardwareBuffer::HBU_STATIC_WRITE_ONLY,
44                TU_DYNAMIC_WRITE_ONLY = HardwareBuffer::HBU_DYNAMIC_WRITE_ONLY,
45                TU_DYNAMIC_WRITE_ONLY_DISCARDABLE = HardwareBuffer::HBU_DYNAMIC_WRITE_ONLY_DISCARDABLE,
46                /// mipmaps will be automatically generated for this texture
47                TU_AUTOMIPMAP = 0x100,
48                /// this texture will be a render target, ie. used as a target for render to texture
49                /// setting this flag will ignore all other texture usages except TU_AUTOMIPMAP
50                TU_RENDERTARGET = 0x200,
51                /// default to automatic mipmap generation static textures
52                TU_DEFAULT = TU_AUTOMIPMAP | TU_STATIC_WRITE_ONLY
53       
54    };
55
56    /** Enum identifying the texture type
57    */
58    enum TextureType
59    {
60        /// 1D texture, used in combination with 1D texture coordinates
61        TEX_TYPE_1D = 1,
62        /// 2D texture, used in combination with 2D texture coordinates (default)
63        TEX_TYPE_2D = 2,
64        /// 3D volume texture, used in combination with 3D texture coordinates
65        TEX_TYPE_3D = 3,
66        /// 3D cube map, used in combination with 3D texture coordinates
67        TEX_TYPE_CUBE_MAP = 4
68    };
69
70        /** Enum identifying special mipmap numbers
71    */
72        enum TextureMipmap
73        {
74                /// Generate mipmaps up to 1x1
75                MIP_UNLIMITED = 0x7FFFFFFF
76        };
77
78    // Forward declaration
79    class TexturePtr;
80
81    /** Abstract class representing a Texture resource.
82        @remarks
83            The actual concrete subclass which will exist for a texture
84            is dependent on the rendering system in use (Direct3D, OpenGL etc).
85            This class represents the commonalities, and is the one 'used'
86            by programmers even though the real implementation could be
87            different in reality. Texture objects are created through
88            the 'create' method of the TextureManager concrete subclass.
89     */
90    class _OgreExport Texture : public Resource
91    {
92    public:
93        Texture(ResourceManager* creator, const String& name, ResourceHandle handle,
94            const String& group, bool isManual = false, ManualResourceLoader* loader = 0);
95
96        /** Sets the type of texture; can only be changed before load()
97        */
98        virtual void setTextureType(TextureType ttype ) { mTextureType = ttype; }
99
100        /** Gets the type of texture
101        */
102        virtual TextureType getTextureType(void) const { return mTextureType; }
103
104        /** Gets the number of mipmaps to be used for this texture.
105        */
106        virtual size_t getNumMipmaps(void) const {return mNumMipmaps;}
107
108                /** Sets the number of mipmaps to be used for this texture.
109            @note
110                Must be set before calling any 'load' method.
111        */
112        virtual void setNumMipmaps(size_t num) {mNumRequestedMipmaps = mNumMipmaps = num;}
113
114                /** Are mipmaps hardware generated?
115                @remarks
116                        Will only be accurate after texture load, or createInternalResources
117                */
118                virtual bool getMipmapsHardwareGenerated(void) const { return mMipmapsHardwareGenerated; }
119
120        /** Returns the gamma adjustment factor applied to this texture.
121        */
122        virtual float getGamma(void) const { return mGamma; }
123
124        /** Sets the gamma adjustment factor applied to this texture.
125            @note
126                Must be called before any 'load' method.
127        */
128        virtual void setGamma(float g) { mGamma = g; }
129
130        /** Returns the height of the texture.
131        */
132        virtual unsigned int getHeight(void) const { return mHeight; }
133
134        /** Returns the width of the texture.
135        */
136        virtual unsigned int getWidth(void) const { return mWidth; }
137
138        /** Returns the depth of the texture (only applicable for 3D textures).
139        */
140        virtual unsigned int getDepth(void) const { return mDepth; }
141
142        /** Returns the height of the original input texture (may differ due to hardware requirements).
143        */
144        virtual unsigned int getSrcHeight(void) const { return mSrcHeight; }
145
146        /** Returns the width of the original input texture (may differ due to hardware requirements).
147        */
148        virtual unsigned int getSrcWidth(void) const { return mSrcWidth; }
149
150        /** Returns the original depth of the input texture (only applicable for 3D textures).
151        */
152        virtual unsigned int getSrcDepth(void) const { return mSrcDepth; }
153
154        /** Set the height of the texture; can only do this before load();
155        */
156        virtual void setHeight(unsigned int h) { mHeight = mSrcHeight = h; }
157
158        /** Set the width of the texture; can only do this before load();
159        */
160        virtual void setWidth(unsigned int w) { mWidth = mSrcWidth = w; }
161
162        /** Set the depth of the texture (only applicable for 3D textures);
163            ; can only do this before load();
164        */
165        virtual void setDepth(unsigned int d)  { mDepth = mSrcDepth = d; }
166
167        /** Returns the TextureUsage indentifier for this Texture
168        */
169        virtual int getUsage() const
170        {
171            return mUsage;
172        }
173
174        /** Sets the TextureUsage indentifier for this Texture; only useful before load()
175                       
176                        @param u is a combination of TU_STATIC, TU_DYNAMIC, TU_WRITE_ONLY
177                                TU_AUTOMIPMAP and TU_RENDERTARGET (see TextureUsage enum). You are
178                strongly advised to use HBU_STATIC_WRITE_ONLY wherever possible, if you need to
179                update regularly, consider HBU_DYNAMIC_WRITE_ONLY.
180        */
181        virtual void setUsage(int u) { mUsage = u; }
182
183        /** Creates the internal texture resources for this texture.
184        @remarks
185            This method creates the internal texture resources (pixel buffers,
186            texture surfaces etc) required to begin using this texture. You do
187            not need to call this method directly unless you are manually creating
188            a texture, in which case something must call it, after having set the
189            size and format of the texture (e.g. the ManualResourceLoader might
190            be the best one to call it). If you are not defining a manual texture,
191            or if you use one of the self-contained load...() methods, then it will be
192            called for you.
193        */
194        virtual void createInternalResources(void);
195
196        /** Frees internal texture resources for this texture.
197        */
198        virtual void freeInternalResources(void);
199       
200                /** Copies (and maybe scales to fit) the contents of this texture to
201                        another texture. */
202                virtual void copyToTexture( TexturePtr& target );
203
204        /** Loads the data from an image.
205        */
206        virtual void loadImage( const Image &img ) = 0;
207                       
208                /** Loads the data from a raw stream.
209                */
210                virtual void loadRawData( DataStreamPtr& stream,
211                        ushort uWidth, ushort uHeight, PixelFormat eFormat);
212
213        virtual void enable32Bit( bool setting = true )
214        {
215            setting ? mFinalBpp = 32 : mFinalBpp = 16;
216        }
217
218                /** Returns the pixel format for the texture surface. */
219                virtual PixelFormat getFormat() const
220                {
221                        return mFormat;
222                }
223
224        /** Sets the pixel format for the texture surface; can only be set before load(). */
225        virtual void setFormat(PixelFormat pf);
226
227        /** Returns true if the texture has an alpha layer. */
228        virtual bool hasAlpha(void) const
229        {
230            return mHasAlpha;
231        }
232       
233        /** Return the number of faces this texture has. This will be 6 for a cubemap
234                texture and 1 for a 1D, 2D or 3D one.
235        */
236        virtual size_t getNumFaces() const;
237
238                /** Return hardware pixel buffer for a surface. This buffer can then
239                        be used to copy data from and to a particular level of the texture.
240                        @param face     Face number, in case of a cubemap texture. Must be 0
241                                                        for other types of textures.
242                            For cubemaps, this is one of
243                            +X (0), -X (1), +Y (2), -Y (3), +Z (4), -Z (5)
244                        @param mipmap   Mipmap level. This goes from 0 for the first, largest
245                                                        mipmap level to getNumMipmaps()-1 for the smallest.
246                        @returns        A shared pointer to a hardware pixel buffer
247                        @remarks        The buffer is invalidated when the resource is unloaded or destroyed.
248                                                Do not use it after the lifetime of the containing texture.
249                */
250                virtual HardwarePixelBufferSharedPtr getBuffer(size_t face=0, size_t mipmap=0) = 0;
251
252    protected:
253        unsigned long mHeight;
254        unsigned long mWidth;
255        unsigned long mDepth;
256
257        size_t mNumRequestedMipmaps;
258                size_t mNumMipmaps;
259                bool mMipmapsHardwareGenerated;
260        float mGamma;
261
262        TextureType mTextureType;
263                PixelFormat mFormat;
264        int mUsage; // Bit field, so this can't be TextureUsage
265
266        unsigned short mSrcBpp;
267        unsigned long mSrcWidth, mSrcHeight, mSrcDepth;
268        unsigned short mFinalBpp;
269        bool mHasAlpha;
270
271                bool mInternalResourcesCreated;
272
273                /// @copydoc Resource::calculateSize
274                size_t calculateSize(void) const;
275               
276                /** Generic method to load the texture from a set of images. This can be
277                        used by the specific implementation for convience. Implementations
278                        might decide not to use this function if they can use their own image loading
279                        functions.
280                        @param images   Vector of pointers to Images. If there is only one image
281                        in this vector, the faces of that image will be used. If there are multiple
282                        images in the vector each image will be loaded as a face.
283                */
284        virtual void _loadImages( const std::vector<const Image*>& images );
285
286
287                /** Implementation of creating internal texture resources
288                */
289                virtual void createInternalResourcesImpl(void) = 0;
290
291                /** Implementation of freeing internal texture resources
292                */
293                virtual void freeInternalResourcesImpl(void) = 0;
294
295                /** Default implementation of unload which calls freeInternalResources */
296                void unloadImpl(void);
297
298    };
299
300    /** Specialisation of SharedPtr to allow SharedPtr to be assigned to TexturePtr
301    @note Has to be a subclass since we need operator=.
302    We could templatise this instead of repeating per Resource subclass,
303    except to do so requires a form VC6 does not support i.e.
304    ResourceSubclassPtr<T> : public SharedPtr<T>
305    */
306    class _OgreExport TexturePtr : public SharedPtr<Texture>
307    {
308    public:
309        TexturePtr() : SharedPtr<Texture>() {}
310        explicit TexturePtr(Texture* rep) : SharedPtr<Texture>(rep) {}
311        TexturePtr(const TexturePtr& r) : SharedPtr<Texture>(r) {}
312        TexturePtr(const ResourcePtr& r) : SharedPtr<Texture>()
313        {
314                        // lock & copy other mutex pointer
315            OGRE_MUTEX_CONDITIONAL(r.OGRE_AUTO_MUTEX_NAME)
316            {
317                            OGRE_LOCK_MUTEX(*r.OGRE_AUTO_MUTEX_NAME)
318                            OGRE_COPY_AUTO_SHARED_MUTEX(r.OGRE_AUTO_MUTEX_NAME)
319                pRep = static_cast<Texture*>(r.getPointer());
320                pUseCount = r.useCountPointer();
321                if (pUseCount)
322                {
323                    ++(*pUseCount);
324                }
325            }
326        }
327
328        /// Operator used to convert a ResourcePtr to a TexturePtr
329        TexturePtr& operator=(const ResourcePtr& r)
330        {
331            if (pRep == static_cast<Texture*>(r.getPointer()))
332                return *this;
333            release();
334                        // lock & copy other mutex pointer
335            OGRE_MUTEX_CONDITIONAL(r.OGRE_AUTO_MUTEX_NAME)
336            {
337                            OGRE_LOCK_MUTEX(*r.OGRE_AUTO_MUTEX_NAME)
338                            OGRE_COPY_AUTO_SHARED_MUTEX(r.OGRE_AUTO_MUTEX_NAME)
339                pRep = static_cast<Texture*>(r.getPointer());
340                pUseCount = r.useCountPointer();
341                if (pUseCount)
342                {
343                    ++(*pUseCount);
344                }
345            }
346            return *this;
347        }
348    };
349
350}
351
352#endif
Note: See TracBrowser for help on using the repository browser.