The devices, queues, and other entities in Vulkan are represented by Vulkan objects. At the API level, all objects are referred to by handles. There are two classes of handles, dispatchable and non-dispatchable. Dispatchable handle types are a pointer to an opaque type. This pointer may be used by layers as part of intercepting API commands, and thus each API command takes a dispatchable type as its first parameter. Each object of a dispatchable type must have a unique handle value during its lifetime.
Non-dispatchable handle types are a 64-bit integer type whose meaning is implementation-dependent, and may encode object information directly in the handle rather than pointing to a software structure. Objects of a non-dispatchable type may not have unique handle values within a type or across types. If handle values are not unique, then destroying one such handle must not cause identical handles of other types to become invalid, and must not cause identical handles of the same type to become invalid if that handle value has been created more times than it has been destroyed.
All objects created or allocated from a VkDevice
(i.e. with a
VkDevice
as the first parameter) are private to that device, and must
not be used on other devices.
Objects are created or allocated by vkCreate*
and vkAllocate*
commands, respectively.
Once an object is created or allocated, its “structure” is considered to
be immutable, though the contents of certain object types is still free to
change.
Objects are destroyed or freed by vkDestroy*
and vkFree*
commands, respectively.
Objects that are allocated (rather than created) take resources from an existing pool object or memory heap, and when freed return resources to that pool or heap. While object creation and destruction are generally expected to be low-frequency occurrences during runtime, allocating and freeing objects can occur at high frequency. Pool objects help accommodate improved performance of the allocations and frees.
It is an application’s responsibility to track the lifetime of Vulkan objects, and not to destroy them while they are still in use.
Application-owned memory is immediately consumed by any Vulkan command it is passed into. The application can alter or free this memory as soon as the commands that consume it have returned.
The following object types are consumed when they are passed into a Vulkan command and not further accessed by the objects they are used to create. They must not be destroyed in the duration of any API command they are passed into:
VkShaderModule
VkPipelineCache
A VkPipelineLayout
object must not be destroyed while any command
buffer that uses it is in the recording state.
VkDescriptorSetLayout
objects may be accessed by commands that
operate on descriptor sets allocated using that layout, and those descriptor
sets must not be updated with vkUpdateDescriptorSets
after the
descriptor set layout has been destroyed.
Otherwise, descriptor set layouts can be destroyed any time they are not in
use by an API command.
The application must not destroy any other type of Vulkan object until all uses of that object by the device (such as via command buffer execution) have completed.
The following Vulkan objects must not be destroyed while any command buffers using the object are recording or pending execution:
VkEvent
VkQueryPool
VkBuffer
VkBufferView
VkImage
VkImageView
VkPipeline
VkSampler
VkDescriptorPool
VkFramebuffer
VkRenderPass
VkCommandPool
VkDeviceMemory
VkDescriptorSet
The following Vulkan objects must not be destroyed while any queue is executing commands that use the object:
VkFence
VkSemaphore
VkCommandBuffer
VkCommandPool
In general, objects can be destroyed or freed in any order, even if the object being freed is involved in the use of another object (e.g. use of a resource in a view, use of a view in a descriptor set, use of an object in a command buffer, binding of a memory allocation to a resource), as long as any object that uses the freed object is not further used in any way except to be destroyed or to be reset in such a way that it no longer uses the other object (such as resetting a command buffer). If the object has been reset, then it can be used as if it never used the freed object. An exception to this is when there is a parent/child relationship between objects. In this case, the application must not destroy a parent object before its children, except when the parent is explicitly defined to free its children when it is destroyed (e.g. for pool objects, as defined below).
VkCommandPool
objects are parents of VkCommandBuffer
objects.
VkDescriptorPool
objects are parents of VkDescriptorSet
objects.
VkDevice
objects are parents of many object types (all that take a
VkDevice
as a parameter to their creation).
The following Vulkan objects have specific restrictions for when they can be destroyed:
VkQueue
objects cannot be explicitly destroyed.
Instead, they are implicitly destroyed when the VkDevice
object
they are retrieved from is destroyed.
VkCommandPool
frees all
VkCommandBuffer
objects that were allocated from it, and
destroying VkDescriptorPool
frees all VkDescriptorSet
objects that were allocated from it.
VkDevice
objects can be destroyed when all VkQueue
objects
retrieved from them are idle, and all objects created from them have
been destroyed.
This includes the following objects:
VkFence
VkSemaphore
VkEvent
VkQueryPool
VkBuffer
VkBufferView
VkImage
VkImageView
VkShaderModule
VkPipelineCache
VkPipeline
VkPipelineLayout
VkSampler
VkDescriptorSetLayout
VkDescriptorPool
VkFramebuffer
VkRenderPass
VkCommandPool
VkCommandBuffer
VkDeviceMemory
VkPhysicalDevice
objects cannot be explicitly destroyed.
Instead, they are implicitly destroyed when the VkInstance
object
they are retrieved from is destroyed.
VkInstance
objects can be destroyed once all VkDevice
objects created from any of its VkPhysicalDevice
objects have been
destroyed.