Difference between revisions of "SpriteCard"

From Valve Developer Community
Jump to: navigation, search
m (Changed DX9 information to use DX9 template, misc fixes)
(SpriteCard rewrite, reorganized parameters and added a load of undocumented parameters from newer engine branches)
 
(2 intermediate revisions by 2 users not shown)
Line 1: Line 1:
The '''<code>SpriteCard</code>''' [[shader]] is for materials that will be used with Source's [[:Category:Particle System|particle system]]. It supports the unusual animation frame storage of Source's particles (see [[Animated Particles]]), and also provides the following unique parameters:
+
{{Shader|SpriteCard|since=Source 2007}} It is for sprite cards that are used with Source's [[:Category:Particle System|particle system]]. It supports the unusual animation frame storage of Source's particles (see [[Animated Particles]]).
 +
== Parameters ==
  
;<code>$minsize <[[normal]]></code>
+
{{MatParam|$basetexture|texture|The sprite sheet to use for the shader.}}
;<code>$maxsize <normal></code>
 
: A minimum/maximum on-screen size for a particle. It will never go over/under the specified value. {{todo|What if it's in a rendertarget?}} {{tip|$minsize is good for ensuring that effects like bloodspray are visible at a distance.}}
 
;<code>$minfadesize <normal></code>
 
;<code>$maxfadesize <normal></code>
 
: Causes a particle to begin (min) and end (max) fading out based on its on-screen size. Both params are required.
 
: {{tip|Good for controlling performance when walking through a cloud of large particles.}}
 
; <code>$maxdistance <[[float]]></code>
 
: Maximum number of units within which this particle will be visible (default = 100,000). Can be overwritten by a particle system.
 
; <code>$farfadeinterval <float></code>
 
: Number of [[unit]]s over which a particle should fade (default = 400). If this is higher than <code>$maxdistance</code>, the particle will never reach full opacity.
 
;<code>$blendframes <[[bool]]></code>
 
: By default animated textures blend between any given two animation frames to increase the apparent animation rate. In translucent materials this adds additional [[overdraw]] to the scene, however. Disabling frame blend will trade the animation smoothing for performance.
 
;<code>$overbrightfactor <[[normal]]></code>
 
: Allows an HDR-like factor to be applied to the sprite. The base value is 0, where 1.0 would make it nearly two times as bright. This value can help make sprites like fire and light glows feel more realistic.
 
;<code>$depthblend <bool></code> {{dx9}}
 
;<code>$depthblendscale <float></code> {{dx9}}
 
: Enables soft particle rendering. This uses the [[depth buffer]] to reduce the harsh edges otherwise seen when a particle sprite intersects 3D geometry.
 
: <code>$depthblend</code> enables the effect, while <code>$depthblendscale</code> (default = 50) determines the extent to which the particles should be softened: low values soften less but lead to visible color banding along edges, while high values soften more but lead to very obvious opacity falloff. {{note|The depth blend effect is limited by the very short 128-unit range of the depth buffer. Beyond this distance, it has no effect.}}
 
  
== Untested params ==
+
=== Distance and Size ===
 +
{{MatParam|$minsize|normal}}
 +
{{MatParam|$maxsize|normal|A minimum/maximum on-screen size for a particle. It will never go over/under the specified value. {{todo|What if it's in a rendertarget?}} {{tip|<code>$minsize</code> is good for ensuring that effects like bloodspray are visible at a distance.}}}}
 +
{{MatParam|$minfadesize|normal}}
 +
{{MatParam|$maxfadesize|normal|Causes a particle to begin (min) and end (max) fading out based on its on-screen size. Both params are required.
 +
: {{tip|Good for controlling performance when walking through a cloud of large particles.}}}}
 +
{{MatParam|$maxdistance|float|Maximum number of units within which this particle will be visible (default {{=}} 100,000). Can be overwritten by a particle system.}}
 +
{{MatParam|$farfadeinterval|float|Number of [[unit]]s over which a particle should fade (default {{=}} 400). If this is higher than the <code>$maxdistance</code>, the particle will never reach full opacity.}}
  
; <code>$dualsequence <[[bool]]></code>
+
=== Blending ===
: Blend two separate animated sequences
+
{{MatParam|$blendframes|bool|By default, animated textures blend between any given two animation frames to increase the apparent animation rate. In translucent materials this adds additional [[overdraw]] to the scene, however. Disabling frame blend will trade the animation smoothing for performance.}}
; <code>$sequence_blend_mode <choices></code>
+
{{MatParam|$dualsequence|bool|Blend two separate animated sequences.}}
: Defines the blend mode between the images in dual sequence particles. 0 = avg, 1=alpha from first, rgb from 2nd, 2= first over second
+
{{MatParam|$sequence_blend_mode|choices|Defines the blend mode between the images in dual sequence particles. 0 {{=}} avg, 1{{=}}alpha from first, rgb from 2nd, 2{{=}} first over second.}}
; <code>$maxlumframeblend1</code>
+
{{MatParam|$maxlumframeblend1|and=$maxlumframeblend2|int|Instead of blending between animation frames for the first/second sequence, select pixels based upon max luminance.}}
; <code>$maxlumframeblend2</code>
+
{{MatParam|$zoomanimateseq2|float|Amount to gradually zoom between frames on the second sequence. 2.0 will double the size of a frame over its lifetime.|dx9=1}}
: Instead of blending between animation frames for the first/second sequence, select pixels based upon max luminance.
+
{{MatParam|$addoverblend|bool|Use ONE:INVSRCALPHA blending.}}
; <code>$zoomanimateseq2 <[[normal]]></code>
+
{{MatParam|$addself|float|Amount of base texture to additively blend in.}}
: Amount to gradually zoom between frames on the second sequence. 2.0 will double the size of a frame over its lifetime.
+
{{MatParam|$addbasetexture2|float|Amount to blend second texture into frame by.}}
; <code>$ramptexture <[[texture]]></code> {{dx9}}
+
 
: If specified, then the red value of the image is used to index this ramp to produce the output color.
+
=== Depth ===
; <code>$extractgreenalpha <bool></code>
+
{{MatParam|$depthblend|bool|Enables soft particle rendering. This uses the [[depth buffer]] to reduce the harsh edges otherwise seen when a particle sprite intersects 3D geometry.|dx9=1}}
: Grayscale data sitting in green/alpha channels.
+
{{MatParam|$depthblendscale|float|<code>$depthblendscale</code> (default {{=}} 50) determines the extent to which the particles should be softened: low values soften less but lead to visible color banding along edges, while high values soften more but lead to very obvious opacity falloff. {{note|The depth blend effect is limited by the very short 128-unit range of the depth buffer. Beyond this distance, it has no effect. This may be different in games or mods with an increased depth buffer range, although precision may be an issue.}}|dx9=1}}
; <code>$addoverblend <bool></code>
+
{{MatParam|$inversedepthblend|bool|Calculate 1-depthblendalpha so that sprites appear when they are near geometry.|since={{l4d}}}}
: Use ONE:INVSRCALPHA blending
+
{{MatParam|$scenedepth|texture|{{todo|What is this?}}|only={{csgo}}}}
; <code>$addself <[[float]]></code>
+
 
: Amount of base texture to additively blend in.
+
=== Orientation ===
; <code>$splinetype</code>
+
{{MatParam|$orientation|int|0 {{=}} always face camera, 1 {{=}} rotate around z, 2 {{=}} parallel to ground}}
: Spline type. 0 = none, 1=ctamull rom. Disables instancing.
+
{{MatParam|$orientationmatrix|matrix|Matrix used to orient in orientation mode 2.|since={{l4d}}}}
; <code>$useinstancing <bool></code>
+
{{MatParam|$aimatcamera|bool|Aim at camera using orientation mode 1.|only={{csgo}}}}
: Whether to use GPU vertex instancing. Xbox 360 only.
+
 
 +
=== Appearance ===
 +
 
 +
{{MatParam|$alpha|float|Cheap transparency.}}
 +
{{MatParam|$translucent|bool|Enables expensive transparency.}}
 +
{{MatParam|[[$nocull]]|bool|Disable backface culling. Useful for thin particles.}}
 +
{{MatParam|$overbrightfactor|normal|Allows an HDR-like factor to be applied to the sprite. The base value is 0, where 1.0 would make it nearly two times as bright. This value can help make sprites like fire and light glows feel more realistic.}}
 +
{{MatParam|$ramptexture|texture|If specified, then the red value of the image is used to index this ramp to produce the output color.|dx9=1}}
 +
{{MatParam|[[$mod2x]]|bool|Multiply the output by 2x.|since={{l4d}}}}
 +
{{MatParam|$opaque|bool|Are we opaque? Default 0.{{note|Enabling this disables these parameters: <code>$addbasetexture2, $dualsequence, $sequence_blend_mode, $maxlumframeblend1, $maxlumframeblend2, $extractgreenalpha, $ramptexture, $zoomanimateseq2, $addoverblend, $addself, $blendframes, $depthblend</code>, and <code>$inversedepthblend</code>.}}|since={{l4d}}}}
 +
{{MatParam|$muloutputbyalpha|bool|Multiply output RGB by output alpha to avoid precision problems.|since={{portal2}}}}
 +
{{MatParam|$intensity|float|Multiply output RGB by intensity factor.|since={{portal2}}}}
 +
 
 +
=== Vertex Colors ===
 +
{{MatParam|[[$vertexcolor]]|bool|Use computed vertex colors.}}
 +
{{MatParam|[[$vertexalpha]]|bool|Use computed vertex alpha values.}}
 +
{{MatParam|$vertexcolorlerp|bool|Enable computing vertex color by interpolating two colors based on vertex r color channels.|since={{l4d}}}}
 +
{{MatParam|$lerpcolor1|vector3|Lerp color 1.|since={{l4d}}}}
 +
{{MatParam|$lerpcolor2|vector3|Lerp color 2.|since={{l4d}}}}
 +
{{MatParam|$vertexfogamount|float|Amount of vertex fog to apply.|since={{l4d}}}}
 +
 
 +
=== Misc ===
 +
{{MatParam|$extractgreenalpha|bool|Weight green/alphas from the two frames for a scalar result.}}
 +
{{MatParam|$splinetype|int|Spline type. 0 {{=}} none, 1 {{=}} [https://en.wikipedia.org/wiki/Cubic_Hermite_spline#Catmull%E2%80%93Rom_spline catmulll rom]. Disables instancing. {{Todo|2 found in .vmts.}}}}
 +
{{MatParam|$useinstancing|bool|Whether to use GPU vertex instancing. Xbox 360 only.}}
 +
{{MatParam|$alphatrailfade|float|Amount to scale alpha by between start and end of trail/rope.|since={{l4d}}}}
 +
{{MatParam|$radiustrailfade|float|Amount to scale radius by between start and end of trail/rope.|since={{l4d}}}}
 +
{{MatParam|$shadowdepth|int|{{todo|Writing to a shadow depth buffer}}|since={{l4d}}}}
 +
{{MatParam|$cropfactor|vector2|{{todo|Crop based on these dimensions?}}|since={{l4d}}}}
 +
 
 +
=== $distancealpha ===
 +
{{MatParam|[[$distancealpha]]|bool|Use distance-coded alpha generated from hi-res texture by vtex.|since={{l4d2}}}}
 +
{{MatParam|$softedges|bool|Enable soft edges to distance coded textures.|since={{l4d2}}}}
 +
{{MatParam|$edgesoftnessstart|float|Start value for soft edges for distance coded textures.|since={{l4d2}}}}
 +
{{MatParam|$edgesoftnessend|float|End value for soft edges for distance coded textures.|since={{l4d2}}}}
 +
{{MatParam|$outline|bool|Enable outline for distance coded textures.|since={{l4d2}}}}
 +
{{MatParam|$outlinecolor|RGB matrix|Color of the outline for distance coded images.|since={{l4d2}}}}
 +
{{MatParam|$outlinealpha|float|Alpha value for the outline.|since={{l4d2}}}}
 +
{{MatParam|$outlinestart0|float|Outer start value for the outline.|since={{l4d2}}}}
 +
{{MatParam|$outlinestart1|float|Inner start value for the outline.|since={{l4d2}}}}
 +
{{MatParam|$outlineend0|float|Inner end value for the outline.|since={{l4d2}}}}
 +
{{MatParam|$outlineend1|float|Outer end value for the outline.|since={{l4d2}}}}
 +
{{MatParam|$perparticleoutline|bool|Allow per particle outline control.|since={{l4d2}}}}
  
 
[[Category:Shaders]]
 
[[Category:Shaders]]
 
[[Category:List of Shader Parameters]]
 
[[Category:List of Shader Parameters]]
 
[[Category:Particle System]]
 
[[Category:Particle System]]

Latest revision as of 14:54, 30 April 2021

SpriteCard is a material shader available in all Source games since <Source><Source> Source 2007. It is for sprite cards that are used with Source's particle system. It supports the unusual animation frame storage of Source's particles (see Animated Particles).

Parameters

$basetexture <texture>
The sprite sheet to use for the shader.

Distance and Size

$minsize <normal>
$maxsize <normal>
A minimum/maximum on-screen size for a particle. It will never go over/under the specified value. To do: What if it's in a rendertarget?
Tip.png Tip: $minsize is good for ensuring that effects like bloodspray are visible at a distance.
$minfadesize <normal>
$maxfadesize <normal>
Causes a particle to begin (min) and end (max) fading out based on its on-screen size. Both params are required.
Tip.png Tip: Good for controlling performance when walking through a cloud of large particles.
$maxdistance <float>
Maximum number of units within which this particle will be visible (default = 100,000). Can be overwritten by a particle system.
$farfadeinterval <float>
Number of units over which a particle should fade (default = 400). If this is higher than the $maxdistance, the particle will never reach full opacity.

Blending

$blendframes <boolean>
By default, animated textures blend between any given two animation frames to increase the apparent animation rate. In translucent materials this adds additional overdraw to the scene, however. Disabling frame blend will trade the animation smoothing for performance.
$dualsequence <boolean>
Blend two separate animated sequences.
$sequence_blend_mode <choices>
Defines the blend mode between the images in dual sequence particles. 0 = avg, 1=alpha from first, rgb from 2nd, 2= first over second.
$maxlumframeblend1 and $maxlumframeblend2 <integer>
Instead of blending between animation frames for the first/second sequence, select pixels based upon max luminance.
$zoomanimateseq2 <float>  (DX9+)
Amount to gradually zoom between frames on the second sequence. 2.0 will double the size of a frame over its lifetime.
$addoverblend <boolean>
Use ONE:INVSRCALPHA blending.
$addself <float>
Amount of base texture to additively blend in.
$addbasetexture2 <float>
Amount to blend second texture into frame by.

Depth

$depthblend <boolean>  (DX9+)
Enables soft particle rendering. This uses the depth buffer to reduce the harsh edges otherwise seen when a particle sprite intersects 3D geometry.
$depthblendscale <float>  (DX9+)
$depthblendscale (default = 50) determines the extent to which the particles should be softened: low values soften less but lead to visible color banding along edges, while high values soften more but lead to very obvious opacity falloff.
Note.png Note: The depth blend effect is limited by the very short 128-unit range of the depth buffer. Beyond this distance, it has no effect. This may be different in games or mods with an increased depth buffer range, although precision may be an issue.
$inversedepthblend <boolean> (in all games since <Left 4 Dead>)
Calculate 1-depthblendalpha so that sprites appear when they are near geometry.
$scenedepth <texture> (only in Counter-Strike: Global Offensive)
To do: What is this?

Orientation

$orientation <integer>
0 = always face camera, 1 = rotate around z, 2 = parallel to ground
$orientationmatrix <matrix> (in all games since <Left 4 Dead>)
Matrix used to orient in orientation mode 2.
$aimatcamera <boolean> (only in Counter-Strike: Global Offensive)
Aim at camera using orientation mode 1.

Appearance

$alpha <float>
Cheap transparency.
$translucent <boolean>
Enables expensive transparency.
$nocull <boolean>
Disable backface culling. Useful for thin particles.
$overbrightfactor <normal>
Allows an HDR-like factor to be applied to the sprite. The base value is 0, where 1.0 would make it nearly two times as bright. This value can help make sprites like fire and light glows feel more realistic.
$ramptexture <texture>  (DX9+)
If specified, then the red value of the image is used to index this ramp to produce the output color.
$mod2x <boolean> (in all games since <Left 4 Dead>)
Multiply the output by 2x.
$opaque <boolean> (in all games since <Left 4 Dead>)
Are we opaque? Default 0.
Note.png Note: Enabling this disables these parameters: $addbasetexture2, $dualsequence, $sequence_blend_mode, $maxlumframeblend1, $maxlumframeblend2, $extractgreenalpha, $ramptexture, $zoomanimateseq2, $addoverblend, $addself, $blendframes, $depthblend, and $inversedepthblend.
$muloutputbyalpha <boolean> (in all games since [Portal 2])
Multiply output RGB by output alpha to avoid precision problems.
$intensity <float> (in all games since [Portal 2])
Multiply output RGB by intensity factor.

Vertex Colors

$vertexcolor <boolean>
Use computed vertex colors.
$vertexalpha <boolean>
Use computed vertex alpha values.
$vertexcolorlerp <boolean> (in all games since <Left 4 Dead>)
Enable computing vertex color by interpolating two colors based on vertex r color channels.
$lerpcolor1 <vector3> (in all games since <Left 4 Dead>)
Lerp color 1.
$lerpcolor2 <vector3> (in all games since <Left 4 Dead>)
Lerp color 2.
$vertexfogamount <float> (in all games since <Left 4 Dead>)
Amount of vertex fog to apply.

Misc

$extractgreenalpha <boolean>
Weight green/alphas from the two frames for a scalar result.
$splinetype <integer>
Spline type. 0 = none, 1 = catmulll rom. Disables instancing. To do: 2 found in .vmts.
$useinstancing <boolean>
Whether to use GPU vertex instancing. Xbox 360 only.
$alphatrailfade <float> (in all games since <Left 4 Dead>)
Amount to scale alpha by between start and end of trail/rope.
$radiustrailfade <float> (in all games since <Left 4 Dead>)
Amount to scale radius by between start and end of trail/rope.
$shadowdepth <integer> (in all games since <Left 4 Dead>)
To do: Writing to a shadow depth buffer
$cropfactor <vector2> (in all games since <Left 4 Dead>)
To do: Crop based on these dimensions?

$distancealpha

$distancealpha <boolean> (in all games since <Left 4 Dead 2>)
Use distance-coded alpha generated from hi-res texture by vtex.
$softedges <boolean> (in all games since <Left 4 Dead 2>)
Enable soft edges to distance coded textures.
$edgesoftnessstart <float> (in all games since <Left 4 Dead 2>)
Start value for soft edges for distance coded textures.
$edgesoftnessend <float> (in all games since <Left 4 Dead 2>)
End value for soft edges for distance coded textures.
$outline <boolean> (in all games since <Left 4 Dead 2>)
Enable outline for distance coded textures.
$outlinecolor <RGB matrix> (in all games since <Left 4 Dead 2>)
Color of the outline for distance coded images.
$outlinealpha <float> (in all games since <Left 4 Dead 2>)
Alpha value for the outline.
$outlinestart0 <float> (in all games since <Left 4 Dead 2>)
Outer start value for the outline.
$outlinestart1 <float> (in all games since <Left 4 Dead 2>)
Inner start value for the outline.
$outlineend0 <float> (in all games since <Left 4 Dead 2>)
Inner end value for the outline.
$outlineend1 <float> (in all games since <Left 4 Dead 2>)
Outer end value for the outline.
$perparticleoutline <boolean> (in all games since <Left 4 Dead 2>)
Allow per particle outline control.