Source SDK 2013: Your Second Shader

Introduction

This page will teach you the basics of passing parameters to your shaders.

Prerequisites

This tutorial assumes the following:

1. You've followed all of the instructions on the Source SDK 2013: Your First Shader page.
   • And you've been able to successfully build the shader source code on that page.

Overview

What are shader parameters?

Shader parameters are bits of data that you can feed into a shader from a Valve Material File. It turns out that VMT files are actually KeyValues which you can add additional data to. The following snippet is from materials/dev/lumcompare.vmt:

"screenspace_general"
{
    "$PIXSHADER"            "luminance_compare_ps20"
    "$BASETEXTURE"          "_rt_FullFrameFB"
    "$ALPHATESTED"          "1"
    "$DISABLE_COLOR_WRITES" "1"
}

Recall back to the first tutorial. The first line in a VMT file is the name of the shader to draw that material with. The subsequent lines that begin with $ however, are known as material parameters. In this example, there are four parameters, each of which are associated with a value.

You might be asking yourself how we know what the parameters of a given shader are. Unfortunately, there isn't a simple in-game command (as far as the author is aware of) that lists them for you. You'll need to take a look at the source code of the shader. Luckily, we have the source code for screenspace_general. The parameters it can handle are listed in its BEGIN_SHADER_PARAMS block:

Note:For Source SDK 2013, the screenspace_general code lives under src/materialsystem/stdshaders/screenspace_general.cpp.

SHADER_PARAM( C0_X,SHADER_PARAM_TYPE_FLOAT,"0","")
SHADER_PARAM( C0_Y,SHADER_PARAM_TYPE_FLOAT,"0","")
SHADER_PARAM( C0_Z,SHADER_PARAM_TYPE_FLOAT,"0","")
SHADER_PARAM( C0_W,SHADER_PARAM_TYPE_FLOAT,"0","")
SHADER_PARAM( C1_X,SHADER_PARAM_TYPE_FLOAT,"0","")
SHADER_PARAM( C1_Y,SHADER_PARAM_TYPE_FLOAT,"0","")
SHADER_PARAM( C1_Z,SHADER_PARAM_TYPE_FLOAT,"0","")
SHADER_PARAM( C1_W,SHADER_PARAM_TYPE_FLOAT,"0","")
SHADER_PARAM( C2_X,SHADER_PARAM_TYPE_FLOAT,"0","")
SHADER_PARAM( C2_Y,SHADER_PARAM_TYPE_FLOAT,"0","")
SHADER_PARAM( C2_Z,SHADER_PARAM_TYPE_FLOAT,"0","")
SHADER_PARAM( C2_W,SHADER_PARAM_TYPE_FLOAT,"0","")
SHADER_PARAM( C3_X,SHADER_PARAM_TYPE_FLOAT,"0","")
SHADER_PARAM( C3_Y,SHADER_PARAM_TYPE_FLOAT,"0","")
SHADER_PARAM( C3_Z,SHADER_PARAM_TYPE_FLOAT,"0","")
SHADER_PARAM( C3_W,SHADER_PARAM_TYPE_FLOAT,"0","")
SHADER_PARAM( PIXSHADER, SHADER_PARAM_TYPE_STRING, "", "Name of the pixel shader to use" )
SHADER_PARAM( DISABLE_COLOR_WRITES,SHADER_PARAM_TYPE_INTEGER,"0","")
SHADER_PARAM( ALPHATESTED,SHADER_PARAM_TYPE_FLOAT,"0","")
SHADER_PARAM( TEXTURE1, SHADER_PARAM_TYPE_TEXTURE, "", "" )
SHADER_PARAM( TEXTURE2, SHADER_PARAM_TYPE_TEXTURE, "", "" )
SHADER_PARAM( TEXTURE3, SHADER_PARAM_TYPE_TEXTURE, "", "" )
SHADER_PARAM( LINEARREAD_BASETEXTURE, SHADER_PARAM_TYPE_INTEGER, "0", "" )
SHADER_PARAM( LINEARREAD_TEXTURE1, SHADER_PARAM_TYPE_INTEGER, "0", "" )
SHADER_PARAM( LINEARREAD_TEXTURE2, SHADER_PARAM_TYPE_INTEGER, "0", "" )
SHADER_PARAM( LINEARREAD_TEXTURE3, SHADER_PARAM_TYPE_INTEGER, "0", "" )
SHADER_PARAM( LINEARWRITE,SHADER_PARAM_TYPE_INTEGER,"0","")
SHADER_PARAM( X360APPCHOOSER, SHADER_PARAM_TYPE_INTEGER, "0", "Needed for movies in 360 launcher" )

The next section will cover each piece of the SHADER_PARAM macro.

Understanding SHADER_PARAM

The SHADER_PARAM macro has the following definition:

#define SHADER_PARAM( param, paramtype, paramdefault, paramhelp ) \
	static CShaderParam param( "$" #param, paramtype, paramdefault, paramhelp, 0 );

Note:Essentially, every shader parameter you create with this macro gets written as a static variable in memory. When your shader is loaded into the game, each shader parameter adds itself to a static vector called s_ShaderParams, which was created in the BEGIN_SHADER macro. The materialsystem uses this vector to load in data from VMT files.

The macro itself is pretty straight forward. The first parameter is the name you want your shader parameter to have. You'll need to use this name in your VMT file in order to pass data to your shader. In the VMT example above, we had the following material parameter:

"$PIXSHADER"            "luminance_compare_ps20"

In order for this to work, the corresponding shader parameter needs to have the same name (which it does):

SHADER_PARAM( PIXSHADER, SHADER_PARAM_TYPE_STRING, "", "Name of the pixel shader to use" )

This is a nice segue into shader parameter types.

Shader parameter types

As you can tell by the code snippet above, there are multiple types of data you can pass to a shader. Twelve of them to be exact. You can find a list of all supported data types under src/public/materialsystem/imaterialsystem.h. As of the time of this writing (12/27/2014), the types are as follows: The following table explains each possible shader parameter type and how to use it:

Parameter type	Explanation	Usage
SHADER_PARAM_TYPE_TEXTURE	A texture reference.	Pass in the name of the texture you want to bind (e.g. _rt_FullFrameFB).
SHADER_PARAM_TYPE_INTEGER	An integer value.	Pass in a scalar value (e.g. 0 or 5).
SHADER_PARAM_TYPE_COLOR	A color value.	Pass in an RGBA color value (e.g. [0 255 152 255]). Note, the brackets are required.
SHADER_PARAM_TYPE_VEC2	A two component vector.	Pass in a vector2d (e.g. [0.0 1.0]). Note, the brackets are required.
SHADER_PARAM_TYPE_VEC3	A three component vector.	Pass in a vector3d (e.g. [0.0 1.0 0.5]). Note, the brackets are required.
SHADER_PARAM_TYPE_VEC4	A four component vector.	Pass in a vector4d (e.g. [0.0 1.0 0.5 0.4]). Note, the brackets are required.
SHADER_PARAM_TYPE_ENVMAP	Unknown.	Unknown.
SHADER_PARAM_TYPE_FLOAT	A floating point value.	Pass in a scalar float (e.g. 0.4).
SHADER_PARAM_TYPE_BOOL	A boolean value.	Pass in 0 for false and 1 for true.
SHADER_PARAM_TYPE_FOURCC	Unknown. Appears as if this denotes custom data that isn't a regular data type.	Unknown.
SHADER_PARAM_TYPE_MATRIX	Allows you to define a transformation matrix or a 4x4 regular matrix.	If you want to define a transformation matrix, you need to use the following value: center a b scale c d rotate e translate f g. Replace a-g with values from 0..1. If you want to define a regular matrix, you will need to put sixteen floating point values within brackets as such: [0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0]
SHADER_PARAM_TYPE_MATERIAL	A material.	Pass in the path to a VMT (e.g. dev/lumcompare.vmt).
SHADER_PARAM_TYPE_STRING	A string.	Pass in a string (e.g. "Hello").