[3] | 1 | /* |
---|
| 2 | ----------------------------------------------------------------------------- |
---|
| 3 | This source file is part of OGRE |
---|
| 4 | (Object-oriented Graphics Rendering Engine) |
---|
| 5 | For the latest info, see http://www.ogre3d.org/ |
---|
| 6 | |
---|
| 7 | Copyright (c) 2000-2006 Torus Knot Software Ltd |
---|
| 8 | Also see acknowledgements in Readme.html |
---|
| 9 | |
---|
| 10 | This program is free software; you can redistribute it and/or modify it under |
---|
| 11 | the terms of the GNU Lesser General Public License as published by the Free Software |
---|
| 12 | Foundation; either version 2 of the License, or (at your option) any later |
---|
| 13 | version. |
---|
| 14 | |
---|
| 15 | This program is distributed in the hope that it will be useful, but WITHOUT |
---|
| 16 | ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS |
---|
| 17 | FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details. |
---|
| 18 | |
---|
| 19 | You should have received a copy of the GNU Lesser General Public License along with |
---|
| 20 | this program; if not, write to the Free Software Foundation, Inc., 59 Temple |
---|
| 21 | Place - Suite 330, Boston, MA 02111-1307, USA, or go to |
---|
| 22 | http://www.gnu.org/copyleft/lesser.txt. |
---|
| 23 | |
---|
| 24 | You may alternatively use this source under the terms of a specific version of |
---|
| 25 | the OGRE Unrestricted License provided you have obtained such a license from |
---|
| 26 | Torus Knot Software Ltd. |
---|
| 27 | ----------------------------------------------------------------------------- |
---|
| 28 | */ |
---|
| 29 | #ifndef _Texture_H__ |
---|
| 30 | #define _Texture_H__ |
---|
| 31 | |
---|
| 32 | #include "OgrePrerequisites.h" |
---|
| 33 | #include "OgreHardwareBuffer.h" |
---|
| 34 | #include "OgreResource.h" |
---|
| 35 | #include "OgreImage.h" |
---|
| 36 | |
---|
| 37 | namespace Ogre { |
---|
| 38 | |
---|
| 39 | /** Enum identifying the texture usage |
---|
| 40 | */ |
---|
| 41 | enum TextureUsage |
---|
| 42 | { |
---|
| 43 | /// @copydoc HardwareBuffer::Usage |
---|
| 44 | TU_STATIC = HardwareBuffer::HBU_STATIC, |
---|
| 45 | TU_DYNAMIC = HardwareBuffer::HBU_DYNAMIC, |
---|
| 46 | TU_WRITE_ONLY = HardwareBuffer::HBU_WRITE_ONLY, |
---|
| 47 | TU_STATIC_WRITE_ONLY = HardwareBuffer::HBU_STATIC_WRITE_ONLY, |
---|
| 48 | TU_DYNAMIC_WRITE_ONLY = HardwareBuffer::HBU_DYNAMIC_WRITE_ONLY, |
---|
| 49 | TU_DYNAMIC_WRITE_ONLY_DISCARDABLE = HardwareBuffer::HBU_DYNAMIC_WRITE_ONLY_DISCARDABLE, |
---|
| 50 | /// mipmaps will be automatically generated for this texture |
---|
| 51 | TU_AUTOMIPMAP = 0x100, |
---|
| 52 | /// this texture will be a render target, ie. used as a target for render to texture |
---|
| 53 | /// setting this flag will ignore all other texture usages except TU_AUTOMIPMAP |
---|
| 54 | TU_RENDERTARGET = 0x200, |
---|
| 55 | /// default to automatic mipmap generation static textures |
---|
| 56 | TU_DEFAULT = TU_AUTOMIPMAP | TU_STATIC_WRITE_ONLY |
---|
| 57 | |
---|
| 58 | }; |
---|
| 59 | |
---|
| 60 | /** Enum identifying the texture type |
---|
| 61 | */ |
---|
| 62 | enum TextureType |
---|
| 63 | { |
---|
| 64 | /// 1D texture, used in combination with 1D texture coordinates |
---|
| 65 | TEX_TYPE_1D = 1, |
---|
| 66 | /// 2D texture, used in combination with 2D texture coordinates (default) |
---|
| 67 | TEX_TYPE_2D = 2, |
---|
| 68 | /// 3D volume texture, used in combination with 3D texture coordinates |
---|
| 69 | TEX_TYPE_3D = 3, |
---|
| 70 | /// 3D cube map, used in combination with 3D texture coordinates |
---|
| 71 | TEX_TYPE_CUBE_MAP = 4 |
---|
| 72 | }; |
---|
| 73 | |
---|
| 74 | /** Enum identifying special mipmap numbers |
---|
| 75 | */ |
---|
| 76 | enum TextureMipmap |
---|
| 77 | { |
---|
| 78 | /// Generate mipmaps up to 1x1 |
---|
| 79 | MIP_UNLIMITED = 0x7FFFFFFF, |
---|
| 80 | /// Use TextureManager default |
---|
| 81 | MIP_DEFAULT = -1 |
---|
| 82 | }; |
---|
| 83 | |
---|
| 84 | // Forward declaration |
---|
| 85 | class TexturePtr; |
---|
| 86 | |
---|
| 87 | /** Abstract class representing a Texture resource. |
---|
| 88 | @remarks |
---|
| 89 | The actual concrete subclass which will exist for a texture |
---|
| 90 | is dependent on the rendering system in use (Direct3D, OpenGL etc). |
---|
| 91 | This class represents the commonalities, and is the one 'used' |
---|
| 92 | by programmers even though the real implementation could be |
---|
| 93 | different in reality. Texture objects are created through |
---|
| 94 | the 'create' method of the TextureManager concrete subclass. |
---|
| 95 | */ |
---|
| 96 | class _OgreExport Texture : public Resource |
---|
| 97 | { |
---|
| 98 | public: |
---|
| 99 | Texture(ResourceManager* creator, const String& name, ResourceHandle handle, |
---|
| 100 | const String& group, bool isManual = false, ManualResourceLoader* loader = 0); |
---|
| 101 | |
---|
| 102 | /** Sets the type of texture; can only be changed before load() |
---|
| 103 | */ |
---|
| 104 | virtual void setTextureType(TextureType ttype ) { mTextureType = ttype; } |
---|
| 105 | |
---|
| 106 | /** Gets the type of texture |
---|
| 107 | */ |
---|
| 108 | virtual TextureType getTextureType(void) const { return mTextureType; } |
---|
| 109 | |
---|
| 110 | /** Gets the number of mipmaps to be used for this texture. |
---|
| 111 | */ |
---|
| 112 | virtual size_t getNumMipmaps(void) const {return mNumMipmaps;} |
---|
| 113 | |
---|
| 114 | /** Sets the number of mipmaps to be used for this texture. |
---|
| 115 | @note |
---|
| 116 | Must be set before calling any 'load' method. |
---|
| 117 | */ |
---|
| 118 | virtual void setNumMipmaps(size_t num) {mNumRequestedMipmaps = mNumMipmaps = num;} |
---|
| 119 | |
---|
| 120 | /** Are mipmaps hardware generated? |
---|
| 121 | @remarks |
---|
| 122 | Will only be accurate after texture load, or createInternalResources |
---|
| 123 | */ |
---|
| 124 | virtual bool getMipmapsHardwareGenerated(void) const { return mMipmapsHardwareGenerated; } |
---|
| 125 | |
---|
| 126 | /** Returns the gamma adjustment factor applied to this texture. |
---|
| 127 | */ |
---|
| 128 | virtual float getGamma(void) const { return mGamma; } |
---|
| 129 | |
---|
| 130 | /** Sets the gamma adjustment factor applied to this texture. |
---|
| 131 | @note |
---|
| 132 | Must be called before any 'load' method. |
---|
| 133 | */ |
---|
| 134 | virtual void setGamma(float g) { mGamma = g; } |
---|
| 135 | |
---|
| 136 | /** Returns the height of the texture. |
---|
| 137 | */ |
---|
| 138 | virtual size_t getHeight(void) const { return mHeight; } |
---|
| 139 | |
---|
| 140 | /** Returns the width of the texture. |
---|
| 141 | */ |
---|
| 142 | virtual size_t getWidth(void) const { return mWidth; } |
---|
| 143 | |
---|
| 144 | /** Returns the depth of the texture (only applicable for 3D textures). |
---|
| 145 | */ |
---|
| 146 | virtual size_t getDepth(void) const { return mDepth; } |
---|
| 147 | |
---|
| 148 | /** Returns the height of the original input texture (may differ due to hardware requirements). |
---|
| 149 | */ |
---|
| 150 | virtual size_t getSrcHeight(void) const { return mSrcHeight; } |
---|
| 151 | |
---|
| 152 | /** Returns the width of the original input texture (may differ due to hardware requirements). |
---|
| 153 | */ |
---|
| 154 | virtual size_t getSrcWidth(void) const { return mSrcWidth; } |
---|
| 155 | |
---|
| 156 | /** Returns the original depth of the input texture (only applicable for 3D textures). |
---|
| 157 | */ |
---|
| 158 | virtual size_t getSrcDepth(void) const { return mSrcDepth; } |
---|
| 159 | |
---|
| 160 | /** Set the height of the texture; can only do this before load(); |
---|
| 161 | */ |
---|
| 162 | virtual void setHeight(size_t h) { mHeight = mSrcHeight = h; } |
---|
| 163 | |
---|
| 164 | /** Set the width of the texture; can only do this before load(); |
---|
| 165 | */ |
---|
| 166 | virtual void setWidth(size_t w) { mWidth = mSrcWidth = w; } |
---|
| 167 | |
---|
| 168 | /** Set the depth of the texture (only applicable for 3D textures); |
---|
| 169 | ; can only do this before load(); |
---|
| 170 | */ |
---|
| 171 | virtual void setDepth(size_t d) { mDepth = mSrcDepth = d; } |
---|
| 172 | |
---|
| 173 | /** Returns the TextureUsage indentifier for this Texture |
---|
| 174 | */ |
---|
| 175 | virtual int getUsage() const |
---|
| 176 | { |
---|
| 177 | return mUsage; |
---|
| 178 | } |
---|
| 179 | |
---|
| 180 | /** Sets the TextureUsage indentifier for this Texture; only useful before load() |
---|
| 181 | |
---|
| 182 | @param u is a combination of TU_STATIC, TU_DYNAMIC, TU_WRITE_ONLY |
---|
| 183 | TU_AUTOMIPMAP and TU_RENDERTARGET (see TextureUsage enum). You are |
---|
| 184 | strongly advised to use HBU_STATIC_WRITE_ONLY wherever possible, if you need to |
---|
| 185 | update regularly, consider HBU_DYNAMIC_WRITE_ONLY. |
---|
| 186 | */ |
---|
| 187 | virtual void setUsage(int u) { mUsage = u; } |
---|
| 188 | |
---|
| 189 | /** Creates the internal texture resources for this texture. |
---|
| 190 | @remarks |
---|
| 191 | This method creates the internal texture resources (pixel buffers, |
---|
| 192 | texture surfaces etc) required to begin using this texture. You do |
---|
| 193 | not need to call this method directly unless you are manually creating |
---|
| 194 | a texture, in which case something must call it, after having set the |
---|
| 195 | size and format of the texture (e.g. the ManualResourceLoader might |
---|
| 196 | be the best one to call it). If you are not defining a manual texture, |
---|
| 197 | or if you use one of the self-contained load...() methods, then it will be |
---|
| 198 | called for you. |
---|
| 199 | */ |
---|
| 200 | virtual void createInternalResources(void); |
---|
| 201 | |
---|
| 202 | /** Frees internal texture resources for this texture. |
---|
| 203 | */ |
---|
| 204 | virtual void freeInternalResources(void); |
---|
| 205 | |
---|
| 206 | /** Copies (and maybe scales to fit) the contents of this texture to |
---|
| 207 | another texture. */ |
---|
| 208 | virtual void copyToTexture( TexturePtr& target ); |
---|
| 209 | |
---|
| 210 | /** Loads the data from an image. |
---|
| 211 | @note Important: only call this from outside the load() routine of a |
---|
| 212 | Resource. Don't call it within (including ManualResourceLoader) - use |
---|
| 213 | _loadImages() instead. This method is designed to be external, |
---|
| 214 | performs locking and checks the load status before loading. |
---|
| 215 | */ |
---|
| 216 | virtual void loadImage( const Image &img ); |
---|
| 217 | |
---|
| 218 | /** Loads the data from a raw stream. |
---|
| 219 | @note Important: only call this from outside the load() routine of a |
---|
| 220 | Resource. Don't call it within (including ManualResourceLoader) - use |
---|
| 221 | _loadImages() instead. This method is designed to be external, |
---|
| 222 | performs locking and checks the load status before loading. |
---|
| 223 | @param stream Data stream containing the raw pixel data |
---|
| 224 | @param uWidth Width of the image |
---|
| 225 | @param uHeight Height of the image |
---|
| 226 | @param eFormat The format of the pixel data |
---|
| 227 | */ |
---|
| 228 | virtual void loadRawData( DataStreamPtr& stream, |
---|
| 229 | ushort uWidth, ushort uHeight, PixelFormat eFormat); |
---|
| 230 | |
---|
| 231 | /** Internal method to load the texture from a set of images. |
---|
| 232 | @note Do NOT call this method unless you are inside the load() routine |
---|
| 233 | already, e.g. a ManualResourceLoader. It is not threadsafe and does |
---|
| 234 | not check or update resource loading status. |
---|
| 235 | */ |
---|
| 236 | virtual void _loadImages( const ConstImagePtrList& images ); |
---|
| 237 | |
---|
| 238 | /** Returns the pixel format for the texture surface. */ |
---|
| 239 | virtual PixelFormat getFormat() const |
---|
| 240 | { |
---|
| 241 | return mFormat; |
---|
| 242 | } |
---|
| 243 | |
---|
| 244 | /** Returns the desired pixel format for the texture surface. */ |
---|
| 245 | virtual PixelFormat getDesiredFormat(void) const |
---|
| 246 | { |
---|
| 247 | return mDesiredFormat; |
---|
| 248 | } |
---|
| 249 | |
---|
| 250 | /** Returns the pixel format of the original input texture (may differ due to |
---|
| 251 | hardware requirements and pixel format convertion). |
---|
| 252 | */ |
---|
| 253 | virtual PixelFormat getSrcFormat(void) const |
---|
| 254 | { |
---|
| 255 | return mSrcFormat; |
---|
| 256 | } |
---|
| 257 | |
---|
| 258 | /** Sets the pixel format for the texture surface; can only be set before load(). */ |
---|
| 259 | virtual void setFormat(PixelFormat pf); |
---|
| 260 | |
---|
| 261 | /** Returns true if the texture has an alpha layer. */ |
---|
| 262 | virtual bool hasAlpha(void) const; |
---|
| 263 | |
---|
| 264 | /** Sets desired bit depth for integer pixel format textures. |
---|
| 265 | @note |
---|
| 266 | Available values: 0, 16 and 32, where 0 (the default) means keep original format |
---|
| 267 | as it is. This value is number of bits for the pixel. |
---|
| 268 | */ |
---|
| 269 | virtual void setDesiredIntegerBitDepth(ushort bits); |
---|
| 270 | |
---|
| 271 | /** gets desired bit depth for integer pixel format textures. |
---|
| 272 | */ |
---|
| 273 | virtual ushort getDesiredIntegerBitDepth(void) const; |
---|
| 274 | |
---|
| 275 | /** Sets desired bit depth for float pixel format textures. |
---|
| 276 | @note |
---|
| 277 | Available values: 0, 16 and 32, where 0 (the default) means keep original format |
---|
| 278 | as it is. This value is number of bits for a channel of the pixel. |
---|
| 279 | */ |
---|
| 280 | virtual void setDesiredFloatBitDepth(ushort bits); |
---|
| 281 | |
---|
| 282 | /** gets desired bit depth for float pixel format textures. |
---|
| 283 | */ |
---|
| 284 | virtual ushort getDesiredFloatBitDepth(void) const; |
---|
| 285 | |
---|
| 286 | /** Sets desired bit depth for integer and float pixel format. |
---|
| 287 | */ |
---|
| 288 | virtual void setDesiredBitDepths(ushort integerBits, ushort floatBits); |
---|
| 289 | |
---|
| 290 | /** Sets whether luminace pixel format will treated as alpha format when load this texture. |
---|
| 291 | */ |
---|
| 292 | virtual void setTreatLuminanceAsAlpha(bool asAlpha); |
---|
| 293 | |
---|
| 294 | /** Gets whether luminace pixel format will treated as alpha format when load this texture. |
---|
| 295 | */ |
---|
| 296 | virtual bool getTreatLuminanceAsAlpha(void) const; |
---|
| 297 | |
---|
| 298 | /** Return the number of faces this texture has. This will be 6 for a cubemap |
---|
| 299 | texture and 1 for a 1D, 2D or 3D one. |
---|
| 300 | */ |
---|
| 301 | virtual size_t getNumFaces() const; |
---|
| 302 | |
---|
| 303 | /** Return hardware pixel buffer for a surface. This buffer can then |
---|
| 304 | be used to copy data from and to a particular level of the texture. |
---|
| 305 | @param face Face number, in case of a cubemap texture. Must be 0 |
---|
| 306 | for other types of textures. |
---|
| 307 | For cubemaps, this is one of |
---|
| 308 | +X (0), -X (1), +Y (2), -Y (3), +Z (4), -Z (5) |
---|
| 309 | @param mipmap Mipmap level. This goes from 0 for the first, largest |
---|
| 310 | mipmap level to getNumMipmaps()-1 for the smallest. |
---|
| 311 | @returns A shared pointer to a hardware pixel buffer |
---|
| 312 | @remarks The buffer is invalidated when the resource is unloaded or destroyed. |
---|
| 313 | Do not use it after the lifetime of the containing texture. |
---|
| 314 | */ |
---|
| 315 | virtual HardwarePixelBufferSharedPtr getBuffer(size_t face=0, size_t mipmap=0) = 0; |
---|
| 316 | |
---|
| 317 | protected: |
---|
| 318 | size_t mHeight; |
---|
| 319 | size_t mWidth; |
---|
| 320 | size_t mDepth; |
---|
| 321 | |
---|
| 322 | size_t mNumRequestedMipmaps; |
---|
| 323 | size_t mNumMipmaps; |
---|
| 324 | bool mMipmapsHardwareGenerated; |
---|
| 325 | float mGamma; |
---|
| 326 | |
---|
| 327 | TextureType mTextureType; |
---|
| 328 | PixelFormat mFormat; |
---|
| 329 | int mUsage; // Bit field, so this can't be TextureUsage |
---|
| 330 | |
---|
| 331 | PixelFormat mSrcFormat; |
---|
| 332 | size_t mSrcWidth, mSrcHeight, mSrcDepth; |
---|
| 333 | |
---|
| 334 | PixelFormat mDesiredFormat; |
---|
| 335 | unsigned short mDesiredIntegerBitDepth; |
---|
| 336 | unsigned short mDesiredFloatBitDepth; |
---|
| 337 | bool mTreatLuminanceAsAlpha; |
---|
| 338 | |
---|
| 339 | bool mInternalResourcesCreated; |
---|
| 340 | |
---|
| 341 | /// @copydoc Resource::calculateSize |
---|
| 342 | size_t calculateSize(void) const; |
---|
| 343 | |
---|
| 344 | |
---|
| 345 | /** Implementation of creating internal texture resources |
---|
| 346 | */ |
---|
| 347 | virtual void createInternalResourcesImpl(void) = 0; |
---|
| 348 | |
---|
| 349 | /** Implementation of freeing internal texture resources |
---|
| 350 | */ |
---|
| 351 | virtual void freeInternalResourcesImpl(void) = 0; |
---|
| 352 | |
---|
| 353 | /** Default implementation of unload which calls freeInternalResources */ |
---|
| 354 | void unloadImpl(void); |
---|
| 355 | |
---|
| 356 | }; |
---|
| 357 | |
---|
| 358 | /** Specialisation of SharedPtr to allow SharedPtr to be assigned to TexturePtr |
---|
| 359 | @note Has to be a subclass since we need operator=. |
---|
| 360 | We could templatise this instead of repeating per Resource subclass, |
---|
| 361 | except to do so requires a form VC6 does not support i.e. |
---|
| 362 | ResourceSubclassPtr<T> : public SharedPtr<T> |
---|
| 363 | */ |
---|
| 364 | class _OgreExport TexturePtr : public SharedPtr<Texture> |
---|
| 365 | { |
---|
| 366 | public: |
---|
| 367 | TexturePtr() : SharedPtr<Texture>() {} |
---|
| 368 | explicit TexturePtr(Texture* rep) : SharedPtr<Texture>(rep) {} |
---|
| 369 | TexturePtr(const TexturePtr& r) : SharedPtr<Texture>(r) {} |
---|
| 370 | TexturePtr(const ResourcePtr& r) : SharedPtr<Texture>() |
---|
| 371 | { |
---|
| 372 | // lock & copy other mutex pointer |
---|
| 373 | OGRE_MUTEX_CONDITIONAL(r.OGRE_AUTO_MUTEX_NAME) |
---|
| 374 | { |
---|
| 375 | OGRE_LOCK_MUTEX(*r.OGRE_AUTO_MUTEX_NAME) |
---|
| 376 | OGRE_COPY_AUTO_SHARED_MUTEX(r.OGRE_AUTO_MUTEX_NAME) |
---|
| 377 | pRep = static_cast<Texture*>(r.getPointer()); |
---|
| 378 | pUseCount = r.useCountPointer(); |
---|
| 379 | if (pUseCount) |
---|
| 380 | { |
---|
| 381 | ++(*pUseCount); |
---|
| 382 | } |
---|
| 383 | } |
---|
| 384 | } |
---|
| 385 | |
---|
| 386 | /// Operator used to convert a ResourcePtr to a TexturePtr |
---|
| 387 | TexturePtr& operator=(const ResourcePtr& r) |
---|
| 388 | { |
---|
| 389 | if (pRep == static_cast<Texture*>(r.getPointer())) |
---|
| 390 | return *this; |
---|
| 391 | release(); |
---|
| 392 | // lock & copy other mutex pointer |
---|
| 393 | OGRE_MUTEX_CONDITIONAL(r.OGRE_AUTO_MUTEX_NAME) |
---|
| 394 | { |
---|
| 395 | OGRE_LOCK_MUTEX(*r.OGRE_AUTO_MUTEX_NAME) |
---|
| 396 | OGRE_COPY_AUTO_SHARED_MUTEX(r.OGRE_AUTO_MUTEX_NAME) |
---|
| 397 | pRep = static_cast<Texture*>(r.getPointer()); |
---|
| 398 | pUseCount = r.useCountPointer(); |
---|
| 399 | if (pUseCount) |
---|
| 400 | { |
---|
| 401 | ++(*pUseCount); |
---|
| 402 | } |
---|
| 403 | } |
---|
| 404 | else |
---|
| 405 | { |
---|
| 406 | // RHS must be a null pointer |
---|
| 407 | assert(r.isNull() && "RHS must be null if it has no mutex!"); |
---|
| 408 | setNull(); |
---|
| 409 | } |
---|
| 410 | return *this; |
---|
| 411 | } |
---|
| 412 | }; |
---|
| 413 | |
---|
| 414 | } |
---|
| 415 | |
---|
| 416 | #endif |
---|