Add an overview of RenderPass and how render state works. (#4055)

* Explain the general relationship of `set` and `draw` methods.
* Explain render state changes and that you can have lots of them.
* Specify default values of render state.

CHANGELOG.md

@@ -85,6 +85,10 @@ By @Valaphee in [#3402](https://github.com/gfx-rs/wgpu/pull/3402)
 
 - DX12 doesn't support `Features::POLYGON_MODE_POINT``. By @teoxoy in [#4032](https://github.com/gfx-rs/wgpu/pull/4032).
 
+### Documentation
+
+- Add an overview of `RenderPass` and how render state works. By @kpreid in [#4055](https://github.com/gfx-rs/wgpu/pull/4055)
+
 ## v0.17.0 (2023-07-20)
 
 This is the first release that featured `wgpu-info` as a binary crate for getting information about what devices wgpu sees in your system. It can dump the information in both human readable format and json.

wgpu/src/lib.rs

@@ -764,9 +764,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).
@@ -3416,11 +3428,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,
@@ -3454,6 +3469,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,
@@ -3507,6 +3524,11 @@ impl<'a> RenderPass<'a> {
  /// After transformation into [viewport coordinates](https://www.w3.org/TR/webgpu/#viewport-coordinates).
  ///
  /// Subsequent draw calls will discard any fragments which fall outside the scissor rectangle.
+ /// 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,
@@ -3522,7 +3544,9 @@ impl<'a> RenderPass<'a> {
  /// Sets the viewport used during the rasterization stage to linearly map
  /// from [normalized device coordinates](https://www.w3.org/TR/webgpu/#ndc) to [viewport coordinates](https://www.w3.org/TR/webgpu/#viewport-coordinates).
  ///
- /// 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,
@@ -3540,6 +3564,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,
@@ -3567,6 +3592,9 @@ impl<'a> RenderPass<'a> {
  /// }
  /// }
  /// ```
+ ///
+ /// 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<u32>, instances: Range<u32>) {
  DynContext::render_pass_draw(
  &*self.parent.context,
@@ -3627,6 +3655,9 @@ impl<'a> RenderPass<'a> {
  /// }
  /// }
  /// ```
+ ///
+ /// 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<u32>, base_vertex: i32, instances: Range<u32>) {
  DynContext::render_pass_draw_indexed(
  &*self.parent.context,
@@ -3643,6 +3674,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,
@@ -3661,6 +3695,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,
@@ -3678,6 +3715,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<I: IntoIterator<Item = &'a RenderBundle> + 'a>(
  &mut self,
  render_bundles: I,
@@ -3703,8 +3743,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,
@@ -3729,8 +3771,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,
@@ -3760,7 +3804,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:
@@ -3771,6 +3814,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,
@@ -3815,6 +3861,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,