feat(water): add flowmap parallax

[davo0411]

Uses alpha channel of riverflow.dds for a parallax effect. Works similar to regular water parallax except significant differences in world scaling.

1. with
2. without
   
   

Summary by CodeRabbit

• New Features
  • Water surfaces now include flowmap-driven parallax for improved apparent depth and motion.
  • Height sampling added to drive finer surface detail and more accurate normal blending.
  • Parallax-aware sampling improves consistency of water normals and visual quality across detail mip levels.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

Walkthrough

Adds flowmap-driven parallax and height sampling utilities to water shaders and updates a vertex output field to carry 2D flowmap UVs for parallax-aware sampling.

Changes

Cohort / File(s)	Summary
Parallax utility functions features/Water Effects/Shaders/WaterEffects/WaterParallax.hlsli	Adds flowmap-gated functions: GetFlowmapHeight, GetFlowmapBlendedHeight, GetFlowmapParallaxAmount, GetFlowmapParallaxHeight, GetFlowmapParallaxUVOffset, and GetFlowmapParallaxOffset for computing flowmap-driven heights and UV offsets (ray-marching and blended sampling logic).
Flowmap height integration & struct change package/Shaders/Water.hlsl	Introduces GetFlowmapHeightBlended, GetFlowmapHeightBarycentric, GetFlowmapMipLevel; reworks flowmap height sampling to mirror normal sampling and apply parallax-aware UVs; changes VS_OUTPUT::TexCoord4 from float to float2; switches a flowmap data sample to SampleLevel(..., 0).

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

• Verify all call sites handle VS_OUTPUT::TexCoord4 now being float2.
• Review mip-level calculation and SampleLevel usage for correctness across LODs.
• Inspect ray-marching/stepping (GetFlowmapParallaxAmount) for edge cases, blending stability, and performance.
• Confirm conditional compilation with FLOWMAP preserves prior behavior when unset.

Suggested reviewers

• doodlum

Poem

🐰 I nibble at UVs beneath moonlit tide,
Flowmaps guide my hops where ripples hide,
Ray-marches trace the shimmer and the gleam,
Offsets stitch the water into dream,
A rabbit cheers — parallax springs to life! 💧

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'feat(water): add flowmap parallax' directly and clearly summarizes the main change: adding a flowmap parallax feature to the water shader system.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[github-actions]

Using provided base ref: 5dce430
Using base ref: 5dce430
Base commit date: 2025-12-10T21:06:31Z (Wednesday, December 10, 2025 09:06 PM)
No actionable suggestions for changed features.

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (2)

features/Water Effects/Shaders/WaterEffects/WaterParallax.hlsli (1)

206-209: Unused parameter flowmapDimensions.

The flowmapDimensions parameter is not used in this function or passed to GetFlowmapParallaxUVOffset. If not needed, consider removing it to avoid confusion. If planned for future use, add a comment indicating so.

package/Shaders/Water.hlsl (1)

535-540: Dead code with misleading comment.

The comment states "This is now unused" but the function still exists. Either remove it entirely or update the implementation if it serves a compatibility purpose. Currently it just performs a simple texture sample which doesn't match what GetFlowmapHeightBlended does.

If this function is truly unused, remove it:

-// Keep this for compatibility - just forwards to the proper function
-float GetFlowmapHeightBarycentric(PS_INPUT input, float2 flowmapDimensions, float2 baseUV, float mipLevel)
-{
-	// This is now unused - we use GetFlowmapHeightBlended directly
-	return FlowMapNormalsTex.SampleLevel(FlowMapNormalsSampler, baseUV, mipLevel).w;
-}

If kept for compatibility, update the comment to explain when/why it's still needed.

📜 Review details

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 5dce430 and 3635854.

📒 Files selected for processing (2)

• features/Water Effects/Shaders/WaterEffects/WaterParallax.hlsli (1 hunks)
• package/Shaders/Water.hlsl (4 hunks)

🧰 Additional context used

📓 Path-based instructions (3)

**/*.{cpp,cxx,cc,c,h,hpp,hxx,hlsl,hlsli,fx,fxh,py}

📄 CodeRabbit inference engine (.github/copilot-instructions.md)

Do not include TODO/FIXME placeholders; provide complete, working solutions

Files:

• features/Water Effects/Shaders/WaterEffects/WaterParallax.hlsli
• package/Shaders/Water.hlsl

features/*/Shaders/**/*.{hlsl,hlsli,fx,fxh}

📄 CodeRabbit inference engine (.github/copilot-instructions.md)

features/*/Shaders/**/*.{hlsl,hlsli,fx,fxh}: Place all feature shaders under features/YourFeature/Shaders/
Avoid GPU register/buffer conflicts in HLSL; verify register usage (e.g., with hlslkit buffer scanning)

Files:

• features/Water Effects/Shaders/WaterEffects/WaterParallax.hlsli

**/*

⚙️ CodeRabbit configuration file

**/*: When reviewing PRs, please provide suggestions for:

1. Conventional Commit Titles (if not following https://www.conventionalcommits.org/ or
   if the existing title does not describe the code changes):
   Format: type(scope): description
   Length: 50 characters limit for title, 72 for body
   Style: lowercase description, no ending period
   Examples:

   • feat(vr): add cross-eye sampling
   • fix(water): resolve flowmap bug
   • docs: update shader documentation

2. Issue References (if PR fixes bugs or implements features):
   Suggest adding appropriate GitHub keywords:

   • "Fixes #123" or "Closes #123" for bug fixes
   • "Implements #123" or "Addresses #123" for features
   • "Related to #123" for partial implementations

Otherwise, use your standard review approach focusing on code quality.

Files:

• features/Water Effects/Shaders/WaterEffects/WaterParallax.hlsli
• package/Shaders/Water.hlsl

🧠 Learnings (2)

📓 Common learnings

Learnt from: alandtse
Repo: doodlum/skyrim-community-shaders PR: 0
File: :0-0
Timestamp: 2025-06-24T07:17:36.604Z
Learning: When reviewing PRs, always clarify the scope if there are multiple related features or dependencies. WeatherPicker was a separate PR that was already merged, while this PR focuses specifically on WetnessEffects climate preset system enhancements.

Learnt from: jiayev
Repo: doodlum/skyrim-community-shaders PR: 0
File: :0-0
Timestamp: 2025-08-03T18:37:19.690Z
Learning: ISReflectionsRayTracing.hlsl and ISWorldMap.hlsl in the skyrim-community-shaders repository are image-space post-processing shaders that perform color sampling and blending operations that need proper linear color space handling for the linear lighting system. ISReflectionsRayTracing handles screen-space reflections and should use conditional Color::IrradianceToLinear/Gamma conversions similar to ISCompositeLensFlareVolumetricLighting.hlsl. ISWorldMap performs 7x7 color accumulation that should be done in linear space similar to the pattern used in ISSAOComposite.hlsl.

📚 Learning: 2025-08-03T18:37:19.690Z

Learnt from: jiayev
Repo: doodlum/skyrim-community-shaders PR: 0
File: :0-0
Timestamp: 2025-08-03T18:37:19.690Z
Learning: ISReflectionsRayTracing.hlsl and ISWorldMap.hlsl in the skyrim-community-shaders repository are image-space post-processing shaders that perform color sampling and blending operations that need proper linear color space handling for the linear lighting system. ISReflectionsRayTracing handles screen-space reflections and should use conditional Color::IrradianceToLinear/Gamma conversions similar to ISCompositeLensFlareVolumetricLighting.hlsl. ISWorldMap performs 7x7 color accumulation that should be done in linear space similar to the pattern used in ISSAOComposite.hlsl.

Applied to files:

• features/Water Effects/Shaders/WaterEffects/WaterParallax.hlsli
• package/Shaders/Water.hlsl

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (3)

• GitHub Check: Build plugin and addons
• GitHub Check: Validate shader compilation (Flatrim, .github/configs/shader-validation.yaml)
• GitHub Check: Validate shader compilation (VR, .github/configs/shader-validation-vr.yaml)

🔇 Additional comments (7)

features/Water Effects/Shaders/WaterEffects/WaterParallax.hlsli (2)

91-110: LGTM - Flowmap height sampling functions.

The height sampling logic correctly mirrors the normal sampling pattern used in GetFlowmapNormal, ensuring height transitions match normal transitions. The blending formula is consistent.

---

112-152: Well-structured parallax computation with proper safeguards.

Good implementation choices:

• Early exit at line 116-117 for grazing angles prevents artifacts
• Bounded for-loop at line 134 prevents infinite iteration
• Zero-denominator check at line 151 prevents division by zero

package/Shaders/Water.hlsl (5)

91-91: TexCoord4 type widened from float to float2.

This enables future support for non-square flowmap dimensions (UNIFIED_WATER). Currently, line 257 in the VS assigns ObjectUV.x which broadcasts to both components, so existing behavior is preserved.

---

502-533: Height blending correctly mirrors normal blending logic.

The UV computation and blending formula match GetFlowmapNormal exactly, ensuring height and normal transitions stay synchronized. The inline comments clearly document each sample's parameters.

---

545-562: LGTM - Standard mip level computation.

Correctly mirrors the pattern used in WaterEffects::GetMipLevel with appropriate VR scaling adjustment.

---

657-676: Clean parallax integration approach.

Creating a copy of input as flowmapInput and modifying only the necessary texture coordinates for parallax sampling is a good pattern - it keeps the original input intact for other calculations while applying parallax-aware offsets where needed.

---

698-712: The preprocessor nesting for FLOWMAP/WATER_PARALLAX combinations is correctly structured and all four combinations are properly handled.

The code properly guards all four cases:

• FLOWMAP + WATER_PARALLAX: samples normals with flowmap-derived parallax offset (lines 699–703)
• FLOWMAP without WATER_PARALLAX: samples normals without parallax offset
• No FLOWMAP + WATER_PARALLAX: samples normals with regular parallax offset (line 709)
• No FLOWMAP without WATER_PARALLAX: samples normals with no offset (line 711)

All preprocessor directives are balanced and nested correctly.

[coderabbitai]

Actionable comments posted: 0

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

package/Shaders/Water.hlsl (1)

653-705: Guard against division by zero in flowmap parallax direction and align comments with actual behavior

The FLOWMAP+WATER_PARALLAX path contains three correctness and clarity issues:

1. Unguarded division by viewDirection.z (line 673):

float2 parallaxDir = viewDirection.xy / -viewDirection.z;

At near-horizon viewing angles, viewDirection.z approaches zero, producing unbounded magnitudes or INF/NaN before the later saturation. This contaminates flowmap UVs and normals. Apply a denominator guard:

float viewDotUp = -viewDirection.z;
float denom = max(abs(viewDotUp), 1e-3);
float2 parallaxDir = viewDirection.xy / denom;
parallaxDir.y = -parallaxDir.y;
parallaxDir *= 0.008 * saturate(viewDotUp * 2.0);

2. Misleading comment on line 678: The comment claims "Calculate cell blend weights using parallaxed input," but normalMul reads from flowmapInput.TexCoord2.zw, which is never modified by the parallax offset. Only TexCoord3.xy receives the parallax shift. Either adjust TexCoord2.zw for cell indices or clarify that only the flow vector is parallaxed.

3. Inconsistent parallax across normal layers (lines 723–724): When BLEND_NORMALS is active, normals2 and normals3 use parallaxOffset (from non-flowmap path), while normals1 in the FLOWMAP path uses flowmapParallaxOffset. This divergence may be intentional, but consider reusing flowmapParallaxOffset for all three layers to keep them visually coherent, or document why they differ.

🧹 Nitpick comments (2)

package/Shaders/Water.hlsl (2)

79-96: TexCoord4 widened to float2: confirm data source for UNIFIED_WATER

Changing TexCoord4 to nointerpolation float2 and reading it as:

#if defined(UNIFIED_WATER)
	float2 flowmapDimensions = input.TexCoord4.xy;
#else
	float2 flowmapDimensions = input.TexCoord4.xx;
#endif

matches the intent of carrying 2D flowmap dimensions. However, in this VS path you still write:

vsout.TexCoord4 = ObjectUV.x;

which will replicate ObjectUV.x into both .x and .y.

• For the non‑UNIFIED_WATER case (.xx) this preserves the old behavior.
• For UNIFIED_WATER, flowmapDimensions.y will currently just mirror .x unless some other VS variant writes a proper float2.

If UNIFIED_WATER water surfaces compiled with this shader are expected to use non‑square flowmap dimensions, you probably want to explicitly populate both components in the VS (e.g. vsout.TexCoord4 = float2(flowmapWidth, flowmapHeight);). Otherwise, consider using .xx in both branches to make the intent clearer and avoid subtle dependence on scalar replication.

Also applies to: 231-258, 657-663

---

1-10: Conventional commit title and issue reference suggestions

For this PR, a conventional commit‑style title that matches the changes could be:

• feat(water): add flowmap parallax

If this work corresponds to a tracked issue or feature request, consider adding one of the following to the PR description:

• Implements #<id> or Addresses #<id> if this fully/partially implements a feature.
• Related to #<id> if it’s part of a broader effort.

This will help with changelog generation and traceability.

📜 Review details

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 3635854 and 49b2f5a.

📒 Files selected for processing (1)

• package/Shaders/Water.hlsl (5 hunks)

🧰 Additional context used

📓 Path-based instructions (2)

**/*.{cpp,cxx,cc,c,h,hpp,hxx,hlsl,hlsli,fx,fxh,py}

📄 CodeRabbit inference engine (.github/copilot-instructions.md)

Do not include TODO/FIXME placeholders; provide complete, working solutions

Files:

• package/Shaders/Water.hlsl

**/*

⚙️ CodeRabbit configuration file

**/*: When reviewing PRs, please provide suggestions for:

1. Conventional Commit Titles (if not following https://www.conventionalcommits.org/ or
   if the existing title does not describe the code changes):
   Format: type(scope): description
   Length: 50 characters limit for title, 72 for body
   Style: lowercase description, no ending period
   Examples:

   • feat(vr): add cross-eye sampling
   • fix(water): resolve flowmap bug
   • docs: update shader documentation

2. Issue References (if PR fixes bugs or implements features):
   Suggest adding appropriate GitHub keywords:

   • "Fixes #123" or "Closes #123" for bug fixes
   • "Implements #123" or "Addresses #123" for features
   • "Related to #123" for partial implementations

Otherwise, use your standard review approach focusing on code quality.

Files:

• package/Shaders/Water.hlsl

🧠 Learnings (2)

📓 Common learnings

Learnt from: alandtse
Repo: doodlum/skyrim-community-shaders PR: 0
File: :0-0
Timestamp: 2025-06-24T07:17:36.604Z
Learning: When reviewing PRs, always clarify the scope if there are multiple related features or dependencies. WeatherPicker was a separate PR that was already merged, while this PR focuses specifically on WetnessEffects climate preset system enhancements.

📚 Learning: 2025-08-03T18:37:19.690Z

Learnt from: jiayev
Repo: doodlum/skyrim-community-shaders PR: 0
File: :0-0
Timestamp: 2025-08-03T18:37:19.690Z
Learning: ISReflectionsRayTracing.hlsl and ISWorldMap.hlsl in the skyrim-community-shaders repository are image-space post-processing shaders that perform color sampling and blending operations that need proper linear color space handling for the linear lighting system. ISReflectionsRayTracing handles screen-space reflections and should use conditional Color::IrradianceToLinear/Gamma conversions similar to ISCompositeLensFlareVolumetricLighting.hlsl. ISWorldMap performs 7x7 color accumulation that should be done in linear space similar to the pattern used in ISSAOComposite.hlsl.

Applied to files:

• package/Shaders/Water.hlsl

🔇 Additional comments (2)

package/Shaders/Water.hlsl (2)

453-460: Switch to SampleLevel(..., 0) for flowmap texture looks fine

GetFlowmapDataTextureSpace now forces LOD 0:

data.color = FlowMapTex.SampleLevel(FlowMapSampler, input.TexCoord2.zw + uvShift, 0);

Given this function’s role as a low‑level flow data provider (used before UV‑space transformations), pinning it to the highest‑detail mip for stable flow vectors is reasonable and should avoid derivative‑driven LOD variation when you later manipulate coordinates for parallax. No issues from a correctness standpoint.

---

489-563: Flowmap height helpers: Remove or clarify purpose of unused functions

The new height utilities and mip computation function are defined but not called anywhere in the codebase. Before merging:

1. GetFlowmapHeightBlended, GetFlowmapHeightBarycentric, and GetFlowmapMipLevel are unused: If these are intended for future use or external shaders, add comments explaining their purpose and expected caller. If not needed, remove them.

2. Constant duplication concern (secondary): GetFlowmapHeightBlended hardcodes the same four constant sets (9.92, 10.64, 8, 8.48 with offsets) that are used in GetFlowmapNormal calls. While GetFlowmapHeightBlended is itself unused, if it is enabled in the future, consider refactoring to avoid maintaining duplicate constant values.

3. log2(0) edge case in GetFlowmapMipLevel: log2(0) returns +INF in HLSL; the subsequent max(..., 0) does not clamp it as intended. Add epsilon clamping before the log call for safety:

float minTexCoordDelta = max(max(dTexCoords.x, dTexCoords.y), 1e-8);
return max(0.5 * log2(minTexCoordDelta), 0);

4. GetDimensions type note: The current code using float2 textureDims with GetDimensions(textureDims.x, textureDims.y) is valid—HLSL supports both uint and float output parameter overloads.

[github-actions]

✅ A pre-release build is available for this PR:
Download