Trait wgpu_hal::Queue

source ·

pub trait Queue: WasmNotSendSync {
    type A: Api;

    // Required methods
    unsafe fn submit(
        &self,
        command_buffers: &[&<Self::A as Api>::CommandBuffer],
        surface_textures: &[&<Self::A as Api>::SurfaceTexture],
        signal_fence: (&mut <Self::A as Api>::Fence, FenceValue),
    ) -> Result<(), DeviceError>;
    unsafe fn present(
        &self,
        surface: &<Self::A as Api>::Surface,
        texture: <Self::A as Api>::SurfaceTexture,
    ) -> Result<(), SurfaceError>;
    unsafe fn get_timestamp_period(&self) -> f32;
}

Required Associated Types§

source

type A: Api

Required Methods§

source

unsafe fn submit( &self, command_buffers: &[&<Self::A as Api>::CommandBuffer], surface_textures: &[&<Self::A as Api>::SurfaceTexture], signal_fence: (&mut <Self::A as Api>::Fence, FenceValue), ) -> Result<(), DeviceError>

Submit command_buffers for execution on GPU.

Update fence to value when the operation is complete. See Fence for details.

A wgpu_hal queue is “single threaded”: all command buffers are executed in the order they’re submitted, with each buffer able to see previous buffers’ results. Specifically:

If two calls to submit on a single Queue occur in a particular order (that is, they happen on the same thread, or on two threads that have synchronized to establish an ordering), then the first submission’s commands all complete execution before any of the second submission’s commands begin. All results produced by one submission are visible to the next.
Within a submission, command buffers execute in the order in which they appear in command_buffers. All results produced by one buffer are visible to the next.

If two calls to submit on a single Queue from different threads are not synchronized to occur in a particular order, they must pass distinct Fences. As explained in the Fence documentation, waiting for operations to complete is only trustworthy when operations finish in order of increasing fence value, but submissions from different threads cannot determine how to order the fence values if the submissions themselves are unordered. If each thread uses a separate Fence, this problem does not arise.

§Safety

Each CommandBuffer in command_buffers must have been created from a CommandEncoder that was constructed from the Device associated with this Queue.
Each CommandBuffer must remain alive until the submitted commands have finished execution. Since command buffers must not outlive their encoders, this implies that the encoders must remain alive as well.
All resources used by a submitted CommandBuffer (Textures, BindGroups, RenderPipelines, and so on) must remain alive until the command buffer finishes execution.
Every SurfaceTexture that any command in command_buffers writes to must appear in the surface_textures argument.
No SurfaceTexture may appear in the surface_textures argument more than once.
Each SurfaceTexture in surface_textures must be configured for use with the Device associated with this Queue, typically by calling Surface::configure.
All calls to this function that include a given SurfaceTexture in surface_textures must use the same Fence.
The Fence passed as signal_fence.0 must remain alive until all submissions that will signal it have completed.