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, PassTimestampCapture};
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    /// Installs opt-in capture or takes it back with None.
23    /// The previous capture retains its query resource and preallocated metadata.
24    /// Disabled recording does not allocate or collect pass metadata.
25    fn set_timestamp_capture(
26        &mut self,
27        capture: Option<PassTimestampCapture<D::QuerySet>>,
28    ) -> Option<PassTimestampCapture<D::QuerySet>>;
29
30    /// Tags subsequent actual pass occurrences when capture is enabled.
31    fn set_timestamp_sample(&mut self, sample: Option<u32>);
32
33    /// Begins a render pass over the given attachments.
34    fn begin_render_pass<'e>(&'e mut self, desc: &RenderPassDesc<'_, D>) -> Self::RenderPass<'e>;
35
36    /// Begins a compute pass.
37    fn begin_compute_pass<'e>(&'e mut self, desc: &ComputePassDesc<'_, D>)
38    -> Self::ComputePass<'e>;
39
40    /// GPU-to-GPU buffer copy; how indirect-argument templates reset
41    /// per-frame counts without a host write.
42    fn copy_buffer_to_buffer(
43        &mut self,
44        src: &D::Buffer,
45        src_offset: u64,
46        dst: &D::Buffer,
47        dst_offset: u64,
48        size: u64,
49    );
50
51    /// Copies one texture's contents into a buffer, tightly packed rows.
52    /// Off the frame path except for picking's few-texel read.
53    fn copy_texture_to_buffer(
54        &mut self,
55        src: &D::Texture,
56        origin: (u32, u32),
57        size: (u32, u32),
58        bytes_per_row: u32,
59        destination_offset: u64,
60        dst: &D::Buffer,
61    );
62
63    /// GPU-to-GPU copy of the whole of one texture's first mip into another of
64    /// the same format and size.
65    fn copy_texture_to_texture(&mut self, src: &D::Texture, dst: &D::Texture, size: (u32, u32));
66
67    /// Resolves query values into a GPU buffer for later copy/readback.
68    fn resolve_query_set(
69        &mut self,
70        queries: &D::QuerySet,
71        range: Range<u32>,
72        dst: &D::Buffer,
73        offset: u64,
74    );
75
76    /// Records one BLAS build.
77    ///
78    /// # Errors
79    ///
80    /// Returns a capability, validation or backend recording failure.
81    fn build_blas(&mut self, _desc: &BlasBuildDesc<'_, D>) -> Result<(), GpuError> {
82        Err(GpuError::Capability { name: "ray query" })
83    }
84
85    /// Records one TLAS build.
86    ///
87    /// # Errors
88    ///
89    /// Returns a capability, validation or backend recording failure.
90    fn build_tlas(&mut self, _tlas: &D::Tlas) -> Result<(), GpuError> {
91        Err(GpuError::Capability { name: "ray query" })
92    }
93}
94
95/// Command-encoder extension for acceleration-structure builds.
96pub trait RayQueryCommandEncoder<D: RayQueryDevice>: CommandEncoder<D> {
97    /// Records one BLAS build.
98    ///
99    /// # Errors
100    ///
101    /// Returns capability, validation or backend recording failures.
102    fn build_blas(&mut self, desc: &BlasBuildDesc<'_, D>) -> Result<(), GpuError> {
103        CommandEncoder::build_blas(self, desc)
104    }
105
106    /// Records one TLAS build after its referenced BLAS builds.
107    ///
108    /// # Errors
109    ///
110    /// Returns capability, validation or backend recording failures.
111    fn build_tlas(&mut self, tlas: &D::Tlas) -> Result<(), GpuError> {
112        CommandEncoder::build_tlas(self, tlas)
113    }
114}
115
116impl<D, E> RayQueryCommandEncoder<D> for E
117where
118    D: RayQueryDevice,
119    E: CommandEncoder<D>,
120{
121}
122
123/// Records draws inside an open render pass.
124pub trait RenderPassEncoder<D: Device> {
125    /// Sets the active pipeline.
126    fn set_pipeline(&mut self, pipeline: &D::Pipeline);
127
128    /// Binds a group at an index (0 frame / 1 pass / 2 representation /
129    /// 3 material), with dynamic offsets where the layout declared them.
130    fn set_bind_group(&mut self, index: u32, group: &D::BindGroup, dynamic_offsets: &[u32]);
131
132    /// Direct draw; used only for fullscreen passes whose vertex count is a
133    /// constant, never per scene primitive.
134    fn draw(&mut self, vertices: Range<u32>, instances: Range<u32>);
135
136    /// Indirect draw against arguments a compute pass wrote; the only draw
137    /// the scene-geometry path uses.
138    fn draw_indirect(&mut self, args: &D::Buffer, offset: u64);
139}
140
141/// Records dispatches inside an open compute pass.
142pub trait ComputePassEncoder<D: Device> {
143    /// Sets the active pipeline.
144    fn set_pipeline(&mut self, pipeline: &D::Pipeline);
145
146    /// Binds a group at an index.
147    fn set_bind_group(&mut self, index: u32, group: &D::BindGroup, dynamic_offsets: &[u32]);
148
149    /// Dispatches workgroups.
150    fn dispatch(&mut self, x: u32, y: u32, z: u32);
151}
molgfx_gpu/encoder.rs

molgfx_gpu/
encoder.rs
