Debugging HLSL & GLSL shaders in VS Code

2021-05-20 14:28:08

SHADERed v1.5.3 ships with a built-in Debug Adapter Protocol (DAP) support. This means that SHADERed's debugger can be accessed by any other IDE/text editor that supports DAP. Though, today I am showcasing this feature solely with VS Code and a newly released VS Code extension.
This extension brings shader debugging to Visual Studio Code. Here's a simple tutorial on how to get started:


Setting up

To get started, first you need to install the VS Code extension. You can do this directly through Visual Studio Code:

SHADERed extension

If the extension doesn't show up in the search for some reason, you can go to https://marketplace.visualstudio.com/items?itemName=dfranx.shadered and manually install the plugin or compile it by yourself from the source code: https://github.com/dfranx/vscode-shadered.

Once you've got the extension installed, you need to tell VS Code the location of your SHADERed executable (you have to have SHADERed downloaded for this extension to work!). You can do this by going to the Settings (FilePreferencesSettings) and searching for "shadered". A textbox will appear where you have to enter the path to your SHADERed executable.

Visual Studio Code SHADERed settings


Now that VS Code knows the location of SHADERed, open a directory/workspace which contains a SHADERed project file (.sprj). To start the debugger, either open the .sprj file in the text editor or add the .vscode/launch.json file to your workspace with the following code:

VS Code project launch.json

and then press the F5 key. Without the launch.json file, you will always have to change focus to a .sprj file in VS Code before you press the F5 key.

Debugging HLSL & GLSL shaders

With this extension you can debug both HLSL and GLSL shaders.
Once you've opened your project, select a pixel by left clicking on it. SHADERed will pause the preview and you will be able to pick the shader stage that you'd like to debug. You can debug vertex, pixel, geometry, compute & tessellation control shaders. To start the actual debugger, click on the "play" button. You will now be able to:

Besides debugging, you can also see your shader's output as you edit the code. When you save your changes to a file, SHADERed will automatically detect them and recompile the shaders.

Prototyping shaders in VS Code


Watches

You can add watches through Visual Studio Code's user interface. Watches will tell you the value of your expression. The value will be updated as you step through your shader's code. You can also see list of all variables and their values.

Watches and variables


Run immediate expressions

If you want to see the result of an expression without having to add it as a watch, you can enter the custom expressions in VS Code's Debug Console window.

Running shader immediate expressions


Breakpoints

You can add breakpoints to your shaders. The debugger will pause the execution when it hits the breakpoint. These breakpoints can also have a condition (the debugger will only pause when the condition has been met)

Adding breakpoints to shaders


Inline values & hover

If you've got the "debug.inlineValues" option turned on, VS Code will show variable values next to the each line. You can also hover over a variable's name to see it's value.

Hovering over variables while debugging shaders


Debugging geometry shaders

Besides vertex and pixel shaders, you can also debug geometry shaders. A window showing GS output will open when you start the geometry shader debugger.

Debugging geometry shader in VS Code


Debugging compute shaders

Debugging compute shaders with this extension is somewhat limited. There's currently no way to start debugging a specific thread (though, this can be done through standalone SHADERed). You can only initiate the CS debugger through the so-called "suggestions" (these suggestions are thread ID predictions made by SHADERed):

Debugging compute shader in VS Code


What's next

Before I say what's planned for the next release of SHADERed, I just want to mention again that the DAP support added to SHADERed is in no way specific to VS Code -- SHADERed can now be 'linked' with any other tool that implements DAP.
Here are some of the things I plan to do next:

  1. I've seen that emitting OpLine opcode has possibly been added to rust-gpu so I'd like to add rust-gpu shader debugging to SHADERed (+ it'd automatically be supported by this extension).
  2. SHADERed currently uses OpenGL but the main focus of the next update will be abstracting the renderer. I will be doing this so that I can then easily implement the WebGPU backend (which, by the way, is not coming in the next update) without needing to change lots of code (+ in the future if I ever get my hands on a RTX card, I'd be able to add Vulkan backend easily).
  3. I also plan to release two plugins (Unity shaders & node based shaders). The node-based shaders plugin will probably come out before the next SHADERed update, while the Unity one might require new Plugin API capabilities (so I will most likely also have to update the Plugin API for it to work, meaning that Unity shaders will come sometimes after the next release).

Not sure when I'll drop the next update since abstracting the renderer will be a lot of work.

If your company uses (and/or likes) SHADERed, please do consider sponsoring the project as SHADERed is completely free & open-source.

I'd also like to mention that SHADERed v1.0 turns 2 years old on June 28th so I'd like to thank everyone for using it, supporting the development, giving feedback, etc... It means a lot! <3