Module Tolk_metal.Icb

type t

The type for indirect command buffers.

val create : State.t -> count:int -> t

create state ~count allocates an ICB with capacity for count compute commands.

Raises Failure if Metal cannot allocate the ICB.

val encode : t -> index:int -> program:nativeint -> buffers:nativeint array -> arg_buf:nativeint -> arg_offsets:int array -> global:int array -> local:int array -> unit

encode t ~index ~program ~buffers ~arg_buf ~arg_offsets ~global ~local encodes a compute dispatch at command index with:

  • program — opaque Metal program handle for the kernel pipeline.
  • buffers — kernel buffer bindings (array of Metal buffer addresses).
  • arg_buf — Metal buffer holding packed int32 variable parameters, or 0n if there are none.
  • arg_offsets — byte offsets into arg_buf for each variable parameter.
  • global — threadgroup grid dimensions, length 3.
  • local — threads per threadgroup, length 3.

A memory barrier is inserted after the dispatch so commands execute in order.

Raises Failure if local threads exceed the pipeline's maximum.

val update_buffer : t -> index:int -> buf_index:int -> buf:nativeint -> unit

update_buffer t ~index ~buf_index ~buf replaces the buffer at binding buf_index for command index. The buffer offset is set to 0.

val update_dispatch : t -> index:int -> global:int array -> local:int array -> unit

update_dispatch t ~index ~global ~local updates the threadgroup dimensions for command index. Both arrays must have length 3.

val execute : State.t -> t -> resources:nativeint array -> pipelines:nativeint array -> unit

execute state t ~resources ~pipelines submits the ICB for GPU execution.

resources are Metal buffer handles marked for read and write access by the GPU. Every buffer referenced by encoded commands must appear here.

pipelines are pipeline handles for the M1/M2 ICB workaround: on pre-M3 GPUs (AGXG family < 15), a zero-size dummy dispatch is issued per pipeline before executing the ICB to prevent kIOGPUCommandBufferCallbackErrorInvalidResource crashes. On M3+ the array is ignored.

The resulting command buffer is appended to the in-flight list and is waited by State.synchronize.

val release : t -> unit

release t frees the underlying Metal ICB.