Struct vulkano::command_buffer::allocator::StandardCommandBufferAllocator

pub struct StandardCommandBufferAllocator { /* private fields */ }

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 CommandPools, 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 CommandPools 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

impl StandardCommandBufferAllocator

pub fn new(
    device: Arc<Device>,
    create_info: StandardCommandBufferAllocatorCreateInfo
) -> Self

Creates a new StandardCommandBufferAllocator.

pub fn try_reset_pool(
    &self,
    queue_family_index: u32,
    release_resources: bool
) -> Result<(), CommandPoolResetError>

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.

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

impl CommandBufferAllocator for StandardCommandBufferAllocator

fn allocate(
    &self,
    queue_family_index: u32,
    level: CommandBufferLevel,
    command_buffer_count: u32
) -> Result<Self::Iter, OomError>

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 to level.

type Iter = IntoIter<[StandardCommandBufferBuilderAlloc; 1]>

See allocate.

type Builder = StandardCommandBufferBuilderAlloc

Represents a command buffer that has been allocated and that is currently being built.

type Alloc = StandardCommandBufferAlloc

Represents a command buffer that has been allocated and that is pending execution or is being executed.

impl Debug for StandardCommandBufferAllocator

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl DeviceOwned for StandardCommandBufferAllocator

fn device(&self) -> &Arc<Device>

Returns the device that owns Self.