Luce packages
LuceLuce BaseLuciaOS

dymokomi/luce-gpu

Source of release 0.5.4

0.5.4 / src / gpu / metal / drawing.lucb

#==============================================================================================
#
#   drawing - The Metal drawing pipelines
#
#   DESCRIPTION:
#       Backend implementation of the portable drawing contract, shared by every surface and
#       texture of a device: one shader library, one pipeline per color format, the depth
#       states, the two samplers, a placeholder texture for draws that sample nothing, and a
#       cached depth attachment. The vertex input uses eight scalar floats, avoiding native
#       vector alignment in the ABI. Applications never supply Metal source or native pipeline
#       objects.
#
#==============================================================================================

## Pipeline slots: 0 is the BGRA8 sRGB presentation format, 1..4 follow the
## renderable `Format`s, and 5 is the BGRA8 presentation format of an encoded
## surface.
let metal_slot_count: usize = 6
let metal_encoded_slot: usize = 5

struct MetalDrawing:
    # The vertex library and the built-in fill fragment library.
    var library: void*?
    var fill: void*?
    var pipelines: void*?[6]
    var geometry_library: void*?
    var geometry_pipelines: void*?[6]
    # Mesh stages (metal/mesh.lucb): pipelines per MeshKind and slot, and a
    # buffer bound where a draw leaves one out.
    var mesh_library: void*?
    var mesh_wire_library: void*?
    var mesh_fragment_library: void*?
    var mesh_id_library: void*?
    var mesh_placeholder: void*?
    var mesh_pipelines: void*?[18]
    # The vertex stage of shade_quads (shaders/quads.vert), compiled on first use.
    var quad_library: void*?
    var depth_on: void*?
    var depth_off: void*?
    # Tested (less) without writing: client pipelines made with depth_test.
    var depth_read: void*?
    var nearest: void*?
    var linear: void*?
    var trilinear: void*?
    var placeholder: void*?
    var depth_texture: void*?
    var width: u64
    var height: u64
    # The depth copied for draws that read the scene depth (r32float), sized
    # with the depth attachment.
    var depth_copy: void*?

func metal_text(value: c.str) -> void*!:
    return metal_string(try metal_class("NSString"), metal_sel("stringWithUTF8String:"), value) else error(failed, "could not create Metal shader text")

## The MTLPixelFormat of a pipeline slot.
func metal_slot_format(slot: usize) -> u64:
    if slot == 1: return 71  # RGBA8Unorm_sRGB
    if slot == 2: return 70  # RGBA8Unorm
    if slot == 3: return 115  # RGBA16Float
    if slot == 4: return 10  # R8Unorm
    if slot == 5: return 80  # BGRA8Unorm
    return 81  # BGRA8Unorm_sRGB

## The pipeline slot of a renderable format.
func metal_format_slot(pixel_format: Format) -> usize:
    return (usize)pixel_format + 1

## The MTLPixelFormat of a texture format.
func metal_pixel_format(pixel_format: Format) -> u64:
    if pixel_format == Format.rgba32_float: return 125  # RGBA32Float
    if pixel_format == Format.r32_float: return 55  # R32Float
    if pixel_format == Format.r32_uint: return 53  # R32Uint
    if pixel_format == Format.rg32_float: return 105  # RG32Float
    return metal_slot_format(metal_format_slot(pixel_format))

## The vertex stages. `luce_vertex`: eight scalar floats per vertex from buffer
## 0, passed through with the color at user location 0 for every fragment
## program. `luce_instance` (shade_instances): sixteen floats per instance from
## buffer 1, a clip-space rectangle (left, top, right, bottom) as two triangles
## and twelve values for locations 1..3, with opaque white at location 0.
## `luce_vertex` leaves locations 1..3 zero, so one fragment program serves both.
let metal_vertex_source: c.str = "#include <metal_stdlib>\nusing namespace metal;\nstruct V { float4 position [[position]]; float4 color [[user(locn0)]]; float4 data0 [[user(locn1)]]; float4 data1 [[user(locn2)]]; float4 data2 [[user(locn3)]]; };\nvertex V luce_vertex(const device float* data [[buffer(0)]], uint id [[vertex_id]]) {\n uint i=id*8; V v; v.position=float4(data[i],data[i+1],data[i+2],data[i+3]); v.color=float4(data[i+4],data[i+5],data[i+6],data[i+7]); v.data0=float4(0.0); v.data1=float4(0.0); v.data2=float4(0.0); return v;\n}\nvertex V luce_instance(const device float4* data [[buffer(1)]], uint id [[vertex_id]], uint instance [[instance_id]]) {\n uint i=instance*4; float4 r=data[i]; uint c=id==3u?0u:(id==4u?2u:(id==5u?3u:id)); V v; v.position=float4((c==1u||c==2u)?r.z:r.x,c>=2u?r.w:r.y,0.0,1.0); v.color=float4(1.0); v.data0=data[i+1]; v.data1=data[i+2]; v.data2=data[i+3]; return v;\n}"

func metal_drawing_open(device: MetalDevice*) -> MetalDrawing*!:
    let state = try new MetalDrawing() in memory.heap
    errdefer metal_drawing_destroy(state)
    let native = metal_required(device.device)
    state.library = try metal_compile(native, metal_vertex_source, true)
    state.fill = try metal_compile(native, fill_frag_msl, true)
    let depth = metal_ptr(try metal_class("MTLDepthStencilDescriptor"), metal_sel("new")) else error(failed, "could not create a GPU depth descriptor")
    defer metal_void(depth, metal_sel("release"))
    metal_uint_arg(depth, metal_sel("setDepthCompareFunction:"), 1)
    metal_bool_arg(depth, metal_sel("setDepthWriteEnabled:"), true)
    state.depth_on = metal_with_object(native, metal_sel("newDepthStencilStateWithDescriptor:"), depth) else error(failed, "could not create GPU depth testing")
    metal_uint_arg(depth, metal_sel("setDepthCompareFunction:"), 7)
    metal_bool_arg(depth, metal_sel("setDepthWriteEnabled:"), false)
    state.depth_off = metal_with_object(native, metal_sel("newDepthStencilStateWithDescriptor:"), depth) else error(failed, "could not create GPU overlay state")
    metal_uint_arg(depth, metal_sel("setDepthCompareFunction:"), 1)
    state.depth_read = metal_with_object(native, metal_sel("newDepthStencilStateWithDescriptor:"), depth) else error(failed, "could not create GPU depth reading")
    state.nearest = try metal_sampler(native, 0)
    state.linear = try metal_sampler(native, 1)
    state.trilinear = try metal_sampler(native, 1, true)
    # Every draw binds a texture; one opaque texel stands in for draws that sample none.
    let placeholder = try metal_texture_create(device, 1, 1, Format.rgba8_linear, false)
    var white: u8[4] = [255, 255, 255, 255]
    metal_texture_upload(device, placeholder, white, Region(0, 0, 1, 1)) catch problem:
        metal_texture_destroy(placeholder)
        error(problem.code, problem.message)
    state.placeholder = placeholder.texture
    free(placeholder) in memory.heap
    return state

## A clamped sampler filtering with `filter` (0 nearest, 1 linear); `mipmapped`
## also blends linearly between levels, where the others read the first only.
func metal_sampler(device: void*, filter: u64, mipmapped: bool = false) -> void*!:
    let descriptor = metal_ptr(try metal_class("MTLSamplerDescriptor"), metal_sel("new")) else error(failed, "could not create a GPU sampler descriptor")
    defer metal_void(descriptor, metal_sel("release"))
    metal_uint_arg(descriptor, metal_sel("setMinFilter:"), filter)
    metal_uint_arg(descriptor, metal_sel("setMagFilter:"), filter)
    # MTLSamplerMipFilterNotMipmapped (0) or Linear (2).
    metal_uint_arg(descriptor, metal_sel("setMipFilter:"), 2 if mipmapped else 0)
    # MTLSamplerAddressModeClampToEdge on both axes.
    metal_uint_arg(descriptor, metal_sel("setSAddressMode:"), 0)
    metal_uint_arg(descriptor, metal_sel("setTAddressMode:"), 0)
    return metal_with_object(device, metal_sel("newSamplerStateWithDescriptor:"), descriptor) else error(failed, "could not create a GPU sampler")

## The device's drawing state, compiled on first use.
func metal_drawing(device: MetalDevice*) -> MetalDrawing*!:
    if let drawing = device.drawing:
        return drawing
    let drawing = try metal_drawing_open(device)
    device.drawing = drawing
    return drawing

## Compile one Metal source into a library. Metal defaults to fast math, which
## may drop infinities and NaNs and reorder float operations. Client shaders
## keep IEEE rules, as on Vulkan, unless they ask for fast math; the built-in
## drawing shaders, which do no inf- or NaN-sensitive work, use fast math (IEEE
## rules cost the fill shader about 12% of a heavy frame's GPU time).
## A nonzero `version` (an MTLLanguageVersion) asks for that language version,
## which source using newer features needs.
func metal_compile(native: void*, source: c.str, fast_math: bool, version: u64 = 0) -> void*!:
    let options = metal_ptr(try metal_class("MTLCompileOptions"), metal_sel("new")) else error(failed, "could not create Metal compile options")
    defer metal_void(options, metal_sel("release"))
    metal_bool_arg(options, metal_sel("setFastMathEnabled:"), fast_math)
    if version != 0: metal_uint_arg(options, metal_sel("setLanguageVersion:"), version)
    var failure: void*? = none
    return metal_library(native, metal_sel("newLibraryWithSource:options:error:"), try metal_text(source), options, &failure) else error(invalid_shader, "could not compile the Metal shader source")

## The built-in pipeline rendering into color attachments of `slot`, built on first use.
func metal_pipeline_for(device: MetalDevice*, drawing: MetalDrawing*, slot: usize) -> void*!:
    if let pipeline = drawing.pipelines[slot]:
        return pipeline
    let pipeline = try metal_build_pipeline(device, drawing, metal_required(drawing.fill), Blend.over, slot)
    drawing.pipelines[slot] = pipeline
    return pipeline

## A pipeline of the vertex stage (the geometry one, the instanced one, or
## shade_quads'), `fragment_library`'s `luce_fragment`, and `blend`, rendering
## into color attachments of `slot`.
func metal_build_pipeline(device: MetalDevice*, drawing: MetalDrawing*, fragment_library: void*, blend: Blend, slot: usize, geometry: bool = false, instanced: bool = false,
                          quads: bool = false) -> void*!:
    if geometry:
        return try metal_stage_pipeline(device, metal_required(drawing.geometry_library), "luce_geometry", fragment_library, blend, slot)
    if quads:
        if drawing.quad_library == none:
            drawing.quad_library = try metal_compile(metal_required(device.device), quads_vert_msl, true)
        return try metal_stage_pipeline(device, metal_required(drawing.quad_library), "luce_geometry", fragment_library, blend, slot)
    return try metal_stage_pipeline(device, metal_required(drawing.library), "luce_instance" if instanced else "luce_vertex", fragment_library, blend, slot)

## A pipeline of `vertex_library`'s `vertex_name`, `fragment_library`'s
## `luce_fragment`, and `blend`, rendering into color attachments of `slot`.
func metal_stage_pipeline(device: MetalDevice*, vertex_library: void*, vertex_name: c.str, fragment_library: void*, blend: Blend, slot: usize) -> void*!:
    let native = metal_required(device.device)
    let vertex = metal_with_object(vertex_library, metal_sel("newFunctionWithName:"), try metal_text(vertex_name)) else error(failed, "the GPU vertex entry is missing")
    defer metal_void(vertex, metal_sel("release"))
    let fragment = metal_with_object(fragment_library, metal_sel("newFunctionWithName:"), try metal_text("luce_fragment")) else error(invalid_shader, "the fragment shader has no luce_fragment entry")
    defer metal_void(fragment, metal_sel("release"))
    let descriptor = metal_ptr(try metal_class("MTLRenderPipelineDescriptor"), metal_sel("new")) else error(failed, "could not create a GPU pipeline descriptor")
    defer metal_void(descriptor, metal_sel("release"))
    metal_object(descriptor, metal_sel("setVertexFunction:"), vertex)
    metal_object(descriptor, metal_sel("setFragmentFunction:"), fragment)
    metal_uint_arg(descriptor, metal_sel("setDepthAttachmentPixelFormat:"), 252)
    let attachments = metal_required(metal_ptr(descriptor, metal_sel("colorAttachments")))
    let color = metal_required(metal_index(attachments, metal_sel("objectAtIndexedSubscript:"), 0))
    metal_uint_arg(color, metal_sel("setPixelFormat:"), metal_slot_format(slot))
    # Fragments emit premultiplied color. Factors: 1 = One, 5 = OneMinusSourceAlpha.
    metal_bool_arg(color, metal_sel("setBlendingEnabled:"), blend != Blend.replace)
    metal_uint_arg(color, metal_sel("setSourceRGBBlendFactor:"), 1)
    metal_uint_arg(color, metal_sel("setDestinationRGBBlendFactor:"), 1 if blend == Blend.add else 5)
    metal_uint_arg(color, metal_sel("setSourceAlphaBlendFactor:"), 1)
    metal_uint_arg(color, metal_sel("setDestinationAlphaBlendFactor:"), 1 if blend == Blend.add else 5)
    var failure: void*? = none
    return metal_pipeline(native, metal_sel("newRenderPipelineStateWithDescriptor:error:"), descriptor, &failure) else error(invalid_shader, "could not build a pipeline from the fragment shader")

# mark: Client shaders and pipelines ===========================================================

func metal_shader_create(device: MetalDevice*, msl: c.str, fast_math: bool) -> void*!:
    let pool = objc_autoreleasePoolPush()
    defer objc_autoreleasePoolPop(pool)
    return try metal_compile(metal_required(device.device), msl, fast_math)

func metal_shader_destroy(library: void*):
    metal_void(library, metal_sel("release"))

## A client pipeline: its fragment library and blend, and the pipeline states
## built from them per color slot, for ordinary, instanced and quad draws
## (`slot * 3 + variant`, see client_variant). The state for the format it was
## made for is built at creation, so a bad shader fails there; the others when
## first drawn.
struct MetalClientPipeline:
    var library: void*
    var blend: Blend
    var states: void*?[18]

func metal_pipeline_create(device: MetalDevice*, library: void*, blend: Blend, pixel_format: Format?) -> void*!:
    let pool = objc_autoreleasePoolPush()
    defer objc_autoreleasePoolPop(pool)
    let state = try new MetalClientPipeline(library = library, blend = blend) in memory.heap
    errdefer metal_pipeline_destroy((void*)state)
    var slot: usize = 0
    if let target = pixel_format:
        slot = metal_format_slot(target)
    _ = try metal_client_state(device, state, slot, 0)
    return (void*)state

## The state of `pipeline` for color slot `slot` and vertex stage `variant`
## (client_variant), built on first use.
func metal_client_state(device: MetalDevice*, pipeline: MetalClientPipeline*, slot: usize, variant: usize) -> void*!:
    let index = slot * 3 + variant
    if let built = pipeline.states[index]:
        return built
    let built = try metal_build_pipeline(device, try metal_drawing(device), pipeline.library, pipeline.blend, slot, instanced = variant == 1, quads = variant == 2)
    pipeline.states[index] = built
    return built

func metal_pipeline_destroy(pipeline: void*):
    let state = (MetalClientPipeline*)pipeline
    for built in state.states:
        if let value = built:
            metal_void(value, metal_sel("release"))
    free(state) in memory.heap

func metal_depth(device: MetalDevice*, state: MetalDrawing*, width: u64, height: u64) -> void*!:
    if state.width == width and state.height == height:
        return metal_required(state.depth_texture)
    let descriptor = metal_ptr(try metal_class("MTLTextureDescriptor"), metal_sel("new")) else error(failed, "could not create a GPU depth texture descriptor")
    defer metal_void(descriptor, metal_sel("release"))
    metal_uint_arg(descriptor, metal_sel("setTextureType:"), 2)
    metal_uint_arg(descriptor, metal_sel("setPixelFormat:"), 252)
    metal_uint_arg(descriptor, metal_sel("setWidth:"), width)
    metal_uint_arg(descriptor, metal_sel("setHeight:"), height)
    metal_uint_arg(descriptor, metal_sel("setStorageMode:"), 2)
    # MTLTextureUsageRenderTarget | ShaderRead: a scene depth copy reads it.
    metal_uint_arg(descriptor, metal_sel("setUsage:"), 5)
    let texture = metal_with_object(metal_required(device.device), metal_sel("newTextureWithDescriptor:"), descriptor) else error(failed, "could not allocate GPU depth storage")
    # The copy for scene depth draws: r32float, made again at this size.
    metal_uint_arg(descriptor, metal_sel("setPixelFormat:"), 55)
    errdefer metal_void(texture, metal_sel("release"))
    let copy = metal_with_object(metal_required(device.device), metal_sel("newTextureWithDescriptor:"), descriptor) else error(failed, "could not allocate GPU depth storage")
    if let previous = state.depth_texture:
        metal_void(previous, metal_sel("release"))
    metal_release_optional(state.depth_copy)
    state.depth_texture = texture
    state.depth_copy = copy
    state.width = width
    state.height = height
    return texture

func metal_drawing_destroy(state: MetalDrawing*):
    if let texture = state.depth_texture:
        metal_void(texture, metal_sel("release"))
    metal_release_optional(state.depth_copy)
    if let texture = state.placeholder:
        metal_void(texture, metal_sel("release"))
    for pipeline in state.pipelines:
        if let value = pipeline:
            metal_void(value, metal_sel("release"))
    for pipeline in state.geometry_pipelines:
        if let value = pipeline: metal_void(value, metal_sel("release"))
    for pipeline in state.mesh_pipelines:
        if let value = pipeline: metal_void(value, metal_sel("release"))
    for object in [state.depth_on, state.depth_off, state.depth_read, state.nearest, state.linear, state.trilinear, state.library, state.fill, state.geometry_library,
                   state.mesh_library, state.mesh_wire_library, state.mesh_fragment_library, state.mesh_id_library, state.mesh_placeholder, state.quad_library]:
        if let value = object:
            metal_void(value, metal_sel("release"))
    free(state) in memory.heap

## Record `canvas` into `target` (a color texture of `slot`'s format) cleared to
## `color`, or over its contents when `keep`, as render passes of `command`. Its
## vertices, coverage and instances go in the upload ring. The encoded slot
## clears to the encoded color and has the built-in draws encode theirs. One
## pass draws everything, unless draws read the scene depth: before each that
## needs a fresh copy (`depth_copy_before`), the pass ends storing its depth,
## a copy pass writes the depth to `depth_copy`, and a new pass resumes over
## both attachments.
func metal_pass(device: MetalDevice*, command: void*, target: void*, slot: usize, canvas: Canvas, color: Color, width: u64, height: u64, keep: bool = false) -> !:
    let encoded = slot == metal_encoded_slot
    let descriptor = metal_ptr(try metal_class("MTLRenderPassDescriptor"), metal_sel("renderPassDescriptor")) else error(failed, "could not create a Metal render pass")
    let attachments = metal_required(metal_ptr(descriptor, metal_sel("colorAttachments")))
    let attachment = metal_required(metal_index(attachments, metal_sel("objectAtIndexedSubscript:"), 0))
    metal_object(attachment, metal_sel("setTexture:"), target)
    # MTLLoadActionLoad (1) keeps the contents, MTLLoadActionClear (2) clears.
    metal_uint_arg(attachment, metal_sel("setLoadAction:"), 1 if keep else 2)
    metal_uint_arg(attachment, metal_sel("setStoreAction:"), 1)
    let clear = Color(srgb_encoded(color.red), srgb_encoded(color.green), srgb_encoded(color.blue), color.alpha) if encoded else color
    metal_color_arg(attachment, metal_sel("setClearColor:"), LuceGpuMetalClearColor(red = clear.red * clear.alpha, green = clear.green * clear.alpha, blue = clear.blue * clear.alpha, alpha = clear.alpha))
    if canvas.draw_count == 0:
        let encoder = metal_with_object(command, metal_sel("renderCommandEncoderWithDescriptor:"), descriptor) else error(failed, "could not create a Metal render encoder")
        metal_void(encoder, metal_sel("endEncoding"))
        return
    let state = try metal_drawing(device)
    let depth = metal_required(metal_ptr(descriptor, metal_sel("depthAttachment")))
    metal_object(depth, metal_sel("setTexture:"), try metal_depth(device, state, width, height))
    metal_uint_arg(depth, metal_sel("setLoadAction:"), 2)
    metal_double_arg(depth, metal_sel("setClearDepth:"), 1.0)
    # Empty arrays still bind a span: the shaders' buffers are never unbound.
    let vertices = try metal_ring_stage(device, u8[]((u8*)canvas.vertices.data, canvas.vertex_count * 32))
    let coverage = try metal_ring_stage(device, u8[]((u8*)canvas.coverage.data, canvas.coverage_count * 4))
    var instances: MetalSpan? = none
    if canvas.instance_count > 0:
        instances = try metal_ring_stage(device, u8[]((u8*)canvas.instances.data, canvas.instance_count * memory.size_of(ShadeInstance)))
    # Pipeline states are built before encoding, so encoding cannot fail.
    var copies: MetalCopies*? = none
    let pipeline = try metal_pipeline_for(device, state, slot)
    var geometry_pipeline = pipeline
    for index in 0..<canvas.draw_count:
        let draw = canvas.draws[index]
        if let custom = draw.pipeline:
            _ = try metal_client_state(device, (MetalClientPipeline*)custom.native, slot, client_variant(draw))
        if draw.geometry != none and geometry_pipeline == pipeline:
            geometry_pipeline = try metal_geometry_pipeline(device, state, slot)
        if let mesh = draw.mesh:
            _ = try metal_mesh_pipeline(device, state, mesh.kind, slot)
        if copies == none and depth_copy_before(&canvas, index):
            let made = try metal_copies(device)
            _ = try metal_copy_pipeline(device, made, metal_copy_depth, 55)
            copies = made
    var start: usize = 0
    var first = true
    while true:
        # This pass draws start..<end; a depth copy follows unless it is the
        # last. Later passes start at a draw whose copy was just made.
        var end = start if first else start + 1
        while end < canvas.draw_count and not depth_copy_before(&canvas, end): end += 1
        let last = end >= canvas.draw_count
        # MTLStoreActionStore (1) keeps the depth for the copy; DontCare (0) drops it.
        metal_uint_arg(depth, metal_sel("setStoreAction:"), 0 if last else 1)
        let encoder = metal_with_object(command, metal_sel("renderCommandEncoderWithDescriptor:"), descriptor) else error(failed, "could not create a Metal render encoder")
        metal_encode(encoder, state, pipeline, geometry_pipeline, vertices, coverage, instances, canvas, start, end, width, height, slot)
        metal_void(encoder, metal_sel("endEncoding"))
        if last: return
        try metal_copy_depth_texture(device, command, copies else trap("a Metal depth copy lost its pipeline"), metal_required(state.depth_texture),
                                     metal_required(state.depth_copy), width, height)
        # The next pass draws over what this one left, color and depth.
        metal_uint_arg(attachment, metal_sel("setLoadAction:"), 1)
        metal_uint_arg(depth, metal_sel("setLoadAction:"), 1)
        start = end
        first = false

## Encode draws `first..<end` of `canvas`; draws reading the scene depth get
## `drawing.depth_copy` at binding 4.
func metal_encode(encoder: void*, drawing: MetalDrawing*, pipeline: void*, geometry_pipeline: void*, buffer: MetalSpan, masks: MetalSpan, instances: MetalSpan?, canvas: Canvas,
                  first: usize, end: usize, width: u64, height: u64, slot: usize):
    metal_bind_buffer(encoder, metal_sel("setVertexBuffer:offset:atIndex:"), buffer.buffer, buffer.offset, 0)
    if let instance_buffer = instances:
        metal_bind_buffer(encoder, metal_sel("setVertexBuffer:offset:atIndex:"), instance_buffer.buffer, instance_buffer.offset, 1)
    metal_bind_buffer(encoder, metal_sel("setFragmentBuffer:offset:atIndex:"), masks.buffer, masks.offset, 5)
    for draw in canvas.draws[first..<end]:
        let x = metal_min((u64)draw.clip.x, width)
        let y = metal_min((u64)draw.clip.y, height)
        let w = metal_min((u64)draw.clip.width, width - x)
        let h = metal_min((u64)draw.clip.height, height - y)
        if w == 0 or h == 0:
            continue
        let region = draw.viewport else Viewport(width = (f64)width, height = (f64)height)
        metal_viewport(encoder, metal_sel("setViewport:"), LuceGpuMetalViewport(x = region.x, y = region.y, width = region.width, height = region.height, near = 0.0, far = 1.0))
        metal_scissor(encoder, metal_sel("setScissorRect:"), LuceGpuMetalScissor(x = x, y = y, width = w, height = h))
        var depth_state = drawing.depth_on if draw.depth else drawing.depth_off
        if let custom = draw.pipeline:
            if custom.depth_test: depth_state = drawing.depth_read
        metal_object(encoder, metal_sel("setDepthStencilState:"), depth_state)
        # Always reset between draws: neither wires nor UI inherit fill bias.
        metal_depth_bias(encoder,metal_sel("setDepthBias:slopeScale:clamp:"),0.0,draw.depth_slope,0.0)
        if let mesh = draw.mesh:
            let mesh_pipeline = metal_required(drawing.mesh_pipelines[(usize)(u8)mesh.kind * metal_slot_count + slot])
            metal_encode_mesh(encoder, drawing, mesh, mesh_pipeline, draw.count)
            # Later ordinary draws expect the canvas vertices at 0.
            metal_bind_buffer(encoder, metal_sel("setVertexBuffer:offset:atIndex:"), buffer.buffer, buffer.offset, 0)
            continue
        var selected = pipeline
        if let custom = draw.pipeline:
            selected = metal_required(((MetalClientPipeline*)custom.native).states[slot * 3 + client_variant(draw)])
        if let geometry = draw.geometry:
            selected = geometry_pipeline
            metal_bind_buffer(encoder, metal_sel("setVertexBuffer:offset:atIndex:"), geometry.native, 0, 6)
            var uniforms = draw.geometry_uniforms
            metal_inline_bytes(encoder, metal_sel("setVertexBytes:length:atIndex:"), &uniforms, 112, 7)
        metal_object(encoder, metal_sel("setRenderPipelineState:"), selected)
        if draw.uniform_count > 0:
            var uniforms = draw.uniforms
            # The whole zero-padded block: the shader's struct may be padded past the bytes given.
            metal_inline_bytes(encoder, metal_sel("setFragmentBytes:length:atIndex:"), &uniforms, (u64)uniform_limit, 0)
        else:
            var params = draw.params
            if slot == metal_encoded_slot:
                params.mode = params.mode | draw_encoded
            metal_inline_bytes(encoder, metal_sel("setFragmentBytes:length:atIndex:"), &params, 48, 0)
        let sampler = metal_sampler_for(drawing, draw.filter)
        for index in 0..<image_limit:
            var image = metal_required(drawing.placeholder)
            if let texture = draw.images[index]:
                image = metal_required(((MetalTexture*)texture.native).texture)
            if index == image_limit - 1 and reads_scene_depth(&draw):
                image = metal_required(drawing.depth_copy)
            metal_bind_texture(encoder, metal_sel("setFragmentTexture:atIndex:"), image, (u64)index + 1)
            metal_bind_texture(encoder, metal_sel("setFragmentSamplerState:atIndex:"), sampler, (u64)index + 1)
        if draw.instanced:
            # Six vertices per rectangle, the draw's run of instances.
            metal_draw_instances(encoder, metal_sel("drawPrimitives:vertexStart:vertexCount:instanceCount:baseInstance:"), 3, 0, 6, (u64)draw.count, (u64)draw.first)
            continue
        if let quads = draw.quads:
            metal_encode_quads(encoder, quads)
            continue
        metal_draw(encoder, metal_sel("drawPrimitives:vertexStart:vertexCount:"), 3, (u64)draw.first, (u64)draw.count)

## One shade_quads draw: its records at vertex buffer 6, its parameters at 7,
## its order (or the records, unread) at 8; a strip of four vertices (MTLPrimitiveTypeTriangleStrip, 4) per
## quad, as many as its count or its indirect arguments say.
func metal_encode_quads(encoder: void*, quads: const QuadDraw*):
    let records = quads.records.native
    metal_bind_buffer(encoder, metal_sel("setVertexBuffer:offset:atIndex:"), records, 0, 6)
    var control = quads.control
    metal_inline_bytes(encoder, metal_sel("setVertexBytes:length:atIndex:"), &control, 16, 7)
    var order = records
    if let state = quads.order: order = state.native
    metal_bind_buffer(encoder, metal_sel("setVertexBuffer:offset:atIndex:"), order, 0, 8)
    if let arguments = quads.arguments:
        metal_draw_indirect(encoder, metal_sel("drawPrimitives:indirectBuffer:indirectBufferOffset:"), 4, arguments.native, (u64)quads.arguments_offset)
        return
    metal_draw_instances(encoder, metal_sel("drawPrimitives:vertexStart:vertexCount:instanceCount:baseInstance:"), 4, 0, (u64)quad_vertex_count, (u64)quads.count, 0)

## The device's sampler for `filter`.
func metal_sampler_for(drawing: MetalDrawing*, filter: Filter) -> void*:
    if filter == Filter.trilinear:
        return metal_required(drawing.trilinear)
    return metal_required(drawing.linear if filter == Filter.linear else drawing.nearest)

func metal_min(a: u64, b: u64) -> u64:
    return a if a < b else b

extern func metal_draw_indirect as "objc_msgSend"(object: void*, selector: void*, primitive: u64, buffer: void*, offset: u64)
extern func metal_draw_instances as "objc_msgSend"(object: void*, selector: void*, primitive: u64, start: u64, count: u64, instances: u64, base: u64)
extern func metal_inline_bytes as "objc_msgSend"(object: void*, selector: void*, bytes: const void*, length: u64, index: u64)
extern func metal_bind_texture as "objc_msgSend"(object: void*, selector: void*, value: void*, index: u64)