1 // Copyright (c) 2016 The vulkano developers 2 // Licensed under the Apache License, Version 2.0 3 // <LICENSE-APACHE or 4 // https://www.apache.org/licenses/LICENSE-2.0> or the MIT 5 // license <LICENSE-MIT or https://opensource.org/licenses/MIT>, 6 // at your option. All files in the project carrying such 7 // notice may not be copied, modified, or distributed except 8 // according to those terms. 9 10 //! In the Vulkan API, command buffers must be allocated from *command pools*. 11 //! 12 //! A command pool holds and manages the memory of one or more command buffers. If you destroy a 13 //! command pool, all of its command buffers are automatically destroyed. 14 //! 15 //! In vulkano, creating a command buffer requires passing an implementation of the `CommandPool` 16 //! trait. By default vulkano will use the `StandardCommandPool` struct, but you can implement 17 //! this trait yourself by wrapping around the `UnsafeCommandPool` type. 18 19 use crate::device::physical::QueueFamily; 20 21 use crate::device::DeviceOwned; 22 use crate::OomError; 23 24 pub use self::standard::StandardCommandPool; 25 pub use self::sys::CommandPoolTrimError; 26 pub use self::sys::UnsafeCommandPool; 27 pub use self::sys::UnsafeCommandPoolAlloc; 28 pub use self::sys::UnsafeCommandPoolAllocIter; 29 30 pub mod standard; 31 mod sys; 32 33 /// Types that manage the memory of command buffers. 34 /// 35 /// # Safety 36 /// 37 /// A Vulkan command pool must be externally synchronized as if it owned the command buffers that 38 /// were allocated from it. This includes allocating from the pool, freeing from the pool, 39 /// resetting the pool or individual command buffers, and most importantly recording commands to 40 /// command buffers. 41 /// 42 /// The implementation of `CommandPool` is expected to manage this. For as long as a `Builder` 43 /// is alive, the trait implementation is expected to lock the pool that allocated the `Builder` 44 /// for the current thread. 45 /// 46 /// > **Note**: This may be modified in the future to allow different implementation strategies. 47 /// 48 /// The destructors of the `CommandPoolBuilderAlloc` and the `CommandPoolAlloc` are expected to 49 /// free the command buffer, reset the command buffer, or add it to a pool so that it gets reused. 50 /// If the implementation frees or resets the command buffer, it must not forget that this 51 /// operation must lock the pool. 52 /// 53 pub unsafe trait CommandPool: DeviceOwned { 54 /// See `alloc()`. 55 type Iter: Iterator<Item = Self::Builder>; 56 /// Represents a command buffer that has been allocated and that is currently being built. 57 type Builder: CommandPoolBuilderAlloc<Alloc = Self::Alloc>; 58 /// Represents a command buffer that has been allocated and that is pending execution or is 59 /// being executed. 60 type Alloc: CommandPoolAlloc; 61 62 /// Allocates command buffers from this pool. 63 /// 64 /// Returns an iterator that contains an bunch of allocated command buffers. alloc(&self, secondary: bool, count: u32) -> Result<Self::Iter, OomError>65 fn alloc(&self, secondary: bool, count: u32) -> Result<Self::Iter, OomError>; 66 67 /// Returns the queue family that this pool targets. queue_family(&self) -> QueueFamily68 fn queue_family(&self) -> QueueFamily; 69 } 70 71 /// A command buffer allocated from a pool and that can be recorded. 72 /// 73 /// # Safety 74 /// 75 /// See `CommandPool` for information about safety. 76 /// 77 pub unsafe trait CommandPoolBuilderAlloc: DeviceOwned { 78 /// Return type of `into_alloc`. 79 type Alloc: CommandPoolAlloc; 80 81 /// Returns the internal object that contains the command buffer. inner(&self) -> &UnsafeCommandPoolAlloc82 fn inner(&self) -> &UnsafeCommandPoolAlloc; 83 84 /// Turns this builder into a command buffer that is pending execution. into_alloc(self) -> Self::Alloc85 fn into_alloc(self) -> Self::Alloc; 86 87 /// Returns the queue family that the pool targets. queue_family(&self) -> QueueFamily88 fn queue_family(&self) -> QueueFamily; 89 } 90 91 /// A command buffer allocated from a pool that has finished being recorded. 92 /// 93 /// # Safety 94 /// 95 /// See `CommandPool` for information about safety. 96 /// 97 pub unsafe trait CommandPoolAlloc: DeviceOwned { 98 /// Returns the internal object that contains the command buffer. inner(&self) -> &UnsafeCommandPoolAlloc99 fn inner(&self) -> &UnsafeCommandPoolAlloc; 100 101 /// Returns the queue family that the pool targets. queue_family(&self) -> QueueFamily102 fn queue_family(&self) -> QueueFamily; 103 } 104