Crest Water 4 Documentation

Crest Water 4 is an advanced water system implemented in Unity. This specific repository targets the Unity built-in renderer. For users utilizing other render pipelines, specialized versions are available on the Unity Asset Store:

• Crest Water 4 BIRP (Built-in Render Pipeline)
• Crest Water 4 HDRP (High Definition Render Pipeline)
• Crest Water 4 URP (Universal Render Pipeline)

Note that Crest Water 5 is also available for newer requirements.

Crest uses an efficient Level of Detail (LOD) representation for ocean data (surface shape/displacements, foam values, shadowing data, water depth, etc.).

Key characteristics:

• Multi-resolution format: Data is stored in cascaded textures centered at the viewer.
• GPU-driven: Data is generated and sampled on the GPU using a command buffer constructed each frame by BuildCommandBuffer.
• Smooth Transitions: LOD data is interpolated using a blend factor to prevent visual pops or hard edges between different resolutions.
• Dynamic Scaling: LOD scales change based on the viewpoint. For example, elevated perspectives prioritize horizontal range, while low perspectives prioritize fine wave details.
• Scale Limits: The OceanRenderer script provides min and max scale settings to control the dynamic range of this scaling.

To install Crest Water 4 in an existing Unity project:

1. Download the latest stable release from the GitHub tags page.
2. Extract the downloaded files.
3. Copy the contents of crest/Assets/Crest into your Unity project's Assets folder.

Important Folders

• crest/Assets/Crest/Crest-Examples: Contains example content useful for first-time users (optional).
• crest/Assets/Crest/Development: Not required for core functionality; used only for Crest development.

Flow enables horizontal motion in the water.

Requirement: You must enable 'Create Flow Sim' on the OceanRenderer script to generate the necessary flow data.

To use surface clipping (carving holes in the ocean surface), you must configure both the renderer and the material:

1. On the OceanRenderer script, enable the Create Clip Surface Data option.
2. On the ocean material, locate the Clip Surface group and ensure the Enable option is ticked.

Note: This feature only affects the ocean surface and has no effect on the water volume. Holes are carved when the data values are greater than 0.5.

For developers building or extending wave simulation logic, the following resources provide theoretical foundations:

• General Wave Phenomena: Comprehensive texts on water waves and pressure profiles.
• Dispersive Waves: Notes on dispersive vs. non-dispersive waves and the 1D Dispersive Wave Equation.
• Shallow Water Equations (SWE): Detailed descriptions of SWE and their application to large-scale ocean simulation.
• Wind-Wave Interaction: Research on how energy transfers from wind to waves and the three stages of wind-generated wave spectra.
• Wave Equation Derivation: Mathematical justifications for the wave equation.

You can manually place foam in the world using geometry or textures. To do this, add geometry to the desired area and attach the RegisterFoamInput script. The material used must have a shader of type Crest/Inputs/Foam/....

Available input shaders:

• Add From Texture: Adds foam based on a user-provided texture (useful for 'blobs' or runtime painting).
• Add From Vert Colours: Uses the red channel of vertex colors to add foam.
• Override Foam: Sets foam to a specific value (useful for removing foam from unwanted areas).

When using an orthographic camera, Crest's LOD system (which relies on camera position) may require manual adjustment:

1. Override Viewpoint: Use the Viewpoint property on the OceanRenderer to set a custom position.
2. Uniform Detail: Increase the minimum scale via Ocean Renderer --> Detail Params --> Min Scale to spread detail more uniformly.
3. Camera Height: Ensure the camera height is equal to or higher than the camera's size value for correct rendering.
4. Underwater: Requires a positive near clip plane.

Assets that handle atmosphere (sky and weather) often require integration to ensure their fog effects are correctly applied to transparent objects like Crest water.

Important: When using these integrations, ensure you select the Crest render pipeline variant that matches your asset's supported pipeline.

Known integrated atmosphere assets include:

• Atmospheric Height Fog
• Azure[Sky]
• Buto
• Cozy 3
• Enviro 3
• Expanse
• Volumetric Fog & Mist 2

For efficient and effective shoreline wave modeling using a spline, use ShapeGerstner with the following settings:

• Reverse Wave Weight: Set to 0 to prevent waves from traveling in the opposite direction.
• Blend Mode: Set to Blend to overwrite existing global waves and prevent interference.