View source for Water (shader)

{{LanguageBar|title = Water (shader)}}
{{split|[[Water (shader)]] and [[Liquid materials]].<br>The latter should document the shader-agnostic parameters for %CompileWater and %CompileSlime materials}}
{{this is a|pixel shader|name=Water}}

[[File:Ep2 jalopy.jpg|thumb|200px|Water [[#Reflection|reflecting]] entities in real-time in [[Episode Two]].]]
[[File:L4d2 flowmap user.jpg|thumb|200px|[[Left 4 Dead 2]] introduced [[#Flowing water|flowing water]] and [[#Fog|lightmapped fog]].]]

It creates water that realistically reflects and refracts the world, and that can flow throughout a map.

{{tip|[[Water]] does not ''need'' to use the {{mono|Water}} shader! If a less realistic effect is desired, or the water volume is oddly shaped, other shaders can be used, such as [[LightmappedGeneric]] or [[Refract]]. The method for creating the materials is the same.
{{todo|Move shader-agnostic water parameters to a separate section.}} }}
== Special behaviour ==

; 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 {{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
: <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
: 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 ==

=== Textures ===

{{MatParam|$basetexture|texture|Usually referred to as a "sludge-layer", acts as a layer on top of the surface of the $AboveWater Material.
{{warning|The $BaseTexture will only be lightmapped if there is no $FlowMap!}}
{{warning|When not using a $FlowMap, this parameter does not work with projected textures or $LightMapWaterFog!}}
{{note|In games before {{As}}, the surface is a combination of fog color, animated bump map, reflection and refraction.<br>{{tip|If a BaseTexture is necessary in earlier games, and real-time reflections are not necessary, then the [[Refract]] shader could be used instead.}}}}
|since={{as}}}}

{{MatParam|$abovewater|bool|Whether this material is used for above or below the water’s surface.<br>
{{note|Not setting this in the VMT will automatically force it to 1. If not defined, a warning will appear saying <code>Need to set $abovewater for material x</code>}}}}
{{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. {{tip|Add {{cmd|%notooltexture}} to the bottom material to hide it in the texture browser {{hammer++|not}}.}} }}
{{note|If the above water material does not have reflections, refractions, or $underwateroverlay: $abovewater can be omitted, [[$nocull]] can be used, and $bottommaterial can be set to the same material as the abovewater material.}}
{{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.<br>
{{note|This is technically not a parameter on the water shader, meaning it can be abused for other unintended purposes! The overlay may still be applied even when the underwater material is told not to render ( {{ent|$no_draw}})}}|since={{src07}}}}
{{MatParam|$bumpmap|texture|dx8=1}}
{{MatParam|$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.
: {{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.}}}}
{{MatParam|$dudvframe|int}}
{{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]].}}
{{MatParam|$bumptransform|matrix|Transforms the bump map texture.
{{VMT UVtransform}}}}
{{MatParam|$scale|vector2|Unused Parameter.-Likely a precursor of $RefractAmount and $ReflectAmount.<br>
In {{src13}} and {{as}}'s Shadercode it will bundle up $Reflect/$RefractAmount into a single float4 to save some instructions, like so:<br>
<code>"[$ReflectAmount, $ReflectAmount, $RefractAmount, $RefractAmount]"</code> This is pretty much $Scale but with two more components.<br>
The constant register is referred to as 'g_ReflectRefractScale' as well. The only thing the shader does with it now is set a default value of "[1 1]".}}
{{MatParam|$flashlighttint|float|Tints the results of projected textures on the water. The flashlight mainly affects the brightness of the fog in the water. A comment in {{as}}'s Shadercode explains :<br>
"The flashlight on the water surface is basically the diffuse flashlight * waterfogcolor * g_flFlashlightTint.
g_flFlashlightTint is tweakable in cases where the water fog color is really dark and the flashlight doesn't show up, etc."|since={{l4d2}}}}
{{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}}}}
{{MatParam|$depth_feather|int|{{todo|What does this do exactly? Found in liquids/nuke_water.vmt.}}|since={{csgo}}}}

=== Fog ===

{{MatParam|$fogenable|bool|Enable volumetric fog for the water. If disabled on the Water shader, fog will be applied to the brush uniformly.<br>
{{note|This parameter does not exist on the shader itself, the logic behind it is handled somewhere else.}}}}
{{MatParam|$fogcolor|RGB matrix|Color of the water’s volumetric fog. Generally this value should match the color used in the bottom material.<br>
{{Important| If this parameter is not defined in a VMT, the shader will force its value to <code>"[1 0 0]"</code> and spew an error message saying <code>Material x needs to have a $fogcolor.</code>}}
{{warning|
Cheap water treats this parameters as a linear value where 0.0 is 0% and 1.0 is 100%.<br>
Expensive water treats this parameter as a Gamma value,<br>
and due do this, each component ( red, green and blue respectively ) can not go above 1.0 or below 0.0 ( on expensive water )<br>
To calculate the eventual linear value that the shader is supplied with, apply the formula <code>x^(1/2.2)</code>{{tip|While expensive water cannot, cheap water ''can'' go higher than 1.0, achieving a more "neon" effect.}} }}}}

{{MatParam|$fogstart|float|Distance in units/inches from the eye at which water fog starts.
: {{warning|Must be 0 for edge fading to work properly.}}}}
{{MatParam|$fogend|float|Distance in units/inches from the eye at which water fog ends.}}
{{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. <br>
{{note| Bumped Lightmaps are only enabled when a $BaseTexture has been defined, without it, a regular Lightmap will be used instead.}}
{{warning|This feature does not exist for cheap water.}}
|since={{l4d2}}}}

=== Reflection ===

{{MatParam|$reflecttexture|texture|Texture to use for reflection. For real-time reflections, use {{ent|_rt_WaterReflection}}.}}
{{MatParam|$reflectamount|float|Amount of warp for the reflection. Higher values produce more visible reflections.}}
{{MatParam|$reflecttint|RGB matrix|Color tint for both expensive and cheap reflections.<br>
{{warning|
This parameter is in Gamma space on expensive water, meaning it will be converted to linear before being sent to the shader.<br>
To calculate the eventual linear value that the shader is supplied with, apply the formula <code>x^(1/2.2)</code>}}}}
{{MatParam|$envmap|env_cubemap / texture|See {{ent|$envmap}}. Provides reflections for cheap water.
: {{Note|Don't use this on underwater materials{{why}}.}}}}
{{MatParam|$envmapframe|int|The frame to start an animated cubemap on.}}
{{MatParam|$forceenvmap|bool|Forces the water to use <code>$envmap</code> for reflections.|since={{portal2}}}}
{{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.}}
{{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.}}
{{MatParam|$cheapwaterstartdistance|float|Distance from the eye in inches that the shader should start transitioning to a cheaper water shader.}}
{{MatParam|$cheapwaterenddistance|float|Distance from the eye in inches that the shader should finish transitioning to a cheaper water shader.}}
{{MatParam|$reflectentities|bool|Make the water reflect entities. By default, no entities are reflected.}}
{{MatParam|$reflectonlymarkedentities|bool|Make the water reflect only entities and static props with "Render in Fast Reflections" enabled.|since={{portal2}}}}
{{MatParam|$reflectskyboxonly|bool|Make the water reflect only the [[skybox]].{{bug|'''Not''' using this setting in {{l4d2}} causes the {{ent|env_sun}} sprite to appear through the floor whenever water without "reflectskyboxonly" is on screen.}}|since={{l4d2}}}}
{{MatParam|$reflect2dskybox|bool|Make the water reflect the [[skybox]] material ''in addition'' to other reflections.|since={{portal2}}}}
{{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.'''
: {{Note|Requires a {{ent|sky_camera}} entity to be placed in the map, otherwise this might cause crashes.}}|only={{csgo}}}}
{{MatParam|$reflectblendfactor|float|{{todo|What does this do?}}}}
{{MatParam|$nofresnel|bool|Disable the fresnel on the water's reflection.
: {{Bug|Does not do anything in any engine branch.}}|since={{src06}}}}
{{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}}}}
{{MatParam|$basereflectance|float|{{todo|What is this?}}}}
{{MatParam|$maxreflectance|float|{{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.<br>
{{warning|It is recommended that you set this to white or something close to white so that edge transitions work properly on DX9.}}
{{warning| This parameter is in Gamma space, meaning it will be converted to linear before being sent to the shader.<br>
To calculate the eventual linear value that the shader is supplied with, apply the formula <code>x^(1/2.2)</code>}}}}
{{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={{src07}}|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={{portal2}}}}
{{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={{portal2}}}}
; [[File:Orange Box Scrolling Water.png|right|300px|Size/angle of $scroll1 and $scroll2]]

=== Flowing water ===

; <code>$scroll1 "[<[[normal]] X> <normal Y>]"</code> {{since|{{src06}}}}
; <code>$scroll2 "[<[[normal]] X> <normal Y>]"</code> {{since|{{src06}}}}
: 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].
: [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].<br>
{{warning|Using this parameter with $BaseTexture will make the $BaseTexture not be affected by lighting.}}|since={{l4d2}}|also={{Xe}}}}
{{MatParam|$flow_normaluvscale|float|The number of world units covered by the normal map before it repeats. Typically in the 100s.|since={{l4d2}}|also={{Xe}}}}
{{MatParam|$flow_worlduvscale|float|The number of times the flow map fits into the material. Face texture scale affects this.|since={{l4d2}}|also={{Xe}}}}
{{MatParam|$flow_uvscrolldistance|float|How far along the flow map the normal map should be distorted. Higher values lead to more distortion.|since={{l4d2}}|also={{Xe}}}}
{{MatParam|$flow_timeintervalinseconds|float|Time needed for the normal map to cross the <code>$flow_uvscrolldistance</code>.|since={{l4d2}}|also={{Xe}}}}
{{MatParam|$flow_timescale|float|Modifies flow speed without affecting the amount of distortion.|since={{l4d2}}}}
{{MatParam|$flow_bumpstrength|normal|How rough the surface of the water is.|since={{l4d2}}|also={{Xe}}}}
{{MatParam|$flow_noise_texture|texture|A treatment texture used to break up repetition of the normal map.|since={{l4d2}}|also={{Xe}}}}
{{MatParam|$flow_noise_scale|float|How many times to fit the noise texture into the normal map. Typically around 0.01.|since={{l4d2}}|also={{Xe}}}}
{{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}}|also={{Xe}}}}
{{todo|Add {{bms|4}} parameters.}}

==== Basetexture Flow ====

{{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.
: {{Note|From {{portal2}} onwards, the opacity of the <code>$basetexture</code> is controlled by the alpha channel of the flow map.}}||since={{as}}|also={{Xe}}}}
{{MatParam|$color_flow_uvscale|float|The number of world units covered by the base texture before it repeats. Typically in the 100s.|since={{as}}|also={{Xe}}}}
{{MatParam|$color_flow_timescale|float|Modifies flow speed without affecting the amount of distortion.|since={{as}}}}
{{MatParam|$color_flow_timeintervalinseconds|float|Time needed for the base texture to cross the <code>$color_flow_uvscrolldistance</code>.|since={{as}}|also={{Xe}}}}
{{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}}|also={{Xe}}}}
{{MatParam|$color_flow_lerpexp|float|How sharp the transition should be between repeats, should be 1.
: {{todo|Better explanation}}|since={{as}}|also={{Xe}}}}
{{MatParam|$color_flow_displacebynormalstrength|float|How much the normal map affects the base texture. Uses extremely low values, usually 0.01 or less.|since={{portal2}}|also={{Xe}}}}
==== Authoring a 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 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 <code>$basetexture</code> blending from {{portal2}} onwards.

; There are now tools to assist in painting flowmaps.
: Flow field editor from algoholic.eu : http://algoholic.eu/another-flow-field-editor-update/ {{Dead link}}
: 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 {{Dead link}}

=== Other ===

{{MatParam|%CompileWater|bool|This is needed to make a map using the material compile properly.}}
{{MatParam|%CompileSlime|bool|Can be used instead of %CompileWater to get different particles. 
{{important|Planar reflections doesn't work with this.}}
}}
{{MatParam|$surfaceprop|water|Tells the physics system that the surface is water. See [[$surfaceprop]].}}
{{MatParam|%tooltexture|texture|Defines the texture Hammer will display in the material browser. Any texture can be used, but it is customary to use the [[$normalmap]].}}
; <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.

== See also ==
* [[Adding Water]] (in Hammer)
* [[Creating a Waterfall Material]]
* [[Making a wall of water]]
* [[True reflections under CSS]]
[[Category:Water]]