gfx_hal/queue/
mod.rs

1//! Command queues.
2//!
3//! Queues are the execution paths of the graphical processing units. These process
4//! submitted commands buffers.
5//!
6//! There are different types of queues, which can only handle associated command buffers.
7//! `Queue<B, C>` has the capability defined by `C`: graphics, compute and transfer.
8
9pub mod family;
10
11use crate::{
12    device::OutOfMemory,
13    pso,
14    window::{PresentError, PresentationSurface, Suboptimal},
15    Backend,
16};
17use std::{any::Any, fmt};
18
19pub use self::family::{QueueFamily, QueueFamilyId, QueueGroup};
20use crate::memory::{SparseBind, SparseImageBind};
21
22/// The type of the queue, an enum encompassing `queue::Capability`
23#[derive(Debug, Copy, Clone, PartialEq, Eq)]
24#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
25pub enum QueueType {
26    /// Supports all operations.
27    General,
28    /// Only supports graphics and transfer operations.
29    Graphics,
30    /// Only supports compute and transfer operations.
31    Compute,
32    /// Only supports transfer operations.
33    Transfer,
34}
35
36impl QueueType {
37    /// Returns true if the queue supports graphics operations.
38    pub fn supports_graphics(&self) -> bool {
39        match *self {
40            QueueType::General | QueueType::Graphics => true,
41            QueueType::Compute | QueueType::Transfer => false,
42        }
43    }
44    /// Returns true if the queue supports compute operations.
45    pub fn supports_compute(&self) -> bool {
46        match *self {
47            QueueType::General | QueueType::Graphics | QueueType::Compute => true,
48            QueueType::Transfer => false,
49        }
50    }
51    /// Returns true if the queue supports transfer operations.
52    pub fn supports_transfer(&self) -> bool {
53        true
54    }
55}
56
57/// Scheduling hint for devices about the priority of a queue.  Values range from `0.0` (low) to
58/// `1.0` (high).
59pub type QueuePriority = f32;
60
61/// Abstraction for an internal GPU execution engine.
62///
63/// Commands are executed on the the device by submitting
64/// [command buffers][crate::command::CommandBuffer].
65///
66/// Queues can also be used for presenting to a surface
67/// (that is, flip the front buffer with the next one in the chain).
68pub trait Queue<B: Backend>: fmt::Debug + Any + Send + Sync {
69    /// Sparse memory bind operation.
70    ///
71    /// # Arguments
72    ///
73    /// * `info` - information about the memory bindings.
74    ///
75    /// # Safety
76    ///
77    /// - Defining memory as `None` will cause undefined behaviour when the
78    /// tile is read or written from in some hardware.
79    /// - The memory regions provided are not checked to be valid and matching
80    /// of the sparse resource type.
81    /// - If extents are not a multiple of the block size, additional space will be
82    /// bound, and accessing memory is unsafe.
83    unsafe fn bind_sparse<'a, Iw, Is, Ibi, Ib, Iii, Io, Ii>(
84        &mut self,
85        _wait_semaphores: Iw,
86        _signal_semaphores: Is,
87        _buffer_memory_binds: Ib,
88        _image_opaque_memory_binds: Io,
89        _image_memory_binds: Ii,
90        _device: &B::Device,
91        _fence: Option<&B::Fence>,
92    ) where
93        Ibi: Iterator<Item = &'a SparseBind<&'a B::Memory>>,
94        Ib: Iterator<Item = (&'a mut B::Buffer, Ibi)>,
95        Iii: Iterator<Item = &'a SparseImageBind<&'a B::Memory>>,
96        Io: Iterator<Item = (&'a mut B::Image, Ibi)>,
97        Ii: Iterator<Item = (&'a mut B::Image, Iii)>,
98        Iw: Iterator<Item = &'a B::Semaphore>,
99        Is: Iterator<Item = &'a B::Semaphore>,
100    {
101        unimplemented!()
102    }
103
104    /// Submit command buffers to queue for execution.
105    ///
106    /// # Arguments
107    ///
108    /// * `command_buffers` - command buffers to submit.
109    /// * `wait_semaphores` - semaphores to wait being signalled before submission.
110    /// * `signal_semaphores` - semaphores to signal after all command buffers
111    ///   in the submission have finished execution.
112    /// * `fence` - must be in unsignaled state, and will be signaled after
113    ///   all command buffers in the submission have finished execution.
114    ///
115    /// # Safety
116    ///
117    /// It's not checked that the queue can process the submitted command buffers.
118    ///
119    /// For example, trying to submit compute commands to a graphics queue
120    /// will result in undefined behavior.
121    unsafe fn submit<'a, Ic, Iw, Is>(
122        &mut self,
123        command_buffers: Ic,
124        wait_semaphores: Iw,
125        signal_semaphores: Is,
126        fence: Option<&mut B::Fence>,
127    ) where
128        Ic: Iterator<Item = &'a B::CommandBuffer>,
129        Iw: Iterator<Item = (&'a B::Semaphore, pso::PipelineStage)>,
130        Is: Iterator<Item = &'a B::Semaphore>;
131
132    /// Present a swapchain image directly to a surface, after waiting on `wait_semaphore`.
133    ///
134    /// # Safety
135    ///
136    /// Unsafe for the same reasons as [`submit`][Queue::submit].
137    /// No checks are performed to verify that this queue supports present operations.
138    unsafe fn present(
139        &mut self,
140        surface: &mut B::Surface,
141        image: <B::Surface as PresentationSurface<B>>::SwapchainImage,
142        wait_semaphore: Option<&mut B::Semaphore>,
143    ) -> Result<Option<Suboptimal>, PresentError>;
144
145    /// Wait for the queue to be idle.
146    fn wait_idle(&mut self) -> Result<(), OutOfMemory>;
147
148    /// The amount of nanoseconds that causes a timestamp query value to increment by one.
149    fn timestamp_period(&self) -> f32;
150}
gfx_hal/queue/mod.rs

gfx_hal/queue/
mod.rs
