⏱ 1 min read

Shader NaN guards

Defended against NaN propagation from zero vectors / zero values in normalize / rcp / atan2 with a consistent pattern — blocking the mobile black-screen issue

Problem

On mobile GPUs, when math functions like normalize(), rcp(), and atan2() receive a zero vector or zero value, NaN is produced; once a NaN appears, it propagates across the frame and causes black screens and rendering corruption. Risky cases: 1. Camera entering an object's interior → viewDir converges to zero 2. Interpolation produces a zero-vector normal 3. Edge cases in billboard math where forward / right vectors become parallel 4. Center pixel (ru ≈ 0) handling in post-processing distortion functions Existing shaders had either no boundary-condition guards or inconsistent ones.

Approach

셰이더 레벨 일관 NaN 가드

Chosen

Pros

Safe regardless of inputs; one fix applies broadly

Cons

Some functions add a branch / extra ops

머티리얼·런타임 입력값 검증 강화

Pros

No shader changes

Cons

Many input paths make full defense hard — not a root-cause fix

Why 셰이더 레벨 일관 NaN 가드: Shader inputs come from many paths — materials, VFX, runtime — and external validation alone cannot defend against all of them. The fundamental fix is making the shader itself behave safely under zero inputs.

Implementation

01
Step 1 — Define a consistent guard pattern
- Precision-aligned: 1e-6h (half) / 1e-6 (float)
- Context-specific fallbacks: direction (0,0,1), angle 0.5, etc.
- Intent annotated with // NaN guard comments

Architecture

[Before] Inlined NaN guards per shader (~40 duplicated lines) [After] Common.hlsl ├─ SafeNormalize(half3 v, half3 fallback) ← inline compiled └─ SafeNormalize(float3 v, float3 fallback) │ └─ Called as a single line from 8 shaders Future threshold / fallback policy changes can happen in one place.

SafeNormalize definition:

inline half3 SafeNormalize(half3 v, half3 fallback) { half lenSq = dot(v, v); return lenSq > 1e-6h ? v * rsqrt(lenSq) : fallback; }

Tradeoffs & Future Work

Tradeoffs

Vertex-shader guards are negligible due to low vertex counts. Fragment shaders are unified on the rcp(max(...)) ALU pattern to avoid actual branching.
An early implementation that wrapped the whole function in `if (ru > 1e-6)` caused both fragment-level branching and a regression on the center pixel — flagged as Critical for priority fix.
The 1e-6 threshold is based on typical mobile environments. Tuning may be needed if extremely small-scale objects are added.