molgfx_gpu/
queue.rs

1//! The submission queue trait.
2
3use crate::device::Device;
4use crate::error::GpuError;
5use crate::{FenceValue, TextureWrite};
6use std::future::Future;
7
8/// Uploads and submission. One submission per frame is the discipline the
9/// engine holds; the trait does not enforce it, the render loop does.
10pub trait Queue<D: Device> {
11    /// Writes bytes into a buffer at an offset. The source is borrowed for
12    /// the duration of the call — an upload from a caller's slice is
13    /// copy-free on the host side.
14    fn write_buffer(&self, buffer: &D::Buffer, offset: u64, data: &[u8]);
15
16    /// Uploads a borrowed, tightly described region into a texture.
17    fn write_texture(&self, texture: &D::Texture, write: &TextureWrite<'_>);
18
19    /// Submits one encoder's recorded work.
20    fn submit(&self, encoder: D::CommandEncoder);
21
22    /// Submits work whose completion must gate resource residency.
23    fn submit_tracked(&self, encoder: D::CommandEncoder) -> FenceValue;
24
25    /// Polls the backend and returns the greatest submission known complete.
26    ///
27    /// # Errors
28    ///
29    /// Returns device loss when completion status can no longer be queried.
30    fn completed_fence(&self, device: &D) -> Result<FenceValue, GpuError>;
31
32    /// Resolves a mapped buffer range without blocking the browser event loop.
33    /// Off the frame path only: golden-image capture, picking and export.
34    ///
35    /// # Errors
36    ///
37    /// The device was lost, or the buffer was not readable.
38    fn read_buffer_async<'a>(
39        &'a self,
40        device: &'a D,
41        buffer: &'a D::Buffer,
42        offset: u64,
43        size: u64,
44    ) -> impl Future<Output = Result<Vec<u8>, GpuError>> + 'a;
45
46    /// Native convenience that waits for a mapped range. Browser callers use
47    /// [`Self::read_buffer_async`].
48    ///
49    /// # Errors
50    ///
51    /// The device was lost, or the buffer was not readable.
52    #[cfg(not(all(target_arch = "wasm32", target_os = "unknown")))]
53    fn read_buffer_blocking(
54        &self,
55        device: &D,
56        buffer: &D::Buffer,
57        offset: u64,
58        size: u64,
59    ) -> Result<Vec<u8>, GpuError>;
60
61    /// Nanoseconds represented by one timestamp-query tick.
62    fn timestamp_period(&self) -> f32;
63}
molgfx_gpu/queue.rs

molgfx_gpu/
queue.rs
