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/// A detached readback over one buffer.
9///
10/// The handle owns everything it needs to await a mapped range, so a caller
11/// can release every borrow of the renderer that submitted the copy before
12/// the wait begins. On the browser's single JavaScript thread that is what
13/// lets a frame render while a pick is still resolving its readback.
14pub trait Readback: std::fmt::Debug {
15    /// Awaits the mapped range and returns its bytes.
16    ///
17    /// # Errors
18    ///
19    /// The device was lost, or the buffer was not readable.
20    fn resolve(
21        &self,
22        offset: u64,
23        size: u64,
24    ) -> impl Future<Output = Result<Vec<u8>, GpuError>> + '_;
25}
26
27/// Uploads and submission. One submission per frame is the discipline the
28/// engine holds; the trait does not enforce it, the render loop does.
29pub trait Queue<D: Device> {
30    /// Writes bytes into a buffer at an offset. The source is borrowed for
31    /// the duration of the call — an upload from a caller's slice is
32    /// copy-free on the host side.
33    fn write_buffer(&self, buffer: &D::Buffer, offset: u64, data: &[u8]);
34
35    /// Uploads a borrowed, tightly described region into a texture.
36    fn write_texture(&self, texture: &D::Texture, write: &TextureWrite<'_>);
37
38    /// Submits one encoder's recorded work.
39    fn submit(&self, encoder: D::CommandEncoder);
40
41    /// Submits work whose completion must gate resource residency.
42    fn submit_tracked(&self, encoder: D::CommandEncoder) -> FenceValue;
43
44    /// Polls the backend and returns the greatest submission known complete.
45    ///
46    /// # Errors
47    ///
48    /// Returns device loss when completion status can no longer be queried.
49    fn completed_fence(&self, device: &D) -> Result<FenceValue, GpuError>;
50
51    /// Resolves a mapped buffer range without blocking the browser event loop.
52    /// Off the frame path only: golden-image capture, picking and export.
53    ///
54    /// # Errors
55    ///
56    /// The device was lost, or the buffer was not readable.
57    fn read_buffer_async<'a>(
58        &'a self,
59        device: &'a D,
60        buffer: &'a D::Buffer,
61        offset: u64,
62        size: u64,
63    ) -> impl Future<Output = Result<Vec<u8>, GpuError>> + 'a;
64
65    /// Detaches a readback handle over one buffer.
66    ///
67    /// The returned handle borrows nothing, so the caller is free to use the
68    /// device and queue while a [`Readback::resolve`] is still awaiting.
69    fn readback(&self, device: &D, buffer: &D::Buffer) -> D::Readback;
70
71    /// Native convenience that waits for a mapped range. Browser callers use
72    /// [`Self::read_buffer_async`].
73    ///
74    /// # Errors
75    ///
76    /// The device was lost, or the buffer was not readable.
77    #[cfg(not(all(target_arch = "wasm32", target_os = "unknown")))]
78    fn read_buffer_blocking(
79        &self,
80        device: &D,
81        buffer: &D::Buffer,
82        offset: u64,
83        size: u64,
84    ) -> Result<Vec<u8>, GpuError>;
85
86    /// Nanoseconds represented by one timestamp-query tick.
87    fn timestamp_period(&self) -> f32;
88}
molgfx_gpu/queue.rs

molgfx_gpu/
queue.rs
