github/wgpu
1
1
Fork 0
mirror of https://github.com/gfx-rs/wgpu.git synced 2026-04-22 03:02:01 -04:00
Code Issues Packages Projects Releases Wiki Activity

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

Browse Source 
* 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.
This commit is contained in:
Kevin Reid
2023-08-14 13:24:27 -07:00
committed by GitHub
parent f825ce4ac2
commit 2bdb3196f9
2 changed files with 60 additions and 7 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
CHANGELOG.md
View File

@@ -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.

63
wgpu/src/lib.rs
View File

@@ -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,