Struct web_glitz::rendering::GraphicsPipelineTaskBuilder

pub struct GraphicsPipelineTaskBuilder<'a, V, R, Vb, Ib, Rb, T> { /* fields omitted */ }

A builder interface that enforces valid sequencing of pipeline commands.

See ActiveGraphicsPipeline::task_builder.

Implementations

impl<'a, V, R, Vb, Ib, Rb, T> GraphicsPipelineTaskBuilder<'a, V, R, Vb, Ib, Rb, T>

pub fn bind_vertex_buffers<VbNew>(
    self,
    vertex_buffers: VbNew
) -> GraphicsPipelineTaskBuilder<'a, V, R, VbNew, Ib, Rb, Sequence<T, BindVertexBuffersCommand, PipelineTaskContext>> where
    V: TypedVertexInputLayout,
    VbNew: TypedVertexBuffers<Layout = V>,
    T: GpuTask<PipelineTaskContext>, 

Binds typed a (set of) vertex buffer(s) to the active graphics pipeline.

When the active graphics pipeline is invoked (see [draw] and [draw_indexed]), then the vertex_buffers define a vertex input array for the pipeline.

The vertex_buffers must be a TypedVertexBuffers type with a vertex attribute layout (see [TypedVertexBuffers::VertexAttributeLayout]) that matches the vertex attribute layout specified for the pipeline. This is statically verified by the type system; if this compiles, then this performs no further runtime checks on the compatibility of the vertex buffers with the active graphics pipeline, it only checks that every buffer that is bound belongs to the same context as the pipeline. This will not result in invalid behaviour as long as vertex_buffers meets the safety contract on the TypedVertexBuffers trait (implementing TypedVertexBuffers is unsafe, but several safe implementations are provided by this library).

See also [bind_vertex_buffers_untyped] for an unsafe alternative with relaxed type constraints.

Panics

Panics if a vertex buffers belongs to different rendering context.

pub unsafe fn bind_vertex_buffers_untyped<VbNew>(
    self,
    vertex_buffers: VbNew
) -> GraphicsPipelineTaskBuilder<'a, V, R, VbNew, Ib, Rb, Sequence<T, BindVertexBuffersCommand, PipelineTaskContext>> where
    VbNew: VertexBuffers,
    T: GpuTask<PipelineTaskContext>, 

Binds a (set of) vertex buffer(s) to the active graphics pipeline.

When the active graphics pipeline is invoked (see [draw] and [draw_indexed]), then the vertex_buffers define a vertex input array for the pipeline.

Unsafe

The vertex buffers must contain data compatible with the vertex input layout specified for the pipeline.

This function is an unsafe alternative to [bind_vertex_buffers] with relaxed type constraints. If your vertex input data has a statically known layout, consider implementing [TypedVertexInputBuffers] for your data and specifying a TypedVertexInputLayout for your pipeline (see [GraphicsPipelineDescriptorBuilder::typed_vertex_input_layout]; this will allow you to use [bind_vertex_buffers] instead. Note that [TypedVertexInputBuffers] is already implemented for any tuple of buffers (up to 16 buffers) where each buffer contains a slice of [Vertex] types.

Panics

Panics of any of the vertex buffers belong to a different context than the pipeline.

pub fn bind_index_buffer<IbNew>(
    self,
    index_buffer: IbNew
) -> GraphicsPipelineTaskBuilder<'a, V, R, Vb, IbNew, Rb, Sequence<T, BindIndexBufferCommand, PipelineTaskContext>> where
    IbNew: IndexData,
    T: GpuTask<PipelineTaskContext>, 

Binds an index buffer to the graphics pipeline.

A graphics pipeline typically requires a source of vertex data (see [bind_vertex_buffers]). This vertex data defines an array of vertices which by itself can serve as the vertex input stream for the pipeline, where the vertices are simply streamed once in the canonical array order, see [draw_command]. When an index buffer is specified, then the pipeline may also be executed in "indexed" mode, see [draw_indexed]. In indexed mode the indices in the index buffer determine the vertex sequence of the vertex stream. For example, if the first index is 8, then the first vertex in the vertex stream is the 9th vertex in the vertex array. The same index may also occur more than once in the index buffer, in which case the same vertex will appear more than once in the vertex stream.

pub fn bind_resources<RbNew>(
    self,
    resource_bindings: RbNew
) -> GraphicsPipelineTaskBuilder<'a, V, R, Vb, Ib, RbNew, Sequence<T, BindResourcesCommand<RbNew::BindGroups>, PipelineTaskContext>> where
    R: TypedResourceBindingsLayout,
    RbNew: TypedResourceBindings<Layout = R>,
    T: GpuTask<PipelineTaskContext>, 

Binds one or more bind groups containing typed resource groups to the active graphics pipeline.

When the pipeline is invoked, each invocation may access the bound resources.

The resource_bindings must implement TypedResourceBindings and the TypedResourceBindings::Layout must match the TypedResourceBindingsLayout specified for the pipeline (see [GraphicsPipelineDescriptorBuilder::typed_resource_bindings_layout]); this is statically verified by the type-checker. No further runtime checks are performed to ensure compatibility of the resource bindings with the pipeline.

See also [bind_resources_untyped] for an unsafe alternative with relaxed type constraints.

Panics

Panics if any of the bind groups belong to a different context than the pipeline.

pub unsafe fn bind_resources_untyped<RbNew>(
    self,
    resource_bindings: RbNew
) -> GraphicsPipelineTaskBuilder<'a, V, R, Vb, Ib, RbNew, Sequence<T, BindResourcesCommand<RbNew::BindGroups>, PipelineTaskContext>> where
    RbNew: ResourceBindings,
    T: GpuTask<PipelineTaskContext>, 

Binds one or more bind groups to the active graphics pipeline.

When the pipeline is invoked, each invocation may access the bound resources.

Unsafe

The resource bindings must be compatible with the resource bindings layout specified for the pipeline.

This function is an unsafe alternative to bind_resources with relaxed type constraints. If your resource bindings layout is statically know, consider implementing TypedResourceBindings for your bind groups and specifying a TypedResourceBindingsLayout for your pipeline (see [GraphicsPipelineDescriptorBuilder::typed_resource_bindings_layout]); this will allow you to use [bind_resources] instead. Note that TypedResourceBindings is implemented for any tuple of bind groups where the resources in each bind group implement [Resources].

Panics

Panics if any of the bind groups belong to a different context than the pipeline.

pub fn draw(
    self,
    vertex_count: usize,
    instance_count: usize
) -> GraphicsPipelineTaskBuilder<'a, V, R, Vb, Ib, R, Sequence<T, DrawCommand, PipelineTaskContext>> where
    Vb: VertexBuffers,
    Rb: ResourceBindings,
    T: GpuTask<PipelineTaskContext>, 

Creates a DrawCommand that will execute the active graphics pipeline, streaming vertex_count vertices for instance_count instances from the currently bound vertex buffers.

If the pipeline requires vertex buffers, then this command may only be added to the builder after appropriate vertex buffers have been bound (see [bind_vertex_buffers]). If the pipeline requires resources, then this command may only be added to the builder after appropriate resources have been bound (see [bind_resources]).

This will draw to the framebuffer that created the encapsulating [PipelineTask] (see [Framebuffer::pipeline_task]). The pipeline's first color output will be stored to the framebuffer's first color buffer (if present), the second color output will be stored to the framebuffer's second color buffer (if present), etc. The pipeline's depth test (if enabled) may update the framebuffer's depth-stencil buffer (if it present and is a DepthRenderable or DepthStencilRenderable format, otherwise the depth test will act as if it was disabled). The pipeline's stencil test (if enabled) may update the framebuffer's depth-stencil buffer (if it is present and is StencilRenderable or DepthStencilRenderable format, otherwise the stencil test will act as if was disabled).

See also [draw_indexed] for indexed mode drawing with an index buffer.

Example

let render_pass = render_target.create_render_pass(|framebuffer| {
    framebuffer.pipeline_task(&graphics_pipeline, |active_pipeline| {
        active_pipeline.task_builder()
            .bind_vertex_buffers(vertex_buffers)
            .bind_resources(resources)
            .draw(16, 1)
            .finish()
    })
});

In this example graphics_pipeline is a GraphicsPipeline, see GraphicsPipeline and [RenderingContext::create_graphics_pipeline] for details; vertex_buffers is a set of VertexBuffers; resources is a user-defined type for which the [Resources] trait is implemented, see [Resources] for details.

pub fn draw_indexed(
    self,
    index_count: usize,
    instance_count: usize
) -> GraphicsPipelineTaskBuilder<'a, V, R, Vb, Ib, R, Sequence<T, DrawIndexedCommand, PipelineTaskContext>> where
    Vb: VertexBuffers,
    Ib: IndexData,
    Rb: ResourceBindings,
    T: GpuTask<PipelineTaskContext>, 

Creates a DrawIndexedCommand that will execute the active graphics pipeline, streaming index_count vertex indices for instance_count instances from the currently bound index buffer, which produces a vertex stream by indexing into the vertex array defined by the currently bound per-vertex vertex buffers.

This command may only be added to the builder after an index buffer has been bound (see [bind_index_buffer]. If the pipeline requires vertex buffers, then this command may only be added to the builder after appropriate vertex buffers have been bound (see [bind_vertex_buffers]). If the pipeline requires resources, then this command may only be added to the builder after appropriate resources have been bound (see [bind_resources]).

This will draw to the framebuffer that created the encapsulating [PipelineTask] (see [Framebuffer::pipeline_task]). The pipeline's first color output will be stored to the framebuffer's first color buffer (if present), the second color output will be stored to the framebuffer's second color buffer (if present), etc. The pipeline's depth test (if enabled) may update the framebuffer's depth-stencil buffer (if it present and is a DepthRenderable or DepthStencilRenderable format, otherwise the depth test will act as if it was disabled). The pipeline's stencil test (if enabled) may update the framebuffer's depth-stencil buffer (if it is present and is StencilRenderable or DepthStencilRenderable format, otherwise the stencil test will act as if was disabled).

See also [draw] for drawing without an index buffer.

Example

let render_pass = render_target.create_render_pass(|framebuffer| {
    framebuffer.pipeline_task(&graphics_pipeline, |active_pipeline| {
        active_pipeline.task_builder()
            .bind_vertex_buffers(vertex_buffers)
            .bind_index_buffer(index_buffer)
            .bind_resources(resources)
            .draw_indexed(16, 1)
            .finish()
    })
});

In this example graphics_pipeline is a GraphicsPipeline, see GraphicsPipeline and [RenderingContext::create_graphics_pipeline] for details; vertex_buffers is a set of VertexBuffers; index_buffer is an [IndexBuffer]; resources is a user-defined type for which the [Resources] trait is implemented, see [Resources] for details.

pub fn finish(self) -> T

Finishes the builder and returns the resulting pipeline task.