Luce packages
LuceLuce BaseLuciaOS

dymokomi/luce-gpu

Source of release 0.5.2

0.5.2 / tests / gpu / compute.lucb

import c
from luce_gpu import gpu
from luce_window import window
import memory
import thread
import kernels

## Compute contracts on a device: kernels from embedded GLSL, chained dispatches
## that read what earlier ones wrote, atomics, indirect dispatch, copies, fills,
## readback, large buffers, and resources destroyed while work still uses them.
pub func checks(device: gpu.Device) -> !:
    let limits = try device.limits()
    assert(limits.buffer_bytes >= 134217728 and limits.group_threads >= 256 and limits.shared_bytes >= 16384)
    try saxpy(device)
    try reduction(device)
    try compaction(device)
    try transfers(device)
    try large(device, limits)
    try images(device)
    try float_atomics(device, limits)
    try ieee(device)
    try specialization(device)
    try background(device)
    try subgroups(device, limits)
    try timing(device, limits)
    try frame_timing(device, limits)
    try addresses(device, limits)
    try tables(device, limits)
    try refusals(device)

func kernel(device: gpu.Device, words: const u32[], msl: c.str, group: const u32[], bindings: const u8[]) -> gpu.Kernel!:
    return try gpu.Kernel.create(device, words, msl, group, bindings)

func word_bytes(values: const u32[]) -> u8[]!:
    let bytes = try new u8[values.length * 4] in memory.heap
    for index in 0..<values.length:
        memory.write[u32]((void*)&bytes[index * 4], values[index])
    return bytes

func word(bytes: const u8[], index: usize) -> u32:
    return memory.read[u32]((const void*)&bytes[index * 4])

func float_at(bytes: const u8[], index: usize) -> f32:
    return memory.read[f32]((const void*)&bytes[index * 4])

## y = 2x + y over 1000 floats, polled to completion.
func saxpy(device: gpu.Device) -> !:
    var program = try kernel(device, kernels.saxpy_comp_words, kernels.saxpy_comp_msl, kernels.saxpy_comp_group, kernels.saxpy_comp_bindings)
    defer program.destroy()
    let group = try program.group()
    assert(group[0] == 64 and group[1] == 1 and group[2] == 1)
    let count: usize = 1000
    var x_bytes: u8[4000]
    var y_bytes: u8[4000]
    for index in 0..<count:
        memory.write[f32]((void*)&x_bytes[index * 4], (f32)index)
        memory.write[f32]((void*)&y_bytes[index * 4], 1.0)
    var x = try gpu.Buffer.create(device, x_bytes)
    defer x.destroy()
    var y = try gpu.Buffer.create(device, y_bytes)
    defer y.destroy()
    var uniforms: u8[8]
    memory.write[f32]((void*)&uniforms[0], 2.0)
    memory.write[u32]((void*)&uniforms[4], (u32)count)
    var pass = try gpu.Compute.begin(device)
    defer pass.close()
    let bindings: gpu.Binding[2] = [gpu.Binding(buffer = x), gpu.Binding(buffer = y)]
    try pass.dispatch(program, bindings, uniforms, 16)
    try pass.submit()
    var polls: usize = 0
    while not (try pass.done()):
        polls += 1
        assert(polls < 100000000)
    try pass.wait()
    var result: u8[4000]
    try y.read(0, result)
    for index in 0..<count:
        assert(float_at(result, index) == 2.0 * (f32)index + 1.0)

## Twelve dependent dispatches halve 4096 values into their sum. The kernel
## and the values' handle are destroyed before the work is submitted.
func reduction(device: gpu.Device) -> !:
    var program = try kernel(device, kernels.reduce_comp_words, kernels.reduce_comp_msl, kernels.reduce_comp_group, kernels.reduce_comp_bindings)
    let count: usize = 4096
    var values = try new u32[count] in memory.heap
    defer free(values) in memory.heap
    for index in 0..<count:
        values[index] = (u32)index + 1
    let bytes = try word_bytes(values)
    defer free(bytes) in memory.heap
    var data = try gpu.Buffer.create(device, bytes)
    var total = try gpu.Buffer.allocate(device, 4)
    defer total.destroy()
    var pass = try gpu.Compute.begin(device)
    defer pass.close()
    let bindings: gpu.Binding[1] = [gpu.Binding(buffer = data)]
    var half = count // 2
    while half > 0:
        var uniforms: u8[4]
        memory.write[u32]((void*)&uniforms[0], (u32)half)
        try pass.dispatch(program, bindings, uniforms, (u32)((half + 63) // 64))
        half = half // 2
    try pass.copy(data, 0, total, 0, 4)
    program.destroy()
    data.destroy()
    try pass.submit()
    try pass.wait()
    var result: u8[4]
    try total.read(0, result)
    assert(word(result, 0) == 8390656)

## Compaction with atomics feeds dispatch_indirect: the odd values of 0..999
## are kept, a kernel turns their count into workgroup counts, and an indirect
## dispatch doubles exactly the kept ones.
func compaction(device: gpu.Device) -> !:
    var compact = try kernel(device, kernels.compact_comp_words, kernels.compact_comp_msl, kernels.compact_comp_group, kernels.compact_comp_bindings)
    defer compact.destroy()
    var arguments = try kernel(device, kernels.arguments_comp_words, kernels.arguments_comp_msl, kernels.arguments_comp_group, kernels.arguments_comp_bindings)
    defer arguments.destroy()
    var doubled = try kernel(device, kernels.double_comp_words, kernels.double_comp_msl, kernels.double_comp_group, kernels.double_comp_bindings)
    defer doubled.destroy()
    let count: usize = 1000
    var values = try new u32[count] in memory.heap
    defer free(values) in memory.heap
    for index in 0..<count:
        values[index] = (u32)index
    let bytes = try word_bytes(values)
    defer free(bytes) in memory.heap
    var input = try gpu.Buffer.create(device, bytes)
    defer input.destroy()
    var kept = try gpu.Buffer.allocate(device, count * 4)
    defer kept.destroy()
    var counters = try gpu.Buffer.allocate(device, 20)
    defer counters.destroy()
    var groups = try gpu.Buffer.allocate(device, 16)
    defer groups.destroy()
    var pass = try gpu.Compute.begin(device)
    defer pass.close()
    # smallest starts at i32 max (a word fill), largest at zero (a byte fill).
    try pass.fill(counters, 0, 20, 0)
    try pass.fill(counters, 4, 4, 0x7fffffff)
    var uniforms: u8[4]
    memory.write[u32]((void*)&uniforms[0], (u32)count)
    let compact_bindings: gpu.Binding[3] = [gpu.Binding(buffer = input), gpu.Binding(buffer = kept), gpu.Binding(buffer = counters)]
    try pass.dispatch(compact, compact_bindings, uniforms, 16)
    let argument_bindings: gpu.Binding[2] = [gpu.Binding(buffer = counters), gpu.Binding(buffer = groups)]
    var none_given: u8[]
    try pass.dispatch(arguments, argument_bindings, none_given, 1)
    let double_bindings: gpu.Binding[2] = [gpu.Binding(buffer = kept), gpu.Binding(buffer = counters)]
    try pass.dispatch_indirect(doubled, double_bindings, none_given, groups, 0)
    try pass.submit()
    try pass.wait()
    var counted: u8[20]
    try counters.read(0, counted)
    assert(word(counted, 0) == 500)
    assert(word(counted, 1) == 1 and word(counted, 2) == 999)
    assert(word(counted, 3) % 2 == 1)
    assert(word(counted, 4) >= 1 and word(counted, 4) <= 1000)
    var arguments_read: u8[12]
    try groups.read(0, arguments_read)
    assert(word(arguments_read, 0) == 8 and word(arguments_read, 1) == 1 and word(arguments_read, 2) == 1)
    var results: u8[2000]
    try kept.read(0, results)
    var sum: u64 = 0
    var seen: bool[1000]
    for index in 0..<(usize)500:
        let value = word(results, index)
        assert(value % 4 == 2 and value < 2000 and not seen[value // 2])
        seen[value // 2] = true
        sum += (u64)value
    assert(sum == 500000)

## Allocation zeroes; fills by word and by byte; buffer-to-buffer copies; a
## shared buffer's CPU view; and reads at an offset.
func transfers(device: gpu.Device) -> !:
    let size: usize = 1 << 20
    var first = try gpu.Buffer.allocate(device, size)
    defer first.destroy()
    assert(first.bytes() == size and (try first.memory_kind()) == gpu.Memory.device)
    var second = try gpu.Buffer.allocate(device, size)
    defer second.destroy()
    var shared = try gpu.Buffer.allocate(device, 64, gpu.Memory.shared)
    defer shared.destroy()
    var everything = try new u8[size] in memory.heap
    defer free(everything) in memory.heap
    try first.read(0, everything)
    for byte in everything:
        assert(byte == 0)
    let view = try shared.view()
    assert(view.length == 64)
    for index in 0..<(usize)16:
        assert(word(view, index) == 0)
        memory.write[u32]((void*)&view[index * 4], (u32)index * 3)
    var pass = try gpu.Compute.begin(device)
    defer pass.close()
    try pass.fill(first, 0, size, 0xdeadbeef)
    try pass.fill(first, 4096, 4096, 0x01010101)
    try pass.copy(first, 0, second, 8, 8192)
    try pass.copy(shared, 0, second, 65536, 64)
    try pass.fill(shared, 0, 16, 0xffffffff)
    try pass.submit()
    try pass.wait()
    var back: u8[16]
    try first.read(4092, back)
    assert(word(back, 0) == 0xdeadbeef and word(back, 1) == 0x01010101)
    try first.read(8192, back)
    assert(word(back, 0) == 0xdeadbeef)
    try second.read(0, back)
    assert(word(back, 0) == 0 and word(back, 1) == 0 and word(back, 2) == 0xdeadbeef)
    try second.read(4104, back)
    assert(word(back, 0) == 0x01010101)
    var copied: u8[64]
    try second.read(65536, copied)
    for index in 0..<(usize)16:
        assert(word(copied, index) == (u32)index * 3)
    assert(word(view, 0) == 0xffffffff and word(view, 3) == 0xffffffff and word(view, 4) == 12)

## A buffer past the old 128 MiB cap, written at its far end by a word fill
## and read back there, where the device allows one.
func large(device: gpu.Device, limits: gpu.Limits) -> !:
    let size: usize = 256 << 20
    if limits.buffer_bytes < (u64)size:
        print("skip large buffer: the device allows less than 256 MiB")
        return
    var big = try gpu.Buffer.allocate(device, size)
    defer big.destroy()
    var pass = try gpu.Compute.begin(device)
    defer pass.close()
    try pass.fill(big, size - 4096, 4096, 0x12345678)
    try pass.submit()
    try pass.wait()
    var back: u8[16]
    try big.read(size - 4100, back)
    assert(word(back, 0) == 0 and word(back, 1) == 0x12345678 and word(back, 3) == 0x12345678)

## Storage images of each 32-bit format written by a kernel and read back; one
## sampled, one loaded and stored in place, an integer one read into a buffer;
## and a float image drawn into an 8-bit target for display.
func images(device: gpu.Device) -> !:
    let width: u32 = 8
    let height: u32 = 4
    let texels = (usize)(width * height)
    var color = try gpu.Texture.create(device, width, height, gpu.Format.rgba32_float, true)
    defer color.destroy()
    var depth = try gpu.Texture.create(device, width, height, gpu.Format.r32_float, true)
    defer depth.destroy()
    var ids = try gpu.Texture.create(device, width, height, gpu.Format.r32_uint, true)
    defer ids.destroy()
    var motion = try gpu.Texture.create(device, width, height, gpu.Format.rg32_float, true)
    defer motion.destroy()
    var total = try gpu.Texture.create(device, width, height, gpu.Format.rgba32_float, true)
    defer total.destroy()
    assert(try total.storage())
    var ones: u8[512]
    for index in 0..<texels * 4:
        memory.write[f32]((void*)&ones[index * 4], 1.0)
    try total.upload(ones)
    var write = try kernel(device, kernels.image_write_comp_words, kernels.image_write_comp_msl, kernels.image_write_comp_group, kernels.image_write_comp_bindings)
    defer write.destroy()
    var accumulate = try kernel(device, kernels.image_accumulate_comp_words, kernels.image_accumulate_comp_msl, kernels.image_accumulate_comp_group, kernels.image_accumulate_comp_bindings)
    defer accumulate.destroy()
    var copied = try gpu.Buffer.allocate(device, texels * 4)
    defer copied.destroy()
    var size: u8[8]
    memory.write[u32]((void*)&size[0], width)
    memory.write[u32]((void*)&size[4], height)
    var pass = try gpu.Compute.begin(device)
    defer pass.close()
    let written: gpu.Binding[4] = [gpu.Binding(texture = color), gpu.Binding(texture = depth), gpu.Binding(texture = ids), gpu.Binding(texture = motion)]
    try pass.dispatch(write, written, size, 1, 1)
    let summed: gpu.Binding[4] = [gpu.Binding(texture = color), gpu.Binding(texture = total), gpu.Binding(texture = ids), gpu.Binding(buffer = copied)]
    try pass.dispatch(accumulate, summed, size, 1, 1)
    try pass.submit()
    try pass.wait()
    var rgba: u8[512]
    try color.read(rgba)
    var sums: u8[512]
    try total.read(sums)
    var single: u8[128]
    try depth.read(single)
    var integers: u8[128]
    try ids.read(integers)
    var pairs: u8[256]
    try motion.read(pairs)
    var from_buffer: u8[128]
    try copied.read(0, from_buffer)
    for y in 0..<height:
        for x in 0..<width:
            let texel = (usize)(y * width + x)
            assert(float_at(rgba, texel * 4) == (f32)x / (f32)width and float_at(rgba, texel * 4 + 1) == (f32)y / (f32)height)
            assert(float_at(rgba, texel * 4 + 2) == 0.5 and float_at(rgba, texel * 4 + 3) == 1.0)
            assert(float_at(sums, texel * 4) == 1.0 + (f32)x / (f32)width and float_at(sums, texel * 4 + 3) == 2.0)
            assert(float_at(single, texel) == (f32)(x + y))
            assert(word(integers, texel) == x * 1000 + y and word(from_buffer, texel) == x * 1000 + y)
            assert(float_at(pairs, texel * 2) == (f32)x and float_at(pairs, texel * 2 + 1) == -(f32)y)
    # Display: the float image drawn texel for texel into an 8-bit target.
    var shown = try gpu.Texture.create(device, width, height, gpu.Format.rgba8_linear)
    defer shown.destroy()
    let frame = try shown.frame()
    defer frame.release()
    let root = try frame.value().target()
    defer root.release()
    try gpu.draw_image(root.value(), color, gpu.Rect(width = (f64)width, height = (f64)height), filter = gpu.Filter.nearest)
    # Integers are not drawn as color.
    var refused = false
    gpu.draw_image(root.value(), ids, gpu.Rect(width = 1.0, height = 1.0)) catch failure:
        assert(failure.code == gpu.invalid_geometry)
        refused = true
    assert(refused)
    assert((try frame.value().present(gpu.Color(0.0, 0.0, 0.0, 0.0))) == gpu.PresentResult.submitted)
    var pixels: u8[128]
    try shown.read(pixels)
    for y in 0..<height:
        for x in 0..<width:
            let texel = (usize)(y * width + x) * 4
            let red = (i32)((f32)x / (f32)width * 255.0 + 0.5)
            let green = (i32)((f32)y / (f32)height * 255.0 + 0.5)
            assert(close((i32)pixels[texel], red) and close((i32)pixels[texel + 1], green) and close((i32)pixels[texel + 2], 128) and pixels[texel + 3] == 255)
    # Refused: a storage binding of a plain texture, and rendering into a
    # 32-bit texture.
    var plain = try gpu.Texture.create(device, width, height, gpu.Format.rgba32_float)
    defer plain.destroy()
    var other = try gpu.Compute.begin(device)
    defer other.close()
    refused = false
    let wrong: gpu.Binding[4] = [gpu.Binding(texture = plain), gpu.Binding(texture = depth), gpu.Binding(texture = ids), gpu.Binding(texture = motion)]
    other.dispatch(write, wrong, size, 1, 1) catch failure:
        assert(failure.code == gpu.invalid_geometry)
        refused = true
    assert(refused)
    refused = false
    _ = plain.frame() catch failure:
        assert(failure.code == gpu.invalid_geometry)
        refused = true
        recover frame
    assert(refused)

## 4096 halves added to one float by atomicAdd, where the device can.
func float_atomics(device: gpu.Device, limits: gpu.Limits) -> !:
    if not limits.float_atomic_add:
        print("skip float atomics: the device has none")
        return
    var sum = try kernel(device, kernels.float_sum_comp_words, kernels.float_sum_comp_msl, kernels.float_sum_comp_group, kernels.float_sum_comp_bindings)
    defer sum.destroy()
    let count: usize = 4096
    var halves = try new u8[count * 4] in memory.heap
    defer free(halves) in memory.heap
    for index in 0..<count:
        memory.write[f32]((void*)&halves[index * 4], 0.5)
    var values = try gpu.Buffer.create(device, halves)
    defer values.destroy()
    var total = try gpu.Buffer.allocate(device, 4)
    defer total.destroy()
    var uniforms: u8[4]
    memory.write[u32]((void*)&uniforms[0], (u32)count)
    var pass = try gpu.Compute.begin(device)
    defer pass.close()
    let bindings: gpu.Binding[2] = [gpu.Binding(buffer = values), gpu.Binding(buffer = total)]
    try pass.dispatch(sum, bindings, uniforms, (u32)(count // 64))
    try pass.submit()
    try pass.wait()
    var result: u8[4]
    try total.read(0, result)
    assert(float_at(result, 0) == 2048.0)

## Infinities and NaNs propagate as IEEE says, on Metal as on Vulkan; a fast
## math kernel builds and runs (its results are not promised).
func ieee(device: gpu.Device) -> !:
    var exact = try gpu.Kernel.create(device, kernels.ieee_comp_words, kernels.ieee_comp_msl, kernels.ieee_comp_group, kernels.ieee_comp_bindings, kernels.ieee_comp_fast_math)
    defer exact.destroy()
    var fast = try gpu.Kernel.create(device, kernels.ieee_fast_comp_words, kernels.ieee_fast_comp_msl, kernels.ieee_fast_comp_group, kernels.ieee_fast_comp_bindings, kernels.ieee_fast_comp_fast_math)
    defer fast.destroy()
    var inputs: u8[16]
    memory.write[f32]((void*)&inputs[0], 0.0)
    memory.write[f32]((void*)&inputs[4], 1.0)
    memory.write[f32]((void*)&inputs[8], -2.0)
    memory.write[f32]((void*)&inputs[12], 3.0)
    var values = try gpu.Buffer.create(device, inputs)
    defer values.destroy()
    var exact_out = try gpu.Buffer.allocate(device, 32)
    defer exact_out.destroy()
    var fast_out = try gpu.Buffer.allocate(device, 32)
    defer fast_out.destroy()
    var nothing: u8[]
    var pass = try gpu.Compute.begin(device)
    defer pass.close()
    let exact_bindings: gpu.Binding[2] = [gpu.Binding(buffer = values), gpu.Binding(buffer = exact_out)]
    try pass.dispatch(exact, exact_bindings, nothing, 1)
    let fast_bindings: gpu.Binding[2] = [gpu.Binding(buffer = values), gpu.Binding(buffer = fast_out)]
    try pass.dispatch(fast, fast_bindings, nothing, 1)
    try pass.submit()
    try pass.wait()
    var results: u8[32]
    try exact_out.read(0, results)
    assert(word(results, 0) == 0x7f800000 and word(results, 1) == 0xff800000)
    assert(word(results, 2) == 1 and word(results, 3) == 1 and word(results, 4) == 1)
    assert(word(results, 5) == 0xff800000 and word(results, 6) == 0x7f800000 and word(results, 7) == 1)

## Every lane of every subgroup sees the subgroup size the device reports, by
## the built-in, by addition and by ballot, and shuffle, broadcast and vote agree.
func subgroups(device: gpu.Device, limits: gpu.Limits) -> !:
    if not limits.subgroup_ops:
        print("skip subgroups: the device lacks the KHR subgroup operations")
        return
    assert(limits.subgroup_size >= 4 and limits.subgroup_size <= 128)
    var program = try kernel(device, kernels.subgroup_comp_words, kernels.subgroup_comp_msl, kernels.subgroup_comp_group, kernels.subgroup_comp_bindings)
    defer program.destroy()
    let count: usize = 256
    var out = try gpu.Buffer.allocate(device, count * 16)
    defer out.destroy()
    var nothing: u8[]
    var pass = try gpu.Compute.begin(device)
    defer pass.close()
    let bindings: gpu.Binding[1] = [gpu.Binding(buffer = out)]
    try pass.dispatch(program, bindings, nothing, (u32)(count // 64))
    try pass.submit()
    try pass.wait()
    var results: u8[4096]
    try out.read(0, results)
    for index in 0..<count:
        assert(word(results, index * 4) == limits.subgroup_size and word(results, index * 4 + 1) == limits.subgroup_size)
        assert(word(results, index * 4 + 2) == limits.subgroup_size and word(results, index * 4 + 3) == 1)

## A pass's submission completes through the device, its GPU time spans its
## timestamps in order, and only recent submissions keep a time.
func timing(device: gpu.Device, limits: gpu.Limits) -> !:
    assert(try device.done(gpu.Submission()))
    try device.wait(gpu.Submission())
    if not limits.timestamps:
        print("skip GPU timing: the device keeps no timestamps")
        return
    var program = try kernel(device, kernels.reduce_comp_words, kernels.reduce_comp_msl, kernels.reduce_comp_group, kernels.reduce_comp_bindings)
    defer program.destroy()
    var data = try gpu.Buffer.allocate(device, 1 << 20)
    defer data.destroy()
    let bindings: gpu.Binding[1] = [gpu.Binding(buffer = data)]
    var uniforms: u8[4]
    memory.write[u32]((void*)&uniforms[0], 1 << 17)
    var pass = try gpu.Compute.begin(device)
    defer pass.close()
    try pass.dispatch(program, bindings, uniforms, 2048)
    assert((try pass.timestamp()) == 0)
    try pass.dispatch(program, bindings, uniforms, 2048)
    assert((try pass.timestamp()) == 1)
    try pass.fill(data, 0, 1 << 20, 7)
    try pass.submit()
    let submission = try pass.submission()
    assert(submission.serial > 0)
    var stamps: u64[2]
    var refused = false
    pass.timestamps(stamps) catch failure:
        assert(failure.code == gpu.invalid_geometry)
        refused = true
    assert(refused or (try pass.done()))
    try device.wait(submission)
    assert(try device.done(submission))
    try pass.wait()
    try pass.timestamps(stamps)
    let span = (try device.gpu_time(submission)) else error(gpu.failed, "a finished pass has no GPU time")
    assert(span.start <= stamps[0] and stamps[0] <= stamps[1] and stamps[1] <= span.end and span.elapsed() == span.end - span.start)
    var wrong: u64[1]
    refused = false
    pass.timestamps(wrong) catch failure:
        assert(failure.code == gpu.invalid_geometry)
        refused = true
    assert(refused)
    # More submissions than the ring keeps: the oldest has finished and has
    # no time any more; the newest has one.
    var newest = gpu.Submission()
    for round in 0..<gpu.timed_submissions + 1:
        var next = try gpu.Compute.begin(device)
        try next.fill(data, 0, 4, (u32)round)
        try next.submit()
        newest = try next.submission()
        next.close()
    try device.wait(newest)
    assert(try device.done(submission))
    assert((try device.gpu_time(submission)) == none)
    assert((try device.gpu_time(newest)) != none)

## Texture frames (plain and keep) hand out their submissions, in queue
## order with a texture copy between them; waiting on the last finishes all,
## and each has a GPU time, started in order.
func frame_timing(device: gpu.Device, limits: gpu.Limits) -> !:
    var texture = try gpu.Texture.create(device, 16, 16, gpu.Format.rgba8_linear)
    defer texture.destroy()
    var other = try gpu.Texture.create(device, 16, 16, gpu.Format.rgba8_linear)
    defer other.destroy()
    let first = try texture.frame()
    defer first.release()
    assert(first.value().submission().serial == 0)
    assert((try first.value().present(gpu.Color(1.0, 0.0, 0.0, 1.0))) == gpu.PresentResult.submitted)
    let painted = first.value().submission()
    try gpu.copy_texture(texture, gpu.Region(0, 0, 16, 16), other, 0, 0)
    let kept = try texture.frame(true)
    defer kept.release()
    assert((try kept.value().present(gpu.Color(0.0, 0.0, 0.0, 0.0))) == gpu.PresentResult.submitted)
    let drawn = kept.value().submission()
    # Texture frames and copies may share a submission (Metal commits them
    # together); a later one is never numbered before an earlier one.
    assert(painted.serial > 0 and drawn.serial >= painted.serial)
    try device.wait(drawn)
    assert((try device.done(painted)) and (try device.done(drawn)))
    if not limits.timestamps:
        return
    let painted_time = (try device.gpu_time(painted)) else error(gpu.failed, "a finished frame has no GPU time")
    let drawn_time = (try device.gpu_time(drawn)) else error(gpu.failed, "a finished frame has no GPU time")
    assert(painted_time.start <= painted_time.end and drawn_time.start <= drawn_time.end and painted_time.start <= drawn_time.start)
    # A standalone frame submits nothing.
    var standalone = try gpu.Frame(window.Size(width = 4.0, height = 4.0, pixel_width = 4.0, pixel_height = 4.0, scale = 1.0))
    defer standalone.close()
    _ = standalone.present() catch failure:
        assert(failure.code == gpu.unavailable)
        recover gpu.PresentResult.skipped
    assert(standalone.submission().serial == 0)

## Buffers reached by GPU address: a table of addresses picks each value's
## source, and the push constants carry the results' address. The sources are
## bound nowhere; taking their addresses keeps them resident and alive.
func addresses(device: gpu.Device, limits: gpu.Limits) -> !:
    if not limits.buffer_addresses:
        print("skip buffer addresses: the device has none")
        return
    var program = try kernel(device, kernels.addresses_comp_words, kernels.addresses_comp_msl, kernels.addresses_comp_group, kernels.addresses_comp_bindings)
    defer program.destroy()
    let count: usize = 128
    var first_values: u8[512]
    var second_values: u8[512]
    for index in 0..<count:
        memory.write[f32]((void*)&first_values[index * 4], (f32)index)
        memory.write[f32]((void*)&second_values[index * 4], -(f32)index)
    var first = try gpu.Buffer.create(device, first_values)
    defer first.destroy()
    var second = try gpu.Buffer.create(device, second_values)
    defer second.destroy()
    var results = try gpu.Buffer.allocate(device, count * 4)
    defer results.destroy()
    var sources: u8[16]
    memory.write[u64]((void*)&sources[0], try first.address())
    memory.write[u64]((void*)&sources[8], try second.address())
    assert((try first.address()) != 0 and (try first.address()) != (try second.address()))
    var table = try gpu.Buffer.create(device, sources)
    defer table.destroy()
    var uniforms: u8[12]
    memory.write[u64]((void*)&uniforms[0], try results.address())
    memory.write[u32]((void*)&uniforms[8], (u32)count)
    var pass = try gpu.Compute.begin(device)
    defer pass.close()
    let bindings: gpu.Binding[1] = [gpu.Binding(buffer = table)]
    try pass.dispatch(program, bindings, uniforms, 2)
    try pass.submit()
    try pass.wait()
    var back: u8[512]
    try results.read(0, back)
    for index in 0..<count:
        let wanted = (f32)index * 2.0 if index % 2 == 0 else -(f32)index * 2.0
        assert(float_at(back, index) == wanted)

## Materials sample their textures through a texture table: slots chosen per
## item at run time, a slot replaced between passes, and textures destroyed
## while the table holds them.
func tables(device: gpu.Device, limits: gpu.Limits) -> !:
    if not limits.texture_tables:
        print("skip texture tables: the device has none")
        return
    assert(limits.texture_table_size >= 64)
    var program = try gpu.Kernel.create(device, kernels.table_comp_words, kernels.table_comp_msl, kernels.table_comp_group, kernels.table_comp_bindings,
                                        kernels.table_comp_fast_math, kernels.table_comp_table)
    defer program.destroy()
    var table = try gpu.TextureTable.create(device, 8)
    defer table.destroy()
    assert(table.capacity() == 8)
    var colors: u8[12] = [200, 0, 0, 255, 0, 100, 0, 255, 0, 0, 50, 255]
    for slot in 0..<(usize)3:
        var texture = try gpu.Texture.create(device, 1, 1, gpu.Format.rgba8_linear)
        try texture.upload(colors[slot * 4..<slot * 4 + 4])
        try table.set((u32)(slot * 3), texture)
        # The table keeps it.
        texture.destroy()
    var slot_bytes: u8[16]
    let chosen: u32[4] = [3, 0, 6, 3]
    for index in 0..<(usize)4:
        memory.write[u32]((void*)&slot_bytes[index * 4], chosen[index])
    var materials = try gpu.Buffer.create(device, slot_bytes)
    defer materials.destroy()
    var out = try gpu.Buffer.allocate(device, 64)
    defer out.destroy()
    var uniforms: u8[4]
    memory.write[u32]((void*)&uniforms[0], 4)
    let bindings: gpu.Binding[3] = [gpu.Binding(buffer = materials), gpu.Binding(buffer = out), gpu.Binding(filter = gpu.Filter.nearest)]
    var pass = try gpu.Compute.begin(device)
    defer pass.close()
    try pass.dispatch(program, bindings, uniforms, 1, textures = table)
    try pass.submit()
    # Replacing a slot waits for the pass reading the table.
    var green = try gpu.Texture.create(device, 1, 1, gpu.Format.rgba8_linear)
    defer green.destroy()
    var bright: u8[4] = [0, 255, 0, 255]
    try green.upload(bright)
    try table.set(3, green)
    try table.clear(6)
    try pass.wait()
    var back: u8[64]
    try out.read(0, back)
    assert(close_float(float_at(back, 0), 0.0) and close_float(float_at(back, 1), 100.0 / 255.0))
    assert(close_float(float_at(back, 4), 200.0 / 255.0) and float_at(back, 7) == 1.0)
    assert(close_float(float_at(back, 10), 50.0 / 255.0) and close_float(float_at(back, 12), 0.0))
    # The replaced slot is seen by the next pass, which reads no cleared slot.
    memory.write[u32]((void*)&slot_bytes[8], 0)
    try materials.upload(0, slot_bytes)
    var again = try gpu.Compute.begin(device)
    defer again.close()
    try again.dispatch(program, bindings, uniforms, 1, textures = table)
    try again.submit()
    try again.wait()
    try out.read(0, back)
    assert(close_float(float_at(back, 1), 1.0) and close_float(float_at(back, 0), 0.0))
    # A table kernel needs its table, and only such a kernel takes one.
    var refused = false
    var other = try gpu.Compute.begin(device)
    defer other.close()
    other.dispatch(program, bindings, uniforms, 1) catch failure:
        assert(failure.code == gpu.invalid_geometry)
        refused = true
    assert(refused)

func close_float(value: f32, wanted: f32) -> bool:
    return value >= wanted - 0.002 and value <= wanted + 0.002

## Specialization constants of each kind change what a kernel computes;
## constants given no value keep their defaults; a value for an id the
## kernel lacks, of the wrong kind, or given twice is refused.
func specialization(device: gpu.Device) -> !:
    assert(kernels.special_comp_constant_ids[0] == 0 and kernels.special_comp_constant_ids[3] == 5)
    assert(kernels.special_comp_constant_kinds[2] == (u8)gpu.ConstantKind.float32 and kernels.special_comp_constant_defaults[1] == 0xffffffff)
    let count: usize = 64
    var out = try gpu.Buffer.allocate(device, count * 4)
    defer out.destroy()
    let everything: gpu.Constant[4] = [gpu.Constant.uint32(0, 1), gpu.Constant.int32(1, 3), gpu.Constant.float32(2, 0.5), gpu.Constant.boolean(5, true)]
    try special_run(device, &out, none, count)
    var values: u8[256]
    try out.read(0, values)
    for index in 0..<count:
        assert(float_at(values, index) == 2.0 * (f32)index - 1.0)
    try special_run(device, &out, everything, count)
    try out.read(0, values)
    for index in 0..<count:
        assert(float_at(values, index) == -(0.5 * (f32)index + 3.0) * 10.0)
    let flip_only: gpu.Constant[1] = [gpu.Constant.boolean(5, true)]
    try special_run(device, &out, flip_only, count)
    try out.read(0, values)
    for index in 0..<count:
        assert(float_at(values, index) == (2.0 * (f32)index - 1.0) * 10.0)
    let refused_sets: gpu.Constant[3] = [gpu.Constant.uint32(9, 1), gpu.Constant.int32(0, 1), gpu.Constant.float32(5, 1.0)]
    for constant in refused_sets:
        let one: gpu.Constant[1] = [constant]
        var refused = false
        _ = gpu.Kernel.create(device, kernels.special_comp_words, kernels.special_comp_msl, kernels.special_comp_group, kernels.special_comp_bindings, constants = one) catch failure:
            assert(failure.code == gpu.invalid_shader)
            refused = true
            recover gpu.Kernel()
        assert(refused)
    let twice: gpu.Constant[2] = [gpu.Constant.uint32(0, 1), gpu.Constant.uint32(0, 2)]
    var refused = false
    _ = gpu.Kernel.create(device, kernels.special_comp_words, kernels.special_comp_msl, kernels.special_comp_group, kernels.special_comp_bindings, constants = twice) catch failure:
        assert(failure.code == gpu.invalid_shader)
        refused = true
        recover gpu.Kernel()
    assert(refused)

## Kernels built in the background: polled until ready and then dispatched,
## dispatched at once (the dispatch waits), destroyed while building, and
## created twice from the same code and constants (the device shares them).
func background(device: gpu.Device) -> !:
    let count: usize = 64
    var out = try gpu.Buffer.allocate(device, count * 4)
    defer out.destroy()
    let negate: gpu.Constant[2] = [gpu.Constant.uint32(0, 1), gpu.Constant.int32(1, 7)]
    var polled = try gpu.Kernel.create(device, kernels.special_comp_words, kernels.special_comp_msl, kernels.special_comp_group, kernels.special_comp_bindings,
                                       constants = negate, background = true)
    defer polled.destroy()
    var spins: usize = 0
    while not (try polled.ready()):
        spins += 1
        assert(spins < 100000)
        thread.sleep(1)
    try special_dispatch(device, polled, &out, count)
    var values: u8[256]
    try out.read(0, values)
    for index in 0..<count:
        assert(float_at(values, index) == -(2.0 * (f32)index + 7.0))
    let flip: gpu.Constant[1] = [gpu.Constant.boolean(5, true)]
    var waited = try gpu.Kernel.create(device, kernels.special_comp_words, kernels.special_comp_msl, kernels.special_comp_group, kernels.special_comp_bindings,
                                       constants = flip, background = true)
    defer waited.destroy()
    try special_dispatch(device, waited, &out, count)
    try out.read(0, values)
    for index in 0..<count:
        assert(float_at(values, index) == (2.0 * (f32)index - 1.0) * 10.0)
    assert(try waited.ready())
    # The same code and constants again: the cache hands out the built kernel.
    var again = try gpu.Kernel.create(device, kernels.special_comp_words, kernels.special_comp_msl, kernels.special_comp_group, kernels.special_comp_bindings,
                                      constants = flip, background = true)
    assert(try again.ready())
    again.destroy()
    let scale: gpu.Constant[1] = [gpu.Constant.float32(2, 3.0)]
    var abandoned = try gpu.Kernel.create(device, kernels.special_comp_words, kernels.special_comp_msl, kernels.special_comp_group, kernels.special_comp_bindings,
                                          constants = scale, background = true)
    abandoned.destroy()

func special_dispatch(device: gpu.Device, program: gpu.Kernel, out: gpu.Buffer*, count: usize) -> !:
    var uniforms: u8[4]
    memory.write[u32]((void*)&uniforms[0], (u32)count)
    var pass = try gpu.Compute.begin(device)
    defer pass.close()
    let bindings: gpu.Binding[1] = [gpu.Binding(buffer = *out)]
    try pass.dispatch(program, bindings, uniforms, (u32)((count + 63) // 64))
    try pass.submit()
    try pass.wait()

func special_run(device: gpu.Device, out: gpu.Buffer*, constants: const gpu.Constant[]?, count: usize) -> !:
    var program = try gpu.Kernel.create(device, kernels.special_comp_words, kernels.special_comp_msl, kernels.special_comp_group, kernels.special_comp_bindings, constants = constants)
    defer program.destroy()
    var uniforms: u8[4]
    memory.write[u32]((void*)&uniforms[0], (u32)count)
    var pass = try gpu.Compute.begin(device)
    defer pass.close()
    let bindings: gpu.Binding[1] = [gpu.Binding(buffer = *out)]
    try pass.dispatch(program, bindings, uniforms, (u32)((count + 63) // 64))
    try pass.submit()
    try pass.wait()

func close(value: i32, wanted: i32) -> bool:
    return value >= wanted - 1 and value <= wanted + 1

## Mismatched bindings, oversized uniforms, misaligned ranges and recording
## after submission are refused before anything reaches the GPU.
func refusals(device: gpu.Device) -> !:
    var program = try kernel(device, kernels.saxpy_comp_words, kernels.saxpy_comp_msl, kernels.saxpy_comp_group, kernels.saxpy_comp_bindings)
    defer program.destroy()
    var buffer = try gpu.Buffer.allocate(device, 256)
    defer buffer.destroy()
    var pass = try gpu.Compute.begin(device)
    defer pass.close()
    var nothing: u8[]
    var refused = false
    let one: gpu.Binding[1] = [gpu.Binding(buffer = buffer)]
    pass.dispatch(program, one, nothing, 1) catch failure:
        assert(failure.code == gpu.invalid_geometry)
        refused = true
    assert(refused)
    refused = false
    let two: gpu.Binding[2] = [gpu.Binding(buffer = buffer), gpu.Binding()]
    pass.dispatch(program, two, nothing, 1) catch failure:
        assert(failure.code == gpu.closed)
        refused = true
    assert(refused)
    refused = false
    var big: u8[132]
    let both: gpu.Binding[2] = [gpu.Binding(buffer = buffer), gpu.Binding(buffer = buffer)]
    pass.dispatch(program, both, big, 1) catch failure:
        assert(failure.code == gpu.invalid_geometry)
        refused = true
    assert(refused)
    refused = false
    pass.fill(buffer, 2, 8, 0) catch failure:
        assert(failure.code == gpu.invalid_geometry)
        refused = true
    assert(refused)
    refused = false
    pass.copy(buffer, 0, buffer, 4, 8) catch failure:
        assert(failure.code == gpu.invalid_geometry)
        refused = true
    assert(refused)
    refused = false
    _ = gpu.Buffer.allocate(device, 6) catch failure:
        assert(failure.code == gpu.invalid_geometry)
        refused = true
        recover gpu.Buffer()
    assert(refused)
    refused = false
    _ = buffer.view() catch failure:
        assert(failure.code == gpu.invalid_geometry)
        refused = true
        recover nothing
    assert(refused)
    try pass.dispatch(program, both, nothing, 1)
    try pass.submit()
    refused = false
    pass.fill(buffer, 0, 4, 0) catch failure:
        assert(failure.code == gpu.frame_finished)
        refused = true
    assert(refused)
    try pass.wait()
    pass.close()
    pass.close()