Using SHADERed to create a Windows Terminal shader

Introduction

SHADERed can be a valuable tool for helping you develop shaders for the Microsoft Windows Terminal. SHADERed is an open-source cross-platform tool which can help you write HLSL and GLSL shaders with a built-in debugger to assist that process.

The WindowsTerminal.sprj is a SHADERed project file template which includes everything needed to get started.

Getting Started

1. Install SHADERed. If you aren't familiar with Scoop, it is a very convenient system for installing and maintaining programs.
2. Download the WindowsTerminal.sprj zip archive and extract to the location you want to write your shader. Links to WindowsTerminal.sprj still to be provided
3. Open SHADERed.
4. From the File menu, navigate to where you saved the project template and open the WindowsTerminal.sprj file.

WindowsTerminal.sprj file layout

File	Description
WindowsTerminal.hlsl	The shader which will be used by Windows Terminal. This and maybe the image file should be the only files you need to modify.
sample.png	A .png screen capture of a terminal window representative of what might be seen. This can be replaced with another image, but it is discouraged to delete the image from the project and add a new one because of the additional settings required for things to work smoothly. Just replace the image on disk and reload the project for it to take effect.
---	---
WindowsTerminal.sprj	The SHADERed project file
SHADERed\SHADERed.hlsl	Used by SHADERed to render and pass expected values for the pixel shader
SHADERed\Debug.hlsl	Used by SHADERed to provide useful debug output
SHADERed\GeometryPatch.hlsl	Used by SHADERed to translate the coordinate geometry used with SHADERed to the coordinate geometry expected by Windows Terminal.

Integrating with Windows Terminal

It is recommended to create a .terminal folder under your user profile and keep links to your shader files there.

Create a folder for your shaders

Command Prompt	Windows PowerShell
C:>md "%USERPROFILE%\.terminal"	PS >md "$env:userprofile\.terminal"

Link your shader to a file in the .terminal folder

For PowerShell, "ni: Administrator privilege required for this operation." You must do this from an elevated PowerShell window.

Command Prompt	Administrator: Windows PowerShell
C:>mklink "%USERPROFILE%\.terminal\<DesiredShadername>.hlsl" "<ShaderTemplateDirectory>\WindowsTerminal.hlsl"	PS >ni -ItemType SymbolicLink -Path "$env:userprofile\.terminal\<DesiredShadername>.hlsl" -Target "<ShaderTemplateDirectory>\WindowsTerminal.hlsl"

Configure in Windows Terminal settings

Use Ctrl+, to open settings.json for Windows Terminal. With newer versions of Windows Terminal, use the Settings UI to follow the link to "Open JSON file."

{
  "profiles": {
    "defaults": {
       // Put settings here that you want to apply to all profiles.
       // Recommended only after testing in a regular profile first
       "experimental.pixelShaderPath": "<FullPathTo>\\.terminal\\<DesiredShadername>.hlsl",
    },
    "list" : [
      {
        // Make changes here to the <ProfileToChange> profile.
        "experimental.pixelShaderPath": "<FullPathTo>\\.terminal\\<DesiredShadername>.hlsl",
      },
    ]
  }
}

This makes the