Enum rafx_api::RafxCommandBuffer

pub enum RafxCommandBuffer {
    Empty(RafxCommandBufferEmpty),
}

A list of commands recorded by the CPU and submitted to the GPU.

It cannot be created directly. It must be allocated out of a pool.

The command pool and all command buffers allocated from it share memory. The standard rust rules about mutability apply but are not enforced at compile time or runtime.

• Do not modify two command buffers from the same pool concurrently
• Do not allocate from a command pool while modifying one of its command buffers
• Once a command buffer is submitted to the GPU, do not modify its pool, or any command buffers created from it, until the GPU completes its work.

In general, do not modify textures, buffers, command buffers, or other GPU resources while a command buffer referencing them is submitted. Additionally, these resources must persist for the entire duration of the submitted workload.

Semaphores and fences can be used for achieve the more fine-grained scheduling necessary to modify resources that are referenced from a submitted and in-use command buffer.

Command pools MAY be dropped if they are in use by the GPU, but the command pool must not be dropped. Dropped command pools that are not returned to the pool will not be available for reuse.

Variants

Empty

Tuple Fields of Empty

0: RafxCommandBufferEmpty

Implementations

impl RafxCommandBuffer

pub fn begin(&self) -> RafxResult<()>

Begins writing a command buffer. This can only be called when the command buffer is first allocated or if the pool has been reset since it was last written

pub fn end(&self) -> RafxResult<()>

End writing the command buffer. This must be called before submitting the command buffer to the GPU

pub fn return_to_pool(&self) -> RafxResult<()>

This returns the command buffer to the pool, allowing it to be allocated again. This must not be called if the command buffer is still in-use by the GPU.

Dropping a command buffer without returning it to the pool is allowed. In this case, it remains usable by the GPU until the command pool is dropped. However, even if the command buffer is reset, this command buffer will not be available for use again.

pub fn cmd_begin_render_pass(
    &self,
    color_targets: &[RafxColorRenderTargetBinding<'_>],
    depth_target: Option<RafxDepthStencilRenderTargetBinding<'_>>
) -> RafxResult<()>

Begin a new renderpass using the given color targets and depth targets. This is similar to beginning a renderpass in vulkan.

Some command must be used within a renderpass and some may only be used outside of a renderpass.

pub fn cmd_end_render_pass(&self) -> RafxResult<()>

Finish the renderpass.

pub fn cmd_set_viewport(
    &self,
    x: f32,
    y: f32,
    width: f32,
    height: f32,
    depth_min: f32,
    depth_max: f32
) -> RafxResult<()>

Set the viewport state. This may be called inside or outside of a renderpass.

Viewport state defines where on the screen the draw will occur.

pub fn cmd_set_scissor(
    &self,
    x: u32,
    y: u32,
    width: u32,
    height: u32
) -> RafxResult<()>

Set the scissor state. This may be called inside or outside of a renderpass.

Scissor state can be used to restrict rendering to a specific area of a render target

pub fn cmd_set_stencil_reference_value(&self, value: u32) -> RafxResult<()>

Set the stencil buffer state. This may be called inside or outside of a renderpass.

Stencil buffer state is used with a stencil render target to discard rendering results in specific portions of a render target

pub fn cmd_bind_pipeline(&self, pipeline: &RafxPipeline) -> RafxResult<()>

Binds the given pipeline - which represents fixed-function state and shaders. Draw calls that produce primitives or dispatch compute will use the bound pipeline.

pub fn cmd_bind_vertex_buffers(
    &self,
    first_binding: u32,
    bindings: &[RafxVertexBufferBinding<'_>]
) -> RafxResult<()>

Binds a buffer as a vertex buffer. Draw calls will use this buffer as input.

Multiple buffers can be bound, but the number is limited depending on API/hardware. Less than 4 is a relatively safe number.

pub fn cmd_bind_index_buffer(
    &self,
    binding: &RafxIndexBufferBinding<'_>
) -> RafxResult<()>

Binds a buffer as a vertex buffer. Draw calls will use this buffer as input.

Multiple buffers can be bound, but the number is limited depending on API/hardware. Less than 4 is a relatively safe number.

pub fn cmd_bind_descriptor_set(
    &self,
    descriptor_set_array: &RafxDescriptorSetArray,
    index: u32
) -> RafxResult<()>

Binds a descriptor set for use by the shader in the currently bound pipeline.

Multiple descriptor sets can be bound, but the number is limited to 4.

pub fn cmd_bind_descriptor_set_handle(
    &self,
    root_signature: &RafxRootSignature,
    set_index: u32,
    descriptor_set_handle: &RafxDescriptorSetHandle
) -> RafxResult<()>

Binds a descriptor set for use by the shader in the currently bound pipeline.

This is the same as cmd_bind_descriptor_set but uses a lightweight, opaque handle. This may make using the API easier in multi-threaded scenarios.

pub fn cmd_draw(&self, vertex_count: u32, first_vertex: u32) -> RafxResult<()>

Draw primitives using the currently bound pipeline and vertex buffer

pub fn cmd_draw_instanced(
    &self,
    vertex_count: u32,
    first_vertex: u32,
    instance_count: u32,
    first_instance: u32
) -> RafxResult<()>

Draw instanced primitives using the currently bound pipeline and vertex buffer

pub fn cmd_draw_indexed(
    &self,
    index_count: u32,
    first_index: u32,
    vertex_offset: i32
) -> RafxResult<()>

Draw primitives using the currently bound pipeline, vertex, and index buffer index_count: Number of vertices to draw first_index: Base index within the index buffer vertex_offset: Value added to the vertex index before indexing into the vertex buffer

pub fn cmd_draw_indexed_instanced(
    &self,
    index_count: u32,
    first_index: u32,
    instance_count: u32,
    first_instance: u32,
    vertex_offset: i32
) -> RafxResult<()>

Draw instanced primitives using the currently bound pipeline, vertex, and index buffer

pub fn cmd_dispatch(
    &self,
    group_count_x: u32,
    group_count_y: u32,
    group_count_z: u32
) -> RafxResult<()>

Dispatch the current pipeline. Only usable with compute pipelines.

pub fn cmd_resource_barrier(
    &self,
    buffer_barriers: &[RafxBufferBarrier<'_>],
    texture_barriers: &[RafxTextureBarrier<'_>]
) -> RafxResult<()>

Add a memory barrier for one or more resources. This must occur OUTSIDE of a renderpass.

pub fn cmd_copy_buffer_to_buffer(
    &self,
    src_buffer: &RafxBuffer,
    dst_buffer: &RafxBuffer,
    src_offset: u64,
    dst_offset: u64,
    size: u64
) -> RafxResult<()>

Copy the contents of one buffer into another. This occurs on the GPU and allows modifying resources that are not accessible to the CPU.

pub fn cmd_copy_buffer_to_texture(
    &self,
    src_buffer: &RafxBuffer,
    dst_texture: &RafxTexture,
    params: &RafxCmdCopyBufferToTextureParams
) -> RafxResult<()>

Copy the contents of a buffer into a texture. This occurs on the GPU and allows modifying resources that are not accessible to the CPU.

pub fn empty_command_buffer(&self) -> Option<&RafxCommandBufferEmpty>

Get the underlying metal API object. This provides access to any internally created metal objects.

Trait Implementations

impl Debug for RafxCommandBuffer

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.