Shader authoring/Quick Start

__TOC__
=High Level Concepts=
The two major pieces of code that have to be written to create a new shader are the HLSL code and the C++ code:
* HLSL code is compiled into files that are put under a mod directory's shaders directory. The specifics of HLSL are described in the DirectX docs here.
* The C++ code is compiled into a "shader DLL" that fits the pattern game_shader_dx*.dll or game_shader_generic*.dll. The shader DLL goes in the mod's bin directory (the same place where the client.dll and server.dll goes). The C++ code describes the high-level operation of the shader to the Source Engine. It tells the engine things like:
** Which textures the shader wants to use (texture names usually come from the .VMT [material] file). 
** How many rendering passes the shader will use. 
** Which HLSL code the shader will use. 
** Which parameters to pass into the HLSL code from the material file. 
** What shader to fallback to if the user's system can't support the shader. 
Every shader has one C++ class and one or more HLSL files that it uses to render.
Additionally certain types of effects, such as full screen postprocessing effects, may require a certain amount of C++ code to be written in the general game .dll to setup the texture and render it at the appropriate times.
=Quick Start - Sample Shaders=
The Source SDK ships with some of our production shaders that can be copied or modified to use in your own mod. To compile them and use them in a game read the following instructions:
1. Make sure that you have installed the Microsoft Direct X 9 SDK on your machine as well as some flavor of Perl. In addition, make sure that you have followed all of the setup instructions in Introduction, including setting your path and fixing the outdated files runvmpi.pl and common_fxc.h. You can verify that the folders containing perl.exe, nmake.exe and fxc.exe are included in your "path" environmental variable by entering path into a command line. This is a one-time step and will allow you to update this third-party software independent of a Source SDK release.
2. Install a copy of the source code by running the Create a Mod from the SDK launcher. If the latest version of the source code is already installed, this step can be skipped. 
 
3. Open a Windows command prompt (enter cmd in the start menu 'run' dialogue, change to the C:\MyMod\src\materialsystem\stdshaders directory with the cd command. Then type:
buildsdkshaders.bat
This will compile the DirectX 8 and 9 sample HLSL code and copy the resulting files into a directory called shaders in the specified mod game directory. 
4. If you wish to build a DirectX 8 shader DLL open stdshader_dx8-2003.vcproj in Visual Studio 2003 or stdshader_dx8-2005.vcproj in Visual Studio 2005 and build it. This will build the C++ part of each shader into a DLL and it will automatically copy the DLL into the game's bin directory (where the client.dll and server.dll are stored). 
Build the solution and verify that game_shader_dx8.dll is now in your game's bin directory.
5. If you wish to build a DirectX 9 shader DLL open stdshader_dx9-2003.vcproj in Visual Studio 2003 or stdshader_dx9-2005.vcproj in Visual Studio 2005 and build it. This will build the C++ part of each shader into a DLL and it will automatically copy the DLL into the game's bin directory (where the client.dll and server.dll are stored). 
Build the solution and verify that game_shader_dx9.dll is now in your game's bin directory.
6. Now modify a material (.VMT) file to use the new shaders at the top. Something like the following:
 "SDK_UnlitGeneric"
 {
 "$basetexture" "Brick/brickwall003a"
 "$surfaceprop" "brick"
 }
7. The SDK includes some example files that can be copied into a mod to see how to refer to the sample shaders that were just compiled. The relevant sample files are listed below:
Filename 	Use
[steam]\half-life 2\hl2\maps\sdk_shader_samples.bsp 	Small map that refers to the shaders
[steam]\sourcesdk_content\hl2\mapsrc\sdk_shader_samples.vmf	Map source
[steam]\half-life 2\hl2\materials\sdk\sdk_lightmap.vmt 	Material sample 1
[steam]\half-life 2\hl2\materials\sdk\sdk_particle.vmt 	Material sample 2
These files are automatically installed by the SDK, but they will need to be copied into the same relative locations in the mod's own folder. For example, if Steam was installed in C:\Program Files\Valve\Steam, and the mod is called MyMod, the files would have to be copied like this: 
C:\Program Files\Valve\Steam\steamapps\username\half-life 2\hl2\materials\sdk\sdk_lightmap.vmt
into
C:\Program Files\Valve\Steam\steamapps\SourceMods\MyMod\materials\sdk\sdk_lightmap.vmt
Category: Programming
Category: Shaders