Luce packages
LuceLuce BaseLuciaOS

dymokomi/luce-gpu

Source of release 0.5.4

0.5.4 / src / gpu / compute.lucb

#==============================================================================================
#
#   compute - Compute kernels and the passes that dispatch them
#
#   DESCRIPTION:
#       A Kernel is one GLSL compute shader on a device, supplied in both backends' forms by
#       tools/embed_shaders.py: SPIR-V for Vulkan, Metal Shading Language for Metal, its
#       workgroup size and what each binding of set 0 holds. A Compute records dispatches,
#       buffer copies and fills, then submits them as one submission on the device's queue.
#       Every command sees what the commands before it wrote (Metal: a serial encoder over
#       tracked resources; Vulkan: a memory barrier between commands), and work submitted
#       after it, frames included, sees its results.
#
#       Commands are recorded portably and encoded at `submit`, so a pass holds no backend
#       recording open between calls and the device's other work can go on meanwhile.
#
#==============================================================================================

# mark: Kernels ===============================================================================
## The most bindings a kernel has: set 0, bindings 0..15.
pub let binding_limit: usize = 16

## What a kernel binding holds (`<stem>_comp_bindings`, made by embed_shaders.py).
pub enum BindingKind as u8:
    unused = 0
    ## A storage buffer (`buffer` block); bound with `Binding(buffer = ...)`.
    storage_buffer = 1
    ## A storage image (`image2D` and the like), loaded and stored.
    storage_image = 2
    ## A sampled image (`sampler2D` and the like).
    sampled_image = 3
    ## A ray-tracing acceleration structure (`accelerationStructureEXT`):
    ## a Tlas, bound with `Binding(accel = ...)`.
    acceleration_structure = 4
    ## A sampler (`uniform sampler`), for a texture table's textures; bound
    ## with `Binding(filter = ...)`.
    sampler = 5

## A compute program on one device; the zero value is closed, copies alias
## ownership, and submitted work keeps it alive until it finishes.
pub struct Kernel:
    var state: KernelState*?

    ## Build a kernel from its SPIR-V words and Metal source (each backend
    ## uses its own form), its workgroup size and its binding kinds, as
    ## embed_shaders.py emits them: `<stem>_comp_words`, `_msl`, `_group`,
    ## `_bindings`, `_fast_math` and `_table`. Float math follows IEEE rules
    ## (infinities and NaNs propagate) unless `fast_math` lets Metal relax
    ## them; `table` says the kernel reads a texture table (set 1). `constants`
    ## specialize the kernel: a value for each specialization constant to
    ## change, the others keeping their defaults. With `background` the kernel
    ## builds on a thread of its own: `ready()` polls it, and a dispatch waits
    ## for it. Creating a kernel the device already holds open, from the same
    ## code, workgroup, bindings, flags and constants, shares that one.
    pub static func create(device: Device, spirv: const u32[], msl: c.str, group: const u32[], bindings: const u8[], fast_math: bool = false, table: bool = false,
                           constants: const Constant[]? = none, background: bool = false) -> Kernel!:
        let owner = try device.checked()
        if spirv.length < 5 or spirv[0] != 0x07230203:
            error(invalid_shader, "SPIR-V words must begin with the SPIR-V magic number")
        if group.length != 3 or bindings.length > binding_limit:
            error(invalid_shader, "a kernel has a three-part workgroup size and at most 16 bindings")
        let limits = owner.limits
        var threads: u64 = 1
        for axis in 0..<(usize)3:
            if group[axis] == 0 or group[axis] > limits.group_size[axis]:
                error(invalid_shader, "the kernel's workgroup size exceeds the device's limits().group_size")
            threads *= (u64)group[axis]
        if threads > (u64)limits.group_threads:
            error(invalid_shader, "the kernel's workgroup holds more invocations than the device's limits().group_threads")
        var kinds: u8[16]
        for index in 0..<bindings.length:
            if bindings[index] > (u8)BindingKind.sampler:
                error(invalid_shader, "a kernel binding of an unknown kind")
            if bindings[index] == (u8)BindingKind.acceleration_structure and not owner.limits.ray_query:
                error(unsupported, "the device has no ray queries")
            kinds[index] = bindings[index]
        if table and not owner.limits.texture_tables:
            error(unsupported, "the device has no texture tables")
        var none_given: Constant[]
        let values: const Constant[] = constants else none_given
        try check_constants(spirv, values)
        var size: u32[3] = [group[0], group[1], group[2]]
        let hash = try kernel_hash(spirv, msl)
        if let cached = kernel_cached(owner, hash, size, kinds, fast_math, table, values):
            cached.references += 1
            return Kernel(state = cached)
        let state = try new KernelState(device = owner, group = size, bindings = kinds, table = table, fast_math = fast_math, hash = hash) in memory.heap
        errdefer free(state) in memory.heap
        if values.length > 0:
            state.constants = try new Constant[values.length] --- in memory.heap
            memory.copy(state.constants, values, values.length)
        errdefer:
            if state.constants.length > 0: free(state.constants) in memory.heap
        if background:
            state.build = try kernel_build_start(owner, spirv, msl, size, kinds, fast_math, table, values)
        else:
            state.native = try backend_kernel_create(owner, spirv, msl, size, kinds, fast_math, table, values)
        kernel_remember(owner, state) catch failure:
            # Uncached is still a kernel.
            _ = failure
        owner.references += 1
        return Kernel(state = state)

    ## Whether the kernel is built: always, unless it builds in the background
    ## and has not finished. A build that failed reports its error here (and
    ## at its dispatch).
    pub func ready() -> bool!:
        let state = try self.checked()
        if let build = state.build:
            if build.done.load(.acquire) == 0:
                return false
        try state.finish()
        return true

    ## The workgroup size the kernel was built with.
    pub func group() -> u32[3]!:
        return (try self.checked()).group

    pub func is_open() -> bool:
        return self.state != none

    ## Release this handle on the main thread; submitted work keeps the kernel
    ## until it finishes.
    pub func destroy():
        let state = self.state else return
        require_thread()
        self.state = none
        release_kernel(state)

    func checked() -> KernelState*!:
        try check_thread()
        return self.state else error(closed, "the GPU kernel is closed")

struct KernelState:
    var device: DeviceState*
    ## The built pipeline; none while a background build runs.
    var native: void*?
    var group: u32[3]
    var bindings: u8[16]
    var table: bool
    var fast_math: bool
    var constants: Constant[]
    ## The code's hash, the key of the device's kernel cache.
    var hash: u64
    var references: usize = 1
    ## A background build not yet taken, and whether one failed.
    var build: KernelBuild*?
    var failed: bool

    ## The built pipeline, once `finish` has taken it (every dispatch has).
    func built() -> void*:
        return self.native else trap("a kernel was encoded before it was built")

    ## Take a background build's result, waiting for it if it still runs.
    func finish() -> !:
        if self.failed:
            error(invalid_shader, "the kernel could not be built")
        let build = self.build else return
        self.build = none
        defer kernel_build_free(build)
        self.native = kernel_build_finish(build) catch failure:
            self.failed = true
            error(failure.code, failure.message)

func release_kernel(state: KernelState*):
    state.references -= 1
    if state.references == 0:
        kernel_forget(state.device, state)
        state.finish() catch failure:
            _ = failure
        if let native = state.native:
            state.device.destroy_kernel(state.device.native, native)
        release_device(state.device)
        if state.constants.length > 0: free(state.constants) in memory.heap
        free(state) in memory.heap

# mark: Bindings ==============================================================================
## What a dispatch binds at one binding of set 0: element `n` of a dispatch's
## bindings is binding `n`. Bindings the kernel does not use may stay closed.
pub struct Binding:
    ## A storage buffer, bound whole.
    pub var buffer: Buffer
    ## A storage image (a texture created with `storage`) or a sampled image,
    ## as the kernel declares the binding.
    pub var texture: Texture
    ## How a sampled image, or a sampler binding, filters.
    pub var filter: Filter = Filter.nearest
    ## An acceleration structure binding's Tlas.
    pub var accel: Tlas

# mark: Recording =============================================================================
let command_dispatch: u8 = 0
let command_indirect: u8 = 1
let command_copy: u8 = 2
let command_fill: u8 = 3
let command_timestamp: u8 = 4
let command_build_blas: u8 = 5
let command_refit_blas: u8 = 6
let command_build_tlas: u8 = 7
let command_update_tlas: u8 = 8

## The most timestamps one pass records.
pub let timestamp_limit: usize = 64

## One recorded command, with the references it holds until it is encoded.
## Every command is preceded by a barrier against all earlier ones; a command
## that waives it can be added as a flag here without changing the API.
struct ComputeCommand:
    var kind: u8
    var kernel: KernelState*?
    var buffers: BufferState*?[16]
    var textures: TextureState*?[16]
    var filters: Filter[16]
    ## The texture table set 1 reads.
    var table: TableState*?
    ## Acceleration structure bindings.
    var accels: AccelState*?[16]
    var uniforms: u8[128]
    var groups: u32[3]
    ## The indirect arguments, the copy's source or the fill's target.
    var buffer: BufferState*?
    ## The copy's destination.
    var target: BufferState*?
    var offset: usize
    var target_offset: usize
    var bytes: usize
    var value: u32
    ## A build's Blas or Tlas; a Blas build's geometry (from `buffer` and
    ## `target`), or a Tlas build's instances and the Blases they instance.
    var accel: AccelState*?
    var geometry: GeometryRecord
    var instances: InstanceRecord[]
    var instanced: AccelState*[]

func release_command(command: ComputeCommand*):
    if let kernel = command.kernel: release_kernel(kernel)
    for slot in command.buffers:
        if let buffer = slot: release_buffer(buffer)
    for slot in command.textures:
        if let texture = slot: release_texture(texture)
    if let table = command.table: release_table(table)
    for slot in command.accels:
        if let accel = slot: release_accel(accel)
    if let accel = command.accel: release_accel(accel)
    for blas in command.instanced:
        release_accel(blas)
    if command.instances.length > 0: free(command.instances) in memory.heap
    if command.instanced.length > 0: free(command.instanced) in memory.heap
    if let buffer = command.buffer: release_buffer(buffer)
    if let target = command.target: release_buffer(target)
    *command = ComputeCommand()

## One submission of compute work on a device: record dispatches, copies and
## fills, `submit` once, then poll `done` or `wait`. The zero value is closed;
## `close` gives up an unsubmitted recording. Main thread only, like every
## GPU call. Resources may be destroyed as soon as they are recorded: the
## pass and then the submitted work keep them alive.
pub struct Compute:
    var state: ComputeState*?

    ## Begin recording compute work for `device`.
    pub static func begin(device: Device) -> Compute!:
        let owner = try device.checked()
        let state = try new ComputeState(device = owner) in memory.heap
        owner.references += 1
        return Compute(state = state)

    ## Run `kernel` over `x` by `y` by `z` workgroups with `bindings` (element n
    ## is binding n) and up to 128 `uniforms` bytes as its push constants;
    ## `textures` is the texture table a kernel made with `table` reads. A
    ## zero count records nothing.
    pub func dispatch(kernel: Kernel, bindings: const Binding[], uniforms: const u8[], x: u32, y: u32 = 1, z: u32 = 1, textures: TextureTable? = none) -> !:
        let state = try self.recording()
        let limits = state.device.limits
        if x > limits.group_count[0] or y > limits.group_count[1] or z > limits.group_count[2]:
            error(invalid_geometry, "a dispatch launches more workgroups than the device's limits().group_count")
        if x == 0 or y == 0 or z == 0:
            return
        var command = try state.bound(command_dispatch, kernel, bindings, uniforms, textures)
        command.groups = [x, y, z]
        try state.append(&command)

    ## Run `kernel` over the workgroup counts the GPU wrote to `arguments` at
    ## `offset`: three u32s, x, y and z, as earlier commands left them.
    pub func dispatch_indirect(kernel: Kernel, bindings: const Binding[], uniforms: const u8[], arguments: Buffer, offset: usize, textures: TextureTable? = none) -> !:
        let state = try self.recording()
        let source = try state.own(arguments)
        try check_buffer_range(source, offset, 12)
        var command = try state.bound(command_indirect, kernel, bindings, uniforms, textures)
        command.buffer = source
        command.offset = offset
        source.references += 1
        try state.append(&command)

    ## Copy `bytes` from `source` at `source_offset` to `destination` at
    ## `destination_offset`; offsets and length four-byte aligned, the ranges
    ## inside their buffers and apart when the buffers are the same.
    pub func copy(source: Buffer, source_offset: usize, destination: Buffer, destination_offset: usize, bytes: usize) -> !:
        let state = try self.recording()
        let origin = try state.own(source)
        let goal = try state.own(destination)
        try check_buffer_range(origin, source_offset, bytes)
        try check_buffer_range(goal, destination_offset, bytes)
        if origin == goal and source_offset < destination_offset + bytes and destination_offset < source_offset + bytes:
            error(invalid_geometry, "a buffer copy's ranges overlap")
        if bytes == 0: return
        var command = ComputeCommand(kind = command_copy, buffer = origin, target = goal, offset = source_offset, target_offset = destination_offset, bytes = bytes)
        origin.references += 1
        goal.references += 1
        try state.append(&command)

    ## Set every 32-bit word of `bytes` of `buffer` from `offset` to `value`
    ## (zero clears); offset and length four-byte aligned.
    pub func fill(buffer: Buffer, offset: usize, bytes: usize, value: u32 = 0) -> !:
        let state = try self.recording()
        let target = try state.own(buffer)
        try check_buffer_range(target, offset, bytes)
        if bytes == 0: return
        var command = ComputeCommand(kind = command_fill, buffer = target, offset = offset, bytes = bytes, value = value)
        target.references += 1
        try state.append(&command)

    ## Build `blas` from `triangles` (the counts it was created for).
    pub func build_blas(blas: Blas, triangles: Triangles) -> !:
        try self.record_blas(command_build_blas, blas, &triangles)

    ## Refit `blas` to `triangles`' moved vertices: same counts and indices,
    ## faster than a build, where the Blas was created with `refit` and built.
    pub func refit_blas(blas: Blas, triangles: Triangles) -> !:
        try self.record_blas(command_refit_blas, blas, &triangles)

    ## Build a Blas of boxes from `boxes` (the count it was created for).
    pub func build_boxes(blas: Blas, boxes: Boxes) -> !:
        try self.record_boxes(command_build_blas, blas, &boxes)

    ## Refit a Blas of boxes to `boxes` moved or resized: the same count,
    ## where the Blas was created with `refit` and built.
    pub func refit_boxes(blas: Blas, boxes: Boxes) -> !:
        try self.record_boxes(command_refit_blas, blas, &boxes)

    ## Build `tlas` from `instances` (at most its capacity), each a built Blas
    ## of the device. The Tlas holds the Blases until it is built again.
    pub func build_tlas(tlas: Tlas, instances: const Instance[]) -> !:
        try self.record_tlas(command_build_tlas, tlas, instances)

    ## Update a built `tlas` with new transforms, ids and masks: the same
    ## number of instances, of the same Blases in the same order.
    pub func update_tlas(tlas: Tlas, instances: const Instance[]) -> !:
        try self.record_tlas(command_update_tlas, tlas, instances)

    func record_blas(kind: u8, blas: Blas, triangles: const Triangles*) -> !:
        let state = try self.recording()
        let target = try self.blas_target(kind, blas)
        try check_triangles(state.device, target, triangles)
        let vertices = triangles.vertices.state else trap("checked vertices went missing")
        let indices = triangles.indices.state else trap("checked indices went missing")
        var command = ComputeCommand(kind = kind, accel = target, buffer = vertices, target = indices,
                                     geometry = GeometryRecord(offset = triangles.vertex_offset, stride = triangles.stride, vertex_count = triangles.vertex_count,
                                                               index_offset = triangles.index_offset, count = triangles.triangle_count, opaque = triangles.opaque))
        target.references += 1
        vertices.references += 1
        indices.references += 1
        try state.append(&command)
        target.built = true

    func record_boxes(kind: u8, blas: Blas, boxes: const Boxes*) -> !:
        let state = try self.recording()
        let target = try self.blas_target(kind, blas)
        try check_boxes(state.device, target, boxes)
        let source = boxes.buffer.state else trap("checked boxes went missing")
        var command = ComputeCommand(kind = kind, accel = target, buffer = source,
                                     geometry = GeometryRecord(boxes = true, offset = boxes.offset, stride = boxes.stride, count = boxes.count))
        target.references += 1
        source.references += 1
        try state.append(&command)
        target.built = true

    ## The Blas a build or refit of `kind` records into, checked.
    func blas_target(kind: u8, blas: Blas) -> AccelState*!:
        let state = try self.recording()
        let target = try blas.checked()
        if target.device != state.device:
            error(wrong_device, "a compute pass builds Blases of its own device")
        if kind == command_refit_blas and not (target.refit and target.built):
            error(invalid_geometry, "a refit needs a Blas created with refit and built before")
        return target

    func record_tlas(kind: u8, tlas: Tlas, instances: const Instance[]) -> !:
        let state = try self.recording()
        let target = try tlas.checked()
        if target.device != state.device:
            error(wrong_device, "a compute pass builds Tlases of its own device")
        if instances.length == 0 or instances.length > (usize)target.capacity:
            error(invalid_geometry, "a Tlas build has 1 to its capacity of instances")
        if kind == command_update_tlas and not (target.built and target.instanced_count == instances.length):
            error(invalid_geometry, "an update needs a built Tlas and as many instances as its build")
        for index in 0..<instances.length:
            let blas = instances[index].blas.state else error(closed, "a Tlas instance names a closed Blas")
            if blas.device != state.device or blas.top or not blas.built:
                error(invalid_geometry, "a Tlas instances built Blases of its own device")
            if instances[index].id > instance_id_limit:
                error(invalid_geometry, "an instance id has 24 bits")
            if kind == command_update_tlas and target.instanced[index] != blas:
                error(invalid_geometry, "an update instances the same Blases in the same order")
        let records = try new InstanceRecord[instances.length] --- in memory.heap
        errdefer free(records) in memory.heap
        let blases = try new AccelState*[instances.length] --- in memory.heap
        errdefer free(blases) in memory.heap
        for index in 0..<instances.length:
            let blas = instances[index].blas.state else trap("a checked instance lost its Blas")
            records[index] = InstanceRecord(transform = instances[index].transform, id = instances[index].id, mask = instances[index].mask)
            blases[index] = blas
        # The command holds the Blases until it is encoded; the Tlas from now
        # until it is built again.
        if kind == command_build_tlas:
            try target.keep_instanced(blases)
        for blas in blases:
            blas.references += 1
        var command = ComputeCommand(kind = kind, accel = target, instances = records, instanced = blases)
        target.references += 1
        try state.append(&command)
        target.built = true

    ## Record a timestamp: the GPU time at which every command recorded before
    ## it has finished, read with `timestamps` once the pass has. Its index,
    ## counting from zero; at most `timestamp_limit` per pass, where the device
    ## has `limits().timestamps`. On Metal each one also ends a command buffer,
    ## which costs a few microseconds.
    pub func timestamp() -> usize!:
        let state = try self.recording()
        if not state.device.limits.timestamps:
            error(unsupported, "the device keeps no GPU timestamps")
        if state.stamps == timestamp_limit:
            error(command_limit, "a compute pass records at most 64 timestamps")
        var command = ComputeCommand(kind = command_timestamp, value = (u32)state.stamps)
        try state.append(&command)
        state.stamps += 1
        return state.stamps - 1

    ## Submit the recorded commands as one submission, without waiting. Work
    ## submitted later, frames and reads included, sees their results.
    pub func submit() -> !:
        let state = try self.recording()
        defer state.release_commands()
        let submitted = backend_compute_submit(state.device, state.commands[..<state.count], state.stamps, state.device.addressed[..<state.device.addressed_count]) catch failure:
            # Nothing reached the queue: the pass is over and reports the failure.
            state.phase = 2
            state.failed = true
            error(failure.code, failure.message)
        state.submission = Submission(serial = submitted.serial)
        state.native = submitted.native
        state.phase = 1
        for command in state.commands[..<state.count]:
            if let table = command.table: table.last = state.submission

    ## The pass's submission on the device's queue, once submitted: for
    ## `Device.done`, `Device.wait` and `Device.gpu_time`.
    pub func submission() -> Submission!:
        return (try self.submitted()).submission

    ## Whether the submitted work has finished, without waiting; the way to keep
    ## a long render from stopping the UI: poll once a frame. An execution
    ## failure is reported here or by `wait`.
    pub func done() -> bool!:
        let state = try self.submitted()
        if state.phase == 2:
            return true
        if not backend_submission_done(state.device, state.submission):
            return false
        try self.wait()
        return true

    ## Wait for the submitted work, reporting `execution_failed` if it failed.
    pub func wait() -> !:
        let state = try self.submitted()
        if state.phase == 2:
            if state.failed: error(execution_failed, "the GPU failed while running compute work")
            return
        state.phase = 2
        backend_submission_wait(state.device, state.submission) catch failure:
            state.failed = true
            error(failure.code, failure.message)

    ## The pass's timestamps in nanoseconds on the GPU clock, in recording
    ## order, once it has finished (`wait` or `done`); `out` holds exactly as
    ## many as were recorded.
    pub func timestamps(out: u64[]) -> !:
        let state = try self.submitted()
        if state.phase != 2 or state.failed:
            error(invalid_geometry, "a pass's timestamps are there once it has finished")
        if out.length != state.stamps:
            error(invalid_geometry, "timestamps are read all at once, as many as were recorded")
        if state.stamps == 0: return
        try backend_compute_stamps(state.device, state.native, out)

    pub func is_open() -> bool:
        return self.state != none

    ## End the pass: an unsubmitted recording is given up; submitted work runs
    ## to completion on its own. Idempotent.
    pub func close():
        let state = self.state else return
        require_thread()
        self.state = none
        state.release_commands()
        if state.commands.length > 0:
            free(state.commands) in memory.heap
        if let native = state.native:
            backend_compute_release(state.device, native, state.submission)
        release_device(state.device)
        free(state) in memory.heap

    func recording() -> ComputeState*!:
        try check_thread()
        let state = self.state else error(closed, "the compute pass is closed")
        if state.phase != 0:
            error(frame_finished, "a submitted compute pass records nothing more; begin another")
        return state

    func submitted() -> ComputeState*!:
        try check_thread()
        let state = self.state else error(closed, "the compute pass is closed")
        if state.phase == 0:
            error(invalid_geometry, "submit a compute pass before waiting for it")
        return state

struct ComputeState:
    var device: DeviceState*
    var commands: ComputeCommand[]
    var count: usize
    ## 0 recording, 1 submitted, 2 complete.
    var phase: u8
    var stamps: usize
    var submission: Submission
    ## What the backend keeps for the pass's timestamps.
    var native: void*?
    var failed: bool

    ## A buffer handle's state, checked to belong to this pass's device.
    func own(buffer: Buffer) -> BufferState*!:
        let state = buffer.state else error(closed, "a compute pass was given a closed buffer")
        if state.device != self.device:
            error(wrong_device, "a compute pass uses buffers of its own device")
        return state

    ## A dispatch of `kernel` holding its bindings and uniforms, checked
    ## against what the kernel declares; it holds a reference to each.
    func bound(kind: u8, kernel: Kernel, bindings: const Binding[], uniforms: const u8[], textures: TextureTable?) -> ComputeCommand!:
        let program = try kernel.checked()
        # A kernel still building in the background is waited for here.
        try program.finish()
        if program.device != self.device:
            error(wrong_device, "the kernel belongs to another GPU device")
        var table: TableState*? = none
        if let given = textures:
            table = try given.checked()
        if program.table != (table != none):
            error(invalid_geometry, "a kernel reading a texture table is dispatched with one, and only such a kernel")
        if let held = table:
            if held.device != self.device:
                error(wrong_device, "a compute pass uses texture tables of its own device")
        if uniforms.length > uniform_limit:
            error(invalid_geometry, "a dispatch carries at most 128 uniform bytes")
        if bindings.length > binding_limit:
            error(invalid_geometry, "a dispatch has at most 16 bindings")
        var command = ComputeCommand(kind = kind, kernel = program)
        memory.copy(command.uniforms[..<uniforms.length], uniforms, uniforms.length)
        for index in 0..<binding_limit:
            let declared = program.bindings[index]
            if declared == 0:
                continue
            if index >= bindings.length:
                error(invalid_geometry, "a dispatch leaves out a binding its kernel uses")
            if declared == (u8)BindingKind.storage_buffer:
                command.buffers[index] = try self.own(bindings[index].buffer)
                continue
            if declared == (u8)BindingKind.sampler:
                command.filters[index] = bindings[index].filter
                continue
            if declared == (u8)BindingKind.acceleration_structure:
                let accel = try bindings[index].accel.checked()
                if accel.device != self.device or not accel.built:
                    error(invalid_geometry, "an acceleration structure binding takes a built Tlas of the pass's device")
                command.accels[index] = accel
                continue
            let image = bindings[index].texture.state else error(closed, "a compute pass was given a closed texture")
            if image.closed or image.device != self.device:
                error(wrong_device, "a compute pass uses open textures of its own device")
            if declared == (u8)BindingKind.storage_image and not image.storage:
                error(invalid_geometry, "a storage image binding takes a texture created with storage")
            command.textures[index] = image
            command.filters[index] = bindings[index].filter
        program.references += 1
        if let held = table:
            held.references += 1
            command.table = held
        for slot in command.buffers:
            if let buffer = slot: buffer.references += 1
        for slot in command.textures:
            if let texture = slot: texture.references += 1
        for slot in command.accels:
            if let accel = slot: accel.references += 1
        return command

    func append(command: ComputeCommand*) -> !:
        errdefer release_command(command)
        if self.count == self.commands.length:
            let grown = try new ComputeCommand[self.commands.length * 2 + 16] --- in memory.heap
            memory.copy(grown, self.commands, self.count)
            if self.commands.length > 0:
                free(self.commands) in memory.heap
            self.commands = grown
        self.commands[self.count] = *command
        self.count += 1

    func release_commands():
        for index in 0..<self.count:
            release_command(&self.commands[index])
        self.count = 0

# mark: Dispatch ==============================================================================

func backend_kernel_create(device: DeviceState*, spirv: const u32[], msl: c.str, group: u32[3], bindings: u8[16], fast_math: bool, table: bool, constants: const Constant[]) -> void*!:
    if (platform.windows or platform.linux) and device.backend == Backend.vulkan:
        return (void*)try vulkan_kernel_create((VulkanDevice*)device.native, spirv, bindings, table, constants)
    if platform.macos and platform.arm64:
        if device.backend == Backend.metal:
            return try metal_kernel_create((MetalDevice*)device.native, msl, group, fast_math, constants)
    error(unsupported, "compute kernels are unavailable on this backend")

func backend_kernel_destroyer(backend: Backend) -> func(void*, void*) -> unit:
    if (platform.windows or platform.linux) and backend == Backend.vulkan: return vulkan_kernel_release
    if platform.macos and platform.arm64 and backend == Backend.metal: return metal_kernel_release
    trap("compute kernels are unavailable on this backend")

## A submitted pass: its serial, and what the backend keeps for its timestamps.
struct ComputeSubmitted:
    var serial: u64
    var native: void*?

## `addressed` are the buffers whose addresses were taken: every pass may
## reach them, so each counts as using them.
func backend_compute_submit(device: DeviceState*, commands: const ComputeCommand[], stamps: usize, addressed: BufferState*[]) -> ComputeSubmitted!:
    if (platform.windows or platform.linux) and device.backend == Backend.vulkan:
        return try vulkan_compute_submit((VulkanDevice*)device.native, commands, stamps, addressed)
    if platform.macos and platform.arm64:
        if device.backend == Backend.metal:
            return try metal_compute_submit((MetalDevice*)device.native, commands, stamps, addressed)
    error(unsupported, "compute work is unavailable on this backend")

func backend_compute_stamps(device: DeviceState*, native: void*?, out: u64[]) -> !:
    if (platform.windows or platform.linux) and device.backend == Backend.vulkan:
        try vulkan_compute_stamps((VulkanDevice*)device.native, native, out)
        return
    if platform.macos and platform.arm64:
        if device.backend == Backend.metal:
            try metal_compute_stamps(native, out)
            return
    error(unsupported, "compute work is unavailable on this backend")

## Let go of what the backend keeps for a pass; work still running finishes
## on its own.
func backend_compute_release(device: DeviceState*, native: void*, submission: Submission):
    if (platform.windows or platform.linux) and device.backend == Backend.vulkan:
        vulkan_compute_release((VulkanDevice*)device.native, native, submission.serial)
        return
    if platform.macos and platform.arm64:
        if device.backend == Backend.metal:
            metal_compute_release(native)