pub struct StandardCommandBufferAllocator { /* private fields */ }
Expand description
Standard implementation of a command buffer allocator.
The intended way to use this allocator is to have one that is used globally for the duration of
the program, in order to avoid creating and destroying CommandPool
s, as that is expensive.
Alternatively, you can have one locally on a thread for the duration of the thread.
Internally, this allocator keeps one or more CommandPool
s per queue family index per thread,
using Thread-Local Storage. When a thread first allocates, an entry is reserved for the thread
and queue family combination. After a thread exits and the allocator wasn’t dropped yet, its
entries are freed, but the pools it used are not dropped. The next time a new thread allocates
for the first time, the entries are reused along with the pools. If all threads drop their
reference to the allocator, all entries along with the allocator are dropped, even if the
threads didn’t exit yet, which is why you should keep the allocator alive for as long as you
need to allocate so that the pools can keep being reused.
This allocator only needs to lock when a thread first allocates or when a thread that previously allocated exits. In all other cases, allocation is lock-free.
Command buffers can’t be moved between threads during the building process, but finished command buffers can. When a command buffer is dropped, it is returned back to the pool for reuse.
Implementations§
source§impl StandardCommandBufferAllocator
impl StandardCommandBufferAllocator
sourcepub fn new(
device: Arc<Device>,
create_info: StandardCommandBufferAllocatorCreateInfo
) -> Self
pub fn new( device: Arc<Device>, create_info: StandardCommandBufferAllocatorCreateInfo ) -> Self
Creates a new StandardCommandBufferAllocator
.
sourcepub fn try_reset_pool(
&self,
queue_family_index: u32,
flags: CommandPoolResetFlags
) -> Result<(), Validated<ResetCommandPoolError>>
pub fn try_reset_pool( &self, queue_family_index: u32, flags: CommandPoolResetFlags ) -> Result<(), Validated<ResetCommandPoolError>>
Tries to reset the CommandPool
that’s currently in use for the given queue family index
on the current thread.
If successful, the memory of the pool can be reused again along with all command buffers allocated from it. This is only possible if all command buffers allocated from the pool have been dropped.
This has no effect if the entry wasn’t initialized yet or if the entry was cleared.
Panics
- Panics if
queue_family_index
is not less than the number of queue families.
sourcepub fn clear(&self, queue_family_index: u32)
pub fn clear(&self, queue_family_index: u32)
Clears the entry for the given queue family index and the current thread. This does not mean that the pools are dropped immediately. A pool is kept alive for as long as command buffers allocated from it exist.
This has no effect if the entry was not initialized yet.
Panics
- Panics if
queue_family_index
is not less than the number of queue families.
Trait Implementations§
source§impl CommandBufferAllocator for StandardCommandBufferAllocator
impl CommandBufferAllocator for StandardCommandBufferAllocator
source§fn allocate(
&self,
queue_family_index: u32,
level: CommandBufferLevel,
command_buffer_count: u32
) -> Result<Self::Iter, VulkanError>
fn allocate( &self, queue_family_index: u32, level: CommandBufferLevel, command_buffer_count: u32 ) -> Result<Self::Iter, VulkanError>
Allocates command buffers.
Returns an iterator that contains the requested amount of allocated command buffers.
Panics
- Panics if the queue family index is not active on the device.
- Panics if
command_buffer_count
exceeds the count configured for the pool corresponding tolevel
.