View source for Water (shader)

{{lang|Water (shader)}}
[[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]].]]

{{Shader|Water}} It creates water that realistically reflects and refracts the world, and that can flow throughout a map.

== 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 ===

{{note|In games before {{As}}, there is no {{ent|$basetexture}}. The surface is a combination of fog color, animated bump map, reflection and refraction.}}

{{MatParam|$abovewater|bool|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.}}
{{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={{src07}}}}
{{MatParam|[[Du/dv_map|$bumpmap]]|texture|dx8=1}}
{{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.
: {{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|{{todo|What does this do?}}}}
{{MatParam|$flashlighttint|float|{{confirm|How much projected textures should tint the water?}}|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.}}
{{MatParam|$fogcolor|RGB matrix|Color of the water’s volumetric fog. Generally this value should match the color used in the bottom material.}}
{{MatParam|$fogstart|float|Distance in inches from the eye at which water fog starts.
: {{warning|Must be 0 for edge fading to work properly.}}}}
{{MatParam|$fogend|float|Distance in 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.|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.}}
{{MatParam|[[$envmap]]|env_cubemap / texture|See {{ent|$envmap}}. Provides reflections for cheap water.
: {{Note|Don't use this on underwater materials.}}}}
{{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]].|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.
: {{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={{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}}}}
; [[Image: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].|since={{l4d2}}}}
{{MatParam|$flow_normaluvscale|float|The number of world units covered by the normal map before it repeats. Typically in the 100s.|since={{l4d2}}}}
{{MatParam|$flow_worlduvscale|float|The number of times the flow map fits into the material. Face texture scale affects this.|since={{l4d2}}}}
{{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}}}}
{{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}}}}
{{MatParam|$flow_noise_texture|texture|A treatment texture used to break up repetition of the normal map.|since={{l4d2}}}}
{{MatParam|$flow_noise_scale|float|How many times to fit the noise texture into the normal map. Typically around 0.01.|since={{l4d2}}}}
{{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}}}}
==== 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}}}}
{{MatParam|$color_flow_uvscale|float|The number of world units covered by the base texture before it repeats. Typically in the 100s.|since={{as}}}}
{{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}}}}
{{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}}}}
{{MatParam|$color_flow_lerpexp|float|How sharp the transition should be between repeats, should be 1.
: {{todo|Better explanation}}|since={{as}}}}
{{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}}}}
==== 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/
: 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 ===

{{MatParam|%compilewater|bool|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]].}}
{{MatParam|%tooltexture|texture|Defines the texture Hammer will display in the material browser.}}
; <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:fr|True reflections under CSS]] (French)

[[Category:Water]]