Difference between revisions of "Water (shader)"

From Valve Developer Community
Jump to: navigation, search
m (fixed an incorrect link)
(Reordered some parameters, changed $reflect3dskybox to CSGO only, misc fixes)
 
(6 intermediate revisions by 5 users not shown)
Line 1: Line 1:
 +
[[File:Ep2 jalopy.jpg|thumb|200px|Water [[#Reflection/Refraction|reflecting]] entities in real-time in [[Episode Two]].]]
 
[[File:L4d2 flowmap user.jpg|thumb|200px|[[Left 4 Dead 2]] introduced [[#Flowing water|flowing water]].]]
 
[[File:L4d2 flowmap user.jpg|thumb|200px|[[Left 4 Dead 2]] introduced [[#Flowing water|flowing water]].]]
[[File:Ep2 jalopy.jpg|thumb|200px|Real-time [[#Reflection/Refraction|reflection]] of entities in [[Episode Two]].]]
 
  
'''<code>Water</code>''' is one of the Source engine's most complex shaders. It creates animated, real-time reflective & refractive, fogged, normal-mapped, and flowing water.
+
{{Shader|Water}} It creates water that realistically reflects and refracts the world, and that can flow throughout a map.
  
 
== Special behaviour ==
 
== Special behaviour ==
  
 
; Expensive and cheap
 
; Expensive and cheap
: <code>Water</code> materials fall into two groups: [[expensive]] and [[cheap]]. Expensive water reflects and refracts the world in real-time, while cheap water uses an <code>[[$envmap]]</code> and does not refract. Users can disable expensive water rendering through their video options, so always place [[env_cubemap]]s.
+
: <code>Water</code> materials fall into two groups: [[expensive]] and [[cheap]]. Expensive water reflects and refracts the world in real-time, while cheap water uses an {{ent|$envmap}} and does not refract. Users can disable expensive water rendering through their video options, so always place {{ent|env_cubemap}} entities throughout a map.
 
; Above and below
 
; Above and below
: <code>Water</code> actually requires two materials: one for above the surface and one for below. These materials are independent of each other, but of course for proper effect need to correlate in most areas.
+
: <code>Water</code> actually requires two materials: one for above the surface and one for below. These materials are independent of each other, but for proper effect need to correlate in most areas.
 
; Flow Mapping
 
; Flow Mapping
: Water can [[#Flow|flow in arbitrary directions]]. It's very tricky to create a flow map by hand however, and the tool Valve used internally hasn't been released.
+
: Water can [[#Flowing water|flow in arbitrary directions]]. It's very tricky to create a flow map by hand however, and the tool Valve used internally hasn't been released.
  
 
== Shader parameters ==
 
== Shader parameters ==
Line 17: Line 17:
 
=== Textures ===
 
=== Textures ===
  
{{note|In Orange box games and below, there is no <code>[[$basetexture]]</code>, The surface is a combination of fog color, animated bump map, reflection and refraction.}}
+
{{note|In games before {{As}}, there is no {{ent|$basetexture}}. The surface is a combination of fog color, animated bump map, reflection and refraction.}}
  
; <code>$abovewater <[[bool]]></code>
+
{{MatParam|$abovewater|bool|Whether this material is used for above or below the water’s surface.}}
: Whether this material is used for above or below the water’s surface.
+
{{MatParam|$bottommaterial|material|Required parameter. This is the material ('''not''' texture) to use when underneath the water’s surface. The bottom material must have <code>$reflecttexture</code>, <code>$abovewater</code> and <code>$envmap</code> disabled, but can otherwise do whatever it wants.}}
; <code>$bottommaterial <material></code>
+
{{MatParam|$underwateroverlay|material|Applies a refracting screen overlay when the camera is underwater. Generally used with <code>effects\water_warp01</code>. Requires <code>$abovewater</code> to be 0.|since=EP2}}
: Required field. This is the material ('''not''' texture) to use when underneath the water’s surface. The bottom material must have <code>$reflecttexture</code> and <code>$abovewater</code> disabled, but can otherwise do whatever it wants.
+
{{MatParam|[[Du/dv_map|$bumpmap]]|texture|dx8=1}}
; {{EP2 add|<code>$underwateroverlay <material></code>}}
+
{{MatParam|[[normalmap|$normalmap]]|texture|A [[Du/dv map]] for DirectX 8 rendering (<code>$bumpmap</code>), and a [[bump map]] for DirectX 9 and above (<code>$normalmap</code>). These should be animated unless the water is to be perfectly still or you're using a flow map, which makes an animated bump map redundant.
: Applies a screen overlay when the camera is underwater. Generally used with <code>effects\water_warp01</code>. Requires <code>$abovewater</code> to be 0.
+
: {{note|The <code>[[normalmap|$normalmap]]</code> parameter is unique to the <code>Water</code> shader, and uses a [[normalmap|normal map]]. A [[Du/dv_map|du/dv map]] is used for {{ent|$bumpmap}} when using the <code>Water</code> shader. The <code>[[Du/dv_map|$dudvmap]]</code> command is obsolete.}} {{tip|Use <code>$bumptransform</code> with the [[TextureScroll]] proxy to move the normal map in pre-2006 engine branches.}}}}
; <code>[[Du/dv_map|$bumpmap]] <texture></code>
+
{{MatParam|$dudvframe|int}}
; <code>[[normalmap|$normalmap]] <texture></code>
+
{{MatParam|$bumpframe|int|Frame to start the animated du/dv map and bump map on, respectively. Somewhat confusingly, <code>$bumpframe</code> affects <code>$''normal''map</code>, which should be pointing to a [[bump map]].}}
: A [[Du/dv map]] for DirectX 8 rendering (<code>$bumpmap</code>), and a [[bump map]] for DirectX 9 and above (<code>$normalmap</code>). These should be animated unless the water is to be perfectly still.
+
{{MatParam|$bumptransform|matrix|Transforms the bump map texture.
: {{note|The <code>[[normalmap|$normalmap]]</code> command is unique to the <code>Water</code> shader, and uses a [[normalmap|normal map]]. A [[Du/dv_map|du/dv map]] is used for <code>[[$bumpmap]]</code> when using the <code>Water</code> shader. The <code>[[Du/dv_map|$dudvmap]]</code> command is obsolete.}} {{tip|Use <code>$bumptransform</code> with the [[TextureScroll]] proxy to move the normal map.}}
+
{{VMT UVtransform}}}}
; <code>$dudvframe <[[int]]></code>
+
{{MatParam|$scale|vector2|{{todo|What does this do?}}}}
; <code>$bumpframe <int></code>
+
{{MatParam|$flashlighttint|float|{{confirm|How much projected textures should tint the water?}}|since=l4d2}}
: Frame to start the animated du/dv map and bump map on, respectively. Somewhat confusingly, <code>$bumpframe</code> affects <code>$''normal''map</code>, which should be pointing to a [[bump map]].
+
{{MatParam|$waterdepth|float|{{todo|What does this do exactly? Seems like it's related to $waterblendfactor, Found in liquids/nuke_water.vmt. Found in 2006/2007 code, does it do anything there?}}|since=CSGO}}
; {{l4d2 add|<code>$flashlighttint <[[int]]></code>}}
+
{{MatParam|$depth_feather|int|{{todo|What does this do exactly? Found in liquids/nuke_water.vmt.}}|since=CSGO}}
: {{confirm|How much projected textures should tint the water?}}
 
; {{p2 add|<code>$pseudotranslucent <[[bool]]></code>}}
 
: {{todo|What does this do exactly?}}
 
; {{p2 add|<code>$waterblendfactor <[[float]]></code>}}
 
: {{todo|What does this do exactly? Seems like it's related to $pseudotranslucent.}}
 
; {{CSGO add|<code>$waterdepth <[[int]]></code>}}
 
: {{todo|What does this do exactly? Seems like it's related to $waterblendfactor, Found in liquids/nuke_water.vmt.}}
 
; {{CSGO add|<code>$depth_feather <[[int]]></code>}}
 
: {{todo|What does this do exactly? Found in liquids/nuke_water.vmt.}}
 
; {{CSGO add|<code>$nofresnel <[[bool]]></code>}}
 
: Disable fresnel on the water. {{todo|Check if this does anything, as it's commented out in liquids/nuke_water.vmt, and isn't used anywhere else so far.}}
 
; {{CSGO add|<code>$forcefresnel <[[int]]></code>}}
 
: Force this amount of fresnel on the water. {{todo|Check if this does anything, as it's commented out in liquids/nuke_water.vmt, and isn't used anywhere else so far.}}
 
  
 
=== Fog ===
 
=== Fog ===
  
; <code>$fogcolor <[[RGB]] matrix></code>
+
{{MatParam|$fogenable|bool|Enable volumetric fog for the water.}}
: This is the color of the water’s volumetric fog. Generally this value should match the color used in the bottom material.
+
{{MatParam|$fogcolor|RGB matrix|Color of the water’s volumetric fog. Generally this value should match the color used in the bottom material.}}
; {{l4d2 add|<code>$lightmapwaterfog <[[bool]]></code>}}
+
{{MatParam|$fogstart|float|Distance in inches from the eye at which water fog starts.
: Allows the fog to receive [[lightmap]]s, so that static objects can cast shadows onto the water. Must be enabled when the map is compiled.
+
: {{warning|Must be 0 for edge fading to work properly.}}}}
; <code>$fogenable <[[bool]]></code>
+
{{MatParam|$fogend|float|Distance in inches from the eye at which water fog ends.}}
: Enable volumetric fog for the water.
+
{{MatParam|$lightmapwaterfog|bool|Allows the fog to receive [[lightmap]]s, so that static objects can cast shadows onto the water. This must be enabled when the map is compiled.|since=l4d2}}
; <code>$fogend <[[float]]></code>
 
: This is the distance in inches from the eye at which water fog ends.
 
; <code>$fogstart <[[float]]></code>
 
: This is the distance in inches from the eye at which water fog starts. {{warning|Must be <code>0</code> for edge fading to work properly.}}
 
  
=== Reflection/Refraction ===
+
=== Reflection ===
  
; {{p2 add|<code>$forceenvmap <[[bool]]></code>}}
+
{{MatParam|$reflecttexture|texture|Texture to use for reflection. For real-time reflections, use {{ent|_rt_WaterReflection}}.}}
: Forces the water to use $envmap for reflections.
+
{{MatParam|$reflectamount|float|Amount of warp for the reflection. Higher values produce more visible reflections.}}
; <code>$envmap <[[env_cubemap]] / [[texture]]></code>
+
{{MatParam|$reflecttint|RGB matrix|Color tint for both expensive and cheap reflections.}}
: See <code>[[$envmap]]</code>. Provides reflections for cheap water.
+
{{MatParam|[[$envmap]]|env_cubemap / texture|See {{ent|$envmap}}. Provides reflections for cheap water.
; <code>$forcecheap <[[bool]]></code>
+
: {{Note|Don't use this on underwater materials.}}}}
: Make this water [[cheap]] regardless of the water_lod_control entity's or user's settings. This will disable real-time reflection and instead use <code>$envmap</code>. Refraction is assumed to be opaquely the water fog color.
+
{{MatParam|$envmapframe|int|The frame to start an animated cubemap on.}}
; <code>$forceexpensive <[[bool]]></code>
+
{{MatParam|$forceenvmap|bool|Forces the water to use <code>$envmap</code> for reflections.|since=p2}}
: This forces the water to render itself as [[expensive]], regardless of the map's [[water_lod_control]] or the user's settings.
+
{{MatParam|$forcecheap|bool|Force the water to render itself as [[cheap]], regardless of the map's {{ent|water_lod_control}} entity settings or the user's settings. This will disable real-time reflection and instead use <code>$envmap</code>. Refraction is assumed to be opaquely the water fog color.}}
; {{p2 add|<code>$reflect2dskybox</code>}}
+
{{MatParam|$forceexpensive|bool|Force the water to render itself as [[expensive]], regardless of the map's <code>water_lod_control</code> entity settings or the user's settings.}}
: Makes this water reflect the [[skybox]] material ''in addition'' to other reflections.
+
{{MatParam|$cheapwaterstartdistance|float|Distance from the eye in inches that the shader should start transitioning to a cheaper water shader.}}
; {{l4d2 add|<code>$reflectskyboxonly</code>}}
+
{{MatParam|$cheapwaterenddistance|float|Distance from the eye in inches that the shader should finish transitioning to a cheaper water shader.}}
: Makes this water reflect the [[skybox]] only.
+
{{MatParam|$reflectentities|bool|Make the water reflect entities. By default, no entities are reflected.}}
; {{p2 add|<code>$reflectonlymarkedentities <[[bool]]></code>}}
+
{{MatParam|$reflectonlymarkedentities|bool|Make the water reflect only entities and static props with "Render in Fast Reflections" enabled.|since=p2}}
: Whether or not to reflect only entities and static props with "Render in Fast Reflections" on.
+
{{MatParam|$reflectskyboxonly|bool|Make the water reflect only the [[skybox]].|since=l4d2}}
; <code>$reflectamount <[[float]]></code>
+
{{MatParam|$reflect2dskybox|bool|Make the water reflect the [[skybox]] material ''in addition'' to other reflections.|since=p2}}
: This is the amount of warp for the reflection. Higher values produce more visible reflections.
+
{{MatParam|$reflect3dskybox|bool|Make the water reflect the 3D skybox ''in addition'' to other reflections. Added in the Danger Zone update and used on '''dz_blacksite.'''
; <code>$reflectentities <[[bool]]></code>
+
: {{Note|Requires a {{ent|sky_camera}} entity to be placed in the map, otherwise this might cause crashes.}}|only=CSGO}}
: Make the water reflect entities. By default, no entities are reflected.
+
{{MatParam|$reflectblendfactor|float|{{todo|What does this do?}}}}
; <code>$reflecttexture <[[texture]]></code>
+
{{MatParam|$nofresnel|bool|Disable the fresnel on the water's reflection.
: Texture to use for reflection. For real-time reflections, use <code>[[_rt_WaterReflection]]</code>.
+
: {{Bug|Does not do anything in any engine branch.}}|since=EP1}}
: {{tip|Specify <code>$refracttexture</code> without <code>$reflecttexture</code> to get real-time refraction on <code>[[$envmap]]</code> reflections.}}
+
{{MatParam|$forcefresnel|float|Force this amount of fresnel on the water. Higher values usually cause the water to appear brighter. {{bug|Does not work properly in {{insurgency}}{{doi}}.}}|since=AS}}
; <code>$reflecttint <[[RGB]] matrix></code>
+
{{MatParam|$basereflectance|float|{{todo|What is this?}}}}
: This is the color tint for the real-time reflection and environment map.
+
{{MatParam|$maxreflectance|float|{{todo|What is this?}}}}
; {{l4d2 add|<code>$refract <[[bool]]></code>}}
 
: Whether the material should refract at all.
 
; <code>$refractamount <[[float]]></code>
 
: This is the amount of warp for the refraction. Higher values produce more warping.
 
; <code>$refracttexture <[[texture]]></code>
 
: Texture to use for refraction. For real-time refractions, use <code>[[_rt_WaterRefraction]]</code>.
 
: {{tip|Specify <code>$refracttexture</code> without <code>$reflecttexture</code> to get real-time refraction on <code>$envmap</code> reflections.}}
 
; <code>$refracttint <[[RGB]] matrix></code>
 
: This is the color of the refraction.
 
: {{warning|It is recommended that you set this to white or something close to white so that edge transitions work properly on DX9.}}
 
; <code>$basereflectance <[[float]]></code>
 
: {{todo|What is this?}}
 
; <code>$maxreflectance <[[float]]></code>
 
: {{todo|What is this?}}
 
  
 +
===Refraction===
 +
 +
{{MatParam|$refract|bool|Whether the material should refract at all.|since=l4d2}}
 +
{{MatParam|$refracttexture|texture|Texture to use for refraction. For real-time refractions, use {{ent|_rt_WaterRefraction}}.
 +
: {{tip|Specify <code>$refracttexture</code> without <code>$reflecttexture</code> to get real-time refraction on <code>$envmap</code> reflections.}}}}
 +
{{MatParam|$refractamount|float|Amount of warp for the refraction. Higher values produce more warping.}}
 +
{{MatParam|$refracttint|RGB matrix|Color of the refraction.
 +
: {{warning|It is recommended that you set this to white or something close to white so that edge transitions work properly on DX9.}}}}
 +
{{MatParam|$blurrefract|bool|Blurs the refraction when underwater.
 +
: {{warning|Underwater materials only; this will cause buggy behavior on any material with <code>$abovewater</code> set to 1.}}|since=EP2|dx9=1}}
 +
{{MatParam|$pseudotranslucent|bool|Make the water translucent. This is a cheap substitute for refractive water; do not use this when refraction is enabled.|since=p2}}
 +
{{MatParam|$waterblendfactor|normal|How translucent the water should be when <code>$pseudotranslucent</code> is enabled. At 0, the water is completely transparent, while at 1 the water is completely opaque.|since=p2}}
 +
 +
; [[Image:Orange Box Scrolling Water.png|right|300px|Size/angle of $scroll1 and $scroll2]]
 
=== Flowing water ===
 
=== Flowing water ===
 
+
; <code>$scroll1 "[<[[normal]] X> <normal Y>]"</code> {{EP1 add}}
; [[Image:Orange Box Scrolling Water.png|right|300px|Size/angle of $scroll1 and $scroll2]] {{EP2 add|<code>$scroll1 "[<[[normal]] X> <normal Y>]"</code>}}
+
; <code>$scroll2 "[<[[normal]] X> <normal Y>]"</code> {{EP1 add}}
; {{EP2 add|<code>$scroll2 "[<normal X> <normal Y>]"</code>}}
 
 
: If <code>$scroll1</code> is defined and X is not zero, two more instances of the normal map will be drawn in such a way that they are merged together. The first layer is 7x larger and rotated 45&deg;; the second is 2x larger and rotated 90&deg;. The parameters specify the speed and direction that the extra layers will move. (Valve's materials usually contain a third number, but it doesn't have any apparent effect and is most likely obsolete.)
 
: If <code>$scroll1</code> is defined and X is not zero, two more instances of the normal map will be drawn in such a way that they are merged together. The first layer is 7x larger and rotated 45&deg;; the second is 2x larger and rotated 90&deg;. The parameters specify the speed and direction that the extra layers will move. (Valve's materials usually contain a third number, but it doesn't have any apparent effect and is most likely obsolete.)
 
+
==== Flow maps ====
 
+
[[File:L4d2 flowmap tex.jpg|right|200px|A flow map texture.]] [[File:L4d2 flowmap dev.jpg|right|200px|The flow map texture in-engine, shown with $flow_debug 1.]] [[File:L4d2 flowmap user.jpg|right|200px|The result in-engine.]]
 
+
{{MatParam|$flowmap|texture|Texture that defines flow velocity by skewing and scrolling the <code>$normalmap</code>. Valve generates their flowmaps with [https://www.sidefx.com/products/houdini/ Houdini].
==== Flowmaps ====
+
: [http://www.youtube.com/watch?v{{=}}iY6vkpQDcpU Video of the effect.] For technical details, see [https://steamcdn-a.akamaihd.net/apps/valve/2010/siggraph2010_vlachos_waterflow.pdf Alex Vlachos' SIGGRAPH 2010 paper] and [https://steamcdn-a.akamaihd.net/apps/valve/2011/gdc_2011_grimes_nonstandard_textures.pdf Valve's GDC 2011 paper].|since=l4d2}}
{{MatVar|$flowmap|texture|3=This is a texture that defines flow velocity by skewing and scrolling the $normalmap. This effect isn't limited to the water shader, It was first used for the purple Vortigaunt warp effect seen in Episode 1 and 2. For the preservation of sanity Valve generate theirs with [http://www.sidefx.com/index.php?option=com_content&task=view&id=1774&Itemid=343 Houdini]
+
{{MatParam|$flow_normaluvscale|float|The number of world units covered by the normal map before it repeats. Typically in the 100s.|since=l4d2}}
: [[File:L4d2 flowmap user.jpg|300px]] [[File:L4d2 flowmap tex.jpg|169px]] [[File:L4d2 flowmap dev.jpg|300px]]
+
{{MatParam|$flow_worlduvscale|float|The number of times the flow map fits into the material. Face texture scale affects this.|since=l4d2}}
: [http://www.youtube.com/watch?v=iY6vkpQDcpU See a clip of the effect on YouTube.] For a detailed description of how it all works see [http://www.valvesoftware.com/publications/2010/siggraph2010_vlachos_waterflow.pdf Alex Vlachos' SIGGRAPH 2010 paper].
+
{{MatParam|$flow_uvscrolldistance|float|How far along the flow map the normal map should be distorted. Higher values lead to more distortion.|since=l4d2}}
}}
+
{{MatParam|$flow_timeintervalinseconds|float|Time needed for the normal map to cross the <code>$flow_uvscrolldistance</code>.|since=l4d2}}
{{MatVar|$flow_normaluvscale|float|The number of world units covered by the normal map before it repeats. Typically in the 100s.}}
+
{{MatParam|$flow_timescale|float|Modifies flow speed without affecting the amount of distortion.|since=l4d2}}
{{MatVar|$flow_worlduvscale|float|The number of times the flow map fits into the material. Face texture scale affects this.}}
+
{{MatParam|$flow_bumpstrength|normal|How rough the surface of the water is.|since=l4d2}}
{{MatVar|$flow_uvscrolldistance|float|How far along the flow map the normal map should be distorted. Higher values lead to more distortion.}}
+
{{MatParam|$flow_noise_texture|texture|A treatment texture used to break up repetition of the normal map.|since=l4d2}}
{{MatVar|$flow_timeintervalinseconds|float|Time needed for the normal map to cross the <code>$flow_uvscrolldistance</code>.}}
+
{{MatParam|$flow_noise_scale|float|How many times to fit the noise texture into the normal map. Typically around 0.01.|since=l4d2}}
{{MatVar|$flow_timescale|float|Modifies flow speed without affecting the amount of distortion.}}
+
{{MatParam|$flow_debug|bool|Replaces the water surface with a literal rendering of the flow map. {{bug|Although the flow map will show up in Hammer, it may not be in the correct place! Don't rely on Hammer's view for alignment.}}|since=l4d2}}
{{MatVar|$flow_bumpstrength|normal|How rough surface of the water is. Going above 1 is not recommended.}}
 
{{MatVar|$flow_noise_texture|texture|A treatment texture used to break up repetition of the normal map.}}
 
{{MatVar|$flow_noise_scale|float|How many times to fit the noise texture into the normal map. Typically around 0.01.}}
 
{{MatVar|$flow_debug|bool|Replaces the water surface with a literal rendering of the flow map. {{bug|Although the flow map will show up in Hammer, it may not be in the correct place! Don't rely on Hammer's view for alignment.}}}}
 
  
 
==== Basetexture Flow ====
 
==== Basetexture Flow ====
; {{p2 add|<code>$basetexture <texture></code>}}
+
{{MatParam|$basetexture|texture|A "sludge layer", used in {{portal2}} for the sludge and debris in test chambers. The alpha channel of the <code>$basetexture</code> acts as a mask for the reflection; darker values are more reflective, while lighter values are less reflective.
: Used to create the floating debris and sludge inside test chambers.
+
: {{Note|From {{portal2}} onwards, the opacity of the <code>$basetexture</code> is controlled by the alpha channel of the flow map.}}|since=AS}}
 
+
{{MatParam|$color_flow_uvscale|float|The number of world units covered by the base texture before it repeats. Typically in the 100s.|since=AS}}
{{MatVar|$color_flow_uvscale|float|The number of world units covered by the basetexture before it repeats. Typically in the 100s.}}
+
{{MatParam|$color_flow_timescale|float|Modifies flow speed without affecting the amount of distortion.|since=AS}}
{{MatVar|$color_flow_timeintervalinseconds|float|Time needed for the normal map to cross the <code>$color_flow_uvscrolldistance</code>.}}
+
{{MatParam|$color_flow_timeintervalinseconds|float|Time needed for the base texture to cross the <code>$color_flow_uvscrolldistance</code>.|since=AS}}
{{MatVar|$color_flow_uvscrolldistance|float|How far along the flow map the normal map should be distorted. Higher values lead to more distortion.}}
+
{{MatParam|$color_flow_uvscrolldistance|float|How far along the flow map the base texture should be distorted. Higher values lead to more distortion.|since=AS}}
{{MatVar|$color_flow_lerpexp|float|How sharp the transition between repeats, should be 1.}}
+
{{MatParam|$color_flow_lerpexp|float|How sharp the transition should be between repeats, should be 1.
:{{todo|Better explanation}}
+
: {{todo|Better explanation}}|since=AS}}
{{MatVar|$color_flow_displacebynormalstrength|float|How much the normalmap effects the basetexture. around 0.01}}
+
{{MatParam|$color_flow_displacebynormalstrength|float|How much the normal map affects the base texture. Uses extremely low values, usually 0.01 or less.|since=p2}}
  
 
==== Authoring a flow map ====
 
==== Authoring a flow map ====
Line 138: Line 116:
 
[[File:Water_flow_test.png|thumb|200px|Directions of water flow depend on the red and green channels of the flow map.]]
 
[[File:Water_flow_test.png|thumb|200px|Directions of water flow depend on the red and green channels of the flow map.]]
  
Overall, trying to create a flow map manually is a nightmare. Painting the flowmap, fitting it into the world, and painting foam, is extremely difficult.
+
Overall, trying to create a flow map manually is a nightmare. Painting the flow map, fitting it into the world, and painting foam, is extremely difficult.
  
 
But if you do want to give it a try, flow direction is read from the red and green channels of the flow map. 50% tone means no movement.
 
But if you do want to give it a try, flow direction is read from the red and green channels of the flow map. 50% tone means no movement.
Line 149: Line 127:
 
: Y axis
 
: Y axis
 
; Alpha channel
 
; Alpha channel
: In Portal 2, Controls basetexture blend (water/sludge)
+
: Controls <code>$basetexture</code> blending from {{portal2}} onwards.
 
 
  
;There are now tools to assist in painting flowmaps.
+
; There are now tools to assist in painting flowmaps.
:Flow field editor from algoholic.eu : http://algoholic.eu/another-flow-field-editor-update/
+
: Flow field editor from algoholic.eu : http://algoholic.eu/another-flow-field-editor-update/
:Flowmap generator (paid): http://www.superpositiongames.com/products/flowmap-generator
+
: Flowmap generator (paid): http://www.superpositiongames.com/products/flowmap-generator
:Creating flowmaps using Houdini (UDK) : https://www.dropbox.com/s/ii2x077vj64lyhl/Water%20Flow%20For%20UDK.pdf
+
: Creating flowmaps using Houdini (UDK) : https://www.dropbox.com/s/ii2x077vj64lyhl/Water%20Flow%20For%20UDK.pdf
  
 
=== Other ===
 
=== Other ===
  
; <code>%compilewater <bool></code>
+
{{MatParam|%compilewater|bool|This is needed to make a map using the material compile properly.}}
: This is needed to make a map using the material compile properly.
+
{{MatParam|$surfaceprop|water|Tells the physics system that the surface is water. See [[$surfaceprop]].}}
; <code>$surfaceprop water</code>
+
{{MatParam|%tooltexture|texture|Defines the texture Hammer will display in the material browser.}}
: Tells the physics system that the surface is water. See [[$surfaceprop]].
 
; <code>%tooltexture <texture></code>
 
: Defines the texture Hammer will display in the material browser.
 
 
; <code>WaterLOD proxy</code>
 
; <code>WaterLOD proxy</code>
 
: This connects the [[water_lod_control]] entity in a level to the water’s internal parameters. This must be declared in the material for the LOD mechanisms to work properly.
 
: This connects the [[water_lod_control]] entity in a level to the water’s internal parameters. This must be declared in the material for the LOD mechanisms to work properly.
Line 175: Line 149:
 
*[[True reflections under CSS:fr|True reflections under CSS]] (French)
 
*[[True reflections under CSS:fr|True reflections under CSS]] (French)
  
[[Category:Shaders]]
 
[[Category:List of Shader Parameters]]
 
 
[[Category:Water]]
 
[[Category:Water]]

Latest revision as of 20:53, 25 August 2019

Water reflecting entities in real-time in Episode Two.

Water is a material shader available in all Source games. It creates water that realistically reflects and refracts the world, and that can flow throughout a map.

Special behaviour

Expensive and cheap
Water materials fall into two groups: expensive and cheap. Expensive water reflects and refracts the world in real-time, while cheap water uses an $envmap and does not refract. Users can disable expensive water rendering through their video options, so always place env_cubemap entities throughout a map.
Above and below
Water actually requires two materials: one for above the surface and one for below. These materials are independent of each other, but for proper effect need to correlate in most areas.
Flow Mapping
Water can flow in arbitrary directions. It's very tricky to create a flow map by hand however, and the tool Valve used internally hasn't been released.

Shader parameters

Textures

Note:In games before <Alien Swarm>, there is no $basetexture. The surface is a combination of fog color, animated bump map, reflection and refraction.
$abovewater <boolean>
Whether this material is used for above or below the water’s surface.
$bottommaterial <material>
Required parameter. This is the material (not texture) to use when underneath the water’s surface. The bottom material must have $reflecttexture, $abovewater and $envmap disabled, but can otherwise do whatever it wants.
$underwateroverlay <material> (New with Half-Life 2: Episode Two / Source 2007)
Applies a refracting screen overlay when the camera is underwater. Generally used with effects\water_warp01. Requires $abovewater to be 0.
$bumpmap <texture> (DX8)
$normalmap <texture>
A Du/dv map for DirectX 8 rendering ($bumpmap), and a bump map for DirectX 9 and above ($normalmap). These should be animated unless the water is to be perfectly still or you're using a flow map, which makes an animated bump map redundant.
Note:The $normalmap parameter is unique to the Water shader, and uses a normal map. A du/dv map is used for $bumpmap when using the Water shader. The $dudvmap command is obsolete.
Tip:Use $bumptransform with the TextureScroll proxy to move the normal map in pre-2006 engine branches.
$dudvframe <integer>
$bumpframe <integer>
Frame to start the animated du/dv map and bump map on, respectively. Somewhat confusingly, $bumpframe affects $normalmap, which should be pointing to a bump map.
$bumptransform <matrix>
Transforms the bump map texture.
The default position is "center .5 .5 scale 1 1 rotate 0 translate 0 0".
  1. center defines the point of rotation. Only useful if rotate is being used.
  2. scale fits the texture into the material the given number of times. '2 1' is a 50% scale in the X axis.
  3. rotate rotates the texture counter-clockwise in degrees. Accepts any number, including negatives.
  4. translate shifts the texture by the given numbers. '.5' will shift it half-way.
Note:All values must be included!
Bug: Scaling the texture may cause odd issues where the Texture Lock tool in Hammer will not actually lock the texture in place.
Bug: Rotating textures applied on brushes will rotate around the map origin (confirm: Orangebox engine only?). A fix for this is to change the center position in the VMT to the brush's origin.
$scale <vector2>
To do: What does this do?
$flashlighttint <float> (New with Left 4 Dead 2)
Confirm:How much projected textures should tint the water?
$waterdepth <float> (New with Counter-Strike: Global Offensive)
To do: What does this do exactly? Seems like it's related to $waterblendfactor, Found in liquids/nuke_water.vmt. Found in 2006/2007 code, does it do anything there?
$depth_feather <integer> (New with Counter-Strike: Global Offensive)
To do: What does this do exactly? Found in liquids/nuke_water.vmt.

Fog

$fogenable <boolean>
Enable volumetric fog for the water.
$fogcolor <RGB matrix>
Color of the water’s volumetric fog. Generally this value should match the color used in the bottom material.
$fogstart <float>
Distance in inches from the eye at which water fog starts.
Warning: Must be 0 for edge fading to work properly.
$fogend <float>
Distance in inches from the eye at which water fog ends.
$lightmapwaterfog <boolean> (New with Left 4 Dead 2)
Allows the fog to receive lightmaps, so that static objects can cast shadows onto the water. This must be enabled when the map is compiled.

Reflection

$reflecttexture <texture>
Texture to use for reflection. For real-time reflections, use _rt_WaterReflection.
$reflectamount <float>
Amount of warp for the reflection. Higher values produce more visible reflections.
$reflecttint <RGB matrix>
Color tint for both expensive and cheap reflections.
$envmap <env_cubemap / texture>
See $envmap. Provides reflections for cheap water.
Note:Don't use this on underwater materials.
$envmapframe <integer>
The frame to start an animated cubemap on.
$forceenvmap <boolean> (New with Portal 2)
Forces the water to use $envmap for reflections.
$forcecheap <boolean>
Force the water to render itself as cheap, regardless of the map's water_lod_control entity settings or the user's settings. This will disable real-time reflection and instead use $envmap. Refraction is assumed to be opaquely the water fog color.
$forceexpensive <boolean>
Force the water to render itself as expensive, regardless of the map's water_lod_control entity settings or the user's settings.
$cheapwaterstartdistance <float>
Distance from the eye in inches that the shader should start transitioning to a cheaper water shader.
$cheapwaterenddistance <float>
Distance from the eye in inches that the shader should finish transitioning to a cheaper water shader.
$reflectentities <boolean>
Make the water reflect entities. By default, no entities are reflected.
$reflectonlymarkedentities <boolean> (New with Portal 2)
Make the water reflect only entities and static props with "Render in Fast Reflections" enabled.
$reflectskyboxonly <boolean> (New with Left 4 Dead 2)
Make the water reflect only the skybox.
$reflect2dskybox <boolean> (New with Portal 2)
Make the water reflect the skybox material in addition to other reflections.
$reflect3dskybox <boolean> (Only in Counter-Strike: Global Offensive)
Make the water reflect the 3D skybox in addition to other reflections. Added in the Danger Zone update and used on dz_blacksite.
Note:Requires a sky_camera entity to be placed in the map, otherwise this might cause crashes.
$reflectblendfactor <float>
To do: What does this do?
$nofresnel <boolean> (New with Half-Life 2: Episode One / Source 2006)
Disable the fresnel on the water's reflection.
Bug: Does not do anything in any engine branch.
$forcefresnel <float> (New with Alien Swarm)
Force this amount of fresnel on the water. Higher values usually cause the water to appear brighter.
Bug: Does not work properly in <Insurgency><Day of Infamy>.
$basereflectance <float>
To do: What is this?
$maxreflectance <float>
To do: What is this?

Refraction

$refract <boolean> (New with Left 4 Dead 2)
Whether the material should refract at all.
$refracttexture <texture>
Texture to use for refraction. For real-time refractions, use _rt_WaterRefraction.
Tip:Specify $refracttexture without $reflecttexture to get real-time refraction on $envmap reflections.
$refractamount <float>
Amount of warp for the refraction. Higher values produce more warping.
$refracttint <RGB matrix>
Color of the refraction.
Warning: It is recommended that you set this to white or something close to white so that edge transitions work properly on DX9.
$blurrefract <boolean> (New with Half-Life 2: Episode Two / Source 2007) (DX9+)
Blurs the refraction when underwater.
Warning: Underwater materials only; this will cause buggy behavior on any material with $abovewater set to 1.
$pseudotranslucent <boolean> (New with Portal 2)
Make the water translucent. This is a cheap substitute for refractive water; do not use this when refraction is enabled.
$waterblendfactor <normal> (New with Portal 2)
How translucent the water should be when $pseudotranslucent is enabled. At 0, the water is completely transparent, while at 1 the water is completely opaque.
Size/angle of $scroll1 and $scroll2

Flowing water

$scroll1 "[<normal X> <normal Y>]" (New with Half-Life 2: Episode One / Source 2006)
$scroll2 "[<normal X> <normal Y>]" (New with Half-Life 2: Episode One / Source 2006)
If $scroll1 is defined and X is not zero, two more instances of the normal map will be drawn in such a way that they are merged together. The first layer is 7x larger and rotated 45°; the second is 2x larger and rotated 90°. The parameters specify the speed and direction that the extra layers will move. (Valve's materials usually contain a third number, but it doesn't have any apparent effect and is most likely obsolete.)

Flow maps

A flow map texture.
The flow map texture in-engine, shown with $flow_debug 1.
The result in-engine.
$flowmap <texture> (New with Left 4 Dead 2)
Texture that defines flow velocity by skewing and scrolling the $normalmap. Valve generates their flowmaps with Houdini.
Video of the effect. For technical details, see Alex Vlachos' SIGGRAPH 2010 paper and Valve's GDC 2011 paper.
$flow_normaluvscale <float> (New with Left 4 Dead 2)
The number of world units covered by the normal map before it repeats. Typically in the 100s.
$flow_worlduvscale <float> (New with Left 4 Dead 2)
The number of times the flow map fits into the material. Face texture scale affects this.
$flow_uvscrolldistance <float> (New with Left 4 Dead 2)
How far along the flow map the normal map should be distorted. Higher values lead to more distortion.
$flow_timeintervalinseconds <float> (New with Left 4 Dead 2)
Time needed for the normal map to cross the $flow_uvscrolldistance.
$flow_timescale <float> (New with Left 4 Dead 2)
Modifies flow speed without affecting the amount of distortion.
$flow_bumpstrength <normal> (New with Left 4 Dead 2)
How rough the surface of the water is.
$flow_noise_texture <texture> (New with Left 4 Dead 2)
A treatment texture used to break up repetition of the normal map.
$flow_noise_scale <float> (New with Left 4 Dead 2)
How many times to fit the noise texture into the normal map. Typically around 0.01.
$flow_debug <boolean> (New with Left 4 Dead 2)
Replaces the water surface with a literal rendering of the flow map.
Bug: Although the flow map will show up in Hammer, it may not be in the correct place! Don't rely on Hammer's view for alignment.

Basetexture Flow

$basetexture <texture> (New with Alien Swarm)
A "sludge layer", used in [Portal 2] for the sludge and debris in test chambers. The alpha channel of the $basetexture acts as a mask for the reflection; darker values are more reflective, while lighter values are less reflective.
Note:From [Portal 2] onwards, the opacity of the $basetexture is controlled by the alpha channel of the flow map.
$color_flow_uvscale <float> (New with Alien Swarm)
The number of world units covered by the base texture before it repeats. Typically in the 100s.
$color_flow_timescale <float> (New with Alien Swarm)
Modifies flow speed without affecting the amount of distortion.
$color_flow_timeintervalinseconds <float> (New with Alien Swarm)
Time needed for the base texture to cross the $color_flow_uvscrolldistance.
$color_flow_uvscrolldistance <float> (New with Alien Swarm)
How far along the flow map the base texture should be distorted. Higher values lead to more distortion.
$color_flow_lerpexp <float> (New with Alien Swarm)
How sharp the transition should be between repeats, should be 1.
To do: Better explanation
$color_flow_displacebynormalstrength <float> (New with Portal 2)
How much the normal map affects the base texture. Uses extremely low values, usually 0.01 or less.

Authoring a flow map

Directions of water flow depend on the red and green channels of the flow map.

Overall, trying to create a flow map manually is a nightmare. Painting the flow map, fitting it into the world, and painting foam, is extremely difficult.

But if you do want to give it a try, flow direction is read from the red and green channels of the flow map. 50% tone means no movement.

The texture scale of any faces using a water texture with a flow map appear to have a direct correlation on the flow map. The fewer water faces or planes you use the easier the process of authoring a custom flow map will be (selecting all of your water faces and using 'treat as one' when using the fit scaling may also be an option)

Red channel
X axis
Green channel
Y axis
Alpha channel
Controls $basetexture blending from [Portal 2] onwards.
There are now tools to assist in painting flowmaps.
Flow field editor from algoholic.eu : http://algoholic.eu/another-flow-field-editor-update/
Flowmap generator (paid): http://www.superpositiongames.com/products/flowmap-generator
Creating flowmaps using Houdini (UDK) : https://www.dropbox.com/s/ii2x077vj64lyhl/Water%20Flow%20For%20UDK.pdf

Other

%compilewater <boolean>
This is needed to make a map using the material compile properly.
$surfaceprop <water>
Tells the physics system that the surface is water. See $surfaceprop.
%tooltexture <texture>
Defines the texture Hammer will display in the material browser.
WaterLOD proxy
This connects the water_lod_control entity in a level to the water’s internal parameters. This must be declared in the material for the LOD mechanisms to work properly.

See also