Deshader 🔦

Shaders are often shiny but sometimes also shady, fishy and stinky!

What if I could just step-debug that shader as I do with my CPU programs?

Now you can, and in your favorite code editor¹! Deshader intercepts OpenGL calls and adds instrumentation code to your shaders (so you don't need to write your own visualizations to debug shader execution process anymore).

Features

• Step through the shader execution (...breakpoints, logging, conditional bps...)
• Arrange shaders in a virtual filesystem (#include friendly!)
• Track variable values for different output primitives and pixels
• Incrementally visualise primitive and pixel output (so you can fix that weird vertex!)
• Open the integrated editor (VSCode in a separate window or in your browser - at localhost:8080/index.html by default)
• Runs on Linux, Windows and macOS

Goals

• Compatibility between OpenGL vendor implementations (ICDs)
• Flexibility
• Broader API support than GLIntercept, different features than ApiTrace

Non-goals

...and some dead ends, which have been encountered.

• Debugging other languages than GLSL (feel free to fork and add your own language)
• Vendor API/ISA level debugging
• Assembly (ISA) or pseudo-assembly (SPIR-V) level debugging
• Profiling
• Custom WebView profile data directory
• Cross compilation for macOS

Possible future goals

• View assembly
  • SPIR-V (compile by GLSLang)
  • ISA level (nvdisasm, nvcachetools, envytools)
• Vulkan support
• Profiling
• Validation
• Modular instrumentation API

Feel free to fork and add your own goals or even better, break the non-goals!

Installation

Prebuilt packages

Packages for macOS, Debian-like, Arch Linux and Windows are in the releases section.

Arch Linux (AUR)

Download and install using an AUR helper. For example, Yay:.

yay -S deshader-git

or

pamac build deshader-git

Build and packaging scripts

Build scripts for Debian-like and Arch Linux reside in a separate repository.

Usage

Display the Launcher GUI:

deshader-run

Advanced instructions are contained in Deshader Manual.

Build

Components

Deshader consists of several (mostly third party; mostly forked) components that require different dev stacks and frameworks. Some of them are installed as git submodules or as Zig dependencies.

• Deshader Launcher
  • /src/launcher/launcher.zig
• Deshader library
  • /src/
  • Web View (WebKit2Gtk) at /libs/positron/ (MIT)
  • Example applications
    • /examples/
  • Fork of GLSL Analyzer at /libs/glsl_analyzer/ (GPL-3.0)
• Deshader VSCode extension
  • /editor/deshader-vscode/ (MIT)
  • With node.js packages
  • Managed by Bun
• A distribution of Visual Studio Code for web (MIT)
  • /editor/
  • With node.js packages
  • Managed by Bun

Requirements

• Zig 0.14 (MIT)

• Bun 1.2.8 Install (MIT)

• VCPKG (MIT)

  • Make sure you are using the latest version
  • VCPKG may download another dependencies, such as pwsh on Windows, cmake...

• C libraries

  • Linux
    • gtk-3 (LGPL-2.1) and webkit2gtk 4.0-4.1 (BSD, LGPL-2.1)
  • Windows
    • Edge Dev Channel
    • WebView2 runtime
  • Cross-compilation under Linux
    • for Windows
      • install Wine
      • add VCPKG path to ~/.local/share/vcpkg/vcpkg.path.txt (e.g. echo $(which vcpkg) > ~/.local/share/vcpkg/vcpkg.path.txt)
      • Edge Dev Channel installed by offline installer
      • WebView2 runtime must be installed by standalone installer (not bootstraper) under Wine
      • zig build deshader -fwine -Dtarget=x86_64-windows
      • NOTES
        • DLL interception does not work for OpenGL under Wine. Intercept on host side instead (however this does not really work for now)

• Building examples requires Vulkan SDK (mixed licenses...) (for GLFW)

• for Linux and macOS:

  • pkg-config
  • ld from binutils package

• for Windows (installable by Visual Studio Installer):

  • Build Tools

• Examples on macOS require gcc

Building from source

After you install all the required frameworks, clone this repository with submodules, open terminal in its folder and create a debug build by

git clone --recurse-submodules https://github.com/OSDVF/deshader # git submodule update --init --recursive # if you cloned non-recursively
cd deshader
zig build deshader

There are multiple ways how to use Deshader. For example, Deshader Launcher can be built and used like this:

# Build Launcher
zig build launcher

# Use Launcher as command line tool
./zig-out/bin/deshader-run your_application

# Or display Launcher GUI
./zig-out/bin/deshader-run

# Or run & build all the provided examples one-by-one
zig build examples-run

If Launcher is not able to find Deshader library, you can specify it in environment variable:

DESHADER_LIB=zig-out/lib/libdeshader.so deshader-run

Deshader and its build process support some configuraiton options.

Usage Without Launcher

Linux

DESHADER_LIB=your/lib/dir/libdeshader.so /your/app/dir/app # Loads Deshader into your application

Windows

copy path\to\deshader.dll your\app\dir\opengl32.dll
copy path\to\libwolfssl.dll path\to\glslang.dll path\to\WebView2Loader.dll your\app\dir
your\app\dir\app.exe

Mac OS

DYLD_INSERT_LIBRARIES=./zig-out/lib/libdeshader.dylib your_application

Frequently Seen Build Errors

• Cannot compile
  • Something with struct_XSTAT inside WolfSSL
    • fix by powershell .\fix_c_import.sh or ./fix_c_import.ps1 and build again CAUTION: The script searches the whole zls global cache in ~/.cache/zls and deletes lines with struct_XSTAT so be careful.
• Segmentation fault at when starting application from Launcher GUI
  • Check if Launcher is build with the same tracing and release options as Deshader
• Editor window is blank
  • This is a known issue between WebKit and vendor GL drivers
  • Disable GPU acceleration
    • Set environment variable WEBKIT_DISABLE_COMPOSITING_MODE=1
  • Or select a different GPU
    • by setting __GLX_VENDOR_LIBRARY_NAME=nvidia __NV_PRIME_RENDER_OFFLOAD=1
    • or DRI_PRIME=1

Build process

Deshader components are built with different build systems. They are being called inside the main build process (zig build ...). The notes here are just for reference:

Editor

• Installing Node.js dependencies
  • bun install inside /editor/ and /editor/deshader-vscode/
• Compiling Deshader VSCode Extension
  • bun compile-dev or bun compile-prod inside /editor/deshader-vscode/

VCPKG Dependencies

• Installing VCPKG managed libraries (when target is Windows, or they are not present or system) and correct ther names

  GLEW, GLSLang, GLFW, WolfSSL, nativefiledialog
  • vcpkg install --triplet=x(86/64)-[os](-zig) --x-install-root=build/vcpkg_installed
  • Rename .dll.a -> .lib in build/vcpkg_installed/*/lib

Zig dependencies

Some of the dependencies are managed as git submodules, other are specified in build.zig.zon. zig build without additonal target name will only download Zig-managed dependencies.

Build Outputs

Output files will be placed at ./zig-out/:

• bin/

  • deshader-run
  • (internal tools)
    • generate_headers
    • generate_stubs
  • deshader-examples-all
  • deshader-examples/
    • quad
    • editor
    • quad_cpp
    • editor_cpp

• lib/ (also bin/ for Windows)

  • (lib)deshader.[a|so|dll|lib|dylib]
  • (dependencies for Windows version)
    • libwolfssl.dll
    • glslang.dll
    • WebView2Loader.dll

• include/

  • deshader
    • commands.h
    • macros.h
    • deshader.h
    • deshader.hpp
    • deshader.zig
    • deshader_prefixed.zig

The files inside include/ are API definitions for use in your application.

License

Deshader is licensed under the GPL-3.0 license. See LICENSE for more information.
This repository also contains third-party software, which is licensed under their respective licenses. See NOTICES for more information.

If Deshader saved some of your time, you can leave a comment in the discussions or star the repo.

Footnotes

1. VSCode derivatives and the standalone Deshader Editor is supported for now. You can also: ↩