Luce packages
LuceLuce BaseLuciaOS

dymokomi/luce-render

Source of release 0.1.0

0.1.0 / 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 film_convert (the film's average into the 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.
#
#       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

## 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

    ## 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, 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)
        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, 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)

    func destroy():
        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()

## Intersection kernels serve both builds: they read no spectra.
func intersect_kernel(device: gpu.Device, rays: bool, constants: const gpu.Constant[]) -> Kernel!:
    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)

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
    var kernels: Kernels
    var scene: GpuScene
    var lights: gpu.Buffer
    var constants: gpu.Buffer
    var materials: gpu.Buffer
    var tables: gpu.Buffer
    var emitters: gpu.Buffer
    ## The path-guiding grid (guide.glsl), reached by its address.
    var guide: gpu.Buffer
    var guide_address: u64
    var state_v: gpu.Buffer
    var state_u: gpu.Buffer
    var queues: gpu.Buffer
    var film: gpu.Buffer
    var output: gpu.Texture
    var shown: gpu.Texture
    ## Display settings changed since the display image was last made.
    var display_stale: bool
    var frame: RayFrame
    var pool: usize
    var light_count: usize
    ## Rounds of each pass beyond the bounces, for rays passing through cut-outs.
    var through: usize
    ## The passes in flight (older first) and the samples each completes; what
    ## comes next: sample `sample`, band `band`.
    var older: gpu.Compute?
    var newer: gpu.Compute?
    var older_completes: u32
    var newer_completes: u32
    var sample: u32
    var band: usize
    var completed: 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),
    ## and the pool's slots: a band's camera paths, then the light paths.
    var lights_in_pass: u32
    var slots: usize
    ## The materials' textures, and the triangles' texture coordinates.
    var textures: MaterialTextures
    var uvs: gpu.Buffer
    ## The materials' node-graph programs (shader_graph.lucb).
    var programs: gpu.Buffer

    ## 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")
        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")
        let camera = try find_camera(scene, settings.camera)
        let frame = try ray_frame(scene.objects.object(camera), settings.width, settings.height)
        let pixels = (usize)settings.width * (usize)settings.height
        let pool = (usize)settings.pool if settings.pool > 0 else default_pool
        let band = pool if pool < pixels else pixels
        var uploaded = try GpuScene.upload(device, scene, not settings.software_bvh)
        errdefer uploaded.destroy()
        var packed = Growing[f32]()
        defer packed.close()
        # The first dome with an image lights by it (environment.lucb).
        var environment = Environment()
        defer environment.close()
        var environment_view: const Environment*? = none
        for index in 0..<scene.objects.count():
            let item = scene.objects.object(index)
            if item.kind != SceneKind.light or item.light.shape != LightShape.dome or scene.objects.texture(index).length == 0: continue
            environment = try load_environment(scene.objects.texture(index))
            environment_view = &environment
            break
        let (light_count, distant_power, dome) = try pack_lights(&scene.objects, scene_radius(scene), &packed, environment_view)
        # Materials: the default first (material 0), then the scene's library.
        var library = Growing[OpenPbr]()
        defer library.close()
        try library.push(settings.material)
        for index in 0..<scene.materials.count(): try library.push(openpbr_of(&scene.materials, index))
        # The light tree's nodes follow the light records; its links, emitter
        # records and triangle map make the emitter buffer.
        var tree = try build_light_tree(scene, packed.view(), light_count, library.view())
        defer tree.close()
        let node_offset = packed.count // 4
        for value in tree.nodes.view(): try packed.push(value)
        # The dome's texels (a vec4 each), then its cumulative weights.
        var dome_row: f64[8] = [-1.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0]
        if dome >= 0:
            while packed.count % 4 != 0: try packed.push(0.0)
            let texel_base = packed.count // 4
            for value in environment.texels.view(): try packed.push(value)
            let cdf_base = packed.count
            for value in environment.cdf.view(): try packed.push(value)
            while packed.count % 4 != 0: try packed.push(0.0)
            dome_row = [(f64)dome, (f64)texel_base, (f64)environment.width, (f64)environment.height, (f64)cdf_base, environment.total, 0.0, 0.0]
        var lights = try buffer_of(device, u8[]((u8*)packed.items.data, packed.count * 4))
        errdefer lights.destroy()
        var links = Growing[u32]()
        defer links.close()
        try links.assign(tree.links.view())
        for value in tree.records.view(): try links.push(value)
        var emitters = try buffer_of(device, u8[]((u8*)links.items.data, links.count * 4))
        errdefer emitters.destroy()
        let total = distant_power + tree.energy
        let p_distant = (distant_power / total if total > 0.0 else 0.0) if tree.emitter_count > 0 else (1.0 if distant_power > 0.0 else 0.0)
        var rows: f32[128]
        # A pixel's width at unit distance (perspective; orthographic cells
        # grow with distance just the same, which is harmless).
        try fill_constants(rows, settings, light_count, scene_radius(scene), frame.du.length())
        let tree_row: f64[4] = [(f64)tree.node_count(), (f64)node_offset, p_distant, (f64)tree.emitter_count]
        let offsets_row: f64[4] = [(f64)tree.links.count, (f64)(tree.links.count + tree.emitter_count * 4), 0.0, 0.0]
        for k in 0..<(usize)4:
            rows[32 + k] = (f32)tree_row[k]
            rows[40 + k] = (f32)offsets_row[k]
        # The materials' textures (slots a material, the default's first),
        # and the buffers kernels reach by address: the albedo tables and the
        # triangles' texture coordinates.
        var textures = try load_textures(device, &scene.materials)
        errdefer textures.destroy()
        var tables = try make_tables(device)
        errdefer tables.destroy()
        var corner_uvs = Growing[f32]()
        defer corner_uvs.close()
        try corner_uvs.assign(scene.uvs.view())
        while corner_uvs.count < 6: try corner_uvs.push(0.0)
        var uvs = try buffer_of(device, u8[]((u8*)corner_uvs.items.data, corner_uvs.count * 4))
        errdefer uvs.destroy()
        var programs = try buffer_of(device, u8[]((u8*)textures.programs.items.data, textures.programs.count * 4))
        errdefer programs.destroy()
        memory.write[u64]((void*)&rows[92], try tables.address())
        memory.write[u64]((void*)&rows[94], try uvs.address())
        memory.write[u64]((void*)&rows[96], try programs.address())
        var records = Growing[f32]()
        defer records.close()
        var cutouts = false
        for index in 0..<library.count:
            let material = library.items[index]
            try pack_material(material, textures.entries.items[index], &records)
            cutouts = cutouts or material.geometry_opacity < 1.0
        rows[3] = 1.0 if cutouts else 0.0
        # The camera: light paths a sample (at most a band's; they take the
        # pool's slots after the band's camera paths), the image plane's pixel
        # area at unit distance, the lens, the camera's axis.
        # Domes and distant lights with a size start light paths too, on a disk
        # around what casts caustics (shaders/lights.glsl), sharing them with
        # the tree's emitters by power.
        let (focus, focus_radius, casters) = caster_bounds(scene, library.view())
        var afar = false
        for index in 0..<light_count:
            let kind = packed.items[index * light_stride * 4 + 3]
            if kind == 4.0 or (kind == 3.0 and packed.items[index * light_stride * 4 + 11] < 1.0 - 1e-7): afar = casters
        let afar_power = distant_power * (focus_radius / scene_radius(scene)) * (focus_radius / scene_radius(scene)) if afar else 0.0
        let afar_share = afar_power / (afar_power + tree.energy) if afar_power + tree.energy > 0.0 else 0.0
        let emit_rows: f64[8] = [afar_share, focus_radius, 0.0, 0.0, focus.x, focus.y, focus.z, 0.0]
        for k in 0..<(usize)8: rows[84 + k] = (f32)emit_rows[k]
        var light_paths: usize = 0
        if settings.light_tracing > 0.0 and not frame.orthographic and (tree.emitter_count > 0 or afar):
            let wanted = (usize)math.max(1.0, math.round(settings.light_tracing * (f64)pixels))
            light_paths = wanted if wanted < band else band
        let slots = band + light_paths
        let pixel_area = frame.du.length() * frame.dv.length()
        let view_rows: f64[8] = [(f64)light_paths, 1.0 / pixel_area if pixel_area > 0.0 else 0.0, frame.lens_radius, frame.focus_distance,
                                 frame.forward.x, frame.forward.y, frame.forward.z, 0.0]
        for k in 0..<(usize)8: rows[56 + k] = (f32)view_rows[k]
        for k in 0..<(usize)8: rows[64 + k] = (f32)dome_row[k]
        var constants = try gpu.Buffer.create(device, u8[]((u8*)&rows[0], constants_rows * 16))
        errdefer constants.destroy()
        # Kernels specialized to the scene: the features its materials use, its
        # light count, guiding.
        var has_programs = false
        for entry in textures.entries.view(): has_programs = has_programs or entry >= 0.0
        var features = scene_features(library.view(), light_count, settings, light_paths > 0, has_programs)
        var kernels = try Kernels.create(device, settings.spectral, uploaded.accelerated, features)
        errdefer kernels.destroy()
        var materials = try buffer_of(device, u8[]((u8*)records.items.data, records.count * 4))
        errdefer materials.destroy()
        var guide = try gpu.Buffer.allocate(device, guide_bytes)
        errdefer guide.destroy()
        let guide_address = try guide.address()
        var state_v = try gpu.Buffer.allocate(device, state_v_fields * slots * 16)
        errdefer state_v.destroy()
        var state_u = try gpu.Buffer.allocate(device, state_u_fields * slots * 4)
        errdefer state_u.destroy()
        var queues = try gpu.Buffer.allocate(device, (queue_base + queue_count * slots) * 4)
        errdefer queues.destroy()
        var film = try gpu.Buffer.allocate(device, 4 * pixels * 16)
        errdefer film.destroy()
        var output = try gpu.Texture.create(device, settings.width, settings.height, gpu.Format.rgba32_float, storage = true)
        errdefer output.destroy()
        let shown = try gpu.Texture.create(device, settings.width, settings.height, gpu.Format.rgba32_float, storage = true)
        return Renderer(device, settings, kernels, uploaded, lights, constants, materials, tables, emitters, guide, guide_address, state_v, state_u, queues, film, output, shown, false, frame, band, light_count, 8 if cutouts else 0, none, none, 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], light_paths, 0, 0, slots, textures, uvs, programs)

    ## 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!:
        # Retire the older pass when it has finished.
        if let running = self.older:
            if try running.done():
                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()
                self.completed = self.older_completes
                self.older = self.newer
                self.older_completes = self.newer_completes
                self.newer = none
        # 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
            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.kernels.film_convert, block, 0, 0, 0, self.light_samples, (self.settings.width + 7) // 8, (self.settings.height + 7) // 8)
            try convert.submit()
            self.queue_pass(convert, self.sample)
            return true
        self.display_stale = false
        var pass = try gpu.Compute.begin(self.device)
        errdefer pass.close()
        self.marks.clear()
        if self.settings.profile: try self.mark(&pass, kind_rest)
        try self.record(&pass)
        if self.settings.profile: try self.mark(&pass, kind_rest)
        try pass.submit()
        let bands = (self.pixels() + self.pool - 1) // self.pool
        self.band += 1
        if self.band == bands:
            self.band = 0
            self.sample += 1
        self.queue_pass(pass, self.sample if self.band == 0 else self.sample)
        return true

    ## Hold a submitted pass: the samples every pixel has once it finishes.
    func queue_pass(pass: gpu.Compute, completes: u32):
        if self.older == none:
            self.older = pass
            self.older_completes = completes
        else:
            self.newer = pass
            self.newer_completes = completes

    ## 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.
    pub func image() -> gpu.Texture:
        return self.output

    ## The render ready to show: exposed, in linear Rec.709, through the view.
    pub func display() -> gpu.Texture:
        return self.shown

    ## 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.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).
    pub func read(out: f32[]) -> !:
        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.settings.width * (usize)self.settings.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.kernels.camera, block, start, count, 0, 0, groups, 1)
        if self.lights_in_pass > 0:
            try self.dispatch(pass, &self.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.through:
            let current = (u32)(bounce % 2)
            # Each kernel's last workgroup sizes the next (common.glsl: last_group).
            try self.indirect(pass, &self.kernels.intersect_closest, block, start, count, current, (usize)current)
            try self.indirect(pass, &self.kernels.shade_surface, block, start, count, current, 2)
            try self.indirect(pass, &self.kernels.shade_miss, block, start, count, current, 3)
            try self.indirect(pass, &self.kernels.intersect_shadow, block, start, count, current, 4)
        try self.dispatch(pass, &self.kernels.finish, block, start, count, 0, 0, groups, 1)
        if self.settings.guiding:
            try self.dispatch(pass, &self.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.settings.width + 7) // 8
            let y = (self.settings.height + 7) // 8
            try self.dispatch(pass, &self.kernels.adaptive, block, start, count, 0, 0, x, y)
            try self.dispatch(pass, &self.kernels.adaptive, block, start, count, 0, 1, x, y)
        try self.dispatch(pass, &self.kernels.film_convert, block, start, count, 0, self.light_samples, (self.settings.width + 7) // 8, (self.settings.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.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.constants), gpu.Binding(texture = self.shown),
                                    gpu.Binding(buffer = self.scene.shading), gpu.Binding(buffer = self.materials),
                                    gpu.Binding(filter = gpu.Filter.linear), gpu.Binding(), gpu.Binding(buffer = self.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.kernels.camera: return kind_camera
        if kernel == &self.kernels.intersect_closest: return kind_closest
        if kernel == &self.kernels.shade_surface: return kind_surface
        if kernel == &self.kernels.shade_miss: return kind_miss
        if kernel == &self.kernels.intersect_shadow: return kind_shadow
        if kernel == &self.kernels.finish: return kind_finish
        if kernel == &self.kernels.film_convert: return kind_convert
        if kernel == &self.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.kernels.shade_surface:
            try pass.dispatch_indirect(kernel.kernel, bound, block, self.queues, (16 + 3 * queue) * 4, textures = self.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.kernels.destroy()
        self.scene.destroy()
        self.lights.destroy()
        self.constants.destroy()
        self.materials.destroy()
        self.tables.destroy()
        self.textures.destroy()
        self.uvs.destroy()
        self.programs.destroy()
        self.emitters.destroy()
        self.guide.destroy()
        self.state_v.destroy()
        self.state_u.destroy()
        self.queues.destroy()
        self.film.destroy()
        self.output.destroy()
        self.shown.destroy()
        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

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)
    try pass.submit()
    try pass.wait()
    return tables

## The specialization constants of the integrator kernels (shaders/common.glsl):
## which material features the scene uses, cut-outs, guiding, the light count,
## light tracing.
func scene_features(library: const OpenPbr[], light_count: usize, settings: RenderSettings, light_tracing: bool, programs: bool) -> gpu.Constant[9]:
    var coat = false
    var transmission = false
    var metal = false
    var emission = false
    var cutouts = false
    for material in library:
        coat = coat or material.coat_weight > 0.0
        transmission = transmission or material.transmission_weight > 0.0
        metal = metal or material.base_metalness > 0.0
        emission = emission or material.emission_luminance > 0.0
        cutouts = cutouts or material.geometry_opacity < 1.0
    return [gpu.Constant.boolean(0, coat), gpu.Constant.boolean(1, transmission), gpu.Constant.boolean(2, metal),
            gpu.Constant.boolean(3, emission), gpu.Constant.boolean(4, cutouts), gpu.Constant.boolean(5, settings.guiding),
            gpu.Constant.uint32(6, (u32)light_count), gpu.Constant.boolean(7, light_tracing), gpu.Constant.boolean(8, programs)]

## 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")

## Whether a material casts caustics: it refracts, or reflects sharply
## enough (metal, glossy specular or a clear coat) to focus light.
func casts_caustics(material: const OpenPbr*) -> bool:
    if material.transmission_weight > 0.0: return true
    if material.base_metalness > 0.0 and material.specular_roughness < 0.3: return true
    if material.coat_weight > 0.0 and material.coat_roughness < 0.3: return true
    return material.specular_weight > 0.0 and material.specular_roughness < 0.1

## The sphere around the triangles that cast caustics, where light paths
## from afar start toward (shaders/lights.glsl): light from a dome or the sun
## needs light paths for what glass and mirrors focus, and only there. False
## when nothing casts.
func caster_bounds(scene: const CompiledScene*, library: const OpenPbr[]) -> (Vector3, f64, bool):
    var lo = Vector3(1e30, 1e30, 1e30)
    var hi = Vector3(-1e30, -1e30, -1e30)
    var any = false
    let p = scene.positions.view()
    for triangle in 0..<scene.triangle_count():
        let material = (usize)scene.shading.items[triangle * 4 + 3]
        if material >= library.length or not casts_caustics(&library[material]): continue
        for corner in 0..<(usize)3:
            let at = (usize)scene.indices.items[triangle * 3 + corner] * 3
            let point = Vector3((f64)p[at], (f64)p[at + 1], (f64)p[at + 2])
            lo = Vector3(math.min(lo.x, point.x), math.min(lo.y, point.y), math.min(lo.z, point.z))
            hi = Vector3(math.max(hi.x, point.x), math.max(hi.y, point.y), math.max(hi.z, point.z))
        any = true
    if not any: return (Vector3(), 1.0, false)
    return (lo.add(hi).multiply_scalar(0.5), math.max(1e-3, 0.5 * hi.subtract(lo).length()), true)

## Half the diagonal of the triangles' bounds (1 for an empty scene).
func scene_radius(scene: const CompiledScene*) -> f64:
    if scene.point_count() == 0: return 1.0
    let root = scene.nodes.items[0]
    let d = Vector3((f64)(root.hi.x - root.lo.x), (f64)(root.hi.y - root.lo.y), (f64)(root.hi.z - root.lo.z))
    return math.max(1.0, 0.5 * d.length())

## Constants rows (shaders/common.glsl K_*), 16 vec4s.
func fill_constants(rows: f32[], settings: RenderSettings, light_count: usize, radius: f64, footprint: f64) -> !:
    for at in 0..<rows.length: rows[at] = 0.0
    let film = film_matrix()
    let integrals = cmf_integrals()
    let background = fit_spectrum(settings.background)
    let values: f64[32] = [(f64)light_count, (f64)settings.max_bounces, settings.clamp_indirect, 0.0,
                           background.c0, background.c1, background.c2, background.scale,
                           settings.background.x, settings.background.y, settings.background.z, 0.0,
                           film.m[0], film.m[1], film.m[2], 0.0,
                           film.m[3], film.m[4], film.m[5], 0.0,
                           film.m[6], film.m[7], film.m[8], 0.0,
                           integrals.x, integrals.y, integrals.z, 0.0,
                           (f64)settings.diffuse_bounces, (f64)settings.glossy_bounces, (f64)settings.transmission_bounces, 0.0]
    rows[44] = (f32)settings.noise_threshold
    rows[45] = (f32)settings.adaptive_minimum
    # Guiding: on, the cell width per unit of distance from the camera (8
    # pixels' footprint), the guide's share of samples where trained, the
    # samples that train a cell; and the smallest cell.
    let guide_row: f64[5] = [1.0 if settings.guiding else 0.0, 8.0 * footprint, 0.5, 16.0, radius * 1e-4]
    for k in 0..<(usize)5: rows[48 + k] = (f32)guide_row[k]
    for at in 0..<(usize)32: rows[at] = (f32)values[at]
    # Environment texels' spectra: ACEScg to the basis spectra's weights.
    let basis = basis_weights()
    for r in 0..<(usize)3:
        for k in 0..<(usize)3: rows[72 + r * 4 + k] = (f32)basis.m[r * 3 + k]