1Command Pools 2============= 3 4The Vulkan runtime code provides a common ``VkCommandPool`` implementation 5which makes managing the lifetimes of command buffers and recycling their 6internal state easier. To use the common command pool a driver needs to 7fill out a :c:struct:`vk_command_buffer_ops` struct and set the 8``command_buffer_ops`` field of :c:struct:`vk_device`. 9 10.. c:autostruct:: vk_command_buffer_ops 11 :file: src/vulkan/runtime/vk_command_buffer.h 12 :members: 13 14By reducing the entirety of command buffer lifetime management to these 15three functions, much of the complexity of command pools can be implemented 16in common code, providing better, more consistent behavior across Mesa. 17 18 19Command Buffer Recycling 20------------------------ 21 22The common command pool provides automatic command buffer recycling as long 23as the driver uses the common ``vkAllocateCommandBuffers()`` and 24``vkFreeCommandBuffers()`` implementations. The driver must also provide the 25``reset`` function pointer in :c:struct:`vk_command_buffer_ops`. 26 27With the common command buffer pool, when the client calls 28``vkFreeCommandBuffers()``, the command buffers are not immediately freed. 29Instead, they are reset with 30``VK_COMMAND_BUFFER_RESET_RELEASE_RESOURCES_BIT``, their base object is 31recycled, and they are added to a free list inside the pool. When the 32client then calls ``vkAllocateCommandBuffers()``, we check the free list 33and return a recycled command buffer, if any are available. This provides 34some basic command buffer pooling without the driver doing any additional 35work. 36 37 38Custom command pools 39-------------------- 40 41If a driver wishes to recycle at a finer granularity than whole command 42buffers, they can do so by providing their own command pool implementation 43which wraps :c:struct:`vk_command_pool`. The common use-case here is if 44the driver wants to pool command-buffer-internal objects at a finer 45granularity than whole command buffers. The command pool provides a place 46where things like GPU command buffers or upload buffers can be cached 47without having to take a lock. 48 49When implementing a custom command pool, drivers need only implement three 50entrypoints: 51 52 - ``vkCreateCommandPool()`` 53 - ``vkDestroyCommandPool()`` 54 - ``vkTrimCommandPool()`` 55 56All of the other entrypoints will be handled by common code so long as the 57driver's command pool derives from :c:struct:`vk_command_pool`. 58 59The driver implementation of the command buffer ``recycle()`` function 60should respect ``VK_COMMAND_BUFFER_RESET_RELEASE_RESOURCES_BIT`` and, when 61set, return any recyclable resources to the command pool. This may be set 62by the client when it calls ``vkResetCommandBuffer()``, come from a 63whole-pool reset via ``VK_COMMAND_POOL_RESET_RELEASE_RESOURCES_BIT``, or 64come from the common command buffer code when a command buffer is recycled. 65 66The driver's implementation of ``vkTrimCommandPool()`` should free any 67resources that have been cached within the command pool back to the device 68or back to the OS. It **must** also call :c:func:`vk_command_pool_trim` 69to allow the common code to free any recycled command buffers. 70 71Reference 72--------- 73 74.. c:autostruct:: vk_command_pool 75 :file: src/vulkan/runtime/vk_command_pool.h 76 :members: 77 78.. c:autofunction:: vk_command_pool_init 79 :file: src/vulkan/runtime/vk_command_pool.h 80 81.. c:autofunction:: vk_command_pool_finish 82 :file: src/vulkan/runtime/vk_command_pool.h 83 84.. c:autofunction:: vk_command_pool_trim 85 :file: src/vulkan/runtime/vk_command_pool.h 86