跳至内容

用户调试标记

用户标记可以帮助应用程序开发者将 RGP 中看到的数据与其应用程序行为关联起来。用户标记目前不支持 OpenCL 或 HIP。

DirectX12 用户标记

对于 DirectX12，有两种推荐的方法可以使用用户标记来检测您的应用程序，这些标记可以在 RGP 中查看：

  1. 使用 Microsoft® PIX3 事件检测，或
  2. 使用 AMD GPU Services (AGS) 库中的调试标记支持。

使用 PIX3 事件检测实现 DirectX12 用户调试标记 如果您的应用程序已使用 PIX3 用户标记进行检测，则在 RGP 中查看标记只需重新编译应用程序的源代码并使用稍作修改的 PIX 头文件即可。此处描述的步骤需要 WinPixEventRuntime 版本至少为 1.0.200127001。

RGP 支持的 PIX3 事件检测函数包括：

void PIXBeginEvent(ID3D12GraphicsCommandList* commandList, ...)
void PIXEndEvent(ID3D12GraphicsCommandList* commandList)
void PIXSetMarker(ID3D12GraphicsCommandList* commandList, ...)

更新 PIX 头文件的步骤是：

  1. 将 RGP 包中提供的整个 samples\AmdDxExt 文件夹复制到 PIX 头文件（pix3.h、pix3_win.h）所在的目录（通常是 WinPixEventRuntime.[x.x]\Include\WinPixEventRuntime）。

  2. 在 PIXEvents.h 的顶部添加 #include "AmdDxExt\AmdPix3.h"

当使用 WinPixEventRuntime 版本 1.0.210209001 或更新版本时

#if defined(USE_PIX) || !defined(PIX_XBOX)
  #define PIX_CONTEXT_EMIT_CPU_EVENTS


  #ifndef PIX_XBOX
    #include "AmdDxExt\AmdPix3.h"
    #define PIX_AMD_EXT
  #endif
#endif

当使用 WinPixEventRuntime 版本 1.0.200127001 时

#include "PIXEventsCommon.h"


#if defined(XBOX) || defined(_XBOX_ONE) || defined(_DURANGO)
# define PIX_XBOX
#else
#include "AmdDxExt\AmdPix3.h"
#endif
  1. 更新 PIXEvents.h 文件，为现有的 PIXBeginEventOnContextCpu、PIXEndEventOnContextCpu 和 PIXSetMarkerOnContextCpu 调用添加 Rgp 前缀。

当使用 WinPixEventRuntime 版本 1.0.231030001 或更新版本时

#ifdef PIX_CONTEXT_EMIT_CPU_EVENTS
#ifdef PIX_AMD_EXT
  RgpPIXBeginEventOnContextCpu(destination, eventSize, context, color, formatString, args...);
#else
  PIXBeginEventOnContextCpu(destination, eventSize, context, color, formatString, args...);
#endif
#endif
#ifdef PIX_CONTEXT_EMIT_CPU_EVENTS
#ifdef PIX_AMD_EXT
  RgpPIXSetMarkerOnContextCpu(destination, eventSize, context, color, formatString, args...);
#else
  PIXSetMarkerOnContextCpu(destination, eventSize, context, color, formatString, args...);
#endif
#endif
#ifdef PIX_CONTEXT_EMIT_CPU_EVENTS
#ifdef PIX_AMD_EXT
  RgpPIXEndEventOnContextCpu(destination, context);
#else
  destination = PIXEndEventOnContextCpu(context);
#endif
#endif

当使用 WinPixEventRuntime 版本 1.0.210209001 到 1.0.230302001 时

#ifdef PIX_CONTEXT_EMIT_CPU_EVENTS
#ifdef PIX_AMD_EXT
  RgpPIXBeginEventOnContextCpuLegacy(context, color, formatString, args...);
#else
  PIXBeginEventOnContextCpu(context, color, formatString, args...);
#endif
#endif
#ifdef PIX_CONTEXT_EMIT_CPU_EVENTS
#ifdef PIX_AMD_EXT
  RgpPIXSetMarkerOnContextCpuLegacy(context, color, formatString, args...);
#else
  PIXSetMarkerOnContextCpu(context, color, formatString, args...);
#endif
#endif
#ifdef PIX_CONTEXT_EMIT_CPU_EVENTS
#ifdef PIX_AMD_EXT
  RgpPIXEndEventOnContextCpuLegacy(context);
#else
  PIXEndEventOnContextCpu(context);
#endif
#endif

当使用 WinPixEventRuntime 版本 1.0.200127001 时

#if PIX_XBOX
  PIXBeginEvent(color, formatString, args...);
#else
#ifdef PIX_AMD_EXT
  RgpPIXBeginEventOnContextCpuLegacy(context, color, formatString, args...);
#else
  PIXBeginEventOnContextCpu(context, color, formatString, args...);
#endif
#endif
#if PIX_XBOX
  PIXEndEvent();
#else
#ifdef PIX_AMD_EXT
   RgpPIXEndEventOnContextCpuLegacy(context);
#else
   PIXEndEventOnContextCpu(context);
#endif
#endif
#if PIX_XBOX
  PIXSetMarker(color, formatString, args...);
#else
#ifdef PIX_AMD_EXT
  RgpPIXSetMarkerOnContextCpuLegacy(context, color, formatString, args...);
#else
  PIXSetMarkerOnContextCpu(context, color, formatString, args...);
#endif
#endif
  1. 重新编译应用程序。请注意，当相应的 PIX 事件检测也使用以下预处理器符号之一启用时，RGP 用户标记才会被启用：USE_PIX、DBG、_DEBUG、PROFILE 或 PROFILE_BUILD。

应用程序中的 PIX3 事件检测可继续用于 Microsoft PIX 工具，而不会产生额外的副作用或开销。

有关如何使用 PIX 事件检测的更完整说明，请参阅 https://blogs.msdn.microsoft.com/pix/winpixeventruntime/。

在 https://github.com/Microsoft/DirectX-Graphics-Samples 上查看 PIX 事件检测用法的许多示例。

使用 AGS 实现 DirectX12 用户调试标记 AMD GPU Services (AGS) 库为软件开发者提供了查询 AMD GPU 软件和硬件状态信息的能力，而这些信息通常无法通过标准操作系统或图形 API 获取。AGS 支持查询图形驱动程序版本信息、GPU 性能、CrossFire™（AMD 的多 GPU 渲染技术）配置信息以及 Eyefinity（AMD 的多显示器渲染技术）配置信息。AGS 还公开了显式 Crossfire API 扩展、GCN 着色器扩展以及 AMD 驱动程序对 DirectX® 11 和 DirectX 12 所支持的其他扩展。AGS 的一项功能是支持 DirectX 12 用户调试标记。

可以使用 AGS 函数调用将用户标记插入到您的应用程序中。然后，可以在 RGP 中查看这些插入的用户标记。获取用户标记的主要步骤如下：

有关 AGS 的文章和博客可以在这里找到：/amd-gpu-services-ags-library/

AGS 的其他 API 文档可以在这里找到：https://gpuopen-librariesandsdks.github.io/ags/

下载 AGS 从：https://github.com/GPUOpen-LibrariesAndSDKs/AGS_SDK/ 下载 AGS 库

该库包含预编译的 Windows 库、DLL、示例和文档。您需要使用以下两个目录中的文件。

  • 头文件：AGS_SDK-master\ags_lib\inc

  • 库文件：AGS_SDK-master\ags_lib\lib

将 AGS 头文件、库和 DLL 集成到您的项目中 AGS 需要一个头文件（amd_ags.h）包含在您的源代码中。将 AGS 头文件的位置添加到 Visual Studio 项目设置中，并在相关代码文件中包含该头文件。

#include “amd_ags.h”

将您的 exe 文件链接到适用于您项目的正确 AGS 库（32 位或 64 位，MD 或 MT 静态库，调试或发布，或 DLL）。

库名称需要 AGS Runtime DLL库类型
64 位amd_ags_x64.libamd_ags_x64.dllDLL
amd_ags_x64_2015_MD.lib不适用VS2015 库（多线程 DLL 运行时库）
amd_ags_x64_2015_MT.lib不适用VS2015 库（多线程静态运行时库）
amd_ags_x64_2015_MDd.lib不适用VS2015 库（调试多线程 DLL 运行时库）
amd_ags_x64_2015_MTd.lib不适用VS2015 库（调试多线程静态运行时库）
amd_ags_x64_2017_MD.lib不适用VS2017 库（多线程 DLL 运行时库）
amd_ags_x64_2017_MT.lib不适用VS2017 库（多线程静态运行时库
amd_ags_x64_2017_MDd.lib不适用VS2017 库（调试多线程 DLL 运行时库）
amd_ags_x64_2017_MTd.lib不适用VS2017 库（调试多线程静态运行时库）
amd_ags_x64_2019_MD.lib不适用VS2019 库（多线程 DLL 运行时库）
amd_ags_x64_2019_MT.lib不适用VS2019 库（多线程静态运行时库
amd_ags_x64_2019_MDd.lib不适用VS2019 库（调试多线程 DLL 运行时库）
amd_ags_x64_2019_MTd.lib不适用VS2019 库（调试多线程静态运行时库）
32 位amd_ags_x86.libamd_ags_x86.dllDLL
amd_ags_x86_2015_MD.lib不适用VS2015 库（多线程 DLL 运行时库）
amd_ags_x86_2015_MT.lib不适用VS2015 库（多线程静态运行时库）
amd_ags_x86_2015_MDd.lib不适用VS2015 库（调试多线程 DLL 运行时库）
amd_ags_x86_2015_MTd.lib不适用VS2015 库（调试多线程静态运行时库）
amd_ags_x86_2017_MD.lib不适用VS2017 库（多线程 DLL 运行时库）
amd_ags_x86_2017_MT.lib不适用VS2017 库（多线程静态运行时库）
amd_ags_x86_2017_MDd.lib不适用VS2017 库（调试多线程 DLL 运行时库）
amd_ags_x86_2017_MTd.lib不适用VS2017 库（调试多线程静态运行时库）
amd_ags_x86_2019_MD.lib不适用VS2019 库（多线程 DLL 运行时库）
amd_ags_x86_2019_MT.lib不适用VS2019 库（多线程静态运行时库
amd_ags_x86_2019_MDd.lib不适用VS2019 库（调试多线程 DLL 运行时库）
amd_ags_x86_2019_MTd.lib不适用VS2019 库（调试多线程静态运行时库）

初始化 AGS 项目构建后，首先要做的是初始化 AGS 上下文。

// Specify AGS configuration (optional memory allocation callbacks)
AGSConfiguration config = {};


// Initialize AGS
AGSReturnCode agsInitReturn = agsInitialize(AGS_MAKE_VERSION(AMD_AGS_VERSION_MAJOR, AMD_AGS_VERSION_MINOR, AMD_AGS_VERSION_PATCH), &config, &m_AGSContext, &m_AmdgpuInfo);


// Report error on AGS initialization failure
if (agsInitReturn != AGS_SUCCESS)
{
        printf("\\nError: AGS Library was NOT initialized - Return Code %d\\n", agsInitReturn);
}

初始化 DirectX12 扩展成功创建 AGS 扩展后，需要创建 DirectX12 扩展，如下所示：

// Create the device using AGS
AGSDX12DeviceCreationParams dxCreateParams = {hardwareAdapter.Get(), __uuidof(ID3D12Device), D3D_FEATURE_LEVEL_11_0};
AGSDX12ReturnedParams dxReturnedParams;
AGSReturnCode dxInitReturn = agsDriverExtensionsDX12_CreateDevice(m_AGSContext, &dxCreateParams, nullptr, &dxReturnedParams);


// Report error on AGS DX12 device creation failure
if (dxInitReturn != AGS_SUCCESS)
{
        printf("Error: AGS DX12 extension could not create a device - Return Code %d\n", agsInitReturn);
}
else
{
        printf("AGS DX12 device was created.\n");
        m_device = dxReturnedParams.pDevice;


        // Check whether user markers are supported by the current driver
        if (dxReturnedParams.extensionsSupported.userMarkers == 1)
        {
                printf("AGS_DX12_EXTENSION_USER_MARKERS are supported.\n");
        }
        else
        {
                printf("AGS_DX12_EXTENSION_USER_MARKERS are NOT supported.\n");
        }
}

请注意，上面的代码通过检查驱动程序支持的扩展来判断驱动程序是否能够支持用户标记。此步骤在旧版驱动程序上可能会失败。

在应用程序中插入标记 AGS 提供的用于标记应用程序的主要函数是：

agsDriverExtensionsDX12_PushMarker;
agsDriverExtensionsDX12_PopMarker;
agsDriverExtensionsDX12_SetMarker;

下面的示例展示了如何将一个绘制调用包含在“绘制粒子”用户标记中，然后插入一个标记。

// Push a marker
agsDriverExtensionsDX12_PushMarker(m_AGSContext, pCommandList, "DrawParticles");


// This draw call will be in the "Draw Particles" User Marker
pCommandList->DrawInstanced(ParticleCount, 1, 0, 0);


// Pop a marker
agsDriverExtensionsDX12_PopMarker(m_AGSContext, pCommandList);


// Insert a marker
agsDriverExtensionsDX12_SetMarker(m_AGSContext, pCommandList, "Finished Drawing Particles");

Vulkan 用户标记

调试工具扩展 Vulkan 支持使用 VK_EXT_debug_utils 扩展的用户调试标记。可以在这里查看有关此扩展的文档：

https://www.lunarg.com/wp-content/uploads/2018/05/Vulkan-Debug-Utils_05_18_v1.pdf

代码示例可以在这里找到：

https://github.com/SaschaWillems/Vulkan/blob/master/examples/debugutils/debugutils.cpp

调试标记扩展较旧的、已弃用的扩展 VK_EXT_debug_marker 也存在。以下文章详细介绍了这个较旧的扩展：

https://www.saschawillems.de/blog/2016/05/28/tutorial-on-using-vulkans-vk_ext_debug_marker-with-renderdoc/

RGP 支持 VK_EXT_debug_utils 和 VK_EXT_debug_marker 扩展。通过这些扩展插入的用户标记应该会在您的 RGP 配置文件中生成用户事件，您可以在 RGP 用户界面中查看这些事件。

查看用户标记

上面应用程序的一个帧捕获的 RGP 文件包含许多用户标记。当您选择“按用户标记分组”选项时，可以在“事件时序”和“管线状态”视图中看到用户标记，如下图所示：

“绘制粒子”用户标记，绘制调用包含在用户标记中

当按用户事件着色时，用户标记也可以在波前占用率视图中看到。在事件时序视图中也可以按用户事件着色。如上所示，同一用户标记包含的任何事件都将显示为相同的颜色。未包含在用户标记中的事件显示为灰色。着色仅受 Push/PopMarker 组合的影响；SetMarker 对用户事件颜色没有影响，因为这些标记只是标记一个特定的时间点。

此外，用户事件名称显示在事件时间线视图顶部的叠加层中。

完整的用户事件层次结构在单击单个事件时，在侧边窗格的第三行也可以看到。如果事件不包含用户事件层次结构，则不会显示任何内容。

包含在用户标记中的事件在波前占用率视图中着色。它们也显示在侧边面板中。

© . This site is unofficial and not affiliated with AMD.