threejs-photoreal

The settings Blender users turn on when they want a render to look real, for three.js r186 WebGPU, as one parametric pipeline: AgX colour management, ground-truth AO or screen-space GI, roughness-aware SSR, contact shadows, temporal anti-aliasing, physically thresholded bloom, cascaded sun shadows sized to the sun's disc, physical light units, quality presets and adaptive quality. Motion blur, depth of field, god rays, lens flare and chromatic aberration are there too, off by default. Optional React Three Fiber component.

import * as THREE from 'three/webgpu'
import { PhotorealPipeline, configureSunShadows, createEnvironment, configureTextures } from 'threejs-photoreal'

const renderer = new THREE.WebGPURenderer({ antialias: false }) // MSAA belongs to the pipeline's scene pass
await renderer.init()
const sunShadows = configureSunShadows(sun, camera, { maxDistance: 1000 }, renderer)
createEnvironment(renderer, scene, skyScene) // PMREM image-based lighting from a sky (or an HDR)
configureTextures(scene, renderer)            // sRGB for colour, linear for data, mipmaps, max anisotropy

const pipeline = new PhotorealPipeline(renderer, scene, camera, { quality: 'high' })
renderer.setAnimationLoop(() => {
  sunShadows.update()
  pipeline.render() // instead of renderer.render(scene, camera)
})
pipeline.set({ ssr: { enabled: false }, color: { exposure: 1.2 } }) // live; JSON in, JSON out

React Three Fiber:

import { PhotorealPipeline } from 'threejs-photoreal/react'

<Canvas gl={async (props) => { const r = new WebGPURenderer({ ...(props as any), antialias: false }); await r.init(); return r }}>
  <PhotorealPipeline quality="high" bloom={{ strength: 0.08 }} />
</Canvas>

Blender → threejs-photoreal

Costs are GPU time at 1280×720 on an Apple M-series GPU in the test scene (see the demo's HUD with ?timing); they scale with pixels, not scene size, except the pre-pass, which re-draws the scene's geometry.

| Blender setting | Option | Default | Cost | Notes | |---|---|---|---|---| | Color Management → View Transform: AgX | color.toneMapping: 'agx' \| 'neutral' \| 'aces' \| 'none' | agx | free | Blender 4's default. neutral is Khronos PBR Neutral (keeps product colours). | | Color Management → Exposure | color.exposure | 1 | free | Linear. For physical units use exposureFromEV100() (below). | | (auto exposure) | pipeline.autoExposure = (ms) => exposure | none | free | A hook; meter with ev100FromIlluminance() or ev100FromLuminance(). | | Color Management → Display: sRGB | always | sRGB | free | | | Film → dither / grain | color.dither, color.grain | on, 0 | ~0 | ±1 LSB triangular dither after tone mapping stops sky banding. | | Eevee: Ambient Occlusion | ao.method: 'gtao', ao.radius, ao.intensity, ao.samples | gtao, 0.5 m | pre-pass + ~0.5 ms | Applied inside the lighting via builtinAOContext: occludes ambient/sky light only, never direct sun. | | Eevee: Raytracing / screen-trace GI | ao.method: 'ssgi', ao.giIntensity, ao.slices, ao.steps | ultra only | ~2–4 ms | AO plus one diffuse bounce (colour bleeding). | | Eevee: Screen Space Reflections | ssr.enabled, ssr.quality, ssr.maxDistance, ssr.thickness, ssr.resolutionScale (Half Res Trace) | on, half res | ~1–2 ms | Stochastic GGX rays with TRAA: roughness-aware, dielectric Fresnel (water, wet ground, glass). Without TRAA, mirror rays on metals only. | | Light → Contact Shadows | contactShadows.enabled, .maxDistance, .thickness, .intensity | on, 0.3 m | ~0.3 ms | Screen-space shadows from the sun, applied to the sun's light only (builtinShadowContext). | | Render samples / Film filter | antialias.method: 'traa' \| 'smaa' \| 'fxaa' \| 'msaa' \| 'none' | traa | ~0.3 ms | Temporal: foliage, particles and specular stop crawling. TRAA needs single-sample buffers, so MSAA is off with it. | | (MSAA) | antialias.msaaSamples | 4 | memory | For every method except traa. | | Eevee: Bloom / Compositor Glare | bloom.threshold, bloom.knee, bloom.strength, bloom.radius | 1, 1, 0.05, 0.6 | ~0.4 ms | Threshold is in exposed units (1 = display white), so only genuinely bright HDR values (sun, glints, bulbs) glow. | | Motion Blur → Shutter | motionBlur.enabled, motionBlur.shutter, motionBlur.samples | off, 0.5 | ~0.5 ms | Per-object velocity from the MRT. | | Camera → Depth of Field (Focus Distance, F-Stop) | depthOfField.focusDistance, .fStop, .bokehScale | off | ~1–2 ms | Blur ramp from the thin-lens CoC using the camera's real focal length. | | Volumetrics (sun shafts) | godRays.enabled, .density, .intensity | off (ultra: on) | ~1–2 ms | Ray-marches the sun's shadow map (the outermost CSM cascade). Needs a shadow-casting sun. | | Compositor Glare → Ghosts | lensFlare.enabled, .threshold, .strength | off | ~0.5 ms | Built from the bloom chain. | | Compositor Lens Distortion → Dispersion | chromaticAberration.enabled, .strength | off | ~0.1 ms | | | Output → Resolution % | resolutionScale | 1 | saves | TRAA reconstructs below 1. | | Light → Shadow → Cascade count / Max distance / Distribution / Fade | configureSunShadows(light, camera, { cascades, maxDistance, splitLambda, fade }) | 4, 1000 m, 0.85, on | per cascade: a shadow draw | CSMShadowNode. | | Sun → Angle (soft shadows) | angularDiameter, occluderDistance | 0.53°, 2 m | free | Per-cascade PCF radius = sun penumbra / texel size; normal bias = a texel plus half the filter (no acne, no peter-panning). | | World (HDRI / sky) | createEnvironment(renderer, scene, source, { intensity }) | | once | PMREM from a Scene, equirect HDR or cube map. pipeline.setEnvironmentMap(hdr) also gives SSR importance-sampled HDR misses. | | Sun Strength (W/m²) | sun.intensity = sunIlluminance(elevation) * exposureFromEV100(ev) | | | Lux. ~100 klx at noon, colour from air mass. | | Image Texture → Color Space | configureTexture(tex, renderer, 'color' \| 'data'), configureTextures(root, renderer) | | | sRGB for colour, NoColorSpace for data, mipmaps, max anisotropy. |

Physical units and pre-exposure. The sun is ~100 000 lux and its disc ~1.5×10⁹ cd/m², which overflow the half-float buffers every post effect reads. Multiply light values by the exposure before they reach the GPU (Filament's pre-exposure) and keep color.exposure at 1 for artistic stops:

const ev = ev100FromIlluminance(sunLux * Math.sin(elevation) + skyLux) // what an incident-light meter reads (~15 in full sun)
const k = exposureFromEV100(ev)
sun.intensity = sunIlluminance(elevation) * k        // lux
bulb.material.emissiveIntensity = 2e6 * k             // cd/m² (a bare bulb)
pointLight.intensity = 80 * k                         // candela

Quality presets

quality is the starting point; anything you set explicitly wins over it.

| Preset | AO | SSR | Contact shadows | AA | God rays | Pre-pass | |---|---|---|---|---|---|---| | low | off | off | off | FXAA | off | no | | medium | GTAO, 8 samples, half res | off | on (quality 0.3) | TRAA | off | yes | | high (default) | GTAO, 16 samples, full res | on, half res | on | TRAA | off | yes | | ultra | SSGI (AO + bounce) | on, full res, quality 0.8 | on (quality 0.8) | TRAA | on | yes |

Adaptive quality (adaptive: { enabled: true, targetMs: 16.7 }) walks a ladder of cheaper settings to hold the frame time: halve SSR and AO resolution, then drop god rays, SSR, SSGI → GTAO, contact shadows, motion blur and DOF, AO, and finally render at 75% and 50% resolution. It drops a step after 30 slow frames, probes back up after 300 fast ones, and doubles the wait whenever a probe fails. Resolution steps are uniforms; dropping a pass rebuilds the graph once. adaptiveLadder() and AdaptiveQuality are pure, if you'd rather drive your own.

Everything that's off is left out of the render graph (no render targets, no shader work). Only turning a pass on or off rebuilds the graph; every other setting is a uniform.

Limits

• Screen-space effects only see what's on screen: SSR and SSGI miss off-screen objects; SSR adds to (rather than replaces) the environment reflection, so keep ssr.intensity ≤ 1 on dielectrics.
• God rays need the sun to cast shadows; their composite assumes a standard (not reversed or logarithmic) depth buffer.
• The pre-pass (for GTAO and contact shadows) draws opaque geometry twice; in very geometry-heavy scenes medium's half-res GTAO or ao.method: 'off' is the bigger saving than any post effect.
• The renderer should be created with antialias: false; MSAA, when wanted, belongs to the pipeline's scene pass.

License

Apache-2.0