include/ITexture.h

   1 // Copyright (C) 2002-2012 Nikolaus Gebhardt\r
   2 // This file is part of the "Irrlicht Engine".\r
   3 // For conditions of distribution and use, see copyright notice in irrlicht.h\r
   4 \r
   5 #ifndef __I_TEXTURE_H_INCLUDED__\r
   6 #define __I_TEXTURE_H_INCLUDED__\r
   7 \r
   8 #include "IReferenceCounted.h"\r
   9 #include "IImage.h"\r
  10 #include "dimension2d.h"\r
  11 #include "EDriverTypes.h"\r
  12 #include "path.h"\r
  13 #include "matrix4.h"\r
  14 \r
  15 namespace irr\r
  16 {\r
  17 namespace video\r
  18 {\r
  19 \r
  20 \r
  21 //! Enumeration flags used to tell the video driver with setTextureCreationFlag in which format textures should be created.\r
  22 enum E_TEXTURE_CREATION_FLAG\r
  23 {\r
  24         /** Forces the driver to create 16 bit textures always, independent of\r
  25         which format the file on disk has. When choosing this you may lose\r
  26         some color detail, but gain much speed and memory. 16 bit textures can\r
  27         be transferred twice as fast as 32 bit textures and only use half of\r
  28         the space in memory.\r
  29         When using this flag, it does not make sense to use the flags\r
  30         ETCF_ALWAYS_32_BIT, ETCF_OPTIMIZED_FOR_QUALITY, or\r
  31         ETCF_OPTIMIZED_FOR_SPEED at the same time. \r
  32         Not all texture formats are affected (usually those up to ECF_A8R8G8B8). */\r
  33         ETCF_ALWAYS_16_BIT = 0x00000001,\r
  34 \r
  35         /** Forces the driver to create 32 bit textures always, independent of\r
  36         which format the file on disk has. Please note that some drivers (like\r
  37         the software device) will ignore this, because they are only able to\r
  38         create and use 16 bit textures.\r
  39         Default is true.\r
  40         When using this flag, it does not make sense to use the flags\r
  41         ETCF_ALWAYS_16_BIT, ETCF_OPTIMIZED_FOR_QUALITY, or\r
  42         ETCF_OPTIMIZED_FOR_SPEED at the same time. \r
  43         Not all texture formats are affected (usually those up to ECF_A8R8G8B8). */\r
  44         ETCF_ALWAYS_32_BIT = 0x00000002,\r
  45 \r
  46         /** Lets the driver decide in which format the textures are created and\r
  47         tries to make the textures look as good as possible. Usually it simply\r
  48         chooses the format in which the texture was stored on disk.\r
  49         When using this flag, it does not make sense to use the flags\r
  50         ETCF_ALWAYS_16_BIT, ETCF_ALWAYS_32_BIT, or ETCF_OPTIMIZED_FOR_SPEED at\r
  51         the same time. \r
  52         Not all texture formats are affected (usually those up to ECF_A8R8G8B8). */\r
  53         ETCF_OPTIMIZED_FOR_QUALITY = 0x00000004,\r
  54 \r
  55         /** Lets the driver decide in which format the textures are created and\r
  56         tries to create them maximizing render speed.\r
  57         When using this flag, it does not make sense to use the flags\r
  58         ETCF_ALWAYS_16_BIT, ETCF_ALWAYS_32_BIT, or ETCF_OPTIMIZED_FOR_QUALITY,\r
  59         at the same time. \r
  60         Not all texture formats are affected (usually those up to ECF_A8R8G8B8). */\r
  61         ETCF_OPTIMIZED_FOR_SPEED = 0x00000008,\r
  62 \r
  63         /** Creates textures with mipmap levels. \r
  64         If disabled textures can not have mipmaps.\r
  65         Default is true. */\r
  66         ETCF_CREATE_MIP_MAPS = 0x00000010,\r
  67 \r
  68         /** Discard any alpha layer and use non-alpha color format. \r
  69         Warning: This may lead to getting 24-bit texture formats which \r
  70                  are often badly supported by drivers. So it's generally\r
  71                          not recommended to enable this flag.   */\r
  72         ETCF_NO_ALPHA_CHANNEL = 0x00000020,\r
  73 \r
  74         //! Allow the Driver to use Non-Power-2-Textures\r
  75         /** BurningVideo can handle Non-Power-2 Textures in 2D (GUI), but not in 3D. */\r
  76         ETCF_ALLOW_NON_POWER_2 = 0x00000040,\r
  77 \r
  78         //! Allow the driver to keep a copy of the texture in memory\r
  79         /** Enabling this makes calls to ITexture::lock a lot faster, but costs main memory.\r
  80         Currently only used in combination with OpenGL drivers.\r
  81         NOTE: Disabling this does not yet work correctly with alpha-textures.\r
  82         So the default is on for now (but might change with Irrlicht 1.9 if we get the alpha-troubles fixed).\r
  83         */\r
  84         ETCF_ALLOW_MEMORY_COPY = 0x00000080,\r
  85 \r
  86         //! Enable automatic updating mip maps when the base texture changes.\r
  87         /** Default is true.\r
  88         This flag is only used when ETCF_CREATE_MIP_MAPS is also enabled and if the driver supports it.\r
  89         Please note:\r
  90         - On D3D (and maybe older OGL?) you can no longer manually set mipmap data when enabled \r
  91          (for example mips from image loading will be ignored).\r
  92         - On D3D (and maybe older OGL?) texture locking for mipmap levels usually won't work anymore.\r
  93         - On new OGL this flag is ignored.\r
  94         - When disabled you do _not_ get hardware mipmaps on D3D, so mipmap generation can be slower.\r
  95         - When disabled you can still update your mipmaps when the texture changed by manually calling regenerateMipMapLevels.\r
  96         - You can still call regenerateMipMapLevels when this flag is enabled (it will be a hint on d3d to update mips immediately)\r
  97           */\r
  98         ETCF_AUTO_GENERATE_MIP_MAPS = 0x00000100,\r
  99 \r
 100         //! Enable support for vertex shader texture sampling on some drivers\r
 101         /** Default is false.\r
 102         This adds a small costs to all texture switches.\r
 103         Currently only affects D3D9. \r
 104         On OpenGL vertex shaders use the same texture unit as pixel shaders, so support there only depends on GL version and not on this flag\r
 105         */\r
 106         ETCF_SUPPORT_VERTEXT_TEXTURE = 0x00000200,\r
 107 \r
 108         /** This flag is never used, it only forces the compiler to compile\r
 109         these enumeration values to 32 bit. */\r
 110         ETCF_FORCE_32_BIT_DO_NOT_USE = 0x7fffffff\r
 111 };\r
 112 \r
 113 //! Enum for the mode for texture locking. Read-Only, write-only or read/write.\r
 114 enum E_TEXTURE_LOCK_MODE\r
 115 {\r
 116         //! The default mode. Texture can be read and written to.\r
 117         ETLM_READ_WRITE = 0,\r
 118 \r
 119         //! Read only. The texture is downloaded, but not uploaded again.\r
 120         /** Often used to read back shader generated textures. */\r
 121         ETLM_READ_ONLY,\r
 122 \r
 123         //! Write only. The texture is not downloaded and might be uninitialized.\r
 124         /** The updated texture is uploaded to the GPU.\r
 125         Used for initializing the shader from the CPU. */\r
 126         ETLM_WRITE_ONLY\r
 127 };\r
 128 \r
 129 //! Additional bitflags for ITexture::lock() call\r
 130 enum E_TEXTURE_LOCK_FLAGS\r
 131 {\r
 132         ETLF_NONE = 0,\r
 133 \r
 134         //! Flip left-bottom origin rendertarget textures upside-down\r
 135         /** Irrlicht usually has all textures with left-top as origin.\r
 136         And for drivers with a left-bottom origin coordinate system (OpenGL)\r
 137         Irrlicht modifies the texture-matrix in the fixed function pipeline to make\r
 138         the textures show up correctly (shader coders have to handle upside down \r
 139         textures themselves).\r
 140         But rendertarget textures (RTT's) are written by drivers the way the \r
 141         coordinate system of that driver works. So on OpenGL images tend to look \r
 142         upside down (aka Y coordinate going up) on lock() when this flag isn't set.\r
 143         When the flag is set it will flip such textures on lock() to make them look\r
 144         like non-rtt textures (origin left-top). Note that this also means the texture\r
 145         will be uploaded flipped on unlock. So mostly you want to have this flag set \r
 146         when you want to look at the texture or save it, but unset if you want to \r
 147         upload it again to the card.\r
 148         If you disable this flag you get the memory just as it is on the graphic card.\r
 149         For backward compatibility reasons this flag is enabled by default. */\r
 150         ETLF_FLIP_Y_UP_RTT = 1  \r
 151 };\r
 152 \r
 153 //! Where did the last IVideoDriver::getTexture call find this texture\r
 154 enum E_TEXTURE_SOURCE\r
 155 {\r
 156         //! IVideoDriver::getTexture was never called (texture created otherwise)\r
 157         ETS_UNKNOWN,\r
 158 \r
 159         //! Texture has been found in cache\r
 160         ETS_FROM_CACHE,\r
 161 \r
 162         //! Texture had to be loaded\r
 163         ETS_FROM_FILE\r
 164 };\r
 165 \r
 166 //! Enumeration describing the type of ITexture.\r
 167 enum E_TEXTURE_TYPE\r
 168 {\r
 169         //! 2D texture.\r
 170         ETT_2D,\r
 171 \r
 172         //! Cubemap texture.\r
 173         ETT_CUBEMAP\r
 174 };\r
 175 \r
 176 //! Interface of a Video Driver dependent Texture.\r
 177 /** An ITexture is created by an IVideoDriver by using IVideoDriver::addTexture\r
 178 or IVideoDriver::getTexture. After that, the texture may only be used by this\r
 179 VideoDriver. As you can imagine, textures of the DirectX and the OpenGL device\r
 180 will, e.g., not be compatible. An exception is the Software device and the\r
 181 NULL device, their textures are compatible. If you try to use a texture\r
 182 created by one device with an other device, the device will refuse to do that\r
 183 and write a warning or an error message to the output buffer.\r
 184 */\r
 185 class ITexture : public virtual IReferenceCounted\r
 186 {\r
 187 public:\r
 188 \r
 189         //! constructor\r
 190         ITexture(const io::path& name, E_TEXTURE_TYPE type) : NamedPath(name), DriverType(EDT_NULL), OriginalColorFormat(ECF_UNKNOWN),\r
 191                 ColorFormat(ECF_UNKNOWN), Pitch(0), HasMipMaps(false), IsRenderTarget(false), Source(ETS_UNKNOWN), Type(type)\r
 192         {\r
 193         }\r
 194 \r
 195         //! Lock function.\r
 196         /** Locks the Texture and returns a pointer to access the\r
 197         pixels. After lock() has been called and all operations on the pixels\r
 198         are done, you must call unlock().\r
 199         Locks are not accumulating, hence one unlock will do for an arbitrary\r
 200         number of previous locks. You should avoid locking different levels without\r
 201         unlocking in between, though, because only the last level locked will be\r
 202         unlocked.\r
 203         The size of the i-th mipmap level is defined as max(getSize().Width>>i,1)\r
 204         and max(getSize().Height>>i,1)\r
 205         \param mode Specifies what kind of changes to the locked texture are\r
 206         allowed. Unspecified behavior will arise if texture is written in read\r
 207         only mode or read from in write only mode.\r
 208         Support for this feature depends on the driver, so don't rely on the\r
 209         texture being write-protected when locking with read-only, etc.\r
 210         \param mipmapLevel NOTE: Currently broken, sorry, we try if we can repair it for 1.9 release.\r
 211         Number of the mipmapLevel to lock. 0 is main texture.\r
 212         Non-existing levels will silently fail and return 0.\r
 213         \param layer It determines which cubemap face or texture array layer should be locked.\r
 214         \param lockFlags See E_TEXTURE_LOCK_FLAGS documentation.\r
 215         \return Returns a pointer to the pixel data. The format of the pixel can\r
 216         be determined by using getColorFormat(). 0 is returned, if\r
 217         the texture cannot be locked. */\r
 218         virtual void* lock(E_TEXTURE_LOCK_MODE mode = ETLM_READ_WRITE, u32 mipmapLevel=0, u32 layer = 0, E_TEXTURE_LOCK_FLAGS lockFlags = ETLF_FLIP_Y_UP_RTT) = 0;\r
 219 \r
 220         //! Unlock function. Must be called after a lock() to the texture.\r
 221         /** One should avoid to call unlock more than once before another lock.\r
 222         The last locked mip level will be unlocked. \r
 223         You may want to call regenerateMipMapLevels() after this when you changed any data.     */\r
 224         virtual void unlock() = 0;\r
 225 \r
 226         //! Regenerates the mip map levels of the texture.\r
 227         /** Required after modifying the texture, usually after calling unlock().\r
 228         \param data Optional parameter to pass in image data which will be\r
 229         used instead of the previously stored or automatically generated mipmap\r
 230         data. The data has to be a continuous pixel data for all mipmaps until\r
 231         1x1 pixel. Each mipmap has to be half the width and height of the previous\r
 232         level. At least one pixel will be always kept.\r
 233         \param layer It informs a texture about which cubemap or texture array layer \r
 234         needs mipmap regeneration. */\r
 235         virtual void regenerateMipMapLevels(void* data = 0, u32 layer = 0) = 0;\r
 236 \r
 237         //! Get original size of the texture.\r
 238         /** The texture is usually scaled, if it was created with an unoptimal\r
 239         size. For example if the size was not a power of two. This method\r
 240         returns the size of the texture it had before it was scaled. Can be\r
 241         useful when drawing 2d images on the screen, which should have the\r
 242         exact size of the original texture. Use ITexture::getSize() if you want\r
 243         to know the real size it has now stored in the system.\r
 244         \return The original size of the texture. */\r
 245         const core::dimension2d<u32>& getOriginalSize() const { return OriginalSize; };\r
 246 \r
 247         //! Get dimension (=size) of the texture.\r
 248         /** \return The size of the texture. */\r
 249         const core::dimension2d<u32>& getSize() const { return Size; };\r
 250 \r
 251         //! Get driver type of texture.\r
 252         /** This is the driver, which created the texture. This method is used\r
 253         internally by the video devices, to check, if they may use a texture\r
 254         because textures may be incompatible between different devices.\r
 255         \return Driver type of texture. */\r
 256         E_DRIVER_TYPE getDriverType() const { return DriverType; };\r
 257 \r
 258         //! Get the color format of texture.\r
 259         /** \return The color format of texture. */\r
 260         ECOLOR_FORMAT getColorFormat() const { return ColorFormat; };\r
 261 \r
 262         //! Get the original color format\r
 263         /** When create textures from image data we will often use different color formats.\r
 264         For example depending on driver TextureCreationFlag's. \r
 265         This can give you the original format which the image used to create the texture had    */\r
 266         ECOLOR_FORMAT getOriginalColorFormat() const { return OriginalColorFormat; };\r
 267 \r
 268         //! Get pitch of the main texture (in bytes).\r
 269         /** The pitch is the amount of bytes used for a row of pixels in a\r
 270         texture.\r
 271         \return Pitch of texture in bytes. */\r
 272         u32 getPitch() const { return Pitch; };\r
 273 \r
 274         //! Check whether the texture has MipMaps\r
 275         /** \return True if texture has MipMaps, else false. */\r
 276         bool hasMipMaps() const { return HasMipMaps; }\r
 277 \r
 278         //! Check whether the texture is a render target\r
 279         /** Render targets can be set as such in the video driver, in order to\r
 280         render a scene into the texture. Once unbound as render target, they can\r
 281         be used just as usual textures again.\r
 282         \return True if this is a render target, otherwise false. */\r
 283         bool isRenderTarget() const { return IsRenderTarget; }\r
 284 \r
 285         //! Get name of texture (in most cases this is the filename)\r
 286         const io::SNamedPath& getName() const { return NamedPath; }\r
 287 \r
 288         //! Check where the last IVideoDriver::getTexture found this texture\r
 289         E_TEXTURE_SOURCE getSource() const { return Source; }\r
 290 \r
 291         //! Used internally by the engine to update Source status on IVideoDriver::getTexture calls.\r
 292         void updateSource(E_TEXTURE_SOURCE source) { Source = source; }\r
 293 \r
 294         //! Returns if the texture has an alpha channel\r
 295         bool hasAlpha() const\r
 296         {\r
 297                 bool status = false;\r
 298 \r
 299                 switch (ColorFormat)\r
 300                 {\r
 301                 case ECF_A8R8G8B8:\r
 302                 case ECF_A1R5G5B5:\r
 303                 case ECF_DXT1:\r
 304                 case ECF_DXT2:\r
 305                 case ECF_DXT3:\r
 306                 case ECF_DXT4:\r
 307                 case ECF_DXT5:\r
 308                 case ECF_A16B16G16R16F:\r
 309                 case ECF_A32B32G32R32F:\r
 310                         status = true;\r
 311                         break;\r
 312                 default:\r
 313                         break;\r
 314                 }\r
 315 \r
 316                 return status;\r
 317         }\r
 318 \r
 319         //! Returns the type of texture\r
 320         E_TEXTURE_TYPE getType() const { return Type; }\r
 321 \r
 322 protected:\r
 323 \r
 324         //! Helper function, helps to get the desired texture creation format from the flags.\r
 325         /** \return Either ETCF_ALWAYS_32_BIT, ETCF_ALWAYS_16_BIT,\r
 326         ETCF_OPTIMIZED_FOR_QUALITY, or ETCF_OPTIMIZED_FOR_SPEED. */\r
 327         inline E_TEXTURE_CREATION_FLAG getTextureFormatFromFlags(u32 flags)\r
 328         {\r
 329                 if (flags & ETCF_OPTIMIZED_FOR_SPEED)\r
 330                         return ETCF_OPTIMIZED_FOR_SPEED;\r
 331                 if (flags & ETCF_ALWAYS_16_BIT)\r
 332                         return ETCF_ALWAYS_16_BIT;\r
 333                 if (flags & ETCF_ALWAYS_32_BIT)\r
 334                         return ETCF_ALWAYS_32_BIT;\r
 335                 if (flags & ETCF_OPTIMIZED_FOR_QUALITY)\r
 336                         return ETCF_OPTIMIZED_FOR_QUALITY;\r
 337                 return ETCF_OPTIMIZED_FOR_SPEED;\r
 338         }\r
 339 \r
 340         io::SNamedPath NamedPath;\r
 341         core::dimension2d<u32> OriginalSize;\r
 342         core::dimension2d<u32> Size;\r
 343         E_DRIVER_TYPE DriverType;\r
 344         ECOLOR_FORMAT OriginalColorFormat;\r
 345         ECOLOR_FORMAT ColorFormat;\r
 346         u32 Pitch;\r
 347         bool HasMipMaps;\r
 348         bool IsRenderTarget;\r
 349         E_TEXTURE_SOURCE Source;\r
 350         E_TEXTURE_TYPE Type;\r
 351 };\r
 352 \r
 353 \r
 354 } // end namespace video\r
 355 } // end namespace irr\r
 356 \r
 357 #endif\r
 358 \r