Fix 5 Common WebGPU Shadow Bugs: 2025 Quick Guide

Bug #3: Jagged Edges (The Blocky Nightmare)

The Problem: The edges of your shadows are sharp, blocky, and aliased. They don't look soft and natural; they look like a staircase.

Why It Happens

A shadow map is a texture. Like any texture, it has a finite resolution. If you stretch a low-resolution shadow map over a large area, each texel of the map covers a significant portion of your scene, resulting in that characteristic blocky look. This is called aliasing.

The Fix in WebGPU

You have two primary tools to fight jagged edges:

1. Increase Shadow Map Resolution: The most straightforward approach. If your shadow map is 1024x1024, try bumping it to 2048x2048. This gives you more detail but comes at the cost of increased VRAM usage and slower shadow map rendering. It's a trade-off.

// In your shadow map texture creation
const shadowDepthTexture = device.createTexture({
  size: [2048, 2048], // Formerly [1024, 1024]
  usage: GPUTextureUsage.RENDER_ATTACHMENT | GPUTextureUsage.TEXTURE_BINDING,
  format: 'depth24plus',
});

2. Percentage-Closer Filtering (PCF): A much more effective technique. Instead of a single binary check (is it in shadow or not?), PCF samples the shadow map multiple times in a small grid around the target coordinate and averages the results. This turns the hard, blocky edge into a soft, smooth gradient.

Here's a simple 2x2 PCF implementation in WGSL:

// Assumes t_shadow is your texture_depth_2d and s_shadow is your sampler_comparison
// shadowPos is the fragment's position in light-space (vec3<f32>)
// shadowMapSize is a uniform for the texture size (e.g., 2048.0)

fn calculate_shadow_pcf(shadowPos: vec3<f32>, shadowMapSize: f32) -> f32 {
  let texelSize = 1.0 / shadowMapSize;
  var shadowFactor: f32 = 0.0;

  // 2x2 PCF Kernel
  for (var y: i32 = -1; y <= 0; y = y + 1) {
    for (var x: i32 = -1; x <= 0; x = x + 1) {
      let offset = vec2<f32>(f32(x) * texelSize, f32(y) * texelSize);
      shadowFactor += textureSampleCompare(
        t_shadow, 
        s_shadow, 
        shadowPos.xy + offset, 
        shadowPos.z
      );
    }
  }
  return shadowFactor / 4.0;
}

Bug #4: Mismatched Projections (The Warped Shadow)

The Problem: Shadows appear stretched, squashed, or severely distorted. They might move incorrectly as the light or camera moves, or be projected in the wrong direction entirely.

Why It Happens

This is a classic data integrity bug. The view-projection matrix you used to render the scene from the light's perspective (during the shadow pass) does not match the one you're using in the main fragment shader to test for shadows. Common culprits include:

• Passing the camera's matrix to the shadow shader by mistake.
• Calculating the light's orthographic or perspective projection incorrectly.
• Forgetting to update the light matrix uniform buffer when the light's position or direction changes.
• Matrix multiplication order errors. Remember, matrix math is not commutative!

The Fix in WebGPU

This requires careful debugging. There's no magic setting; you just have to ensure your data is correct.

1. Isolate Your Matrices: Have one clear source of truth for your light's view-projection matrix. Calculate it once per frame (if the light moves).
2. Use a Reliable Math Library: Don't write matrix math from scratch unless you're an expert. Use a well-tested library like gl-matrix to handle look-at, perspective, and orthographic projections.
3. Check Your Uniforms: Ensure the uniform buffer that holds the light matrix is correctly bound to both the shadow pass pipeline and the main rendering pipeline. Verify that it's being updated on the GPU every frame if needed.
4. Log and Verify: When in doubt, console.log() your matrix values before you write them to the GPU buffer. Do they look reasonable? Are they all NaNs? This can save you hours of headache.

Bug #5: The Disappearing Act (The Vanishing Shadow)

The Problem: Shadows on objects far from the camera are missing entirely. As you move closer, they suddenly pop into existence.

Why It Happens

The volume covered by the light's projection (its frustum) is not large enough to contain all the objects visible to the camera. Any object (or part of an object) outside the light's frustum will not be rendered into the shadow map and, therefore, cannot cast a shadow.

The Fix in WebGPU

You need to ensure the light's frustum covers what the camera can see.

The Simple Fix: Enlarge the Light's Frustum. For a directional light (using an orthographic projection), you can increase the width, height, and depth of the projection volume. The major downside is that you are now stretching the same resolution shadow map over a larger area, which can bring back the jagged edges from Bug #3. It's a constant balancing act.

The Advanced Fix: Cascaded Shadow Maps (CSM). This is the industry-standard technique for large outdoor scenes. The core idea is to split the camera's view frustum into several sections or "cascades" (e.g., near, middle, and far). You then render a separate, high-quality shadow map for each cascade.

• The near cascade covers a small area close to the camera with a very high-resolution shadow map.
• The far cascade covers a huge area in the distance with a lower-resolution shadow map.

In your main shader, you determine which cascade a fragment falls into and sample the appropriate shadow map. This gives you the best of both worlds: crisp, detailed shadows up close and stable, present shadows in the distance. Implementing CSM is a more involved topic, but it's the ultimate solution to this problem.

Bringing It All Together

Shadows are one of the most challenging, yet rewarding, aspects of real-time 3D graphics. While WebGPU gives you unprecedented control, it also asks you to manage the complexities that older APIs might have hidden. Don't be discouraged! These five bugs—Peter Panning, acne, aliasing, mismatched matrices, and disappearing shadows—represent the vast majority of issues you'll face.

By learning to identify them and systematically applying the right fixes, from tuning bias settings to implementing PCF and managing your frustums, you'll be well on your way to rendering beautiful, dynamic, and artifact-free scenes. Happy coding!