Shader authoring/Quick Start

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 of either 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.

Quick Start - Sample Shaders

Note:As of 01/08/06 the Advanced Shaders have a number of issues, these may be corrected in a future SDK update. These issues include: A number of lines with incorrect shader names not matching 'sdk_', incorrect includes and many of the sample advanced shaders will not light correctly.

The Source SDK ships with some sample shaders that can be compiled and used right away. To compile them and use them in a game read the following instructions:

1. 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.

Note:In this document, we refer to the mod's source directory as C:\MyMod\src (replace it as appropriate).

2. Open a Windows command prompt (enter cmd in the start menu 'run' dialogue, change to the C:\MyMod\src\sdkshaders directory with the cd command. Then type:

build_sample_shaders.bat -game [mod directory]

This will compile the sample HLSL code and copy the resulting files into a directory called shaders in the specified mod directory.

3. Open game_shader_generic_sample.vcproj in Visual Studio .NET 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).

Note:Check the bin directory, if no new dlls exist, copy them manually from the Release folder.

4. Now modify a material (.VMT) file to use the new shaders at the top. Something like the following:

"SDK_Lightmap"
{
  "$basetexture" "Brick/brickwall003a"
  "$surfaceprop" "brick"
}

5. 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

Note:Using the newly compiled shaders is just like referring to any other shader. See Creating_a_Material for more information.