concinnity-device 0.19.119

//! Safe command recording. [`Recorder`] is a command buffer that is known to be
//! in the recording state, and the surface over it that every pass records
//! through.
//!
//! The `unsafe` on `vkCmd*` carries two obligations: the command buffer is in
//! the recording state, and every handle and slice the command names is live for
//! the call. Both were restated verbatim at every recording site in this backend,
//! which is how they stop being checked. `Recorder` discharges the first by
//! construction -- the only safe way to get one is [`Recorder::begin`], which
//! puts the buffer into that state itself -- and the second by taking the owning
//! wrappers from `owned.rs` by reference, so a pipeline or layout cannot be bound
//! unless its owner is alive at the call.
//!
//! Passes convert to this surface one at a time: `encode_pass_into` hands each
//! arm the recorder, and an arm that has not converted reads the raw buffer back
//! out with [`Recorder::raw`]. Growing the surface is what converting the next
//! pass costs; it carries only the commands its callers use.
//!
//! What is left raw is stated rather than hidden: descriptor sets, buffers and
//! image views are still `vk::*` handles here, because they are owned by a
//! descriptor pool, the device allocator or a swapchain rather than by a wrapper
//! of their own. Those keep the liveness argument they always had, and
//! [`Recorder::raw`] exists for the commands this surface does not cover (the
//! extension loaders: acceleration-structure builds and the upscaler SDKs), so a
//! pass that needs one does not have to abandon the type.

use ash::vk;

use super::owned::{OwnedFramebuffer, OwnedPipeline, OwnedPipelineLayout, OwnedRenderPass};

// Push one `#[repr(C)]` block at offset 0 onto a raw command buffer. Typed, so
// the byte length comes from the value rather than from a pointer cast beside a
// hand-written size.
//
// # Safety
// `cmd` must be in the recording state, and `cmd` and `layout` must belong to
// `device` and be live for the call.
pub(in crate::vulkan) unsafe fn cmd_push_constants<T: bytemuck::NoUninit>(
    device: &ash::Device,
    cmd: vk::CommandBuffer,
    layout: vk::PipelineLayout,
    stages: vk::ShaderStageFlags,
    value: &T,
) {
    // SAFETY: the caller upholds the recording state and handle liveness, and the bytes are
    // `value`'s own, borrowed for the call.
    unsafe { device.cmd_push_constants(cmd, layout, stages, 0, bytemuck::bytes_of(value)) };
}

// A command buffer in the recording state.
//
// Borrows the raw device rather than sharing the owning handle: recording never
// creates or retires an owned object, so a recorder holds no claim on the
// device's lifetime and carries only the dispatch table onto the render-graph's
// worker threads.
pub(in crate::vulkan) struct Recorder<'a> {
    device: &'a ash::Device,
    cmd: vk::CommandBuffer,
}

impl<'a> Recorder<'a> {
    // Begin recording into `cmd`, which must not be in flight. The caller
    // establishes that with the frame fence it already waits on; putting the
    // buffer into the recording state is what this call does, so no caller has
    // to claim it.
    pub(in crate::vulkan) fn begin(
        device: &'a ash::Device,
        cmd: vk::CommandBuffer,
        flags: vk::CommandBufferUsageFlags,
    ) -> Result<Self, vk::Result> {
        let info = vk::CommandBufferBeginInfo::default().flags(flags);
        // SAFETY: the create-info is live for the call, and `cmd` belongs to this device. The
        // caller's fence wait is what guarantees it is not in flight.
        unsafe { device.begin_command_buffer(cmd, &info) }?;
        Ok(Self { device, cmd })
    }

    // Adopt a command buffer someone else began.
    //
    // # Safety
    // `cmd` must be in the recording state and must belong to `device`. Only
    // for the recording scopes whose `vkBeginCommandBuffer` sits in a caller
    // that cannot hand the recorder down (the one-shot upload helpers).
    pub(in crate::vulkan) unsafe fn assume_recording(
        device: &'a ash::Device,
        cmd: vk::CommandBuffer,
    ) -> Self {
        Self { device, cmd }
    }

    // Finish recording. Consumes the recorder, so nothing can record into the
    // buffer afterwards.
    pub(in crate::vulkan) fn end(self) -> Result<vk::CommandBuffer, vk::Result> {
        // SAFETY: `self` exists only for a buffer in the recording state, which is what
        // `end_command_buffer` requires.
        unsafe { self.device.end_command_buffer(self.cmd) }?;
        Ok(self.cmd)
    }

    // The command buffer, for the submit call and for the extension loaders
    // this surface does not wrap.
    pub(in crate::vulkan) fn raw(&self) -> vk::CommandBuffer {
        self.cmd
    }

    pub(in crate::vulkan) fn bind_pipeline(
        &self,
        bind_point: vk::PipelineBindPoint,
        pipeline: &OwnedPipeline,
    ) {
        // SAFETY: `self.cmd` is in the recording state by construction, and the pipeline is alive
        // for the call because this borrows its owner.
        unsafe {
            self.device
                .cmd_bind_pipeline(self.cmd, bind_point, pipeline.handle())
        };
    }

    pub(in crate::vulkan) fn bind_descriptor_sets(
        &self,
        bind_point: vk::PipelineBindPoint,
        layout: &OwnedPipelineLayout,
        first_set: u32,
        sets: &[vk::DescriptorSet],
        dynamic_offsets: &[u32],
    ) {
        // SAFETY: `self.cmd` is in the recording state by construction, the layout is alive because
        // this borrows its owner, and the slices are live for the call. The sets outlive the
        // submission with the pool they were allocated from.
        unsafe {
            self.device.cmd_bind_descriptor_sets(
                self.cmd,
                bind_point,
                layout.handle(),
                first_set,
                sets,
                dynamic_offsets,
            )
        };
    }

    // Push one `#[repr(C)]` block. Typed, so the byte length comes from the
    // value rather than from a hand-written `size_of` beside a pointer cast.
    pub(in crate::vulkan) fn push_constants<T: bytemuck::NoUninit>(
        &self,
        layout: &OwnedPipelineLayout,
        stages: vk::ShaderStageFlags,
        offset: u32,
        value: &T,
    ) {
        self.push_constant_bytes(layout, stages, offset, bytemuck::bytes_of(value));
    }

    // Push a byte range, for the blocks assembled at runtime rather than from
    // one struct.
    pub(in crate::vulkan) fn push_constant_bytes(
        &self,
        layout: &OwnedPipelineLayout,
        stages: vk::ShaderStageFlags,
        offset: u32,
        bytes: &[u8],
    ) {
        // SAFETY: `self.cmd` is in the recording state by construction, the layout is alive because
        // this borrows its owner, and `bytes` is live for the call.
        unsafe {
            self.device
                .cmd_push_constants(self.cmd, layout.handle(), stages, offset, bytes)
        };
    }

    // Begin a render pass over `framebuffer`. Borrowing both owners is what
    // keeps them alive across the pass this opens.
    pub(in crate::vulkan) fn begin_render_pass(
        &self,
        render_pass: &OwnedRenderPass,
        framebuffer: &OwnedFramebuffer,
        area: vk::Rect2D,
        clear_values: &[vk::ClearValue],
    ) {
        let info = vk::RenderPassBeginInfo::default()
            .render_pass(render_pass.handle())
            .framebuffer(framebuffer.handle())
            .render_area(area)
            .clear_values(clear_values);
        // SAFETY: `self.cmd` is in the recording state by construction, the pass and framebuffer
        // are alive because this borrows their owners, and the info and its slice are live for the
        // call.
        unsafe {
            self.device
                .cmd_begin_render_pass(self.cmd, &info, vk::SubpassContents::INLINE)
        };
    }

    pub(in crate::vulkan) fn end_render_pass(&self) {
        // SAFETY: `self.cmd` is in the recording state by construction.
        unsafe { self.device.cmd_end_render_pass(self.cmd) };
    }

    pub(in crate::vulkan) fn set_viewport(&self, viewport: &vk::Viewport) {
        // SAFETY: `self.cmd` is in the recording state by construction, and the slice is live for
        // the call.
        unsafe {
            self.device
                .cmd_set_viewport(self.cmd, 0, std::slice::from_ref(viewport))
        };
    }

    pub(in crate::vulkan) fn set_scissor(&self, scissor: &vk::Rect2D) {
        // SAFETY: `self.cmd` is in the recording state by construction, and the slice is live for
        // the call.
        unsafe {
            self.device
                .cmd_set_scissor(self.cmd, 0, std::slice::from_ref(scissor))
        };
    }

    pub(in crate::vulkan) fn draw(
        &self,
        vertex_count: u32,
        instance_count: u32,
        first_vertex: u32,
        first_instance: u32,
    ) {
        // SAFETY: `self.cmd` is in the recording state by construction.
        unsafe {
            self.device.cmd_draw(
                self.cmd,
                vertex_count,
                instance_count,
                first_vertex,
                first_instance,
            )
        };
    }

    pub(in crate::vulkan) fn dispatch(&self, x: u32, y: u32, z: u32) {
        // SAFETY: `self.cmd` is in the recording state by construction.
        unsafe { self.device.cmd_dispatch(self.cmd, x, y, z) };
    }

    // The full barrier form, for a pass that carries buffer or image barriers.
    pub(in crate::vulkan) fn pipeline_barrier(
        &self,
        src_stage: vk::PipelineStageFlags,
        dst_stage: vk::PipelineStageFlags,
        memory: &[vk::MemoryBarrier],
        buffers: &[vk::BufferMemoryBarrier],
        images: &[vk::ImageMemoryBarrier],
    ) {
        // SAFETY: `self.cmd` is in the recording state by construction, and the barriers and the
        // handles they name are live for the call.
        unsafe {
            self.device.cmd_pipeline_barrier(
                self.cmd,
                src_stage,
                dst_stage,
                vk::DependencyFlags::empty(),
                memory,
                buffers,
                images,
            )
        };
    }

    pub(in crate::vulkan) fn bind_vertex_buffers(
        &self,
        first_binding: u32,
        buffers: &[vk::Buffer],
        offsets: &[vk::DeviceSize],
    ) {
        // SAFETY: `self.cmd` is in the recording state by construction, and the buffers and the
        // slices naming them are live for the call.
        unsafe {
            self.device
                .cmd_bind_vertex_buffers(self.cmd, first_binding, buffers, offsets)
        };
    }

    pub(in crate::vulkan) fn copy_buffer(
        &self,
        src: vk::Buffer,
        dst: vk::Buffer,
        regions: &[vk::BufferCopy],
    ) {
        // SAFETY: `self.cmd` is in the recording state by construction, and the buffers and the
        // region slice are live for the call.
        unsafe { self.device.cmd_copy_buffer(self.cmd, src, dst, regions) };
    }

    pub(in crate::vulkan) fn write_timestamp(
        &self,
        stage: vk::PipelineStageFlags,
        pool: vk::QueryPool,
        query: u32,
    ) {
        // SAFETY: `self.cmd` is in the recording state by construction, and the query pool is live
        // for the call.
        unsafe {
            self.device
                .cmd_write_timestamp(self.cmd, stage, pool, query)
        };
    }
}