Trait 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 wait_for_idle(&self) -> Result<(), DeviceError>;
    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.

All command buffers submitted to a wgpu_hal queue are executed in the order they’re submitted, with each buffer able to observe the effects of previous buffers’ execution. 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.

Source

unsafe fn present( &self, surface: &<Self::A as Api>::Surface, texture: <Self::A as Api>::SurfaceTexture, ) -> Result<(), SurfaceError>

Present a surface texture to the screen.

This consumes the surface texture, returning it to the swapchain.

§Safety

texture must have been acquired from surface via Surface::acquire_texture and not yet presented or discarded.
surface must be configured for use with the Device associated with this Queue.
texture must be in the “present” state. Either:
- It was passed in submit’s surface_textures argument (which transitions it to the present state), or
- The caller has otherwise transitioned it (e.g. via a clear + barrier to PRESENT for textures that were never rendered to).
Any command buffers that write to texture must have been submitted via submit before this call. The submissions do not need to have completed on the GPU; platform-level synchronization handles the ordering between rendering and display.
Must be externally synchronized with all other queue operations (submit, present, wait_for_idle) on the same queue.