Luce packages
LuceLuce BaseLuciaOS

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