View source for Source SDK 2013: Shader Authoring

= Introduction =
Shaders are an important part of Source development. They allow you to create and utilize complex graphical effects that would not be possible with art assets alone. The intention of this page will be to serve as both an introduction to and a gateway for shader development '''specifically''' using the Source 2013 SDK. The [[Shader Authoring]] pages will be left untouched for historical purposes.

== Quick Links ==
Here are some useful shader pages for [[Source SDK 2013]]:
* [[Source SDK 2013: Your First Shader]] - An article that teaches you how to make a simple shader. Also discusses shader architecture for Source.
* [[Source SDK 2013: Your Second Shader]] - Introduces the concept of shader parameters.

== Assumptions ==
In order to avoid cluttering this page with tons of information, this guide assumes you've already checked out the Source 2013 SDK from GitHub. If you haven't, please follow the instructions on the [[Source SDK 2013]] page. This guide will further assume that you've built the SDK successfully before reading this page.

= Prerequisites =
== Installing Strawberry Perl ==
The Source SDK contains a bunch of Perl scripts that are run during the shader compile process. Naturally, to run these, you'll need to install Strawberry Perl. You should grab the 64-bit version from [https://strawberryperl.com/ here] and install it. When the installation completes, you will need to install the '''String::CRC32''' Perl module using the '''CPAN Client''' which you can find via the start menu. When both products are installed, open up a command prompt window and type:
<pre>perl -v</pre>
You should see output similar to the following:
<pre>This is perl 5, version 32, subversion 1 (v5.32.1) built for MSWin32-x64-multi-thread

Copyright 1987-2021, Larry Wall

Perl may be copied only under the terms of either the Artistic License or the
GNU General Public License, which may be found in the Perl 5 source kit.

Complete documentation for Perl, including FAQ lists, should be found on
this system using "man perl" or "perldoc perl".  If you have access to the
Internet, point your browser at http://www.perl.org/, the Perl Home Page.</pre>
If you see output similar to the above, it means Perl was installed successfully and you can continue.

= Setting up the build =
Previous versions of the Source SDK used to ship all of the code for the stdshader_dx9 module. This paradigm was abandoned in favor of using a custom game shader module approach. There are two advantages with this approach:
# You no longer need to build all of the base shaders that ship with the Source SDK.
#* Like <code>vertexlitgeneric</code> which had thousands of shader combinations.
# You can replace stock SDK shaders with your own implementation.
#* In theory all you'd need to do is create a shader with the same name.

== Creating your game_shader_dx9 project ==
Navigate to <code>src/materialsystem/stdshaders</code> and perform the following steps:
# Copy the <code>game_shader_dx9_episodic.vpc</code> file and rename it to <code>game_shader_dx9_<modname>.vpc</code>. 
#* Make sure you change the '''GAMENAME''' macro to point to your mod!
# Modify the <code>game_shader_dx9</code> section in <code>src/vpc_scripts/projects.vgc</code> so that it points to the game_shader_dx9_<modname>.vpc file you created in step 1.
# Create a batch file that actually generates a solution/makefile for the <code>shaders</code> project group or - much easier - use the [[Valve Project Creator]] to create the project directly.

== Creating a batch file to build shaders ==
You'll need to create a batch file that calls <code>buildsdkshaders.bat</code> in order to compile your shaders. Luckily, you can just re-use the batch files shipped with the SDK. Navigate to <code>src/materialsystem/stdshaders</code> and perform the following steps to create your batch file:
# Copy <code>buildepisodicshaders.bat</code> and rename it to <code>build<modname>shaders.bat</code>.
# Open up <code>build<modname>shaders.bat</code> in notepad and modify the following:
## Change '''GAMEDIR''' to wherever your mod directory is located at.
## Change '''SDKBINDIR''' to point to the \bin directory of the variant of the Source SDK Base 2013 you're basing your mod off of. '''NOTE:''' If you have any spaces in the directory path that leads to your chosen Source SDK installation, the build process will fail. Read the [[Source SDK 2013: Shader Authoring#Fixing broken batch files|Fixing broken batch files]] section for a fix.
You should now have a batch file that is capable of building shaders for your mod.

== Fixing broken batch files ==
If you have spaces in your '''SDKBINDIR''' variable, you'll need to change the following line in <code>buildshaders.bat</code>:
<pre>set ChangeToDir=%SDKBINDIR%</pre>
To:
<pre>set ChangeToDir="%SDKBINDIR%"</pre>

= Integrating your shaders into the build process =
This section will detail some key concepts and caveats you should be aware of when you integrate your shaders into your mod. Details in this section will remain light as subsequent articles will cover these topics in further depth.
== Step 1: Create shader source files ==
Navigate to <code>src/materialsystem/stdshaders</code> and perform the following steps:
# Create a shader source file named <shader-name>.cpp (if required).
# Create a pixel shader file named <shader-name>_psXY.fxc (if required).
#* Note: '''XY''' here can be 2x (for pixel shader 2.0b) or 30 (for pixel shader 3.0). Most people typically stick with 2.0b unless they need the higher instruction limit. '''This MUST match your chosen vertex shader version!'''
# Create a vertex shader file named <shader-name>_vsXY.fxc (if required).
#* Note: '''XY''' here can be 20 (for vertex shader 2.0) or 30 (for vertex shader 3.0). '''This MUST match your chosen pixel shader version!'''
Shader authoring is a pretty complex subject. As such, material on this topic will be split out to other articles. Check the [[Source_SDK_2013:_Shader_Authoring#Quick_Links|Quick Links]] section for further information. For the time being, the next section assumes you've filled in your three shader files with the appropriate code.

== Step 2: Adding the shaders to the build process ==
In order to get Source to build your shader, you'll need to modify one of two files: <code>stdshader_dx9_20b.txt</code> or <code>stdshader_dx9_30.txt</code>. Which one you modify depends on what shader model version your shader is using. For example: If your shader files were named <code>_ps2x</code> or <code>_vs20</code>, you'd modify <code>stdshader_dx9_20b.txt</code>. Assuming your shader name was called <shader-name> and it used shader model 2.0b, you'd place the following lines in <code>stdshader_dx9_20b.txt</code>:
<pre><shader-name>_ps2x.fxc
<shader-name>_vs20.fxc</pre>
If you have a .cpp file for your shader, you will now need to add it to your game_shader_dx9 VPC script.
== Step 3: Building your shaders ==
# Ensure you've run vpc.exe to generate the latest version of your project files.
# Run the <code>build<modname>shaders.bat</code> script you created while reading the [[Source SDK 2013: Shader Authoring#Creating a batch file to build shaders|Creating a batch file to build shaders]] section.
#* This step will compile your vertex and pixel shaders which your .cpp file will depend on.
# Build your Game Shader DX9 project.

Your shaders are now ready to be used in your game.

[[Category: SDK 2013]][[Category: Programming]][[Category: Shaders]]