[Port] [6000.0] [HDRP] Documentation for VFX Sample Water Surface node

Unity-Technologies · UnityAljosha · Mar 5, 2025 · Jan 28, 2025 · Jan 29, 2025 · Jan 29, 2025
commit 6779ef2c916426fa18981b884c20f0f708adbdd8
diff --git a/...ages/com.unity.render-pipelines.high-definition/Documentation~/Anti-Aliasing.md b/...ages/com.unity.render-pipelines.high-definition/Documentation~/Anti-Aliasing.md
@@ -90,7 +90,7 @@ When you use MSAA, be aware of the following:
   * [Subsurface scattering](skin-and-diffusive-surfaces-subsurface-scattering.md).
   * Low Resolution Transparency.
 * Ray tracing doesn't support MSAA. If you use ray tracing in your project, you are unable to use MSAA.
-* The Water System is not compatible with MSAA. If enable the water system in your project, you are unable to use MSAA.
+* The water system is not compatible with MSAA. If enable the water system in your project, you are unable to use MSAA.
 
 When you enable MSAA in your Unity Project, you must also enable it for your Cameras in their [Frame Settings](Frame-Settings.md). You can do this either globally or on individual Cameras. To enable MSAA globally, go to **Edit** > **Project Settings** > **HDRP Default Settings** > **Frame Settings**. To enable MSAA on a per-Camera basis, enable Forward Lit Shader Mode and then enable the MSAA within Forward checkbox. For information on where to find global and local Frame Settings, see the documentation on [Frame Settings](Frame-Settings.md).
 

diff --git a/...ity.render-pipelines.high-definition/Documentation~/Environement-Limitations.md b/...ity.render-pipelines.high-definition/Documentation~/Environement-Limitations.md
@@ -14,7 +14,7 @@ Additionally, atmosphere absorbs part of the sun light before it reaches the pla
 To have precise atmospheric attenuation and per pixel absorption of the sun light, you can disable the `PrecomputedAtmosphericAttenuation` option in the HDRP config package, which can be done using the [Render Pipeline Wizard](Render-Pipeline-Wizard.md). For more info, see [HDRP Config](configure-a-project-using-the-hdrp-config-package.md).
 
 
-### Water System
+### Water system
 
 Water is a refractive transparent object, however for performance reasons, it is necessary to render the depth of the water surface in the depth buffer.
 As a result, other transparent objects that are located behind the water surface will get culled during rendering by z-testing.

diff --git a/...ages/com.unity.render-pipelines.high-definition/Documentation~/HDRP-Features.md b/...ages/com.unity.render-pipelines.high-definition/Documentation~/HDRP-Features.md
@@ -427,7 +427,7 @@ In HDRP, you set up fog inside a [Volume](understand-volumes.md) which means you
 
 ![](Images/Water2023-1.png)
 
-Use HDRP's Water system to create and control realistic water surfaces. HDRP's water system includes the following features:
+Use HDRP's water system to create and control realistic water surfaces. HDRP's water system includes the following features:
 - Multiple presets.
 - Simulation-based caustics.
 - Underwater rendering.
@@ -438,7 +438,7 @@ Use HDRP's Water system to create and control realistic water surfaces. HDRP's w
 - A shader graph interaction for advanced visual customization.
 - Visualize transparent objects that intersect the water line.
 
-For more information, refer to [Water System](water.md).
+For more information, refer to [Water system](water.md).
 
 <a name="Camera"></a>
 

diff --git a/...m.unity.render-pipelines.high-definition/Documentation~/HDRP-Sample-Projects.md b/...m.unity.render-pipelines.high-definition/Documentation~/HDRP-Sample-Projects.md
@@ -70,9 +70,9 @@ https://github.com/Unity-Technologies/WaterScenes
 
 ![Water Scenes](Images/HDRPDemos-Water.png)
 
-This project demonstrates the following HDRP Water System features:
+This project demonstrates the following HDRP water system features:
 
-* Water System
+* Water system
 * Visual Effect Graph
 * Shader Graph
 * Custom Render Texture

diff --git a/...es/com.unity.render-pipelines.high-definition/Documentation~/TableOfContents.md b/...es/com.unity.render-pipelines.high-definition/Documentation~/TableOfContents.md
@@ -199,21 +199,25 @@
     * [Create a Fog Volume shader](create-a-fog-volume-shader.md)
     * [Troubleshoot fog](troubleshoot-fog.md)
   * [Water](water.md)
-    * [Use the Water System in your Project](water-use-the-water-system-in-your-project.md)
-    * [Capabilities of the Water System](water-capabilities-of-the-water-system.md)
+    * [Use the water system in your Project](water-use-the-water-system-in-your-project.md)
+    * [Capabilities of the water system](water-capabilities-of-the-water-system.md)
     * [Water system simulation](water-water-system-simulation.md)
     * [Quality and performance decisions](water-quality-and-performance-decisions.md)
     * [Water Override for Volumes](water-the-water-system-volume-override.md)
-    * [Decals and masking in the Water System](water-decals-and-masking-in-the-water-system.md)
-    * [Foam in the Water System](water-foam-in-the-water-system.md)
-    * [Caustics in the Water System](water-caustics-in-the-water-system.md)
-    * [Create a current in the Water System](water-create-a-current-in-the-water-system.md)
+    * [Decals and masking in the water system](water-decals-and-masking-in-the-water-system.md)
+    * [Foam in the water system](water-foam-in-the-water-system.md)
+    * [Caustics in the water system](water-caustics-in-the-water-system.md)
+    * [Create a current in the water system](water-create-a-current-in-the-water-system.md)
     * [Deform a water surface](water-deform-a-water-surface.md)
     * [Exclude part of a water surface](water-exclude-part-of-the-water-surface.md)
     * [Underwater view](water-underwater-view.md)
-    * [Materials in the Water System](water-materials-in-the-water-system.md)
-    * [Scripting in the Water System](water-scripting-in-the-water-system.md)
-    * [Debug in the Water System](water-debug-mode.md)
+    * [Materials in the water system](water-materials-in-the-water-system.md)
+    * [Scripting in the water system](water-scripting-in-the-water-system.md)
+      * [Float objects on a water surface](float-objects-on-a-water-surface.md)
+      * [Align objects to the water surface using normals](align-objects-to-water-surface-using-normals.md)
+      * [Add caustics](add-caustics-and-foam-and-check-waves-and-ripples.md)
+      * [Synchronize water surfaces](synchronize-water-surfaces.md)
+    * [Debug in the water system](water-debug-mode.md)
   * [Environment limitations](Environment-Limitations.md)
 * [Camera and scene composition](camera-and-scene-composition.md)
   * [Graphics Compositor](graphics-compositor.md)
@@ -431,7 +435,7 @@
     * [Fog reference](reference-fog.md)
       * [Fog Volume Override reference](fog-volume-override-reference.md)
       * [Local Volumetric Fog Volume reference](local-volumetric-fog-volume-reference.md)
-    * [Settings and properties related to the Water System](settings-and-properties-related-to-the-water-system.md)
+    * [Settings and properties related to the water system](settings-and-properties-related-to-the-water-system.md)
   * [Camera and scene composition reference](reference-camera-scene-composition.md)
     * [HDRP camera component reference](hdrp-camera-component-reference.md)
     * [HDRP Scene view camera settings reference](hdrp-scene-view-camera-settings-reference.md)

diff --git a/...-definition/Documentation~/add-caustics-and-foam-and-check-waves-and-ripples.md b/...-definition/Documentation~/add-caustics-and-foam-and-check-waves-and-ripples.md
@@ -0,0 +1,121 @@
+# Add caustics or foam and check waves and ripples
+
+To add caustics or foam, or get information about water surface displacement due to waves and ripples, get buffers from the [`WaterSurface`](xref:UnityEngine.Rendering.HighDefinition.WaterSurface) class:
+
+| Action                      | API                                                               |
+|-----------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| Add caustics            | [GetCausticsBuffer](../api/UnityEngine.Rendering.HighDefinition.WaterSurface.html#UnityEngine_Rendering_HighDefinition_WaterSurface_GetCausticsBuffer_System_Single__) |
+| Add foam                | [GetFoamBuffer](../api/UnityEngine.Rendering.HighDefinition.WaterSurface.html#UnityEngine_Rendering_HighDefinition_WaterSurface_GetFoamBuffer_UnityEngine_Vector2__)   |
+| Check waves and ripples | [GetDeformationBuffer](../api/UnityEngine.Rendering.HighDefinition.WaterSurface.html#UnityEngine_Rendering_HighDefinition_WaterSurface_GetDeformationBuffer)           |
+
+## Example: Add caustics
+
+```
+using UnityEngine;
+using UnityEngine.Rendering.HighDefinition;
+
+public class WaterCausticsExample : MonoBehaviour
+{
+    // Reference to the water surface component
+    public WaterSurface waterSurface;
+
+    // Size of the region on the water surface from which the caustics effect is calculated
+    public float regionSize = 1.0f;
+
+    // Material to apply the caustics effect
+    public Material waterMaterial;
+
+    void Start()
+    {
+        // Get the caustics buffer for the specified region size on the water surface
+        Texture causticsBuffer = waterSurface.GetCausticsBuffer(out regionSize);
+
+        if (causticsBuffer != null)
+        {
+            // Apply the caustics buffer as a texture to the water material
+            waterMaterial.SetTexture("_CausticsTex", causticsBuffer);
+            Debug.Log("Caustics buffer applied successfully.");
+        }
+        else
+        {
+            Debug.LogWarning("Caustics buffer could not be retrieved.");
+        }
+    }
+}
+```
+
+## Example: Add foam
+
+```
+using UnityEngine;
+using UnityEngine.Rendering.HighDefinition;
+
+public class WaterFoamExample : MonoBehaviour
+{
+    // Reference to the water surface component
+    public WaterSurface waterSurface;
+
+    // The area of the water surface where the foam buffer should be queried
+    public Vector2 foamArea;
+
+    // Material to apply the foam effect
+    public Material waterMaterial;
+
+    // Shader property name for foam texture in the water material
+    private readonly string _foamTextureProperty = "_FoamTex";
+
+    void Start()
+    {
+        // Get the foam buffer for the specified 2D area on the water surface
+        Texture foamBuffer = waterSurface.GetFoamBuffer(out foamArea);
+
+        if (foamBuffer != null)
+        {
+            // Apply the foam buffer as a texture to the water material
+            waterMaterial.SetTexture(_foamTextureProperty, foamBuffer);
+            Debug.Log("Foam buffer applied successfully.");
+        }
+        else
+        {
+            Debug.LogWarning("Foam buffer could not be retrieved.");
+        }
+    }
+}
+```
+
+## Example: Check waves and ripples
+
+```
+using UnityEngine;
+using UnityEngine.Rendering.HighDefinition;
+
+public class WaterDeformationExample : MonoBehaviour
+{
+    // Reference to the water surface component
+    public WaterSurface waterSurface;
+
+    // Material to apply the deformation (waves and ripples) effect
+    public Material waterMaterial;
+
+    // Shader property name for deformation texture in the water material
+    private readonly string _deformationTextureProperty = "_DeformationTex";
+
+    void Start()
+    {
+        // Get the deformation buffer for the entire water surface
+        Texture deformationBuffer = waterSurface.GetDeformationBuffer();
+
+        if (deformationBuffer != null)
+        {
+            // Apply the deformation buffer as a texture to the water material
+            waterMaterial.SetTexture(_deformationTextureProperty, deformationBuffer);
+            Debug.Log("Deformation buffer applied successfully.");
+        }
+        else
+        {
+            Debug.LogWarning("Deformation buffer could not be retrieved.");
+        }
+    }
+
+}
+```
diff --git a/....high-definition/Documentation~/align-objects-to-water-surface-using-normals.md b/....high-definition/Documentation~/align-objects-to-water-surface-using-normals.md
@@ -0,0 +1,42 @@
+# Align objects to the water surface using normals
+
+When accessing height, you can query the normal of the water surface at a given point as an additional output.
+
+1. Set the following variable in the search parameter `struct` sent to the system:
+
+	```
+	searchParameters.outputNormal = true;
+	```
+
+1. Use the result to align an object along the surface of the water, for example:
+
+	```
+	gameObject.transform.LookAt(searchResult.projectedPositionWS + searchResult.normalWS, Vector3.up);
+	```
+
+1. When using the [Burst version of the API](float-objects-on-a-water-surface.md#burstversion), allocate the array to store normals.
+
+	The following script contains only the relevant lines to add to the [script to float an array of objects](float-objects-on-a-water-surface.md#burstversion) to support querying normals.
+
+	```
+	public class FitToWaterSurface_Burst : MonoBehaviour
+	{
+	    NativeArray<float3> normalWSBuffer;
+
+	    void Start()
+	    {
+	        normalWSBuffer = new NativeArray<float3>(resolution * resolution, Allocator.Persistent);
+	    }
+
+	    void Update()
+	    {
+	        searchJob.outputNormal = true;
+	        searchJob.normalWSBuffer = normalWSBuffer;
+	    }
+
+	    private void OnDestroy()
+	    {
+	        normalWSBuffer.Dispose();
+	    }
+	}
+	```