Luce packages
LuceLuce BaseLuciaOS

dymokomi/luce-develop

Source of release 0.1.0

0.1.0 / src / film_passes.lucb

## Film on the negative, on the CPU: shaders/film_stages.glsl's passes step for
## step, at the scene's own size, each pass's output in single floats as the
## GPU's textures hold it. `filmed` turns a scene into the filmed one, which the
## develop then draws with the identity for its matrix and no lens vignetting
## (film did both). `plan_for` sizes the blurs for both paths.
##
## The passes: expose (the develop's matrix and lens vignetting, then each
## layer's exposure); scatter (each layer's exponential, across then down);
## halation (film_halation.lucb: the exposure averaged over blocks, gathered at
## the kernel's samples, and the halo added back at full size to the scattered
## exposure); development in steps (film.lucb's `chemistry_steps`), each
## releasing inhibitor and using developer (alpha) as the layers develop under
## the inhibitor the steps before released, as far as it has spread by then:
## the field is added to and diffused one step at a time (across, then down),
## so each step's kinetics see the field as it is at that time; develop as dye clouds
## with their grain, and scan. Or, for the stochastic render
## (film_grains.lucb), the effective log H the film developed at, then each
## pixel the light its samples pass through the grains, averaged and scanned.
import memory
from luce_std import math
from luce_std import parallel
from film import Film
import film
import film_halation
import film_grains
from tables import build as build_tables
from settings import parse as settings_text
from scene import Scene
from tables import Tables

## Blurs are never wider than this many pixels a side.
let widest: f64 = 64.0

## A pass's blur: its size per channel in pixels (a Gaussian's σ, or an
## exponential's length), which kind, and how many pixels a side it reads.
pub struct Blur:
    pub var sigma: f32[3]
    pub var radius: i32
    pub var exponential: bool
    ## A Gaussian's σ for alpha (the developer's spread), 0: alpha unblurred.
    pub var alpha: f32 = 0.0f32

## The blurs and grain for a scene `width` pixels wide, in the values the GPU is
## handed (single floats).
pub struct Plan:
    ## µm of negative per scene pixel.
    pub var pitch: f32
    pub var scatter: Blur
    ## Halation: each layer's strength, and the block (texels a side) its
    ## gather runs at, about an eighth of the ring's radius.
    pub var halation_strength: f32[3]
    pub var halation_block: i32
    ## Development's steps: how far the inhibitor and used developer spread in
    ## one step (a release at step s has spread √(k − s) times this by step k,
    ## √(n − s + 1) by the end), and how much of the used developer each step
    ## leaves unrenewed.
    pub var step_spread: Blur
    pub var keep: f64
    ## The duplicates' blur over the developed image (none: radius 0).
    pub var duplicated: Blur

## Gaussians are cut at 3σ, exponentials at 6 lengths.
func blur_of(sigmas: f64[3], exponential: bool = false) -> Blur:
    let most = math.max(sigmas[0], math.max(sigmas[1], sigmas[2]))
    let reach = 6.0 if exponential else 3.0
    return Blur(sigma = [(f32)sigmas[0], (f32)sigmas[1], (f32)sigmas[2]], radius = (i32)math.min(math.ceil(reach * most), widest),
                exponential = exponential)

pub func plan_for(source: const Film*, width: usize) -> Plan:
    let pitch = source.value(6)[2] * 2.0 / (f64)width
    let sharp = source.value(14)
    let halo = source.value(15)
    let spread = source.value(16)
    # The inhibitor's spread, and in alpha the developer's: what is released at
    # step s spreads through the steps left, so each step spreads by σ/√W, W
    # the steps left weighed by how much grey releases at each.
    let n = film.chemistry_steps
    let grey = source.value(53)[3]
    var weighed = 0.0
    var before = 0.0
    for step in 1..=n:
        let now = film.progress(source, [grey, grey, grey], (f64)step / (f64)n)
        let mean = (now[0] + now[1] + now[2]) / 3.0
        weighed += (mean - before) * (f64)(n - step + 1)
        before = mean
    let per_step = 1.0 / math.sqrt(math.max(weighed, 1.0e-6))
    var held = blur_of([spread[0] / pitch * per_step, spread[1] / pitch * per_step, spread[2] / pitch * per_step])
    held.alpha = (f32)(source.value(20)[3] / pitch * per_step)
    let keep = source.value(55)[1]
    let copies = source.value(21)[1] / pitch
    return Plan(pitch = (f32)pitch, duplicated = blur_of([copies, copies, copies]),
                scatter = blur_of([sharp[0] / pitch, sharp[1] / pitch, sharp[2] / pitch], true),
                halation_strength = [(f32)halo[0], (f32)halo[1], (f32)halo[2]],
                halation_block = (i32)math.clamp(math.round(halo[3] / 8.0 / pitch), 1.0, 32.0),
                step_spread = held, keep = keep)

## One step's spread of the inhibitor (and, in alpha, the used developer),
## reaching far enough for both.
pub func step_blur(plan: const Plan*) -> Blur:
    let base = plan.step_spread
    var out = blur_of([(f64)base.sigma[0], (f64)base.sigma[1], (f64)base.sigma[2]])
    out.alpha = base.alpha
    out.radius = (i32)math.min(math.max((f64)out.radius, math.ceil(3.0 * (f64)base.alpha)), widest)
    return out

## Whether halation adds anything.
pub func has_halation(blurs: const Plan*) -> bool:
    return blurs.halation_strength[0] > 0.0f32 or blurs.halation_strength[1] > 0.0f32 or blurs.halation_strength[2] > 0.0f32

## The size of the halation's blocks over an image `size` texels long.
pub func blocks(size: usize, block: i32) -> usize:
    return (size + (usize)block - 1) // (usize)block

# mark: Passes ================================================================

## One pass over the rows: its stage, inputs and output, all RGBA half floats.
struct Pass:
    var stage: i64
    var film: const Film*
    var width: usize
    var height: usize
    var first: const f32[]
    var second: const f32[]
    var out: f32[]
    ## Stage 0: the scene, its matrix into AP1, the tables (lens vignetting) and
    ## the output's aspect.
    var source: const Scene*
    var matrix: f64[9]
    var tables: const Tables*
    var aspect: f64
    ## The lens's veiling glare, added to the scene light before exposure.
    var veil: f64
    ## Blurs: the step between taps, and the blur.
    var dx: i64
    var dy: i64
    var blur: Blur
    var weights: f32[3]
    var pitch: f64
    ## Halation: the block size, and the size of `first` when it differs from
    ## the output's (the gather reads blocks; the halo's addition reads them).
    var block: i64
    var first_width: usize
    var first_height: usize
    ## Development's step (stage 8): from and to which share of the way, how
    ## much used developer it leaves unrenewed, and whether it is the first.
    var begun: f64
    var reached: f64
    var keep: f64
    var first_step: bool
    ## How far through the development to show (stage 4; 1 the end).
    var share: f64 = 1.0
    ## The stochastic render (stage 11): samples per pixel, and the grains.
    var samples: usize
    var geometry: film_grains.Geometry[9]
    ## Fewer developed clouds a pixel than this: traced (tests trace all).
    var traced_below: f64 = film_grains.gaussian_from

func texel(image: const f32[], width: usize, height: usize, x: i64, y: i64) -> f64[3]:
    let at = place(width, height, x, y)
    return [(f64)image[at], (f64)image[at + 1], (f64)image[at + 2]]

func alpha(image: const f32[], width: usize, height: usize, x: i64, y: i64) -> f64:
    return (f64)image[place(width, height, x, y) + 3]

## Texel (`x`, `y`)'s first value, held at the edges.
func place(width: usize, height: usize, x: i64, y: i64) -> usize:
    let cx = (usize)(0 if x < 0 else (x if x < (i64)width else (i64)width - 1))
    let cy = (usize)(0 if y < 0 else (y if y < (i64)height else (i64)height - 1))
    return (cy * width + cx) * 4

func blurred(pass: const Pass*, image: const f32[], x: i64, y: i64) -> f64[4]:
    var sum: f64[4] = [0.0, 0.0, 0.0, 0.0]
    var weights: f64[4] = [0.0, 0.0, 0.0, 0.0]
    let r = (i64)pass.blur.radius
    for i in -r..=r:
        let d = (f64)i
        let at = place(pass.width, pass.height, x + pass.dx * i, y + pass.dy * i)
        for k in 0..<(usize)4:
            let sigma = (f64)pass.blur.sigma[k] if k < 3 else (f64)pass.blur.alpha
            var w = 1.0 if i == 0 else 0.0
            if sigma > 1.0e-3:
                w = math.exp(-math.abs(d) / sigma) if pass.blur.exponential and k < 3 else math.exp(-0.5 * d * d / (sigma * sigma))
            sum[k] += w * (f64)image[at + k]
            weights[k] += w
    return [sum[0] / weights[0], sum[1] / weights[1], sum[2] / weights[2], sum[3] / weights[3]]

## `image` (`width` × `height`) at (`x`, `y`) in texels, bilinear between texel
## centres, held at the edges (film_stages.glsl's `bilinear`).
func bilinear(image: const f32[], width: usize, height: usize, x: f64, y: f64) -> f64[3]:
    let bx = math.floor(x)
    let by = math.floor(y)
    let fx = x - bx
    let fy = y - by
    let ix = (i64)bx
    let iy = (i64)by
    let a = texel(image, width, height, ix, iy)
    let c = texel(image, width, height, ix + 1, iy)
    let d = texel(image, width, height, ix, iy + 1)
    let e = texel(image, width, height, ix + 1, iy + 1)
    var out: f64[3]
    for k in 0..<(usize)3:
        out[k] = (a[k] * (1.0 - fx) + c[k] * fx) * (1.0 - fy) + (d[k] * (1.0 - fx) + e[k] * fx) * fy
    return out

## The developed negative at (`x`, `y`) µm: the pixel there, from the exposure
## (`first`) and the inhibitor (`second`).
func developed_at(context: void*, x: f64, y: f64) -> film.Developed:
    let pass = (Pass*)context
    let px = (i64)math.floor(x / pass.pitch)
    let py = (i64)math.floor(y / pass.pitch)
    return film.developed(pass.film, texel(pass.first, pass.width, pass.height, px, py), texel(pass.second, pass.width, pass.height, px, py),
                          alpha(pass.second, pass.width, pass.height, px, py), pass.share)

func run_row(context: void*, row: usize, worker: usize) -> !:
    let pass = (Pass*)context
    let y = (i64)row
    for column in 0..<pass.width:
        let x = (i64)column
        var out: f64[3]
        var spent = 1.0
        if pass.stage == 0:
            let camera = pass.source.value_at(row * pass.width + column)
            var c: f64[3]
            for k in 0..<(usize)3:
                c[k] = math.max(pass.matrix[k * 3] * camera[0] + pass.matrix[k * 3 + 1] * camera[1] + pass.matrix[k * 3 + 2] * camera[2], 0.0)
            let v = pass.tables.value(5)
            if v[1] > 0.0:
                let u = ((f64)column + 0.5) / (f64)pass.width
                let w = ((f64)row + 0.5) / (f64)pass.height
                let px = (u - 0.5) * 2.0 * pass.aspect
                let py = (w - 0.5) * 2.0
                let radius = math.sqrt(px * px + py * py) / math.sqrt(pass.aspect * pass.aspect + 1.0)
                let start = v[2] * 0.6
                let t = math.clamp((radius - start) / (1.0 - start), 0.0, 1.0)
                for k in 0..<(usize)3:
                    c[k] *= 1.0 + v[1] * 2.0 * t * t
            out = film.expose(pass.film, [c[0] + pass.veil, c[1] + pass.veil, c[2] + pass.veil])
        elif pass.stage == 1:
            let blur = blurred(pass, pass.first, x, y)
            out = [blur[0], blur[1], blur[2]]
            spent = blur[3]
        elif pass.stage == 5:
            # Halation, 1: the exposure averaged over blocks.
            out = [0.0, 0.0, 0.0]
            for by in 0..<pass.block:
                for bx in 0..<pass.block:
                    let v = texel(pass.first, pass.first_width, pass.first_height, x * pass.block + bx, y * pass.block + by)
                    for k in 0..<(usize)3:
                        out[k] += v[k]
            let count = (f64)(pass.block * pass.block)
            out = [out[0] / count, out[1] / count, out[2] / count]
        elif pass.stage == 6:
            # 2: gathered at the kernel's samples (µm), at this block size.
            let block = (f64)pass.block * pass.pitch
            out = [0.0, 0.0, 0.0]
            for k in 0..<film_halation.sample_count:
                let offset = pass.film.value(64 + k)
                let v = bilinear(pass.first, pass.width, pass.height, (f64)x + offset[0] / block, (f64)y + offset[1] / block)
                for c in 0..<(usize)3:
                    out[c] += v[c]
            let n = (f64)film_halation.sample_count
            out = [out[0] / n, out[1] / n, out[2] / n]
        elif pass.stage == 7:
            # 3: the halo at full size, at each layer's strength, onto the scattered exposure.
            let scattered = texel(pass.second, pass.width, pass.height, x, y)
            let block = (f64)pass.block
            let halo = bilinear(pass.first, pass.first_width, pass.first_height, ((f64)x + 0.5) / block - 0.5, ((f64)y + 0.5) / block - 0.5)
            for k in 0..<(usize)3:
                out[k] = scattered[k] + (f64)pass.weights[k] * halo[k]
        elif pass.stage == 8:
            # The inhibitor the steps before released, as spread by now (none
            # yet at the first), and this step's release added to it.
            let held = [0.0, 0.0, 0.0] if pass.first_step else texel(pass.second, pass.width, pass.height, x, y)
            let used = 0.0 if pass.first_step else alpha(pass.second, pass.width, pass.height, x, y)
            let stepped = film.release(pass.film, texel(pass.first, pass.width, pass.height, x, y), held, pass.begun, pass.reached, pass.keep)
            out = [held[0] + stepped[0], held[1] + stepped[1], held[2] + stepped[2]]
            spent = used + stepped[3]
        elif pass.stage == 10:
            # The effective log H the film developed at (the stochastic render's).
            let d = film.developed(pass.film, texel(pass.first, pass.width, pass.height, x, y), texel(pass.second, pass.width, pass.height, x, y),
                                   alpha(pass.second, pass.width, pass.height, x, y))
            out = d.effective
        elif pass.stage == 11:
            out = stochastic(pass, column, row)
        else:
            if pass.film.value(6)[3] > 0.0:
                # Grain: the image made of dye clouds, each the negative at its centre.
                let (amounts, unbias) = film.clouded(pass.film, ((f64)column + 0.5) * pass.pitch, ((f64)row + 0.5) * pass.pitch, pass.pitch,
                                                     developed_at, context)
                out = film.finish(pass.film, amounts, unbias)
            else:
                let e = texel(pass.first, pass.width, pass.height, x, y)
                let held = texel(pass.second, pass.width, pass.height, x, y)
                out = film.scan(pass.film, e, held, alpha(pass.second, pass.width, pass.height, x, y), (f64)column + 0.5, (f64)row + 0.5, pass.pitch,
                                share = pass.share)
        let at = (row * pass.width + column) * 4
        pass.out[at] = (f32)out[0]
        pass.out[at + 1] = (f32)out[1]
        pass.out[at + 2] = (f32)out[2]
        pass.out[at + 3] = (f32)spent

## What the film says at a grain's centre (`x`, `y` µm) for layer `layer`
## (film_grains.lucb's `clouds`): its populations' shares developed and the
## clouds' strength at the effective log H there (`first`), the shares as far
## as the development has come (a slide's first developer is what grows).
func grain_place(context: void*, layer: usize, x: f64, y: f64) -> f64[4]:
    let pass = (Pass*)context
    let h = bilinear(pass.first, pass.width, pass.height, x / pass.pitch - 0.5, y / pass.pitch - 0.5)
    var said = pass.film.grain_table(layer, h[layer])
    if pass.share < 1.0:
        let grown = film.progress(pass.film, h, pass.share)[layer]
        let reversal = pass.film.value(17)[3] == 1.0
        for p in 0..<film_grains.populations:
            said[p] = 1.0 - (1.0 - said[p]) * grown if reversal else said[p] * grown
    return said

## Pixel (`column`, `row`) of the stochastic render: `samples` points spread
## over it, each the dye of the grains there scanned to light (a negative's
## transmittance, a slide's light on the lightbox), the light averaged and
## read back as density, less what the grains add on average across channels
## (`Film.grain_bias`); the grain's strength (Grain, 0..2) taken about the
## developed film's own density there.
func stochastic(pass: const Pass*, column: usize, row: usize) -> f64[3]:
    let (mean, read) = stochastic_reading(pass, column, row)
    let strength = pass.film.value(6)[3]
    var d: f64[3]
    for c in 0..<(usize)3:
        d[c] = mean[c] + strength * (read[c] - mean[c])
    return film.finish_density(pass.film, film.reading_of(pass.film, [math.pow(10.0, -d[0]), math.pow(10.0, -d[1]), math.pow(10.0, -d[2])]),
                               [0.0, 0.0, 0.0])

## What the scanner reads at pixel (`column`, `row`), as density (a slide's
## light too): the developed film without grain, and with its grains. Each
## layer either traced grain by grain (few develop in the pixel, or the pixel
## is not much wider than a grain): its samples' dye read through the scan's
## slopes about the developed film's reading, to light, averaged, back to
## density, less the traced grains' average (`Film.grain_bias`); or taken from
## its distribution over the pixel (film_grains.lucb): the granularity scaled
## to the pixel's area, by the pixel's own deviate, the mean light kept.
func stochastic_reading(pass: const Pass*, column: usize, row: usize) -> (f64[3], f64[3]):
    let source = pass.film
    let effective = texel(pass.first, pass.width, pass.height, (i64)column, (i64)row)
    let developed = film.developed_amounts(source, effective, pass.share)
    let mean = source.density_read(developed)
    let slopes = source.scan_slopes(developed)
    let base = source.value(338)
    let layers = (usize)base[3]
    var (traced, bounds) = regimes(pass, column, row, effective, layers)
    var light: f64[3] = [1.0, 1.0, 1.0]
    var gathered: film_grains.Cloud[128]
    var count: usize = 0
    if traced[0] or traced[1] or traced[2]:
        # The grains reaching the pixel, once; then its samples among them.
        let left = (f64)column * pass.pitch
        let top = (f64)row * pass.pitch
        count = film_grains.gather(pass.geometry, layers, left, top, left + pass.pitch, top + pass.pitch, traced, bounds, grain_place,
                                   (void*)pass, gathered)
        if count > film_grains.cloud_most:
            # Too many to trace: drawn from their distribution after all.
            traced = [false, false, false]
    if traced[0] or traced[1] or traced[2]:
        light = [0.0, 0.0, 0.0]
        for k in 0..<pass.samples:
            let (ox, oy) = film_grains.sample_place((u32)column, (u32)row, (u32)k)
            let x = ((f64)column + ox) * pass.pitch
            let y = ((f64)row + oy) * pass.pitch
            let clouds = film_grains.dye_at(gathered, count, x, y)
            # Light over the developed film's (near 1).
            for c in 0..<(usize)3:
                var d = 0.0
                for layer in 0..<(usize)3:
                    let source_layer = 0 if layers == 1 else layer
                    if traced[source_layer]:
                        d += slopes[layer * 3 + c] * (base[layer] + clouds[source_layer] - developed[layer])
                # Within four decades of it (the scan's slopes are a line; far
                # from the film's reading they would run away).
                light[c] += math.pow(10.0, -math.clamp(d, -4.0, 4.0)) / (f64)pass.samples
    let bias = source.grain_bias(effective, slopes, traced)
    let spread = drawn_grain(pass, column, row, effective, slopes, traced, layers)
    var read: f64[3]
    for c in 0..<(usize)3:
        read[c] = mean[c] - math.log10(math.max(light[c], 1.0e-30)) - bias[c] + spread[c]
    return (mean, read)

## Which of pixel (`column`, `row`)'s layers are traced grain by grain (few
## develop in it), and for
## them each population's most share developed within reach of the pixel (the
## rank bins made: film_grains.lucb's `clouds`).
func regimes(pass: const Pass*, column: usize, row: usize, effective: f64[3], layers: usize) -> (bool[3], f64[9]):
    let source = pass.film
    var traced: bool[3] = [false, false, false]
    var bounds: f64[9]
    for k in 0..<(usize)9:
        bounds[k] = 0.0
    let area = pass.pitch * pass.pitch
    for layer in 0..<layers:
        var largest = 0.0
        var developed = 0.0
        let table = source.grain_table(layer, effective[layer])
        for p in 0..<film_grains.populations:
            let g = pass.geometry[layer * 3 + p]
            largest = math.max(largest, g.radius)
            developed += g.density * table[p] * area
        let reach = film_grains.cell_radii * film_grains.size_high * largest
        traced[layer] = developed < pass.traced_below
        if not traced[layer]:
            continue
        # The effective log H over the pixels a grain reaching this one sits in.
        let around = (i64)math.min(math.ceil(reach / pass.pitch) + 1.0, 4.0)
        var low = effective[layer]
        var high = effective[layer]
        for dy in -around..=around:
            for dx in -around..=around:
                let h = texel(pass.first, pass.width, pass.height, (i64)column + dx, (i64)row + dy)[layer]
                low = math.min(low, h)
                high = math.max(high, h)
        let most = source.share_bound(layer, low, high)
        for p in 0..<film_grains.populations:
            bounds[layer * 3 + p] = most[p]
    return (traced, bounds)

## The grain of the layers not traced, as density per channel: each layer's
## rms over the pixel (the granularity through 48 µm scaled to the pixel's
## area, Selwyn, times how much of the clouds' spread a pixel this wide
## averages: film_grains.lucb's `pixel_covariance`), by the pixel's deviate
## for the layer (tied to its neighbours' as clouds across its border tie
## them), through the scan's slopes; plus what keeps the mean light (a
## Gaussian density spread adds ln 10 · σ² / 2 to the mean density of the
## light it passes).
func drawn_grain(pass: const Pass*, column: usize, row: usize, effective: f64[3], slopes: f64[9], traced: bool[3], layers: usize) -> f64[3]:
    let scale = math.sqrt(film_grains.aperture_area / (pass.pitch * pass.pitch))
    var out: f64[3] = [0.0, 0.0, 0.0]
    var variance: f64[3] = [0.0, 0.0, 0.0]
    for layer in 0..<layers:
        if traced[layer]:
            continue
        # The clouds' radius as the variance weighs them.
        let table = pass.film.grain_table(layer, effective[layer])
        var second = 0.0
        var fourth = 0.0
        for p in 0..<film_grains.populations:
            let g = pass.geometry[layer * 3 + p]
            let lambda = g.density * table[p]
            second += lambda * g.radius * g.radius
            fourth += lambda * g.radius * g.radius * g.radius * g.radius
        let radius = math.sqrt(fourth / math.max(second, 1.0e-12))
        let shares = film_grains.pixel_covariance(pass.pitch / math.max(radius, 1.0e-6))
        var sigma = pass.film.grain_granularity(layer, effective[layer]) * scale * math.sqrt(shares[0])
        if pass.share < 1.0:
            sigma *= math.sqrt(film.progress(pass.film, effective, pass.share)[layer])
        let z = film_grains.pixel_deviate((u32)column, (u32)row, (u32)layer, shares)
        for c in 0..<(usize)3:
            let factor = slopes[c] + slopes[3 + c] + slopes[6 + c] if layers == 1 else slopes[layer * 3 + c]
            out[c] += factor * sigma * z
            variance[c] += factor * factor * sigma * sigma
    for c in 0..<(usize)3:
        out[c] += 0.5 * 2.302585092994046 * variance[c]
    return out

## `source` (camera values) through the film: the filmed scene, scene light in
## AP1 at the same size, which the caller closes. `matrix` takes the scene into
## AP1 (the develop's white balance and exposure); `tables` and `aspect` (the
## scene's) give the lens vignetting, done here on the negative.
## With `samples` (and the film's grain on), the stochastic render, that many
## samples a pixel, its grains fitted first (`Film.fit_grains`).
pub func filmed(source: Film*, scene: const Scene*, matrix: f64[9], tables: const Tables*, aspect: f64, veil: f64 = 0.0,
                samples: usize = 0) -> Scene!:
    let width = (usize)scene.width()
    let height = (usize)scene.height()
    let size = width * height * 4
    let plan = plan_for(source, width)
    let exposed = try new f32[size] --- in memory.heap
    defer free(exposed) in memory.heap
    let one = try new f32[size] --- in memory.heap
    defer free(one) in memory.heap
    let two = try new f32[size] --- in memory.heap
    defer free(two) in memory.heap
    let out = try new f32[size] --- in memory.heap
    errdefer free(out) in memory.heap
    var pass = Pass(stage = 0, film = source, width = width, height = height, first = exposed, second = exposed, out = exposed,
                    source = scene, matrix = matrix, tables = tables, aspect = aspect, veil = veil, pitch = (f64)plan.pitch)
    try parallel.for_each(height, (void*)&pass, run_row)
    # Scatter, across then down: exposed → one → two.
    try run_blur(&pass, exposed, exposed, one, 1, 1, 0, plan.scatter)
    try run_blur(&pass, one, one, two, 1, 0, 1, plan.scatter)
    # Halation: blocks of the exposure, gathered, added back onto the scatter.
    if has_halation(&plan):
        let block = (i64)plan.halation_block
        let low_width = blocks(width, plan.halation_block)
        let low_height = blocks(height, plan.halation_block)
        let low = try new f32[low_width * low_height * 4] --- in memory.heap
        defer free(low) in memory.heap
        let gathered = try new f32[low_width * low_height * 4] --- in memory.heap
        defer free(gathered) in memory.heap
        pass.block = block
        pass.first_width = width
        pass.first_height = height
        try run_sized(&pass, exposed, exposed, low, 5, low_width, low_height)
        try run_sized(&pass, low, low, gathered, 6, low_width, low_height)
        pass.first_width = low_width
        pass.first_height = low_height
        pass.weights = plan.halation_strength
        try run_sized(&pass, gathered, two, exposed, 7, width, height)
    else:
        memory.copy(exposed, two, size)
    # Development, step by step: the field in `one`, each step's release added
    # into `out`, diffused across into `two` and down into `one` again.
    try develop_steps(&pass, exposed, one, two, out, &plan)
    if samples > 0 and source.value(6)[3] > 0.0:
        try source.fit_grains()
        pass.geometry = source.grain_geometry()
        pass.samples = samples
        # The effective log H into `two`, then the grains' light.
        pass.stage = 10
        pass.first = exposed
        pass.second = one
        pass.out = two
        try parallel.for_each(height, (void*)&pass, run_row)
        pass.stage = 11
        pass.first = two
        pass.out = out
        try parallel.for_each(height, (void*)&pass, run_row)
    else:
        pass.stage = 4
        pass.first = exposed
        pass.second = one
        pass.out = out
        try parallel.for_each(height, (void*)&pass, run_row)
    # The duplicates between negative and print soften the developed image.
    if plan.duplicated.radius > 0:
        try run_blur(&pass, out, out, one, 1, 1, 0, plan.duplicated)
        try run_blur(&pass, one, one, out, 1, 0, 1, plan.duplicated)
    let pixels = try new f16[size] --- in memory.heap
    for at in 0..<size:
        pixels[at] = (f16)out[at]
    free(out) in memory.heap
    return Scene.from_pixels(width, height, pixels)

## Development's steps on the exposure `exposed`: each step's release added
## to `field` (into `scratch`), then the whole field diffused one step, across
## into `spare` and down into `field`, which ends holding the inhibitor and
## used developer.
func develop_steps(pass: Pass*, exposed: const f32[], field: f32[], spare: f32[], scratch: f32[], plan: const Plan*) -> !:
    let n = film.chemistry_steps
    let spread = step_blur(plan)
    for step in 1..=n:
        pass.stage = 8
        pass.first = exposed
        pass.second = field
        pass.out = scratch
        pass.first_step = step == 1
        pass.begun = (f64)(step - 1) / (f64)n
        pass.reached = (f64)step / (f64)n
        pass.keep = math.pow(plan.keep, (f64)(n - step))
        try parallel.for_each(pass.height, (void*)pass, run_row)
        try run_blur(pass, scratch, scratch, spare, 1, 1, 0, spread)
        try run_blur(pass, spare, spare, field, 1, 0, 1, spread)

## Stage `stage` into `out` of `width` × `height` (the halation's sizes), the
## pass's size put back after.
func run_sized(pass: Pass*, first: const f32[], second: const f32[], out: f32[], stage: i64, width: usize, height: usize) -> !:
    let full_width = pass.width
    let full_height = pass.height
    pass.stage = stage
    pass.first = first
    pass.second = second
    pass.out = out
    pass.width = width
    pass.height = height
    defer:
        pass.width = full_width
        pass.height = full_height
    try parallel.for_each(height, (void*)pass, run_row)

func run_blur(pass: Pass*, first: const f32[], second: const f32[], out: f32[], stage: i64, dx: i64, dy: i64, blur: Blur) -> !:
    pass.stage = stage
    pass.first = first
    pass.second = second
    pass.out = out
    pass.dx = dx
    pass.dy = dy
    pass.blur = blur
    try parallel.for_each(pass.height, (void*)pass, run_row)

# mark: Tests =================================================================

## A scene `width` × `height` of `left` light left of `split` columns and
## `right` light after (AP1, as film's input); the caller closes it.
func two_halves(width: usize, height: usize, split: usize, left: f64, right: f64) -> Scene!:
    let pixels = try new f16[width * height * 4] --- in memory.heap
    for y in 0..<height:
        for x in 0..<width:
            let v = left if x < split else right
            let at = (y * width + x) * 4
            pixels[at] = (f16)v
            pixels[at + 1] = (f16)v
            pixels[at + 2] = (f16)v
            pixels[at + 3] = (f16)1.0
    return Scene.from_pixels(width, height, pixels)

func film_for(text: str) -> Film!:
    var made = Film()
    var settings = settings_text(text)
    try made.prepare(&settings)
    return made

## Develop `scene` through `source` with no matrix (the scene is AP1 already).
func developed_scene(source: Film*, scene: const Scene*) -> Scene!:
    let identity: f64[9] = [1.0, 0.0, 0.0, 0.0, 1.0, 0.0, 0.0, 0.0, 1.0]
    var settings = settings_text("")
    let built = build_tables(&settings)
    return try filmed(source, scene, identity, &built, 1.0)

test "a large even patch developed in steps is the published curve's":
    var negative = film_for("film_stock=Kodak Vision 500T 5279;film_grain=0") catch failure:
        assert(false)
        return
    defer negative.release()
    var scene = two_halves(96, 64, 96, 0.18, 0.18) catch failure:
        assert(false)
        return
    defer scene.close()
    var out = developed_scene(&negative, &scene) catch failure:
        assert(false)
        return
    defer out.close()
    let middle = out.value_at(32 * 96 + 48)
    let even = film.develop(&negative, [0.18, 0.18, 0.18], 0.5, 0.5, 20.0)
    for k in 0..<(usize)3:
        assert(math.abs(middle[k] / even[k] - 1.0) < 0.01)

test "stand development draws stronger edges than continuous agitation":
    # Tri-X in D-76, a dense half beside a thin one: the dense side's border
    # lacks developer the thin side does not use, the thin side's border has
    # its neighbor's to spare (Eberhard, Kostinsky). Measured as the step's
    # overshoot on the scanned positive.
    var overshoot: f64[2]
    let texts: str[2] = ["film_stock=Kodak Tri-X 400;film_grain=0;develop_process=D-76;develop_agitation=Continuous",
                         "film_stock=Kodak Tri-X 400;film_grain=0;develop_process=D-76;develop_agitation=Stand"]
    for (index, text) in texts.indexed():
        var tri_x = film_for(text) catch failure:
            assert(false)
            return
        defer tri_x.release()
        # 4096 pixels across the 35 mm frame: about 5 µm each, finer than the
        # developer's spread.
        var scene = two_halves(4096, 4, 2048, 0.03, 0.6) catch failure:
            assert(false)
            return
        defer scene.close()
        var out = developed_scene(&tri_x, &scene) catch failure:
            assert(false)
            return
        defer out.close()
        let far = out.value_at(2 * 4096 + 3800)[1]
        let near = out.value_at(2 * 4096 + 2052)[1]
        overshoot[index] = near / far
        print(f"agitation {index}: border over far {overshoot[index]} edge {tri_x.value(20)[2]} width {tri_x.value(20)[3]} kept {tri_x.value(54)[3]} renewal {tri_x.value(54)[2]}")
    assert(overshoot[1] > overshoot[0])

## Developed negative density (over a constant) of filmed scene light `v`
## through `source`'s scan, in its green channel: the scan read density back
## to light as 0.18 · 10^((d − grey) · g); this undoes it.
func density_of(source: const Film*, v: f64) -> f64:
    return math.log10(math.max(v, 1.0e-9) / 0.18) / source.value(8)[1]

test "a colour negative's edges overshoot, fading within a few tens of µm":
    # Portra 400 in C-41 (its standard machine agitation), no halation (its
    # glow is not chemistry), 4096 pixels across 35 mm (about 6 µm each): the
    # green record's overshoot on the dense side of a step, as a share of the
    # step, and how far it takes to fall to 1/e. The model is fitted to
    # Portra 400's MTF (1.11 near 12 cycles/mm); one MTF ordinate does not fix
    # a step's overshoot (many spatial responses share it), so its size here is
    # the model's prediction, bounded loosely. The e-folding is checked against
    # Nelson's chemical spread fitted to Kodak Gold (Rajkowski and Nowak,
    # Optica Applicata 1999: 10^(−2|x|/Kc), Kc 90 µm, an e-folding of 19.5 µm).
    # Their 6.24 % (Gold 100) and 5.28 % (Gold 200) are the chemical spread's
    # weight in their combined spread function, not an edge's overshoot, so
    # they are not compared with this (docs/PHYSICAL-FILM.md, part 4).
    var portra = film_for("film_stock=Kodak Portra 400;film_grain=0;film_halation=0") catch failure:
        assert(false)
        return
    defer portra.release()
    var scene = two_halves(4096, 4, 2048, 0.03, 0.6) catch failure:
        assert(false)
        return
    defer scene.close()
    var out = developed_scene(&portra, &scene) catch failure:
        assert(false)
        return
    defer out.close()
    let pitch = portra.value(6)[2] * 2.0 / 4096.0
    let far_dense = density_of(&portra, out.value_at(2 * 4096 + 3900)[1])
    let far_thin = density_of(&portra, out.value_at(2 * 4096 + 200)[1])
    let step = far_dense - far_thin
    var peak = 0.0
    var peak_at: usize = 0
    for column in 2048..<(usize)2300:
        let over = density_of(&portra, out.value_at(2 * 4096 + column)[1]) - far_dense
        if over > peak:
            peak = over
            peak_at = column
    var folded = peak_at
    while folded < 3800 and density_of(&portra, out.value_at(2 * 4096 + folded)[1]) - far_dense > peak / math.e:
        folded += 1
    let share = peak / step
    let reach = (f64)(folded - peak_at) * pitch
    print(f"Portra 400 edge: overshoot {peak} of a {step} step ({share * 100.0} %), e-folding {reach} µm")
    assert(share > 0.05 and share < 0.2)
    assert(reach > 10.0 and reach < 40.0)

test "agitation changes edges, not contrast":
    # Far from any edge the negative is the published curve whatever the
    # agitation: a large even patch's density, continuous against stand. This
    # is a calibrated correction, not a prediction: the developer here is not
    # yet a conserved field with the bath's flux at its surface, and stretching
    # the edges' strength over even areas moved a dense patch 1.6 D (stand
    # against continuous), far more than real; docs/PHYSICAL-FILM.md, part 4.
    var reads: f64[2]
    let texts: str[2] = ["film_stock=Kodak Tri-X 400;film_grain=0;develop_process=D-76;develop_agitation=Continuous",
                         "film_stock=Kodak Tri-X 400;film_grain=0;develop_process=D-76;develop_agitation=Stand"]
    for (index, text) in texts.indexed():
        var tri_x = film_for(text) catch failure:
            assert(false)
            return
        defer tri_x.release()
        var scene = two_halves(256, 8, 256, 0.4, 0.4) catch failure:
            assert(false)
            return
        defer scene.close()
        var out = developed_scene(&tri_x, &scene) catch failure:
            assert(false)
            return
        defer out.close()
        reads[index] = out.value_at(4 * 256 + 128)[1]
    assert(math.abs(reads[1] / reads[0] - 1.0) < 0.01)

test "part of the way through, a negative is thinner":
    var negative = film_for("film_stock=Kodak Vision 500T 5279;film_grain=0") catch failure:
        assert(false)
        return
    defer negative.release()
    let e = film.expose(&negative, [0.36, 0.36, 0.36])
    let (held, spent) = film.even_field(&negative, e)
    let half = film.developed(&negative, e, held, spent, 0.5)
    let whole = film.developed(&negative, e, held, spent, 1.0)
    for k in 0..<(usize)3:
        assert(half.amounts[k] < whole.amounts[k])

## Where a large grey patch develops: each layer's effective log H (held back
## by its own inhibitor, as film.lucb's `develop` has it).
func even_effective(source: const Film*, light: f64 = 0.18) -> f64[3]:
    let e = film.expose(source, [light, light, light])
    let (held, missing) = film.even_field(source, e)
    return film.developed(source, e, held, missing).effective

## A patch of `size` × `size` pixels of `pitch` µm, developed evenly at grey
## (its effective log H the stock's grey), read by the stochastic render with
## `samples` a pixel, per channel in density (a slide's light as density too):
## the readings' mean light, the grainless reading, and the readings' rms.
func even_reading(source: Film*, size: usize, pitch: f64, samples: usize, level: f64 = 0.18) -> (f64[3], f64[3], f64[3])!:
    try source.fit_grains()
    let field = try new f32[size * size * 4] --- in memory.heap
    defer free(field) in memory.heap
    let grey = even_effective(source, level)
    for at in 0..<size * size:
        for k in 0..<(usize)3:
            field[at * 4 + k] = (f32)grey[k]
        field[at * 4 + 3] = (f32)1.0
    var nothing = Scene()
    var settings = settings_text("")
    let built = build_tables(&settings)
    var pass = Pass(stage = 11, film = source, width = size, height = size, first = field, second = field, out = field,
                    source = &nothing, tables = &built, pitch = pitch, samples = samples, geometry = source.grain_geometry())
    var light: f64[3] = [0.0, 0.0, 0.0]
    var sum: f64[3] = [0.0, 0.0, 0.0]
    var squares: f64[3] = [0.0, 0.0, 0.0]
    var flat: f64[3] = [0.0, 0.0, 0.0]
    for row in 0..<size:
        for column in 0..<size:
            let (mean, read) = stochastic_reading(&pass, column, row)
            for c in 0..<(usize)3:
                flat[c] = mean[c]
                light[c] += math.pow(10.0, -read[c])
                sum[c] += read[c]
                squares[c] += read[c] * read[c]
    let n = (f64)(size * size)
    var read: f64[3]
    var rms: f64[3]
    var grainless: f64[3]
    for c in 0..<(usize)3:
        read[c] = -math.log10(light[c] / n)
        grainless[c] = flat[c]
        let average = sum[c] / n
        rms[c] = math.sqrt(math.max(squares[c] / n - average * average, 0.0))
    return (read, grainless, rms)

test "the stochastic render reads grey as the curve and the stock's granularity":
    # At grey, pixels 8 µm: the mean light reads as the developed curve's
    # density in every channel; the pixels' rms, scaled to a 48 µm aperture
    # (Selwyn: σ·√area), as the granularity the stock publishes there. A color
    # negative (5279), a slide (Velvia 50) and black and white (Tri-X).
    let stocks: str[3] = ["film_stock=Kodak Vision 500T 5279", "film_stock=Fujifilm Velvia 50", "film_stock=Kodak Tri-X 400"]
    for text in stocks:
        var negative = film_for(text) catch failure:
            assert(false)
            return
        defer negative.release()
        let pitch = 8.0
        let (read, flat, rms) = even_reading(&negative, 40, pitch, 64) catch failure:
            assert(false)
            return
        let monochrome = negative.value(17)[3] == 2.0
        for c in 0..<(usize)3:
            let layer = 0 if monochrome else c
            let wanted = negative.granularity_at(layer, even_effective(&negative)[layer])
            let scaled = rms[c] * math.sqrt(pitch * pitch / film_grains.aperture_area)
            print(f"{text} channel {c}: read {read[c]} flat {flat[c]} as 48 µm {scaled} wanted {wanted}")
            assert(math.abs(read[c] - flat[c]) < 0.015)



## A grey patch at full-resolution pixels (`pitch` µm), its green readings
## (Tri-X: one silver layer), traced or drawn: their variance and the
## correlation of each pixel with the one beside it.
func patch_statistics(source: Film*, size: usize, pitch: f64, samples: usize, traced_below: f64, level: f64) -> (f64, f64)!:
    try source.fit_grains()
    let field = try new f32[size * size * 4] --- in memory.heap
    defer free(field) in memory.heap
    let grey = even_effective(source, level)
    for at in 0..<size * size:
        for k in 0..<(usize)3:
            field[at * 4 + k] = (f32)grey[k]
        field[at * 4 + 3] = (f32)1.0
    var nothing = Scene()
    var settings = settings_text("")
    let built = build_tables(&settings)
    var pass = Pass(stage = 11, film = source, width = size, height = size, first = field, second = field, out = field, source = &nothing,
                    tables = &built, pitch = pitch, samples = samples, geometry = source.grain_geometry(), traced_below = traced_below)
    let reads = try new f64[size * size] --- in memory.heap
    defer free(reads) in memory.heap
    var sum = 0.0
    for row in 0..<size:
        for column in 0..<size:
            let (_, read) = stochastic_reading(&pass, column, row)
            reads[row * size + column] = read[1]
            sum += read[1]
    let mean = sum / (f64)(size * size)
    var variance = 0.0
    var beside = 0.0
    for row in 0..<size:
        for column in 0..<size:
            let d = reads[row * size + column] - mean
            variance += d * d
            if column + 1 < size:
                beside += d * (reads[row * size + column + 1] - mean)
    variance /= (f64)(size * size)
    beside /= (f64)(size * (size - 1))
    return (variance, beside / variance)

## The light (relative, 0.18 grey) that develops layer `layer` of `source` to
## `net` dye over its unexposed film's.
func light_for(source: const Film*, layer: usize, net: f64) -> f64:
    let floor = source.curve_amount(layer, -4.5)
    var low = 0.0005
    var high = 50.0
    for _ in 0..<50:
        let middle = math.sqrt(low * high)
        let dye = source.curve_amount(layer, even_effective(source, middle)[layer]) - floor
        if dye < net:
            low = middle
        else:
            high = middle
    return math.sqrt(low * high)

test "Portra 160, 400 and 800 grain in Kodak's order, rendered":
    # Kodak gives their rms granularity at a net density of 1.0 (8, 9 and
    # 10.5); the stochastic render of a patch developed there (10 µm pixels)
    # keeps that order in each channel.
    var rms: f64[9]
    let stocks: str[3] = ["film_stock=Kodak Portra 160", "film_stock=Kodak Portra 400", "film_stock=Kodak Portra 800"]
    for (index, text) in stocks.indexed():
        var portra = film_for(text) catch failure:
            assert(false)
            return
        defer portra.release()
        let (_, _, spread) = even_reading(&portra, 24, 10.0, 64, light_for(&portra, 1, 1.0)) catch failure:
            assert(false)
            return
        for c in 0..<(usize)3:
            rms[index * 3 + c] = spread[c]
    print(f"Portra 160 / 400 / 800 green rms at net density 1.0, 10 µm: {rms[1]} {rms[4]} {rms[7]}")
    for c in 0..<(usize)3:
        assert(rms[c] < rms[3 + c] and rms[3 + c] < rms[6 + c])

test "drawn pixels have the traced grains' variance and neighbours' correlation":
    # Tri-X at 4.4 µm pixels (a 45-megapixel scan of 35 mm), in its toe where a
    # pixel holds tens of developed grains: every grain traced (512 samples a
    # pixel) against the pixels drawn from their distribution.
    var tri_x = film_for("film_stock=Kodak Tri-X 400") catch failure:
        assert(false)
        return
    defer tri_x.release()
    let (traced_variance, traced_beside) = patch_statistics(&tri_x, 48, 4.4, 512, 1.0e9, 0.012) catch failure:
        assert(false)
        return
    let (drawn_variance, drawn_beside) = patch_statistics(&tri_x, 48, 4.4, 1, 0.0, 0.012) catch failure:
        assert(false)
        return
    print(f"traced rms {math.sqrt(traced_variance)} beside {traced_beside}; drawn rms {math.sqrt(drawn_variance)} beside {drawn_beside}")
    assert(math.abs(math.sqrt(drawn_variance / traced_variance) - 1.0) < 0.12)
    assert(math.abs(drawn_beside - traced_beside) < 0.08)