HDR Sky Dome¶

RayON supports two sky models: a built-in procedural gradient (zero setup required) and a full HDR environment map loaded from an .hdr file and projected as an equirectangular sky dome.

Built-in gradient sky¶

When no YAML sky key is specified, the renderer uses a simple linear gradient between a horizon colour and a zenith colour:

settings:
  background_color: [0.05, 0.05, 0.08]  # overrides gradient with a solid colour

Omit background_color entirely to get the default blue-to-white gradient. This sky model requires no image files and renders at zero memory cost.

HDR environment sky dome¶

An equirectangular .hdr file (Radiance RGBE format) is mapped onto an infinite sphere around the scene. Any ray that misses all geometry samples the sky dome at the corresponding direction.

settings:
  hdr_sky: "../resources/hdri/venice_sunset_8k.hdr"

The mapping is derived from the ray's unit direction vector:

The resulting $ (u, v) \in [0,1]^2 $ coordinates index into the equirectangular texture, with \(v = 0\) at the north pole and \(v = 1\) at the south pole.

Switching sky in interactive mode¶

In interactive mode the sky can be cycled at runtime without restarting:

A Sky combo-box in the Environment section of the ImGui panel also lets you pick any loaded .hdr file by name.

Downloading the HDRI files¶

The bundled HDRIs are sourced from Poly Haven under the CC0 licence. Because each file is 25–250 MB, they are not included in the repository. A download script is provided:

# Download 8K HDRIs (recommended quality)
cd resources/hdri
bash download_hdri.sh 8k

# Or lower resolutions
bash download_hdri.sh 2k
bash download_hdri.sh 4k

The six bundled environments:

Gallery¶

Technical implementation¶

float16 GPU texture¶

The .hdr file is decoded from Radiance RGBE (four bytes per pixel) to 32-bit float triplets by stb_image, then each channel is converted to IEEE 754 float16 (half precision). The resulting four-channel half-float image is uploaded to a cudaTextureObject_t with format:

cudaChannelFormatDesc{16, 16, 16, 16, cudaChannelFormatKindFloat}

CUDA hardware automatically promotes the fp16 values to fp32 on tex2D<float4> fetch — no shader-side conversion is needed.

Memory impact:

Binary disk cache (.hdrcache)¶

Loading and decoding an 8K .hdr file (≈ 200 MB on disk) takes several seconds. On subsequent launches, the renderer writes a binary sidecar next to the .hdr file (e.g. venice_sunset_8k.hdr.hdrcache) and reads it on the next run.

A .hdrcache file is a compact binary blob with a 24-byte header followed by the raw fp16 pixel data — no decompression or format conversion needed. Typical time savings: 5–10× faster loads compared to re-decoding the RGBE source.

┌─────────────────────────────────┐
│  magic  │  version  │  w  │  h  │  (16 bytes)
│            source_size          │  (8 bytes, staleness check)
├─────────────────────────────────┤
│  width × height × 4 × uint16_t │  (raw fp16 pixels, RGBA order)
└─────────────────────────────────┘

The source file's byte-size is stored in the header. If the .hdr file is replaced or modified (size changes), the cache is automatically invalidated and regenerated.

To skip the cache entirely (e.g. for diagnostics):

./rayon --no-hdr-cache --scene ../resources/scenes/default_scene.yaml

fp16 clamping¶

HDR scene radiance values can exceed the fp16 finite range (65 504). Values above this threshold are clamped to ±65504 before storage — ensuring the GPU texture never receives ±∞, which would propagate as NaN during path-tracing arithmetic and produce black "firefly" pixels.