Enable AGS Markers to Replay

USAGE_desktop_D3D12.md

@@ -290,6 +290,9 @@ Optional arguments:
   --dx12-override-object-names
                         Generates unique names for all ID3D12Objects and assigns each object the generated
                         name.  This is intended to assist replay debugging.
+  --dx12-ags-inject-markers
+                        Label each API calls as block index of the trace
+                        Radeon GPU Detective could dump the label for debugging.
   --batching-memory-usage <pct>
                         Limits the max amount of additional memory that can be used to batch resource data
                         uploads during trim state load. Batching resource data uploads may reduce the number

framework/decode/CMakeLists.txt

@@ -1,6 +1,6 @@
 ###############################################################################
 # Copyright (c) 2018-2023 LunarG, Inc.
-# Copyright (c) 2019-2023 Advanced Micro Devices, Inc.
+# Copyright (c) 2019-2025 Advanced Micro Devices, Inc.
 # All rights reserved
 #
 # Permission is hereby granted, free of charge, to any person obtaining a copy
@@ -271,6 +271,8 @@ target_sources(gfxrecon_decode
                     ${CMAKE_CURRENT_LIST_DIR}/custom_ags_replay_consumer.h
                     ${CMAKE_CURRENT_LIST_DIR}/custom_ags_replay_consumer.cpp
                     ${CMAKE_CURRENT_LIST_DIR}/ags_detection_consumer.h
+                    ${CMAKE_CURRENT_LIST_DIR}/ags_gpu_cmd_wrapper.h
+                    ${CMAKE_CURRENT_LIST_DIR}/ags_gpu_cmd_wrapper.cpp
                )
 endif()
 

framework/decode/ags_gpu_cmd_wrapper.cpp

@@ -0,0 +1,107 @@
+/*
+** Copyright (c) 2025 Advanced Micro Devices, Inc. All rights reserved.
+**
+** Permission is hereby granted, free of charge, to any person obtaining a
+** copy of this software and associated documentation files (the "Software"),
+** to deal in the Software without restriction, including without limitation
+** the rights to use, copy, modify, merge, publish, distribute, sublicense,
+** and/or sell copies of the Software, and to permit persons to whom the
+** Software is furnished to do so, subject to the following conditions:
+**
+** The above copyright notice and this permission notice shall be included in
+** all copies or substantial portions of the Software.
+**
+** THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+** IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+** FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+** AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+** LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+** FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+** DEALINGS IN THE SOFTWARE.
+*/
+
+#include "decode/ags_gpu_cmd_wrapper.h"
+
+#include "generated/generated_dx12_call_id_to_string.h"
+#include "graphics/dx12_ags_marker_injector.h"
+
+#include <locale>
+#include <codecvt>
+
+GFXRECON_BEGIN_NAMESPACE(gfxrecon)
+GFXRECON_BEGIN_NAMESPACE(decode)
+
+AgsGpuCmdWrapper::AgsGpuCmdWrapper(DxReplayOptions*           options,
+                                   ID3D12GraphicsCommandList* command_list,
+                                   format::HandleId           capture_id,
+                                   format::ApiCallId          call_id,
+                                   uint64_t                   block_idx)
+{
+    if ((options != nullptr))
+    {
+        current_options = options;
+
+        if (current_options->ags_inject_markers)
+        {
+            if (command_list != nullptr)
+            {
+                current_command_list = command_list;
+
+                if (call_id == format::ApiCallId::ApiCall_ID3D12GraphicsCommandList_BeginEvent ||
+                    call_id == format::ApiCallId::ApiCall_ID3D12GraphicsCommandList_EndEvent ||
+                    call_id == format::ApiCallId::ApiCall_ID3D12GraphicsCommandList_SetMarker)
+                {
+                    bypass_marker_ = true;
+                }
+
+                if (bypass_marker_ == false)
+                {
+                    graphics::Dx12AgsMarkerInjector* injector = graphics::Dx12AgsMarkerInjector::Get();
+
+                    if (injector != nullptr)
+                    {
+                        std::wstring api_id_w = gfxrecon::util::GetDx12CallIdString(call_id);
+
+                        std::wstring_convert<std::codecvt_utf8<wchar_t>, wchar_t> temp_convert;
+                        std::string api_id = temp_convert.to_bytes(api_id_w);
+
+                        std::string marker_str = "gfxr_cmd_list_";
+                        marker_str.append(std::to_string(capture_id));
+                        marker_str.append(" - ");
+                        marker_str.append(api_id);
+                        marker_str.append(" - ");
+                        marker_str.append("block_idx_");
+                        marker_str.append(std::to_string(block_idx));
+
+                        injector->PushMarker(current_command_list, marker_str);
+                    }
+                }
+            }
+        }
+    }
+}
+
+AgsGpuCmdWrapper::~AgsGpuCmdWrapper()
+{
+    if (current_options != nullptr)
+    {
+        if (current_options->ags_inject_markers)
+        {
+            if (current_command_list != nullptr)
+            {
+                if (bypass_marker_ == false)
+                {
+                    graphics::Dx12AgsMarkerInjector* injector = graphics::Dx12AgsMarkerInjector::Get();
+
+                    if (injector != nullptr)
+                    {
+                        injector->PopMarker(current_command_list);
+                    }
+                }
+            }
+        }
+    }
+}
+
+GFXRECON_END_NAMESPACE(decode)
+GFXRECON_END_NAMESPACE(gfxrecon)

framework/decode/ags_gpu_cmd_wrapper.h

@@ -0,0 +1,56 @@
+/*
+** Copyright (c) 2025 Advanced Micro Devices, Inc. All rights reserved.
+**
+** Permission is hereby granted, free of charge, to any person obtaining a
+** copy of this software and associated documentation files (the "Software"),
+** to deal in the Software without restriction, including without limitation
+** the rights to use, copy, modify, merge, publish, distribute, sublicense,
+** and/or sell copies of the Software, and to permit persons to whom the
+** Software is furnished to do so, subject to the following conditions:
+**
+** The above copyright notice and this permission notice shall be included in
+** all copies or substantial portions of the Software.
+**
+** THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+** IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+** FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+** AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+** LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+** FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+** DEALINGS IN THE SOFTWARE.
+*/
+
+#ifndef GFXRECON_AGS_GPU_CMD_WRAPPER_H
+#define GFXRECON_AGS_GPU_CMD_WRAPPER_H
+
+#include "util/defines.h"
+#include "format/format.h"
+
+#include "decode/dx_replay_options.h"
+
+#include <d3d12.h>
+
+GFXRECON_BEGIN_NAMESPACE(gfxrecon)
+GFXRECON_BEGIN_NAMESPACE(decode)
+
+class AgsGpuCmdWrapper
+{
+  public:
+    AgsGpuCmdWrapper(DxReplayOptions*           options,
+                     ID3D12GraphicsCommandList* command_list,
+                     format::HandleId           capture_id,
+                     format::ApiCallId          call_id,
+                     uint64_t                   block_idx);
+
+    ~AgsGpuCmdWrapper();
+
+  private:
+    DxReplayOptions*           current_options{ nullptr };
+    ID3D12GraphicsCommandList* current_command_list{ nullptr };
+    bool                       bypass_marker_ = false;
+};
+
+GFXRECON_END_NAMESPACE(decode)
+GFXRECON_END_NAMESPACE(gfxrecon)
+
+#endif // GFXRECON_AGS_GPU_CMD_WRAPPER_H

framework/decode/custom_ags_replay_consumer.cpp

@@ -163,6 +163,7 @@ void AgsReplayConsumer::Process_agsInitialize(const ApiCallInfo&      call_info,
     if (result == AGS_SUCCESS)
     {
         context_map_[context] = replay_context;
+        dx12_replay_consumer_->SetAgsMarkerInjector(replay_context);
     }
 
     CheckReplayResult("Process_agsInitialize", return_value, result);

framework/decode/dx12_replay_consumer_base.cpp

@@ -1,6 +1,6 @@
 /*
 ** Copyright (c) 2021-2023 LunarG, Inc.
-** Copyright (c) 2021-2023 Advanced Micro Devices, Inc. All rights reserved.
+** Copyright (c) 2021-2025 Advanced Micro Devices, Inc. All rights reserved.
 **
 ** Permission is hereby granted, free of charge, to any person obtaining a
 ** copy of this software and associated documentation files (the "Software"),
@@ -75,11 +75,10 @@ void InitialResourceExtraInfo(HandlePointerDecoder<void*>* resource_decoder,
 
 Dx12ReplayConsumerBase::Dx12ReplayConsumerBase(std::shared_ptr<application::Application> application,
                                                const DxReplayOptions&                    options) :
-    application_(application),
-    options_(options), current_message_length_(0), info_queue_(nullptr), resource_data_util_(nullptr),
-    frame_buffer_renderer_(nullptr), debug_layer_enabled_(false), set_auto_breadcrumbs_enablement_(false),
-    set_breadcrumb_context_enablement_(false), set_page_fault_enablement_(false), loading_trim_state_(false),
-    fps_info_(nullptr), frame_end_marker_count_(0)
+    application_(application), options_(options), current_message_length_(0), info_queue_(nullptr),
+    resource_data_util_(nullptr), frame_buffer_renderer_(nullptr), debug_layer_enabled_(false),
+    set_auto_breadcrumbs_enablement_(false), set_breadcrumb_context_enablement_(false),
+    set_page_fault_enablement_(false), loading_trim_state_(false), fps_info_(nullptr), frame_end_marker_count_(0)
 {
     if (options_.enable_validation_layer)
     {
@@ -118,13 +117,54 @@ Dx12ReplayConsumerBase::Dx12ReplayConsumerBase(std::shared_ptr<application::Appl
         InitializeScreenshotHandler();
     }
 
+#ifdef GFXRECON_AGS_SUPPORT
+    SetAgsMarkerInjector();
+#endif
+
     DetectAdapters();
 
     auto get_object_func = std::bind(&Dx12ReplayConsumerBase::GetObjectInfo, this, std::placeholders::_1);
     resource_value_mapper_ =
         std::make_unique<Dx12ResourceValueMapper>(get_object_func, shader_id_map_, gpu_va_map_, descriptor_map_);
 }
 
+#ifdef GFXRECON_AGS_SUPPORT
+void Dx12ReplayConsumerBase::SetAgsMarkerInjector(AGSContext* ags_context)
+{
+    if (options_.ags_inject_markers)
+    {
+        ags_marker_injector_ = graphics::Dx12AgsMarkerInjector::Create();
+
+        if (ags_marker_injector_ != nullptr)
+        {
+            AGSConfiguration ags_config   = {};
+            AGSGPUInfo       ags_gpu_info = {};
+
+            if (ags_context == nullptr)
+            {
+                AGSReturnCode ags_return =
+                    agsInitialize(AGS_MAKE_VERSION(AMD_AGS_VERSION_MAJOR, AMD_AGS_VERSION_MINOR, AMD_AGS_VERSION_PATCH),
+                                  &ags_config,
+                                  &ags_context,
+                                  &ags_gpu_info);
+
+                if (ags_return != AGS_SUCCESS)
+                {
+                    GFXRECON_LOG_WARNING("Failed to initialize AGS. Marker injection disabled.");
+
+                    options_.ags_inject_markers = false;
+                    ags_marker_injector_        = nullptr;
+                }
+            }
+            if (ags_context != nullptr)
+            {
+                ags_marker_injector_->SetContext(ags_context);
+            }
+        }
+    }
+}
+#endif
+
 void Dx12ReplayConsumerBase::EnableDebugLayer(ID3D12Debug* dx12_debug)
 {
     if (!debug_layer_enabled_)
@@ -390,7 +430,7 @@ void Dx12ReplayConsumerBase::ApplyBatchedResourceInitInfo(
         // 2. One ExecuteCommandLists could work for only one swapchain buffer.
         // 3. The current back buffer index has to match the swapchain buffer.
         // 4. After ExecuteCommandLists, the current back buffer index has to back init.
-        // 5. It shouldn't change resource states until all Presnt are done since Present require 
+        // 5. It shouldn't change resource states until all Presnt are done since Present require
         //    D3D12_RESOURCE_STATE_PRESENT. The before_states supposes to be PRESENT.
 
         // Although it has only one swapchain mostly, it probably has a plural in some cases.
@@ -404,7 +444,7 @@ void Dx12ReplayConsumerBase::ApplyBatchedResourceInitInfo(
             auto swapchain             = reinterpret_cast<IDXGISwapChain3*>(swapchain_info->object);
             swapchain_infos[swapchain] = swapchain_extra_info;
 
-            for (auto &state : resource_info.second->before_states)
+            for (auto& state : resource_info.second->before_states)
             {
                 if (state.states != D3D12_RESOURCE_STATE_PRESENT)
                 {
@@ -1078,8 +1118,57 @@ HRESULT Dx12ReplayConsumerBase::OverrideD3D12CreateDevice(HRESULT
 
     IUnknown* adapter = GetCreateDeviceAdapter(adapter_info);
 
-    auto replay_result =
-        D3D12CreateDevice(adapter, minimum_feature_level, *riid.decoded_value, device->GetHandlePointer());
+    auto replay_result = E_FAIL;
+#ifdef GFXRECON_AGS_SUPPORT
+    if (options_.ags_inject_markers)
+    {
+        AGSDX12DeviceCreationParams creation_params = {};
+        creation_params.pAdapter                    = GetAdapter();
+        creation_params.iid                         = IID_ID3D12Device;
+        creation_params.FeatureLevel                = minimum_feature_level;
+
+        AGSDX12ExtensionParams extension_params = {};
+        AGSDX12ReturnedParams  returned_params  = {};
+
+        // Create AGS device for marker injection
+        AGSReturnCode ags_return = agsDriverExtensionsDX12_CreateDevice(
+            ags_marker_injector_->Context(), &creation_params, &extension_params, &returned_params);
+
+        if (ags_return == AGS_SUCCESS)
+        {
+            GFXRECON_LOG_DEBUG("Created AGS device.");
+
+            if (device->GetHandlePointer() != nullptr)
+            {
+                *device->GetHandlePointer() = returned_params.pDevice;
+            }
+
+            replay_result = S_OK;
+
+            if (returned_params.extensionsSupported.userMarkers == 0)
+            {
+                GFXRECON_LOG_WARNING("Device does not support the AGS marker extension. Marker injection disabled.");
+
+                options_.ags_inject_markers = false;
+            }
+        }
+        else
+        {
+            GFXRECON_LOG_WARNING("Failed to create AGS device, so falling back to creation of regular ID3D12Device. "
+                                 "Marker injection disabled.");
+
+            options_.ags_inject_markers = false;
+
+            replay_result =
+                D3D12CreateDevice(adapter, minimum_feature_level, *riid.decoded_value, device->GetHandlePointer());
+        }
+    }
+    else
+#endif
+    {
+        replay_result =
+            D3D12CreateDevice(adapter, minimum_feature_level, *riid.decoded_value, device->GetHandlePointer());
+    }
 
     if (SUCCEEDED(replay_result) && !device->IsNull())
     {
@@ -4633,7 +4722,7 @@ void Dx12ReplayConsumerBase::PostCall_ID3D12Device_CreateShaderResourceView(
     }
     else
     {
-        srv_info.desc     = *(pDesc->GetMetaStructPointer()->decoded_value);
+        srv_info.desc         = *(pDesc->GetMetaStructPointer()->decoded_value);
         srv_info.is_desc_null = false;
 
         if (options_.enable_dump_resources)

framework/decode/dx12_replay_consumer_base.h

@@ -42,6 +42,10 @@
 #include "graphics/dx12_util.h"
 #include "application/application.h"
 
+#ifdef GFXRECON_AGS_SUPPORT
+#include "graphics/dx12_ags_marker_injector.h"
+#endif
+
 #include <functional>
 #include <unordered_map>
 #include <unordered_set>
@@ -64,6 +68,10 @@ class Dx12ReplayConsumerBase : public Dx12Consumer
         gfxrecon::util::filepath::CheckReplayerName(info_record.AppName);
     }
 
+#ifdef GFXRECON_AGS_SUPPORT
+    void SetAgsMarkerInjector(AGSContext* ags_context = nullptr);
+#endif
+
     void SetFatalErrorHandler(std::function<void(const char*)> handler) { fatal_error_handler_ = handler; }
 
     void SetFpsInfo(graphics::FpsInfo* fps_info) { fps_info_ = fps_info; }
@@ -1170,6 +1178,10 @@ class Dx12ReplayConsumerBase : public Dx12Consumer
     std::unique_ptr<ScreenshotHandlerBase>                screenshot_handler_;
     std::unordered_map<ID3D12Resource*, ResourceInitInfo> resource_init_infos_;
     uint64_t                                              frame_end_marker_count_;
+
+#ifdef GFXRECON_AGS_SUPPORT
+    graphics::Dx12AgsMarkerInjector* ags_marker_injector_{ nullptr };
+#endif
 };
 
 GFXRECON_END_NAMESPACE(decode)