Copyright
Copyright (c) 2014-2020 Khronos Group. This work is licensed under a Creative Commons Attribution 4.0 International License.
Vulkan Commands
vkAcquireFullScreenExclusiveModeEXT(3)
C Specification
To acquire exclusive full-screen access for a swapchain, call:
VkResult vkAcquireFullScreenExclusiveModeEXT(
VkDevice device,
VkSwapchainKHR swapchain);Parameters
-
deviceis the device associated withswapchain. -
swapchainis the swapchain to acquire exclusive full-screen access for.
Description
A return value of VK_SUCCESS indicates that the swapchain
successfully acquired exclusive full-screen access.
The swapchain will retain this exclusivity until either the application
releases exclusive full-screen access with
vkReleaseFullScreenExclusiveModeEXT, destroys the swapchain, or if any
of the swapchain commands return
VK_ERROR_FULL_SCREEN_EXCLUSIVE_MODE_LOST_EXT indicating that the mode
was lost because of platform-specific changes.
If the swapchain was unable to acquire exclusive full-screen access to the
display then VK_ERROR_INITIALIZATION_FAILED is returned.
An application can attempt to acquire exclusive full-screen access again
for the same swapchain even if this command fails, or if
VK_ERROR_FULL_SCREEN_EXCLUSIVE_MODE_LOST_EXT has been returned by a
swapchain command.
Document Notes
For more information, see the Vulkan Specification
This page is extracted from the Vulkan Specification. Fixes and changes should be made to the Specification, not directly.
vkAcquireNextImage2KHR(3)
C Specification
To acquire an available presentable image to use, and retrieve the index of that image, call:
VkResult vkAcquireNextImage2KHR(
VkDevice device,
const VkAcquireNextImageInfoKHR* pAcquireInfo,
uint32_t* pImageIndex);Parameters
-
deviceis the device associated withswapchain. -
pAcquireInfois a pointer to a VkAcquireNextImageInfoKHR structure containing parameters of the acquire. -
pImageIndexis a pointer to auint32_tthat is set to the index of the next image to use.
Document Notes
For more information, see the Vulkan Specification
This page is extracted from the Vulkan Specification. Fixes and changes should be made to the Specification, not directly.
vkAcquireNextImageKHR(3)
C Specification
To acquire an available presentable image to use, and retrieve the index of that image, call:
VkResult vkAcquireNextImageKHR(
VkDevice device,
VkSwapchainKHR swapchain,
uint64_t timeout,
VkSemaphore semaphore,
VkFence fence,
uint32_t* pImageIndex);Parameters
-
deviceis the device associated withswapchain. -
swapchainis the non-retired swapchain from which an image is being acquired. -
timeoutspecifies how long the function waits, in nanoseconds, if no image is available. -
semaphoreis VK_NULL_HANDLE or a semaphore to signal. -
fenceis VK_NULL_HANDLE or a fence to signal. -
pImageIndexis a pointer to auint32_tin which the index of the next image to use (i.e. an index into the array of images returned byvkGetSwapchainImagesKHR) is returned.
Document Notes
For more information, see the Vulkan Specification
This page is extracted from the Vulkan Specification. Fixes and changes should be made to the Specification, not directly.
vkAcquirePerformanceConfigurationINTEL(3)
C Specification
To acquire a device performance configuration, call:
VkResult vkAcquirePerformanceConfigurationINTEL(
VkDevice device,
const VkPerformanceConfigurationAcquireInfoINTEL* pAcquireInfo,
VkPerformanceConfigurationINTEL* pConfiguration);Parameters
-
deviceis the logical device that the performance query commands will be submitted to. -
pAcquireInfois a pointer to a VkPerformanceConfigurationAcquireInfoINTEL structure, specifying the performance configuration to acquire. -
pConfigurationis a pointer to aVkPerformanceConfigurationINTELhandle in which the resulting configuration object is returned.
Document Notes
For more information, see the Vulkan Specification
This page is extracted from the Vulkan Specification. Fixes and changes should be made to the Specification, not directly.
vkAcquireProfilingLockKHR(3)
C Specification
To record and submit a command buffer that contains a performance query pool the profiling lock must be held. The profiling lock must be acquired prior to any call to vkBeginCommandBuffer that will be using a performance query pool. The profiling lock must be held while any command buffer that contains a performance query pool is in the recording, executable, or pending state. To acquire the profiling lock, call:
VkResult vkAcquireProfilingLockKHR(
VkDevice device,
const VkAcquireProfilingLockInfoKHR* pInfo);Parameters
-
deviceis the logical device to profile. -
pInfois a pointer to aVkAcquireProfilingLockInfoKHRstructure which contains information about how the profiling is to be acquired.
Document Notes
For more information, see the Vulkan Specification
This page is extracted from the Vulkan Specification. Fixes and changes should be made to the Specification, not directly.
vkAcquireXlibDisplayEXT(3)
C Specification
To acquire permission to directly access a display in Vulkan from an X11 server, call:
VkResult vkAcquireXlibDisplayEXT(
VkPhysicalDevice physicalDevice,
Display* dpy,
VkDisplayKHR display);Parameters
-
physicalDeviceThe physical device the display is on. -
dpyA connection to the X11 server that currently ownsdisplay. -
displayThe display the caller wishes to control in Vulkan.
Description
All permissions necessary to control the display are granted to the Vulkan
instance associated with physicalDevice until the display is released
or the X11 connection specified by dpy is terminated.
Permission to access the display may be temporarily revoked during periods
when the X11 server from which control was acquired itself loses access to
display.
During such periods, operations which require access to the display must
fail with an approriate error code.
If the X11 server associated with dpy does not own display, or
if permission to access it has already been acquired by another entity, the
call must return the error code VK_ERROR_INITIALIZATION_FAILED.
|
Note
One example of when an X11 server loses access to a display is when it loses ownership of its virtual terminal. |
Document Notes
For more information, see the Vulkan Specification
This page is extracted from the Vulkan Specification. Fixes and changes should be made to the Specification, not directly.
vkAllocateCommandBuffers(3)
C Specification
To allocate command buffers, call:
VkResult vkAllocateCommandBuffers(
VkDevice device,
const VkCommandBufferAllocateInfo* pAllocateInfo,
VkCommandBuffer* pCommandBuffers);Parameters
-
deviceis the logical device that owns the command pool. -
pAllocateInfois a pointer to aVkCommandBufferAllocateInfostructure describing parameters of the allocation. -
pCommandBuffersis a pointer to an array of VkCommandBuffer handles in which the resulting command buffer objects are returned. The array must be at least the length specified by thecommandBufferCountmember ofpAllocateInfo. Each allocated command buffer begins in the initial state.
Description
vkAllocateCommandBuffers can be used to create multiple command
buffers.
If the creation of any of those command buffers fails, the implementation
must destroy all successfully created command buffer objects from this
command, set all entries of the pCommandBuffers array to NULL and
return the error.
When command buffers are first allocated, they are in the initial state.
Document Notes
For more information, see the Vulkan Specification
This page is extracted from the Vulkan Specification. Fixes and changes should be made to the Specification, not directly.
vkAllocateDescriptorSets(3)
C Specification
To allocate descriptor sets from a descriptor pool, call:
VkResult vkAllocateDescriptorSets(
VkDevice device,
const VkDescriptorSetAllocateInfo* pAllocateInfo,
VkDescriptorSet* pDescriptorSets);Parameters
-
deviceis the logical device that owns the descriptor pool. -
pAllocateInfois a pointer to a VkDescriptorSetAllocateInfo structure describing parameters of the allocation. -
pDescriptorSetsis a pointer to an array of VkDescriptorSet handles in which the resulting descriptor set objects are returned.
Description
The allocated descriptor sets are returned in pDescriptorSets.
When a descriptor set is allocated, the initial state is largely uninitialized and all descriptors are undefined. Descriptors also become undefined if the underlying resource is destroyed. Descriptor sets containing undefined descriptors can still be bound and used, subject to the following conditions:
-
For descriptor set bindings created with the
VK_DESCRIPTOR_BINDING_PARTIALLY_BOUND_BITbit set, all descriptors in that binding that are dynamically used must have been populated before the descriptor set is consumed. -
For descriptor set bindings created without the
VK_DESCRIPTOR_BINDING_PARTIALLY_BOUND_BITbit set, all descriptors in that binding that are statically used must have been populated before the descriptor set is consumed. -
Descriptor bindings with descriptor type of
VK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCK_EXTcan be undefined when the descriptor set is consumed; though values in that block will be undefined. -
Entries that are not used by a pipeline can have undefined descriptors.
If a call to vkAllocateDescriptorSets would cause the total number of
descriptor sets allocated from the pool to exceed the value of
VkDescriptorPoolCreateInfo::maxSets used to create
pAllocateInfo->descriptorPool, then the allocation may fail due to
lack of space in the descriptor pool.
Similarly, the allocation may fail due to lack of space if the call to
vkAllocateDescriptorSets would cause the number of any given
descriptor type to exceed the sum of all the descriptorCount members
of each element of VkDescriptorPoolCreateInfo::pPoolSizes with a
member equal to that type.
Additionally, the allocation may also fail if a call to
vkAllocateDescriptorSets would cause the total number of inline
uniform block bindings allocated from the pool to exceed the value of
VkDescriptorPoolInlineUniformBlockCreateInfoEXT::maxInlineUniformBlockBindings
used to create the descriptor pool.
If the allocation fails due to no more space in the descriptor pool, and not
because of system or device memory exhaustion, then
VK_ERROR_OUT_OF_POOL_MEMORY must be returned.
vkAllocateDescriptorSets can be used to create multiple descriptor
sets.
If the creation of any of those descriptor sets fails, then the
implementation must destroy all successfully created descriptor set objects
from this command, set all entries of the pDescriptorSets array to
VK_NULL_HANDLE and return the error.
Document Notes
For more information, see the Vulkan Specification
This page is extracted from the Vulkan Specification. Fixes and changes should be made to the Specification, not directly.
vkAllocateMemory(3)
C Specification
To allocate memory objects, call:
VkResult vkAllocateMemory(
VkDevice device,
const VkMemoryAllocateInfo* pAllocateInfo,
const VkAllocationCallbacks* pAllocator,
VkDeviceMemory* pMemory);Parameters
-
deviceis the logical device that owns the memory. -
pAllocateInfois a pointer to a VkMemoryAllocateInfo structure describing parameters of the allocation. A successful returned allocation must use the requested parameters — no substitution is permitted by the implementation. -
pAllocatorcontrols host memory allocation as described in the Memory Allocation chapter. -
pMemoryis a pointer to a VkDeviceMemory handle in which information about the allocated memory is returned.
Description
Allocations returned by vkAllocateMemory are guaranteed to meet any
alignment requirement of the implementation.
For example, if an implementation requires 128 byte alignment for images and
64 byte alignment for buffers, the device memory returned through this
mechanism would be 128-byte aligned.
This ensures that applications can correctly suballocate objects of
different types (with potentially different alignment requirements) in the
same memory object.
When memory is allocated, its contents are undefined with the following constraint:
-
The contents of unprotected memory must not be a function of data protected memory objects, even if those memory objects were previously freed.
|
Note
The contents of memory allocated by one application should not be a function of data from protected memory objects of another application, even if those memory objects were previously freed. |
The maximum number of valid memory allocations that can exist
simultaneously within a VkDevice may be restricted by implementation-
or platform-dependent limits.
If a call to vkAllocateMemory would cause the total number of
allocations to exceed these limits, such a call will fail and must return
VK_ERROR_TOO_MANY_OBJECTS.
The maxMemoryAllocationCount
feature describes the number of allocations that can exist simultaneously
before encountering these internal limits.
Some platforms may have a limit on the maximum size of a single allocation.
For example, certain systems may fail to create allocations with a size
greater than or equal to 4GB.
Such a limit is implementation-dependent, and if such a failure occurs then
the error VK_ERROR_OUT_OF_DEVICE_MEMORY must be returned.
This limit is advertised in
VkPhysicalDeviceMaintenance3Properties::maxMemoryAllocationSize.
The cumulative memory size allocated to a heap can be limited by the size
of the specified heap.
In such cases, allocated memory is tracked on a per-device and per-heap
basis.
Some platforms allow overallocation into other heaps.
The overallocation behavior can be specified through the
https://www.khronos.org/registry/vulkan/specs/1.2-extensions/html/vkspec.html#VK_AMD_memory_overallocation_behavior extension.
Document Notes
For more information, see the Vulkan Specification
This page is extracted from the Vulkan Specification. Fixes and changes should be made to the Specification, not directly.
vkBeginCommandBuffer(3)
C Specification
To begin recording a command buffer, call:
VkResult vkBeginCommandBuffer(
VkCommandBuffer commandBuffer,
const VkCommandBufferBeginInfo* pBeginInfo);Parameters
-
commandBufferis the handle of the command buffer which is to be put in the recording state. -
pBeginInfopoints to a VkCommandBufferBeginInfo structure defining additional information about how the command buffer begins recording.
Document Notes
For more information, see the Vulkan Specification
This page is extracted from the Vulkan Specification. Fixes and changes should be made to the Specification, not directly.
vkBindAccelerationStructureMemoryNV(3)
C Specification
To attach memory to one or more acceleration structures at a time, call:
VkResult vkBindAccelerationStructureMemoryNV(
VkDevice device,
uint32_t bindInfoCount,
const VkBindAccelerationStructureMemoryInfoNV* pBindInfos);Parameters
-
deviceis the logical device that owns the acceleration structures and memory. -
bindInfoCountis the number of elements inpBindInfos. -
pBindInfosis a pointer to an array of VkBindAccelerationStructureMemoryInfoNV structures describing images and memory to bind.
Document Notes
For more information, see the Vulkan Specification
This page is extracted from the Vulkan Specification. Fixes and changes should be made to the Specification, not directly.
vkBindBufferMemory(3)
C Specification
To attach memory to a buffer object, call:
VkResult vkBindBufferMemory(
VkDevice device,
VkBuffer buffer,
VkDeviceMemory memory,
VkDeviceSize memoryOffset);Parameters
-
deviceis the logical device that owns the buffer and memory. -
bufferis the buffer to be attached to memory. -
memoryis a VkDeviceMemory object describing the device memory to attach. -
memoryOffsetis the start offset of the region ofmemorywhich is to be bound to the buffer. The number of bytes returned in theVkMemoryRequirements::sizemember inmemory, starting frommemoryOffsetbytes, will be bound to the specified buffer.
Description
vkBindBufferMemory is equivalent to passing the same parameters
through VkBindBufferMemoryInfo to vkBindBufferMemory2.
See Also
VkBuffer, VkDevice, VkDeviceMemory, VkDeviceSize
Document Notes
For more information, see the Vulkan Specification
This page is extracted from the Vulkan Specification. Fixes and changes should be made to the Specification, not directly.
vkBindBufferMemory2(3)
C Specification
To attach memory to buffer objects for one or more buffers at a time, call:
VkResult vkBindBufferMemory2(
VkDevice device,
uint32_t bindInfoCount,
const VkBindBufferMemoryInfo* pBindInfos);or the equivalent command
VkResult vkBindBufferMemory2KHR(
VkDevice device,
uint32_t bindInfoCount,
const VkBindBufferMemoryInfo* pBindInfos);Parameters
-
deviceis the logical device that owns the buffers and memory. -
bindInfoCountis the number of elements inpBindInfos. -
pBindInfosis a pointer to an array ofbindInfoCountVkBindBufferMemoryInfo structures describing buffers and memory to bind.
Description
On some implementations, it may be more efficient to batch memory bindings into a single command.
Document Notes
For more information, see the Vulkan Specification
This page is extracted from the Vulkan Specification. Fixes and changes should be made to the Specification, not directly.
vkBindImageMemory(3)
C Specification
To attach memory to a VkImage object created without the
VK_IMAGE_CREATE_DISJOINT_BIT set, call:
VkResult vkBindImageMemory(
VkDevice device,
VkImage image,
VkDeviceMemory memory,
VkDeviceSize memoryOffset);Parameters
-
deviceis the logical device that owns the image and memory. -
imageis the image. -
memoryis the VkDeviceMemory object describing the device memory to attach. -
memoryOffsetis the start offset of the region ofmemorywhich is to be bound to the image. The number of bytes returned in theVkMemoryRequirements::sizemember inmemory, starting frommemoryOffsetbytes, will be bound to the specified image.
Description
vkBindImageMemory is equivalent to passing the same parameters through
VkBindImageMemoryInfo to vkBindImageMemory2.
See Also
VkDevice, VkDeviceMemory, VkDeviceSize, VkImage
Document Notes
For more information, see the Vulkan Specification
This page is extracted from the Vulkan Specification. Fixes and changes should be made to the Specification, not directly.
vkBindImageMemory2(3)
C Specification
To attach memory to image objects for one or more images at a time, call:
VkResult vkBindImageMemory2(
VkDevice device,
uint32_t bindInfoCount,
const VkBindImageMemoryInfo* pBindInfos);or the equivalent command
VkResult vkBindImageMemory2KHR(
VkDevice device,
uint32_t bindInfoCount,
const VkBindImageMemoryInfo* pBindInfos);Parameters
-
deviceis the logical device that owns the images and memory. -
bindInfoCountis the number of elements inpBindInfos. -
pBindInfosis a pointer to an array of VkBindImageMemoryInfo structures, describing images and memory to bind.
Description
On some implementations, it may be more efficient to batch memory bindings into a single command.
Document Notes
For more information, see the Vulkan Specification
This page is extracted from the Vulkan Specification. Fixes and changes should be made to the Specification, not directly.
vkCmdBeginConditionalRenderingEXT(3)
C Specification
To begin conditional rendering, call:
void vkCmdBeginConditionalRenderingEXT(
VkCommandBuffer commandBuffer,
const VkConditionalRenderingBeginInfoEXT* pConditionalRenderingBegin);Parameters
-
commandBufferis the command buffer into which this command will be recorded. -
pConditionalRenderingBeginis a pointer to a VkConditionalRenderingBeginInfoEXT structure specifying parameters of conditional rendering.
Document Notes
For more information, see the Vulkan Specification
This page is extracted from the Vulkan Specification. Fixes and changes should be made to the Specification, not directly.
vkCmdBeginDebugUtilsLabelEXT(3)
C Specification
A command buffer debug label region can be opened by calling:
void vkCmdBeginDebugUtilsLabelEXT(
VkCommandBuffer commandBuffer,
const VkDebugUtilsLabelEXT* pLabelInfo);Parameters
-
commandBufferis the command buffer into which the command is recorded. -
pLabelInfois a pointer to a VkDebugUtilsLabelEXT structure specifying parameters of the label region to open.
Document Notes
For more information, see the Vulkan Specification
This page is extracted from the Vulkan Specification. Fixes and changes should be made to the Specification, not directly.
vkCmdBeginQuery(3)
C Specification
To begin a query, call:
void vkCmdBeginQuery(
VkCommandBuffer commandBuffer,
VkQueryPool queryPool,
uint32_t query,
VkQueryControlFlags flags);Parameters
-
commandBufferis the command buffer into which this command will be recorded. -
queryPoolis the query pool that will manage the results of the query. -
queryis the query index within the query pool that will contain the results. -
flagsis a bitmask of VkQueryControlFlagBits specifying constraints on the types of queries that can be performed.
Description
If the queryType of the pool is VK_QUERY_TYPE_OCCLUSION and
flags contains VK_QUERY_CONTROL_PRECISE_BIT, an implementation
must return a result that matches the actual number of samples passed.
This is described in more detail in Occlusion Queries.
Calling vkCmdBeginQuery is equivalent to calling
vkCmdBeginQueryIndexedEXT with the index parameter set to zero.
After beginning a query, that query is considered active within the command buffer it was called in until that same query is ended. Queries active in a primary command buffer when secondary command buffers are executed are considered active for those secondary command buffers.
Document Notes
For more information, see the Vulkan Specification
This page is extracted from the Vulkan Specification. Fixes and changes should be made to the Specification, not directly.
vkCmdBeginQueryIndexedEXT(3)
C Specification
To begin an indexed query, call:
void vkCmdBeginQueryIndexedEXT(
VkCommandBuffer commandBuffer,
VkQueryPool queryPool,
uint32_t query,
VkQueryControlFlags flags,
uint32_t index);Parameters
-
commandBufferis the command buffer into which this command will be recorded. -
queryPoolis the query pool that will manage the results of the query. -
queryis the query index within the query pool that will contain the results. -
flagsis a bitmask of VkQueryControlFlagBits specifying constraints on the types of queries that can be performed. -
indexis the query type specific index. When the query type isVK_QUERY_TYPE_TRANSFORM_FEEDBACK_STREAM_EXTthe index represents the vertex stream.
Description
The vkCmdBeginQueryIndexedEXT command operates the same as the
vkCmdBeginQuery command, except that it also accepts a query type
specific index parameter.
Document Notes
For more information, see the Vulkan Specification
This page is extracted from the Vulkan Specification. Fixes and changes should be made to the Specification, not directly.
vkCmdBeginRenderPass(3)
C Specification
To begin a render pass instance, call:
void vkCmdBeginRenderPass(
VkCommandBuffer commandBuffer,
const VkRenderPassBeginInfo* pRenderPassBegin,
VkSubpassContents contents);Parameters
-
commandBufferis the command buffer in which to record the command. -
pRenderPassBeginis a pointer to a VkRenderPassBeginInfo structure specifying the render pass to begin an instance of, and the framebuffer the instance uses. -
contentsis a VkSubpassContents value specifying how the commands in the first subpass will be provided.
Description
After beginning a render pass instance, the command buffer is ready to record the commands for the first subpass of that render pass.
Document Notes
For more information, see the Vulkan Specification
This page is extracted from the Vulkan Specification. Fixes and changes should be made to the Specification, not directly.
vkCmdBeginRenderPass2(3)
C Specification
Alternatively to begin a render pass, call:
void vkCmdBeginRenderPass2(
VkCommandBuffer commandBuffer,
const VkRenderPassBeginInfo* pRenderPassBegin,
const VkSubpassBeginInfo* pSubpassBeginInfo);or the equivalent command
void vkCmdBeginRenderPass2KHR(
VkCommandBuffer commandBuffer,
const VkRenderPassBeginInfo* pRenderPassBegin,
const VkSubpassBeginInfo* pSubpassBeginInfo);Parameters
-
commandBufferis the command buffer in which to record the command. -
pRenderPassBeginis a pointer to a VkRenderPassBeginInfo structure specifying the render pass to begin an instance of, and the framebuffer the instance uses. -
pSubpassBeginInfois a pointer to a VkSubpassBeginInfo structure containing information about the subpass which is about to begin rendering.
Description
After beginning a render pass instance, the command buffer is ready to record the commands for the first subpass of that render pass.
Document Notes
For more information, see the Vulkan Specification
This page is extracted from the Vulkan Specification. Fixes and changes should be made to the Specification, not directly.
vkCmdBeginTransformFeedbackEXT(3)
C Specification
Transform feedback for specific transform feedback buffers is made active by calling:
void vkCmdBeginTransformFeedbackEXT(
VkCommandBuffer commandBuffer,
uint32_t firstCounterBuffer,
uint32_t counterBufferCount,
const VkBuffer* pCounterBuffers,
const VkDeviceSize* pCounterBufferOffsets);Parameters
-
commandBufferis the command buffer into which the command is recorded. -
firstCounterBufferis the index of the first transform feedback buffer corresponding topCounterBuffers[0] andpCounterBufferOffsets[0]. -
counterBufferCountis the size of thepCounterBuffersandpCounterBufferOffsetsarrays. -
pCounterBuffersis an optional array of buffer handles to the counter buffers which contain a 4 byte integer value representing the byte offset from the start of the corresponding transform feedback buffer from where to start capturing vertex data. If the byte offset stored to the counter buffer location was done using vkCmdEndTransformFeedbackEXT it can be used to resume transform feedback from the previous location. IfpCounterBuffersisNULL, then transform feedback will start capturing vertex data to byte offset zero in all bound transform feedback buffers. For each element ofpCounterBuffersthat is VK_NULL_HANDLE, transform feedback will start capturing vertex data to byte zero in the corresponding bound transform feedback buffer. -
pCounterBufferOffsetsis an optional array of offsets within each of thepCounterBufferswhere the counter values were previously written. The location in each counter buffer at these offsets must be large enough to contain 4 bytes of data. This data is the number of bytes captured by the previous transform feedback to this buffer. IfpCounterBufferOffsetsisNULL, then it is assumed the offsets are zero.
Description
The active transform feedback buffers will capture primitives emitted from
the corresponding XfbBuffer in the bound graphics pipeline.
Any XfbBuffer emitted that does not output to an active transform
feedback buffer will not be captured.
See Also
VkBuffer, VkCommandBuffer, VkDeviceSize
Document Notes
For more information, see the Vulkan Specification
This page is extracted from the Vulkan Specification. Fixes and changes should be made to the Specification, not directly.
vkCmdBindDescriptorSets(3)
C Specification
To bind one or more descriptor sets to a command buffer, call:
void vkCmdBindDescriptorSets(
VkCommandBuffer commandBuffer,
VkPipelineBindPoint pipelineBindPoint,
VkPipelineLayout layout,
uint32_t firstSet,
uint32_t descriptorSetCount,
const VkDescriptorSet* pDescriptorSets,
uint32_t dynamicOffsetCount,
const uint32_t* pDynamicOffsets);Parameters
-
commandBufferis the command buffer that the descriptor sets will be bound to. -
pipelineBindPointis a VkPipelineBindPoint indicating whether the descriptors will be used by graphics pipelines or compute pipelines. There is a separate set of bind points for each of graphics and compute, so binding one does not disturb the other. -
layoutis a VkPipelineLayout object used to program the bindings. -
firstSetis the set number of the first descriptor set to be bound. -
descriptorSetCountis the number of elements in thepDescriptorSetsarray. -
pDescriptorSetsis a pointer to an array of handles to VkDescriptorSet objects describing the descriptor sets to write to. -
dynamicOffsetCountis the number of dynamic offsets in thepDynamicOffsetsarray. -
pDynamicOffsetsis a pointer to an array ofuint32_tvalues specifying dynamic offsets.
Description
vkCmdBindDescriptorSets causes the sets numbered [firstSet..
firstSet+descriptorSetCount-1] to use the bindings stored in
pDescriptorSets[0..descriptorSetCount-1] for subsequent rendering
commands (either compute or graphics, according to the
pipelineBindPoint).
Any bindings that were previously applied via these sets are no longer
valid.
Once bound, a descriptor set affects rendering of subsequent graphics or compute commands in the command buffer until a different set is bound to the same set number, or else until the set is disturbed as described in Pipeline Layout Compatibility.
A compatible descriptor set must be bound for all set numbers that any shaders in a pipeline access, at the time that a draw or dispatch command is recorded to execute using that pipeline. However, if none of the shaders in a pipeline statically use any bindings with a particular set number, then no descriptor set need be bound for that set number, even if the pipeline layout includes a non-trivial descriptor set layout for that set number.
If any of the sets being bound include dynamic uniform or storage buffers,
then pDynamicOffsets includes one element for each array element in
each dynamic descriptor type binding in each set.
Values are taken from pDynamicOffsets in an order such that all
entries for set N come before set N+1; within a set, entries are ordered by
the binding numbers in the descriptor set layouts; and within a binding
array, elements are in order.
dynamicOffsetCount must equal the total number of dynamic descriptors
in the sets being bound.
The effective offset used for dynamic uniform and storage buffer bindings is
the sum of the relative offset taken from pDynamicOffsets, and the
base address of the buffer plus base offset in the descriptor set.
The range of the dynamic uniform and storage buffer bindings is the buffer
range as specified in the descriptor set.
Each of the pDescriptorSets must be compatible with the pipeline
layout specified by layout.
The layout used to program the bindings must also be compatible with the
pipeline used in subsequent graphics or compute commands, as defined in the
Pipeline Layout Compatibility section.
The descriptor set contents bound by a call to vkCmdBindDescriptorSets
may be consumed at the following times:
-
For descriptor bindings created with the
VK_DESCRIPTOR_BINDING_UPDATE_AFTER_BIND_BITbit set, the contents may be consumed when the command buffer is submitted to a queue, or during shader execution of the resulting draws and dispatches, or any time in between. Otherwise, -
during host execution of the command, or during shader execution of the resulting draws and dispatches, or any time in between.
Thus, the contents of a descriptor set binding must not be altered (overwritten by an update command, or freed) between the first point in time that it may be consumed, and when the command completes executing on the queue.
The contents of pDynamicOffsets are consumed immediately during
execution of vkCmdBindDescriptorSets.
Once all pending uses have completed, it is legal to update and reuse a
descriptor set.
Document Notes
For more information, see the Vulkan Specification
This page is extracted from the Vulkan Specification. Fixes and changes should be made to the Specification, not directly.
vkCmdBindIndexBuffer(3)
C Specification
To bind an index buffer to a command buffer, call:
void vkCmdBindIndexBuffer(
VkCommandBuffer commandBuffer,
VkBuffer buffer,
VkDeviceSize offset,
VkIndexType indexType);Parameters
-
commandBufferis the command buffer into which the command is recorded. -
bufferis the buffer being bound. -
offsetis the starting offset in bytes withinbufferused in index buffer address calculations. -
indexTypeis a VkIndexType value specifying whether indices are treated as 16 bits or 32 bits.
See Also
VkBuffer, VkCommandBuffer, VkDeviceSize, VkIndexType
Document Notes
For more information, see the Vulkan Specification
This page is extracted from the Vulkan Specification. Fixes and changes should be made to the Specification, not directly.
vkCmdBindPipeline(3)
C Specification
Once a pipeline has been created, it can be bound to the command buffer using the command:
void vkCmdBindPipeline(
VkCommandBuffer commandBuffer,
VkPipelineBindPoint pipelineBindPoint,
VkPipeline pipeline);Parameters
-
commandBufferis the command buffer that the pipeline will be bound to. -
pipelineBindPointis a VkPipelineBindPoint value specifying whether to bind to the compute or graphics bind point. Binding one does not disturb the other. -
pipelineis the pipeline to be bound.
Description
Once bound, a pipeline binding affects subsequent graphics or compute
commands in the command buffer until a different pipeline is bound to the
bind point.
The pipeline bound to VK_PIPELINE_BIND_POINT_COMPUTE controls the
behavior of vkCmdDispatch and vkCmdDispatchIndirect.
The pipeline bound to VK_PIPELINE_BIND_POINT_GRAPHICS controls the
behavior of all drawing commands.
The pipeline bound to VK_PIPELINE_BIND_POINT_RAY_TRACING_NV controls
the behavior of vkCmdTraceRaysNV.
No other commands are affected by the pipeline state.
Document Notes
For more information, see the Vulkan Specification
This page is extracted from the Vulkan Specification. Fixes and changes should be made to the Specification, not directly.
vkCmdBindShadingRateImageNV(3)
C Specification
When shading rate image usage is enabled in the bound pipeline, the pipeline uses a shading rate image specified by the command:
void vkCmdBindShadingRateImageNV(
VkCommandBuffer commandBuffer,
VkImageView imageView,
VkImageLayout imageLayout);Parameters
-
commandBufferis the command buffer into which the command will be recorded. -
imageViewis an image view handle specifying the shading rate image.imageViewmay be set to VK_NULL_HANDLE, which is equivalent to specifying a view of an image filled with zero values. -
imageLayoutis the layout that the image subresources accessible fromimageViewwill be in when the shading rate image is accessed.
Document Notes
For more information, see the Vulkan Specification
This page is extracted from the Vulkan Specification. Fixes and changes should be made to the Specification, not directly.
vkCmdBindTransformFeedbackBuffersEXT(3)
C Specification
To bind transform feedback buffers to a command buffer for use in subsequent draw commands, call:
void vkCmdBindTransformFeedbackBuffersEXT(
VkCommandBuffer commandBuffer,
uint32_t firstBinding,
uint32_t bindingCount,
const VkBuffer* pBuffers,
const VkDeviceSize* pOffsets,
const VkDeviceSize* pSizes);Parameters
-
commandBufferis the command buffer into which the command is recorded. -
firstBindingis the index of the first transform feedback binding whose state is updated by the command. -
bindingCountis the number of transform feedback bindings whose state is updated by the command. -
pBuffersis a pointer to an array of buffer handles. -
pOffsetsis a pointer to an array of buffer offsets. -
pSizesis an optional array of buffer sizes, specifying the maximum number of bytes to capture to the corresponding transform feedback buffer. IfpSizesisNULL, or the value of thepSizesarray element isVK_WHOLE_SIZE, then the maximum bytes captured will be the size of the corresponding buffer minus the buffer offset.
Description
The values taken from elements i of pBuffers, pOffsets and
pSizes replace the current state for the transform feedback binding
firstBinding + i, for i in [0,
bindingCount).
The transform feedback binding is updated to start at the offset indicated
by pOffsets[i] from the start of the buffer pBuffers[i].
See Also
VkBuffer, VkCommandBuffer, VkDeviceSize
Document Notes
For more information, see the Vulkan Specification
This page is extracted from the Vulkan Specification. Fixes and changes should be made to the Specification, not directly.
vkCmdBindVertexBuffers(3)
C Specification
To bind vertex buffers to a command buffer for use in subsequent draw commands, call:
void vkCmdBindVertexBuffers(
VkCommandBuffer commandBuffer,
uint32_t firstBinding,
uint32_t bindingCount,
const VkBuffer* pBuffers,
const VkDeviceSize* pOffsets);Parameters
-
commandBufferis the command buffer into which the command is recorded. -
firstBindingis the index of the first vertex input binding whose state is updated by the command. -
bindingCountis the number of vertex input bindings whose state is updated by the command. -
pBuffersis a pointer to an array of buffer handles. -
pOffsetsis a pointer to an array of buffer offsets.
Description
The values taken from elements i of pBuffers and pOffsets
replace the current state for the vertex input binding
firstBinding + i, for i in [0,
bindingCount).
The vertex input binding is updated to start at the offset indicated by
pOffsets[i] from the start of the buffer pBuffers[i].
All vertex input attributes that use each of these bindings will use these
updated addresses in their address calculations for subsequent draw
commands.
See Also
VkBuffer, VkCommandBuffer, VkDeviceSize
Document Notes
For more information, see the Vulkan Specification
This page is extracted from the Vulkan Specification. Fixes and changes should be made to the Specification, not directly.
vkCmdBlitImage(3)
C Specification
To copy regions of a source image into a destination image, potentially performing format conversion, arbitrary scaling, and filtering, call:
void vkCmdBlitImage(
VkCommandBuffer commandBuffer,
VkImage srcImage,
VkImageLayout srcImageLayout,
VkImage dstImage,
VkImageLayout dstImageLayout,
uint32_t regionCount,
const VkImageBlit* pRegions,
VkFilter filter);Parameters
-
commandBufferis the command buffer into which the command will be recorded. -
srcImageis the source image. -
srcImageLayoutis the layout of the source image subresources for the blit. -
dstImageis the destination image. -
dstImageLayoutis the layout of the destination image subresources for the blit. -
regionCountis the number of regions to blit. -
pRegionsis a pointer to an array of VkImageBlit structures specifying the regions to blit. -
filteris a VkFilter specifying the filter to apply if the blits require scaling.
Description
vkCmdBlitImage must not be used for multisampled source or
destination images.
Use vkCmdResolveImage for this purpose.
As the sizes of the source and destination extents can differ in any dimension, texels in the source extent are scaled and filtered to the destination extent. Scaling occurs via the following operations:
-
For each destination texel, the integer coordinate of that texel is converted to an unnormalized texture coordinate, using the effective inverse of the equations described in unnormalized to integer conversion:
-
ubase = i + ½
-
vbase = j + ½
-
wbase = k + ½
-
-
These base coordinates are then offset by the first destination offset:
-
uoffset = ubase - xdst0
-
voffset = vbase - ydst0
-
woffset = wbase - zdst0
-
aoffset = a -
baseArrayCountdst
-
-
The scale is determined from the source and destination regions, and applied to the offset coordinates:
-
scale_u = (xsrc1 - xsrc0) / (xdst1 - xdst0)
-
scale_v = (ysrc1 - ysrc0) / (ydst1 - ydst0)
-
scale_w = (zsrc1 - zsrc0) / (zdst1 - zdst0)
-
uscaled = uoffset * scaleu
-
vscaled = voffset * scalev
-
wscaled = woffset * scalew
-
-
Finally the source offset is added to the scaled coordinates, to determine the final unnormalized coordinates used to sample from
srcImage:-
u = uscaled + xsrc0
-
v = vscaled + ysrc0
-
w = wscaled + zsrc0
-
q =
mipLevel -
a = aoffset +
baseArrayCountsrc
-
These coordinates are used to sample from the source image, as described in
Image Operations chapter, with the filter mode equal to that
of filter, a mipmap mode of VK_SAMPLER_MIPMAP_MODE_NEAREST and
an address mode of VK_SAMPLER_ADDRESS_MODE_CLAMP_TO_EDGE.
Implementations must clamp at the edge of the source image, and may
additionally clamp to the edge of the source region.
|
Note
Due to allowable rounding errors in the generation of the source texture coordinates, it is not always possible to guarantee exactly which source texels will be sampled for a given blit. As rounding errors are implementation dependent, the exact results of a blitting operation are also implementation dependent. |
Blits are done layer by layer starting with the baseArrayLayer member
of srcSubresource for the source and dstSubresource for the
destination.
layerCount layers are blitted to the destination image.
3D textures are blitted slice by slice.
Slices in the source region bounded by srcOffsets[0].z and
srcOffsets[1].z are copied to slices in the destination region bounded
by dstOffsets[0].z and dstOffsets[1].z.
For each destination slice, a source z coordinate is linearly interpolated
between srcOffsets[0].z and srcOffsets[1].z.
If the filter parameter is VK_FILTER_LINEAR then the value
sampled from the source image is taken by doing linear filtering using the
interpolated z coordinate.
If filter parameter is VK_FILTER_NEAREST then the value sampled
from the source image is taken from the single nearest slice, with an
implementation-dependent arithmetic rounding mode.
The following filtering and conversion rules apply:
-
Integer formats can only be converted to other integer formats with the same signedness.
-
No format conversion is supported between depth/stencil images. The formats must match.
-
Format conversions on unorm, snorm, unscaled and packed float formats of the copied aspect of the image are performed by first converting the pixels to float values.
-
For sRGB source formats, nonlinear RGB values are converted to linear representation prior to filtering.
-
After filtering, the float values are first clamped and then cast to the destination image format. In case of sRGB destination format, linear RGB values are converted to nonlinear representation before writing the pixel to the image.
Signed and unsigned integers are converted by first clamping to the representable range of the destination format, then casting the value.
Document Notes
For more information, see the Vulkan Specification
This page is extracted from the Vulkan Specification. Fixes and changes should be made to the Specification, not directly.
vkCmdBuildAccelerationStructureNV(3)
C Specification
To build an acceleration structure call:
void vkCmdBuildAccelerationStructureNV(
VkCommandBuffer commandBuffer,
const VkAccelerationStructureInfoNV* pInfo,
VkBuffer instanceData,
VkDeviceSize instanceOffset,
VkBool32 update,
VkAccelerationStructureNV dst,
VkAccelerationStructureNV src,
VkBuffer scratch,
VkDeviceSize scratchOffset);Parameters
-
commandBufferis the command buffer into which the command will be recorded. -
pInfocontains the shared information for the acceleration structure’s structure. -
instanceDatais the buffer containing instance data that will be used to build the acceleration structure as described in Accelerator structure instances. This parameter must beNULLfor bottom level acceleration structures. -
instanceOffsetis the offset in bytes (relative to the start ofinstanceData) at which the instance data is located. -
updatespecifies whether to update thedstacceleration structure with the data insrc. -
dstis a pointer to the target acceleration structure for the build. -
srcis a pointer to an existing acceleration structure that is to be used to update thedstacceleration structure. -
scratchis the VkBuffer that will be used as scratch memory for the build. -
scratchOffsetis the offset in bytes relative to the start ofscratchthat will be used as a scratch memory.
See Also
VkAccelerationStructureInfoNV, VkAccelerationStructureNV, VkBool32, VkBuffer, VkCommandBuffer, VkDeviceSize
Document Notes
For more information, see the Vulkan Specification
This page is extracted from the Vulkan Specification. Fixes and changes should be made to the Specification, not directly.
vkCmdClearAttachments(3)
C Specification
To clear one or more regions of color and depth/stencil attachments inside a render pass instance, call:
void vkCmdClearAttachments(
VkCommandBuffer commandBuffer,
uint32_t attachmentCount,
const VkClearAttachment* pAttachments,
uint32_t rectCount,
const VkClearRect* pRects);Parameters
-
commandBufferis the command buffer into which the command will be recorded. -
attachmentCountis the number of entries in thepAttachmentsarray. -
pAttachmentsis a pointer to an array of VkClearAttachment structures defining the attachments to clear and the clear values to use. If any attachment to be cleared in the current subpass isVK_ATTACHMENT_UNUSED, then the clear has no effect on that attachment. -
rectCountis the number of entries in thepRectsarray. -
pRectsis a pointer to an array of VkClearRect structures defining regions within each selected attachment to clear.
Description
vkCmdClearAttachments can clear multiple regions of each attachment
used in the current subpass of a render pass instance.
This command must be called only inside a render pass instance, and
implicitly selects the images to clear based on the current framebuffer
attachments and the command parameters.
If the render pass has a fragment density map attachment, clears follow the operations of fragment density maps as if each clear region was a primitive which generates fragments. The clear color is applied to all pixels inside each fragment’s area regardless if the pixels lie outside of the clear region. Clears may have a different set of supported fragment areas than draws.
Unlike other clear commands, vkCmdClearAttachments executes
as a drawing command, rather than a transfer command, with writes performed
by it executing in rasterization order.
Clears to color attachments are executed as color attachment writes, by the
VK_PIPELINE_STAGE_COLOR_ATTACHMENT_OUTPUT_BIT stage.
Clears to depth/stencil attachments are executed as depth
writes and writes by the
VK_PIPELINE_STAGE_EARLY_FRAGMENT_TESTS_BIT and
VK_PIPELINE_STAGE_LATE_FRAGMENT_TESTS_BIT stages.
Document Notes
For more information, see the Vulkan Specification
This page is extracted from the Vulkan Specification. Fixes and changes should be made to the Specification, not directly.
vkCmdClearColorImage(3)
C Specification
To clear one or more subranges of a color image, call:
void vkCmdClearColorImage(
VkCommandBuffer commandBuffer,
VkImage image,
VkImageLayout imageLayout,
const VkClearColorValue* pColor,
uint32_t rangeCount,
const VkImageSubresourceRange* pRanges);Parameters
-
commandBufferis the command buffer into which the command will be recorded. -
imageis the image to be cleared. -
imageLayoutspecifies the current layout of the image subresource ranges to be cleared, and must beVK_IMAGE_LAYOUT_SHARED_PRESENT_KHR,VK_IMAGE_LAYOUT_GENERALorVK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL. -
pColoris a pointer to a VkClearColorValue structure containing the values that the image subresource ranges will be cleared to (see https://www.khronos.org/registry/vulkan/specs/1.2-extensions/html/vkspec.html#clears-values below). -
rangeCountis the number of image subresource range structures inpRanges. -
pRangesis a pointer to an array of VkImageSubresourceRange structures describing a range of mipmap levels, array layers, and aspects to be cleared, as described in Image Views.
Document Notes
For more information, see the Vulkan Specification
This page is extracted from the Vulkan Specification. Fixes and changes should be made to the Specification, not directly.
vkCmdClearDepthStencilImage(3)
C Specification
To clear one or more subranges of a depth/stencil image, call:
void vkCmdClearDepthStencilImage(
VkCommandBuffer commandBuffer,
VkImage image,
VkImageLayout imageLayout,
const VkClearDepthStencilValue* pDepthStencil,
uint32_t rangeCount,
const VkImageSubresourceRange* pRanges);Parameters
-
commandBufferis the command buffer into which the command will be recorded. -
imageis the image to be cleared. -
imageLayoutspecifies the current layout of the image subresource ranges to be cleared, and must beVK_IMAGE_LAYOUT_GENERALorVK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL. -
pDepthStencilis a pointer to a VkClearDepthStencilValue structure containing the values that the depth and stencil image subresource ranges will be cleared to (see https://www.khronos.org/registry/vulkan/specs/1.2-extensions/html/vkspec.html#clears-values below). -
rangeCountis the number of image subresource range structures inpRanges. -
pRangesis a pointer to an array of VkImageSubresourceRange structures describing a range of mipmap levels, array layers, and aspects to be cleared, as described in Image Views.
Document Notes
For more information, see the Vulkan Specification
This page is extracted from the Vulkan Specification. Fixes and changes should be made to the Specification, not directly.
vkCmdCopyAccelerationStructureNV(3)
C Specification
To copy an acceleration structure call:
void vkCmdCopyAccelerationStructureNV(
VkCommandBuffer commandBuffer,
VkAccelerationStructureNV dst,
VkAccelerationStructureNV src,
VkCopyAccelerationStructureModeNV mode);Parameters
-
commandBufferis the command buffer into which the command will be recorded. -
dstis a pointer to the target acceleration structure for the copy. -
srcis a pointer to the source acceleration structure for the copy. -
modeis a VkCopyAccelerationStructureModeNV value specifying additional operations to perform during the copy.
Document Notes
For more information, see the Vulkan Specification
This page is extracted from the Vulkan Specification. Fixes and changes should be made to the Specification, not directly.
vkCmdCopyBuffer(3)
C Specification
To copy data between buffer objects, call:
void vkCmdCopyBuffer(
VkCommandBuffer commandBuffer,
VkBuffer srcBuffer,
VkBuffer dstBuffer,
uint32_t regionCount,
const VkBufferCopy* pRegions);Parameters
-
commandBufferis the command buffer into which the command will be recorded. -
srcBufferis the source buffer. -
dstBufferis the destination buffer. -
regionCountis the number of regions to copy. -
pRegionsis a pointer to an array of VkBufferCopy structures specifying the regions to copy.
Description
Each region in pRegions is copied from the source buffer to the same
region of the destination buffer.
srcBuffer and dstBuffer can be the same buffer or alias the
same memory, but the resulting values are undefined if the copy regions
overlap in memory.
Document Notes
For more information, see the Vulkan Specification
This page is extracted from the Vulkan Specification. Fixes and changes should be made to the Specification, not directly.
vkCmdCopyBufferToImage(3)
C Specification
To copy data from a buffer object to an image object, call:
void vkCmdCopyBufferToImage(
VkCommandBuffer commandBuffer,
VkBuffer srcBuffer,
VkImage dstImage,
VkImageLayout dstImageLayout,
uint32_t regionCount,
const VkBufferImageCopy* pRegions);Parameters
-
commandBufferis the command buffer into which the command will be recorded. -
srcBufferis the source buffer. -
dstImageis the destination image. -
dstImageLayoutis the layout of the destination image subresources for the copy. -
regionCountis the number of regions to copy. -
pRegionsis a pointer to an array of VkBufferImageCopy structures specifying the regions to copy.
Description
Each region in pRegions is copied from the specified region of the
source buffer to the specified region of the destination image.
If the format of dstImage is a
multi-planar image format),
regions of each plane to be a target of a copy must be specified separately
using the pRegions member of the VkBufferImageCopy structure.
In this case, the aspectMask of imageSubresource must be
VK_IMAGE_ASPECT_PLANE_0_BIT, VK_IMAGE_ASPECT_PLANE_1_BIT, or
VK_IMAGE_ASPECT_PLANE_2_BIT.
For the purposes of vkCmdCopyBufferToImage, each plane of a
multi-planar image is treated as having the format listed in
https://www.khronos.org/registry/vulkan/specs/1.2-extensions/html/vkspec.html#formats-compatible-planes for the plane identified by the
aspectMask of the corresponding subresource.
This applies both to VkFormat and to coordinates used in the copy,
which correspond to texels in the plane rather than how these texels map
to coordinates in the image as a whole.
Document Notes
For more information, see the Vulkan Specification
This page is extracted from the Vulkan Specification. Fixes and changes should be made to the Specification, not directly.
vkCmdCopyImage(3)
C Specification
To copy data between image objects, call:
void vkCmdCopyImage(
VkCommandBuffer commandBuffer,
VkImage srcImage,
VkImageLayout srcImageLayout,
VkImage dstImage,
VkImageLayout dstImageLayout,
uint32_t regionCount,
const VkImageCopy* pRegions);Parameters
-
commandBufferis the command buffer into which the command will be recorded. -
srcImageis the source image. -
srcImageLayoutis the current layout of the source image subresource. -
dstImageis the destination image. -
dstImageLayoutis the current layout of the destination image subresource. -
regionCountis the number of regions to copy. -
pRegionsis a pointer to an array of VkImageCopy structures specifying the regions to copy.
Description
Each region in pRegions is copied from the source image to the same
region of the destination image.
srcImage and dstImage can be the same image or alias the same
memory.
The formats of srcImage and dstImage must be compatible.
Formats are compatible if they share the same class, as shown in the
Compatible Formats table.
Depth/stencil formats must match exactly.
If the format of srcImage or dstImage is a
multi-planar image format,
regions of each plane to be copied must be specified separately using the
srcSubresource and dstSubresource members of the
VkImageCopy structure.
In this case, the aspectMask of the srcSubresource or
dstSubresource that refers to the multi-planar image must be
VK_IMAGE_ASPECT_PLANE_0_BIT, VK_IMAGE_ASPECT_PLANE_1_BIT, or
VK_IMAGE_ASPECT_PLANE_2_BIT.
For the purposes of vkCmdCopyImage, each plane of a multi-planar image
is treated as having the format listed in https://www.khronos.org/registry/vulkan/specs/1.2-extensions/html/vkspec.html#formats-compatible-planes for
the plane identified by the aspectMask of the corresponding
subresource.
This applies both to VkFormat and to coordinates used in the copy,
which correspond to texels in the plane rather than how these texels map
to coordinates in the image as a whole.
|
Note
For example, the |
vkCmdCopyImage allows copying between size-compatible compressed and
uncompressed internal formats.
Formats are size-compatible if the texel block size of the uncompressed
format is equal to the texel block size of the compressed format.
Such a copy does not perform on-the-fly compression or decompression.
When copying from an uncompressed format to a compressed format, each texel
of uncompressed data of the source image is copied as a raw value to the
corresponding compressed texel block of the destination image.
When copying from a compressed format to an uncompressed format, each
compressed texel block of the source image is copied as a raw value to the
corresponding texel of uncompressed data in the destination image.
Thus, for example, it is legal to copy between a 128-bit uncompressed format
and a compressed format which has a 128-bit sized compressed texel block
representing 4×4 texels (using 8 bits per texel), or between a 64-bit
uncompressed format and a compressed format which has a 64-bit sized
compressed texel block representing 4×4 texels (using 4 bits per
texel).
When copying between compressed and uncompressed formats the extent
members represent the texel dimensions of the source image and not the
destination.
When copying from a compressed image to an uncompressed image the image
texel dimensions written to the uncompressed image will be source extent
divided by the compressed texel block dimensions.
When copying from an uncompressed image to a compressed image the image
texel dimensions written to the compressed image will be the source extent
multiplied by the compressed texel block dimensions.
In both cases the number of bytes read and the number of bytes written will
be identical.
Copying to or from block-compressed images is typically done in multiples of
the compressed texel block size.
For this reason the extent must be a multiple of the compressed texel
block dimension.
There is one exception to this rule which is required to handle compressed
images created with dimensions that are not a multiple of the compressed
texel block dimensions: if the srcImage is compressed, then:
-
If
extent.widthis not a multiple of the compressed texel block width, then (extent.width+srcOffset.x) must equal the image subresource width. -
If
extent.heightis not a multiple of the compressed texel block height, then (extent.height+srcOffset.y) must equal the image subresource height. -
If
extent.depthis not a multiple of the compressed texel block depth, then (extent.depth+srcOffset.z) must equal the image subresource depth.
Similarly, if the dstImage is compressed, then:
-
If
extent.widthis not a multiple of the compressed texel block width, then (extent.width+dstOffset.x) must equal the image subresource width. -
If
extent.heightis not a multiple of the compressed texel block height, then (extent.height+dstOffset.y) must equal the image subresource height. -
If
extent.depthis not a multiple of the compressed texel block depth, then (extent.depth+dstOffset.z) must equal the image subresource depth.
This allows the last compressed texel block of the image in each non-multiple dimension to be included as a source or destination of the copy.
“_422” image formats that are not
multi-planar are treated as
having a 2×1 compressed texel block for the purposes of these rules.
vkCmdCopyImage can be used to copy image data between multisample
images, but both images must have the same number of samples.
Document Notes
For more information, see the Vulkan Specification
This page is extracted from the Vulkan Specification. Fixes and changes should be made to the Specification, not directly.
vkCmdCopyImageToBuffer(3)
C Specification
To copy data from an image object to a buffer object, call:
void vkCmdCopyImageToBuffer(
VkCommandBuffer commandBuffer,
VkImage srcImage,
VkImageLayout srcImageLayout,
VkBuffer dstBuffer,
uint32_t regionCount,
const VkBufferImageCopy* pRegions);Parameters
-
commandBufferis the command buffer into which the command will be recorded. -
srcImageis the source image. -
srcImageLayoutis the layout of the source image subresources for the copy. -
dstBufferis the destination buffer. -
regionCountis the number of regions to copy. -
pRegionsis a pointer to an array of VkBufferImageCopy structures specifying the regions to copy.
Description
Each region in pRegions is copied from the specified region of the
source image to the specified region of the destination buffer.
If the VkFormat of srcImage is a
multi-planar image format,
regions of each plane to be a source of a copy must be specified separately
using the pRegions member of the VkBufferImageCopy structure.
In this case, the aspectMask of imageSubresource must be
VK_IMAGE_ASPECT_PLANE_0_BIT, VK_IMAGE_ASPECT_PLANE_1_BIT, or
VK_IMAGE_ASPECT_PLANE_2_BIT.
For the purposes of vkCmdCopyBufferToImage, each plane of a
multi-planar image is treated as having the format listed in
https://www.khronos.org/registry/vulkan/specs/1.2-extensions/html/vkspec.html#formats-compatible-planes for the plane identified by the
aspectMask of the corresponding subresource.
This applies both to VkFormat and to coordinates used in the copy,
which correspond to texels in the plane rather than how these texels map
to coordinates in the image as a whole.
Document Notes
For more information, see the Vulkan Specification
This page is extracted from the Vulkan Specification. Fixes and changes should be made to the Specification, not directly.
vkCmdCopyQueryPoolResults(3)
C Specification
To copy query statuses and numerical results directly to buffer memory, call:
void vkCmdCopyQueryPoolResults(
VkCommandBuffer commandBuffer,
VkQueryPool queryPool,
uint32_t firstQuery,
uint32_t queryCount,
VkBuffer dstBuffer,
VkDeviceSize dstOffset,
VkDeviceSize stride,
VkQueryResultFlags flags);Parameters
-
commandBufferis the command buffer into which this command will be recorded. -
queryPoolis the query pool managing the queries containing the desired results. -
firstQueryis the initial query index. -
queryCountis the number of queries.firstQueryandqueryCounttogether define a range of queries. -
dstBufferis a VkBuffer object that will receive the results of the copy command. -
dstOffsetis an offset intodstBuffer. -
strideis the stride in bytes between results for individual queries withindstBuffer. The required size of the backing memory fordstBufferis determined as described above for vkGetQueryPoolResults. -
flagsis a bitmask of VkQueryResultFlagBits specifying how and when results are returned.
Description
vkCmdCopyQueryPoolResults is guaranteed to see the effect of previous
uses of vkCmdResetQueryPool in the same queue, without any additional
synchronization.
Thus, the results will always reflect the most recent use of the query.
flags has the same possible values described above for the flags
parameter of vkGetQueryPoolResults, but the different style of
execution causes some subtle behavioral differences.
Because vkCmdCopyQueryPoolResults executes in order with respect to
other query commands, there is less ambiguity about which use of a query is
being requested.
Results for all requested occlusion queries, pipeline statistics queries,
transform feedback queries,
and timestamp queries are written as 64-bit unsigned integer values if
VK_QUERY_RESULT_64_BIT is set or 32-bit unsigned integer values
otherwise.
Performance queries store results in a tightly packed array whose type is
determined by the unit member of the corresponding
VkPerformanceCounterKHR.
If neither of VK_QUERY_RESULT_WAIT_BIT and
VK_QUERY_RESULT_WITH_AVAILABILITY_BIT are set, results are only
written out for queries in the available state.
If VK_QUERY_RESULT_WAIT_BIT is set, the implementation will wait for
each query’s status to be in the available state before retrieving the
numerical results for that query.
This is guaranteed to reflect the most recent use of the query on the same
queue, assuming that the query is not being simultaneously used by other
queues.
If the query does not become available in a finite amount of time (e.g. due
to not issuing a query since the last reset), a VK_ERROR_DEVICE_LOST
error may occur.
Similarly, if VK_QUERY_RESULT_WITH_AVAILABILITY_BIT is set and
VK_QUERY_RESULT_WAIT_BIT is not set, the availability is guaranteed to
reflect the most recent use of the query on the same queue, assuming that
the query is not being simultaneously used by other queues.
As with vkGetQueryPoolResults, implementations must guarantee that if
they return a non-zero availability value, then the numerical results are
valid.
If VK_QUERY_RESULT_PARTIAL_BIT is set, VK_QUERY_RESULT_WAIT_BIT
is not set, and the query’s status is unavailable, an intermediate result
value between zero and the final result value is written for that query.
VK_QUERY_RESULT_PARTIAL_BIT must not be used if the pool’s
queryType is VK_QUERY_TYPE_TIMESTAMP.
vkCmdCopyQueryPoolResults is considered to be a transfer operation,
and its writes to buffer memory must be synchronized using
VK_PIPELINE_STAGE_TRANSFER_BIT and VK_ACCESS_TRANSFER_WRITE_BIT
before using the results.
See Also
VkBuffer, VkCommandBuffer, VkDeviceSize, VkQueryPool, VkQueryResultFlags
Document Notes
For more information, see the Vulkan Specification
This page is extracted from the Vulkan Specification. Fixes and changes should be made to the Specification, not directly.
vkCmdDebugMarkerBeginEXT(3)
C Specification
A marker region can be opened by calling:
void vkCmdDebugMarkerBeginEXT(
VkCommandBuffer commandBuffer,
const VkDebugMarkerMarkerInfoEXT* pMarkerInfo);Parameters
-
commandBufferis the command buffer into which the command is recorded. -
pMarkerInfois a pointer to a VkDebugMarkerMarkerInfoEXT structure specifying the parameters of the marker region to open.
Document Notes
For more information, see the Vulkan Specification
This page is extracted from the Vulkan Specification. Fixes and changes should be made to the Specification, not directly.
vkCmdDebugMarkerEndEXT(3)
C Specification
A marker region can be closed by calling:
void vkCmdDebugMarkerEndEXT(
VkCommandBuffer commandBuffer);Description
An application may open a marker region in one command buffer and close it
in another, or otherwise split marker regions across multiple command
buffers or multiple queue submissions.
When viewed from the linear series of submissions to a single queue, the
calls to vkCmdDebugMarkerBeginEXT and vkCmdDebugMarkerEndEXT
must be matched and balanced.
Document Notes
For more information, see the Vulkan Specification
This page is extracted from the Vulkan Specification. Fixes and changes should be made to the Specification, not directly.
vkCmdDebugMarkerInsertEXT(3)
C Specification
A single marker label can be inserted into a command buffer by calling:
void vkCmdDebugMarkerInsertEXT(
VkCommandBuffer commandBuffer,
const VkDebugMarkerMarkerInfoEXT* pMarkerInfo);Parameters
-
commandBufferis the command buffer into which the command is recorded. -
pMarkerInfois a pointer to a VkDebugMarkerMarkerInfoEXT structure specifying the parameters of the marker to insert.
Document Notes
For more information, see the Vulkan Specification
This page is extracted from the Vulkan Specification. Fixes and changes should be made to the Specification, not directly.
vkCmdDispatch(3)
C Specification
To record a dispatch, call:
void vkCmdDispatch(
VkCommandBuffer commandBuffer,
uint32_t groupCountX,
uint32_t groupCountY,
uint32_t groupCountZ);Parameters
-
commandBufferis the command buffer into which the command will be recorded. -
groupCountXis the number of local workgroups to dispatch in the X dimension. -
groupCountYis the number of local workgroups to dispatch in the Y dimension. -
groupCountZis the number of local workgroups to dispatch in the Z dimension.
Description
When the command is executed, a global workgroup consisting of
groupCountX × groupCountY × groupCountZ
local workgroups is assembled.
Document Notes
For more information, see the Vulkan Specification
This page is extracted from the Vulkan Specification. Fixes and changes should be made to the Specification, not directly.
vkCmdDispatchBase(3)
C Specification
To record a dispatch using non-zero base values for the components of
WorkgroupId, call:
void vkCmdDispatchBase(
VkCommandBuffer commandBuffer,
uint32_t baseGroupX,
uint32_t baseGroupY,
uint32_t baseGroupZ,
uint32_t groupCountX,
uint32_t groupCountY,
uint32_t groupCountZ);or the equivalent command
void vkCmdDispatchBaseKHR(
VkCommandBuffer commandBuffer,
uint32_t baseGroupX,
uint32_t baseGroupY,
uint32_t baseGroupZ,
uint32_t groupCountX,
uint32_t groupCountY,
uint32_t groupCountZ);Parameters
-
commandBufferis the command buffer into which the command will be recorded. -
baseGroupXis the start value for the X component ofWorkgroupId. -
baseGroupYis the start value for the Y component ofWorkgroupId. -
baseGroupZis the start value for the Z component ofWorkgroupId. -
groupCountXis the number of local workgroups to dispatch in the X dimension. -
groupCountYis the number of local workgroups to dispatch in the Y dimension. -
groupCountZis the number of local workgroups to dispatch in the Z dimension.
Description
When the command is executed, a global workgroup consisting of
groupCountX × groupCountY × groupCountZ
local workgroups is assembled, with WorkgroupId values ranging from
[baseGroup*, baseGroup* + groupCount*) in each
component.
vkCmdDispatch is equivalent to
vkCmdDispatchBase(0,0,0,groupCountX,groupCountY,groupCountZ).
Document Notes
For more information, see the Vulkan Specification
This page is extracted from the Vulkan Specification. Fixes and changes should be made to the Specification, not directly.
vkCmdDispatchIndirect(3)
C Specification
To record an indirect command dispatch, call:
void vkCmdDispatchIndirect(
VkCommandBuffer commandBuffer,
VkBuffer buffer,
VkDeviceSize offset);Parameters
-
commandBufferis the command buffer into which the command will be recorded. -
bufferis the buffer containing dispatch parameters. -
offsetis the byte offset intobufferwhere parameters begin.
Description
vkCmdDispatchIndirect behaves similarly to vkCmdDispatch except
that the parameters are read by the device from a buffer during execution.
The parameters of the dispatch are encoded in a
VkDispatchIndirectCommand structure taken from buffer starting
at offset.
See Also
VkBuffer, VkCommandBuffer, VkDeviceSize
Document Notes
For more information, see the Vulkan Specification
This page is extracted from the Vulkan Specification. Fixes and changes should be made to the Specification, not directly.
vkCmdDraw(3)
C Specification
To record a non-indexed draw, call:
void vkCmdDraw(
VkCommandBuffer commandBuffer,
uint32_t vertexCount,
uint32_t instanceCount,
uint32_t firstVertex,
uint32_t firstInstance);Parameters
-
commandBufferis the command buffer into which the command is recorded. -
vertexCountis the number of vertices to draw. -
instanceCountis the number of instances to draw. -
firstVertexis the index of the first vertex to draw. -
firstInstanceis the instance ID of the first instance to draw.
Description
When the command is executed, primitives are assembled using the current
primitive topology and vertexCount consecutive vertex indices with the
first vertexIndex value equal to firstVertex.
The primitives are drawn instanceCount times with instanceIndex
starting with firstInstance and increasing sequentially for each
instance.
The assembled primitives execute the bound graphics pipeline.
Document Notes
For more information, see the Vulkan Specification
This page is extracted from the Vulkan Specification. Fixes and changes should be made to the Specification, not directly.
vkCmdDrawIndexed(3)
C Specification
To record an indexed draw, call:
void vkCmdDrawIndexed(
VkCommandBuffer commandBuffer,
uint32_t indexCount,
uint32_t instanceCount,
uint32_t firstIndex,
int32_t vertexOffset,
uint32_t firstInstance);Parameters
-
commandBufferis the command buffer into which the command is recorded. -
indexCountis the number of vertices to draw. -
instanceCountis the number of instances to draw. -
firstIndexis the base index within the index buffer. -
vertexOffsetis the value added to the vertex index before indexing into the vertex buffer. -
firstInstanceis the instance ID of the first instance to draw.
Description
When the command is executed, primitives are assembled using the current
primitive topology and indexCount vertices whose indices are retrieved
from the index buffer.
The index buffer is treated as an array of tightly packed unsigned integers
of size defined by the vkCmdBindIndexBuffer::indexType parameter
with which the buffer was bound.
The first vertex index is at an offset of firstIndex * indexSize
+ offset within the bound index buffer, where offset is the
offset specified by vkCmdBindIndexBuffer and indexSize is the
byte size of the type specified by indexType.
Subsequent index values are retrieved from consecutive locations in the
index buffer.
Indices are first compared to the primitive restart value, then zero
extended to 32 bits (if the indexType is
VK_INDEX_TYPE_UINT8_EXT or
VK_INDEX_TYPE_UINT16) and have vertexOffset added to them,
before being supplied as the vertexIndex value.
The primitives are drawn instanceCount times with instanceIndex
starting with firstInstance and increasing sequentially for each
instance.
The assembled primitives execute the bound graphics pipeline.
Document Notes
For more information, see the Vulkan Specification
This page is extracted from the Vulkan Specification. Fixes and changes should be made to the Specification, not directly.
vkCmdDrawIndexedIndirect(3)
C Specification
To record an indexed indirect draw, call:
void vkCmdDrawIndexedIndirect(
VkCommandBuffer commandBuffer,
VkBuffer buffer,
VkDeviceSize offset,
uint32_t drawCount,
uint32_t stride);Parameters
-
commandBufferis the command buffer into which the command is recorded. -
bufferis the buffer containing draw parameters. -
offsetis the byte offset intobufferwhere parameters begin. -
drawCountis the number of draws to execute, and can be zero. -
strideis the byte stride between successive sets of draw parameters.
Description
vkCmdDrawIndexedIndirect behaves similarly to vkCmdDrawIndexed
except that the parameters are read by the device from a buffer during
execution.
drawCount draws are executed by the command, with parameters taken
from buffer starting at offset and increasing by stride
bytes for each successive draw.
The parameters of each draw are encoded in an array of
VkDrawIndexedIndirectCommand structures.
If drawCount is less than or equal to one, stride is ignored.
See Also
VkBuffer, VkCommandBuffer, VkDeviceSize
Document Notes
For more information, see the Vulkan Specification
This page is extracted from the Vulkan Specification. Fixes and changes should be made to the Specification, not directly.
vkCmdDrawIndexedIndirectCount(3)
Name
vkCmdDrawIndexedIndirectCount - Perform an indexed indirect draw with the draw count sourced from a buffer
C Specification
To record an indexed draw call with a draw call count sourced from a buffer, call:
void vkCmdDrawIndexedIndirectCount(
VkCommandBuffer commandBuffer,
VkBuffer buffer,
VkDeviceSize offset,
VkBuffer countBuffer,
VkDeviceSize countBufferOffset,
uint32_t maxDrawCount,
uint32_t stride);or the equivalent command
void vkCmdDrawIndexedIndirectCountKHR(
VkCommandBuffer commandBuffer,
VkBuffer buffer,
VkDeviceSize offset,
VkBuffer countBuffer,
VkDeviceSize countBufferOffset,
uint32_t maxDrawCount,
uint32_t stride);or the equivalent command
void vkCmdDrawIndexedIndirectCountAMD(
VkCommandBuffer commandBuffer,
VkBuffer buffer,
VkDeviceSize offset,
VkBuffer countBuffer,
VkDeviceSize countBufferOffset,
uint32_t maxDrawCount,
uint32_t stride);Parameters
-
commandBufferis the command buffer into which the command is recorded. -
bufferis the buffer containing draw parameters. -
offsetis the byte offset intobufferwhere parameters begin. -
countBufferis the buffer containing the draw count. -
countBufferOffsetis the byte offset intocountBufferwhere the draw count begins. -
maxDrawCountspecifies the maximum number of draws that will be executed. The actual number of executed draw calls is the minimum of the count specified incountBufferandmaxDrawCount. -
strideis the byte stride between successive sets of draw parameters.
Description
vkCmdDrawIndexedIndirectCount behaves similarly to
vkCmdDrawIndexedIndirect except that the draw count is read by the
device from a buffer during execution.
The command will read an unsigned 32-bit integer from countBuffer
located at countBufferOffset and use this as the draw count.
See Also
VkBuffer, VkCommandBuffer, VkDeviceSize
Document Notes
For more information, see the Vulkan Specification
This page is extracted from the Vulkan Specification. Fixes and changes should be made to the Specification, not directly.
vkCmdDrawIndirect(3)
C Specification
To record a non-indexed indirect draw, call:
void vkCmdDrawIndirect(
VkCommandBuffer commandBuffer,
VkBuffer buffer,
VkDeviceSize offset,
uint32_t drawCount,
uint32_t stride);Parameters
-
commandBufferis the command buffer into which the command is recorded. -
bufferis the buffer containing draw parameters. -
offsetis the byte offset intobufferwhere parameters begin. -
drawCountis the number of draws to execute, and can be zero. -
strideis the byte stride between successive sets of draw parameters.
Description
vkCmdDrawIndirect behaves similarly to vkCmdDraw except that the
parameters are read by the device from a buffer during execution.
drawCount draws are executed by the command, with parameters taken
from buffer starting at offset and increasing by stride
bytes for each successive draw.
The parameters of each draw are encoded in an array of
VkDrawIndirectCommand structures.
If drawCount is less than or equal to one, stride is ignored.
See Also
VkBuffer, VkCommandBuffer, VkDeviceSize
Document Notes
For more information, see the Vulkan Specification
This page is extracted from the Vulkan Specification. Fixes and changes should be made to the Specification, not directly.
vkCmdDrawIndirectByteCountEXT(3)
Name
vkCmdDrawIndirectByteCountEXT - Draw primitives where the vertex count is derived from the counter byte value in the counter buffer
C Specification
To record a non-indexed draw call, where the vertex count is based on a byte count read from a buffer and the passed in vertex stride parameter, call:
void vkCmdDrawIndirectByteCountEXT(
VkCommandBuffer commandBuffer,
uint32_t instanceCount,
uint32_t firstInstance,
VkBuffer counterBuffer,
VkDeviceSize counterBufferOffset,
uint32_t counterOffset,
uint32_t vertexStride);Parameters
-
commandBufferis the command buffer into which the command is recorded. -
instanceCountis the number of instances to draw. -
firstInstanceis the instance ID of the first instance to draw. -
counterBufferis the buffer handle from where the byte count is read. -
counterBufferOffsetis the offset into the buffer used to read the byte count, which is used to calculate the vertex count for this draw call. -
counterOffsetis subtracted from the byte count read from thecounterBufferat thecounterBufferOffset -
vertexStrideis the stride in bytes between each element of the vertex data that is used to calculate the vertex count from the counter value. This value is typically the same value that was used in the graphics pipeline state when the transform feedback was captured as theXfbStride.
Description
When the command is executed, primitives are assembled in the same way as
done with vkCmdDraw except the vertexCount is calculated based
on the byte count read from counterBuffer at offset
counterBufferOffset.
The assembled primitives execute the bound graphics pipeline.
The effective vertexCount is calculated as follows:
const uint32_t * counterBufferPtr = (const uint8_t *)counterBuffer.address + counterBufferOffset;
vertexCount = floor(max(0, (*counterBufferPtr - counterOffset)) / vertexStride);The effective firstVertex is zero.
See Also
VkBuffer, VkCommandBuffer, VkDeviceSize
Document Notes
For more information, see the Vulkan Specification
This page is extracted from the Vulkan Specification. Fixes and changes should be made to the Specification, not directly.
vkCmdDrawIndirectCount(3)
C Specification
To record a non-indexed draw call with a draw call count sourced from a buffer, call:
void vkCmdDrawIndirectCount(
VkCommandBuffer commandBuffer,
VkBuffer buffer,
VkDeviceSize offset,
VkBuffer countBuffer,
VkDeviceSize countBufferOffset,
uint32_t maxDrawCount,
uint32_t stride);or the equivalent command
void vkCmdDrawIndirectCountKHR(
VkCommandBuffer commandBuffer,
VkBuffer buffer,
VkDeviceSize offset,
VkBuffer countBuffer,
VkDeviceSize countBufferOffset,
uint32_t maxDrawCount,
uint32_t stride);or the equivalent command
void vkCmdDrawIndirectCountAMD(
VkCommandBuffer commandBuffer,
VkBuffer buffer,
VkDeviceSize offset,
VkBuffer countBuffer,
VkDeviceSize countBufferOffset,
uint32_t maxDrawCount,
uint32_t stride);Parameters
-
commandBufferis the command buffer into which the command is recorded. -
bufferis the buffer containing draw parameters. -
offsetis the byte offset intobufferwhere parameters begin. -
countBufferis the buffer containing the draw count. -
countBufferOffsetis the byte offset intocountBufferwhere the draw count begins. -
maxDrawCountspecifies the maximum number of draws that will be executed. The actual number of executed draw calls is the minimum of the count specified incountBufferandmaxDrawCount. -
strideis the byte stride between successive sets of draw parameters.
Description
vkCmdDrawIndirectCount behaves similarly to vkCmdDrawIndirect
except that the draw count is read by the device from a buffer during
execution.
The command will read an unsigned 32-bit integer from countBuffer
located at countBufferOffset and use this as the draw count.
See Also
VkBuffer, VkCommandBuffer, VkDeviceSize
Document Notes
For more information, see the Vulkan Specification
This page is extracted from the Vulkan Specification. Fixes and changes should be made to the Specification, not directly.
vkCmdDrawMeshTasksIndirectCountNV(3)
Name
vkCmdDrawMeshTasksIndirectCountNV - Perform an indirect mesh tasks draw with the draw count sourced from a buffer
C Specification
To record an indirect mesh tasks draw with the draw count sourced from a buffer, call:
void vkCmdDrawMeshTasksIndirectCountNV(
VkCommandBuffer commandBuffer,
VkBuffer buffer,
VkDeviceSize offset,
VkBuffer countBuffer,
VkDeviceSize countBufferOffset,
uint32_t maxDrawCount,
uint32_t stride);Parameters
-
commandBufferis the command buffer into which the command is recorded. -
bufferis the buffer containing draw parameters. -
offsetis the byte offset intobufferwhere parameters begin. -
countBufferis the buffer containing the draw count. -
countBufferOffsetis the byte offset intocountBufferwhere the draw count begins. -
maxDrawCountspecifies the maximum number of draws that will be executed. The actual number of executed draw calls is the minimum of the count specified incountBufferandmaxDrawCount. -
strideis the byte stride between successive sets of draw parameters.
Description
vkCmdDrawMeshTasksIndirectCountNV behaves similarly to
vkCmdDrawMeshTasksIndirectNV except that the draw count is read by the
device from a buffer during execution.
The command will read an unsigned 32-bit integer from countBuffer
located at countBufferOffset and use this as the draw count.
See Also
VkBuffer, VkCommandBuffer, VkDeviceSize
Document Notes
For more information, see the Vulkan Specification
This page is extracted from the Vulkan Specification. Fixes and changes should be made to the Specification, not directly.
vkCmdDrawMeshTasksIndirectNV(3)
C Specification
To record an indirect mesh tasks draw, call:
void vkCmdDrawMeshTasksIndirectNV(
VkCommandBuffer commandBuffer,
VkBuffer buffer,
VkDeviceSize offset,
uint32_t drawCount,
uint32_t stride);Parameters
-
commandBufferis the command buffer into which the command is recorded. -
bufferis the buffer containing draw parameters. -
offsetis the byte offset intobufferwhere parameters begin. -
drawCountis the number of draws to execute, and can be zero. -
strideis the byte stride between successive sets of draw parameters.
Description
vkCmdDrawMeshTasksIndirectNV behaves similarly to
vkCmdDrawMeshTasksNV except that the parameters are read by the device
from a buffer during execution.
drawCount draws are executed by the command, with parameters taken
from buffer starting at offset and increasing by stride
bytes for each successive draw.
The parameters of each draw are encoded in an array of
VkDrawMeshTasksIndirectCommandNV structures.
If drawCount is less than or equal to one, stride is ignored.
See Also
VkBuffer, VkCommandBuffer, VkDeviceSize
Document Notes
For more information, see the Vulkan Specification
This page is extracted from the Vulkan Specification. Fixes and changes should be made to the Specification, not directly.
vkCmdDrawMeshTasksNV(3)
C Specification
To record a draw that uses the mesh pipeline, call:
void vkCmdDrawMeshTasksNV(
VkCommandBuffer commandBuffer,
uint32_t taskCount,
uint32_t firstTask);Parameters
-
commandBufferis the command buffer into which the command will be recorded. -
taskCountis the number of local workgroups to dispatch in the X dimension. Y and Z dimension are implicitly set to one. -
firstTaskis the X component of the first workgroup ID.
Description
When the command is executed, a global workgroup consisting of
taskCount local workgroups is assembled.
Document Notes
For more information, see the Vulkan Specification
This page is extracted from the Vulkan Specification. Fixes and changes should be made to the Specification, not directly.
vkCmdEndConditionalRenderingEXT(3)
C Specification
To end conditional rendering, call:
void vkCmdEndConditionalRenderingEXT(
VkCommandBuffer commandBuffer);Document Notes
For more information, see the Vulkan Specification
This page is extracted from the Vulkan Specification. Fixes and changes should be made to the Specification, not directly.
vkCmdEndDebugUtilsLabelEXT(3)
C Specification
A command buffer label region can be closed by calling:
void vkCmdEndDebugUtilsLabelEXT(
VkCommandBuffer commandBuffer);Description
An application may open a debug label region in one command buffer and close it in another, or otherwise split debug label regions across multiple command buffers or multiple queue submissions. When viewed from the linear series of submissions to a single queue, the calls to vkCmdBeginDebugUtilsLabelEXT and vkCmdEndDebugUtilsLabelEXT must be matched and balanced.
Document Notes
For more information, see the Vulkan Specification
This page is extracted from the Vulkan Specification. Fixes and changes should be made to the Specification, not directly.
vkCmdEndQuery(3)
C Specification
To end a query after the set of desired draw or dispatch commands is executed, call:
void vkCmdEndQuery(
VkCommandBuffer commandBuffer,
VkQueryPool queryPool,
uint32_t query);Parameters
-
commandBufferis the command buffer into which this command will be recorded. -
queryPoolis the query pool that is managing the results of the query. -
queryis the query index within the query pool where the result is stored.
Description
Calling vkCmdEndQuery is equivalent to calling
vkCmdEndQueryIndexedEXT with the index parameter set to zero.
As queries operate asynchronously, ending a query does not immediately set the query’s status to available. A query is considered finished when the final results of the query are ready to be retrieved by vkGetQueryPoolResults and vkCmdCopyQueryPoolResults, and this is when the query’s status is set to available.
Once a query is ended the query must finish in finite time, unless the state of the query is changed using other commands, e.g. by issuing a reset of the query.
Document Notes
For more information, see the Vulkan Specification
This page is extracted from the Vulkan Specification. Fixes and changes should be made to the Specification, not directly.
vkCmdEndQueryIndexedEXT(3)
C Specification
To end an indexed query after the set of desired draw or dispatch commands is recorded, call:
void vkCmdEndQueryIndexedEXT(
VkCommandBuffer commandBuffer,
VkQueryPool queryPool,
uint32_t query,
uint32_t index);Parameters
-
commandBufferis the command buffer into which this command will be recorded. -
queryPoolis the query pool that is managing the results of the query. -
queryis the query index within the query pool where the result is stored. -
indexis the query type specific index.
Description
The vkCmdEndQueryIndexedEXT command operates the same as the
vkCmdEndQuery command, except that it also accepts a query type
specific index parameter.
Document Notes
For more information, see the Vulkan Specification
This page is extracted from the Vulkan Specification. Fixes and changes should be made to the Specification, not directly.
vkCmdEndRenderPass(3)
C Specification
To record a command to end a render pass instance after recording the commands for the last subpass, call:
void vkCmdEndRenderPass(
VkCommandBuffer commandBuffer);Description
Ending a render pass instance performs any multisample resolve operations on the final subpass.
Document Notes
For more information, see the Vulkan Specification
This page is extracted from the Vulkan Specification. Fixes and changes should be made to the Specification, not directly.
vkCmdEndRenderPass2(3)
C Specification
To record a command to end a render pass instance after recording the commands for the last subpass, call:
void vkCmdEndRenderPass2(
VkCommandBuffer commandBuffer,
const VkSubpassEndInfo* pSubpassEndInfo);or the equivalent command
void vkCmdEndRenderPass2KHR(
VkCommandBuffer commandBuffer,
const VkSubpassEndInfo* pSubpassEndInfo);Parameters
-
commandBufferis the command buffer in which to end the current render pass instance. -
pSubpassEndInfois a pointer to a VkSubpassEndInfo structure containing information about how the previous subpass will be ended.
Description
vkCmdEndRenderPass2 is semantically identical to
vkCmdEndRenderPass, except that it is extensible.
Document Notes
For more information, see the Vulkan Specification
This page is extracted from the Vulkan Specification. Fixes and changes should be made to the Specification, not directly.
vkCmdEndTransformFeedbackEXT(3)
C Specification
Transform feedback for specific transform feedback buffers is made inactive by calling:
void vkCmdEndTransformFeedbackEXT(
VkCommandBuffer commandBuffer,
uint32_t firstCounterBuffer,
uint32_t counterBufferCount,
const VkBuffer* pCounterBuffers,
const VkDeviceSize* pCounterBufferOffsets);Parameters
-
commandBufferis the command buffer into which the command is recorded. -
firstCounterBufferis the index of the first transform feedback buffer corresponding topCounterBuffers[0] andpCounterBufferOffsets[0]. -
counterBufferCountis the size of thepCounterBuffersandpCounterBufferOffsetsarrays. -
pCounterBuffersis an optional array of buffer handles to the counter buffers used to record the current byte positions of each transform feedback buffer where the next vertex output data would be captured. This can be used by a subsequent vkCmdBeginTransformFeedbackEXT call to resume transform feedback capture from this position. It can also be used by vkCmdDrawIndirectByteCountEXT to determine the vertex count of the draw call. -
pCounterBufferOffsetsis an optional array of offsets within each of thepCounterBufferswhere the counter values can be written. The location in each counter buffer at these offsets must be large enough to contain 4 bytes of data. The data stored at this location is the byte offset from the start of the transform feedback buffer binding where the next vertex data would be written. IfpCounterBufferOffsetsisNULL, then it is assumed the offsets are zero.
See Also
VkBuffer, VkCommandBuffer, VkDeviceSize
Document Notes
For more information, see the Vulkan Specification
This page is extracted from the Vulkan Specification. Fixes and changes should be made to the Specification, not directly.
vkCmdExecuteCommands(3)
C Specification
A secondary command buffer must not be directly submitted to a queue. Instead, secondary command buffers are recorded to execute as part of a primary command buffer with the command:
void vkCmdExecuteCommands(
VkCommandBuffer commandBuffer,
uint32_t commandBufferCount,
const VkCommandBuffer* pCommandBuffers);Parameters
-
commandBufferis a handle to a primary command buffer that the secondary command buffers are executed in. -
commandBufferCountis the length of thepCommandBuffersarray. -
pCommandBuffersis a pointer to an array ofcommandBufferCountsecondary command buffer handles, which are recorded to execute in the primary command buffer in the order they are listed in the array.
Description
If any element of pCommandBuffers was not recorded with the
VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT flag, and it was recorded
into any other primary command buffer which is currently in the
executable or recording state, that primary
command buffer becomes invalid.
Document Notes
For more information, see the Vulkan Specification
This page is extracted from the Vulkan Specification. Fixes and changes should be made to the Specification, not directly.
vkCmdFillBuffer(3)
C Specification
To clear buffer data, call:
void vkCmdFillBuffer(
VkCommandBuffer commandBuffer,
VkBuffer dstBuffer,
VkDeviceSize dstOffset,
VkDeviceSize size,
uint32_t data);Parameters
-
commandBufferis the command buffer into which the command will be recorded. -
dstBufferis the buffer to be filled. -
dstOffsetis the byte offset into the buffer at which to start filling, and must be a multiple of 4. -
sizeis the number of bytes to fill, and must be either a multiple of 4, orVK_WHOLE_SIZEto fill the range fromoffsetto the end of the buffer. IfVK_WHOLE_SIZEis used and the remaining size of the buffer is not a multiple of 4, then the nearest smaller multiple is used. -
datais the 4-byte word written repeatedly to the buffer to fillsizebytes of data. The data word is written to memory according to the host endianness.
Description
vkCmdFillBuffer is treated as “transfer” operation for the purposes
of synchronization barriers.
The VK_BUFFER_USAGE_TRANSFER_DST_BIT must be specified in usage
of VkBufferCreateInfo in order for the buffer to be compatible with
vkCmdFillBuffer.
See Also
VkBuffer, VkCommandBuffer, VkDeviceSize
Document Notes
For more information, see the Vulkan Specification
This page is extracted from the Vulkan Specification. Fixes and changes should be made to the Specification, not directly.
vkCmdInsertDebugUtilsLabelEXT(3)
C Specification
A single debug label can be inserted into a command buffer by calling:
void vkCmdInsertDebugUtilsLabelEXT(
VkCommandBuffer commandBuffer,
const VkDebugUtilsLabelEXT* pLabelInfo);Parameters
-
commandBufferis the command buffer into which the command is recorded. -
pInfois a pointer to a VkDebugUtilsLabelEXT structure specifying parameters of the label to insert.
Document Notes
For more information, see the Vulkan Specification
This page is extracted from the Vulkan Specification. Fixes and changes should be made to the Specification, not directly.
vkCmdNextSubpass(3)
C Specification
To transition to the next subpass in the render pass instance after recording the commands for a subpass, call:
void vkCmdNextSubpass(
VkCommandBuffer commandBuffer,
VkSubpassContents contents);Parameters
-
commandBufferis the command buffer in which to record the command. -
contentsspecifies how the commands in the next subpass will be provided, in the same fashion as the corresponding parameter of vkCmdBeginRenderPass.
Description
The subpass index for a render pass begins at zero when
vkCmdBeginRenderPass is recorded, and increments each time
vkCmdNextSubpass is recorded.
Moving to the next subpass automatically performs any multisample resolve
operations in the subpass being ended.
End-of-subpass multisample resolves are treated as color attachment writes
for the purposes of synchronization.
This applies to resolve operations for both color and depth/stencil
attachments.
That is, they are considered to execute in the
VK_PIPELINE_STAGE_COLOR_ATTACHMENT_OUTPUT_BIT pipeline stage and their
writes are synchronized with VK_ACCESS_COLOR_ATTACHMENT_WRITE_BIT.
Synchronization between rendering within a subpass and any resolve
operations at the end of the subpass occurs automatically, without need for
explicit dependencies or pipeline barriers.
However, if the resolve attachment is also used in a different subpass, an
explicit dependency is needed.
After transitioning to the next subpass, the application can record the commands for that subpass.
Document Notes
For more information, see the Vulkan Specification
This page is extracted from the Vulkan Specification. Fixes and changes should be made to the Specification, not directly.
vkCmdNextSubpass2(3)
C Specification
To transition to the next subpass in the render pass instance after recording the commands for a subpass, call:
void vkCmdNextSubpass2(
VkCommandBuffer commandBuffer,
const VkSubpassBeginInfo* pSubpassBeginInfo,
const VkSubpassEndInfo* pSubpassEndInfo);or the equivalent command
void vkCmdNextSubpass2KHR(
VkCommandBuffer commandBuffer,
const VkSubpassBeginInfo* pSubpassBeginInfo,
const VkSubpassEndInfo* pSubpassEndInfo);Parameters
-
commandBufferis the command buffer in which to record the command. -
pSubpassBeginInfois a pointer to a VkSubpassBeginInfo structure containing information about the subpass which is about to begin rendering. -
pSubpassEndInfois a pointer to a VkSubpassEndInfo structure containing information about how the previous subpass will be ended.
Description
vkCmdNextSubpass2 is semantically identical to vkCmdNextSubpass,
except that it is extensible, and that contents is provided as part of
an extensible structure instead of as a flat parameter.
Document Notes
For more information, see the Vulkan Specification
This page is extracted from the Vulkan Specification. Fixes and changes should be made to the Specification, not directly.
vkCmdPipelineBarrier(3)
C Specification
To record a pipeline barrier, call:
void vkCmdPipelineBarrier(
VkCommandBuffer commandBuffer,
VkPipelineStageFlags srcStageMask,
VkPipelineStageFlags dstStageMask,
VkDependencyFlags dependencyFlags,
uint32_t memoryBarrierCount,
const VkMemoryBarrier* pMemoryBarriers,
uint32_t bufferMemoryBarrierCount,
const VkBufferMemoryBarrier* pBufferMemoryBarriers,
uint32_t imageMemoryBarrierCount,
const VkImageMemoryBarrier* pImageMemoryBarriers);Parameters
-
commandBufferis the command buffer into which the command is recorded. -
srcStageMaskis a bitmask of VkPipelineStageFlagBits specifying the source stage mask. -
dstStageMaskis a bitmask of VkPipelineStageFlagBits specifying the destination stage mask. -
dependencyFlagsis a bitmask of VkDependencyFlagBits specifying how execution and memory dependencies are formed. -
memoryBarrierCountis the length of thepMemoryBarriersarray. -
pMemoryBarriersis a pointer to an array of VkMemoryBarrier structures. -
bufferMemoryBarrierCountis the length of thepBufferMemoryBarriersarray. -
pBufferMemoryBarriersis a pointer to an array of VkBufferMemoryBarrier structures. -
imageMemoryBarrierCountis the length of thepImageMemoryBarriersarray. -
pImageMemoryBarriersis a pointer to an array of VkImageMemoryBarrier structures.
Description
When vkCmdPipelineBarrier is submitted to a queue, it defines a memory dependency between commands that were submitted before it, and those submitted after it.
If vkCmdPipelineBarrier was recorded outside a render pass instance,
the first synchronization scope
includes all commands that occur earlier in
submission order.
If vkCmdPipelineBarrier was recorded inside a render pass instance,
the first synchronization scope includes only commands that occur earlier in
submission order within the same
subpass.
In either case, the first synchronization scope is limited to operations on
the pipeline stages determined by the
source stage mask specified by
srcStageMask.
If vkCmdPipelineBarrier was recorded outside a render pass instance,
the second synchronization scope
includes all commands that occur later in
submission order.
If vkCmdPipelineBarrier was recorded inside a render pass instance,
the second synchronization scope includes only commands that occur later in
submission order within the same
subpass.
In either case, the second synchronization scope is limited to operations on
the pipeline stages determined by the
destination stage mask specified
by dstStageMask.
The first access scope is
limited to access in the pipeline stages determined by the
source stage mask specified by
srcStageMask.
Within that, the first access scope only includes the first access scopes
defined by elements of the pMemoryBarriers,
pBufferMemoryBarriers and pImageMemoryBarriers arrays, which
each define a set of memory barriers.
If no memory barriers are specified, then the first access scope includes no
accesses.
The second access scope is
limited to access in the pipeline stages determined by the
destination stage mask specified
by dstStageMask.
Within that, the second access scope only includes the second access scopes
defined by elements of the pMemoryBarriers,
pBufferMemoryBarriers and pImageMemoryBarriers arrays, which
each define a set of memory barriers.
If no memory barriers are specified, then the second access scope includes
no accesses.
If dependencyFlags includes VK_DEPENDENCY_BY_REGION_BIT, then
any dependency between framebuffer-space pipeline stages is
framebuffer-local - otherwise it is
framebuffer-global.
Document Notes
For more information, see the Vulkan Specification
This page is extracted from the Vulkan Specification. Fixes and changes should be made to the Specification, not directly.
vkCmdProcessCommandsNVX(3)
C Specification
The actual generation on the device is handled with:
void vkCmdProcessCommandsNVX(
VkCommandBuffer commandBuffer,
const VkCmdProcessCommandsInfoNVX* pProcessCommandsInfo);Parameters
-
commandBufferis the primary command buffer in which the generation process takes space. -
pProcessCommandsInfois a pointer to a VkCmdProcessCommandsInfoNVX structure containing parameters affecting the processing of commands.
Document Notes
For more information, see the Vulkan Specification
This page is extracted from the Vulkan Specification. Fixes and changes should be made to the Specification, not directly.
vkCmdPushConstants(3)
C Specification
To update push constants, call:
void vkCmdPushConstants(
VkCommandBuffer commandBuffer,
VkPipelineLayout layout,
VkShaderStageFlags stageFlags,
uint32_t offset,
uint32_t size,
const void* pValues);Parameters
-
commandBufferis the command buffer in which the push constant update will be recorded. -
layoutis the pipeline layout used to program the push constant updates. -
stageFlagsis a bitmask of VkShaderStageFlagBits specifying the shader stages that will use the push constants in the updated range. -
offsetis the start offset of the push constant range to update, in units of bytes. -
sizeis the size of the push constant range to update, in units of bytes. -
pValuesis a pointer to an array ofsizebytes containing the new push constant values.
Description
|
Note
As |
Document Notes
For more information, see the Vulkan Specification
This page is extracted from the Vulkan Specification. Fixes and changes should be made to the Specification, not directly.
vkCmdPushDescriptorSetKHR(3)
C Specification
In addition to allocating descriptor sets and binding them to a command buffer, an application can record descriptor updates into the command buffer.
To push descriptor updates into a command buffer, call:
void vkCmdPushDescriptorSetKHR(
VkCommandBuffer commandBuffer,
VkPipelineBindPoint pipelineBindPoint,
VkPipelineLayout layout,
uint32_t set,
uint32_t descriptorWriteCount,
const VkWriteDescriptorSet* pDescriptorWrites);Parameters
-
commandBufferis the command buffer that the descriptors will be recorded in. -
pipelineBindPointis a VkPipelineBindPoint indicating whether the descriptors will be used by graphics pipelines or compute pipelines. There is a separate set of push descriptor bindings for each of graphics and compute, so binding one does not disturb the other. -
layoutis a VkPipelineLayout object used to program the bindings. -
setis the set number of the descriptor set in the pipeline layout that will be updated. -
descriptorWriteCountis the number of elements in thepDescriptorWritesarray. -
pDescriptorWritesis a pointer to an array of VkWriteDescriptorSet structures describing the descriptors to be updated.
Description
Push descriptors are a small bank of descriptors whose storage is internally managed by the command buffer rather than being written into a descriptor set and later bound to a command buffer. Push descriptors allow for incremental updates of descriptors without managing the lifetime of descriptor sets.
When a command buffer begins recording, all push descriptors are undefined.
Push descriptors can be updated incrementally and cause shaders to use the
updated descriptors for subsequent rendering commands (either compute or
graphics, according to the pipelineBindPoint) until the descriptor is
overwritten, or else until the set is disturbed as described in
Pipeline Layout Compatibility.
When the set is disturbed or push descriptors with a different descriptor
set layout are set, all push descriptors are undefined.
Push descriptors that are statically used by a
pipeline must not be undefined at the time that a draw or dispatch command
is recorded to execute using that pipeline.
This includes immutable sampler descriptors, which must be pushed before
they are accessed by a pipeline (the immutable samplers are pushed, rather
than the samplers in pDescriptorWrites).
Push descriptors that are not statically used can remain undefined.
Push descriptors do not use dynamic offsets.
Instead, the corresponding non-dynamic descriptor types can be used and the
offset member of VkDescriptorBufferInfo can be changed each
time the descriptor is written.
Each element of pDescriptorWrites is interpreted as in
VkWriteDescriptorSet, except the dstSet member is ignored.
To push an immutable sampler, use a VkWriteDescriptorSet with
dstBinding and dstArrayElement selecting the immutable sampler’s
binding.
If the descriptor type is VK_DESCRIPTOR_TYPE_SAMPLER, the
pImageInfo parameter is ignored and the immutable sampler is taken
from the push descriptor set layout in the pipeline layout.
If the descriptor type is VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER,
the sampler member of the pImageInfo parameter is ignored and
the immutable sampler is taken from the push descriptor set layout in the
pipeline layout.
Document Notes
For more information, see the Vulkan Specification
This page is extracted from the Vulkan Specification. Fixes and changes should be made to the Specification, not directly.
vkCmdPushDescriptorSetWithTemplateKHR(3)
Name
vkCmdPushDescriptorSetWithTemplateKHR - Pushes descriptor updates into a command buffer using a descriptor update template
C Specification
It is also possible to use a descriptor update template to specify the push descriptors to update. To do so, call:
void vkCmdPushDescriptorSetWithTemplateKHR(
VkCommandBuffer commandBuffer,
VkDescriptorUpdateTemplate descriptorUpdateTemplate,
VkPipelineLayout layout,
uint32_t set,
const void* pData);Parameters
-
commandBufferis the command buffer that the descriptors will be recorded in. -
descriptorUpdateTemplateis a descriptor update template defining how to interpret the descriptor information inpData. -
layoutis a VkPipelineLayout object used to program the bindings. It must be compatible with the layout used to create thedescriptorUpdateTemplatehandle. -
setis the set number of the descriptor set in the pipeline layout that will be updated. This must be the same number used to create thedescriptorUpdateTemplatehandle. -
pDatais a pointer to memory containing descriptors for the templated update.