#pragma once #include "BsCorePrerequisites.h" #include "BsGpuResource.h" #include "BsHardwareBuffer.h" #include "BsPixelUtil.h" #include "BsTextureView.h" namespace BansheeEngine { /** * @brief Properties that describe how is the texture used. */ enum TextureUsage { TU_STATIC = GBU_STATIC, /**< A regular texture that is not often or ever updated from the CPU. */ TU_DYNAMIC = GBU_DYNAMIC, /**< A regular texture that is often updated by the CPU. */ TU_RENDERTARGET = 0x200, /**< Texture used for rendering by the GPU. */ TU_DEPTHSTENCIL = 0x400, /**< Texture used as a depth/stencil buffer by the GPU. */ TU_DEFAULT = TU_STATIC }; /** * @brief Different texture types. */ enum TextureType { TEX_TYPE_1D = 1, /**< One dimensional texture. Just a row of pixels. */ TEX_TYPE_2D = 2, /**< Two dimensional texture. */ TEX_TYPE_3D = 3, /**< Three dimensional texture. */ TEX_TYPE_CUBE_MAP = 4 /**< Texture consisting out of six 2D textures describing an inside of a cube. Allows special sampling. */ }; /** * @brief Mipmap options. */ enum TextureMipmap { MIP_UNLIMITED = 0x7FFFFFFF /**< Create all mip maps down to 1x1. */ }; /** * @brief Abstract class representing a texture. Specific render systems have their * own Texture implementations. Internally represented as one or more surfaces * with pixels in a certain number of dimensions, backed by a hardware buffer. * * @note Core thread unless specified otherwise. */ class BS_CORE_EXPORT Texture : public GpuResource { public: /** * @brief Gets the type of texture. * * @note Thread safe. */ virtual TextureType getTextureType() const { return mTextureType; } /** * @brief Gets the number of mipmaps to be used for this texture. This number excludes the top level * map (which is always assumed to be present). * * @note Thread safe. */ virtual UINT32 getNumMipmaps() const {return mNumMipmaps;} /** * @brief Gets whether this texture will be set up so that on sampling it, * hardware gamma correction is applied. * * @note Thread safe. */ virtual bool isHardwareGammaEnabled() const { return mHwGamma; } /** * @brief Gets the number of samples used for multisampling. * (0 if multisampling is not used). * * @note Thread safe. */ virtual UINT32 getMultisampleCount() const { return mMultisampleCount; } /** * @brief Get a render-system specific hint used for determining * multisampling type. * * @note Thread safe. */ virtual const String& getMultisampleHint() const { return mMultisampleHint; } /** * @brief Returns the height of the texture. * * @note Thread safe. */ virtual UINT32 getHeight() const { return mHeight; } /** * @brief Returns the width of the texture. * * @note Thread safe. */ virtual UINT32 getWidth() const { return mWidth; } /** * @brief Returns the depth of the texture (only applicable for 3D textures). * * @note Thread safe. */ virtual UINT32 getDepth() const { return mDepth; } /** * @brief Returns texture usage (TextureUsage) of this texture. * * @note Thread safe. */ virtual int getUsage() const { return mUsage; } /** * @brief Returns the pixel format for the texture surface. * * @note Thread safe. */ virtual PixelFormat getFormat() const { return mFormat; } /** * @brief Returns true if the texture has an alpha layer. * * @note Thread safe. */ virtual bool hasAlpha() const; /** * @brief Return the number of faces this texture has. * * @note Thread safe. */ virtual UINT32 getNumFaces() const; /** * @copydoc GpuResource::writeSubresource */ virtual void writeSubresource(UINT32 subresourceIdx, const GpuResourceData& data, bool discardEntireBuffer); /** * @copydoc GpuResource::readSubresource */ virtual void readSubresource(UINT32 subresourceIdx, GpuResourceData& data); /** * @brief Allocates a buffer you may use for storage when reading or writing a sub-resource. You * need to allocate such a buffer if you are calling "readSubresource". * * You can retrieve a sub-resource index by calling "mapToSubresourceIdx". * * @note Thread safe. */ PixelDataPtr allocateSubresourceBuffer(UINT32 subresourceIdx) const; /** * @brief Maps a sub-resource index to an exact face and mip level. Sub-resource indexes * are used when reading or writing to the resource. * * @note Sub-resource index is only valid for the instance it was created on. You cannot use a sub-resource * index from a different texture and expect to get valid result. Modifying the resource so the number * of sub-resources changes invalidates all sub-resource indexes. * * Thread safe. */ void mapFromSubresourceIdx(UINT32 subresourceIdx, UINT32& face, UINT32& mip) const; /** * @brief Map a face and a mip level to a sub-resource index you can use for updating or reading * a specific sub-resource. * * @note Generated sub-resource index is only valid for the instance it was created on. Modifying the resource so the number * of sub-resources changes, invalidates all sub-resource indexes. * * Thread safe. */ UINT32 mapToSubresourceIdx(UINT32 face, UINT32 mip) const; /** * @brief Locks the buffer for reading or writing. * * @param options Options for controlling what you may do with the locked data. * @param mipLevel (optional) Mipmap level to lock. * @param face (optional) Texture face to lock. * * @return Pointer to the buffer data. Only valid until you call unlock. * * @note If you are just reading or writing one block of data use * readData/writeData methods as they can be much faster in certain situations. * * Core thread only. */ PixelData lock(GpuLockOptions options, UINT32 mipLevel = 0, UINT32 face = 0); /** * @brief Unlocks a previously locked buffer. After the buffer is unlocked, * any data returned by lock becomes invalid. * * @note Core thread only. */ void unlock(); /** * @brief Copies the contents of this texture to another texture. Texture format * and size must match. * * @note Core thread only. */ void copy(TexturePtr& target); /** * @brief Reads data from the texture buffer into the provided buffer. * * @param dest Previously allocated buffer to read data into. * @param mipLevel (optional) Mipmap level to read from. * @param face (optional) Texture face to read from. * * @note Core thread only. */ virtual void readData(PixelData& dest, UINT32 mipLevel = 0, UINT32 face = 0) = 0; /** * @brief Writes data from the provided buffer into the texture buffer. * * @param dest Buffer to retrieve the data from. * @param mipLevel (optional) Mipmap level to write into. * @param face (optional) Texture face to write into. * @param discardWholeBuffer (optional) If true any existing texture data will be discard. This can * improve performance of the write operation. * * @note Core thread only. */ virtual void writeData(const PixelData& src, UINT32 mipLevel = 0, UINT32 face = 0, bool discardWholeBuffer = false) = 0; /** * @brief Returns a dummy 2x2 texture. Don't modify the returned texture. * * @note Thread safe. */ static const HTexture& dummy(); /** * @brief Returns true if the texture can be bound to a shader. * * @note This is only false for some rare special cases. (e.g. AA render texture in DX9) * Internal method. */ virtual bool isBindableAsShaderResource() const { return true; } /************************************************************************/ /* TEXTURE VIEW */ /************************************************************************/ /** * @brief Requests a texture view for the specified mip and array ranges. Returns an existing view of one for * the specified ranges already exists, otherwise creates a new one. You must release all views * by calling "releaseView" when done. */ static TextureViewPtr requestView(TexturePtr texture, UINT32 mostDetailMip, UINT32 numMips, UINT32 firstArraySlice, UINT32 numArraySlices, GpuViewUsage usage); /** * @brief Releases the view. View won't actually get destroyed until all references to it are released. */ static void releaseView(TextureViewPtr view); /************************************************************************/ /* STATICS */ /************************************************************************/ /** * @brief Creates a new empty texture. * * @param texType Type of the texture. * @param width Width of the texture in pixels. * @param height Height of the texture in pixels. * @param depth Depth of the texture in pixels (Must be 1 for 2D textures). * @param numMips Number of mip-maps the texture has. This number excludes the full resolution map. * @param format Format of the pixels. * @param usage Describes how we plan on using the texture in the pipeline. * @param hwGammaCorrection If true the texture data is assumed to have been gamma corrected and will be * converted back to linear space when sampled on GPU. * @param multisampleCount If higher than 1, texture containing multiple samples per pixel is created. * @param multisampleHint Hint about what kind of multisampling to use. Render system specific. */ static HTexture create(TextureType texType, UINT32 width, UINT32 height, UINT32 depth, int numMips, PixelFormat format, int usage = TU_DEFAULT, bool hwGammaCorrection = false, UINT32 multisampleCount = 0, const String& multisampleHint = StringUtil::BLANK); /** * @brief Creates a new empty texture. * * @param texType Type of the texture. * @param width Width of the texture in pixels. * @param height Height of the texture in pixels. * @param numMips Number of mip-maps the texture has. This number excludes the full resolution map. * @param format Format of the pixels. * @param usage Describes how we plan on using the texture in the pipeline. * @param hwGammaCorrection If true the texture data is assumed to have been gamma corrected and will be * converted back to linear space when sampled on GPU. * @param multisampleCount If higher than 1, texture containing multiple samples per pixel is created. * @param multisampleHint Hint about what kind of multisampling to use. Render system specific. */ static HTexture create(TextureType texType, UINT32 width, UINT32 height, int numMips, PixelFormat format, int usage = TU_DEFAULT, bool hwGammaCorrection = false, UINT32 multisampleCount = 0, const String& multisampleHint = StringUtil::BLANK); /** * @copydoc create * * @note Internal method. Creates a texture pointer without a handle. Use "create" for normal usage. */ static TexturePtr _createPtr(TextureType texType, UINT32 width, UINT32 height, UINT32 depth, int num_mips, PixelFormat format, int usage = TU_DEFAULT, bool hwGammaCorrection = false, UINT32 multisampleCount = 0, const String& multisampleHint = StringUtil::BLANK); /** * @copydoc create * * @note Internal method. Creates a texture pointer without a handle. Use "create" for normal usage. */ static TexturePtr _createPtr(TextureType texType, UINT32 width, UINT32 height, int num_mips, PixelFormat format, int usage = TU_DEFAULT, bool hwGammaCorrection = false, UINT32 multisampleCount = 0, const String& multisampleHint = StringUtil::BLANK); protected: /************************************************************************/ /* TEXTURE VIEW */ /************************************************************************/ /** * @brief Creates a new empty/undefined texture view. */ virtual TextureViewPtr createView(); /** * @brief Releases all internal texture view references. Views won't get destroyed if there are external references still held. */ void clearBufferViews(); /** * @brief Holds a single texture view with a usage reference count. */ struct TextureViewReference { TextureViewReference(TextureViewPtr _view) :view(_view), refCount(0) { } TextureViewPtr view; UINT32 refCount; }; UnorderedMap mTextureViews; protected: friend class TextureManager; Texture(); /** * @copydoc GpuResource::initialize */ void initialize(TextureType textureType, UINT32 width, UINT32 height, UINT32 depth, UINT32 numMipmaps, PixelFormat format, int usage, bool hwGamma, UINT32 multisampleCount, const String& multisampleHint); /** * @copydoc lock */ virtual PixelData lockImpl(GpuLockOptions options, UINT32 mipLevel = 0, UINT32 face = 0) = 0; /** * @copydoc unlock */ virtual void unlockImpl() = 0; /** * @copydoc copy */ virtual void copyImpl(TexturePtr& target) = 0; /** * @copydoc Resource::calculateSize */ UINT32 calculateSize() const; protected: UINT32 mHeight; // Immutable UINT32 mWidth; // Immutable UINT32 mDepth; // Immutable UINT32 mNumMipmaps; // Immutable bool mHwGamma; // Immutable UINT32 mMultisampleCount; // Immutable String mMultisampleHint; // Immutable TextureType mTextureType; // Immutable PixelFormat mFormat; // Immutable int mUsage; // Immutable /************************************************************************/ /* SERIALIZATION */ /************************************************************************/ public: friend class TextureRTTI; static RTTITypeBase* getRTTIStatic(); virtual RTTITypeBase* getRTTI() const; }; }