molgfx_gpu/
encoder.rs

1//! Command recording traits.
2//!
3//! Pass encoders borrow the command encoder for their lifetime (generic
4//! associated types), matching how every modern API scopes a pass.
5
6use crate::descriptors::{ComputePassDesc, RenderPassDesc};
7use crate::device::{Device, RayQueryDevice};
8use crate::{BlasBuildDesc, GpuError};
9use std::ops::Range;
10
11/// Records passes and copies into one submission.
12pub trait CommandEncoder<D: Device>: Sized {
13    /// The recording handle of an open render pass.
14    type RenderPass<'e>: RenderPassEncoder<D>
15    where
16        Self: 'e;
17    /// The recording handle of an open compute pass.
18    type ComputePass<'e>: ComputePassEncoder<D>
19    where
20        Self: 'e;
21
22    /// Begins a render pass over the given attachments.
23    fn begin_render_pass<'e>(&'e mut self, desc: &RenderPassDesc<'_, D>) -> Self::RenderPass<'e>;
24
25    /// Begins a compute pass.
26    fn begin_compute_pass<'e>(&'e mut self, desc: &ComputePassDesc<'_, D>)
27    -> Self::ComputePass<'e>;
28
29    /// GPU-to-GPU buffer copy; how indirect-argument templates reset
30    /// per-frame counts without a host write.
31    fn copy_buffer_to_buffer(
32        &mut self,
33        src: &D::Buffer,
34        src_offset: u64,
35        dst: &D::Buffer,
36        dst_offset: u64,
37        size: u64,
38    );
39
40    /// Copies one texture's contents into a buffer, tightly packed rows.
41    /// Off the frame path except for picking's few-texel read.
42    fn copy_texture_to_buffer(
43        &mut self,
44        src: &D::Texture,
45        origin: (u32, u32),
46        size: (u32, u32),
47        bytes_per_row: u32,
48        destination_offset: u64,
49        dst: &D::Buffer,
50    );
51
52    /// Resolves query values into a GPU buffer for later copy/readback.
53    fn resolve_query_set(
54        &mut self,
55        queries: &D::QuerySet,
56        range: Range<u32>,
57        dst: &D::Buffer,
58        offset: u64,
59    );
60
61    /// Records one BLAS build.
62    ///
63    /// # Errors
64    ///
65    /// Returns a capability, validation or backend recording failure.
66    fn build_blas(&mut self, _desc: &BlasBuildDesc<'_, D>) -> Result<(), GpuError> {
67        Err(GpuError::Capability { name: "ray query" })
68    }
69
70    /// Records one TLAS build.
71    ///
72    /// # Errors
73    ///
74    /// Returns a capability, validation or backend recording failure.
75    fn build_tlas(&mut self, _tlas: &D::Tlas) -> Result<(), GpuError> {
76        Err(GpuError::Capability { name: "ray query" })
77    }
78}
79
80/// Command-encoder extension for acceleration-structure builds.
81pub trait RayQueryCommandEncoder<D: RayQueryDevice>: CommandEncoder<D> {
82    /// Records one BLAS build.
83    ///
84    /// # Errors
85    ///
86    /// Returns capability, validation or backend recording failures.
87    fn build_blas(&mut self, desc: &BlasBuildDesc<'_, D>) -> Result<(), GpuError> {
88        CommandEncoder::build_blas(self, desc)
89    }
90
91    /// Records one TLAS build after its referenced BLAS builds.
92    ///
93    /// # Errors
94    ///
95    /// Returns capability, validation or backend recording failures.
96    fn build_tlas(&mut self, tlas: &D::Tlas) -> Result<(), GpuError> {
97        CommandEncoder::build_tlas(self, tlas)
98    }
99}
100
101impl<D, E> RayQueryCommandEncoder<D> for E
102where
103    D: RayQueryDevice,
104    E: CommandEncoder<D>,
105{
106}
107
108/// Records draws inside an open render pass.
109pub trait RenderPassEncoder<D: Device> {
110    /// Sets the active pipeline.
111    fn set_pipeline(&mut self, pipeline: &D::Pipeline);
112
113    /// Binds a group at an index (0 frame / 1 pass / 2 representation /
114    /// 3 material), with dynamic offsets where the layout declared them.
115    fn set_bind_group(&mut self, index: u32, group: &D::BindGroup, dynamic_offsets: &[u32]);
116
117    /// Direct draw; used only for fullscreen passes whose vertex count is a
118    /// constant, never per scene primitive.
119    fn draw(&mut self, vertices: Range<u32>, instances: Range<u32>);
120
121    /// Indirect draw against arguments a compute pass wrote; the only draw
122    /// the scene-geometry path uses.
123    fn draw_indirect(&mut self, args: &D::Buffer, offset: u64);
124}
125
126/// Records dispatches inside an open compute pass.
127pub trait ComputePassEncoder<D: Device> {
128    /// Sets the active pipeline.
129    fn set_pipeline(&mut self, pipeline: &D::Pipeline);
130
131    /// Binds a group at an index.
132    fn set_bind_group(&mut self, index: u32, group: &D::BindGroup, dynamic_offsets: &[u32]);
133
134    /// Dispatches workgroups.
135    fn dispatch(&mut self, x: u32, y: u32, z: u32);
136}
molgfx_gpu/encoder.rs

molgfx_gpu/
encoder.rs
