path: root/Graphics/GraphicsEngine/interface/Texture.h

/*
 *  Copyright 2019-2021 Diligent Graphics LLC
 *  Copyright 2015-2019 Egor Yusov
 *  
 *  Licensed under the Apache License, Version 2.0 (the "License");
 *  you may not use this file except in compliance with the License.
 *  You may obtain a copy of the License at
 *  
 *      http://www.apache.org/licenses/LICENSE-2.0
 *  
 *  Unless required by applicable law or agreed to in writing, software
 *  distributed under the License is distributed on an "AS IS" BASIS,
 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 *  See the License for the specific language governing permissions and
 *  limitations under the License.
 *
 *  In no event and under no legal theory, whether in tort (including negligence), 
 *  contract, or otherwise, unless required by applicable law (such as deliberate 
 *  and grossly negligent acts) or agreed to in writing, shall any Contributor be
 *  liable for any damages, including any direct, indirect, special, incidental, 
 *  or consequential damages of any character arising as a result of this License or 
 *  out of the use or inability to use the software (including but not limited to damages 
 *  for loss of goodwill, work stoppage, computer failure or malfunction, or any and 
 *  all other commercial damages or losses), even if such Contributor has been advised 
 *  of the possibility of such damages.
 */

#pragma once

// clang-format off

/// \file
/// Definition of the Diligent::ITexture interface and related data structures

#include "GraphicsTypes.h"
#include "DeviceObject.h"
#include "TextureView.h"

DILIGENT_BEGIN_NAMESPACE(Diligent)


// {A64B0E60-1B5E-4CFD-B880-663A1ADCBE98}
static const INTERFACE_ID IID_Texture =
    {0xa64b0e60, 0x1b5e, 0x4cfd,{0xb8, 0x80, 0x66, 0x3a, 0x1a, 0xdc, 0xbe, 0x98}};

/// Texture description
struct TextureDesc DILIGENT_DERIVE(DeviceObjectAttribs)

    /// Texture type. See Diligent::RESOURCE_DIMENSION for details.
    RESOURCE_DIMENSION Type DEFAULT_INITIALIZER(RESOURCE_DIM_UNDEFINED);

    /// Texture width, in pixels.
    Uint32 Width            DEFAULT_INITIALIZER(0);

    /// Texture height, in pixels.
    Uint32 Height           DEFAULT_INITIALIZER(0);

    union
    {
        /// For a 1D array or 2D array, number of array slices
        Uint32 ArraySize    DEFAULT_INITIALIZER(1);

        /// For a 3D texture, number of depth slices
        Uint32 Depth;
    };

    /// Texture format, see Diligent::TEXTURE_FORMAT.
    TEXTURE_FORMAT Format       DEFAULT_INITIALIZER(TEX_FORMAT_UNKNOWN);

    /// Number of Mip levels in the texture. Multisampled textures can only have 1 Mip level.
    /// Specify 0 to create full mipmap chain.
    Uint32          MipLevels   DEFAULT_INITIALIZER(1);

    /// Number of samples.\n
    /// Only 2D textures or 2D texture arrays can be multisampled.
    Uint32          SampleCount DEFAULT_INITIALIZER(1);

    /// Texture usage. See Diligent::USAGE for details.
    USAGE           Usage       DEFAULT_INITIALIZER(USAGE_DEFAULT);

    /// Bind flags, see Diligent::BIND_FLAGS for details. \n
    /// The following bind flags are allowed:
    /// Diligent::BIND_SHADER_RESOURCE, Diligent::BIND_RENDER_TARGET, Diligent::BIND_DEPTH_STENCIL,
    /// Diligent::and BIND_UNORDERED_ACCESS. \n
    /// Multisampled textures cannot have Diligent::BIND_UNORDERED_ACCESS flag set
    BIND_FLAGS      BindFlags   DEFAULT_INITIALIZER(BIND_NONE);

    /// CPU access flags or 0 if no CPU access is allowed, 
    /// see Diligent::CPU_ACCESS_FLAGS for details.
    CPU_ACCESS_FLAGS CPUAccessFlags     DEFAULT_INITIALIZER(CPU_ACCESS_NONE);
    
    /// Miscellaneous flags, see Diligent::MISC_TEXTURE_FLAGS for details.
    MISC_TEXTURE_FLAGS MiscFlags        DEFAULT_INITIALIZER(MISC_TEXTURE_FLAG_NONE);
    
    /// Optimized clear value
    OptimizedClearValue ClearValue;

    /// Defines which command queues this texture can be used with
    Uint64 CommandQueueMask              DEFAULT_INITIALIZER(1);


#if DILIGENT_CPP_INTERFACE
    TextureDesc()noexcept{}

    TextureDesc(RESOURCE_DIMENSION  _Type, 
                Uint32              _Width,
                Uint32              _Height,
                Uint32              _ArraySizeOrDepth,
                TEXTURE_FORMAT      _Format,
                Uint32              _MipLevels        = TextureDesc{}.MipLevels,
                Uint32              _SampleCount      = TextureDesc{}.SampleCount,
                USAGE               _Usage            = TextureDesc{}.Usage,
                BIND_FLAGS          _BindFlags        = TextureDesc{}.BindFlags,
                CPU_ACCESS_FLAGS    _CPUAccessFlags   = TextureDesc{}.CPUAccessFlags,
                MISC_TEXTURE_FLAGS  _MiscFlags        = TextureDesc{}.MiscFlags,
                OptimizedClearValue _ClearValue       = TextureDesc{}.ClearValue,
                Uint64              _CommandQueueMask = TextureDesc{}.CommandQueueMask) : 
        Type             {_Type            }, 
        Width            {_Width           },
        Height           {_Height          },
        ArraySize        {_ArraySizeOrDepth},
        Format           {_Format          },
        MipLevels        {_MipLevels       },
        SampleCount      {_SampleCount     },
        Usage            {_Usage           },
        BindFlags        {_BindFlags       },
        CPUAccessFlags   {_CPUAccessFlags  },
        MiscFlags        {_MiscFlags       },
        ClearValue       {_ClearValue      },
        CommandQueueMask {_CommandQueueMask}
    {}

    /// Tests if two structures are equivalent

    /// \param [in] RHS - reference to the structure to perform comparison with
    /// \return 
    /// - True if all members of the two structures except for the Name are equal.
    /// - False otherwise.
    /// The operator ignores DeviceObjectAttribs::Name field as it does not affect 
    /// the texture description state.
    bool operator ==(const TextureDesc& RHS)const
    {
                // Name is primarily used for debug purposes and does not affect the state.
                // It is ignored in comparison operation.
        return  // strcmp(Name, RHS.Name) == 0          &&
                Type             == RHS.Type           &&
                Width            == RHS.Width          &&
                Height           == RHS.Height         &&
                ArraySize        == RHS.ArraySize      &&
                Format           == RHS.Format         &&
                MipLevels        == RHS.MipLevels      &&
                SampleCount      == RHS.SampleCount    &&
                Usage            == RHS.Usage          &&
                BindFlags        == RHS.BindFlags      &&
                CPUAccessFlags   == RHS.CPUAccessFlags &&
                MiscFlags        == RHS.MiscFlags      &&
                ClearValue       == RHS.ClearValue     &&
                CommandQueueMask == RHS.CommandQueueMask;
    }
#endif
};
typedef struct TextureDesc TextureDesc;

/// Describes data for one subresource
struct TextureSubResData
{
    /// Pointer to the subresource data in CPU memory.
    /// If provided, pSrcBuffer must be null
    const void* pData           DEFAULT_INITIALIZER(nullptr);

    /// Pointer to the GPU buffer that contains subresource data.
    /// If provided, pData must be null
    struct IBuffer* pSrcBuffer   DEFAULT_INITIALIZER(nullptr);

    /// When updating data from the buffer (pSrcBuffer is not null),
    /// offset from the beginning of the buffer to the data start
    Uint32 SrcOffset            DEFAULT_INITIALIZER(0);

    /// For 2D and 3D textures, row stride in bytes
    Uint32 Stride               DEFAULT_INITIALIZER(0);

    /// For 3D textures, depth slice stride in bytes
    /// \note On OpenGL, this must be a mutliple of Stride
    Uint32 DepthStride          DEFAULT_INITIALIZER(0);


#if DILIGENT_CPP_INTERFACE
    /// Initializes the structure members with default values

    /// Default values:
    /// Member          | Default value
    /// ----------------|--------------
    /// pData           | nullptr
    /// SrcOffset       | 0
    /// Stride          | 0
    /// DepthStride     | 0
    TextureSubResData()noexcept{}
    
    /// Initializes the structure members to perform copy from the CPU memory
    TextureSubResData(const void* _pData, Uint32 _Stride, Uint32 _DepthStride = 0)noexcept :
        pData       (_pData),
        pSrcBuffer  (nullptr),
        SrcOffset   (0),
        Stride      (_Stride),
        DepthStride (_DepthStride)
    {}

    /// Initializes the structure members to perform copy from the GPU buffer
    TextureSubResData(IBuffer* _pBuffer, Uint32 _SrcOffset, Uint32 _Stride, Uint32 _DepthStride = 0)noexcept :
        pData       {nullptr     },
        pSrcBuffer  {_pBuffer    },
        SrcOffset   {_SrcOffset  },
        Stride      {_Stride     },
        DepthStride {_DepthStride}
    {}
#endif
};
typedef struct TextureSubResData TextureSubResData;

/// Describes the initial data to store in the texture
struct TextureData
{
    /// Pointer to the array of the TextureSubResData elements containing
    /// information about each subresource.
    TextureSubResData* pSubResources    DEFAULT_INITIALIZER(nullptr);

    /// Number of elements in pSubResources array.
    /// NumSubresources must exactly match the number
    /// of subresources in the texture. Otherwise an error
    /// occurs.
    Uint32             NumSubresources  DEFAULT_INITIALIZER(0);

#if DILIGENT_CPP_INTERFACE
    TextureData() noexcept {}

    TextureData(TextureSubResData* _pSubResources,
                Uint32             _NumSubresources) noexcept :
        pSubResources   {_pSubResources  },
        NumSubresources {_NumSubresources}
    {}
#endif
};
typedef struct TextureData TextureData;

struct MappedTextureSubresource
{
    PVoid  pData       DEFAULT_INITIALIZER(nullptr);
    Uint32 Stride      DEFAULT_INITIALIZER(0);
    Uint32 DepthStride DEFAULT_INITIALIZER(0);

#if DILIGENT_CPP_INTERFACE
    MappedTextureSubresource() noexcept {}

    MappedTextureSubresource(PVoid  _pData,
                             Uint32 _Stride,
                             Uint32 _DepthStride = 0) noexcept :
        pData       {_pData      },
        Stride      {_Stride     },
        DepthStride {_DepthStride}
    {}
#endif
};
typedef struct MappedTextureSubresource MappedTextureSubresource;

#define DILIGENT_INTERFACE_NAME ITexture
#include "../../../Primitives/interface/DefineInterfaceHelperMacros.h"

#define ITextureInclusiveMethods   \
    IDeviceObjectInclusiveMethods; \
    ITextureMethods Texture

/// Texture inteface
DILIGENT_BEGIN_INTERFACE(ITexture, IDeviceObject)
{
#if DILIGENT_CPP_INTERFACE
    /// Returns the texture description used to create the object
    virtual const TextureDesc& METHOD(GetDesc)()const override = 0;
#endif

    /// Creates a new texture view

    /// \param [in] ViewDesc - View description. See Diligent::TextureViewDesc for details.
    /// \param [out] ppView - Address of the memory location where the pointer to the view interface will be written to.
    /// 
    /// \remarks To create a shader resource view addressing the entire texture, set only TextureViewDesc::ViewType 
    ///          member of the ViewDesc parameter to Diligent::TEXTURE_VIEW_SHADER_RESOURCE and leave all other 
    ///          members in their default values. Using the same method, you can create render target or depth stencil
    ///          view addressing the largest mip level.\n
    ///          If texture view format is Diligent::TEX_FORMAT_UNKNOWN, the view format will match the texture format.\n
    ///          If texture view type is Diligent::TEXTURE_VIEW_UNDEFINED, the type will match the texture type.\n
    ///          If the number of mip levels is 0, and the view type is shader resource, the view will address all mip levels.
    ///          For other view types it will address one mip level.\n
    ///          If the number of slices is 0, all slices from FirstArraySlice or FirstDepthSlice will be referenced by the view.
    ///          For non-array textures, the only allowed values for the number of slices are 0 and 1.\n
    ///          Texture view will contain strong reference to the texture, so the texture will not be destroyed
    ///          until all views are released.\n
    ///          The function calls AddRef() for the created interface, so it must be released by
    ///          a call to Release() when it is no longer needed.
    VIRTUAL void METHOD(CreateView)(THIS_
                                    const TextureViewDesc REF ViewDesc,
                                    ITextureView**            ppView) PURE;

    /// Returns the pointer to the default view.
    
    /// \param [in] ViewType - Type of the requested view. See Diligent::TEXTURE_VIEW_TYPE.
    /// \return Pointer to the interface
    ///
    /// \note The function does not increase the reference counter for the returned interface, so
    ///       Release() must *NOT* be called.
    VIRTUAL ITextureView* METHOD(GetDefaultView)(THIS_
                                                 TEXTURE_VIEW_TYPE ViewType) PURE;


    /// Returns native texture handle specific to the underlying graphics API

    /// \return pointer to ID3D11Resource interface, for D3D11 implementation\n
    ///         pointer to ID3D12Resource interface, for D3D12 implementation\n
    ///         GL buffer handle, for GL implementation
    VIRTUAL void* METHOD(GetNativeHandle)(THIS) PURE;

    /// Sets the usage state for all texture subresources.

    /// \note This method does not perform state transition, but
    ///       resets the internal texture state to the given value.
    ///       This method should be used after the application finished
    ///       manually managing the texture state and wants to hand over
    ///       state management back to the engine.
    VIRTUAL void METHOD(SetState)(THIS_
                                  RESOURCE_STATE State) PURE;

    /// Returns the internal texture state
    VIRTUAL RESOURCE_STATE METHOD(GetState)(THIS) CONST PURE;
};
DILIGENT_END_INTERFACE

#include "../../../Primitives/interface/UndefInterfaceHelperMacros.h"

#if DILIGENT_C_INTERFACE

// clang-format off

#    define ITexture_GetDesc(This) (const struct TextureDesc*)IDeviceObject_GetDesc(This)

#    define ITexture_CreateView(This, ...)     CALL_IFACE_METHOD(Texture, CreateView,      This, __VA_ARGS__)
#    define ITexture_GetDefaultView(This, ...) CALL_IFACE_METHOD(Texture, GetDefaultView,  This, __VA_ARGS__)
#    define ITexture_GetNativeHandle(This)     CALL_IFACE_METHOD(Texture, GetNativeHandle, This)
#    define ITexture_SetState(This, ...)       CALL_IFACE_METHOD(Texture, SetState,        This, __VA_ARGS__)
#    define ITexture_GetState(This)            CALL_IFACE_METHOD(Texture, GetState,        This)

// clang-format on

#endif

DILIGENT_END_NAMESPACE // namespace Diligent