Material proxies

Material proxies allow a game's compiled C++ code to manipulate the properties of a material in-game. They can be used to create dynamic or animated textures.
== Usage ==
Material proxies can be added to some material via its VMT file, more specificly in a KeyValues-block named Proxies; Each entry inside it is what we name a proxy. Any number of proxies can be added to a material. Proxies are executed in the order in which they appear. The game repeatedly executes the list of a material's proxies in very quick succession.
The name of the proxy determines what parameters it has and what the proxy does.
Many proxies perform specific tasks, but there are other more general ones that together provide rudimentary scripting support within VMT files.
Typically, each proxy has an output value (e. g. a float number) which will be written to its resultVar which can be either a shader parameter or variable (see below for variables).
For example, the following material has a proxy which generates a float number and writes it to the material's shader parameter, which makes the texture fade in and out of view over a period of eight seconds:
LightmappedGeneric
{
	$basetexture shadertest/LightmappedTexture
	Proxies // proxies are listed inside this block
	{
		Sine // a proxy which produces values of a sine wave
		{
			sineperiod	8 // the sine cycle length in seconds
			sinemin		0 // min output value
			sinemax		1 // max output value
			resultVar	$alpha // where the oscillating output value is written to
		}
	}
}
=== Variables ===
Materials can declare their own variables for internal use. Such variables must be declared outside the Proxies block, in the body of the material, and must have a default value specified on the right-hand side.
These custom variables can be used to pass results between proxies or to submit hard-coded data to them. They are often employed to chain mathematic function proxies (i. e. , , etc.) together into longer equations. For 2D/3D/4D vectors ($vec "[0 0 0]"), the variable name can have [0] suffixed ("$vec[0]") to read/write a specific index. Writes to indexed variables should be encased in quotes.
The engine encodes these custom variables using a 8-bit signed integer. Therefore, there is a limit of 128 unique custom variables per material.
This example extends the one above by staggering the starting position of the sine wave with a random value produced with the proxy:
LightmappedGeneric
{
	$basetexture shadertest/LightmappedTexture
	$offset 0 // declare custom var ($offset is not a shader parameter the game knows)
	
	Proxies
	{
		EntityRandom // generates a random number
		{
			resultVar $offset // write to custom var
		}
		Sine
		{
			resultVar	$alpha
			timeoffset	$offset // read from custom var
			sineperiod	8
			sinemin		0
			sinemax		1
		}
	}
}
Now each entity this material is used on pulses to its own schedule.
This is an example for writing to indexed variables using the $color vector to create 'random' color pulses:
	$color "[0 0 0]" // not custom, the game knows "$color"
	proxies
	{
		sine
		{
			sineperiod	1.3
			sinemin		0
			sinemax		1
			timeoffset	0
			resultvar	"$color[0]"
		}
		sine
		{
			sineperiod	1.7
			sinemin		0
			sinemax		1
			timeoffset	0
			resultvar	"$color[1]"
		}
		sine
		{
			sineperiod	2.3
			sinemin		0
			sinemax		1
			timeoffset	0
			resultvar	"$color[2]"
		}
	}
=== Splitting a vector ===
Using vectors is quirky, because vector component expressions such as "$pos[0]" are not always recognized by the game.
The following proxies, and only these keyvalues, can recognize vector components:
* The resultVar of all proxies
* : min, max
* : offset, max, min, period
* : rate, initial value
* : min, max
* : min, max, mean, halfwidth
* : min, max
* : min, max, scale, offset
If a vector's components need be processed separately, they need to be split into different variables first.
All of the above can be used to split a vector. However, Clamp is the cheapest to use.
== Writing new proxies ==
New proxies are easy to create. They exist on the client only and should inherit from IMaterialProxy or one of its descendants.
You will need these #includes:
* "materialsystem/IMaterialProxy.h"
* "materialsystem/IMaterialVar.h"
These functions are included in the interface:
; bool Init( IMaterial* pMaterial, KeyValues* pKeyValues )
: Called when the material is first precached. Use this function to initialise variables and grab references to the material vars you will be using. Return true on success and false on failure (in which case the proxy will not be run).
: pKeyValues contains the proxy parameters from the VMT file.
; void OnBind( void* pC_BaseEntity )
: Called when the material is about to be rendered on an entity. This is where the work is done.
: When coding this function it is important to remember that all entities using a material share the same material object, and that if you change it on one entity it changes everywhere else too. Since OnBind() is called every time an entity comes up for rendering this is not a problem so long as you reassign the value you want every time. Don't return early just because there has been no change, and don't store any input data in the proxy. 
; void Release()
: 
; IMaterial* GetMaterial()
: The material the proxy is attached to. 
=== Interface ===
The proxy must expose its interface to materials with the EXPOSE_INTERFACE macro:
EXPOSE_INTERFACE( <className>, <interfaceName>, "<proxyName>" IMATERIAL_PROXY_INTERFACE_VERSION );
The lack of a comma between the proxy name and interface version is intentional.
=== Tools recording ===
This code was added to all proxies in the Orange Box:
#include "toolframework_client.h"
void OnBind(...)
{
	//...
	if ( ToolsEnabled() )
		ToolFramework_RecordMaterialParams( GetMaterial() );
}
It's probably related to the Source Filmmaker. It's a good idea to add it to your proxy too in case the Filmmaker is ever released!
== See also ==
* List Of Material Proxies
* Material proxies programming
* Material Creation
* Steam guides, explaining more about various Proxies. Basics, RNG, "Programming"
== External links ==
* Dynamic Materials With Proxies - An article covering practical uses of materials with proxies by NoDraw.net
Category:Source
Category:Material System
Category:C++