Fix WebGPU Shadow Bugs & Boost FPS: 3 Pro Tips for 2025

// WGSL example for the shadow pass vertex shader

struct VertexOutput {
  @builtin(position) position: vec4<f32>,
};

@vertex
fn vs_main(@location(0) in_pos: vec3<f32>, @location(1) in_normal: vec3<f32>) -> VertexOutput {
  // -- Standard depth bias values --
  let slope_scale_bias = 2.5;
  let constant_bias = 0.005; // A small base value

  // -- Normal Offset Calculation --
  // Get the angle of the surface relative to the light
  // For a directional light, light_direction is uniform
  let cos_theta = dot(normalize(in_normal), light_direction);
  
  // The more parallel the surface is to the light, the more offset we need.
  // tan(acos(cos_theta)) gives a much better offset than 1.0 - cos_theta
  let normal_offset = tan(acos(cos_theta)) * slope_scale_bias;

  var world_pos = model_matrix * vec4<f32>(in_pos, 1.0);

  // Apply the offset along the world-space normal
  world_pos.xyz += in_normal * normal_offset;

  var output: VertexOutput;
  // Project the biased position from the light's point of view
  output.position = light_view_proj_matrix * world_pos;

  // Apply a small constant bias to handle flat surfaces and precision issues
  output.position.z -= constant_bias;

  return output;
}

Hard, aliased shadow edges scream "computer graphics." The go-to solution for soft shadows is Percentage-Closer Filtering (PCF), where you take multiple samples from the shadow map around the pixel's location and average the results. A simple 3x3 PCF kernel (9 samples) is a huge improvement over a single tap, but it can also be expensive, especially as you increase the kernel size for softer shadows.

The Pro Solution: Variance Shadow Maps (VSM)

What if you could get beautiful, soft shadows with just a single texture lookup? That's the promise of Variance Shadow Maps (VSM). Instead of just storing the depth (z) in your shadow map, you store two values: the depth and the depth squared (z²). These are the first two "moments" of the depth distribution.

With these two values, you can use a powerful statistical formula called Chebyshev's inequality to estimate the probability that a pixel is in shadow. The magic of VSM is that you can pre-filter the shadow map with a hardware-accelerated blur (like a Gaussian blur). This means you blur the z and z² values *once*, and then your main shader only needs to perform a single, filtered lookup into this blurred map to get a smoothly interpolated result.

VSM vs. PCF: A Quick Comparison

Technique	Performance Cost	Quality & Artifacts
PCF (e.g., 5x5)	High (25 texture samples per pixel)	Accurate, but can show banding with too few samples.
VSM	Low (1 blurred texture sample per pixel)	Very smooth, but can suffer from "light bleeding" on overlapping objects.

The main drawback of VSM is light bleeding, where light can seem to 'leak' through objects that are close together. However, for many scenes, this is a minor issue that can be mitigated with careful bias or by combining it with other techniques. For a massive FPS boost, especially when targeting mid-range hardware, VSM is an incredible tool to have in your arsenal.

Tip 3: Dynamic Cascades for Open-World Scale & Performance

A single shadow map for a large scene is a recipe for disaster. If it covers the whole area, the resolution will be far too low for objects near the camera. If you make it high-resolution for nearby objects, you'll either have no shadows in the distance or need a texture so massive it will cripple your GPU.

The standard solution is Cascaded Shadow Maps (CSM). You split the camera's view frustum into several sections (cascades) and render a separate, high-quality shadow map for each one. This is a fantastic start, but we can do better.

The Pro Solution: Dynamically Fit Cascades to the Scene

The "pro" move is to not just use fixed cascade splits, but to calculate the tightest possible bounding box for each cascade's light-space view *every single frame*. Why? Because the geometry visible in each slice of your frustum changes constantly as the player moves and looks around. By fitting the shadow map projection tightly to only the visible geometry, you maximize every single pixel of your shadow map.

Furthermore, instead of linear splits, use a logarithmic or a hybrid split scheme. This allocates exponentially more shadow map resolution to the cascades closer to the camera, which is where players will notice detail the most.

Here’s the process:

1. Split the Frustum: Divide your camera frustum into 3 or 4 cascades using a logarithmic scheme.
2. Find Visible Geometry: For each cascade, determine the objects that fall within it.
3. Calculate Bounding Sphere: Compute a tight bounding sphere that encloses all visible objects within that cascade.
4. Create Light View/Projection: Create an orthographic projection for the light that tightly frames this bounding sphere. This becomes the `light_view_proj_matrix` for that cascade.
5. Render and Sample: Render the shadow map for each cascade. In the main pass, determine which cascade a pixel belongs to and sample from the correct map.

This dynamic approach ensures you're never wasting resolution. You get crisp, detailed shadows up close and stable, efficient shadows in the distance, providing a massive performance and quality uplift for any scene larger than a single room.

Bringing It All Together

Shadows are a deep and complex topic, but you don't have to settle for buggy, slow results in WebGPU. By moving beyond the textbook implementations, you can achieve a level of quality and performance that was previously unthinkable on the web.

To recap, your new pro toolkit for 2025 includes:

• Normal Offset Bias: For clean, artifact-free shadow lines on any surface.
• Variance Shadow Maps: For blazing-fast, beautifully soft shadows with a single texture fetch.
• Dynamic Cascaded Shadow Maps: For scaling your shadow quality to massive, open-world scenes without killing your frame rate.

Implementing these techniques requires a solid understanding of the rendering pipeline, but the payoff is a dynamic, immersive experience that will make your users forget they're even in a browser. Happy coding!