[−][src]Trait gfx_hal::command::CommandBuffer

pub trait CommandBuffer<B: Backend>: Debug + Any + Send + Sync {
    unsafe fn begin(
        &mut self, 
        flags: CommandBufferFlags, 
        inheritance_info: CommandBufferInheritanceInfo<B>
    );

    unsafe fn finish(&mut self);

    unsafe fn reset(&mut self, release_resources: bool);

    unsafe fn pipeline_barrier<'a, T>(
        &mut self, 
        stages: Range<PipelineStage>, 
        dependencies: Dependencies, 
        barriers: T
    )
    where
        T: IntoIterator,
        T::Item: Borrow<Barrier<'a, B>>;

    unsafe fn fill_buffer(
        &mut self, 
        buffer: &B::Buffer, 
        range: SubRange, 
        data: u32
    );

    unsafe fn update_buffer(
        &mut self, 
        buffer: &B::Buffer, 
        offset: Offset, 
        data: &[u8]
    );

    unsafe fn clear_image<T>(
        &mut self, 
        image: &B::Image, 
        layout: Layout, 
        value: ClearValue, 
        subresource_ranges: T
    )
    where
        T: IntoIterator,
        T::Item: Borrow<SubresourceRange>;

    unsafe fn clear_attachments<T, U>(&mut self, clears: T, rects: U)
    where
        T: IntoIterator,
        T::Item: Borrow<AttachmentClear>,
        U: IntoIterator,
        U::Item: Borrow<ClearRect>;

    unsafe fn resolve_image<T>(
        &mut self, 
        src: &B::Image, 
        src_layout: Layout, 
        dst: &B::Image, 
        dst_layout: Layout, 
        regions: T
    )
    where
        T: IntoIterator,
        T::Item: Borrow<ImageResolve>;

    unsafe fn blit_image<T>(
        &mut self, 
        src: &B::Image, 
        src_layout: Layout, 
        dst: &B::Image, 
        dst_layout: Layout, 
        filter: Filter, 
        regions: T
    )
    where
        T: IntoIterator,
        T::Item: Borrow<ImageBlit>;

    unsafe fn bind_index_buffer(&mut self, view: IndexBufferView<B>);

    unsafe fn bind_vertex_buffers<I, T>(
        &mut self, 
        first_binding: BufferIndex, 
        buffers: I
    )
    where
        I: IntoIterator<Item = (T, SubRange)>,
        T: Borrow<B::Buffer>;

    unsafe fn set_viewports<T>(&mut self, first_viewport: u32, viewports: T)
    where
        T: IntoIterator,
        T::Item: Borrow<Viewport>;

    unsafe fn set_scissors<T>(&mut self, first_scissor: u32, rects: T)
    where
        T: IntoIterator,
        T::Item: Borrow<Rect>;

    unsafe fn set_stencil_reference(&mut self, faces: Face, value: StencilValue);

    unsafe fn set_stencil_read_mask(&mut self, faces: Face, value: StencilValue);

    unsafe fn set_stencil_write_mask(
        &mut self, 
        faces: Face, 
        value: StencilValue
    );

    unsafe fn set_blend_constants(&mut self, color: ColorValue);

    unsafe fn set_depth_bounds(&mut self, bounds: Range<f32>);

    unsafe fn set_line_width(&mut self, width: f32);

    unsafe fn set_depth_bias(&mut self, depth_bias: DepthBias);

    unsafe fn begin_render_pass<T>(
        &mut self, 
        render_pass: &B::RenderPass, 
        framebuffer: &B::Framebuffer, 
        render_area: Rect, 
        clear_values: T, 
        first_subpass: SubpassContents
    )
    where
        T: IntoIterator,
        T::Item: Borrow<ClearValue>;

    unsafe fn next_subpass(&mut self, contents: SubpassContents);

    unsafe fn end_render_pass(&mut self);

    unsafe fn bind_graphics_pipeline(&mut self, pipeline: &B::GraphicsPipeline);

    unsafe fn bind_graphics_descriptor_sets<I, J>(
        &mut self, 
        layout: &B::PipelineLayout, 
        first_set: usize, 
        sets: I, 
        offsets: J
    )
    where
        I: IntoIterator,
        I::Item: Borrow<B::DescriptorSet>,
        J: IntoIterator,
        J::Item: Borrow<DescriptorSetOffset>;

    unsafe fn bind_compute_pipeline(&mut self, pipeline: &B::ComputePipeline);

    unsafe fn bind_compute_descriptor_sets<I, J>(
        &mut self, 
        layout: &B::PipelineLayout, 
        first_set: usize, 
        sets: I, 
        offsets: J
    )
    where
        I: IntoIterator,
        I::Item: Borrow<B::DescriptorSet>,
        J: IntoIterator,
        J::Item: Borrow<DescriptorSetOffset>;

    unsafe fn dispatch(&mut self, count: WorkGroupCount);

    unsafe fn dispatch_indirect(&mut self, buffer: &B::Buffer, offset: Offset);

    unsafe fn copy_buffer<T>(
        &mut self, 
        src: &B::Buffer, 
        dst: &B::Buffer, 
        regions: T
    )
    where
        T: IntoIterator,
        T::Item: Borrow<BufferCopy>;

    unsafe fn copy_image<T>(
        &mut self, 
        src: &B::Image, 
        src_layout: Layout, 
        dst: &B::Image, 
        dst_layout: Layout, 
        regions: T
    )
    where
        T: IntoIterator,
        T::Item: Borrow<ImageCopy>;

    unsafe fn copy_buffer_to_image<T>(
        &mut self, 
        src: &B::Buffer, 
        dst: &B::Image, 
        dst_layout: Layout, 
        regions: T
    )
    where
        T: IntoIterator,
        T::Item: Borrow<BufferImageCopy>;

    unsafe fn copy_image_to_buffer<T>(
        &mut self, 
        src: &B::Image, 
        src_layout: Layout, 
        dst: &B::Buffer, 
        regions: T
    )
    where
        T: IntoIterator,
        T::Item: Borrow<BufferImageCopy>;

    unsafe fn draw(
        &mut self, 
        vertices: Range<VertexCount>, 
        instances: Range<InstanceCount>
    );

    unsafe fn draw_indexed(
        &mut self, 
        indices: Range<IndexCount>, 
        base_vertex: VertexOffset, 
        instances: Range<InstanceCount>
    );

    unsafe fn draw_indirect(
        &mut self, 
        buffer: &B::Buffer, 
        offset: Offset, 
        draw_count: DrawCount, 
        stride: u32
    );

    unsafe fn draw_indexed_indirect(
        &mut self, 
        buffer: &B::Buffer, 
        offset: Offset, 
        draw_count: DrawCount, 
        stride: u32
    );

    unsafe fn set_event(&mut self, event: &B::Event, stages: PipelineStage);

    unsafe fn reset_event(&mut self, event: &B::Event, stages: PipelineStage);

    unsafe fn wait_events<'a, I, J>(
        &mut self, 
        events: I, 
        stages: Range<PipelineStage>, 
        barriers: J
    )
    where
        I: IntoIterator,
        I::Item: Borrow<B::Event>,
        J: IntoIterator,
        J::Item: Borrow<Barrier<'a, B>>;

    unsafe fn begin_query(&mut self, query: Query<B>, flags: ControlFlags);

    unsafe fn end_query(&mut self, query: Query<B>);

    unsafe fn reset_query_pool(
        &mut self, 
        pool: &B::QueryPool, 
        queries: Range<Id>
    );

    unsafe fn copy_query_pool_results(
        &mut self, 
        pool: &B::QueryPool, 
        queries: Range<Id>, 
        buffer: &B::Buffer, 
        offset: Offset, 
        stride: Offset, 
        flags: ResultFlags
    );

    unsafe fn write_timestamp(&mut self, stage: PipelineStage, query: Query<B>);

    unsafe fn push_graphics_constants(
        &mut self, 
        layout: &B::PipelineLayout, 
        stages: ShaderStageFlags, 
        offset: u32, 
        constants: &[u32]
    );

    unsafe fn push_compute_constants(
        &mut self, 
        layout: &B::PipelineLayout, 
        offset: u32, 
        constants: &[u32]
    );

    unsafe fn execute_commands<'a, T, I>(&mut self, cmd_buffers: I)
    where
        T: 'a + Borrow<B::CommandBuffer>,
        I: IntoIterator<Item = &'a T>;

    unsafe fn insert_debug_marker(&mut self, name: &str, color: u32);

    unsafe fn begin_debug_marker(&mut self, name: &str, color: u32);

    unsafe fn end_debug_marker(&mut self);

    unsafe fn begin_primary(&mut self, flags: CommandBufferFlags) { ... }
}

A trait that describes all the operations that must be provided by a Backend's command buffer.

Required methods

unsafe fn begin(
    &mut self,
    flags: CommandBufferFlags,
    inheritance_info: CommandBufferInheritanceInfo<B>
)

Begins recording commands to a command buffer.

unsafe fn finish(&mut self)

Finish recording commands to a command buffer.

unsafe fn reset(&mut self, release_resources: bool)

Empties the command buffer, optionally releasing all resources from the commands that have been submitted.

unsafe fn pipeline_barrier<'a, T>(
    &mut self,
    stages: Range<PipelineStage>,
    dependencies: Dependencies,
    barriers: T
) where
    T: IntoIterator,
    T::Item: Borrow<Barrier<'a, B>>, 

Inserts a synchronization dependency between pipeline stages in the command buffer.

unsafe fn fill_buffer(&mut self, buffer: &B::Buffer, range: SubRange, data: u32)

Fill a buffer with the given u32 value.

unsafe fn update_buffer(
    &mut self,
    buffer: &B::Buffer,
    offset: Offset,
    data: &[u8]
)

Copy data from the given slice into a buffer.

unsafe fn clear_image<T>(
    &mut self,
    image: &B::Image,
    layout: Layout,
    value: ClearValue,
    subresource_ranges: T
) where
    T: IntoIterator,
    T::Item: Borrow<SubresourceRange>, 

Clears an image to the given color/depth/stencil.

unsafe fn clear_attachments<T, U>(&mut self, clears: T, rects: U) where
    T: IntoIterator,
    T::Item: Borrow<AttachmentClear>,
    U: IntoIterator,
    U::Item: Borrow<ClearRect>, 

Takes an iterator of attachments and an iterator of rect's, and clears the given rect's for each attachment.

unsafe fn resolve_image<T>(
    &mut self,
    src: &B::Image,
    src_layout: Layout,
    dst: &B::Image,
    dst_layout: Layout,
    regions: T
) where
    T: IntoIterator,
    T::Item: Borrow<ImageResolve>, 

"Resolves" a multisampled image, converting it into a non-multisampled image. Takes an iterator of regions to apply the resolution to.

unsafe fn blit_image<T>(
    &mut self,
    src: &B::Image,
    src_layout: Layout,
    dst: &B::Image,
    dst_layout: Layout,
    filter: Filter,
    regions: T
) where
    T: IntoIterator,
    T::Item: Borrow<ImageBlit>, 

Copies regions from the source to destination image, applying scaling, filtering and potentially format conversion.

unsafe fn bind_index_buffer(&mut self, view: IndexBufferView<B>)

Bind the index buffer view, making it the "current" one that draw commands will operate on.

unsafe fn bind_vertex_buffers<I, T>(
    &mut self,
    first_binding: BufferIndex,
    buffers: I
) where
    I: IntoIterator<Item = (T, SubRange)>,
    T: Borrow<B::Buffer>, 

Bind the vertex buffer set, making it the "current" one that draw commands will operate on.

Each buffer passed corresponds to the vertex input binding with the same index, starting from an offset index first_binding. For example an iterator with two items and first_binding of 1 would fill vertex buffer binding numbers 1 and 2.

This binding number refers only to binding points for vertex buffers and is completely separate from the binding numbers of Descriptors in DescriptorSets. It needs to match with the VertexBufferDesc and AttributeDescs to which the data from each bound vertex buffer should flow.

The buffers iterator should yield the Buffer to bind, as well as a subrange, in bytes, into that buffer where the vertex data that should be bound.

unsafe fn set_viewports<T>(&mut self, first_viewport: u32, viewports: T) where
    T: IntoIterator,
    T::Item: Borrow<Viewport>, 

Set the viewport parameters for the rasterizer.

Each viewport passed corresponds to the viewport with the same index, starting from an offset index first_viewport.

Errors

This function does not return an error. Invalid usage of this function will result in undefined behavior.

  • Command buffer must be in recording state.
  • Number of viewports must be between 1 and max_viewports - first_viewport.
  • The first viewport must be less than max_viewports.
  • Only queues with graphics capability support this function.
  • The bound pipeline must not have baked viewport state.
  • All viewports used by the pipeline must be specified before the first draw call.

unsafe fn set_scissors<T>(&mut self, first_scissor: u32, rects: T) where
    T: IntoIterator,
    T::Item: Borrow<Rect>, 

Set the scissor rectangles for the rasterizer.

Each scissor corresponds to the viewport with the same index, starting from an offset index first_scissor.

Errors

This function does not return an error. Invalid usage of this function will result in undefined behavior.

  • Command buffer must be in recording state.
  • Number of scissors must be between 1 and max_viewports - first_scissor.
  • The first scissor must be less than max_viewports.
  • Only queues with graphics capability support this function.
  • The bound pipeline must not have baked scissor state.
  • All scissors used by the pipeline must be specified before the first draw call.

unsafe fn set_stencil_reference(&mut self, faces: Face, value: StencilValue)

Sets the stencil reference value for comparison operations and store operations. Will be used on the LHS of stencil compare ops and as store value when the store op is Reference.

unsafe fn set_stencil_read_mask(&mut self, faces: Face, value: StencilValue)

Sets the stencil read mask.

unsafe fn set_stencil_write_mask(&mut self, faces: Face, value: StencilValue)

Sets the stencil write mask.

unsafe fn set_blend_constants(&mut self, color: ColorValue)

Set the blend constant values dynamically.

unsafe fn set_depth_bounds(&mut self, bounds: Range<f32>)

Set the depth bounds test values dynamically.

unsafe fn set_line_width(&mut self, width: f32)

Set the line width dynamically.

Only valid to call if Features::LINE_WIDTH is enabled.

unsafe fn set_depth_bias(&mut self, depth_bias: DepthBias)

Set the depth bias dynamically.

unsafe fn begin_render_pass<T>(
    &mut self,
    render_pass: &B::RenderPass,
    framebuffer: &B::Framebuffer,
    render_area: Rect,
    clear_values: T,
    first_subpass: SubpassContents
) where
    T: IntoIterator,
    T::Item: Borrow<ClearValue>, 

Begins recording commands for a render pass on the given framebuffer. render_area is the section of the framebuffer to render, clear_values is an iterator of ClearValueRaw's to use to use for clear_* commands, one for each attachment of the render pass that has a clear operation. first_subpass specifies, for the first subpass, whether the rendering commands are provided inline or whether the render pass is composed of subpasses.

unsafe fn next_subpass(&mut self, contents: SubpassContents)

Steps to the next subpass in the current render pass.

unsafe fn end_render_pass(&mut self)

Finishes recording commands for the current a render pass.

unsafe fn bind_graphics_pipeline(&mut self, pipeline: &B::GraphicsPipeline)

Bind a graphics pipeline.

Errors

This function does not return an error. Invalid usage of this function will result in an error on finish.

  • Command buffer must be in recording state.
  • Only queues with graphics capability support this function.

unsafe fn bind_graphics_descriptor_sets<I, J>(
    &mut self,
    layout: &B::PipelineLayout,
    first_set: usize,
    sets: I,
    offsets: J
) where
    I: IntoIterator,
    I::Item: Borrow<B::DescriptorSet>,
    J: IntoIterator,
    J::Item: Borrow<DescriptorSetOffset>, 

Takes an iterator of graphics DescriptorSet's, and binds them to the command buffer. first_set is the index that the first descriptor is mapped to in the command buffer.

unsafe fn bind_compute_pipeline(&mut self, pipeline: &B::ComputePipeline)

Bind a compute pipeline.

Errors

This function does not return an error. Invalid usage of this function will result in an error on finish.

  • Command buffer must be in recording state.
  • Only queues with compute capability support this function.

unsafe fn bind_compute_descriptor_sets<I, J>(
    &mut self,
    layout: &B::PipelineLayout,
    first_set: usize,
    sets: I,
    offsets: J
) where
    I: IntoIterator,
    I::Item: Borrow<B::DescriptorSet>,
    J: IntoIterator,
    J::Item: Borrow<DescriptorSetOffset>, 

Takes an iterator of compute DescriptorSet's, and binds them to the command buffer, first_set is the index that the first descriptor is mapped to in the command buffer.

unsafe fn dispatch(&mut self, count: WorkGroupCount)

Execute a workgroup in the compute pipeline. x, y and z are the number of local workgroups to dispatch along each "axis"; a total of xyz local workgroups will be created.

Errors

This function does not return an error. Invalid usage of this function will result in an error on finish.

  • Command buffer must be in recording state.
  • A compute pipeline must be bound using bind_compute_pipeline.
  • Only queues with compute capability support this function.
  • This function must be called outside of a render pass.
  • count must be less than or equal to Limits::max_compute_work_group_count

TODO:

unsafe fn dispatch_indirect(&mut self, buffer: &B::Buffer, offset: Offset)

Works similarly to dispatch() but reads parameters from the given buffer during execution.

unsafe fn copy_buffer<T>(
    &mut self,
    src: &B::Buffer,
    dst: &B::Buffer,
    regions: T
) where
    T: IntoIterator,
    T::Item: Borrow<BufferCopy>, 

Adds a command to copy regions from the source to destination buffer.

unsafe fn copy_image<T>(
    &mut self,
    src: &B::Image,
    src_layout: Layout,
    dst: &B::Image,
    dst_layout: Layout,
    regions: T
) where
    T: IntoIterator,
    T::Item: Borrow<ImageCopy>, 

Copies regions from the source to the destination images, which have the given layouts. No format conversion is done; the source and destination Layout's must have the same sized image formats (such as Rgba8Unorm and R32, both of which are 32 bits).

unsafe fn copy_buffer_to_image<T>(
    &mut self,
    src: &B::Buffer,
    dst: &B::Image,
    dst_layout: Layout,
    regions: T
) where
    T: IntoIterator,
    T::Item: Borrow<BufferImageCopy>, 

Copies regions from the source buffer to the destination image.

unsafe fn copy_image_to_buffer<T>(
    &mut self,
    src: &B::Image,
    src_layout: Layout,
    dst: &B::Buffer,
    regions: T
) where
    T: IntoIterator,
    T::Item: Borrow<BufferImageCopy>, 

Copies regions from the source image to the destination buffer.

unsafe fn draw(
    &mut self,
    vertices: Range<VertexCount>,
    instances: Range<InstanceCount>
)

Performs a non-indexed drawing operation, fetching vertex attributes from the currently bound vertex buffers. It performs instanced drawing, drawing instances.len() times with an instanceIndex starting with the start of the range.

unsafe fn draw_indexed(
    &mut self,
    indices: Range<IndexCount>,
    base_vertex: VertexOffset,
    instances: Range<InstanceCount>
)

Performs indexed drawing, drawing the range of indices given by the current index buffer and any bound vertex buffers. base_vertex specifies the vertex offset corresponding to index 0. That is, the offset into the vertex buffer is (current_index + base_vertex)

It also performs instanced drawing, identical to draw().

unsafe fn draw_indirect(
    &mut self,
    buffer: &B::Buffer,
    offset: Offset,
    draw_count: DrawCount,
    stride: u32
)

Functions identically to draw(), except the parameters are read from the given buffer, starting at offset and increasing stride bytes with each successive draw. Performs draw_count draws total. draw_count may be zero.

Each draw command in the buffer is a series of 4 u32 values specifying, in order, the number of vertices to draw, the number of instances to draw, the index of the first vertex to draw, and the instance ID of the first instance to draw.

unsafe fn draw_indexed_indirect(
    &mut self,
    buffer: &B::Buffer,
    offset: Offset,
    draw_count: DrawCount,
    stride: u32
)

Like draw_indirect(), this does indexed drawing a la draw_indexed() but reads the draw parameters out of the given buffer.

Each draw command in the buffer is a series of 5 values specifying, in order, the number of indices, the number of instances, the first index, the vertex offset, and the first instance. All are u32's except the vertex offset, which is an i32.

unsafe fn set_event(&mut self, event: &B::Event, stages: PipelineStage)

Signals an event once all specified stages of the shader pipeline have completed.

unsafe fn reset_event(&mut self, event: &B::Event, stages: PipelineStage)

Resets an event once all specified stages of the shader pipeline have completed.

unsafe fn wait_events<'a, I, J>(
    &mut self,
    events: I,
    stages: Range<PipelineStage>,
    barriers: J
) where
    I: IntoIterator,
    I::Item: Borrow<B::Event>,
    J: IntoIterator,
    J::Item: Borrow<Barrier<'a, B>>, 

Waits at some shader stage(s) until all events have been signalled.

  • src_stages specifies the shader pipeline stages in which the events were signalled.
  • dst_stages specifies the shader pipeline stages at which execution should wait.
  • barriers specifies a series of memory barriers to be executed before pipeline execution resumes.

unsafe fn begin_query(&mut self, query: Query<B>, flags: ControlFlags)

Begins a query operation. Queries count operations or record timestamps resulting from commands that occur between the beginning and end of the query, and save the results to the query pool.

unsafe fn end_query(&mut self, query: Query<B>)

End a query.

unsafe fn reset_query_pool(&mut self, pool: &B::QueryPool, queries: Range<Id>)

Reset/clear the values in the given range of the query pool.

unsafe fn copy_query_pool_results(
    &mut self,
    pool: &B::QueryPool,
    queries: Range<Id>,
    buffer: &B::Buffer,
    offset: Offset,
    stride: Offset,
    flags: ResultFlags
)

Copy query results into a buffer.

unsafe fn write_timestamp(&mut self, stage: PipelineStage, query: Query<B>)

Requests a timestamp to be written.

unsafe fn push_graphics_constants(
    &mut self,
    layout: &B::PipelineLayout,
    stages: ShaderStageFlags,
    offset: u32,
    constants: &[u32]
)

Modify constant data in a graphics pipeline. Push constants are intended to modify data in a pipeline more quickly than a updating the values inside a descriptor set.

Push constants must be aligned to 4 bytes, and to guarantee alignment, this function takes a &[u32] instead of a &[u8]. Note that the offset is still specified in units of bytes.

unsafe fn push_compute_constants(
    &mut self,
    layout: &B::PipelineLayout,
    offset: u32,
    constants: &[u32]
)

Modify constant data in a compute pipeline. Push constants are intended to modify data in a pipeline more quickly than a updating the values inside a descriptor set.

Push constants must be aligned to 4 bytes, and to guarantee alignment, this function takes a &[u32] instead of a &[u8]. Note that the offset is still specified in units of bytes.

unsafe fn execute_commands<'a, T, I>(&mut self, cmd_buffers: I) where
    T: 'a + Borrow<B::CommandBuffer>,
    I: IntoIterator<Item = &'a T>, 

Execute the given secondary command buffers.

unsafe fn insert_debug_marker(&mut self, name: &str, color: u32)

Debug mark the current spot in the command buffer.

unsafe fn begin_debug_marker(&mut self, name: &str, color: u32)

Start a debug marker at the current place in the command buffer.

unsafe fn end_debug_marker(&mut self)

End the last started debug marker scope.

Loading content...

Provided methods

unsafe fn begin_primary(&mut self, flags: CommandBufferFlags)

Begins recording a primary command buffer (that has no inheritance information).

Loading content...

Implementors

Loading content...