View source for Material proxies

{{LanguageBar}}


{{toc-right}}
'''Material proxies''' allow a game's compiled C++ code to manipulate the properties of a [[material]]. Many proxies perform specific tasks, but [[List Of Material Proxies|there are other more general ones]] that together provide rudimentary scripting support within VMT files.{{clarify}}

Any number of proxies can be added to a material; they will be executed in the order in which they appear.

{{bug|Some users have reported that the tools mode will not run some functional proxies in game.}}
{{todo|Extent of bug untested.}}

{{bug|Using some material proxies on dynamically created particles, for example [[env_smokestack]], will cause the game to crash upon map loading.}}
== Usage ==

This material has a <code>Sine</code> proxy which makes it fade [[$alpha|in and out of view]] over a period of eight seconds:

<source lang=php>
LightmappedGeneric
{
	$basetexture shadertest/LightmappedTexture

	Proxies // proxies are listed inside this block
	{
		Sine // a proxy which produces a sine wave
		{
			resultVar	$alpha // The shader parameter to be manipulated
			sineperiod	8
			sinemin		0
			sinemax		1
		}
	}
}
</source>

=== 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 default values specified on the right-hand side.

These custom variables might 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. <code>Add</code>, <code>Subtract</code>, etc) together into longer equations. For 2D/3D/4D vectors (<code>"[0 0 0]"</code>), the variable name can have <code>[0]</code> suffixed to read/write a specific index. Writes to indexed variables should be encased in quotes.

The engine encode 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:

<source lang=php>
LightmappedGeneric
{
	$basetexture shadertest/LightmappedTexture

	$offset 0 // declare custom var
	
	Proxies
	{
		EntityRandom
		{
			resultVar $offset // write to custom var
		}
		Sine
		{
			resultVar	$alpha
			timeoffset	$offset // read from custom var
			sineperiod	8
			sinemin		0
			sinemax		1
		}
	}
}
</source>

Now each entity this material is used on pulses to its own schedule.

Other examples for writing to indexed variables:

<source lang=php>
	$color "[0 0 0]"

	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]"
		}
	}
</source>

An example of using a color vector to create 'random' color pulses.

<source lang=php>
UnlitGeneric
{
	$basetexture "dev\gradient_dif"
	$color "[1 .8 .6]"

	$detail "dev\noise_512x32"
	$detailscale 1
	$detailblendmode 0
	$detailblendfactor 4.0

	$additive 1
	$nocull 1

	$cvar "[.5 .5]"
	$svar "[1 .25]"
	$rvar 0
	$tvar "[0 0]"

	$sine1 0
	$sine2 0

	proxies
	{
		linearramp
		{
			rate .3
			initialvalue 0
			resultvar "$tvar[1]"
		}
		sine
		{
			sineperiod 1.3
			sinemin -.004
			sinemax .002
			timeoffset 0
			resultvar $sine1
		}
		sine
		{
			sineperiod 1.7
			sinemin -.003
			sinemax .007
			timeoffset .2
			resultvar $sine2
		}
		add
		{
			srcvar1 $sine1
			srcvar2 $sine2
			resultvar "$tvar[0]"
		}
		texturetransform
		{
			centervar $cvar
			scalevar $svar
			rotatevar $rvar
			translatevar $tvar
			resultvar $detailtexturetransform
		}
	}
}
</source>

An example of a dynamic texture transform.

== Splitting a vector ==
Using vectors is quirky. Not all proxies recognize vector components. If a vector's components need be processed separately, they need to be split into different variables first.
<code>resultVar</code> in all proxies will always recognize vector components.

The following proxies, and only these keyvalues, can recognize vector components:
<code>
* '''Clamp: '''        min, max
* '''Sine:'''          offset, max, min, period
* '''LinearRamp:'''    rate, initial value
* '''UniformNoise:'''  min, max
* '''GaussianNoise:''' min, max, mean, halfwidth
* '''WrapMinMax:'''    min, max
* '''Exponential:'''   min, max, scale, offset
</code>
All of the above can be used to split a vector. However Clamp is the [[Cheap|cheapest]] to use:
<source lang="php">
        $pos "[0 0 0]"
        $posX .0        //must be float or Clamp will not save the value properly
        $posY .0        //must be float or Clamp will not save the value properly
        $posZ .0        //must be float or Clamp will not save the value properly
        
        $zero 0
        
        //Proxy that outputs a 3d vector
        PlayerPosition
        {
                scale                    1
                resultVar               "$pos"
        }
        
        //Split the 3d vector for further use
        Clamp
        {
            srcVar1                      $zero
            min                         "$pos[0]"
            max                         "$pos[0]"
            resultVar                    $posX
        }
        
        Clamp
        {
            srcVar1                      $zero
            min                         "$pos[1]"
            max                         "$pos[1]"
            resultVar                    $posY
        }
        
        Clamp
        {
            srcVar1                      $zero
            min                         "$pos[2]"
            max                         "$pos[2]"
            resultVar                    $posZ
        }
</source>

{{warning|Quotes are needed when addressing a vector's component, or when defining a vector.}}

== Writing new proxies ==

New proxies are easy to create. They exist on the client only and should inherit from <code>IMaterialProxy</code> or one of its descendants.

You will need these #includes:

* <code>"materialsystem/IMaterialProxy.h"</code>
* <code>"materialsystem/IMaterialVar.h"</code>

These functions are included in the interface:

; <code>[[bool]] Init( [[IMaterial]]* pMaterial, [[KeyValues]]* pKeyValues )</code>
: Called when the material is first [[precache]]d. 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).
: <code>pKeyValues</code> contains the proxy parameters from the VMT file.
; <code>void OnBind( void* pC_BaseEntity )</code>
: 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 <code>OnBind()</code> 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. {{note|<code>pC_BaseEntity</code> doesn't lead to a <code>[[C_BaseEntity]]</code> as its name suggests, but rather to the associated <code>[[IClientRenderable]]</code>. The easiest way to access the entity directly is to base your class on <code>CEntityMaterialProxy</code> (in <code>proxyentity.h</code>) and use the <code>OnBind(C_BaseEntity*)</code> overload it provides.}}
; <code>void Release()</code>
: {{todo|Called when the proxy is removed, but when is that?}}
; <code>[[IMaterial]]* GetMaterial()</code>
: The material the proxy is attached to. {{tip|If you have a material var stored, you can return <code>IMaterialVar::GetOwningMaterial()</code> here instead of creating a new <code>IMaterial</code> pointer.}}

=== Interface ===

The proxy must expose its interface to materials with the <code>EXPOSE_INTERFACE</code> macro:

<source lang=cpp>
EXPOSE_INTERFACE( <className>, <interfaceName>, "<proxyName>" IMATERIAL_PROXY_INTERFACE_VERSION );
</source>

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:

<source lang=cpp>
#include "toolframework_client.h"

void OnBind(...)
{
	//...

	if ( ToolsEnabled() )
		ToolFramework_RecordMaterialParams( GetMaterial() );
}
</source>

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!

{{tip|<code>CEntityMaterialProxy</code> makes the call by itself.}}

== See also ==
* [[List Of Material Proxies]]
* [[Material proxies programming]]
* [[Material Creation]]
* Steam guides, explaining more about various Proxies. [https://steamcommunity.com/sharedfiles/filedetails/?id=594255575 Basics], [https://steamcommunity.com/sharedfiles/filedetails/?id=668958242 RNG], [https://steamcommunity.com/sharedfiles/filedetails/?id=749130424 "Programming"]

== External links ==
* [https://nodraw.net/2010/01/dynamic-materials-with-proxies/ Dynamic Materials With Proxies] - An article covering practical uses of materials with proxies by [http://www.nodraw.net NoDraw.net]

[[Category:Source]]
[[Category:Material System]]
[[Category:C++]]