source: OGRE/trunk/ogrenew/OgreMain/include/OgreTexture.h @ 657

Revision 657, 12.9 KB checked in by mattausch, 19 years ago (diff)

added ogre dependencies and patched ogre sources

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                /** Copies (and maybe scales to fit) the contents of this texture to
200                        another texture. */
201                virtual void copyToTexture( TexturePtr& target ) {}
202
203        /** Loads the data from an image.
204        */
205        virtual void loadImage( const Image &img ) = 0;
206                       
207                /** Loads the data from a raw stream.
208                */
209                virtual void loadRawData( DataStreamPtr& stream,
210                        ushort uWidth, ushort uHeight, PixelFormat eFormat);
211
212        virtual void enable32Bit( bool setting = true )
213        {
214            setting ? mFinalBpp = 32 : mFinalBpp = 16;
215        }
216
217                /** Returns the pixel format for the texture surface. */
218                virtual PixelFormat getFormat() const
219                {
220                        return mFormat;
221                }
222
223        /** Sets the pixel format for the texture surface; can only be set before load(). */
224        virtual void setFormat(PixelFormat pf);
225
226        /** Returns true if the texture has an alpha layer. */
227        virtual bool hasAlpha(void) const
228        {
229            return mHasAlpha;
230        }
231       
232        /** Return the number of faces this texture has. This will be 6 for a cubemap
233                texture and 1 for a 1D, 2D or 3D one.
234        */
235        virtual size_t getNumFaces() const;
236
237                /** Return hardware pixel buffer for a surface. This buffer can then
238                        be used to copy data from and to a particular level of the texture.
239                        @param face     Face number, in case of a cubemap texture. Must be 0
240                                                        for other types of textures.
241                        @param mipmap   Mipmap level. This goes from 0 for the first, largest
242                                                        mipmap level to getNumMipmaps()-1 for the smallest.
243                        @returns        A shared pointer to a hardware pixel buffer
244                        @remarks        The buffer is invalidated when the resource is unloaded or destroyed.
245                                                Do not use it after the lifetime of the containing texture.
246                */
247                virtual HardwarePixelBufferSharedPtr getBuffer(size_t face=0, size_t mipmap=0) = 0;
248
249    protected:
250        unsigned long mHeight;
251        unsigned long mWidth;
252        unsigned long mDepth;
253
254        size_t mNumRequestedMipmaps;
255                size_t mNumMipmaps;
256                bool mMipmapsHardwareGenerated;
257        float mGamma;
258
259        TextureType mTextureType;
260                PixelFormat mFormat;
261        int mUsage; // Bit field, so this can't be TextureUsage
262
263        unsigned short mSrcBpp;
264        unsigned long mSrcWidth, mSrcHeight, mSrcDepth;
265        unsigned short mFinalBpp;
266        bool mHasAlpha;
267
268                bool mInternalResourcesCreated;
269
270                /// @copydoc Resource::calculateSize
271                size_t calculateSize(void) const;
272               
273                /** Generic method to load the texture from a set of images. This can be
274                        used by the specific implementation for convience. Implementations
275                        might decide not to use this function if they can use their own image loading
276                        functions.
277                        @param images   Vector of pointers to Images. If there is only one image
278                        in this vector, the faces of that image will be used. If there are multiple
279                        images in the vector each image will be loaded as a face.
280                */
281        virtual void _loadImages( const std::vector<const Image*>& images );
282
283
284                /** Implementation of creating internal texture resources
285                */
286                virtual void createInternalResourcesImpl(void) = 0;
287
288                /** Implementation of freeing internal texture resources
289                */
290                virtual void freeInternalResourcesImpl(void) = 0;
291
292                /** Default implementation of unload which calls freeInternalResources */
293                void unloadImpl(void);
294
295    };
296
297    /** Specialisation of SharedPtr to allow SharedPtr to be assigned to TexturePtr
298    @note Has to be a subclass since we need operator=.
299    We could templatise this instead of repeating per Resource subclass,
300    except to do so requires a form VC6 does not support i.e.
301    ResourceSubclassPtr<T> : public SharedPtr<T>
302    */
303    class _OgreExport TexturePtr : public SharedPtr<Texture>
304    {
305    public:
306        TexturePtr() : SharedPtr<Texture>() {}
307        explicit TexturePtr(Texture* rep) : SharedPtr<Texture>(rep) {}
308        TexturePtr(const TexturePtr& r) : SharedPtr<Texture>(r) {}
309        TexturePtr(const ResourcePtr& r) : SharedPtr<Texture>()
310        {
311                        // lock & copy other mutex pointer
312                        OGRE_LOCK_MUTEX(*r.OGRE_AUTO_MUTEX_NAME)
313                        OGRE_COPY_AUTO_SHARED_MUTEX(r.OGRE_AUTO_MUTEX_NAME)
314            pRep = static_cast<Texture*>(r.getPointer());
315            pUseCount = r.useCountPointer();
316            if (pUseCount)
317            {
318                ++(*pUseCount);
319            }
320        }
321
322        /// Operator used to convert a ResourcePtr to a TexturePtr
323        TexturePtr& operator=(const ResourcePtr& r)
324        {
325            if (pRep == static_cast<Texture*>(r.getPointer()))
326                return *this;
327            release();
328                        // lock & copy other mutex pointer
329                        OGRE_LOCK_MUTEX(*r.OGRE_AUTO_MUTEX_NAME)
330                        OGRE_COPY_AUTO_SHARED_MUTEX(r.OGRE_AUTO_MUTEX_NAME)
331            pRep = static_cast<Texture*>(r.getPointer());
332            pUseCount = r.useCountPointer();
333            if (pUseCount)
334            {
335                ++(*pUseCount);
336            }
337            return *this;
338        }
339    };
340
341}
342
343#endif
Note: See TracBrowser for help on using the repository browser.