Material proxies

From Valve Developer Community
Revision as of 20:59, 15 January 2008 by Ts2do (talk | contribs) (revert)

Jump to: navigation, search

The Basics

Material proxies allow materials to change their rendering properties (color, alpha values, etc) using game state and scripted equations. Proxies are defined as a block of text, using key/value pairing, inside of the VMT description of a material. Proxies are available for all materials. A proxy is defined as in the following example:

"LightmappedGeneric"
{
	"$basetexture" "shadertest/LightmappedTexture"

	// Inside these braces are where all the proxies go
	"Proxies"
	{
		// This is a sine proxy
		"Sine"
		{
			// This is the data for the sine proxy
			// Notice there is no '$' on the proxy variables
			"resultVar"	"$alpha"
			"sineperiod"	8
			"sinemin"	0
			"sinemax"	1
		}
	}
}

The above block of text instructs the material to use the Sine material proxy to modify the alpha value of the material when rendered. The other entries define parameters for the proxy to use in its calculations. Here the sine wave has a sineperiod of 8 seconds and oscillates between a value of "0" and "1".

It is possible to define multiple proxies in one material within the Proxies section of that material's definition. If multiple proxies are defined, they are executed in a top to bottom order.

"Proxies" 
{ 
	// This is executed first
	"A"
	{
		. . .
	}
	// This is executed second
	"B"
	{
		. . .
	}
}


Variables

Like a standard programming language, the material proxies may declare temporary local variables to be used to store intermediate values for further use later in the proxy. Variables are declared outside of the Proxies block and have default values specified on their right-hand side.

"LightmappedGeneric"
{
	"$basetexture" "shadertest/LightmappedTexture"

	// A local variable for this material, defaulting to "0.5"
	"$myScale" 0.5
	"Proxies"
	{
		. . .
	}
}

There is no practical limit to the number of local variables declared. Local variables may be used to store results from proxies, or to pass data into proxies as parameters. They are often employed to chain mathematic function proxies (i.e. Add, Subtract, etc) together into longer equations for rendering values.


Common Result Variables

The following values are commonly used as $resultVar variables.

$alpha Fade value (0 = transparent, 1 = opaque)
$color Modulation color (R,G,B) (1,1,1) = white, (0,0,0) = black
$envmapmaskscale An amount to scale the environment map mask
$frame Frame number of an animated texture
$envmaptint Modulation color for the environment map
$selfillumtint Modulation color for the self-illumination
Note:$alpha and $color values are clamped between 0 and 1.
Note:Certain variables like $color and $baseTextureOffset can be accessed like an array. "$color[0]" would access the red component of the variable.


Writing Material Proxy Implementations

Although many generic proxies are included in the client already, it will sometimes be necessary to create a custom material proxy for your MOD. To do this, code will be required on the client-side. Material proxies are descended from the IMaterialProxy interface class. The proxy has three main functions to do its work in. The first is the Init() function, defined as:

bool Init( IMaterial *pMaterial, KeyValues *pKeyValues );
 pMaterial
 Material we’re acting on

 pKeyValues
 List of key-value pairs for this material

The Init() function is called when a material is first created in a session. This function allows you to setup internal state for the material proxy, usually consisting of obtaining references to material variables for later use.

void OnBind( void *pC_BaseEntity );
 pC_BaseEntity
 Entity this material is being applied to (if any)

The OnBind() function is called every time Bind() is called on a material. This is where most of the material proxy’s work is done.

Finally, the proxy must expose its interface so that the named reference to the proxy can be linked up to the class implementation. This is done via the EXPOSE_INTERFACE macro.

EXPOSE_INTERFACE( className, interfaceName, proxyName IMATERIAL_PROXY_INTERFACE_VERSION );
Note:See DummyProxy.cpp for an example of a simple material proxy.

Proxy List

The following proxies are defined in the client DLL for use in any Source game.

Proxy Name Description Variables
Add Adds two variables together.

srcVar1

  • Name of the first source variable.

srcVar2

  • Name of the second source variable.

resultVar

  • ( srcVar1 + srcVar2)
Multiply Multiplies two variables together.

srcVar1

  • Name of the first source variable.

srcVar2

  • Name of the second source variable.

resultVar

  • ( srcVar1 * srcVar2)
Subtract Subtracts the second variable from the first.

srcVar1

  • Name of the first source variable.

srcVar2

  • Name of the second source variable.

resultVar

  • ( srcVar1 - srcVar2)
Divide Divides the first variable by the second.

srcVar1

  • Name of the first source variable.

srcVar2

  • Name of the second source variable.

resultVar

  • ( srcVar1 / srcVar2)
Equals Copies a variable to the result variable.

srcVar1

  • Name of the source variable.

resultVar

  • Set equal to srcVar1
Abs Computes the absolute value of a variable.

srcVar1

  • Name of the source variable.

resultVar

  • abs( srcVar1)
Frac Returns the fractional component of a number.
Note:If a vector type variable is provided, this function will return the fractional component of each member of the array.

srcVar1

  • Number to find the fractional component of
Exponential Computes ( A * e (srcVar1+B) ).

srcVar1

  • Name of the source variable.

scale

  • Specifies the value of A

offset

  • Specifies the value of B

minVal

  • Minimum clamping value

maxVal

  • Maximum clamping value

resultVar

  • ( A * e (srcVar1+B) )
Clamp Clamps a variable to a specified range of values.

srcVar1

  • Name of the source variable.

min

  • Minimum clamping value

max

  • Maximum clamping value

resultVar

  • clamp( srcVar1, Min, Max )
LessOrEqual Returns different values based relation of supplied variables.

srcVar1

  • Name of the first source variable.

srcVar1

  • Name of the second source variable.

lessEqualVar

  • Name of material variable to copy to result if (srcVar1 <= srcVar2)

greaterVar

  • Name of material var to copy to result if (srcVar1 > srcVar2)

resultVar

  • Resulting value
Sine Creates a sine wave.

sineperiod

  • Period of the sine wave in seconds.

sinemin

  • Minimum value of the sine wave.

sinemax

  • Maximum value of the sine wave.

timeoffset

  • Used to start the sine wave at a different point in time

resultVar

  • Resulting value.
LinearRamp Produces an ever increasing value.

rate

  • Rate of increase of the value.

initialValue

  • Initial value to increase.

resultVar

  • Resulting value.
UniformNoise Produces a noisy signal where each value is equally likely to occur

minVal

  • Minimum value range.

maxVal

  • Maximum value range.

resultVar

  • Resulting value.
GaussianNoise Produces a noisy signal where values are near the average.

mean

  • The average random value.

halfWidth

  • The distance from the average at which it’s only 30% likely to occur.

minVal

  • Minimum value range (clamped).

maxVal

  • Maximum value range (clamped).

resultVar

  • Resulting value.
MatrixRotate Creates a rotation matrix from the provided axis and angle.

axisVar

  • Axis of rotation (x,y,z) = (0,1,2).

angle

  • Degrees of rotation around axis.

resultVar

  • Rotation matrix.
PlayerProximity Stores the distance from the entity the material is on to the player into a variable.
Note:Does not work on world surfaces.

scale

  • An amount to scale the distance by.

resultVar

  • Resulting value.
PlayerView Stores the dot product of the view direction + the direction from the camera to the entity the material is on.
Note:Does not work on world surfaces.

scale

  • Amount to scale the dot product by.

resultVar

  • Resulting value.
PlayerSpeed Stores the speed of the player into a variable.

scale

  • Amount to scale the speed by.

resultVar

  • Resulting value.
PlayerPosition Stores the player’s position into a variable.
Note:Only works for vector variables like $baseTextureOffset or $color.

scale

  • An amount to scale the position by.

resultVar

  • Resulting value.
EntitySpeed Stores the entity’s speed into a variable.
Note:Does not work on world surfaces.

scale

  • An amount to scale the speed by.

resultVar

  • Resulting value.
TextureTransform Generates a texture transform matrix.

centerVar

  • Name of a variable holding the center of rotation and scaling. [Optional]

scaleVar

  • Name of scale variable (2D vector). [Optional]

rotateVar

  • Name of rotation angle variable (float). [Optional]

translateVar

  • Name of the translation variable (2D vector).

resultVar

  • Resulting value.
Empty Used to comment out proxies. Surround a bunch of proxies with the empty proxy to cause those proxies to not operate.
TextureScroll Returns a transform matrix or vector that will translate a texture at a given angle at a given rate.

textureScrollVar

  • Destination for the resulting transformation.

textureScrollRate

  • Rate of scroll in units per second.

textureScrollAngle

  • Angle of rotation to move along. (90 = right, 180 = left, etc)
ToggleTexture Toggles a texture based on the frame number set by the attached entity.
Note:Must be attached to an entity.

toggleTextureVar

  • Texture to modify based on frames.

toggleTextureFrameNumVar

  • Variable used for frame number.

toggleShouldWrap

  • Whether the animation should wrap over not.
RandomEntity A proxy that returns a random number associated with the entity the material is applied to. Can be helpful for making animated textures not all be in sync.

scale

  • Amount to scale the random number by.

resultVar

  • Resulting value.
CurrentTime Returns the current time as a float.

resultVar

  • The current time.
PlayerHealth Stores the player health (0-1) in a variable.

scale

  • Amount to scale the health value by.

resultVar

  • Resulting value.
PlayerDamageTime Stores the time since the player was last damaged, in a variable.

scale

  • Amount to scale the time by.

resultVar

  • Resulting value.
MaterialModify Sets the base texture to a value held by the entity (used for entity controlled texture animations).
Note:Only works when attached to an entity.

No return value.

WaterLOD Coordinates water LOD values between the map's env_waterlod entity and the materials internal values.

$CHEAPWATERSTARTDISTANCE

  • Start distance for cheap water
  • Note:must be set outside of proxy block.

$CHEAPWATERENDDISTANCE

  • End distance for cheap water
  • Note:must be set outside of proxy block.

No return value.

BreakableSurface Sets the base texture to a material name held by the entity (used for switching surface material on shatter)
Note:Must be attached to a func_breakablesurface entity.

No return value.

ConveyorScroll Returns the scroll parameters for a texture used as a conveyor.
Note:Must be attached to func_conveyor entity.

textureScrollVar

  • Name of variable to place result in.
  • Note:must be a matrix or vector type variable (i.e. $baseTextureOffset).
LampBeam Modulates the material’s alpha value based on angle between the beam’s direction and the viewer’s eye point. This is used to make the beams of volumetric light on lights fade as you look at them dead on.
Note:Must be attached to entity for angle use.

No return value.

LampHalo Modulates the material’s alpha value based on angle between the beam’s direction and the viewer’s eye point.
Like the LampBeam proxy, but used for the halo at the beam’s base.
Note:Must be attached to entity for angle use.

No return value.

AnimatedTexture Increments frame variable

animatedtexturevar

  • Texture to increment frame for (i.e. $basetexture, $bumpmap)

animatedtextureframenumvar

  • Frame variable to increment (i.e. $frame)

animatedtextureframerate

  • Framerate in frames per second


See also

Material Creation