diff --git a/wgpu/src/lib.rs b/wgpu/src/lib.rs index ad17151ea1a..cd20de85edb 100644 --- a/wgpu/src/lib.rs +++ b/wgpu/src/lib.rs @@ -608,9 +608,21 @@ impl Drop for CommandEncoder { } } -/// In-progress recording of a render pass. +/// In-progress recording of a render pass: a list of render commands in a [`CommandEncoder`]. /// -/// It can be created with [`CommandEncoder::begin_render_pass`]. +/// It can be created with [`CommandEncoder::begin_render_pass()`], whose [`RenderPassDescriptor`] +/// specifies the attachments (textures) that will be rendered to. +/// +/// Most of the methods on `RenderPass` serve one of two purposes, identifiable by their names: +/// +/// * `draw_*()`: Drawing (that is, encoding a render command, which, when executed by the GPU, will +/// rasterize something and execute shaders). +/// * `set_*()`: Setting part of the [render state](https://gpuweb.github.io/gpuweb/#renderstate) +/// for future drawing commands. +/// +/// A render pass may contain any number of drawing commands, and before/between each command the +/// render state may be updated however you wish; each drawing command will be executed using the +/// render state that has been set when the `draw_*()` function is called. /// /// Corresponds to [WebGPU `GPURenderPassEncoder`]( /// https://gpuweb.github.io/gpuweb/#render-pass-encoder). @@ -2988,11 +3000,14 @@ impl CommandEncoder { impl<'a> RenderPass<'a> { /// Sets the active bind group for a given bind group index. The bind group layout - /// in the active pipeline when any `draw()` function is called must match the layout of this bind group. + /// in the active pipeline when any `draw_*()` method is called must match the layout of + /// this bind group. /// /// If the bind group have dynamic offsets, provide them in binding order. /// These offsets have to be aligned to [`Limits::min_uniform_buffer_offset_alignment`] /// or [`Limits::min_storage_buffer_offset_alignment`] appropriately. + /// + /// Subsequent draw calls’ shader executions will be able to access data in these bind groups. pub fn set_bind_group( &mut self, index: u32, @@ -3026,6 +3041,8 @@ impl<'a> RenderPass<'a> { /// Sets the blend color as used by some of the blending modes. /// /// Subsequent blending tests will test against this value. + /// If this method has not been called, the blend constant defaults to [`Color::TRANSPARENT`] + /// (all components zero). pub fn set_blend_constant(&mut self, color: Color) { DynContext::render_pass_set_blend_constant( &*self.parent.context, @@ -3075,9 +3092,14 @@ impl<'a> RenderPass<'a> { ) } - /// Sets the scissor region. + /// Sets the scissor rectangle. /// /// Subsequent draw calls will discard any fragments that fall outside this region. + /// If this method has not been called, the scissor rectangle defaults to the entire bounds of + /// the render targets. + /// + /// The function of the scissor rectangle resembles [`set_viewport()`](Self::set_viewport), + /// but it does not affect the coordinate system, only which fragments are discarded. pub fn set_scissor_rect(&mut self, x: u32, y: u32, width: u32, height: u32) { DynContext::render_pass_set_scissor_rect( &*self.parent.context, @@ -3090,9 +3112,12 @@ impl<'a> RenderPass<'a> { ); } - /// Sets the viewport region. + /// Sets the viewport, which determines the mapping from normalized device coordinates + /// (-1.0 to 1.0 range) to pixels in the render targets. /// - /// Subsequent draw calls will draw any fragments in this region. + /// Subsequent draw calls will only draw within this region. + /// If this method has not been called, the viewport defaults to the entire bounds of the render + /// targets. pub fn set_viewport(&mut self, x: f32, y: f32, w: f32, h: f32, min_depth: f32, max_depth: f32) { DynContext::render_pass_set_viewport( &*self.parent.context, @@ -3110,6 +3135,7 @@ impl<'a> RenderPass<'a> { /// Sets the stencil reference. /// /// Subsequent stencil tests will test against this value. + /// If this method has not been called, the stencil reference value defaults to `0`. pub fn set_stencil_reference(&mut self, reference: u32) { DynContext::render_pass_set_stencil_reference( &*self.parent.context, @@ -3121,7 +3147,10 @@ impl<'a> RenderPass<'a> { /// Draws primitives from the active vertex buffer(s). /// - /// The active vertex buffers can be set with [`RenderPass::set_vertex_buffer`]. + /// The active vertex buffers can be set with [`RenderPass::set_vertex_buffer()`]. + /// + /// This drawing command uses the current render state, as set by preceding `set_*()` methods. + /// It is not affected by changes to the state that are performed after it is called. pub fn draw(&mut self, vertices: Range, instances: Range) { DynContext::render_pass_draw( &*self.parent.context, @@ -3163,8 +3192,11 @@ impl<'a> RenderPass<'a> { /// Draws indexed primitives using the active index buffer and the active vertex buffers. /// - /// The active index buffer can be set with [`RenderPass::set_index_buffer`], while the active - /// vertex buffers can be set with [`RenderPass::set_vertex_buffer`]. + /// The active index buffer can be set with [`RenderPass::set_index_buffer()`], while the active + /// vertex buffers can be set with [`RenderPass::set_vertex_buffer()`]. + /// + /// This drawing command uses the current render state, as set by preceding `set_*()` methods. + /// It is not affected by changes to the state that are performed after it is called. pub fn draw_indexed(&mut self, indices: Range, base_vertex: i32, instances: Range) { DynContext::render_pass_draw_indexed( &*self.parent.context, @@ -3181,6 +3213,9 @@ impl<'a> RenderPass<'a> { /// The active vertex buffers can be set with [`RenderPass::set_vertex_buffer`]. /// /// The structure expected in `indirect_buffer` must conform to [`DrawIndirect`](crate::util::DrawIndirect). + /// + /// This drawing command uses the current render state, as set by preceding `set_*()` methods. + /// It is not affected by changes to the state that are performed after it is called. pub fn draw_indirect(&mut self, indirect_buffer: &'a Buffer, indirect_offset: BufferAddress) { DynContext::render_pass_draw_indirect( &*self.parent.context, @@ -3199,6 +3234,9 @@ impl<'a> RenderPass<'a> { /// vertex buffers can be set with [`RenderPass::set_vertex_buffer`]. /// /// The structure expected in `indirect_buffer` must conform to [`DrawIndexedIndirect`](crate::util::DrawIndexedIndirect). + /// + /// This drawing command uses the current render state, as set by preceding `set_*()` methods. + /// It is not affected by changes to the state that are performed after it is called. pub fn draw_indexed_indirect( &mut self, indirect_buffer: &'a Buffer, @@ -3216,6 +3254,9 @@ impl<'a> RenderPass<'a> { /// Execute a [render bundle][RenderBundle], which is a set of pre-recorded commands /// that can be run together. + /// + /// Commands in the bundle do not inherit this render pass's current render state, and after the + /// bundle has executed, the state is **cleared** (reset to defaults, not the previous state). pub fn execute_bundles + 'a>( &mut self, render_bundles: I, @@ -3237,8 +3278,10 @@ impl<'a> RenderPass<'a> { /// The active vertex buffers can be set with [`RenderPass::set_vertex_buffer`]. /// /// The structure expected in `indirect_buffer` must conform to [`DrawIndirect`](crate::util::DrawIndirect). - /// /// These draw structures are expected to be tightly packed. + /// + /// This drawing command uses the current render state, as set by preceding `set_*()` methods. + /// It is not affected by changes to the state that are performed after it is called. pub fn multi_draw_indirect( &mut self, indirect_buffer: &'a Buffer, @@ -3263,8 +3306,10 @@ impl<'a> RenderPass<'a> { /// vertex buffers can be set with [`RenderPass::set_vertex_buffer`]. /// /// The structure expected in `indirect_buffer` must conform to [`DrawIndexedIndirect`](crate::util::DrawIndexedIndirect). - /// /// These draw structures are expected to be tightly packed. + /// + /// This drawing command uses the current render state, as set by preceding `set_*()` methods. + /// It is not affected by changes to the state that are performed after it is called. pub fn multi_draw_indexed_indirect( &mut self, indirect_buffer: &'a Buffer, @@ -3294,7 +3339,6 @@ impl<'a> RenderPass<'a> { /// The active vertex buffers can be set with [`RenderPass::set_vertex_buffer`]. /// /// The structure expected in `indirect_buffer` must conform to [`DrawIndirect`](crate::util::DrawIndirect). - /// /// These draw structures are expected to be tightly packed. /// /// The structure expected in `count_buffer` is the following: @@ -3305,6 +3349,9 @@ impl<'a> RenderPass<'a> { /// count: u32, // Number of draw calls to issue. /// } /// ``` + /// + /// This drawing command uses the current render state, as set by preceding `set_*()` methods. + /// It is not affected by changes to the state that are performed after it is called. pub fn multi_draw_indirect_count( &mut self, indirect_buffer: &'a Buffer, @@ -3349,6 +3396,9 @@ impl<'a> RenderPass<'a> { /// count: u32, // Number of draw calls to issue. /// } /// ``` + /// + /// This drawing command uses the current render state, as set by preceding `set_*()` methods. + /// It is not affected by changes to the state that are performed after it is called. pub fn multi_draw_indexed_indirect_count( &mut self, indirect_buffer: &'a Buffer,