dymokomi/luce-render
Source of release 0.1.4
0.1.4 / src / render / integrator.lucb
#==============================================================================================
#
# render/integrator - The wavefront path tracer's host side
#
# DESCRIPTION:
# A Renderer owns a scene's buffers, the path state, the film and the output image,
# and records passes. A pass traces one sample for one band of pixels (at most
# `pool` paths): camera, then per bounce intersect_closest → shade_surface →
# shade_miss → intersect_shadow, then finish (paths
# into the film) and, after a sample's last band, film_convert (the film's average
# into the image and a display image). With
# light tracing, the first band's pass also starts the sample's light paths
# (light_emit, into the pool's slots after the band's), which run in the same
# rounds: shade_surface shades their hits after the camera paths', and
# intersect_shadow splats their camera connections on the film. Queue
# sizes never come back to the host: each kernel's last workgroup writes the
# next kernels' indirect arguments.
#
# `advance` is meant to be called once per UI frame: it starts the next pass
# only when the last one has finished, so the UI never waits and the GPU stays
# busy. Device work happens on the main thread.
#
# What a viewport shows is always one whole image of one view: a sample's last
# pass writes the display image into one of three, never the one shown nor one a
# pass in flight writes, and it is shown once that pass has finished. A restart
# or a reload begins a new generation; passes of an older one finish unseen.
# A UI draws after the passes it submitted, so a display image a pass in flight
# still writes is never the one it draws.
#
# Buffers, as shaders/common.glsl binds them: 0 nodes, 1 positions, 2 indices,
# 3 lights, 4 state (vec4 fields), 5 state (uint fields), 6 queues, 7 film,
# 8 the image (ACEScg), 9 constants, 10 the display image (exposed, Rec.709),
# 11 triangle shading attributes, 12 materials, 13 the texture sampler (set 1:
# the materials' texture table; the albedo tables and texture coordinates by
# address), 14 the TLAS
# (hardware ray queries; otherwise intersection walks the BVH in 0..2), 15 the
# light tree's links, emitters and triangle map (light_tree.lucb).
#
#==============================================================================================
## What to render and how.
pub struct RenderSettings:
pub var width: u32
pub var height: u32
pub var samples: u32
## The most surface interactions a path shades: 1 is direct light only.
pub var max_bounces: u32
pub var spectral: bool
## The camera's index among the scene objects; -1 takes the first camera.
pub var camera: i64
## Radiance from every direction no surface covers (linear ACEScg).
pub var background: Vector3
## The material every surface has (until materials are assigned).
pub var material: OpenPbr
## Paths in flight at once; 0 is min(2^21, pixels).
pub var pool: u32
pub var seed: u32
## Trace with the software BVH even where the device has ray queries.
pub var software_bvh: bool
## The most bounces of each kind a path may take (Cycles' limits).
pub var diffuse_bounces: u32
pub var glossy_bounces: u32
pub var transmission_bounces: u32
## Indirect samples are clipped to this brightness against fireflies; 0 is off.
pub var clamp_indirect: f64
## Adaptive sampling: a pixel stops once its noise falls below this (0: every
## pixel takes every sample), checked every 4 samples after `adaptive_minimum`.
pub var noise_threshold: f64
pub var adaptive_minimum: u32
## Time each kernel on the GPU (Renderer.kernel_times); a little slower.
pub var profile: bool
## Path guiding (shaders/guide.glsl): learn where light comes from and send
## paths there. Off by default: in v1 it costs about 25% a sample and cuts
## error about 1.2x in a room lit by bounced light, so it pays only where
## indirect light is concentrated (docs/DESIGN.md).
pub var guiding: bool
## Light tracing: light paths a sample, per pixel (0: none). They connect to
## the camera under MIS with camera paths, which makes caustics and light
## through glass converge (docs/research/FIREFLIES-STUDY.md). Perspective
## cameras only. 0.5 by default: in the Cornell box it costs about 1.5x a
## sample and cuts error about 9x, 6x better at equal time.
pub var light_tracing: f64
pub static func of(width: u32, height: u32, samples: u32) -> RenderSettings:
return RenderSettings(width, height, samples, 12, true, -1, Vector3(), OpenPbr.standard(), 0, 1, false, 1024, 1024, 1024, 0.0, 0.0, 16, false, false, 0.5)
let state_v_fields: usize = 14
let state_u_fields: usize = 11
## The guiding grid: 2^19 cells, each a key, 5 vec4s (4 lobes and their
## weights) and 4 lobes' statistics of 5 floats (shaders/guide.glsl).
let guide_cells: usize = 524288
let guide_bytes: usize = guide_cells * (4 + 5 * 16 + 4 * 5 * 4)
let queue_count: usize = 6
let queue_base: usize = 48
let constants_rows: usize = 32
## 2^21 paths (about 410 MB of state): a 1920 × 1080 image in one band, which
## halves the per-dispatch overhead of two (measured: 9.9 to 9.0 ms a sample).
let default_pool: usize = 2097152
## With splats a path costs far more (the bonsai capture's 1080p sample takes
## about 0.6 s on an M4 Max), so passes cover 2^19 paths, about 150 ms each,
## and the UI and other GPU users get their turns; 2^18 cost 25% more.
let splat_pool: usize = 524288
## Profiling buckets (Renderer.kernel_times).
let kind_camera: u8 = 0
let kind_closest: u8 = 1
let kind_surface: u8 = 2
let kind_miss: u8 = 3
let kind_shadow: u8 = 4
let kind_light: u8 = 5
let kind_finish: u8 = 6
let kind_convert: u8 = 7
let kind_adaptive: u8 = 8
let kind_rest: u8 = 9
pub let kernel_names: str[10] = ["camera", "intersect closest", "shade surface", "shade miss", "intersect shadow", "light emission", "finish", "film convert", "adaptive", "later rounds"]
## The integrator's kernels in one build (spectral or RGB).
struct Kernel:
var kernel: gpu.Kernel
var kinds: const u8[]
## `fast`: Metal may relax IEEE rules (8% a sample: shading 4.3 to 3.3 ms
## at 1080p on an M4 Max). Off where infinities and NaNs must behave: the
## BVH's slab tests (intersection) and the film's NaN guard (finish, convert,
## adaptive).
## `constants`: the scene's features (scene_features), which every
## integrator kernel declares.
## `table`: it samples the materials' texture table.
static func create(device: gpu.Device, constants: const gpu.Constant[], words: const u32[], msl: c.str, group: const u32[], kinds: const u8[], fast: bool = true, table: bool = false) -> Kernel!:
return Kernel(try gpu.Kernel.create(device, words, msl, group, kinds, fast_math = fast, table = table, constants = constants), kinds)
struct Kernels:
var camera: Kernel
var intersect_closest: Kernel
var shade_surface: Kernel
var shade_miss: Kernel
var intersect_shadow: Kernel
var finish: Kernel
var film_convert: Kernel
var adaptive: Kernel
var guide_fit: Kernel
var light_emit: Kernel
## What they were built for: the spectral or RGB build, hardware rays,
## and the scene's features; and whether a later load took them over
## (then this owner frees nothing).
var spectral: bool = false
var rays: bool = false
var features: gpu.Constant[10]
var taken: bool = false
## A successful load's borrowed kernels become its own, `older` (the
## load it replaces) giving them up.
func adopt(older: Kernels*):
if not self.taken: return
older.taken = true
self.taken = false
## Whether these serve a load of the same build and features (a light or
## a material's values changed): the load takes them instead of making
## and checking ten kernels again.
func serves(spectral: bool, rays: bool, features: const gpu.Constant[10]*) -> bool:
if self.taken or spectral != self.spectral or rays != self.rays: return false
for at in 0..<(usize)10:
let a = self.features[at]
let b = (*features)[at]
if a.id != b.id or a.kind != b.kind or a.bits != b.bits: return false
return true
## `reuse`'s kernels when they serve this build, else new ones.
static func take_or_create(device: gpu.Device, spectral: bool, rays: bool, features: const gpu.Constant[10], reuse: Kernels*?) -> Kernels!:
if let older = reuse:
if older.serves(spectral, rays, &features): return older.take()
return try Kernels.create(device, spectral, rays, features)
## The same kernels, borrowed (`taken`: freeing them frees nothing) until
## the load holding them succeeds and `adopt` makes them its own.
func take() -> Kernels:
var borrowed = self
borrowed.taken = true
return borrowed
## The build's kernels; intersection by hardware ray queries when `rays`.
static func create(device: gpu.Device, spectral: bool, rays: bool, constants: const gpu.Constant[]) -> Kernels!:
if spectral:
var camera = try Kernel.create(device, constants, camera_comp_words, camera_comp_msl, camera_comp_group, camera_comp_bindings)
errdefer camera.kernel.destroy()
var closest = try intersect_kernel(device, true, rays, constants)
errdefer closest.kernel.destroy()
var surface = try Kernel.create(device, constants, shade_surface_comp_words, shade_surface_comp_msl, shade_surface_comp_group, shade_surface_comp_bindings, table = shade_surface_comp_table)
errdefer surface.kernel.destroy()
var miss = try Kernel.create(device, constants, shade_miss_comp_words, shade_miss_comp_msl, shade_miss_comp_group, shade_miss_comp_bindings)
errdefer miss.kernel.destroy()
var shadow = try shadow_kernel(device, rays, constants)
errdefer shadow.kernel.destroy()
var finish = try Kernel.create(device, constants, finish_comp_words, finish_comp_msl, finish_comp_group, finish_comp_bindings, false)
errdefer finish.kernel.destroy()
var convert = try Kernel.create(device, constants, film_convert_comp_words, film_convert_comp_msl, film_convert_comp_group, film_convert_comp_bindings, false)
errdefer convert.kernel.destroy()
var adaptive = try Kernel.create(device, constants, adaptive_comp_words, adaptive_comp_msl, adaptive_comp_group, adaptive_comp_bindings, false)
errdefer adaptive.kernel.destroy()
var fit = try Kernel.create(device, constants, guide_fit_comp_words, guide_fit_comp_msl, guide_fit_comp_group, guide_fit_comp_bindings)
errdefer fit.kernel.destroy()
let emit = try Kernel.create(device, constants, light_emit_comp_words, light_emit_comp_msl, light_emit_comp_group, light_emit_comp_bindings)
return Kernels(camera, closest, surface, miss, shadow, finish, convert, adaptive, fit, emit, spectral, rays, keyed(constants))
var camera = try Kernel.create(device, constants, camera_rgb_comp_words, camera_rgb_comp_msl, camera_rgb_comp_group, camera_rgb_comp_bindings)
errdefer camera.kernel.destroy()
var closest = try intersect_kernel(device, false, rays, constants)
errdefer closest.kernel.destroy()
var surface = try Kernel.create(device, constants, shade_surface_rgb_comp_words, shade_surface_rgb_comp_msl, shade_surface_rgb_comp_group, shade_surface_rgb_comp_bindings, table = shade_surface_rgb_comp_table)
errdefer surface.kernel.destroy()
var miss = try Kernel.create(device, constants, shade_miss_rgb_comp_words, shade_miss_rgb_comp_msl, shade_miss_rgb_comp_group, shade_miss_rgb_comp_bindings)
errdefer miss.kernel.destroy()
var shadow = try shadow_kernel(device, rays, constants)
errdefer shadow.kernel.destroy()
var finish = try Kernel.create(device, constants, finish_rgb_comp_words, finish_rgb_comp_msl, finish_rgb_comp_group, finish_rgb_comp_bindings, false)
errdefer finish.kernel.destroy()
var convert = try Kernel.create(device, constants, film_convert_rgb_comp_words, film_convert_rgb_comp_msl, film_convert_rgb_comp_group, film_convert_rgb_comp_bindings, false)
errdefer convert.kernel.destroy()
var adaptive = try Kernel.create(device, constants, adaptive_rgb_comp_words, adaptive_rgb_comp_msl, adaptive_rgb_comp_group, adaptive_rgb_comp_bindings, false)
errdefer adaptive.kernel.destroy()
var fit = try Kernel.create(device, constants, guide_fit_comp_words, guide_fit_comp_msl, guide_fit_comp_group, guide_fit_comp_bindings)
errdefer fit.kernel.destroy()
let emit = try Kernel.create(device, constants, light_emit_rgb_comp_words, light_emit_rgb_comp_msl, light_emit_rgb_comp_group, light_emit_rgb_comp_bindings)
return Kernels(camera, closest, surface, miss, shadow, finish, convert, adaptive, fit, emit, spectral, rays, keyed(constants))
func destroy():
if self.taken: return
self.camera.kernel.destroy()
self.intersect_closest.kernel.destroy()
self.shade_surface.kernel.destroy()
self.shade_miss.kernel.destroy()
self.intersect_shadow.kernel.destroy()
self.finish.kernel.destroy()
self.film_convert.kernel.destroy()
self.adaptive.kernel.destroy()
self.guide_fit.kernel.destroy()
self.light_emit.kernel.destroy()
## The ten features as a kernel set keeps them.
func keyed(constants: const gpu.Constant[]) -> gpu.Constant[10]:
var key: gpu.Constant[10] = [gpu.Constant.uint32(0, 0), gpu.Constant.uint32(0, 0), gpu.Constant.uint32(0, 0), gpu.Constant.uint32(0, 0), gpu.Constant.uint32(0, 0),
gpu.Constant.uint32(0, 0), gpu.Constant.uint32(0, 0), gpu.Constant.uint32(0, 0), gpu.Constant.uint32(0, 0), gpu.Constant.uint32(0, 0)]
for at in 0..<(constants.length if constants.length < 10 else 10): key[at] = constants[at]
return key
## Intersection kernels serve both builds: they read no spectra.
## Closest hits, spectral or RGB (splats add their emission in the build's terms).
func intersect_kernel(device: gpu.Device, spectral: bool, rays: bool, constants: const gpu.Constant[]) -> Kernel!:
if spectral:
if rays: return try Kernel.create(device, constants, intersect_closest_rq_comp_words, intersect_closest_rq_comp_msl, intersect_closest_rq_comp_group, intersect_closest_rq_comp_bindings, false)
return try Kernel.create(device, constants, intersect_closest_comp_words, intersect_closest_comp_msl, intersect_closest_comp_group, intersect_closest_comp_bindings, false)
if rays: return try Kernel.create(device, constants, intersect_closest_rgb_rq_comp_words, intersect_closest_rgb_rq_comp_msl, intersect_closest_rgb_rq_comp_group, intersect_closest_rgb_rq_comp_bindings, false)
return try Kernel.create(device, constants, intersect_closest_rgb_comp_words, intersect_closest_rgb_comp_msl, intersect_closest_rgb_comp_group, intersect_closest_rgb_comp_bindings, false)
func shadow_kernel(device: gpu.Device, rays: bool, constants: const gpu.Constant[]) -> Kernel!:
if rays: return try Kernel.create(device, constants, intersect_shadow_rq_comp_words, intersect_shadow_rq_comp_msl, intersect_shadow_rq_comp_group, intersect_shadow_rq_comp_bindings, false)
return try Kernel.create(device, constants, intersect_shadow_comp_words, intersect_shadow_comp_msl, intersect_shadow_comp_group, intersect_shadow_comp_bindings, false)
pub struct Renderer:
var device: gpu.Device
var settings: RenderSettings
## The geometry (uploaded once per geometry), and what is loaded beside it
## (replaced by `reload`): loading.lucb.
var scene: GpuScene
var loaded: Loaded
## The geometry's triangles in BVH leaf order (CompiledScene.order), for
## reloads compiled without a BVH.
var order: Growing[u32]
## The albedo tables and the path-guiding grid (guide.glsl), reached by
## their addresses; neither depends on the scene.
var tables: gpu.Buffer
var guide: gpu.Buffer
var guide_address: u64
## The view: path state for `slots` paths (a band's camera paths, then
## light paths), queues, the film and the images, made for at most
## `capacity` pixels and images of `image_width` × `image_height`.
var state_v: gpu.Buffer
var state_u: gpu.Buffer
var queues: gpu.Buffer
var film: gpu.Buffer
var output: gpu.Texture
## The display images (rgba16f): `front` is the one shown, of `shown_width` ×
## `shown_height` pixels from its top-left corner.
var shown: gpu.Texture[3]
var front: usize
var capacity: usize
var image_width: u32
var image_height: u32
## Display settings changed since the display image was last made.
var display_stale: bool
## The view rendered now, and the paths a pass traces (a band of pixels).
var frame: RayFrame
var pool: usize
var slots: usize
## The film must be cleared before the next pass (a restart).
var clear_film: bool
## The passes in flight (older first), the samples each completes and the
## size of the image each leaves; what comes next: sample `sample`, band
## `band`. `completed` samples are in the image of `shown_width` ×
## `shown_height` pixels.
var older: gpu.Compute?
var newer: gpu.Compute?
var older_completes: u32
var newer_completes: u32
var older_size: u32[2]
var newer_size: u32[2]
## The display image each pass in flight writes (-1: none, not its sample's
## last band), and the generation it was recorded in: a restart or a reload
## begins the next, and only the current generation's images are shown.
var older_slot: i64
var newer_slot: i64
var older_generation: u64
var newer_generation: u64
var generation: u64
## The display image the pass being recorded writes (-1 none).
var writing: i64
var sample: u32
var band: usize
var completed: u32
var shown_width: u32
var shown_height: u32
## Profiling: the kind of each timestamp of the pass in flight (kind_*), and
## the nanoseconds each kind has taken in finished passes.
var marks: Growing[u8]
var kernel_ns: f64[10]
## Light tracing: the light paths a sample (0: none), and the samples whose
## light paths have been recorded.
var light_count_per_sample: usize
var light_samples: u32
## Light paths in the pass being recorded (common.glsl params.light_count).
var lights_in_pass: u32
## The image files the loaded scene reads, kept across reloads.
var images: ImageStore = ImageStore()
## The scene's triangles in the BVH's order and its materials, as the
## last load had them (`keep_geometry`): a reload whose materials are
## the same reads its emitters and casters from them instead of
## converting every mesh again.
var kept: CompiledScene = CompiledScene()
var keeps: bool = false
## A renderer of `scene` through its camera (see RenderSettings.camera). The
## scene's buffers are uploaded; `scene` may be closed afterwards.
pub static func create(device: gpu.Device, scene: const CompiledScene*, settings: RenderSettings) -> Renderer!:
if settings.width == 0 or settings.height == 0 or settings.width > 16384 or settings.height > 16384: error(invalid, "an image is 1 to 16384 pixels on a side")
let camera = try find_camera(scene, settings.camera)
let frame = try ray_frame(scene.objects.object(camera), settings.width, settings.height)
return try Renderer.create_viewed(device, scene, settings, frame)
## A renderer of `scene` through `frame`, a view of the caller's (a
## viewport's camera, `look_frame`), in place of a scene camera; its size is
## the image's. `restart` moves it.
## Keep `scene`'s triangles and materials (its arrays swapped for the
## renderer's last ones, which the caller closes with it).
pub func keep_geometry(scene: CompiledScene*):
swap_geometry(&self.kept, scene)
let materials = self.kept.materials
self.kept.materials = scene.materials
scene.materials = materials
self.keeps = true
## The materials the kept triangles' indices name, when it keeps them.
pub func kept_materials() -> const Materials*?:
if not self.keeps: return none
return &self.kept.materials
## Whether `frame` keeps this renderer's projection (perspective or
## orthographic): a scene replaced or a restart through it may.
pub func projection_matches(frame: RayFrame) -> bool:
return frame.orthographic == self.frame.orthographic
## Image files read so far (tests: a reload reads none it already has).
pub func image_reads() -> i64:
return self.images.reads
pub static func create_viewed(device: gpu.Device, scene: const CompiledScene*, settings: RenderSettings, frame: RayFrame) -> Renderer!:
if frame.width == 0 or frame.height == 0 or frame.width > 16384 or frame.height > 16384: error(invalid, "an image is 1 to 16384 pixels on a side")
if settings.samples == 0 or settings.max_bounces == 0 or settings.max_bounces > 1024: error(invalid, "a render needs samples and 1 to 1024 bounces")
var chosen = settings
chosen.width = frame.width
chosen.height = frame.height
var uploaded = try GpuScene.upload(device, scene, not settings.software_bvh)
errdefer uploaded.destroy()
if not uploaded.accelerated and scene.nodes.count == 0 and scene.triangle_count() > 0:
error(invalid, "a scene compiled without its BVH needs hardware ray tracing")
var tables = try shared_tables(device)
# The guiding grid only when guiding: a placeholder holds its address.
var guide = try gpu.Buffer.allocate(device, guide_bytes if chosen.guiding else 16)
errdefer guide.destroy()
let guide_address = try guide.address()
var images = ImageStore()
errdefer images.close()
images.begin()
var loaded = try Loaded.create(device, scene, chosen, scene_radius(scene), &uploaded, &tables, &frame, &images)
errdefer loaded.destroy()
images.settle()
var order = Growing[u32]()
order.assign(scene.order.view()) catch failure:
order.close()
loaded.destroy()
error(failure.code, failure.message)
var renderer = Renderer(device, chosen, uploaded, loaded, order, tables, guide, guide_address, gpu.Buffer(), gpu.Buffer(), gpu.Buffer(), gpu.Buffer(), gpu.Texture(),
[gpu.Texture(), gpu.Texture(), gpu.Texture()], 0,
0, 0, 0, false, frame, 0, 0, false, none, none, 0, 0, [0, 0], [0, 0], -1, -1, 0, 0, 0, -1, 0, 0, 0, 0, 0,
Growing[u8](), [0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0], 0, 0, 0)
renderer.images = images
try renderer.allocate_view(frame.width, frame.height) catch failure:
renderer.destroy()
error(failure.code, failure.message)
renderer.show_view() catch failure:
renderer.destroy()
error(failure.code, failure.message)
return renderer
## The buffers that follow the view's size, for `width` × `height` pixels:
## path state for a band (the pool, or every pixel when fewer) and its
## light paths, the queues, the film and the images. Any before go.
func allocate_view(width: u32, height: u32) -> !:
self.release_view()
let pixels = (usize)width * (usize)height
let pool = (usize)self.settings.pool if self.settings.pool > 0 else (splat_pool if self.scene.splat_count > 0 else default_pool)
let band = pool if pool < pixels else pixels
let slots = band + self.loaded.light_paths(self.settings, pixels, band)
self.state_v = try gpu.Buffer.allocate(self.device, state_v_fields * slots * 16)
self.state_u = try gpu.Buffer.allocate(self.device, state_u_fields * slots * 4)
self.queues = try gpu.Buffer.allocate(self.device, (queue_base + queue_count * slots) * 4)
self.film = try gpu.Buffer.allocate(self.device, 4 * pixels * 16)
self.output = try gpu.Texture.create(self.device, width, height, gpu.Format.rgba32_float, storage = true)
for slot in 0..<(usize)3:
self.shown[slot] = try gpu.Texture.create(self.device, width, height, gpu.Format.rgba16_float, storage = true)
self.front = 0
self.capacity = pixels
self.image_width = width
self.image_height = height
self.pool = band
self.slots = slots
self.shown_width = 0
self.shown_height = 0
self.clear_film = true
func release_view():
self.state_v.destroy()
self.state_u.destroy()
self.queues.destroy()
self.film.destroy()
self.output.destroy()
for slot in 0..<(usize)3: self.shown[slot].destroy()
## The light paths a sample of the current view, and the constants' view rows.
func show_view() -> !:
let pixels = self.pixels()
let band = self.pool if self.pool < pixels else pixels
self.light_count_per_sample = self.loaded.light_paths(self.settings, pixels, band)
try self.loaded.show_view(self.settings, &self.frame, self.light_count_per_sample)
## Start over through `frame` (a moved camera, a resized view): the film is
## cleared before the next pass, and passes still in flight count for
## nothing and are never shown; the image shown stays until the new view's
## first whole sample replaces it (a pass that has already finished is
## shown first, since it was current while it ran). The
## scene stays on the device; the view's buffers are made again only when
## the view outgrows them. `frame` keeps the projection (perspective or
## orthographic) the renderer was made with.
pub func restart(frame: RayFrame) -> !:
try self.place(frame)
try self.show_view()
self.forget_passes()
## Take `frame` as the view, its buffers made again only when it
## outgrows them.
func place(frame: RayFrame) -> !:
if frame.width == 0 or frame.height == 0 or frame.width > 16384 or frame.height > 16384: error(invalid, "an image is 1 to 16384 pixels on a side")
if frame.orthographic != self.frame.orthographic: error(invalid, "a restart keeps the view's projection")
try self.retire_finished()
if (usize)frame.width * (usize)frame.height > self.capacity or frame.width > self.image_width or frame.height > self.image_height:
# Room for a quarter more each way: a view growing a few pixels
# at a time (a window resized) makes its buffers again seldom.
try self.settle()
try self.allocate_view(roomy(frame.width, self.image_width), roomy(frame.height, self.image_height))
self.frame = frame
self.settings.width = frame.width
self.settings.height = frame.height
## Load `scene`'s lights, materials and constants again, keeping the
## geometry on the device: `scene` must have the same triangles and splats
## as the scene the renderer was made from (a light or a material changed;
## `compile_scene` with `geometry` false makes such a scene without
## repeating the splats and BVHs, and its triangles are put in the BVH's
## order here). `settings` replace the renderer's but for the size and the
## pool; the film starts over, through `frame` when given (as `restart`
## would, the view's constants sent once).
pub func reload(scene: CompiledScene*, settings: RenderSettings, frame: RayFrame? = none) -> !:
if let wanted = frame: try self.place(wanted)
# Triangles left out (the materials are the same): the kept ones are
# lent for the load and taken back after it.
let lent = scene.meshes_kept and self.keeps
if scene.meshes_kept and not self.keeps: error(invalid, "a reload without triangles needs the renderer's kept")
if lent: swap_geometry(&self.kept, scene)
defer:
if lent: swap_geometry(&self.kept, scene)
if not lent and scene.nodes.count == 0 and scene.triangle_count() > 0 and self.order.count > 0:
if scene.triangle_count() != self.order.count: error(invalid, "a reload keeps the scene's geometry")
try reorder(scene, self.order.view())
if settings.samples == 0 or settings.max_bounces == 0 or settings.max_bounces > 1024: error(invalid, "a render needs samples and 1 to 1024 bounces")
try self.retire_finished()
var chosen = settings
chosen.width = self.settings.width
chosen.height = self.settings.height
chosen.pool = self.settings.pool
chosen.software_bvh = self.settings.software_bvh
# The radius is the geometry's, which `scene` may have no BVH to tell.
# New shading and texture coordinates first: the load reaches them
# by address.
if not lent: try self.scene.replace_shading(self.device, scene)
self.images.begin()
var loaded = try Loaded.create(self.device, scene, chosen, self.loaded.radius, &self.scene, &self.tables, &self.frame, &self.images, &self.loaded.kernels)
errdefer loaded.destroy()
# Light paths need slots: a view made without them grows its state.
let pixels = self.pixels()
let band = self.pool if self.pool < pixels else pixels
let grow = band + loaded.light_paths(chosen, pixels, band) > self.slots
try self.grow_guide(chosen)
loaded.kernels.adopt(&self.loaded.kernels)
self.loaded.destroy()
self.loaded = loaded
self.images.settle()
if not lent and self.keeps: self.keep_geometry(scene)
elif lent:
let materials = self.kept.materials
self.kept.materials = scene.materials
scene.materials = materials
self.settings = chosen
if grow:
try self.settle()
try self.allocate_view(self.image_width, self.image_height)
try self.show_view()
self.forget_passes()
## Take new geometry (`scene`, compiled whole) in place of this one's,
## keeping the view's buffers and images: the last image stays shown
## until the new scene's first whole sample replaces it, and nothing of
## the view is made again. The passes on the old geometry are waited for
## before its buffers go. `settings` keep the pool and BVH choice.
pub func replace_scene(scene: CompiledScene*, settings: RenderSettings, frame: RayFrame) -> !:
if settings.samples == 0 or settings.max_bounces == 0 or settings.max_bounces > 1024: error(invalid, "a render needs samples and 1 to 1024 bounces")
if settings.pool != self.settings.pool or settings.software_bvh != self.settings.software_bvh: error(invalid, "a scene replaced keeps the pool and BVH choice")
try self.place(frame)
try self.retire_finished()
var chosen = settings
chosen.width = self.settings.width
chosen.height = self.settings.height
var uploaded = try GpuScene.upload(self.device, scene, not chosen.software_bvh)
errdefer uploaded.destroy()
if not uploaded.accelerated and scene.nodes.count == 0 and scene.triangle_count() > 0:
error(invalid, "a scene compiled without its BVH needs hardware ray tracing")
self.images.begin()
var loaded = try Loaded.create(self.device, scene, chosen, scene_radius(scene), &uploaded, &self.tables, &self.frame, &self.images, &self.loaded.kernels)
errdefer loaded.destroy()
try self.order.assign(scene.order.view())
try self.grow_guide(chosen)
try self.settle()
loaded.kernels.adopt(&self.loaded.kernels)
self.loaded.destroy()
self.scene.destroy()
self.loaded = loaded
self.scene = uploaded
self.images.settle()
if self.keeps: self.keep_geometry(scene)
self.settings = chosen
let pixels = self.pixels()
let band = self.pool if self.pool < pixels else pixels
if band + self.loaded.light_paths(chosen, pixels, band) > self.slots:
try self.allocate_view(self.image_width, self.image_height)
try self.show_view()
self.forget_passes()
## Guiding turned on: its grid, in place of the placeholder (passes
## made while it was off never read it).
func grow_guide(chosen: RenderSettings) -> !:
if not chosen.guiding or self.guide.bytes() >= guide_bytes: return
var guide = try gpu.Buffer.allocate(self.device, guide_bytes)
errdefer guide.destroy()
self.guide_address = try guide.address()
self.guide.destroy()
self.guide = guide
## Passes in flight finish uncounted and unseen (a new generation); the
## next pass clears the film and starts sample 0.
func forget_passes():
self.generation += 1
self.older_completes = 0
self.newer_completes = 0
self.sample = 0
self.band = 0
self.completed = 0
self.light_samples = 0
self.clear_film = true
self.display_stale = false
## Wait for the passes in flight (before their buffers are replaced).
func settle() -> !:
while self.older != none:
if let running = self.older:
var waiting = running
try waiting.wait()
try self.retire()
## Take samples up to `samples` a pixel: more continues a render that has
## finished, fewer stops it sooner.
pub func set_samples(samples: u32) -> !:
if samples == 0: error(invalid, "a render needs samples")
self.settings.samples = samples
## Retire every pass in flight that has finished, oldest first.
func retire_finished() -> !:
while self.older != none:
let running = self.older else return
if not (try running.done()): return
try self.retire()
## Retire the older pass if it has finished: its samples count, and its
## display image is shown if it wrote one in the current generation.
func retire() -> !:
let running = self.older else return
if not (try running.done()): return
var finished = running
try finished.wait()
if self.settings.profile and self.marks.count > 1:
var stamps: u64[64]
try finished.timestamps(stamps[..<self.marks.count])
for at in 1..<self.marks.count:
self.kernel_ns[(usize)self.marks.items[at]] += (f64)(stamps[at] - stamps[at - 1])
finished.close()
if self.older_generation == self.generation:
self.completed = self.older_completes
if self.older_slot >= 0:
self.front = (usize)self.older_slot
self.shown_width = self.older_size[0]
self.shown_height = self.older_size[1]
self.older = self.newer
self.older_completes = self.newer_completes
self.older_size = self.newer_size
self.older_slot = self.newer_slot
self.older_generation = self.newer_generation
self.newer = none
self.newer_slot = -1
## Start the next pass if the last has finished. True while there is work,
## running or to come; false once every sample is in the image.
pub func advance() -> bool!:
try self.retire()
# Keep two passes in flight (one when profiling, whose timestamps belong
# to one pass), so the GPU never waits for the CPU to notice a finish.
let in_flight = (0 if self.older == none else 1) + (0 if self.newer == none else 1)
let depth = 1 if self.settings.profile else 2
if in_flight >= depth: return true
if self.sample >= self.settings.samples:
if not self.display_stale: return in_flight > 0
# Only the display changed: convert the film again.
self.display_stale = false
self.writing = (i64)self.free_slot()
var convert = try gpu.Compute.begin(self.device)
errdefer convert.close()
var block: u8[104]
var frame: f32[16]
try self.frame.pack(frame)
memory.copy(block[0..<64], u8[]((u8*)&frame[0], 64), 64)
try self.dispatch(&convert, &self.loaded.kernels.film_convert, block, 0, 0, 0, self.light_samples, (self.frame.width + 7) // 8, (self.frame.height + 7) // 8)
try convert.submit()
self.queue_pass(convert, self.sample)
return true
self.display_stale = false
# Only a sample's last band converts the film: a whole image, into a
# display image no one shows or writes.
let bands = (self.pixels() + self.pool - 1) // self.pool
self.writing = (i64)self.free_slot() if self.band + 1 == bands else -1
var pass = try gpu.Compute.begin(self.device)
errdefer pass.close()
self.marks.clear()
if self.settings.profile: try self.mark(&pass, kind_rest)
if self.clear_film:
# The planes the current view addresses (common.glsl's film_at:
# plane · width · height + pixel), not the room a larger view left.
try pass.fill(self.film, 0, 4 * self.pixels() * 16, 0)
self.clear_film = false
try self.record(&pass)
if self.settings.profile: try self.mark(&pass, kind_rest)
try pass.submit()
self.band += 1
if self.band == bands:
self.band = 0
self.sample += 1
self.queue_pass(pass, self.sample)
return true
## Hold a submitted pass: the samples every pixel has once it finishes, the
## display image it writes and its generation.
func queue_pass(pass: gpu.Compute, completes: u32):
let size: u32[2] = [self.frame.width, self.frame.height]
if self.older == none:
self.older = pass
self.older_completes = completes
self.older_size = size
self.older_slot = self.writing
self.older_generation = self.generation
else:
self.newer = pass
self.newer_completes = completes
self.newer_size = size
self.newer_slot = self.writing
self.newer_generation = self.generation
self.writing = -1
## A display image neither shown nor written by a pass in flight (of three,
## with at most two passes in flight, one is always free).
func free_slot() -> usize:
for slot in 0..<(usize)3:
if slot == self.front: continue
if self.older != none and self.older_slot == (i64)slot: continue
if self.newer != none and self.newer_slot == (i64)slot: continue
return slot
return self.front
## Run every remaining pass to the end (offline renders and tests).
pub func finish() -> !:
while try self.advance():
if let running = self.older:
if not (try running.done()):
var waiting = running
try waiting.wait()
## Samples every pixel has, counting only passes that have finished.
pub func samples_done() -> u32:
return self.completed
## The render as linear ACEScg, rgba32f: what is saved. A restarted view
## smaller than the images fills their top-left corner (`shown_size`).
pub func image() -> gpu.Texture:
return self.output
## The render ready to show: exposed, in linear Rec.709, through the view
## (rgba16f). Always one whole image of one view; passes in flight never
## write it.
pub func display() -> gpu.Texture:
return self.shown[self.front]
## The size of the image in `display`, from its top-left corner ((0, 0)
## before the first whole sample).
pub func shown_size() -> u32[2]:
return [self.shown_width, self.shown_height]
## Show the image at `exposure` stops through `view` (0 standard, 1 neutral
## tone mapping); the next pass, or a conversion of its own, applies it.
pub func set_display(exposure: f64, view: i64) -> !:
var row: f32[4] = [(f32)exposure, (f32)view, 0.0, 0.0]
try self.loaded.constants.upload(9 * 16, u8[]((u8*)&row[0], 16))
self.display_stale = true
## How many pixels adaptive sampling has stopped (waits for work in flight).
pub func converged_pixels() -> usize!:
let pixels = self.pixels()
let bytes = try new u8[pixels * 16] --- in memory.heap
defer free(bytes) in memory.heap
try self.film.read(pixels * 16, bytes)
var count: usize = 0
for at in 0..<pixels:
if memory.read[f32]((const void*)&bytes[at * 16 + 12]) > 0.5: count += 1
return count
## Whether intersection uses hardware ray queries.
pub func ray_traced() -> bool:
return self.scene.accelerated
pub func render_settings() -> RenderSettings:
return self.settings
## The image as rgba32f, row by row from the top (waits for work in flight);
## the view must fill the images (never restarted smaller).
pub func read(out: f32[]) -> !:
if self.frame.width != self.image_width or self.frame.height != self.image_height: error(invalid, "reading the image needs a view the size of the image")
let pixels = self.pixels()
if out.length != pixels * 4: error(invalid, "reading the image needs four floats a pixel")
try self.output.read(u8[]((u8*)out.data, out.length * 4))
func pixels() -> usize:
return (usize)self.frame.width * (usize)self.frame.height
## One pass: the band's sample from camera to film, and the image updated.
func record(pass: gpu.Compute*) -> !:
let start = self.band * self.pool
let remaining = self.pixels() - start
let count = self.pool if self.pool < remaining else remaining
var block: u8[104]
var frame: f32[16]
try self.frame.pack(frame)
memory.copy(block[0..<64], u8[]((u8*)&frame[0], 64), 64)
let groups = (u32)((count + 63) // 64)
# The sample's light paths start with its first band.
self.lights_in_pass = (u32)self.light_count_per_sample if self.band == 0 else 0
# Every queue counter and the workgroups' done count start at zero; the
# camera queues only pixels still sampling.
try pass.fill(self.queues, 0, 64, 0)
try self.dispatch(pass, &self.loaded.kernels.camera, block, start, count, 0, 0, groups, 1)
if self.lights_in_pass > 0:
try self.dispatch(pass, &self.loaded.kernels.light_emit, block, start, count, 0, 0, (self.lights_in_pass + 63) // 64, 1)
self.light_samples += 1
# One more round than bounces: the last BSDF rays still find lights;
# with cut-outs, rounds for rays passing through them at the same bounce.
for bounce in 0..<(usize)self.settings.max_bounces + 1 + self.loaded.through:
let current = (u32)(bounce % 2)
# Each kernel's last workgroup sizes the next (common.glsl: last_group).
try self.indirect(pass, &self.loaded.kernels.intersect_closest, block, start, count, current, (usize)current)
try self.indirect(pass, &self.loaded.kernels.shade_surface, block, start, count, current, 2)
try self.indirect(pass, &self.loaded.kernels.shade_miss, block, start, count, current, 3)
try self.indirect(pass, &self.loaded.kernels.intersect_shadow, block, start, count, current, 4)
try self.dispatch(pass, &self.loaded.kernels.finish, block, start, count, 0, 0, groups, 1)
if self.settings.guiding:
try self.dispatch(pass, &self.loaded.kernels.guide_fit, block, start, count, 0, 0, (u32)(guide_cells // 64), 1)
# After the last band of every 4th sample past the minimum, check which
# pixels have converged.
let bands = (self.pixels() + self.pool - 1) // self.pool
let taken = self.sample + 1
if self.settings.noise_threshold > 0.0 and self.band + 1 == bands and taken >= self.settings.adaptive_minimum and taken % 4 == 0:
let x = (self.frame.width + 7) // 8
let y = (self.frame.height + 7) // 8
try self.dispatch(pass, &self.loaded.kernels.adaptive, block, start, count, 0, 0, x, y)
try self.dispatch(pass, &self.loaded.kernels.adaptive, block, start, count, 0, 1, x, y)
if self.writing >= 0:
try self.dispatch(pass, &self.loaded.kernels.film_convert, block, start, count, 0, self.light_samples, (self.frame.width + 7) // 8, (self.frame.height + 7) // 8)
## The push constants after the camera frame: band, sample and step.
func uniforms(block: u8[], start: usize, count: usize, current: u32, phase: u32):
let values: u32[8] = [(u32)start, (u32)count, self.sample, self.lights_in_pass, current, phase, (u32)self.slots, self.settings.seed]
for at in 0..<(usize)8: memory.write[u32]((void*)&block[64 + at * 4], values[at])
memory.write[u64]((void*)&block[96], self.guide_address)
func bindings(kernel: const Kernel*) -> gpu.Binding[16]:
var all: gpu.Binding[16] = [gpu.Binding(buffer = self.scene.nodes), gpu.Binding(buffer = self.scene.positions), gpu.Binding(buffer = self.scene.indices),
gpu.Binding(buffer = self.loaded.lights), gpu.Binding(buffer = self.state_v), gpu.Binding(buffer = self.state_u),
gpu.Binding(buffer = self.queues), gpu.Binding(buffer = self.film), gpu.Binding(texture = self.output),
gpu.Binding(buffer = self.loaded.constants), gpu.Binding(texture = self.shown[(usize)self.writing if self.writing >= 0 else self.front]),
gpu.Binding(buffer = self.scene.shading), gpu.Binding(buffer = self.loaded.materials),
gpu.Binding(filter = gpu.Filter.linear), gpu.Binding(), gpu.Binding(buffer = self.loaded.emitters)]
if self.scene.accelerated: all[14] = gpu.Binding(accel = self.scene.tlas)
for at in 0..<(usize)16:
if at >= kernel.kinds.length or kernel.kinds[at] == 0: all[at] = gpu.Binding()
return all
func dispatch(pass: gpu.Compute*, kernel: const Kernel*, block: u8[], start: usize, count: usize, current: u32, phase: u32, x: u32, y: u32) -> !:
self.uniforms(block, start, count, current, phase)
let bound = self.bindings(kernel)
try pass.dispatch(kernel.kernel, bound, block, x, y)
if self.settings.profile and self.marks.count < 62: try self.mark(pass, self.kind_of(kernel))
## Profiling: a timestamp after the commands so far, charged to `kind`.
func mark(pass: gpu.Compute*, kind: u8) -> !:
_ = try pass.timestamp()
try self.marks.push(kind)
func kind_of(kernel: const Kernel*) -> u8:
if kernel == &self.loaded.kernels.camera: return kind_camera
if kernel == &self.loaded.kernels.intersect_closest: return kind_closest
if kernel == &self.loaded.kernels.shade_surface: return kind_surface
if kernel == &self.loaded.kernels.shade_miss: return kind_miss
if kernel == &self.loaded.kernels.intersect_shadow: return kind_shadow
if kernel == &self.loaded.kernels.finish: return kind_finish
if kernel == &self.loaded.kernels.film_convert: return kind_convert
if kernel == &self.loaded.kernels.light_emit: return kind_light
return kind_adaptive
## Milliseconds each kernel kind has taken over the finished passes, with
## `profile` on, in the order of `kernel_names`: what the first 60 commands
## of each pass took, and the rest under "later rounds".
pub func kernel_times(out: f64[]) -> !:
if out.length < 10: error(invalid, "kernel times need ten numbers")
for at in 0..<(usize)10: out[at] = self.kernel_ns[at] * 1e-6
## A kernel over queue `queue`, sized by the arguments its producer left for it.
func indirect(pass: gpu.Compute*, kernel: const Kernel*, block: u8[], start: usize, count: usize, current: u32, queue: usize) -> !:
self.uniforms(block, start, count, current, 0)
let bound = self.bindings(kernel)
if kernel == &self.loaded.kernels.shade_surface:
try pass.dispatch_indirect(kernel.kernel, bound, block, self.queues, (16 + 3 * queue) * 4, textures = self.loaded.textures.table)
else:
try pass.dispatch_indirect(kernel.kernel, bound, block, self.queues, (16 + 3 * queue) * 4)
if self.settings.profile and self.marks.count < 62: try self.mark(pass, self.kind_of(kernel))
pub func destroy():
for slot in 0..<(usize)2:
let held = self.older if slot == 0 else self.newer
if let running = held:
var waiting = running
waiting.wait() catch failure: _ = failure
waiting.close()
self.older = none
self.newer = none
self.loaded.destroy()
self.images.close()
self.kept.close()
self.scene.destroy()
self.guide.destroy()
self.release_view()
self.order.close()
self.marks.close()
## The albedo tables energy compensation reads (shaders/microfacet.glsl),
## computed on the device by the same GGX code the shading kernels run.
let table_floats: usize = 32 * 32 + 32 + 32 * 32 * 16
## The tables of the device renderers last drew on: they hold no scene, so
## one copy serves every renderer there (a new scene's renderer reads it
## again), until another device or `release_tables`.
struct HeldTables:
var device: gpu.Device
var buffer: gpu.Buffer
var held_tables: HeldTables? = none
func shared_tables(device: gpu.Device) -> gpu.Buffer!:
if let held = held_tables:
var wanted = device
if held.device.same(&wanted): return held.buffer
release_tables()
var buffer = try make_tables(device)
errdefer buffer.destroy()
held_tables = HeldTables(device = try device.share(), buffer = buffer)
return buffer
## Free the shared albedo tables (made again on the next renderer): for a
## clean shutdown, or before closing the device.
pub func release_tables():
let held = held_tables else return
held_tables = none
var buffer = held.buffer
buffer.destroy()
var device = held.device
device.destroy()
func make_tables(device: gpu.Device) -> gpu.Buffer!:
var tables = try gpu.Buffer.allocate(device, table_floats * 4)
errdefer tables.destroy()
var kernel = try gpu.Kernel.create(device, tables_comp_words, tables_comp_msl, tables_comp_group, tables_comp_bindings)
defer kernel.destroy()
var pass = try gpu.Compute.begin(device)
defer pass.close()
let bound: gpu.Binding[1] = [gpu.Binding(buffer = tables)]
var phase: u32[1] = [0]
try pass.dispatch(kernel, bound, u8[]((u8*)&phase[0], 4), (u32)((32 * 32 * 17 + 63) // 64))
phase[0] = 1
try pass.dispatch(kernel, bound, u8[]((u8*)&phase[0], 4), 1)
# Later passes are ordered after this one; nothing waits for it.
try pass.submit()
return tables
## The camera to render through: `index`, or the first camera when it is -1.
func find_camera(scene: const CompiledScene*, index: i64) -> usize!:
if index >= 0:
if (usize)index < scene.objects.count() and scene.objects.object((usize)index).kind == SceneKind.camera: return (usize)index
error(invalid, "the scene object is not a camera")
for at in 0..<scene.objects.count():
if scene.objects.object(at).kind == SceneKind.camera: return at
error(invalid, "the scene has no camera")
## Swap the triangle arrays of `a` and `b`.
func swap_geometry(a: CompiledScene*, b: CompiledScene*):
let positions = a.positions
a.positions = b.positions
b.positions = positions
let indices = a.indices
a.indices = b.indices
b.indices = indices
let faces = a.faces
a.faces = b.faces
b.faces = faces
let shading = a.shading
a.shading = b.shading
b.shading = shading
let uvs = a.uvs
a.uvs = b.uvs
b.uvs = uvs
let used = a.used
a.used = b.used
b.used = used
## A side of `wanted` pixels with room to grow: a quarter more, in steps of
## 64, at most 16384 (and never less than the side held, `held`).
func roomy(wanted: u32, held: u32) -> u32:
var side = (wanted + wanted // 4 + 63) // 64 * 64
if side < held: side = held
return side if side <= 16384 else 16384