Trait CommandBufferAllocator

Source

pub unsafe trait CommandBufferAllocator:
    DeviceOwned
    + Send
    + Sync
    + 'static {
    // Required methods
    fn allocate(
        &self,
        queue_family_index: u32,
        level: CommandBufferLevel,
    ) -> Result<CommandBufferAlloc, Validated<VulkanError>>;
    unsafe fn deallocate(&self, allocation: CommandBufferAlloc);
}

Expand description

Types that manage the memory of command buffers.

§Safety

A Vulkan command pool must be externally synchronized as if it owned the command buffers that were allocated from it. This includes allocating from the pool, freeing from the pool, resetting the pool or individual command buffers, and most importantly recording commands to command buffers. The implementation of CommandBufferAllocator is expected to manage this.

The implementation of allocate must return a valid allocation that stays allocated until either deallocate is called on it or the allocator is dropped. If the allocator is cloned, it must produce the same allocator, and an allocation must stay allocated until either deallocate is called on any of the clones or all clones have been dropped.

The implementation of deallocate is expected to free the command buffer, reset the command buffer or its pool, or add it to a pool so that it gets reused. If the implementation frees the command buffer or resets the command buffer or pool, it must not forget that this operation must be externally synchronized. The implementation should not panic as it is used when dropping command buffers.

Command buffers in the recording state can never be sent between threads in vulkano, which means that the implementation of allocate can freely assume that the command buffer won’t leave the thread it was allocated on until it has finished recording. Note however that after recording is finished, command buffers are free to be sent between threads, which means that deallocate must account for the possibility that a command buffer can be deallocated from a different thread than it was allocated from.