GPUUploadManager: implement texture upload support in Direct3D11

Author: TheMostDiligent

Graphics/GraphicsTools/include/GPUUploadManagerImpl.hpp

@@ -35,11 +35,12 @@
 #include "RefCntAutoPtr.hpp"
 #include "MPSCQueue.hpp"
 #include "ThreadSignal.hpp"
+#include "DynamicAtlasManager.hpp"
 
 #include <memory>
 #include <vector>
-#include <array>
 #include <mutex>
+#include <shared_mutex>
 #include <map>
 #include <unordered_map>
 #include <variant>
@@ -64,14 +65,23 @@ class GPUUploadManagerImpl final : public ObjectBase<IGPUUploadManager>
 
     virtual void DILIGENT_CALL_TYPE ScheduleTextureUpdate(const ScheduleTextureUpdateInfo& UpdateInfo) override final;
 
-    virtual void DILIGENT_CALL_TYPE GetStats(GPUUploadManagerStats& Stats) const override final;
+    virtual void DILIGENT_CALL_TYPE GetStats(GPUUploadManagerStats& Stats) override final;
 
+private:
+    class UploadStream;
+
+public:
     class Page
     {
     public:
         explicit Page(Uint32 Size, bool PersistentMapped = false) noexcept;
 
-        Page(size_t StreamIndex, IRenderDevice* pDevice, Uint32 Size);
+        Page(UploadStream& Stream, IRenderDevice* pDevice, Uint32 Size);
+
+        // Special page for texture updates in Direct3D11, which require a staging texture.
+        // The texture dimensions are Size x Size.
+        Page(UploadStream& Stream, IRenderDevice* pDevice, Uint32 Size, TEXTURE_FORMAT Format);
+
         ~Page();
 
         enum class WritingStatus
@@ -143,7 +153,7 @@ class GPUUploadManagerImpl final : public ObjectBase<IGPUUploadManager>
         // Returns true if the page was not previously enqueued, false otherwise.
         bool TryEnqueue();
 
-        size_t GetStreamIndex() const { return m_StreamIdx; }
+        UploadStream* GetStream() const { return m_pStream; }
 
         Uint64 GetFenceValue() const { return m_FenceValue; }
         Uint32 GetSize() const { return m_Size; }
@@ -179,13 +189,40 @@ class GPUUploadManagerImpl final : public ObjectBase<IGPUUploadManager>
 
         WritingStatus EndWriting();
 
+        void UnmapStagingResource(IDeviceContext* pContext);
+
     private:
-        const size_t m_StreamIdx        = 0;
+        UploadStream* const m_pStream = nullptr;
+
         const Uint32 m_Size             = 0;
         const bool   m_PersistentMapped = false;
 
         RefCntAutoPtr<IBuffer> m_pStagingBuffer;
 
+        // Direct3D11 does not support buffer to texture copies, so we need a
+        // staging texture to perform texture updates.
+        struct StagingTextureAtlas
+        {
+            StagingTextureAtlas(IRenderDevice* pDevice, Uint32 Width, Uint32 Height, TEXTURE_FORMAT Format, const std::string& Name);
+            ~StagingTextureAtlas();
+
+            void* Map(IDeviceContext* pContext);
+            void  Unmap(IDeviceContext* pContext);
+            void  Reset();
+
+            DynamicAtlasManager::Region Allocate(Uint32 Width, Uint32 Height);
+
+            RefCntAutoPtr<ITexture> pTex;
+
+            Uint32 RowStride   = 0;
+            Uint32 DepthStride = 0;
+
+        private:
+            std::mutex          MgrMtx;
+            DynamicAtlasManager Mgr;
+        };
+        std::unique_ptr<StagingTextureAtlas> m_pStagingAtlas;
+
         void* m_pData = nullptr;
 
         std::atomic<Uint32> m_Offset{0};
@@ -217,11 +254,14 @@ class GPUUploadManagerImpl final : public ObjectBase<IGPUUploadManager>
             PendingBufferOp() noexcept = default;
         };
 
-
         struct PendingTextureOp
         {
             RefCntAutoPtr<ITexture> pDstTexture;
 
+            // For Direct3D11, coordinates of the source region within the staging texture.
+            Uint32 SrcX = 0;
+            Uint32 SrcY = 0;
+
             Uint32 SrcOffset      = 0;
             Uint32 SrcStride      = 0;
             Uint32 SrcDepthStride = 0;
@@ -230,20 +270,21 @@ class GPUUploadManagerImpl final : public ObjectBase<IGPUUploadManager>
             Uint32 DstSlice    = 0;
             Box    DstBox;
 
-            CopyStagingTextureCallbackType CopyTexture      = nullptr;
-            void*                          pCopyTextureData = nullptr;
+            CopyStagingTextureCallbackType      CopyTexture      = nullptr;
+            CopyStagingD3D11TextureCallbackType CopyD3D11Texture = nullptr;
+            void*                               pCopyTextureData = nullptr;
 
             GPUTextureUploadEnqueuedCallbackType UploadEnqueued      = nullptr;
             void*                                pUploadEnqueuedData = nullptr;
         };
 
         using PendingOp = std::variant<PendingBufferOp, PendingTextureOp>;
         MPSCQueue<PendingOp> m_PendingOps;
+
+        static std::atomic<int> sm_PageCounter;
     };
 
 private:
-    class UploadStream;
-
     void ReclaimCompletedPages(IDeviceContext* pContext);
     void ProcessPendingPages(IDeviceContext* pContext);
 
@@ -285,10 +326,11 @@ class GPUUploadManagerImpl final : public ObjectBase<IGPUUploadManager>
     {
     public:
         UploadStream(GPUUploadManagerImpl& Mgr,
-                     size_t                StreamIdx,
+                     IDeviceContext*       pContext,
                      Uint32                PageSize,
                      Uint32                MaxPageCount,
-                     Uint32                InitialPageCount) noexcept;
+                     Uint32                InitialPageCount,
+                     TEXTURE_FORMAT        Format = TEX_FORMAT_UNKNOWN) noexcept;
 
         Page* CreatePage(IDeviceContext* pContext, Uint32 RequiredSize = 0);
         Page* AcquireFreePage(IDeviceContext* pContext, Uint32 RequiredSize = 0);
@@ -313,9 +355,9 @@ class GPUUploadManagerImpl final : public ObjectBase<IGPUUploadManager>
 
     private:
         GPUUploadManagerImpl& m_Mgr;
-        const size_t          m_StreamIdx;
         const Uint32          m_PageSize;
         const Uint32          m_MaxPageCount;
+        const TEXTURE_FORMAT  m_Format;
 
         std::atomic<Page*> m_pCurrentPage{nullptr};
 
@@ -336,20 +378,48 @@ class GPUUploadManagerImpl final : public ObjectBase<IGPUUploadManager>
         Uint32              m_PeakPageCount              = 0;
     };
 
-    enum class UploadStreamType : Uint32
+    using UploadStreamUniquePtr = std::unique_ptr<UploadStream>;
+    std::vector<UploadStreamUniquePtr> m_Streams;
+
+    UploadStream* m_pNormalStream = nullptr;
+    UploadStream* m_pLargeStream  = nullptr;
+
+    class TextureUploadStreams
     {
-        Normal = 0,
-        Large  = 1,
-        Count
+    public:
+        TextureUploadStreams(GPUUploadManagerImpl& Mgr, Uint32 PageSizeInBytes, Uint32 MaxPageCount) :
+            m_Mgr{Mgr},
+            m_PageSizeInBytes{PageSizeInBytes},
+            m_MaxPageCount{MaxPageCount}
+        {}
+
+        UploadStream* GetStreamForFormat(IDeviceContext* pContext, TEXTURE_FORMAT Format);
+
+        void MoveNewStreamsToManager();
+        void SetStopping();
+
+    private:
+        GPUUploadManagerImpl& m_Mgr;
+        const Uint32          m_PageSizeInBytes;
+        const Uint32          m_MaxPageCount;
+
+        std::shared_mutex                                 m_Mtx;
+        std::unordered_map<TEXTURE_FORMAT, UploadStream*> m_StreamsByFormat;
+
+        // New streams created by worker threads that are not yet added to parent m_Streams vector.
+        std::mutex                                 m_NewStreamsMtx;
+        std::vector<std::unique_ptr<UploadStream>> m_NewStreams;
+        std::atomic<bool>                          m_HasNewStreams{false};
+        std::atomic<bool>                          m_Stopping{false};
     };
-    std::array<UploadStream, static_cast<size_t>(UploadStreamType::Count)> m_Streams;
+    std::unique_ptr<TextureUploadStreams> m_pTextureStreams;
 
     // The number of running ScheduleBufferUpdate operations.
     std::atomic<Uint32> m_NumRunningUpdates{0};
     std::atomic<bool>   m_Stopping{false};
     Threading::Signal   m_LastRunningThreadFinishedSignal;
 
-    mutable std::array<GPUUploadManagerStreamStats, static_cast<size_t>(UploadStreamType::Count)> m_StreamStats;
+    std::vector<GPUUploadManagerStreamStats> m_StreamStats;
 };
 
 } // namespace Diligent

Graphics/GraphicsTools/interface/GPUUploadManager.h

@@ -121,7 +121,7 @@ typedef void (*GPUBufferUploadEnqueuedCallbackType)(IBuffer* pDstBuffer,
 /// The callback is expected to perform the copy operation itself, using the provided parameters, and schedule it for execution on the GPU.
 ///
 /// \param [in] pContext   - Device context to use for scheduling the copy operation.
-/// \param [in] pSrcBuffer - Source buffer containing the data to copy. The buffer is guaranteed to be valid for the duration of the callback.
+/// \param [in] pSrcBuffer - Source buffer containing the data to copy.
 /// \param [in] SrcOffset  - Offset in the source buffer where the data to copy starts.
 /// \param [in] NumBytes   - Number of bytes to copy.
 /// \param [in] pUserData  - User-provided pointer passed to ScheduleBufferUpdate().
@@ -315,7 +315,7 @@ typedef void (*GPUTextureUploadEnqueuedCallbackType)(ITexture*     pDstTexture,
 /// \param [in] DstMipLevel - Destination mip level in the texture where the update will be applied.
 /// \param [in] DstSlice    - Destination array slice in the texture where the update will be applied.
 /// \param [in] DstBox      - Destination box in the texture where the update will be applied.
-/// \param [in] SrcData     - Source data description. The manager is guaranteed to keep the source data valid for the duration of the callback.
+/// \param [in] SrcData     - Source data description.
 /// \param [in] pUserData   - User-provided pointer passed to ScheduleTextureUpdate().
 ///
 /// If the copy operation was not scheduled by the time the manager is destroyed,
@@ -340,6 +340,28 @@ typedef void (*CopyStagingTextureCallbackType)(IDeviceContext*             pCont
                                                void*                       pUserData);
 
 
+/// Direct3D11-specific callback function type for copying texture data.
+/// This callback is invoked on the render thread when the manager needs to perform the copy operation for a texture update.
+/// The callback is expected to perform the copy operation itself, using the provided parameters, and schedule it for execution on the GPU.
+///
+/// \param [in] pContext    - Device context to use for scheduling the copy operation.
+/// \param [in] DstMipLevel - Destination mip level in the texture where the update will be applied.
+/// \param [in] DstSlice    - Destination array slice in the texture where the update will be applied.
+/// \param [in] DstBox      - Destination box in the texture where the update will be applied.
+/// \param [in] pSrcTexture - Pointer to the staging texture containing the source data.
+/// \param [in] SrcX        - X offset in the staging texture where the source data starts.
+/// \param [in] SrcY        - Y offset in the staging texture where the source data starts.
+/// \param [in] pUserData   - User-provided pointer passed to ScheduleTextureUpdate().
+typedef void (*CopyStagingD3D11TextureCallbackType)(IDeviceContext* pContext,
+                                                    Uint32          DstMipLevel,
+                                                    Uint32          DstSlice,
+                                                    const Box REF   DstBox,
+                                                    ITexture*       pSrcTexture,
+                                                    Uint32          SrcX,
+                                                    Uint32          SrcY,
+                                                    void*           pUserData);
+
+
 /// Structure describing a texture update operation to be scheduled by IGPUUploadManager::ScheduleTextureUpdate().
 struct ScheduleTextureUpdateInfo
 {
@@ -391,8 +413,16 @@ struct ScheduleTextureUpdateInfo
     /// from the source data to the destination texture using its internal staging buffer and copy command.
     /// If the callback is provided, it must perform the copy operation itself. The manager will pass the
     /// necessary parameters to the callback.
+    ///
+    /// \note   This callback is used on all graphics backends, except Direct3D11 because it does not support copying from a
+    ///         buffer to a texture. For Direct3D11, the CopyD3D11Texture callback is used instead, which provides a pointer
+    ///         to the staging texture
     CopyStagingTextureCallbackType CopyTexture DEFAULT_INITIALIZER(nullptr);
 
+    /// Optional Direct3D11-specific callback to perform the copy operation.
+    /// This callback is only called for Direct3D11 backend.
+    CopyStagingD3D11TextureCallbackType CopyD3D11Texture DEFAULT_INITIALIZER(nullptr);
+
     /// Optional pointer to user data that will be passed to the CopyTexture callback.
     void* pCopyTextureData DEFAULT_INITIALIZER(nullptr);
 
@@ -412,6 +442,8 @@ typedef struct ScheduleTextureUpdateInfo ScheduleTextureUpdateInfo;
 struct GPUUploadManagerBucketInfo
 {
     /// Page size in bytes.
+    /// For Direct3D11 texture upload stream, this is the upload texture size (width and height).
+    /// Otherwise, this is the size of the upload page in bytes.
     Uint32 PageSize DEFAULT_INITIALIZER(0);
 
     /// Number of pages currently in the manager.
@@ -423,7 +455,12 @@ typedef struct GPUUploadManagerBucketInfo GPUUploadManagerBucketInfo;
 /// GPU upload manager stream statistics.
 struct GPUUploadManagerStreamStats
 {
+    /// For Direct3D11 only: texture format for texture upload stream.
+    TEXTURE_FORMAT Format DEFAULT_INITIALIZER(TEX_FORMAT_UNKNOWN);
+
     /// Page size in bytes for this stream.
+    /// If Format is not TEX_FORMAT_UNKNOWN, this is the upload texture size (width and height).
+    /// Otherwise, this is the size of the upload page in bytes.
     Uint32 PageSize DEFAULT_INITIALIZER(0);
 
     /// The number of pages in the manager.
@@ -529,7 +566,7 @@ DILIGENT_BEGIN_INTERFACE(IGPUUploadManager, IObject)
     /// Pointers returned in the Stats structure are valid only until the next call to GetStats()
     /// and must not be used after that.
     VIRTUAL void METHOD(GetStats)(THIS_
-                                  GPUUploadManagerStats REF Stats) CONST PURE;
+                                  GPUUploadManagerStats REF Stats) PURE;
 };
 DILIGENT_END_INTERFACE