Configuring Your Application for Optimal Analysis#

In order for your application to work well with the analysis tools provided by Nsight Graphics, there are a number of details you should consider when configuring your application.

Using Performance Markers#

Performance markers are integral to nearly all workflows. We recommend that your application always run with perf markers when running under tools analysis.

Performance markers are most commonly used to delineate sections of events and note where in your application they begin and end. They can also be nested to show sub-sections of events. Perf markers are generally used to measure the amount of time that an inner portion of algorithm takes.

There are multiple different types of perf markers that are supported in Nsight Graphics:

  • D3D9 perf markers are supported for all D3D applications.

  • ID3DUserDefinedAnnotation may be used for D3D11 or D3D12 applications. See ID3DUserDefinedAnnotation interface on MSDN.

  • Perf markers made available by Microsoft’s PIXBeginEvent/PixEndEvent APIs are supported for D3D12. See https://devblogs.microsoft.com/pix/winpixeventruntime/.

  • Vulkan applications may use either VK_EXT_debug_utils or VK_EXT_debug_marker.

  • OpenGL applications use the KHR_debug group, glPushDebugGroup and glPopDebugGroup.

Shader Compilation#

Nsight Graphics works best when you have the full shader source available for debugging. Follow the steps below to set up your application for optimal configuration.

D3D Configuration

Nsight Graphics works best with access to the original HLSL source code of your shaders. There are a few ways to accomplish this task. The first is to precompile the shaders into binary format using the using one of the legacy D3DCompile functions or the latest IDxcCompiler interfaces and saving the results out to a file.

Alternatively, you can use the offline compiler, fxc.exe or dxc.exe, provided by the DirectX SDK.

For each of these methods, you need to specify some flags in order for the HLSL debug information to be embedded in the binary output, outlined below:

Compile type

Required actions

Shaders compiled offline via dxc.exe or fxc.exe

Add "-Zi" option to the command line to get full debug info, such as linetable info required for shader profiling.

For dynamic shader editing, you can retrieve a minimal set of debug info using the "-Zs" option to the pArguments parameter.

Shaders compiled online via IDxcCompiler3::Compile

Add "-Zi" option to the pArguments parameter to get full debug info, such as linetable info required for shader profiling.

For dynamic shader editing, you can retrieve a minimal set of debug info using the "-Zs" option to the pArguments parameter.

Note that earlier versions of the Compile function, including IDxcCompiler::Compile and IDxcCompiler2::CompileWithDebug, are deprecated. Microsoft recommends the use of IDxcCompiler3::Compile as the alternative.

Shaders compiled online via D3DCompile, D3DCompile2, D3DCompileFromFile

Add the D3DCOMPILE_DEBUG flag to the Flags1 parameter.

Nsight Graphics also supports reading debug info from files that have been generated using the dxc.exe -Fd option. To load these external files, you need to set the appropriate path(s) in the Compiled Shader Symbol Paths section of the Search Paths.

Vulkan Configuration

Nsight Graphics works best with access to the original high-level source code of your shaders. To accomplish this, shaders need to be compiled with debug information in order for the original high-level source code to be embedded in the SPIR-V binary modules.

When using the glslangValidator tool, add -g flag to the shader compilation command line. For example:

glslangValidator -V shader.vert -o shader.spv -g

When using the dxc tool, add -Zi flag to the shader compilation command line. For example:

dxc -spirv -T ps_6_5 -E PSMain shader.frag -Fo shader.spv -Zi

Function Debug Information

To enable function debug information in SPIRV, which is the dependency of Flame Graph, Top-Down Calls and Bottom-Up Calls, we need to add the argument -gVS (instead of -g) for glslangValidator or -fspv-debug=vulkan-with-source for dxc, to enable the SPIRV NonSemantic Shader DebugInfo extension.

Note

There’s a known issue for glslangValidator that all DebugFunction instructions are referencing one same file. This leads to wrong correlation from function name to source line numbers. This bug is fixed after glslangValidator 15.0.0.

Naming Objects and Threads#

Many of Nsight Graphics’ views and analysis benefits from naming API objects and threads. Similar to perf markers, these names can help offer increased context for your analysis. The tables below list the supported methods for naming objects and threads.

Naming Objects

D3D11

No programmatic method; use Nsight-generated names

D3D12

ID3D12Object::SetName

OpenGL

glObjectLabel

Vulkan

vkDebugMarkerSetObjectNameEXT or vkSetDebugUtilsObjectNameEXT

Naming Threads#

Platform

Method

Windows

SetThreadNameDescription

Linux

Not yet supported