mirror of https://gitlab.freedesktop.org/mesa/mesa
86 lines
3.4 KiB
ReStructuredText
86 lines
3.4 KiB
ReStructuredText
Command Pools
|
|
=============
|
|
|
|
The Vulkan runtime code provides a common ``VkCommandPool`` implementation
|
|
which makes managing the lifetimes of command buffers and recycling their
|
|
internal state easier. To use the common command pool a driver needs to
|
|
fill out a :c:struct:`vk_command_buffer_ops` struct and set the
|
|
``command_buffer_ops`` field of :c:struct:`vk_device`.
|
|
|
|
.. c:autostruct:: vk_command_buffer_ops
|
|
:file: src/vulkan/runtime/vk_command_buffer.h
|
|
:members:
|
|
|
|
By reducing the entirety of command buffer lifetime management to these
|
|
three functions, much of the complexity of command pools can be implemented
|
|
in common code, providing better, more consistent behavior across Mesa.
|
|
|
|
|
|
Command Buffer Recycling
|
|
------------------------
|
|
|
|
The common command pool provides automatic command buffer recycling as long
|
|
as the driver uses the common ``vkAllocateCommandBuffers()`` and
|
|
``vkFreeCommandBuffers()`` implementations. The driver must also provide the
|
|
``reset`` function pointer in :c:struct:`vk_command_buffer_ops`.
|
|
|
|
With the common command buffer pool, when the client calls
|
|
``vkFreeCommandBuffers()``, the command buffers are not immediately freed.
|
|
Instead, they are reset with
|
|
``VK_COMMAND_BUFFER_RESET_RELEASE_RESOURCES_BIT``, their base object is
|
|
recycled, and they are added to a free list inside the pool. When the
|
|
client then calls ``vkAllocateCommandBuffers()``, we check the free list
|
|
and return a recycled command buffer, if any are available. This provides
|
|
some basic command buffer pooling without the driver doing any additional
|
|
work.
|
|
|
|
|
|
Custom command pools
|
|
--------------------
|
|
|
|
If a driver wishes to recycle at a finer granularity than whole command
|
|
buffers, they can do so by providing their own command pool implementation
|
|
which wraps :c:struct:`vk_command_pool`. The common use-case here is if
|
|
the driver wants to pool command-buffer-internal objects at a finer
|
|
granularity than whole command buffers. The command pool provides a place
|
|
where things like GPU command buffers or upload buffers can be cached
|
|
without having to take a lock.
|
|
|
|
When implementing a custom command pool, drivers need only implement three
|
|
entrypoints:
|
|
|
|
- ``vkCreateCommandPool()``
|
|
- ``vkDestroyCommandPool()``
|
|
- ``vkTrimCommandPool()``
|
|
|
|
All of the other entrypoints will be handled by common code so long as the
|
|
driver's command pool derives from :c:struct:`vk_command_pool`.
|
|
|
|
The driver implementation of the command buffer ``recycle()`` function
|
|
should respect ``VK_COMMAND_BUFFER_RESET_RELEASE_RESOURCES_BIT`` and, when
|
|
set, return any recyclable resources to the command pool. This may be set
|
|
by the client when it calls ``vkResetCommandBuffer()``, come from a
|
|
whole-pool reset via ``VK_COMMAND_POOL_RESET_RELEASE_RESOURCES_BIT``, or
|
|
come from the common command buffer code when a command buffer is recycled.
|
|
|
|
The driver's implementation of ``vkTrimCommandPool()`` should free any
|
|
resources that have been cached within the command pool back to the device
|
|
or back to the OS. It **must** also call :c:func:`vk_command_pool_trim`
|
|
to allow the common code to free any recycled command buffers.
|
|
|
|
Reference
|
|
---------
|
|
|
|
.. c:autostruct:: vk_command_pool
|
|
:file: src/vulkan/runtime/vk_command_pool.h
|
|
:members:
|
|
|
|
.. c:autofunction:: vk_command_pool_init
|
|
:file: src/vulkan/runtime/vk_command_pool.h
|
|
|
|
.. c:autofunction:: vk_command_pool_finish
|
|
:file: src/vulkan/runtime/vk_command_pool.h
|
|
|
|
.. c:autofunction:: vk_command_pool_trim
|
|
:file: src/vulkan/runtime/vk_command_pool.h
|