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    /// Resolves query values into a GPU buffer for later copy/readback.
64    fn resolve_query_set(
65        &mut self,
66        queries: &D::QuerySet,
67        range: Range<u32>,
68        dst: &D::Buffer,
69        offset: u64,
70    );
71
72    /// Records one BLAS build.
73    ///
74    /// # Errors
75    ///
76    /// Returns a capability, validation or backend recording failure.
77    fn build_blas(&mut self, _desc: &BlasBuildDesc<'_, D>) -> Result<(), GpuError> {
78        Err(GpuError::Capability { name: "ray query" })
79    }
80
81    /// Records one TLAS build.
82    ///
83    /// # Errors
84    ///
85    /// Returns a capability, validation or backend recording failure.
86    fn build_tlas(&mut self, _tlas: &D::Tlas) -> Result<(), GpuError> {
87        Err(GpuError::Capability { name: "ray query" })
88    }
89}
90
91/// Command-encoder extension for acceleration-structure builds.
92pub trait RayQueryCommandEncoder<D: RayQueryDevice>: CommandEncoder<D> {
93    /// Records one BLAS build.
94    ///
95    /// # Errors
96    ///
97    /// Returns capability, validation or backend recording failures.
98    fn build_blas(&mut self, desc: &BlasBuildDesc<'_, D>) -> Result<(), GpuError> {
99        CommandEncoder::build_blas(self, desc)
100    }
101
102    /// Records one TLAS build after its referenced BLAS builds.
103    ///
104    /// # Errors
105    ///
106    /// Returns capability, validation or backend recording failures.
107    fn build_tlas(&mut self, tlas: &D::Tlas) -> Result<(), GpuError> {
108        CommandEncoder::build_tlas(self, tlas)
109    }
110}
111
112impl<D, E> RayQueryCommandEncoder<D> for E
113where
114    D: RayQueryDevice,
115    E: CommandEncoder<D>,
116{
117}
118
119/// Records draws inside an open render pass.
120pub trait RenderPassEncoder<D: Device> {
121    /// Sets the active pipeline.
122    fn set_pipeline(&mut self, pipeline: &D::Pipeline);
123
124    /// Binds a group at an index (0 frame / 1 pass / 2 representation /
125    /// 3 material), with dynamic offsets where the layout declared them.
126    fn set_bind_group(&mut self, index: u32, group: &D::BindGroup, dynamic_offsets: &[u32]);
127
128    /// Direct draw; used only for fullscreen passes whose vertex count is a
129    /// constant, never per scene primitive.
130    fn draw(&mut self, vertices: Range<u32>, instances: Range<u32>);
131
132    /// Indirect draw against arguments a compute pass wrote; the only draw
133    /// the scene-geometry path uses.
134    fn draw_indirect(&mut self, args: &D::Buffer, offset: u64);
135}
136
137/// Records dispatches inside an open compute pass.
138pub trait ComputePassEncoder<D: Device> {
139    /// Sets the active pipeline.
140    fn set_pipeline(&mut self, pipeline: &D::Pipeline);
141
142    /// Binds a group at an index.
143    fn set_bind_group(&mut self, index: u32, group: &D::BindGroup, dynamic_offsets: &[u32]);
144
145    /// Dispatches workgroups.
146    fn dispatch(&mut self, x: u32, y: u32, z: u32);
147}
molgfx_gpu/encoder.rs

molgfx_gpu/
encoder.rs
