Core: added annotations for "CommandQueue"

Include/NRI.h

@@ -34,7 +34,10 @@ NriNamespaceBegin
 // Example: Result result = nriGetInterface(device, NRI_INTERFACE(CoreInterface), &coreInterface)
 NRI_API Nri(Result) NRI_CALL nriGetInterface(const NriRef(Device) device, const char* interfaceName, size_t interfaceSize, void* interfacePtr);
 
-// Annotations for profiling tools: host (via NVTX)
+// Annotations for profiling tools: host
+// - Host annotations currently use NVTX (NVIDIA Nsight Systems)
+// - Device (command buffer and queue) annotations use GAPI or PIX (if "WinPixEventRuntime.dll" is nearby)
+// - Colorization requires PIX or NVTX
 NRI_API void NRI_CALL nriBeginAnnotation(const char* name, uint32_t bgra);  // start a named range
 NRI_API void NRI_CALL nriEndAnnotation();                                   // end the last opened range
 NRI_API void NRI_CALL nriAnnotation(const char* name, uint32_t bgra);       // emit a named simultaneous event
@@ -172,15 +175,18 @@ NriStruct(CoreInterface) {
         void                (NRI_CALL *CmdEndQuery)                 (NriRef(CommandBuffer) commandBuffer, NriRef(QueryPool) queryPool, uint32_t offset);
         void                (NRI_CALL *CmdCopyQueries)              (NriRef(CommandBuffer) commandBuffer, const NriRef(QueryPool) queryPool, uint32_t offset, uint32_t num, NriRef(Buffer) dstBuffer, uint64_t dstOffset);
 
-        // Annotations for profiling tools: device (most of tools show them on the CPU timeline too)
-        // D3D11: no colors
-        // D3D12: no colors if "WinPixEventRuntime.dll" is not nearby
-        void                (NRI_CALL *CmdBeginAnnotation)          (NriRef(CommandBuffer) commandBuffer, const char* name, uint32_t bgra); // start a named range
-        void                (NRI_CALL *CmdEndAnnotation)            (NriRef(CommandBuffer) commandBuffer);                                  // end the last opened range
-        void                (NRI_CALL *CmdAnnotation)               (NriRef(CommandBuffer) commandBuffer, const char* name, uint32_t bgra); // emit a named simultaneous event
+        // Annotations for profiling tools: command buffer
+        void                (NRI_CALL *CmdBeginAnnotation)          (NriRef(CommandBuffer) commandBuffer, const char* name, uint32_t bgra);
+        void                (NRI_CALL *CmdEndAnnotation)            (NriRef(CommandBuffer) commandBuffer);
+        void                (NRI_CALL *CmdAnnotation)               (NriRef(CommandBuffer) commandBuffer, const char* name, uint32_t bgra);
     // }                }
     Nri(Result)         (NRI_CALL *EndCommandBuffer)                (NriRef(CommandBuffer) commandBuffer);
 
+    // Annotations for profiling tools: command queue
+    void                (NRI_CALL *QueueBeginAnnotation)            (NriRef(CommandQueue) commandQueue, const char* name, uint32_t bgra);
+    void                (NRI_CALL *QueueEndAnnotation)              (NriRef(CommandQueue) commandQueue);
+    void                (NRI_CALL *QueueAnnotation)                 (NriRef(CommandQueue) commandQueue, const char* name, uint32_t bgra);
+
     // Query
     void                (NRI_CALL *ResetQueries)                    (NriRef(QueryPool) queryPool, uint32_t offset, uint32_t num); // on host
 

Source/D3D11/CommandBufferD3D11.hpp

@@ -1,7 +1,5 @@
 // © 2021 NVIDIA Corporation
 
-#include <pix.h>
-
 static constexpr uint64_t s_nullOffsets[D3D11_IA_VERTEX_INPUT_RESOURCE_SLOT_COUNT] = {0};
 
 uint8_t QueryLatestDeviceContext(ComPtr<ID3D11DeviceContextBest>& in, ComPtr<ID3D11DeviceContextBest>& out) {

Source/D3D11/ImplD3D11.cpp

@@ -462,6 +462,15 @@ static void NRI_CALL CmdCopyQueries(CommandBuffer& commandBuffer, const QueryPoo
 static void NRI_CALL CmdResetQueries(CommandBuffer&, QueryPool&, uint32_t, uint32_t) {
 }
 
+static void NRI_CALL QueueBeginAnnotation(CommandQueue&, const char*, uint32_t) {
+}
+
+static void NRI_CALL QueueEndAnnotation(CommandQueue&) {
+}
+
+static void NRI_CALL QueueAnnotation(CommandQueue&, const char*, uint32_t) {
+}
+
 static void NRI_CALL ResetQueries(QueryPool&, uint32_t, uint32_t) {
 }
 
@@ -767,6 +776,9 @@ Result DeviceD3D11::FillFunctionTable(CoreInterface& table) const {
     table.BindBufferMemory = ::BindBufferMemory;
     table.BindTextureMemory = ::BindTextureMemory;
     table.FreeMemory = ::FreeMemory;
+    table.QueueBeginAnnotation = ::QueueBeginAnnotation;
+    table.QueueEndAnnotation = ::QueueEndAnnotation;
+    table.QueueAnnotation = ::QueueAnnotation;
     table.ResetQueries = ::ResetQueries;
     table.QueueSubmit = ::QueueSubmit;
     table.Wait = ::Wait;

Source/D3D11/SharedD3D11.h

@@ -3,6 +3,7 @@
 #pragma once
 
 #include <d3d11_4.h>
+#include <pix.h>
 
 #include "SharedExternal.h"
 

Source/D3D12/CommandBufferD3D12.hpp

@@ -1,7 +1,5 @@
 // © 2021 NVIDIA Corporation
 
-#include <pix.h>
-
 static uint8_t QueryLatestGraphicsCommandList(ComPtr<ID3D12GraphicsCommandListBest>& in, ComPtr<ID3D12GraphicsCommandListBest>& out) {
     static const IID versions[] = {
 #ifdef NRI_USE_AGILITY_SDK

Source/D3D12/CommandQueueD3D12.h

@@ -41,6 +41,9 @@ struct CommandQueueD3D12 {
         SET_D3D_DEBUG_OBJECT_NAME(m_CommandQueue, name);
     }
 
+    void BeginAnnotation(const char* name, uint32_t bgra);
+    void EndAnnotation();
+    void Annotation(const char* name, uint32_t bgra);
     void Submit(const QueueSubmitDesc& queueSubmitDesc);
     Result UploadData(const TextureUploadDesc* textureUploadDescs, uint32_t textureUploadDescNum, const BufferUploadDesc* bufferUploadDescs, uint32_t bufferUploadDescNum);
     Result WaitForIdle();

Source/D3D12/CommandQueueD3D12.hpp

@@ -24,6 +24,27 @@ Result CommandQueueD3D12::Create(ID3D12CommandQueue* commandQueue) {
     return Result::SUCCESS;
 }
 
+NRI_INLINE void CommandQueueD3D12::BeginAnnotation(const char* name, uint32_t bgra) {
+    if (m_Device.GetExt()->HasPix())
+        m_Device.GetExt()->m_Pix.BeginEventOnCommandQueue(m_CommandQueue, bgra, name);
+    else
+        PIXBeginEvent(m_CommandQueue, bgra, name);
+}
+
+NRI_INLINE void CommandQueueD3D12::EndAnnotation() {
+    if (m_Device.GetExt()->HasPix())
+        m_Device.GetExt()->m_Pix.EndEventOnCommandQueue(m_CommandQueue);
+    else
+        PIXEndEvent(m_CommandQueue);
+}
+
+NRI_INLINE void CommandQueueD3D12::Annotation(const char* name, uint32_t bgra) {
+    if (m_Device.GetExt()->HasPix())
+        m_Device.GetExt()->m_Pix.SetMarkerOnCommandQueue(m_CommandQueue, bgra, name);
+    else
+        PIXSetMarker(m_CommandQueue, bgra, name);
+}
+
 NRI_INLINE void CommandQueueD3D12::Submit(const QueueSubmitDesc& queueSubmitDesc) {
     for (uint32_t i = 0; i < queueSubmitDesc.waitFenceNum; i++) {
         const FenceSubmitDesc& fenceSubmitDesc = queueSubmitDesc.waitFences[i];

Source/D3D12/ImplD3D12.cpp

@@ -298,6 +298,18 @@ static void NRI_CALL CmdCopyQueries(CommandBuffer& commandBuffer, const QueryPoo
 static void NRI_CALL CmdResetQueries(CommandBuffer&, QueryPool&, uint32_t, uint32_t) {
 }
 
+static void NRI_CALL QueueBeginAnnotation(CommandQueue& commandBuffer, const char* name, uint32_t bgra) {
+    ((CommandQueueD3D12&)commandBuffer).BeginAnnotation(name, bgra);
+}
+
+static void NRI_CALL QueueEndAnnotation(CommandQueue& commandBuffer) {
+    ((CommandQueueD3D12&)commandBuffer).EndAnnotation();
+}
+
+static void NRI_CALL QueueAnnotation(CommandQueue& commandBuffer, const char* name, uint32_t bgra) {
+    ((CommandQueueD3D12&)commandBuffer).Annotation(name, bgra);
+}
+
 static void NRI_CALL ResetQueries(QueryPool&, uint32_t, uint32_t) {
 }
 
@@ -640,6 +652,9 @@ Result DeviceD3D12::FillFunctionTable(CoreInterface& table) const {
     table.CmdEndAnnotation = ::CmdEndAnnotation;
     table.CmdAnnotation = ::CmdAnnotation;
     table.EndCommandBuffer = ::EndCommandBuffer;
+    table.QueueBeginAnnotation = ::QueueBeginAnnotation;
+    table.QueueEndAnnotation = ::QueueEndAnnotation;
+    table.QueueAnnotation = ::QueueAnnotation;
     table.ResetQueries = ::ResetQueries;
     table.QueueSubmit = ::QueueSubmit;
     table.Wait = ::Wait;

Source/D3D12/SharedD3D12.h

@@ -3,6 +3,7 @@
 #pragma once
 
 #include <d3d12.h>
+#include <pix.h>
 
 #include "SharedExternal.h"
 

Source/NONE/ImplNONE.cpp

@@ -525,6 +525,15 @@ static Result NRI_CALL EndCommandBuffer(CommandBuffer&) {
     return Result::SUCCESS;
 }
 
+static void NRI_CALL QueueBeginAnnotation(CommandQueue&, const char*, uint32_t) {
+}
+
+static void NRI_CALL QueueEndAnnotation(CommandQueue&) {
+}
+
+static void NRI_CALL QueueAnnotation(CommandQueue&, const char*, uint32_t) {
+}
+
 static void NRI_CALL ResetQueries(QueryPool&, uint32_t, uint32_t) {
 }
 
@@ -706,6 +715,9 @@ Result DeviceNONE::FillFunctionTable(CoreInterface& table) const {
     table.CmdEndAnnotation = ::CmdEndAnnotation;
     table.CmdAnnotation = ::CmdAnnotation;
     table.EndCommandBuffer = ::EndCommandBuffer;
+    table.QueueBeginAnnotation = ::QueueBeginAnnotation;
+    table.QueueEndAnnotation = ::QueueEndAnnotation;
+    table.QueueAnnotation = ::QueueAnnotation;
     table.ResetQueries = ::ResetQueries;
     table.QueueSubmit = ::QueueSubmit;
     table.Wait = ::Wait;

Source/Shared/D3DExt.h

@@ -8,11 +8,17 @@
 typedef HRESULT(WINAPI* PIX_BEGINEVENTONCOMMANDLIST)(ID3D12GraphicsCommandList* commandList, UINT64 color, _In_ PCSTR formatString);
 typedef HRESULT(WINAPI* PIX_ENDEVENTONCOMMANDLIST)(ID3D12GraphicsCommandList* commandList);
 typedef HRESULT(WINAPI* PIX_SETMARKERONCOMMANDLIST)(ID3D12GraphicsCommandList* commandList, UINT64 color, _In_ PCSTR formatString);
+typedef HRESULT(WINAPI* PIX_BEGINEVENTONCOMMANDQUEUE)(ID3D12CommandQueue* commandQueue, UINT64 color, _In_ PCSTR formatString);
+typedef HRESULT(WINAPI* PIX_ENDEVENTONCOMMANDQUEUE)(ID3D12CommandQueue* commandQueue);
+typedef HRESULT(WINAPI* PIX_SETMARKERONCOMMANDQUEUE)(ID3D12CommandQueue* commandQueue, UINT64 color, _In_ PCSTR formatString);
 
 struct PixFuncTable {
     PIX_BEGINEVENTONCOMMANDLIST BeginEventOnCommandList;
     PIX_ENDEVENTONCOMMANDLIST EndEventOnCommandList;
     PIX_SETMARKERONCOMMANDLIST SetMarkerOnCommandList;
+    PIX_BEGINEVENTONCOMMANDQUEUE BeginEventOnCommandQueue;
+    PIX_ENDEVENTONCOMMANDQUEUE EndEventOnCommandQueue;
+    PIX_SETMARKERONCOMMANDQUEUE SetMarkerOnCommandQueue;
 };
 
 #endif

Source/Shared/D3DExt.hpp

@@ -12,6 +12,9 @@ void Ext::InitializePixExt() {
     m_Pix.BeginEventOnCommandList = (PIX_BEGINEVENTONCOMMANDLIST)GetSharedLibraryFunction(*m_PixLibrary, "PIXBeginEventOnCommandList");
     m_Pix.EndEventOnCommandList = (PIX_ENDEVENTONCOMMANDLIST)GetSharedLibraryFunction(*m_PixLibrary, "PIXEndEventOnCommandList");
     m_Pix.SetMarkerOnCommandList = (PIX_SETMARKERONCOMMANDLIST)GetSharedLibraryFunction(*m_PixLibrary, "PIXSetMarkerOnCommandList");
+    m_Pix.BeginEventOnCommandQueue = (PIX_BEGINEVENTONCOMMANDQUEUE)GetSharedLibraryFunction(*m_PixLibrary, "PIXBeginEventOnCommandQueue");
+    m_Pix.EndEventOnCommandQueue = (PIX_ENDEVENTONCOMMANDQUEUE)GetSharedLibraryFunction(*m_PixLibrary, "PIXEndEventOnCommandQueue");
+    m_Pix.SetMarkerOnCommandQueue = (PIX_SETMARKERONCOMMANDQUEUE)GetSharedLibraryFunction(*m_PixLibrary, "PIXSetMarkerOnCommandQueue");
 
     // Verify
     const void** functionArray = (const void**)&m_Pix;

Source/VK/CommandQueueVK.h

@@ -38,6 +38,9 @@ struct CommandQueueVK {
     //================================================================================================================
 
     void SetDebugName(const char* name);
+    void BeginAnnotation(const char* name, uint32_t bgra);
+    void EndAnnotation();
+    void Annotation(const char* name, uint32_t bgra);
     void Submit(const QueueSubmitDesc& queueSubmitDesc, const SwapChain* swapChain);
     Result UploadData(const TextureUploadDesc* textureUploadDescs, uint32_t textureUploadDescNum, const BufferUploadDesc* bufferUploadDescs, uint32_t bufferUploadDescNum);
     Result WaitForIdle();

Source/VK/CommandQueueVK.hpp

@@ -12,6 +12,38 @@ NRI_INLINE void CommandQueueVK::SetDebugName(const char* name) {
     m_Device.SetDebugNameToTrivialObject(VK_OBJECT_TYPE_QUEUE, (uint64_t)m_Handle, name);
 }
 
+NRI_INLINE void CommandQueueVK::BeginAnnotation(const char* name, uint32_t bgra) {
+    VkDebugUtilsLabelEXT info = {VK_STRUCTURE_TYPE_DEBUG_UTILS_LABEL_EXT};
+    info.pLabelName = name;
+    info.color[0] = ((bgra >> 16) & 0xFF) / 255.0f;
+    info.color[1] = ((bgra >> 8) & 0xFF) / 255.0f;
+    info.color[2] = ((bgra >> 0) & 0xFF) / 255.0f;
+    info.color[3] = 1.0f; // PIX sets alpha to 1
+
+    const auto& vk = m_Device.GetDispatchTable();
+    if (vk.QueueBeginDebugUtilsLabelEXT)
+        vk.QueueBeginDebugUtilsLabelEXT(m_Handle, &info);
+}
+
+NRI_INLINE void CommandQueueVK::EndAnnotation() {
+    const auto& vk = m_Device.GetDispatchTable();
+    if (vk.QueueEndDebugUtilsLabelEXT)
+        vk.QueueEndDebugUtilsLabelEXT(m_Handle);
+}
+
+NRI_INLINE void CommandQueueVK::Annotation(const char* name, uint32_t bgra) {
+    VkDebugUtilsLabelEXT info = {VK_STRUCTURE_TYPE_DEBUG_UTILS_LABEL_EXT};
+    info.pLabelName = name;
+    info.color[0] = ((bgra >> 16) & 0xFF) / 255.0f;
+    info.color[1] = ((bgra >> 8) & 0xFF) / 255.0f;
+    info.color[2] = ((bgra >> 0) & 0xFF) / 255.0f;
+    info.color[3] = 1.0f; // PIX sets alpha to 1
+
+    const auto& vk = m_Device.GetDispatchTable();
+    if (vk.QueueInsertDebugUtilsLabelEXT)
+        vk.QueueInsertDebugUtilsLabelEXT(m_Handle, &info);
+}
+
 NRI_INLINE void CommandQueueVK::Submit(const QueueSubmitDesc& queueSubmitDesc, const SwapChain* swapChain) {
     ExclusiveScope lock(m_Lock);
 

Source/VK/DeviceVK.hpp

@@ -1501,6 +1501,9 @@ Result DeviceVK::ResolveInstanceDispatchTable(const Vector<const char*>& desired
         GET_INSTANCE_PROC(CmdBeginDebugUtilsLabelEXT);
         GET_INSTANCE_PROC(CmdEndDebugUtilsLabelEXT);
         GET_INSTANCE_PROC(CmdInsertDebugUtilsLabelEXT);
+        GET_INSTANCE_PROC(QueueBeginDebugUtilsLabelEXT);
+        GET_INSTANCE_PROC(QueueEndDebugUtilsLabelEXT);
+        GET_INSTANCE_PROC(QueueInsertDebugUtilsLabelEXT);
     }
 
     if (IsExtensionSupported(VK_KHR_SURFACE_EXTENSION_NAME, desiredInstanceExts)) {

Source/VK/DispatchTable.h

@@ -52,6 +52,9 @@ struct DispatchTable {
     VULKAN_FUNCTION(CmdBeginDebugUtilsLabelEXT);
     VULKAN_FUNCTION(CmdEndDebugUtilsLabelEXT);
     VULKAN_FUNCTION(CmdInsertDebugUtilsLabelEXT);
+    VULKAN_FUNCTION(QueueBeginDebugUtilsLabelEXT);
+    VULKAN_FUNCTION(QueueEndDebugUtilsLabelEXT);
+    VULKAN_FUNCTION(QueueInsertDebugUtilsLabelEXT);
 
     // Device
     VULKAN_FUNCTION(CreateBuffer);

Source/VK/ImplVK.cpp

@@ -118,6 +118,18 @@ static Result NRI_CALL EndCommandBuffer(CommandBuffer& commandBuffer) {
     return ((CommandBufferVK&)commandBuffer).End();
 }
 
+static void NRI_CALL QueueBeginAnnotation(CommandQueue& commandQueue, const char* name, uint32_t bgra) {
+    ((CommandQueueVK&)commandQueue).BeginAnnotation(name, bgra);
+}
+
+static void NRI_CALL QueueEndAnnotation(CommandQueue& commandQueue) {
+    ((CommandQueueVK&)commandQueue).EndAnnotation();
+}
+
+static void NRI_CALL QueueAnnotation(CommandQueue& commandQueue, const char* name, uint32_t bgra) {
+    ((CommandQueueVK&)commandQueue).Annotation(name, bgra);
+}
+
 static void NRI_CALL ResetQueries(QueryPool& queryPool, uint32_t offset, uint32_t num) {
     ((QueryPoolVK&)queryPool).Reset(offset, num);
 }
@@ -628,6 +640,9 @@ Result DeviceVK::FillFunctionTable(CoreInterface& table) const {
     table.CmdEndAnnotation = ::CmdEndAnnotation;
     table.CmdAnnotation = ::CmdAnnotation;
     table.EndCommandBuffer = ::EndCommandBuffer;
+    table.QueueBeginAnnotation = ::QueueBeginAnnotation;
+    table.QueueEndAnnotation = ::QueueEndAnnotation;
+    table.QueueAnnotation = ::QueueAnnotation;
     table.ResetQueries = ::ResetQueries;
     table.QueueSubmit = ::QueueSubmit;
     table.Wait = ::Wait;

Source/Validation/CommandQueueVal.h

@@ -16,6 +16,9 @@ struct CommandQueueVal : public DeviceObjectVal<CommandQueue> {
     //================================================================================================================
 
     void SetDebugName(const char* name);
+    void BeginAnnotation(const char* name, uint32_t bgra);
+    void EndAnnotation();
+    void Annotation(const char* name, uint32_t bgra);
     void Submit(const QueueSubmitDesc& queueSubmitDesc, const SwapChain* swapChain);
 
     Result WaitForIdle();

Source/Validation/CommandQueueVal.hpp

@@ -52,6 +52,18 @@ NRI_INLINE void CommandQueueVal::SetDebugName(const char* name) {
     GetCoreInterface().SetCommandQueueDebugName(*GetImpl(), name);
 }
 
+NRI_INLINE void CommandQueueVal::BeginAnnotation(const char* name, uint32_t bgra) {
+    GetCoreInterface().QueueBeginAnnotation(*GetImpl(), name, bgra);
+}
+
+NRI_INLINE void CommandQueueVal::EndAnnotation() {
+    GetCoreInterface().QueueEndAnnotation(*GetImpl());
+}
+
+NRI_INLINE void CommandQueueVal::Annotation(const char* name, uint32_t bgra) {
+    GetCoreInterface().QueueAnnotation(*GetImpl(), name, bgra);
+}
+
 NRI_INLINE void CommandQueueVal::Submit(const QueueSubmitDesc& queueSubmitDesc, const SwapChain* swapChain) {
     auto queueSubmitDescImpl = queueSubmitDesc;
 

Source/Validation/ImplVal.cpp

@@ -268,6 +268,18 @@ static void NRI_CALL SetCommandQueueDebugName(CommandQueue& commandQueue, const
     ((CommandQueueVal&)commandQueue).SetDebugName(name);
 }
 
+static void NRI_CALL QueueBeginAnnotation(CommandQueue& commandQueue, const char* name, uint32_t bgra) {
+    ((CommandQueueVal&)commandQueue).BeginAnnotation(name, bgra);
+}
+
+static void NRI_CALL QueueEndAnnotation(CommandQueue& commandQueue) {
+    ((CommandQueueVal&)commandQueue).EndAnnotation();
+}
+
+static void NRI_CALL QueueAnnotation(CommandQueue& commandQueue, const char* name, uint32_t bgra) {
+    ((CommandQueueVal&)commandQueue).Annotation(name, bgra);
+}
+
 static void NRI_CALL ResetQueries(QueryPool& queryPool, uint32_t offset, uint32_t num) {
     ((QueryPoolVal&)queryPool).ResetQueries(offset, num);
 }
@@ -634,6 +646,9 @@ Result DeviceVal::FillFunctionTable(CoreInterface& table) const {
     table.CmdEndAnnotation = ::CmdEndAnnotation;
     table.CmdAnnotation = ::CmdAnnotation;
     table.EndCommandBuffer = ::EndCommandBuffer;
+    table.QueueBeginAnnotation = ::QueueBeginAnnotation;
+    table.QueueEndAnnotation = ::QueueEndAnnotation;
+    table.QueueAnnotation = ::QueueAnnotation;
     table.ResetQueries = ::ResetQueries;
     table.QueueSubmit = ::QueueSubmit;
     table.Wait = ::Wait;