Is this page helpful?

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

Function debug information is used by Flame Graph, Top-Down Calls, Bottom-Up Calls, and Shader Editing. It also enables accurate source correlation for high-level function call sites in Shader Profiler views.

For SPIR-V shaders, the SPIR-V NonSemantic Shader DebugInfo extension is required to provide function debug information. The following compiler-specific guidance explains how to emit the extension.

For SPIR-V compiled with dxc, add -fspv-debug=vulkan-with-source. When debug information is enabled, Slang emits NonSemantic debug information and generally provides reliable function and call-site information.

For SPIR-V compiled with glslangValidator, add -gVS instead of -g. You can also try -Os to encourage the compiler to inline functions in the SPIR-V. This combination may improve call-site correlation, but -Os is a size-optimization option rather than a guarantee that functions will be inlined. Some shaders may also fail to compile when NonSemantic debug information is enabled, so results can vary.

Applications that compile through shaderc should verify that their shaderc version and compilation path can emit NonSemantic debug information. Without this information, function-level and call-site correlation is unavailable.

When function calls remain uninlined in the SPIR-V and sufficient call-site information is unavailable, Nsight Graphics cannot reliably attribute generated instructions to individual high-level call sites.

Note

glslangValidator versions earlier than 15.0.0 have a known issue where all DebugFunction instructions reference the same file. This leads to incorrect correlation between function names and source line numbers. Use glslangValidator 15.0.0 or later to avoid this issue.

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