View source for Water (shader)

[[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.

== 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 <code>[[$envmap]]</code> and does not refract. Users can disable expensive water rendering through their video options, so always place [[env_cubemap]]s.
; 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.
; 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.

== Shader parameters ==

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

; <code>$abovewater <[[bool]]></code>
: Whether this material is used for above or below the water’s surface.
; <code>$bottommaterial <material></code>
: 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.
; {{EP2 add|<code>$underwateroverlay <material></code>}}
: Applies a screen overlay when the camera is underwater. Generally used with <code>effects\water_warp01</code>. Requires <code>$abovewater</code> to be 0.
; <code>[[Du/dv_map|$bumpmap]] <texture></code>
; <code>[[normalmap|$normalmap]] <texture></code>
: 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.
: {{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.}}
; <code>$dudvframe <[[int]]></code>
; <code>$bumpframe <int></code>
: 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]].
; {{l4d2 add|<code>$flashlighttint <[[int]]></code>}}
: {{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.  Higher values usually cause the water to appear brighter. {{bug|Does not work properly in {{insurgency}}{{doi}}.}}


=== Fog ===

; <code>$fogcolor <[[RGB]] matrix></code>
: This is the 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>}}
: 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.
; <code>$fogenable <[[bool]]></code>
: Enable volumetric fog for the water.
; <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 ===

; {{p2 add|<code>$forceenvmap <[[bool]]></code>}}
: Forces the water to use $envmap for reflections.
; <code>$envmap <[[env_cubemap]] / [[texture]]></code>
: See <code>[[$envmap]]</code>. Provides reflections for cheap water.
; <code>$forcecheap <[[bool]]></code>
: 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.
; <code>$forceexpensive <[[bool]]></code>
: This forces the water to render itself as [[expensive]], regardless of the map's [[water_lod_control]] or the user's settings.
; {{p2 add|<code>$reflect2dskybox</code>}}
: Makes this water reflect the [[skybox]] material ''in addition'' to other reflections.
; {{CSGO add|<code>$reflect3dskybox</code>}}
: Added with Danger Zone update, used on ''dz_blacksite'' to reflect 3D sky, requires [[sky_camera]] else it might crash the game.
; {{l4d2 add|<code>$reflectskyboxonly</code>}}
: Makes this water reflect the [[skybox]] only.
; {{p2 add|<code>$reflectonlymarkedentities <[[bool]]></code>}}
: Whether or not to reflect only entities and static props with "Render in Fast Reflections" on.
; <code>$reflectamount <[[float]]></code>
: This is the amount of warp for the reflection. Higher values produce more visible reflections.
; <code>$reflectentities <[[bool]]></code>
: Make the water reflect entities. By default, no entities are reflected.
; <code>$reflecttexture <[[texture]]></code>
: Texture to use for reflection. For real-time reflections, use <code>[[_rt_WaterReflection]]</code>.
: {{tip|Specify <code>$refracttexture</code> without <code>$reflecttexture</code> to get real-time refraction on <code>[[$envmap]]</code> reflections.}}
; <code>$reflecttint <[[RGB]] matrix></code>
: This is the color tint for the real-time reflection and environment map.
; {{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?}}

=== Flowing water ===

; [[Image:Orange Box Scrolling Water.png|right|300px|Size/angle of $scroll1 and $scroll2]] {{EP2 add|<code>$scroll1 "[<[[normal]] X> <normal Y>]"</code>}}
; {{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.)



==== Flowmaps ====
{{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]
: [[File:L4d2 flowmap user.jpg|300px]] [[File:L4d2 flowmap tex.jpg|169px]] [[File:L4d2 flowmap dev.jpg|300px]]
: [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 [https://steamcdn-a.akamaihd.net/apps/valve/2010/siggraph2010_vlachos_waterflow.pdf Alex Vlachos' SIGGRAPH 2010 paper].
}}
{{MatVar|$flow_normaluvscale|float|The number of world units covered by the normal map before it repeats. Typically in the 100s.}}
{{MatVar|$flow_worlduvscale|float|The number of times the flow map fits into the material. Face texture scale affects this.}}
{{MatVar|$flow_uvscrolldistance|float|How far along the flow map the normal map should be distorted. Higher values lead to more distortion.}}
{{MatVar|$flow_timeintervalinseconds|float|Time needed for the normal map to cross the <code>$flow_uvscrolldistance</code>.}}
{{MatVar|$flow_timescale|float|Modifies flow speed without affecting the amount of distortion.}}
{{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 ====
; {{p2 add|<code>$basetexture <texture></code>}}
: Used to create the floating debris and sludge inside test chambers.

{{MatVar|$color_flow_uvscale|float|The number of world units covered by the basetexture before it repeats. Typically in the 100s.}}
{{MatVar|$color_flow_timeintervalinseconds|float|Time needed for the normal map to cross the <code>$color_flow_uvscrolldistance</code>.}}
{{MatVar|$color_flow_uvscrolldistance|float|How far along the flow map the normal map should be distorted. Higher values lead to more distortion.}}
{{MatVar|$color_flow_lerpexp|float|How sharp the transition between repeats, should be 1.}}
:{{todo|Better explanation}}
{{MatVar|$color_flow_displacebynormalstrength|float|How much the normalmap effects the basetexture. around 0.01}}

==== 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 flowmap, 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
: In Portal 2, Controls basetexture blend (water/sludge)


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

; <code>%compilewater <bool></code>
: This is needed to make a map using the material compile properly.
; <code>$surfaceprop water</code>
: 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>
: 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:Shaders]]
[[Category:List of Shader Parameters]]
[[Category:Water]]