Debug GLSL Variable States in NVIDIA Nsight Graphics

NVIDIA Nsight Graphics allows developers to inspect per-invocation variable states in GLSL shaders by isolating specific GPU workloads, instrumenting execution on hardware, and mapping underlying register data back to high-level source code. Through frame capture, hardware replay, and source-level correlation, developers can freeze shader execution at any stage and inspect the distinct runtime state of variables across individual threads, pixels, or vertices.

Invocation Selection and Workload Isolation

Before inspecting variable states, Nsight Graphics isolates the target shader invocation. Because modern GPUs execute thousands of shader invocations simultaneously in warps or wavefronts, Nsight Graphics provides tools such as the Pixel History tool for fragment shaders or the Resource Viewer for compute and mesh workloads.

A developer selects a specific target—such as an \((x, y)\) screen coordinate for a fragment shader, a vertex ID for a vertex shader, or a 3D thread coordinate (gl_GlobalInvocationID) for a compute shader. This selection restricts the debugger’s focus to a single execution thread or a specific active warp.

Shader Instrumentation and Hardware Replay

Once an invocation is selected, Nsight Graphics uses a replay-based debugging model:

  1. Draw Call Replay: The tool isolates the selected draw call or compute dispatch from the captured frame and replays it on the GPU.
  2. Dynamic Instrumentation: Nsight Graphics injects instrumentation instructions into the shader's binary or intermediate representation (SPIR-V or driver-internal assembly). This allows the tool to trace variable changes without altering the deterministic execution path of the draw call.
  3. Register Dumping: As the instrumented shader runs on the target Streaming Multiprocessor (SM), the values stored in physical GPU registers at each instruction are captured and buffered into GPU memory for readout.

Mapping Hardware Registers to GLSL Source

To make low-level GPU states readable, Nsight Graphics maps the raw register data back to high-level GLSL variable identifiers.

When shaders are compiled with debug information (such as through glslangValidator -g for Vulkan SPIR-V, or driver-retained symbols in OpenGL), the compiler embeds symbolic metadata and line-mapping tables. Nsight Graphics reads this metadata to associate physical hardware registers and memory offsets with specific GLSL variable names, data types, and scopes.

If debug symbols are missing, the debugger falls back to displaying compiled intermediate assembly (such as SPIR-V or NVVM) alongside raw hardware register states.

Interactive Stepping and Context Switching

With the invocation data mapped, the debugger exposes the state through an interactive debugging interface:

  • Variable Inspection Windows: The Locals and Watch windows display current values for uniforms, input attributes, output varyings, temporary variables, and buffers relevant to the selected invocation.
  • Instruction Stepping: Developers can step forward through GLSL source lines or assembly instructions. At each step, modified variables highlight dynamically to reflect state changes.
  • Warp and Lane Switching: Because GPU hardware executes threads in lockstep groups (warps), Nsight Graphics allows developers to toggle between active lanes within the same warp. This reveals how conditional branching (such as if-else blocks or divergent dynamic loops) alters variables across neighboring invocations.