GPUUploadManager: add destination buffer/texture state transition mode parameter

TheMostDiligent · TheMostDiligent · commit 3ac224518897 · 2026-04-03T12:29:03.000-07:00
diff --git a/Graphics/GraphicsTools/include/GPUUploadManagerImpl.hpp b/Graphics/GraphicsTools/include/GPUUploadManagerImpl.hpp
@@ -248,6 +248,8 @@ class GPUUploadManagerImpl final : public ObjectBase<IGPUUploadManager>
             GPUBufferUploadEnqueuedCallbackType UploadEnqueued      = nullptr;
             void*                               pUploadEnqueuedData = nullptr;
 
+            RESOURCE_STATE_TRANSITION_MODE DstBufferTransitionMode = RESOURCE_STATE_TRANSITION_MODE_NONE;
+
             Uint32 SrcOffset = 0;
             Uint32 DstOffset = 0;
             Uint32 NumBytes  = 0;
@@ -259,6 +261,8 @@ class GPUUploadManagerImpl final : public ObjectBase<IGPUUploadManager>
         {
             RefCntAutoPtr<ITexture> pDstTexture;
 
+            RESOURCE_STATE_TRANSITION_MODE DstTextureTransitionMode = RESOURCE_STATE_TRANSITION_MODE_NONE;
+
             // For Direct3D11, coordinates of the source region within the staging texture.
             Uint32 SrcX = 0;
             Uint32 SrcY = 0;
@@ -282,7 +286,7 @@ class GPUUploadManagerImpl final : public ObjectBase<IGPUUploadManager>
         using PendingOp = std::variant<PendingBufferOp, PendingTextureOp>;
         MPSCQueue<PendingOp> m_PendingOps;
 
-        static std::atomic<int> sm_PageCounter;
+        static std::atomic<Uint32> sm_PageCounter;
     };
 
 private:
diff --git a/Graphics/GraphicsTools/interface/GPUUploadManager.h b/Graphics/GraphicsTools/interface/GPUUploadManager.h
@@ -161,6 +161,10 @@ struct ScheduleBufferUpdateInfo
     /// Otherwise, this buffer will be used as the destination for the copy operation
     IBuffer* pDstBuffer DEFAULT_INITIALIZER(nullptr);
 
+    /// State transition mode for the destination buffer. This parameter is ignored if CopyBuffer callback is provided,
+    /// and the callback is expected to perform any necessary state transitions itself.
+    RESOURCE_STATE_TRANSITION_MODE DstBufferTransitionMode DEFAULT_INITIALIZER(RESOURCE_STATE_TRANSITION_MODE_TRANSITION);
+
     /// Offset in the destination buffer where the update will be applied.
     /// If CopyBuffer callback is provided, this parameter will be ignored, and the callback must
     /// perform the copy operation itself.
@@ -375,6 +379,10 @@ struct ScheduleTextureUpdateInfo
     /// Otherwise, this texture will be used as the destination for the copy operation
     ITexture* pDstTexture DEFAULT_INITIALIZER(nullptr);
 
+    /// State transition mode for the destination texture. This parameter is ignored if CopyTexture/CopyD3D11Texture callback is provided,
+    /// and the callback is expected to perform any necessary state transitions itself.
+    RESOURCE_STATE_TRANSITION_MODE DstTextureTransitionMode DEFAULT_INITIALIZER(RESOURCE_STATE_TRANSITION_MODE_TRANSITION);
+
     /// Destination mip level in the texture where the update will be applied.
     /// This parameter is ignored if CopyTexture callback is provided.
     Uint32 DstMipLevel DEFAULT_INITIALIZER(0);
diff --git a/Graphics/GraphicsTools/src/GPUUploadManagerImpl.cpp b/Graphics/GraphicsTools/src/GPUUploadManagerImpl.cpp
@@ -61,7 +61,7 @@ bool GPUUploadManagerImpl::Page::Writer::ScheduleTextureUpdate(const ScheduleTex
 {
     if (m_pPage == nullptr)
     {
-        UNEXPECTED("Attempting to schedule a buffer update with an invalid writer.");
+        UNEXPECTED("Attempting to schedule a texture update with an invalid writer.");
         return false;
     }
 
@@ -114,6 +114,7 @@ GPUUploadManagerImpl::Page::StagingTextureAtlas::~StagingTextureAtlas()
 
 void* GPUUploadManagerImpl::Page::StagingTextureAtlas::Map(IDeviceContext* pContext)
 {
+    pContext->TransitionResourceState({pTex, RESOURCE_STATE_UNKNOWN, RESOURCE_STATE_COPY_SOURCE, STATE_TRANSITION_FLAG_UPDATE_STATE});
     MappedTextureSubresource MappedData;
     pContext->MapTextureSubresource(pTex, 0, 0, MAP_WRITE, MAP_FLAG_NONE, nullptr, MappedData);
     RowStride   = static_cast<Uint32>(MappedData.Stride);
@@ -135,7 +136,7 @@ void GPUUploadManagerImpl::Page::StagingTextureAtlas::Reset()
 
 DynamicAtlasManager::Region GPUUploadManagerImpl::Page::StagingTextureAtlas::Allocate(Uint32 Width, Uint32 Height)
 {
-    std::lock_guard<std::mutex> Lock(MgrMtx);
+    std::lock_guard<std::mutex> Lock{MgrMtx};
     return Mgr.Allocate(Width, Height);
 }
 
@@ -148,10 +149,12 @@ GPUUploadManagerImpl::Page::Page(Uint32 Size, bool PersistentMapped) noexcept :
 inline bool PersistentMapSupported(IRenderDevice* pDevice)
 {
     RENDER_DEVICE_TYPE DeviceType = pDevice->GetDeviceInfo().Type;
-    return DeviceType == RENDER_DEVICE_TYPE_D3D12 || DeviceType == RENDER_DEVICE_TYPE_VULKAN;
+    return (DeviceType == RENDER_DEVICE_TYPE_D3D12 ||
+            DeviceType == RENDER_DEVICE_TYPE_VULKAN ||
+            DeviceType == RENDER_DEVICE_TYPE_METAL);
 }
 
-std::atomic<int> GPUUploadManagerImpl::Page::sm_PageCounter{0};
+std::atomic<Uint32> GPUUploadManagerImpl::Page::sm_PageCounter{0};
 
 GPUUploadManagerImpl::Page::Page(UploadStream& Stream, IRenderDevice* pDevice, Uint32 Size) :
     m_pStream{&Stream},
@@ -354,9 +357,10 @@ bool GPUUploadManagerImpl::Page::ScheduleBufferUpdate(const ScheduleBufferUpdate
     }
 
     PendingBufferOp Op;
-    Op.pDstBuffer      = UpdateInfo.pDstBuffer;
-    Op.CopyBuffer      = UpdateInfo.CopyBuffer;
-    Op.pCopyBufferData = UpdateInfo.pCopyBufferData;
+    Op.pDstBuffer              = UpdateInfo.pDstBuffer;
+    Op.DstBufferTransitionMode = UpdateInfo.DstBufferTransitionMode;
+    Op.CopyBuffer              = UpdateInfo.CopyBuffer;
+    Op.pCopyBufferData         = UpdateInfo.pCopyBufferData;
     if (Op.CopyBuffer == nullptr)
     {
         Op.UploadEnqueued      = UpdateInfo.UploadEnqueued;
@@ -456,7 +460,8 @@ bool GPUUploadManagerImpl::Page::ScheduleTextureUpdate(const ScheduleTextureUpda
     }
 
     PendingTextureOp Op;
-    Op.pDstTexture = UpdateInfo.pDstTexture;
+    Op.pDstTexture              = UpdateInfo.pDstTexture;
+    Op.DstTextureTransitionMode = UpdateInfo.DstTextureTransitionMode;
     if (m_pStagingBuffer)
     {
         Op.CopyTexture = UpdateInfo.CopyTexture;
@@ -523,8 +528,8 @@ void GPUUploadManagerImpl::Page::ExecutePendingOps(IDeviceContext* pContext, Uin
             {
                 if (pContext != nullptr && BuffOp.pDstBuffer != nullptr && BuffOp.NumBytes > 0)
                 {
-                    pContext->CopyBuffer(m_pStagingBuffer, BuffOp.SrcOffset, RESOURCE_STATE_TRANSITION_MODE_TRANSITION,
-                                         BuffOp.pDstBuffer, BuffOp.DstOffset, BuffOp.NumBytes, RESOURCE_STATE_TRANSITION_MODE_TRANSITION);
+                    pContext->CopyBuffer(m_pStagingBuffer, BuffOp.SrcOffset, RESOURCE_STATE_TRANSITION_MODE_VERIFY,
+                                         BuffOp.pDstBuffer, BuffOp.DstOffset, BuffOp.NumBytes, BuffOp.DstBufferTransitionMode);
                 }
 
                 if (BuffOp.UploadEnqueued != nullptr)
@@ -558,16 +563,16 @@ void GPUUploadManagerImpl::Page::ExecutePendingOps(IDeviceContext* pContext, Uin
                     if (m_pStagingBuffer)
                     {
                         pContext->UpdateTexture(TexOp.pDstTexture, TexOp.DstMipLevel, TexOp.DstSlice, TexOp.DstBox, SrcData,
-                                                RESOURCE_STATE_TRANSITION_MODE_TRANSITION, RESOURCE_STATE_TRANSITION_MODE_TRANSITION);
+                                                RESOURCE_STATE_TRANSITION_MODE_VERIFY, TexOp.DstTextureTransitionMode);
                     }
                     else if (m_pStagingAtlas)
                     {
                         CopyTextureAttribs CopyAttribs;
 
                         CopyAttribs.pSrcTexture              = m_pStagingAtlas->pTex;
                         CopyAttribs.pDstTexture              = TexOp.pDstTexture;
-                        CopyAttribs.DstTextureTransitionMode = RESOURCE_STATE_TRANSITION_MODE_TRANSITION;
                         CopyAttribs.SrcTextureTransitionMode = RESOURCE_STATE_TRANSITION_MODE_VERIFY;
+                        CopyAttribs.DstTextureTransitionMode = TexOp.DstTextureTransitionMode;
                         CopyAttribs.DstMipLevel              = TexOp.DstMipLevel;
                         CopyAttribs.DstSlice                 = TexOp.DstSlice;
 
@@ -619,6 +624,7 @@ void GPUUploadManagerImpl::Page::Reset(IDeviceContext* pContext)
     {
         if (m_pStagingBuffer)
         {
+            pContext->TransitionResourceState({m_pStagingBuffer, RESOURCE_STATE_UNKNOWN, RESOURCE_STATE_COPY_SOURCE, STATE_TRANSITION_FLAG_UPDATE_STATE});
             const MAP_FLAGS MapFlags = m_PersistentMapped ?
                 MAP_FLAG_DO_NOT_WAIT :
                 MAP_FLAG_NONE;
@@ -721,8 +727,7 @@ GPUUploadManagerImpl::UploadStream::UploadStream(GPUUploadManagerImpl& Mgr,
                                                  TEXTURE_FORMAT        Format) noexcept :
     m_Mgr{Mgr},
     m_PageSize{AlignUpToPowerOfTwo(PageSize)},
-    // Ensure that the max page count is at least 2 to allow for double buffering, unless it's set to 0 which means no limit.
-    m_MaxPageCount{MaxPageCount != 0 ? std::max(MaxPageCount, 2u) : 0},
+    m_MaxPageCount{MaxPageCount},
     m_Format{Format}
 {
     if (pContext != nullptr)
@@ -897,6 +902,7 @@ GPUUploadManagerImpl::~GPUUploadManagerImpl()
     if (m_pTextureStreams)
     {
         m_pTextureStreams->SetStopping();
+        // After the stopping flag is set, no new streams can be added.
         m_pTextureStreams->MoveNewStreamsToManager();
     }
 

Original file line number	Diff line number	Diff line change
`@@ -61,7 +61,7 @@ bool GPUUploadManagerImpl::Page::Writer::ScheduleTextureUpdate(const ScheduleTex`
`61`	`61`	`{`
`62`	`62`	`if (m_pPage == nullptr)`
`63`	`63`	`{`
`64`		`- UNEXPECTED("Attempting to schedule a buffer update with an invalid writer.");`
	`64`	`+ UNEXPECTED("Attempting to schedule a texture update with an invalid writer.");`
`65`	`65`	`return false;`
`66`	`66`	`}`
`67`	`67`
`@@ -114,6 +114,7 @@ GPUUploadManagerImpl::Page::StagingTextureAtlas::~StagingTextureAtlas()`
`114`	`114`
`115`	`115`	`void* GPUUploadManagerImpl::Page::StagingTextureAtlas::Map(IDeviceContext* pContext)`
`116`	`116`	`{`
	`117`	`+ pContext->TransitionResourceState({pTex, RESOURCE_STATE_UNKNOWN, RESOURCE_STATE_COPY_SOURCE, STATE_TRANSITION_FLAG_UPDATE_STATE});`
`117`	`118`	`MappedTextureSubresource MappedData;`
`118`	`119`	`pContext->MapTextureSubresource(pTex, 0, 0, MAP_WRITE, MAP_FLAG_NONE, nullptr, MappedData);`
`119`	`120`	`RowStride = static_cast<Uint32>(MappedData.Stride);`
`@@ -135,7 +136,7 @@ void GPUUploadManagerImpl::Page::StagingTextureAtlas::Reset()`
`135`	`136`
`136`	`137`	`DynamicAtlasManager::Region GPUUploadManagerImpl::Page::StagingTextureAtlas::Allocate(Uint32 Width, Uint32 Height)`
`137`	`138`	`{`
`138`		`- std::lock_guard<std::mutex> Lock(MgrMtx);`
	`139`	`+ std::lock_guard<std::mutex> Lock{MgrMtx};`
`139`	`140`	`return Mgr.Allocate(Width, Height);`
`140`	`141`	`}`
`141`	`142`
`@@ -148,10 +149,12 @@ GPUUploadManagerImpl::Page::Page(Uint32 Size, bool PersistentMapped) noexcept :`
`148`	`149`	`inline bool PersistentMapSupported(IRenderDevice* pDevice)`
`149`	`150`	`{`
`150`	`151`	`RENDER_DEVICE_TYPE DeviceType = pDevice->GetDeviceInfo().Type;`
`151`		`- return DeviceType == RENDER_DEVICE_TYPE_D3D12 \|\| DeviceType == RENDER_DEVICE_TYPE_VULKAN;`
	`152`	`+ return (DeviceType == RENDER_DEVICE_TYPE_D3D12 \|\|`
	`153`	`+ DeviceType == RENDER_DEVICE_TYPE_VULKAN \|\|`
	`154`	`+ DeviceType == RENDER_DEVICE_TYPE_METAL);`
`152`	`155`	`}`
`153`	`156`
`154`		`-std::atomic<int> GPUUploadManagerImpl::Page::sm_PageCounter{0};`
	`157`	`+std::atomic<Uint32> GPUUploadManagerImpl::Page::sm_PageCounter{0};`
`155`	`158`
`156`	`159`	`GPUUploadManagerImpl::Page::Page(UploadStream& Stream, IRenderDevice* pDevice, Uint32 Size) :`
`157`	`160`	`m_pStream{&Stream},`
`@@ -354,9 +357,10 @@ bool GPUUploadManagerImpl::Page::ScheduleBufferUpdate(const ScheduleBufferUpdate`
`354`	`357`	`}`
`355`	`358`
`356`	`359`	`PendingBufferOp Op;`
`357`		`- Op.pDstBuffer = UpdateInfo.pDstBuffer;`
`358`		`- Op.CopyBuffer = UpdateInfo.CopyBuffer;`
`359`		`- Op.pCopyBufferData = UpdateInfo.pCopyBufferData;`
	`360`	`+ Op.pDstBuffer = UpdateInfo.pDstBuffer;`
	`361`	`+ Op.DstBufferTransitionMode = UpdateInfo.DstBufferTransitionMode;`
	`362`	`+ Op.CopyBuffer = UpdateInfo.CopyBuffer;`
	`363`	`+ Op.pCopyBufferData = UpdateInfo.pCopyBufferData;`
`360`	`364`	`if (Op.CopyBuffer == nullptr)`
`361`	`365`	`{`
`362`	`366`	`Op.UploadEnqueued = UpdateInfo.UploadEnqueued;`
`@@ -456,7 +460,8 @@ bool GPUUploadManagerImpl::Page::ScheduleTextureUpdate(const ScheduleTextureUpda`
`456`	`460`	`}`
`457`	`461`
`458`	`462`	`PendingTextureOp Op;`
`459`		`- Op.pDstTexture = UpdateInfo.pDstTexture;`
	`463`	`+ Op.pDstTexture = UpdateInfo.pDstTexture;`
	`464`	`+ Op.DstTextureTransitionMode = UpdateInfo.DstTextureTransitionMode;`
`460`	`465`	`if (m_pStagingBuffer)`
`461`	`466`	`{`
`462`	`467`	`Op.CopyTexture = UpdateInfo.CopyTexture;`
`@@ -523,8 +528,8 @@ void GPUUploadManagerImpl::Page::ExecutePendingOps(IDeviceContext* pContext, Uin`
`523`	`528`	`{`
`524`	`529`	`if (pContext != nullptr && BuffOp.pDstBuffer != nullptr && BuffOp.NumBytes > 0)`
`525`	`530`	`{`
`526`		`- pContext->CopyBuffer(m_pStagingBuffer, BuffOp.SrcOffset, RESOURCE_STATE_TRANSITION_MODE_TRANSITION,`
`527`		`- BuffOp.pDstBuffer, BuffOp.DstOffset, BuffOp.NumBytes, RESOURCE_STATE_TRANSITION_MODE_TRANSITION);`
	`531`	`+ pContext->CopyBuffer(m_pStagingBuffer, BuffOp.SrcOffset, RESOURCE_STATE_TRANSITION_MODE_VERIFY,`
	`532`	`+ BuffOp.pDstBuffer, BuffOp.DstOffset, BuffOp.NumBytes, BuffOp.DstBufferTransitionMode);`
`528`	`533`	`}`
`529`	`534`
`530`	`535`	`if (BuffOp.UploadEnqueued != nullptr)`
`@@ -558,16 +563,16 @@ void GPUUploadManagerImpl::Page::ExecutePendingOps(IDeviceContext* pContext, Uin`
`558`	`563`	`if (m_pStagingBuffer)`
`559`	`564`	`{`
`560`	`565`	`pContext->UpdateTexture(TexOp.pDstTexture, TexOp.DstMipLevel, TexOp.DstSlice, TexOp.DstBox, SrcData,`
`561`		`- RESOURCE_STATE_TRANSITION_MODE_TRANSITION, RESOURCE_STATE_TRANSITION_MODE_TRANSITION);`
	`566`	`+ RESOURCE_STATE_TRANSITION_MODE_VERIFY, TexOp.DstTextureTransitionMode);`
`562`	`567`	`}`
`563`	`568`	`else if (m_pStagingAtlas)`
`564`	`569`	`{`
`565`	`570`	`CopyTextureAttribs CopyAttribs;`
`566`	`571`
`567`	`572`	`CopyAttribs.pSrcTexture = m_pStagingAtlas->pTex;`
`568`	`573`	`CopyAttribs.pDstTexture = TexOp.pDstTexture;`
`569`		`- CopyAttribs.DstTextureTransitionMode = RESOURCE_STATE_TRANSITION_MODE_TRANSITION;`
`570`	`574`	`CopyAttribs.SrcTextureTransitionMode = RESOURCE_STATE_TRANSITION_MODE_VERIFY;`
	`575`	`+ CopyAttribs.DstTextureTransitionMode = TexOp.DstTextureTransitionMode;`
`571`	`576`	`CopyAttribs.DstMipLevel = TexOp.DstMipLevel;`
`572`	`577`	`CopyAttribs.DstSlice = TexOp.DstSlice;`
`573`	`578`
`@@ -619,6 +624,7 @@ void GPUUploadManagerImpl::Page::Reset(IDeviceContext* pContext)`
`619`	`624`	`{`
`620`	`625`	`if (m_pStagingBuffer)`
`621`	`626`	`{`
	`627`	`+ pContext->TransitionResourceState({m_pStagingBuffer, RESOURCE_STATE_UNKNOWN, RESOURCE_STATE_COPY_SOURCE, STATE_TRANSITION_FLAG_UPDATE_STATE});`
`622`	`628`	`const MAP_FLAGS MapFlags = m_PersistentMapped ?`
`623`	`629`	`MAP_FLAG_DO_NOT_WAIT :`
`624`	`630`	`MAP_FLAG_NONE;`
`@@ -721,8 +727,7 @@ GPUUploadManagerImpl::UploadStream::UploadStream(GPUUploadManagerImpl& Mgr,`
`721`	`727`	`TEXTURE_FORMAT Format) noexcept :`
`722`	`728`	`m_Mgr{Mgr},`
`723`	`729`	`m_PageSize{AlignUpToPowerOfTwo(PageSize)},`
`724`		`- // Ensure that the max page count is at least 2 to allow for double buffering, unless it's set to 0 which means no limit.`
`725`		`- m_MaxPageCount{MaxPageCount != 0 ? std::max(MaxPageCount, 2u) : 0},`
	`730`	`+ m_MaxPageCount{MaxPageCount},`
`726`	`731`	`m_Format{Format}`
`727`	`732`	`{`
`728`	`733`	`if (pContext != nullptr)`
`@@ -897,6 +902,7 @@ GPUUploadManagerImpl::~GPUUploadManagerImpl()`
`897`	`902`	`if (m_pTextureStreams)`
`898`	`903`	`{`
`899`	`904`	`m_pTextureStreams->SetStopping();`
	`905`	`+ // After the stopping flag is set, no new streams can be added.`
`900`	`906`	`m_pTextureStreams->MoveNewStreamsToManager();`
`901`	`907`	`}`
`902`	`908`