3D Underwater God Rays

3D Underwater God Rays

Use this when the camera is under the water and the light comes down through it. Reach for a sibling instead in these cases:

• Sun shafts in air, cut by trees and rooflines: use 3d-sky-rays. Its screen-space radial blur of an occlusion mask is the right tool there. It cannot parallax or carry ripples, so under water keep it only as a low companion for fish shadows (Blue Hour runs it at 0.25).
• The ocean surface seen from above, with a horizon: use 3d-ultra-realistic-water.
• Authored shaft planes through one window in a lit interior: use 3d-wood-lighting-scorecard.

Source: extracted from Blue Hour, the living-ocean wallpaper of a Three.js iPhone Duo study. A school of 2,200 Blender sardines turns behind a glass device. The light had to read as sun through water across the whole 38 s camera dolly and on the device's own screen.

Verified stack: Three.js r170, WebGL2, GLSL ShaderMaterials, one HalfFloat render target, and a hand-written ACES pass. No post-processing library.

The mechanism

Sample one drifting swell field across the sun direction, and integrate it along every view ray. Each point in the water is lit by the swell value at its position measured perpendicular to the sun. The shafts are therefore parallel columns in the world. They converge on the sun the way rails converge on a vanishing point, and they slide past the fish when the camera moves. Paint the same shafts in screen space and they stay locked to the lens.

Reuse the working effect

Copy assets/underwater-light.mjs. You pass in your own THREE, and the module does not import a second copy. The demo runs this same module inside Blue Hour's renderer. demo/build.mjs rebuilds it from the Blue Hour sources.

import { createUnderwaterLight, LIGHT_GLSL, WATER_GLSL } from './underwater-light.mjs';

// One uniforms object shared by the water, fish and particle materials.
const uniforms = {
  uSunDirection: { value: new THREE.Vector3(.25, .40, -1).normalize() },   // toward the sun
  uTime: { value: 0 },
  uCameraPosition: { value: camera.position },
  uCameraWorld: { value: camera.matrixWorld },
  uInverseProjection: { value: camera.projectionMatrixInverse },
};
const light = createUnderwaterLight(THREE, { uniforms });   // before creating the materials below
light.setSize(innerWidth * dpr, innerHeight * dpr);          // drawing-buffer pixels, again on resize

// Water: a full-screen quad. Declare uSunDirection, uCameraPosition, uTime,
// uShafts and uShaftTexel, then add ${LIGHT_GLSL}${WATER_GLSL} and in main():
//   vec3 sunRay = ray;
//   color += surfaceUnderside(ray, sunRay);     // also bends sunRay through the ripples
//   ...draw your sun with sunRay...
//   color += underwaterShafts(vUv, ray);
// Fish: declare uSunDirection, then add ${LIGHT_GLSL} and multiply the sun key
// by underwaterDapple(worldPosition, uTime).

// Every frame, in this order:
uniforms.uTime.value = time;
camera.updateMatrixWorld();
light.render(renderer);          // the march, into its own half-resolution target
// then the water, the fish, and one tone map at the end

The numbers that shipped

Rules, each with the failure it prevents

These came from A/B renders of the Blue Hour frame: the same camera, the same frozen fish, one change at a time.

• Shape the swell into sparse peaks, not ridges. 1 − |swell| makes a web of thin sheets, and a ray that crosses many sheets averages them into flat haze. On a frozen frame the ridge web raised the mean brightness of the water by 20% and halved the contrast between pixel columns, from 0.247 to 0.118. The demo's Ridge web switch shows it.
• Start the march 4 units out. Starting at 1.5 units, a shaft passing over the camera filled a quarter of the frame with one bright wedge. Weight the samples by exp(−0.06t): the near ones smear least, so they hold the beam edges.
• Merge the shafts into the sun's glow as the ray points at it. Looking straight up one column, the integral is a single swell value. Where the camera sat between shafts, that left a dark hole on the sun. mix(total, 0.16, μ^28) closes it.
• Integrate the caustic web inside the march. Sampled 4 times at full resolution instead, the web reads as a pool floor painted over the water. Inside the 26-step march at half resolution, it becomes fine streaks that run along each beam. The demo's Painted on screen switch shows it.
• Turn down any uniform glow already in the frame. Blue Hour's corona and screen-space ray pass lit the top of the frame evenly. The first shafts barely showed in the composite at about the gain that later shipped. They read only after the corona was halved and the radial pass cut from 0.82 to 0.25, so the shafts carry the light and the gaps stay dark.
• Judge the gain on the composed page, not the raw canvas. Gain 2.2 looked right on the canvas. On the page, where the canvas sits at 82% opacity under a darkening CSS shade, the same frame showed almost nothing. 3.6 survives the page.
• Lift the sun above the top edge for full-frame beams. At 21° the sun sits in frame: the convergence point is a glow and the beams are short. Between 30° and 44° it clears the top edge, and the beams fan down the whole frame. The demo's Sun slider sweeps it.
• Declare each uniform once per shader. LIGHT_GLSL declares its own uniforms (uSurfaceY, uShaftScale, uShaftFloor, uCompare) and expects the host to declare uSunDirection before it. Declaring one twice is a compile error, and the material quietly draws nothing.