Shader Authoring

This document describes how to author shaders in the Source SDK, for further information on what a shader is and how they can be used, please see Shader.

Getting Started

Every material that is used in Source specifies which shader it uses to render itself. The shader contains the logic and equations to take the source artwork and lighting, and produce the final rendered color for every pixel that the shader is used on.

The Source SDK fully supports Microsoft DirectX HLSL (High-Level Shading Language) and shader assembly languages for writing shaders. It is recommended to use HLSL whenever possible and to only write shader assembly as a last resort.

There are a number of external tools required to compile shaders for use in the Source SDK, the following sections detail the tools and provide links for download along with brief instructions on installation and usage.

The tools used are Perl, the DirectX SDK and make, the following processes, in general, only have to be performed once before the process of compiling shaders can begin.

Options for Building Shaders

Option 1 - Perl & DirectX SDK

Perl

To install Perl, go to the download page on https://www.perl.com/, download, and install Perl - a recommended version of Perl for Windows is Strawberry Perl.

The Orange Box SDK also relies on the non-standard Perl package, String::CRC32. If you are using Strawberry Perl, you can install it through the CPAN Client which can be launched from <StrawberryPerlInstallDir>\perl\bin\cpan.bat

Enter the following command to install the package: install String::CRC32

Note:If you have problems with cpan.bat, try to open PowerShell in <StrawberryPerlInstallDir>\perl\bin\ and run command: cpan String::CRC32

DirectX SDK

To install the November 2008 DirectX SDK, go to https://archive.org/details/dxsdk_nov08, download, and install the DirectX SDK (The old Microsoft link is dead, so we need to use the Wayback Machine).

Note:Just having DirectX 9.x installed is not sufficient, the DirectX SDK must be installed!

Note:It is recommended that you use the November 2008 SDK as needed binaries (psa.exe, vsa.exe) have been removed from newer releases.

Setting The Path

With Perl and the DirectX SDK installed, make sure your "Path" environmental variable has been updated appropriately. In Windows, you can check this by right clicking on My Computer -> properties, going to the Advanced tab, and clicking on "Environment Variables". Assuming that Perl is installed into C:\Perl, and DirectX into C:\DXSDK, your "Path" variable should contain both C:\Perl\bin and C:\DXSDK\Utilities\bin\x86 in a semicolon delimited list.

By setting up the Environmental Variable in this way, you can update the Perl and DirectX SDK as you please without having to copy files. If for some reason you do not wish to do this, you can simply copy the required files into a different directory and add that to your path instead.

Note:You may need to restart your computer for these changes to the environment to take full effect.

Option 2 - SCell555's Shader Compiler

To install SCell555's Shader Compile tools, you must download the zip file which they provide with every release.

Once you have downloaded the zip (or .7z) file, open it up and you should see the following folders:

• bin
• headers
• stdshaders

Place the bin folder into the devtools folder.

Place the stdshaders folder into the materialsytem folder. If it asks you to replace the files, say yes.

Navigate into the headers folder in the zip. You should see a cshader.h file and a VS2013 folder (which also contains another cshader.h file). If you are using Visual Studio 2013 or above, place the cshader.h in the VS2013 folder into public\shaderlib and replace it. If you are using a Visual Studio version before 2013, use the cshader.h file that isn't in the VS2013 folder instead.

Completing the Setup

Modify stdshader_dx9_20b.txt

Open up materialsystem/stdshaders/stdshader_dx9_20b.txt and comment out all of the lines which compile shaders like so:

//
// Standard shaders collection
//
//  These shaders are compiled as the following shader models:
//        _ps20.vcs
//        _ps20b.vcs
//        _vs20.vcs
//
//example_model_ps20b.fxc
//example_model_vs20.fxc
//SDK_Bloom_ps2x.fxc
//SDK_screenspaceeffect_vs20.fxc
//SDK_bloomadd_ps2x.fxc

Modify buildepisodicshaders.bat

Open src\materialsystem\stdshaders\buildepisodicshaders.bat and set the GAMEDIR AND SDKBINDIR as instructed.

Inside buildsdkshaders.bat, you might also need to modify the call to vsvars32.bat on line 7 - If you are using Visual Studio 2013 it should point to %VS120COMNTOOLS% instead.

Note: GAMEDIR AND SDKBINDIR must be kept to the 8.3 directory name standard.

rem == Set the absolute path to your mod's game directory here ==
rem == Note that this path needs does not support long file/directory names ==
rem == So instead of a path such as "C:\Program Files\Steam\steamapps\mymod" ==
rem == you need to find the 8.3 abbreviation for the directory name using 'dir /x' ==
rem == and set the directory to something like C:\PROGRA~2\Steam\steamapps\sourcemods\mymod ==
set GAMEDIR= YOUR PATH HERE

rem == Set the relative path to SourceSDK\bin\orangebox\bin ==
rem == As above, this path does not support long directory names or spaces ==
rem == e.g. ..\..\..\..\..\PROGRA~2\Steam\steamapps\<USER NAME>\sourcesdk\bin\orangebox\bin ==
set SDKBINDIR= YOUR PATH HERE

Shader Compile

Example of a successful compile.

Navigate into the materialsystem\stdshaders folder. Then type in the name of the bat file for compiling your shaders; it will probably be buildepisodicshaders.bat. If you did everything correctly, it should compile with no issues.

Warning:You will encounter errors about D3DVERTEXTEXTURESAMPLER0 being undefined when using SCell555's compiler. The fix is to simply remove any references to this definition from register functions in the Vertex Shader files.

Todo: List which files that have register( D3DVERTEXTEXTURESAMPLER0, s0 ) in them to make finding the references easier.

Warning:SCell's shader compiler doesn't produce any Pixel Shader files below 2.0b, and no Vertex Shader files below 2.0. The stock SDK shaders rely on fallbacks to lower versions of these files and, thus will need to be modified to account for this limitation.

See also

• You can get more information about HLSL and shader assembly programming in the online MSDN docs.
• Category:Material System -- for more general information on the usage of shaders in materials.