vkCmdBindPipeline - Bind a pipeline object to a command buffer

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 PIPELINE_BIND_POINT_COMPUTE controls the behavior of cmdDispatch and cmdDispatchIndirect. The pipeline bound to PIPELINE_BIND_POINT_GRAPHICS controls the behavior of all drawing commands. The pipeline bound to PIPELINE_BIND_POINT_RAY_TRACING_KHR controls the behavior of cmdTraceRaysKHR. No other commands are affected by the pipeline state.

Valid Usage

• If pipelineBindPoint is PIPELINE_BIND_POINT_COMPUTE, the CommandPool that commandBuffer was allocated from must support compute operations

• If pipelineBindPoint is PIPELINE_BIND_POINT_GRAPHICS, the CommandPool that commandBuffer was allocated from must support graphics operations
• If pipelineBindPoint is PIPELINE_BIND_POINT_COMPUTE, pipeline must be a compute pipeline
• If pipelineBindPoint is PIPELINE_BIND_POINT_GRAPHICS, pipeline must be a graphics pipeline
• If the variable multisample rate feature is not supported, pipeline is a graphics pipeline, the current subpass uses no attachments, and this is not the first call to this function with a graphics pipeline after transitioning to the current subpass, then the sample count specified by this pipeline must match that set in the previous pipeline
• If PhysicalDeviceSampleLocationsPropertiesEXT::variableSampleLocations is FALSE, and pipeline is a graphics pipeline created with a PipelineSampleLocationsStateCreateInfoEXT structure having its sampleLocationsEnable member set to TRUE but without DYNAMIC_STATE_SAMPLE_LOCATIONS_EXT enabled then the current render pass instance must have been begun by specifying a RenderPassSampleLocationsBeginInfoEXT structure whose pPostSubpassSampleLocations member contains an element with a subpassIndex matching the current subpass index and the sampleLocationsInfo member of that element must match the sampleLocationsInfo specified in PipelineSampleLocationsStateCreateInfoEXT when the pipeline was created
• This command must not be recorded when transform feedback is active
• If pipelineBindPoint is PIPELINE_BIND_POINT_RAY_TRACING_KHR, the CommandPool that commandBuffer was allocated from must support compute operations
• If pipelineBindPoint is PIPELINE_BIND_POINT_RAY_TRACING_KHR, the pipeline must be a ray tracing pipeline
• The pipeline must not have been created with PIPELINE_CREATE_LIBRARY_BIT_KHR set

Valid Usage (Implicit)

• commandBuffer must be a valid CommandBuffer handle

• pipelineBindPoint must be a valid PipelineBindPoint value
• pipeline must be a valid Pipeline handle
• commandBuffer must be in the recording state
• The CommandPool that commandBuffer was allocated from must support graphics, or compute operations
• Both of commandBuffer, and pipeline must have been created, allocated, or retrieved from the same Device

Host Synchronization

• Host access to commandBuffer must be externally synchronized

• Host access to the CommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties

'

See Also

CommandBuffer, Pipeline, PipelineBindPoint

vkCmdSetViewport - Set the viewport on a command buffer

Description

The viewport parameters taken from element i of pViewports replace the current state for the viewport index firstViewport + i, for i in [0, viewportCount).

Valid Usage

• firstViewport must be less than PhysicalDeviceLimits::maxViewports

• The sum of firstViewport and viewportCount must be between 1 and PhysicalDeviceLimits::maxViewports, inclusive
• If the multiple viewports feature is not enabled, firstViewport must be 0
• If the multiple viewports feature is not enabled, viewportCount must be 1

Valid Usage (Implicit)

• commandBuffer must be a valid CommandBuffer handle

• pViewports must be a valid pointer to an array of viewportCount valid Viewport structures
• commandBuffer must be in the recording state
• The CommandPool that commandBuffer was allocated from must support graphics operations
• viewportCount must be greater than 0

Host Synchronization

• Host access to commandBuffer must be externally synchronized

• Host access to the CommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties

'

See Also

CommandBuffer, Viewport

vkCmdSetScissor - Set the dynamic scissor rectangles on a command buffer

Description

The scissor rectangles taken from element i of pScissors replace the current state for the scissor index firstScissor + i, for i in [0, scissorCount).

This command sets the state for a given draw when the graphics pipeline is created with DYNAMIC_STATE_SCISSOR set in PipelineDynamicStateCreateInfo::pDynamicStates.

Valid Usage

• firstScissor must be less than PhysicalDeviceLimits::maxViewports

• The sum of firstScissor and scissorCount must be between 1 and PhysicalDeviceLimits::maxViewports, inclusive
• If the multiple viewports feature is not enabled, firstScissor must be 0
• If the multiple viewports feature is not enabled, scissorCount must be 1
• The x and y members of offset member of any element of pScissors must be greater than or equal to 0
• Evaluation of (offset.x + extent.width) must not cause a signed integer addition overflow for any element of pScissors
• Evaluation of (offset.y + extent.height) must not cause a signed integer addition overflow for any element of pScissors

Valid Usage (Implicit)

• commandBuffer must be a valid CommandBuffer handle

• pScissors must be a valid pointer to an array of scissorCount Rect2D structures
• commandBuffer must be in the recording state
• The CommandPool that commandBuffer was allocated from must support graphics operations
• scissorCount must be greater than 0

Host Synchronization

• Host access to commandBuffer must be externally synchronized

• Host access to the CommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties

'

See Also

CommandBuffer, Rect2D

vkCmdSetLineWidth - Set the dynamic line width state

Valid Usage

• If the wide lines feature is not enabled, lineWidth must be 1.0

Valid Usage (Implicit)

• commandBuffer must be a valid CommandBuffer handle

• commandBuffer must be in the recording state
• The CommandPool that commandBuffer was allocated from must support graphics operations

Host Synchronization

• Host access to commandBuffer must be externally synchronized

• Host access to the CommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties

'

See Also

CommandBuffer

vkCmdSetDepthBias - Set the depth bias dynamic state

Description

If depthBiasEnable is FALSE, no depth bias is applied and the fragment’s depth values are unchanged.

depthBiasSlopeFactor scales the maximum depth slope of the polygon, and depthBiasConstantFactor scales an implementation-dependent constant that relates to the usable resolution of the depth buffer. The resulting values are summed to produce the depth bias value which is then clamped to a minimum or maximum value specified by depthBiasClamp. depthBiasSlopeFactor, depthBiasConstantFactor, and depthBiasClamp can each be positive, negative, or zero.

The maximum depth slope m of a triangle is

\[m = \sqrt{ \left({{\partial z_f} \over {\partial x_f}}\right)^2 + \left({{\partial z_f} \over {\partial y_f}}\right)^2}\]

where (xf, yf, zf) is a point on the triangle. m may be approximated as

\[m = \max\left( \left| { {\partial z_f} \over {\partial x_f} } \right|, \left| { {\partial z_f} \over {\partial y_f} } \right| \right).\]

The minimum resolvable difference r is an implementation-dependent parameter that depends on the depth buffer representation. It is the smallest difference in framebuffer coordinate z values that is guaranteed to remain distinct throughout polygon rasterization and in the depth buffer. All pairs of fragments generated by the rasterization of two polygons with otherwise identical vertices, but zf values that differ by r, will have distinct depth values.

For fixed-point depth buffer representations, r is constant throughout the range of the entire depth buffer. For floating-point depth buffers, there is no single minimum resolvable difference. In this case, the minimum resolvable difference for a given polygon is dependent on the maximum exponent, e, in the range of z values spanned by the primitive. If n is the number of bits in the floating-point mantissa, the minimum resolvable difference, r, for the given primitive is defined as

• r = 2e-n

If a triangle is rasterized using the POLYGON_MODE_FILL_RECTANGLE_NV polygon mode, then this minimum resolvable difference may not be resolvable for samples outside of the triangle, where the depth is extrapolated.

If no depth buffer is present, r is undefined.

The bias value o for a polygon is

[begin{aligned} o &= mathrm{dbclamp}( m times mathtt{depthBiasSlopeFactor} + r times mathtt{depthBiasConstantFactor} ) -- text{where} &quad mathrm{dbclamp}(x) =

Command Buffer Levels | Render Pass Scope | Supported Queue Types | Pipeline Type | +============================================================================================================================+========================================================================================================================+=======================================================================================================================+=====================================================================================================================================+ | Primary | Both | Graphics | | | Secondary | | | | +----------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------+

See Also

CommandBuffer

vkCmdSetBlendConstants - Set the values of blend constants

Valid Usage (Implicit)

• commandBuffer must be a valid CommandBuffer handle

• commandBuffer must be in the recording state
• The CommandPool that commandBuffer was allocated from must support graphics operations

Host Synchronization

• Host access to commandBuffer must be externally synchronized

• Host access to the CommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties

'

See Also

CommandBuffer

vkCmdSetDepthBounds - Set the depth bounds test values for a command buffer

Description

This command sets the state for a given draw when the graphics pipeline is created with DYNAMIC_STATE_DEPTH_BOUNDS set in PipelineDynamicStateCreateInfo::pDynamicStates.

Valid Usage

• Unless the VK_EXT_depth_range_unrestricted extension is enabled minDepthBounds must be between 0.0 and 1.0, inclusive

• Unless the VK_EXT_depth_range_unrestricted extension is enabled maxDepthBounds must be between 0.0 and 1.0, inclusive

Valid Usage (Implicit)

• commandBuffer must be a valid CommandBuffer handle

• commandBuffer must be in the recording state
• The CommandPool that commandBuffer was allocated from must support graphics operations

Host Synchronization

• Host access to commandBuffer must be externally synchronized

• Host access to the CommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties

'

See Also

CommandBuffer

vkCmdSetStencilCompareMask - Set the stencil compare mask dynamic state

Description

This command sets the state for a given draw when the graphics pipeline is created with DYNAMIC_STATE_STENCIL_COMPARE_MASK set in PipelineDynamicStateCreateInfo::pDynamicStates.

Valid Usage (Implicit)

• commandBuffer must be a valid CommandBuffer handle

• faceMask must be a valid combination of StencilFaceFlagBits values
• faceMask must not be 0
• commandBuffer must be in the recording state
• The CommandPool that commandBuffer was allocated from must support graphics operations

Host Synchronization

• Host access to commandBuffer must be externally synchronized

• Host access to the CommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties

'

See Also

CommandBuffer, StencilFaceFlags

vkCmdSetStencilWriteMask - Set the stencil write mask dynamic state

Description

This command sets the state for a given draw when the graphics pipeline is created with DYNAMIC_STATE_STENCIL_WRITE_MASK set in PipelineDynamicStateCreateInfo::pDynamicStates.

Valid Usage (Implicit)

• commandBuffer must be a valid CommandBuffer handle

• faceMask must be a valid combination of StencilFaceFlagBits values
• faceMask must not be 0
• commandBuffer must be in the recording state
• The CommandPool that commandBuffer was allocated from must support graphics operations

Host Synchronization

• Host access to commandBuffer must be externally synchronized

• Host access to the CommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties

'

See Also

CommandBuffer, StencilFaceFlags

vkCmdSetStencilReference - Set the stencil reference dynamic state

Description

This command sets the state for a given draw when the graphics pipeline is created with DYNAMIC_STATE_STENCIL_REFERENCE set in PipelineDynamicStateCreateInfo::pDynamicStates.

Valid Usage (Implicit)

• commandBuffer must be a valid CommandBuffer handle

• faceMask must be a valid combination of StencilFaceFlagBits values
• faceMask must not be 0
• commandBuffer must be in the recording state
• The CommandPool that commandBuffer was allocated from must support graphics operations

Host Synchronization

• Host access to commandBuffer must be externally synchronized

• Host access to the CommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties

'

See Also

CommandBuffer, StencilFaceFlags

vkCmdBindDescriptorSets - Binds descriptor sets to a command buffer

Description

cmdBindDescriptorSets 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 cmdBindDescriptorSets may be consumed at the following times:

• For descriptor bindings created with the DESCRIPTOR_BINDING_UPDATE_AFTER_BIND_BIT bit 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 cmdBindDescriptorSets. Once all pending uses have completed, it is legal to update and reuse a descriptor set.

Valid Usage

• Each element of pDescriptorSets must have been allocated with a DescriptorSetLayout that matches (is the same as, or identically defined as) the DescriptorSetLayout at set n in layout, where n is the sum of firstSet and the index into pDescriptorSets

• dynamicOffsetCount must be equal to the total number of dynamic descriptors in pDescriptorSets
• The sum of firstSet and descriptorSetCount must be less than or equal to PipelineLayoutCreateInfo::setLayoutCount provided when layout was created
• pipelineBindPoint must be supported by the commandBuffer’s parent CommandPool’s queue family
• Each element of pDynamicOffsets which corresponds to a descriptor binding with type DESCRIPTOR_TYPE_UNIFORM_BUFFER_DYNAMIC must be a multiple of PhysicalDeviceLimits::minUniformBufferOffsetAlignment
• Each element of pDynamicOffsets which corresponds to a descriptor binding with type DESCRIPTOR_TYPE_STORAGE_BUFFER_DYNAMIC must be a multiple of PhysicalDeviceLimits::minStorageBufferOffsetAlignment
• For each dynamic uniform or storage buffer binding in pDescriptorSets, the sum of the effective offset, as defined above, and the range of the binding must be less than or equal to the size of the buffer

Valid Usage (Implicit)

• commandBuffer must be a valid CommandBuffer handle

• pipelineBindPoint must be a valid PipelineBindPoint value
• layout must be a valid PipelineLayout handle
• pDescriptorSets must be a valid pointer to an array of descriptorSetCount valid DescriptorSet handles
• If dynamicOffsetCount is not 0, pDynamicOffsets must be a valid pointer to an array of dynamicOffsetCount uint32_t values
• commandBuffer must be in the recording state
• The CommandPool that commandBuffer was allocated from must support graphics, or compute operations
• descriptorSetCount must be greater than 0
• Each of commandBuffer, layout, and the elements of pDescriptorSets must have been created, allocated, or retrieved from the same Device

Host Synchronization

• Host access to commandBuffer must be externally synchronized

• Host access to the CommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties

'

See Also

CommandBuffer, DescriptorSet, PipelineBindPoint, PipelineLayout

vkCmdBindIndexBuffer - Bind an index buffer to a command buffer

Valid Usage

• offset must be less than the size of buffer

• The sum of offset and the address of the range of DeviceMemory object that is backing buffer, must be a multiple of the type indicated by indexType
• buffer must have been created with the BUFFER_USAGE_INDEX_BUFFER_BIT flag
• If buffer is non-sparse then it must be bound completely and contiguously to a single DeviceMemory object
• indexType must not be INDEX_TYPE_NONE_KHR
• If indexType is INDEX_TYPE_UINT8_EXT, the indexTypeUint8 feature must be enabled

Valid Usage (Implicit)

• commandBuffer must be a valid CommandBuffer handle

• buffer must be a valid Buffer handle
• indexType must be a valid IndexType value
• commandBuffer must be in the recording state
• The CommandPool that commandBuffer was allocated from must support graphics operations
• Both of buffer, and commandBuffer must have been created, allocated, or retrieved from the same Device

Host Synchronization

• Host access to commandBuffer must be externally synchronized

• Host access to the CommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties

'

See Also

Buffer, CommandBuffer, DeviceSize, IndexType

vkCmdBindVertexBuffers - Bind vertex buffers to a command buffer

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. If the nullDescriptor feature is enabled, elements of pBuffers can be NULL_HANDLE, and can be used by the vertex shader. If a vertex input attribute is bound to a vertex input binding that is NULL_HANDLE, the values taken from memory are considered to be zero, and missing G, B, or A components are filled with (0,0,1).

Valid Usage

• firstBinding must be less than PhysicalDeviceLimits::maxVertexInputBindings

• The sum of firstBinding and bindingCount must be less than or equal to PhysicalDeviceLimits::maxVertexInputBindings
• All elements of pOffsets must be less than the size of the corresponding element in pBuffers
• All elements of pBuffers must have been created with the BUFFER_USAGE_VERTEX_BUFFER_BIT flag
• Each element of pBuffers that is non-sparse must be bound completely and contiguously to a single DeviceMemory object
• If the nullDescriptor feature is not enabled, all elements of pBuffers must not be NULL_HANDLE
• If an element of pBuffers is NULL_HANDLE, then the corresponding element of pOffsets must be zero

Valid Usage (Implicit)

• commandBuffer must be a valid CommandBuffer handle

• pBuffers must be a valid pointer to an array of bindingCount valid or NULL_HANDLE Buffer handles
• pOffsets must be a valid pointer to an array of bindingCount DeviceSize values
• commandBuffer must be in the recording state
• The CommandPool that commandBuffer was allocated from must support graphics operations
• bindingCount must be greater than 0
• Both of commandBuffer, and the elements of pBuffers that are valid handles of non-ignored parameters must have been created, allocated, or retrieved from the same Device

Host Synchronization

• Host access to commandBuffer must be externally synchronized

• Host access to the CommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties

'

See Also

Buffer, CommandBuffer, DeviceSize

vkCmdDraw - Draw primitives

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.

Valid Usage

• If a ImageView is sampled with FILTER_LINEAR as a result of this command, then the image view’s format features must contain FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_LINEAR_BIT

• If a ImageView is accessed using atomic operations as a result of this command, then the image view’s format features must contain FORMAT_FEATURE_STORAGE_IMAGE_ATOMIC_BIT
• If a ImageView is sampled with FILTER_CUBIC_EXT as a result of this command, then the image view’s format features must contain FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_CUBIC_BIT_EXT
• Any ImageView being sampled with FILTER_CUBIC_EXT as a result of this command must have a ImageViewType and format that supports cubic filtering, as specified by FilterCubicImageViewImageFormatPropertiesEXT::filterCubic returned by getPhysicalDeviceImageFormatProperties2
• Any ImageView being sampled with FILTER_CUBIC_EXT with a reduction mode of either SAMPLER_REDUCTION_MODE_MIN or SAMPLER_REDUCTION_MODE_MAX as a result of this command must have a ImageViewType and format that supports cubic filtering together with minmax filtering, as specified by FilterCubicImageViewImageFormatPropertiesEXT::filterCubicMinmax returned by getPhysicalDeviceImageFormatProperties2
• Any Image created with a ImageCreateInfo::flags containing IMAGE_CREATE_CORNER_SAMPLED_BIT_NV sampled as a result of this command must only be sampled using a SamplerAddressMode of SAMPLER_ADDRESS_MODE_CLAMP_TO_EDGE
• For each set n that is statically used by the Pipeline bound to the pipeline bind point used by this command, a descriptor set must have been bound to n at the same pipeline bind point, with a PipelineLayout that is compatible for set n, with the PipelineLayout used to create the current Pipeline, as described in ???
• For each push constant that is statically used by the Pipeline bound to the pipeline bind point used by this command, a push constant value must have been set for the same pipeline bind point, with a PipelineLayout that is compatible for push constants, with the PipelineLayout used to create the current Pipeline, as described in ???
• Descriptors in each bound descriptor set, specified via cmdBindDescriptorSets, must be valid if they are statically used by the Pipeline bound to the pipeline bind point used by this command
• A valid pipeline must be bound to the pipeline bind point used by this command
• If the Pipeline object bound to the pipeline bind point used by this command requires any dynamic state, that state must have been set for commandBuffer, and done so after any previously bound pipeline with the corresponding state not specified as dynamic
• There must not have been any calls to dynamic state setting commands for any state not specified as dynamic in the Pipeline object bound to the pipeline bind point used by this command, since that pipeline was bound
• If the Pipeline object bound to the pipeline bind point used by this command accesses a Sampler object that uses unnormalized coordinates, that sampler must not be used to sample from any Image with a ImageView of the type IMAGE_VIEW_TYPE_3D, IMAGE_VIEW_TYPE_CUBE, IMAGE_VIEW_TYPE_1D_ARRAY, IMAGE_VIEW_TYPE_2D_ARRAY or IMAGE_VIEW_TYPE_CUBE_ARRAY, in any shader stage
• If the Pipeline object bound to the pipeline bind point used by this command accesses a Sampler object that uses unnormalized coordinates, that sampler must not be used with any of the SPIR-V OpImageSample* or OpImageSparseSample* instructions with ImplicitLod, Dref or Proj in their name, in any shader stage
• If the Pipeline object bound to the pipeline bind point used by this command accesses a Sampler object that uses unnormalized coordinates, that sampler must not be used with any of the SPIR-V OpImageSample* or OpImageSparseSample* instructions that includes a LOD bias or any offset values, in any shader stage
• If the robust buffer access feature is not enabled, and if the Pipeline object bound to the pipeline bind point used by this command accesses a uniform buffer, it must not access values outside of the range of the buffer as specified in the descriptor set bound to the same pipeline bind point
• If the robust buffer access feature is not enabled, and if the Pipeline object bound to the pipeline bind point used by this command accesses a storage buffer, it must not access values outside of the range of the buffer as specified in the descriptor set bound to the same pipeline bind point
• If commandBuffer is an unprotected command buffer, any resource accessed by the Pipeline object bound to the pipeline bind point used by this command must not be a protected resource
• If a ImageView is accessed using OpImageWrite as a result of this command, then the Type of the Texel operand of that instruction must have at least as many components as the image view’s format.
• The current render pass must be compatible with the renderPass member of the GraphicsPipelineCreateInfo structure specified when creating the Pipeline bound to PIPELINE_BIND_POINT_GRAPHICS
• The subpass index of the current render pass must be equal to the subpass member of the GraphicsPipelineCreateInfo structure specified when creating the Pipeline bound to PIPELINE_BIND_POINT_GRAPHICS
• Every input attachment used by the current subpass must be bound to the pipeline via a descriptor set
• Image subresources used as attachments in the current render pass must not be accessed in any way other than as an attachment by this command
• If the draw is recorded in a render pass instance with multiview enabled, the maximum instance index must be less than or equal to PhysicalDeviceMultiviewProperties::maxMultiviewInstanceIndex
• If the bound graphics pipeline was created with PipelineSampleLocationsStateCreateInfoEXT::sampleLocationsEnable set to TRUE and the current subpass has a depth/stencil attachment, then that attachment must have been created with the IMAGE_CREATE_SAMPLE_LOCATIONS_COMPATIBLE_DEPTH_BIT_EXT bit set
• If the bound graphics pipeline state was created with the DYNAMIC_STATE_VIEWPORT_WITH_COUNT_EXT dynamic state enabled, but not the DYNAMIC_STATE_SCISSOR_WITH_COUNT_EXT dynamic state enabled, then then cmdSetViewportWithCountEXT must have been called in the current command buffer prior to this draw command, and the viewportCount parameter of cmdSetViewportWithCountEXT must match the PipelineViewportStateCreateInfo::scissorCount of the pipeline
• If the bound graphics pipeline state was created with the DYNAMIC_STATE_SCISSOR_WITH_COUNT_EXT dynamic state enabled, but not the DYNAMIC_STATE_VIEWPORT_WITH_COUNT_EXT dynamic state enabled, then then cmdSetScissorWithCountEXT must have been called in the current command buffer prior to this draw command, and the scissorCount parameter of cmdSetScissorWithCountEXT must match the PipelineViewportStateCreateInfo::viewportCount of the pipeline
• If the bound graphics pipeline state was created with both the DYNAMIC_STATE_SCISSOR_WITH_COUNT_EXT and DYNAMIC_STATE_VIEWPORT_WITH_COUNT_EXT dynamic states enabled then both cmdSetViewportWithCountEXT and cmdSetScissorWithCountEXT must have been called in the current command buffer prior to this draw command, and the viewportCount parameter of cmdSetViewportWithCountEXT must match the scissorCount parameter of cmdSetScissorWithCountEXT
• If the bound graphics pipeline state was created with the DYNAMIC_STATE_PRIMITIVE_TOPOLOGY_EXT dynamic state enabled then cmdSetPrimitiveTopologyEXT must have been called in the current command buffer prior to this draw command, and the primitiveTopology parameter of cmdSetPrimitiveTopologyEXT must be of the same topology class as the pipeline PipelineInputAssemblyStateCreateInfo::topology state
• If commandBuffer is a protected command buffer, any resource written to by the Pipeline object bound to the pipeline bind point used by this command must not be an unprotected resource
• If commandBuffer is a protected command buffer, pipeline stages other than the framebuffer-space and compute stages in the Pipeline object bound to the pipeline bind point must not write to any resource
• All vertex input bindings accessed via vertex input variables declared in the vertex shader entry point’s interface must have either valid or NULL_HANDLE buffers bound
• If the nullDescriptor feature is not enabled, all vertex input bindings accessed via vertex input variables declared in the vertex shader entry point’s interface must not be NULL_HANDLE
• For a given vertex buffer binding, any attribute data fetched must be entirely contained within the corresponding vertex buffer binding, as described in ???

Valid Usage (Implicit)

• commandBuffer must be a valid CommandBuffer handle

• commandBuffer must be in the recording state
• The CommandPool that commandBuffer was allocated from must support graphics operations
• This command must only be called inside of a render pass instance

Host Synchronization

• Host access to commandBuffer must be externally synchronized

• Host access to the CommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties

'

See Also

CommandBuffer

vkCmdDrawIndexed - Issue an indexed draw into a command buffer

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 cmdBindIndexBuffer::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 cmdBindIndexBuffer 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 INDEX_TYPE_UINT8_EXT or 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.

Valid Usage

• If a ImageView is sampled with FILTER_LINEAR as a result of this command, then the image view’s format features must contain FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_LINEAR_BIT

• If a ImageView is accessed using atomic operations as a result of this command, then the image view’s format features must contain FORMAT_FEATURE_STORAGE_IMAGE_ATOMIC_BIT
• If a ImageView is sampled with FILTER_CUBIC_EXT as a result of this command, then the image view’s format features must contain FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_CUBIC_BIT_EXT
• Any ImageView being sampled with FILTER_CUBIC_EXT as a result of this command must have a ImageViewType and format that supports cubic filtering, as specified by FilterCubicImageViewImageFormatPropertiesEXT::filterCubic returned by getPhysicalDeviceImageFormatProperties2
• Any ImageView being sampled with FILTER_CUBIC_EXT with a reduction mode of either SAMPLER_REDUCTION_MODE_MIN or SAMPLER_REDUCTION_MODE_MAX as a result of this command must have a ImageViewType and format that supports cubic filtering together with minmax filtering, as specified by FilterCubicImageViewImageFormatPropertiesEXT::filterCubicMinmax returned by getPhysicalDeviceImageFormatProperties2
• Any Image created with a ImageCreateInfo::flags containing IMAGE_CREATE_CORNER_SAMPLED_BIT_NV sampled as a result of this command must only be sampled using a SamplerAddressMode of SAMPLER_ADDRESS_MODE_CLAMP_TO_EDGE
• For each set n that is statically used by the Pipeline bound to the pipeline bind point used by this command, a descriptor set must have been bound to n at the same pipeline bind point, with a PipelineLayout that is compatible for set n, with the PipelineLayout used to create the current Pipeline, as described in ???
• For each push constant that is statically used by the Pipeline bound to the pipeline bind point used by this command, a push constant value must have been set for the same pipeline bind point, with a PipelineLayout that is compatible for push constants, with the PipelineLayout used to create the current Pipeline, as described in ???
• Descriptors in each bound descriptor set, specified via cmdBindDescriptorSets, must be valid if they are statically used by the Pipeline bound to the pipeline bind point used by this command
• A valid pipeline must be bound to the pipeline bind point used by this command
• If the Pipeline object bound to the pipeline bind point used by this command requires any dynamic state, that state must have been set for commandBuffer, and done so after any previously bound pipeline with the corresponding state not specified as dynamic
• There must not have been any calls to dynamic state setting commands for any state not specified as dynamic in the Pipeline object bound to the pipeline bind point used by this command, since that pipeline was bound
• If the Pipeline object bound to the pipeline bind point used by this command accesses a Sampler object that uses unnormalized coordinates, that sampler must not be used to sample from any Image with a ImageView of the type IMAGE_VIEW_TYPE_3D, IMAGE_VIEW_TYPE_CUBE, IMAGE_VIEW_TYPE_1D_ARRAY, IMAGE_VIEW_TYPE_2D_ARRAY or IMAGE_VIEW_TYPE_CUBE_ARRAY, in any shader stage
• If the Pipeline object bound to the pipeline bind point used by this command accesses a Sampler object that uses unnormalized coordinates, that sampler must not be used with any of the SPIR-V OpImageSample* or OpImageSparseSample* instructions with ImplicitLod, Dref or Proj in their name, in any shader stage
• If the Pipeline object bound to the pipeline bind point used by this command accesses a Sampler object that uses unnormalized coordinates, that sampler must not be used with any of the SPIR-V OpImageSample* or OpImageSparseSample* instructions that includes a LOD bias or any offset values, in any shader stage
• If the robust buffer access feature is not enabled, and if the Pipeline object bound to the pipeline bind point used by this command accesses a uniform buffer, it must not access values outside of the range of the buffer as specified in the descriptor set bound to the same pipeline bind point
• If the robust buffer access feature is not enabled, and if the Pipeline object bound to the pipeline bind point used by this command accesses a storage buffer, it must not access values outside of the range of the buffer as specified in the descriptor set bound to the same pipeline bind point
• If commandBuffer is an unprotected command buffer, any resource accessed by the Pipeline object bound to the pipeline bind point used by this command must not be a protected resource
• If a ImageView is accessed using OpImageWrite as a result of this command, then the Type of the Texel operand of that instruction must have at least as many components as the image view’s format.
• The current render pass must be compatible with the renderPass member of the GraphicsPipelineCreateInfo structure specified when creating the Pipeline bound to PIPELINE_BIND_POINT_GRAPHICS
• The subpass index of the current render pass must be equal to the subpass member of the GraphicsPipelineCreateInfo structure specified when creating the Pipeline bound to PIPELINE_BIND_POINT_GRAPHICS
• Every input attachment used by the current subpass must be bound to the pipeline via a descriptor set
• Image subresources used as attachments in the current render pass must not be accessed in any way other than as an attachment by this command
• If the draw is recorded in a render pass instance with multiview enabled, the maximum instance index must be less than or equal to PhysicalDeviceMultiviewProperties::maxMultiviewInstanceIndex
• If the bound graphics pipeline was created with PipelineSampleLocationsStateCreateInfoEXT::sampleLocationsEnable set to TRUE and the current subpass has a depth/stencil attachment, then that attachment must have been created with the IMAGE_CREATE_SAMPLE_LOCATIONS_COMPATIBLE_DEPTH_BIT_EXT bit set
• If the bound graphics pipeline state was created with the DYNAMIC_STATE_VIEWPORT_WITH_COUNT_EXT dynamic state enabled, but not the DYNAMIC_STATE_SCISSOR_WITH_COUNT_EXT dynamic state enabled, then then cmdSetViewportWithCountEXT must have been called in the current command buffer prior to this draw command, and the viewportCount parameter of cmdSetViewportWithCountEXT must match the PipelineViewportStateCreateInfo::scissorCount of the pipeline
• If the bound graphics pipeline state was created with the DYNAMIC_STATE_SCISSOR_WITH_COUNT_EXT dynamic state enabled, but not the DYNAMIC_STATE_VIEWPORT_WITH_COUNT_EXT dynamic state enabled, then then cmdSetScissorWithCountEXT must have been called in the current command buffer prior to this draw command, and the scissorCount parameter of cmdSetScissorWithCountEXT must match the PipelineViewportStateCreateInfo::viewportCount of the pipeline
• If the bound graphics pipeline state was created with both the DYNAMIC_STATE_SCISSOR_WITH_COUNT_EXT and DYNAMIC_STATE_VIEWPORT_WITH_COUNT_EXT dynamic states enabled then both cmdSetViewportWithCountEXT and cmdSetScissorWithCountEXT must have been called in the current command buffer prior to this draw command, and the viewportCount parameter of cmdSetViewportWithCountEXT must match the scissorCount parameter of cmdSetScissorWithCountEXT
• If the bound graphics pipeline state was created with the DYNAMIC_STATE_PRIMITIVE_TOPOLOGY_EXT dynamic state enabled then cmdSetPrimitiveTopologyEXT must have been called in the current command buffer prior to this draw command, and the primitiveTopology parameter of cmdSetPrimitiveTopologyEXT must be of the same topology class as the pipeline PipelineInputAssemblyStateCreateInfo::topology state
• If commandBuffer is a protected command buffer, any resource written to by the Pipeline object bound to the pipeline bind point used by this command must not be an unprotected resource
• If commandBuffer is a protected command buffer, pipeline stages other than the framebuffer-space and compute stages in the Pipeline object bound to the pipeline bind point must not write to any resource
• All vertex input bindings accessed via vertex input variables declared in the vertex shader entry point’s interface must have either valid or NULL_HANDLE buffers bound
• If the nullDescriptor feature is not enabled, all vertex input bindings accessed via vertex input variables declared in the vertex shader entry point’s interface must not be NULL_HANDLE
• For a given vertex buffer binding, any attribute data fetched must be entirely contained within the corresponding vertex buffer binding, as described in ???
• (indexSize × (firstIndex + indexCount) + offset) must be less than or equal to the size of the bound index buffer, with indexSize being based on the type specified by indexType, where the index buffer, indexType, and offset are specified via cmdBindIndexBuffer

Valid Usage (Implicit)

• commandBuffer must be a valid CommandBuffer handle

• commandBuffer must be in the recording state
• The CommandPool that commandBuffer was allocated from must support graphics operations
• This command must only be called inside of a render pass instance

Host Synchronization

• Host access to commandBuffer must be externally synchronized

• Host access to the CommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties

'

See Also

CommandBuffer

vkCmdDrawIndirect - Issue an indirect draw into a command buffer

Description

cmdDrawIndirect behaves similarly to cmdDraw 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 DrawIndirectCommand structures. If drawCount is less than or equal to one, stride is ignored.

Valid Usage

• If a ImageView is sampled with FILTER_LINEAR as a result of this command, then the image view’s format features must contain FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_LINEAR_BIT

• If a ImageView is accessed using atomic operations as a result of this command, then the image view’s format features must contain FORMAT_FEATURE_STORAGE_IMAGE_ATOMIC_BIT
• If a ImageView is sampled with FILTER_CUBIC_EXT as a result of this command, then the image view’s format features must contain FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_CUBIC_BIT_EXT
• Any ImageView being sampled with FILTER_CUBIC_EXT as a result of this command must have a ImageViewType and format that supports cubic filtering, as specified by FilterCubicImageViewImageFormatPropertiesEXT::filterCubic returned by getPhysicalDeviceImageFormatProperties2
• Any ImageView being sampled with FILTER_CUBIC_EXT with a reduction mode of either SAMPLER_REDUCTION_MODE_MIN or SAMPLER_REDUCTION_MODE_MAX as a result of this command must have a ImageViewType and format that supports cubic filtering together with minmax filtering, as specified by FilterCubicImageViewImageFormatPropertiesEXT::filterCubicMinmax returned by getPhysicalDeviceImageFormatProperties2
• Any Image created with a ImageCreateInfo::flags containing IMAGE_CREATE_CORNER_SAMPLED_BIT_NV sampled as a result of this command must only be sampled using a SamplerAddressMode of SAMPLER_ADDRESS_MODE_CLAMP_TO_EDGE
• For each set n that is statically used by the Pipeline bound to the pipeline bind point used by this command, a descriptor set must have been bound to n at the same pipeline bind point, with a PipelineLayout that is compatible for set n, with the PipelineLayout used to create the current Pipeline, as described in ???
• For each push constant that is statically used by the Pipeline bound to the pipeline bind point used by this command, a push constant value must have been set for the same pipeline bind point, with a PipelineLayout that is compatible for push constants, with the PipelineLayout used to create the current Pipeline, as described in ???
• Descriptors in each bound descriptor set, specified via cmdBindDescriptorSets, must be valid if they are statically used by the Pipeline bound to the pipeline bind point used by this command
• A valid pipeline must be bound to the pipeline bind point used by this command
• If the Pipeline object bound to the pipeline bind point used by this command requires any dynamic state, that state must have been set for commandBuffer, and done so after any previously bound pipeline with the corresponding state not specified as dynamic
• There must not have been any calls to dynamic state setting commands for any state not specified as dynamic in the Pipeline object bound to the pipeline bind point used by this command, since that pipeline was bound
• If the Pipeline object bound to the pipeline bind point used by this command accesses a Sampler object that uses unnormalized coordinates, that sampler must not be used to sample from any Image with a ImageView of the type IMAGE_VIEW_TYPE_3D, IMAGE_VIEW_TYPE_CUBE, IMAGE_VIEW_TYPE_1D_ARRAY, IMAGE_VIEW_TYPE_2D_ARRAY or IMAGE_VIEW_TYPE_CUBE_ARRAY, in any shader stage
• If the Pipeline object bound to the pipeline bind point used by this command accesses a Sampler object that uses unnormalized coordinates, that sampler must not be used with any of the SPIR-V OpImageSample* or OpImageSparseSample* instructions with ImplicitLod, Dref or Proj in their name, in any shader stage
• If the Pipeline object bound to the pipeline bind point used by this command accesses a Sampler object that uses unnormalized coordinates, that sampler must not be used with any of the SPIR-V OpImageSample* or OpImageSparseSample* instructions that includes a LOD bias or any offset values, in any shader stage
• If the robust buffer access feature is not enabled, and if the Pipeline object bound to the pipeline bind point used by this command accesses a uniform buffer, it must not access values outside of the range of the buffer as specified in the descriptor set bound to the same pipeline bind point
• If the robust buffer access feature is not enabled, and if the Pipeline object bound to the pipeline bind point used by this command accesses a storage buffer, it must not access values outside of the range of the buffer as specified in the descriptor set bound to the same pipeline bind point
• If commandBuffer is an unprotected command buffer, any resource accessed by the Pipeline object bound to the pipeline bind point used by this command must not be a protected resource
• If a ImageView is accessed using OpImageWrite as a result of this command, then the Type of the Texel operand of that instruction must have at least as many components as the image view’s format.
• The current render pass must be compatible with the renderPass member of the GraphicsPipelineCreateInfo structure specified when creating the Pipeline bound to PIPELINE_BIND_POINT_GRAPHICS
• The subpass index of the current render pass must be equal to the subpass member of the GraphicsPipelineCreateInfo structure specified when creating the Pipeline bound to PIPELINE_BIND_POINT_GRAPHICS
• Every input attachment used by the current subpass must be bound to the pipeline via a descriptor set
• Image subresources used as attachments in the current render pass must not be accessed in any way other than as an attachment by this command
• If the draw is recorded in a render pass instance with multiview enabled, the maximum instance index must be less than or equal to PhysicalDeviceMultiviewProperties::maxMultiviewInstanceIndex
• If the bound graphics pipeline was created with PipelineSampleLocationsStateCreateInfoEXT::sampleLocationsEnable set to TRUE and the current subpass has a depth/stencil attachment, then that attachment must have been created with the IMAGE_CREATE_SAMPLE_LOCATIONS_COMPATIBLE_DEPTH_BIT_EXT bit set
• If the bound graphics pipeline state was created with the DYNAMIC_STATE_VIEWPORT_WITH_COUNT_EXT dynamic state enabled, but not the DYNAMIC_STATE_SCISSOR_WITH_COUNT_EXT dynamic state enabled, then then cmdSetViewportWithCountEXT must have been called in the current command buffer prior to this draw command, and the viewportCount parameter of cmdSetViewportWithCountEXT must match the PipelineViewportStateCreateInfo::scissorCount of the pipeline
• If the bound graphics pipeline state was created with the DYNAMIC_STATE_SCISSOR_WITH_COUNT_EXT dynamic state enabled, but not the DYNAMIC_STATE_VIEWPORT_WITH_COUNT_EXT dynamic state enabled, then then cmdSetScissorWithCountEXT must have been called in the current command buffer prior to this draw command, and the scissorCount parameter of cmdSetScissorWithCountEXT must match the PipelineViewportStateCreateInfo::viewportCount of the pipeline
• If the bound graphics pipeline state was created with both the DYNAMIC_STATE_SCISSOR_WITH_COUNT_EXT and DYNAMIC_STATE_VIEWPORT_WITH_COUNT_EXT dynamic states enabled then both cmdSetViewportWithCountEXT and cmdSetScissorWithCountEXT must have been called in the current command buffer prior to this draw command, and the viewportCount parameter of cmdSetViewportWithCountEXT must match the scissorCount parameter of cmdSetScissorWithCountEXT
• If the bound graphics pipeline state was created with the DYNAMIC_STATE_PRIMITIVE_TOPOLOGY_EXT dynamic state enabled then cmdSetPrimitiveTopologyEXT must have been called in the current command buffer prior to this draw command, and the primitiveTopology parameter of cmdSetPrimitiveTopologyEXT must be of the same topology class as the pipeline PipelineInputAssemblyStateCreateInfo::topology state
• All vertex input bindings accessed via vertex input variables declared in the vertex shader entry point’s interface must have either valid or NULL_HANDLE buffers bound
• If the nullDescriptor feature is not enabled, all vertex input bindings accessed via vertex input variables declared in the vertex shader entry point’s interface must not be NULL_HANDLE
• For a given vertex buffer binding, any attribute data fetched must be entirely contained within the corresponding vertex buffer binding, as described in ???
• If buffer is non-sparse then it must be bound completely and contiguously to a single DeviceMemory object
• buffer must have been created with the BUFFER_USAGE_INDIRECT_BUFFER_BIT bit set
• offset must be a multiple of 4
• commandBuffer must not be a protected command buffer
• If the multi-draw indirect feature is not enabled, drawCount must be 0 or 1
• drawCount must be less than or equal to PhysicalDeviceLimits::maxDrawIndirectCount
• If the drawIndirectFirstInstance feature is not enabled, all the firstInstance members of the DrawIndirectCommand structures accessed by this command must be 0
• If drawCount is greater than 1, stride must be a multiple of 4 and must be greater than or equal to sizeof(DrawIndirectCommand)
• If drawCount is equal to 1, (offset + sizeof(DrawIndirectCommand)) must be less than or equal to the size of buffer
• If drawCount is greater than 1, (stride × (drawCount - 1) + offset + sizeof(DrawIndirectCommand)) must be less than or equal to the size of buffer

Valid Usage (Implicit)

• commandBuffer must be a valid CommandBuffer handle

• buffer must be a valid Buffer handle
• commandBuffer must be in the recording state
• The CommandPool that commandBuffer was allocated from must support graphics operations
• This command must only be called inside of a render pass instance
• Both of buffer, and commandBuffer must have been created, allocated, or retrieved from the same Device

Host Synchronization

• Host access to commandBuffer must be externally synchronized

• Host access to the CommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties

'

See Also

Buffer, CommandBuffer, DeviceSize

vkCmdDrawIndexedIndirect - Perform an indexed indirect draw

Description

cmdDrawIndexedIndirect behaves similarly to cmdDrawIndexed 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 DrawIndexedIndirectCommand structures. If drawCount is less than or equal to one, stride is ignored.

Valid Usage

• If a ImageView is sampled with FILTER_LINEAR as a result of this command, then the image view’s format features must contain FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_LINEAR_BIT

• If a ImageView is accessed using atomic operations as a result of this command, then the image view’s format features must contain FORMAT_FEATURE_STORAGE_IMAGE_ATOMIC_BIT
• If a ImageView is sampled with FILTER_CUBIC_EXT as a result of this command, then the image view’s format features must contain FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_CUBIC_BIT_EXT
• Any ImageView being sampled with FILTER_CUBIC_EXT as a result of this command must have a ImageViewType and format that supports cubic filtering, as specified by FilterCubicImageViewImageFormatPropertiesEXT::filterCubic returned by getPhysicalDeviceImageFormatProperties2
• Any ImageView being sampled with FILTER_CUBIC_EXT with a reduction mode of either SAMPLER_REDUCTION_MODE_MIN or SAMPLER_REDUCTION_MODE_MAX as a result of this command must have a ImageViewType and format that supports cubic filtering together with minmax filtering, as specified by FilterCubicImageViewImageFormatPropertiesEXT::filterCubicMinmax returned by getPhysicalDeviceImageFormatProperties2
• Any Image created with a ImageCreateInfo::flags containing IMAGE_CREATE_CORNER_SAMPLED_BIT_NV sampled as a result of this command must only be sampled using a SamplerAddressMode of SAMPLER_ADDRESS_MODE_CLAMP_TO_EDGE
• For each set n that is statically used by the Pipeline bound to the pipeline bind point used by this command, a descriptor set must have been bound to n at the same pipeline bind point, with a PipelineLayout that is compatible for set n, with the PipelineLayout used to create the current Pipeline, as described in ???
• For each push constant that is statically used by the Pipeline bound to the pipeline bind point used by this command, a push constant value must have been set for the same pipeline bind point, with a PipelineLayout that is compatible for push constants, with the PipelineLayout used to create the current Pipeline, as described in ???
• Descriptors in each bound descriptor set, specified via cmdBindDescriptorSets, must be valid if they are statically used by the Pipeline bound to the pipeline bind point used by this command
• A valid pipeline must be bound to the pipeline bind point used by this command
• If the Pipeline object bound to the pipeline bind point used by this command requires any dynamic state, that state must have been set for commandBuffer, and done so after any previously bound pipeline with the corresponding state not specified as dynamic
• There must not have been any calls to dynamic state setting commands for any state not specified as dynamic in the Pipeline object bound to the pipeline bind point used by this command, since that pipeline was bound
• If the Pipeline object bound to the pipeline bind point used by this command accesses a Sampler object that uses unnormalized coordinates, that sampler must not be used to sample from any Image with a ImageView of the type IMAGE_VIEW_TYPE_3D, IMAGE_VIEW_TYPE_CUBE, IMAGE_VIEW_TYPE_1D_ARRAY, IMAGE_VIEW_TYPE_2D_ARRAY or IMAGE_VIEW_TYPE_CUBE_ARRAY, in any shader stage
• If the Pipeline object bound to the pipeline bind point used by this command accesses a Sampler object that uses unnormalized coordinates, that sampler must not be used with any of the SPIR-V OpImageSample* or OpImageSparseSample* instructions with ImplicitLod, Dref or Proj in their name, in any shader stage
• If the Pipeline object bound to the pipeline bind point used by this command accesses a Sampler object that uses unnormalized coordinates, that sampler must not be used with any of the SPIR-V OpImageSample* or OpImageSparseSample* instructions that includes a LOD bias or any offset values, in any shader stage
• If the robust buffer access feature is not enabled, and if the Pipeline object bound to the pipeline bind point used by this command accesses a uniform buffer, it must not access values outside of the range of the buffer as specified in the descriptor set bound to the same pipeline bind point
• If the robust buffer access feature is not enabled, and if the Pipeline object bound to the pipeline bind point used by this command accesses a storage buffer, it must not access values outside of the range of the buffer as specified in the descriptor set bound to the same pipeline bind point
• If commandBuffer is an unprotected command buffer, any resource accessed by the Pipeline object bound to the pipeline bind point used by this command must not be a protected resource
• If a ImageView is accessed using OpImageWrite as a result of this command, then the Type of the Texel operand of that instruction must have at least as many components as the image view’s format.
• The current render pass must be compatible with the renderPass member of the GraphicsPipelineCreateInfo structure specified when creating the Pipeline bound to PIPELINE_BIND_POINT_GRAPHICS
• The subpass index of the current render pass must be equal to the subpass member of the GraphicsPipelineCreateInfo structure specified when creating the Pipeline bound to PIPELINE_BIND_POINT_GRAPHICS
• Every input attachment used by the current subpass must be bound to the pipeline via a descriptor set
• Image subresources used as attachments in the current render pass must not be accessed in any way other than as an attachment by this command
• If the draw is recorded in a render pass instance with multiview enabled, the maximum instance index must be less than or equal to PhysicalDeviceMultiviewProperties::maxMultiviewInstanceIndex
• If the bound graphics pipeline was created with PipelineSampleLocationsStateCreateInfoEXT::sampleLocationsEnable set to TRUE and the current subpass has a depth/stencil attachment, then that attachment must have been created with the IMAGE_CREATE_SAMPLE_LOCATIONS_COMPATIBLE_DEPTH_BIT_EXT bit set
• If the bound graphics pipeline state was created with the DYNAMIC_STATE_VIEWPORT_WITH_COUNT_EXT dynamic state enabled, but not the DYNAMIC_STATE_SCISSOR_WITH_COUNT_EXT dynamic state enabled, then then cmdSetViewportWithCountEXT must have been called in the current command buffer prior to this draw command, and the viewportCount parameter of cmdSetViewportWithCountEXT must match the PipelineViewportStateCreateInfo::scissorCount of the pipeline
• If the bound graphics pipeline state was created with the DYNAMIC_STATE_SCISSOR_WITH_COUNT_EXT dynamic state enabled, but not the DYNAMIC_STATE_VIEWPORT_WITH_COUNT_EXT dynamic state enabled, then then cmdSetScissorWithCountEXT must have been called in the current command buffer prior to this draw command, and the scissorCount parameter of cmdSetScissorWithCountEXT must match the PipelineViewportStateCreateInfo::viewportCount of the pipeline
• If the bound graphics pipeline state was created with both the DYNAMIC_STATE_SCISSOR_WITH_COUNT_EXT and DYNAMIC_STATE_VIEWPORT_WITH_COUNT_EXT dynamic states enabled then both cmdSetViewportWithCountEXT and cmdSetScissorWithCountEXT must have been called in the current command buffer prior to this draw command, and the viewportCount parameter of cmdSetViewportWithCountEXT must match the scissorCount parameter of cmdSetScissorWithCountEXT
• If the bound graphics pipeline state was created with the DYNAMIC_STATE_PRIMITIVE_TOPOLOGY_EXT dynamic state enabled then cmdSetPrimitiveTopologyEXT must have been called in the current command buffer prior to this draw command, and the primitiveTopology parameter of cmdSetPrimitiveTopologyEXT must be of the same topology class as the pipeline PipelineInputAssemblyStateCreateInfo::topology state
• All vertex input bindings accessed via vertex input variables declared in the vertex shader entry point’s interface must have either valid or NULL_HANDLE buffers bound
• If the nullDescriptor feature is not enabled, all vertex input bindings accessed via vertex input variables declared in the vertex shader entry point’s interface must not be NULL_HANDLE
• For a given vertex buffer binding, any attribute data fetched must be entirely contained within the corresponding vertex buffer binding, as described in ???
• If buffer is non-sparse then it must be bound completely and contiguously to a single DeviceMemory object
• buffer must have been created with the BUFFER_USAGE_INDIRECT_BUFFER_BIT bit set
• offset must be a multiple of 4
• commandBuffer must not be a protected command buffer
• If the multi-draw indirect feature is not enabled, drawCount must be 0 or 1
• drawCount must be less than or equal to PhysicalDeviceLimits::maxDrawIndirectCount
• If drawCount is greater than 1, stride must be a multiple of 4 and must be greater than or equal to sizeof(DrawIndexedIndirectCommand)
• If the drawIndirectFirstInstance feature is not enabled, all the firstInstance members of the DrawIndexedIndirectCommand structures accessed by this command must be 0
• If drawCount is equal to 1, (offset + sizeof(DrawIndexedIndirectCommand)) must be less than or equal to the size of buffer
• If drawCount is greater than 1, (stride × (drawCount - 1) + offset + sizeof(DrawIndexedIndirectCommand)) must be less than or equal to the size of buffer
• If drawIndirectCount is not enabled this function must not be used

Valid Usage (Implicit)

• commandBuffer must be a valid CommandBuffer handle

• buffer must be a valid Buffer handle
• commandBuffer must be in the recording state
• The CommandPool that commandBuffer was allocated from must support graphics operations
• This command must only be called inside of a render pass instance
• Both of buffer, and commandBuffer must have been created, allocated, or retrieved from the same Device

Host Synchronization

• Host access to commandBuffer must be externally synchronized

• Host access to the CommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties

'

See Also

Buffer, CommandBuffer, DeviceSize

vkCmdDispatch - Dispatch compute work items

Description

When the command is executed, a global workgroup consisting of groupCountX × groupCountY × groupCountZ local workgroups is assembled.

Valid Usage

• If a ImageView is sampled with FILTER_LINEAR as a result of this command, then the image view’s format features must contain FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_LINEAR_BIT

• If a ImageView is accessed using atomic operations as a result of this command, then the image view’s format features must contain FORMAT_FEATURE_STORAGE_IMAGE_ATOMIC_BIT
• If a ImageView is sampled with FILTER_CUBIC_EXT as a result of this command, then the image view’s format features must contain FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_CUBIC_BIT_EXT
• Any ImageView being sampled with FILTER_CUBIC_EXT as a result of this command must have a ImageViewType and format that supports cubic filtering, as specified by FilterCubicImageViewImageFormatPropertiesEXT::filterCubic returned by getPhysicalDeviceImageFormatProperties2
• Any ImageView being sampled with FILTER_CUBIC_EXT with a reduction mode of either SAMPLER_REDUCTION_MODE_MIN or SAMPLER_REDUCTION_MODE_MAX as a result of this command must have a ImageViewType and format that supports cubic filtering together with minmax filtering, as specified by FilterCubicImageViewImageFormatPropertiesEXT::filterCubicMinmax returned by getPhysicalDeviceImageFormatProperties2
• Any Image created with a ImageCreateInfo::flags containing IMAGE_CREATE_CORNER_SAMPLED_BIT_NV sampled as a result of this command must only be sampled using a SamplerAddressMode of SAMPLER_ADDRESS_MODE_CLAMP_TO_EDGE
• For each set n that is statically used by the Pipeline bound to the pipeline bind point used by this command, a descriptor set must have been bound to n at the same pipeline bind point, with a PipelineLayout that is compatible for set n, with the PipelineLayout used to create the current Pipeline, as described in ???
• For each push constant that is statically used by the Pipeline bound to the pipeline bind point used by this command, a push constant value must have been set for the same pipeline bind point, with a PipelineLayout that is compatible for push constants, with the PipelineLayout used to create the current Pipeline, as described in ???
• Descriptors in each bound descriptor set, specified via cmdBindDescriptorSets, must be valid if they are statically used by the Pipeline bound to the pipeline bind point used by this command
• A valid pipeline must be bound to the pipeline bind point used by this command
• If the Pipeline object bound to the pipeline bind point used by this command requires any dynamic state, that state must have been set for commandBuffer, and done so after any previously bound pipeline with the corresponding state not specified as dynamic
• There must not have been any calls to dynamic state setting commands for any state not specified as dynamic in the Pipeline object bound to the pipeline bind point used by this command, since that pipeline was bound
• If the Pipeline object bound to the pipeline bind point used by this command accesses a Sampler object that uses unnormalized coordinates, that sampler must not be used to sample from any Image with a ImageView of the type IMAGE_VIEW_TYPE_3D, IMAGE_VIEW_TYPE_CUBE, IMAGE_VIEW_TYPE_1D_ARRAY, IMAGE_VIEW_TYPE_2D_ARRAY or IMAGE_VIEW_TYPE_CUBE_ARRAY, in any shader stage
• If the Pipeline object bound to the pipeline bind point used by this command accesses a Sampler object that uses unnormalized coordinates, that sampler must not be used with any of the SPIR-V OpImageSample* or OpImageSparseSample* instructions with ImplicitLod, Dref or Proj in their name, in any shader stage
• If the Pipeline object bound to the pipeline bind point used by this command accesses a Sampler object that uses unnormalized coordinates, that sampler must not be used with any of the SPIR-V OpImageSample* or OpImageSparseSample* instructions that includes a LOD bias or any offset values, in any shader stage
• If the robust buffer access feature is not enabled, and if the Pipeline object bound to the pipeline bind point used by this command accesses a uniform buffer, it must not access values outside of the range of the buffer as specified in the descriptor set bound to the same pipeline bind point
• If the robust buffer access feature is not enabled, and if the Pipeline object bound to the pipeline bind point used by this command accesses a storage buffer, it must not access values outside of the range of the buffer as specified in the descriptor set bound to the same pipeline bind point
• If commandBuffer is an unprotected command buffer, any resource accessed by the Pipeline object bound to the pipeline bind point used by this command must not be a protected resource
• If a ImageView is accessed using OpImageWrite as a result of this command, then the Type of the Texel operand of that instruction must have at least as many components as the image view’s format.
• If commandBuffer is a protected command buffer, any resource written to by the Pipeline object bound to the pipeline bind point used by this command must not be an unprotected resource
• If commandBuffer is a protected command buffer, pipeline stages other than the framebuffer-space and compute stages in the Pipeline object bound to the pipeline bind point must not write to any resource
• groupCountX must be less than or equal to PhysicalDeviceLimits::maxComputeWorkGroupCount[0]
• groupCountY must be less than or equal to PhysicalDeviceLimits::maxComputeWorkGroupCount[1]
• groupCountZ must be less than or equal to PhysicalDeviceLimits::maxComputeWorkGroupCount[2]

Valid Usage (Implicit)

• commandBuffer must be a valid CommandBuffer handle

• commandBuffer must be in the recording state
• The CommandPool that commandBuffer was allocated from must support compute operations
• This command must only be called outside of a render pass instance

Host Synchronization

• Host access to commandBuffer must be externally synchronized

• Host access to the CommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties

'

See Also

CommandBuffer

vkCmdDispatchIndirect - Dispatch compute work items using indirect parameters

Description

cmdDispatchIndirect behaves similarly to cmdDispatch except that the parameters are read by the device from a buffer during execution. The parameters of the dispatch are encoded in a DispatchIndirectCommand structure taken from buffer starting at offset.

Valid Usage

• If a ImageView is sampled with FILTER_LINEAR as a result of this command, then the image view’s format features must contain FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_LINEAR_BIT

• If a ImageView is accessed using atomic operations as a result of this command, then the image view’s format features must contain FORMAT_FEATURE_STORAGE_IMAGE_ATOMIC_BIT
• If a ImageView is sampled with FILTER_CUBIC_EXT as a result of this command, then the image view’s format features must contain FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_CUBIC_BIT_EXT
• Any ImageView being sampled with FILTER_CUBIC_EXT as a result of this command must have a ImageViewType and format that supports cubic filtering, as specified by FilterCubicImageViewImageFormatPropertiesEXT::filterCubic returned by getPhysicalDeviceImageFormatProperties2
• Any ImageView being sampled with FILTER_CUBIC_EXT with a reduction mode of either SAMPLER_REDUCTION_MODE_MIN or SAMPLER_REDUCTION_MODE_MAX as a result of this command must have a ImageViewType and format that supports cubic filtering together with minmax filtering, as specified by FilterCubicImageViewImageFormatPropertiesEXT::filterCubicMinmax returned by getPhysicalDeviceImageFormatProperties2
• Any Image created with a ImageCreateInfo::flags containing IMAGE_CREATE_CORNER_SAMPLED_BIT_NV sampled as a result of this command must only be sampled using a SamplerAddressMode of SAMPLER_ADDRESS_MODE_CLAMP_TO_EDGE
• For each set n that is statically used by the Pipeline bound to the pipeline bind point used by this command, a descriptor set must have been bound to n at the same pipeline bind point, with a PipelineLayout that is compatible for set n, with the PipelineLayout used to create the current Pipeline, as described in ???
• For each push constant that is statically used by the Pipeline bound to the pipeline bind point used by this command, a push constant value must have been set for the same pipeline bind point, with a PipelineLayout that is compatible for push constants, with the PipelineLayout used to create the current Pipeline, as described in ???
• Descriptors in each bound descriptor set, specified via cmdBindDescriptorSets, must be valid if they are statically used by the Pipeline bound to the pipeline bind point used by this command
• A valid pipeline must be bound to the pipeline bind point used by this command
• If the Pipeline object bound to the pipeline bind point used by this command requires any dynamic state, that state must have been set for commandBuffer, and done so after any previously bound pipeline with the corresponding state not specified as dynamic
• There must not have been any calls to dynamic state setting commands for any state not specified as dynamic in the Pipeline object bound to the pipeline bind point used by this command, since that pipeline was bound
• If the Pipeline object bound to the pipeline bind point used by this command accesses a Sampler object that uses unnormalized coordinates, that sampler must not be used to sample from any Image with a ImageView of the type IMAGE_VIEW_TYPE_3D, IMAGE_VIEW_TYPE_CUBE, IMAGE_VIEW_TYPE_1D_ARRAY, IMAGE_VIEW_TYPE_2D_ARRAY or IMAGE_VIEW_TYPE_CUBE_ARRAY, in any shader stage
• If the Pipeline object bound to the pipeline bind point used by this command accesses a Sampler object that uses unnormalized coordinates, that sampler must not be used with any of the SPIR-V OpImageSample* or OpImageSparseSample* instructions with ImplicitLod, Dref or Proj in their name, in any shader stage
• If the Pipeline object bound to the pipeline bind point used by this command accesses a Sampler object that uses unnormalized coordinates, that sampler must not be used with any of the SPIR-V OpImageSample* or OpImageSparseSample* instructions that includes a LOD bias or any offset values, in any shader stage
• If the robust buffer access feature is not enabled, and if the Pipeline object bound to the pipeline bind point used by this command accesses a uniform buffer, it must not access values outside of the range of the buffer as specified in the descriptor set bound to the same pipeline bind point
• If the robust buffer access feature is not enabled, and if the Pipeline object bound to the pipeline bind point used by this command accesses a storage buffer, it must not access values outside of the range of the buffer as specified in the descriptor set bound to the same pipeline bind point
• If commandBuffer is an unprotected command buffer, any resource accessed by the Pipeline object bound to the pipeline bind point used by this command must not be a protected resource
• If a ImageView is accessed using OpImageWrite as a result of this command, then the Type of the Texel operand of that instruction must have at least as many components as the image view’s format.
• If buffer is non-sparse then it must be bound completely and contiguously to a single DeviceMemory object
• buffer must have been created with the BUFFER_USAGE_INDIRECT_BUFFER_BIT bit set
• offset must be a multiple of 4
• commandBuffer must not be a protected command buffer
• The sum of offset and the size of DispatchIndirectCommand must be less than or equal to the size of buffer

Valid Usage (Implicit)

• commandBuffer must be a valid CommandBuffer handle

• buffer must be a valid Buffer handle
• commandBuffer must be in the recording state
• The CommandPool that commandBuffer was allocated from must support compute operations
• This command must only be called outside of a render pass instance
• Both of buffer, and commandBuffer must have been created, allocated, or retrieved from the same Device

Host Synchronization

• Host access to commandBuffer must be externally synchronized

• Host access to the CommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties

'

See Also

Buffer, CommandBuffer, DeviceSize

vkCmdCopyBuffer - Copy data between buffer regions

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.

Valid Usage

• If commandBuffer is an unprotected command buffer, then srcBuffer must not be a protected buffer

• If commandBuffer is an unprotected command buffer, then dstBuffer must not be a protected buffer
• If commandBuffer is a protected command buffer, then dstBuffer must not be an unprotected buffer
• The srcOffset member of each element of pRegions must be less than the size of srcBuffer
• The dstOffset member of each element of pRegions must be less than the size of dstBuffer
• The size member of each element of pRegions must be less than or equal to the size of srcBuffer minus srcOffset
• The size member of each element of pRegions must be less than or equal to the size of dstBuffer minus dstOffset
• The union of the source regions, and the union of the destination regions, specified by the elements of pRegions, must not overlap in memory
• srcBuffer must have been created with BUFFER_USAGE_TRANSFER_SRC_BIT usage flag
• If srcBuffer is non-sparse then it must be bound completely and contiguously to a single DeviceMemory object
• dstBuffer must have been created with BUFFER_USAGE_TRANSFER_DST_BIT usage flag
• If dstBuffer is non-sparse then it must be bound completely and contiguously to a single DeviceMemory object

Valid Usage (Implicit)

• commandBuffer must be a valid CommandBuffer handle

• srcBuffer must be a valid Buffer handle
• dstBuffer must be a valid Buffer handle
• pRegions must be a valid pointer to an array of regionCount valid BufferCopy structures
• commandBuffer must be in the recording state
• The CommandPool that commandBuffer was allocated from must support transfer, graphics, or compute operations
• This command must only be called outside of a render pass instance
• regionCount must be greater than 0
• Each of commandBuffer, dstBuffer, and srcBuffer must have been created, allocated, or retrieved from the same Device

Host Synchronization

• Host access to commandBuffer must be externally synchronized

• Host access to the CommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties

'

See Also

Buffer, BufferCopy, CommandBuffer

vkCmdCopyImage - Copy data between images

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 ImageCopy structure. In this case, the aspectMask of the srcSubresource or dstSubresource that refers to the multi-planar image must be IMAGE_ASPECT_PLANE_0_BIT, IMAGE_ASPECT_PLANE_1_BIT, or IMAGE_ASPECT_PLANE_2_BIT. For the purposes of cmdCopyImage, 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 Format 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 IMAGE_ASPECT_PLANE_1_BIT plane of a FORMAT_G8_B8R8_2PLANE_420_UNORM image is compatible with an image of format FORMAT_R8G8_UNORM and (less usefully) with the IMAGE_ASPECT_PLANE_0_BIT plane of an image of format FORMAT_G10X6_B10X6_R10X6_3PLANE_420_UNORM_3PACK16, as each texel is 2 bytes in size.

cmdCopyImage 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.width is not a multiple of the compressed texel block width, then (extent.width + srcOffset.x) must equal the image subresource width.
• If extent.height is not a multiple of the compressed texel block height, then (extent.height + srcOffset.y) must equal the image subresource height.
• If extent.depth is 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.width is not a multiple of the compressed texel block width, then (extent.width + dstOffset.x) must equal the image subresource width.
• If extent.height is not a multiple of the compressed texel block height, then (extent.height + dstOffset.y) must equal the image subresource height.
• If extent.depth is 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.

cmdCopyImage can be used to copy image data between multisample images, but both images must have the same number of samples.

Valid Usage

• If commandBuffer is an unprotected command buffer, then srcImage must not be a protected image

• If commandBuffer is an unprotected command buffer, then dstImage must not be a protected image
• If commandBuffer is a protected command buffer, then dstImage must not be an unprotected image
• The union of all source regions, and the union of all destination regions, specified by the elements of pRegions, must not overlap in memory
• The format features of srcImage must contain FORMAT_FEATURE_TRANSFER_SRC_BIT
• srcImage must have been created with IMAGE_USAGE_TRANSFER_SRC_BIT usage flag
• If srcImage is non-sparse then the image or disjoint plane to be copied must be bound completely and contiguously to a single DeviceMemory object
• srcImageLayout must specify the layout of the image subresources of srcImage specified in pRegions at the time this command is executed on a Device
• srcImageLayout must be IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL, IMAGE_LAYOUT_GENERAL, or IMAGE_LAYOUT_SHARED_PRESENT_KHR
• The format features of dstImage must contain FORMAT_FEATURE_TRANSFER_DST_BIT
• dstImage must have been created with IMAGE_USAGE_TRANSFER_DST_BIT usage flag
• If dstImage is non-sparse then the image or disjoint plane that is the destination of the copy must be bound completely and contiguously to a single DeviceMemory object
• dstImageLayout must specify the layout of the image subresources of dstImage specified in pRegions at the time this command is executed on a Device
• dstImageLayout must be IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL, IMAGE_LAYOUT_GENERAL, or IMAGE_LAYOUT_SHARED_PRESENT_KHR
• If the Format of each of srcImage and dstImage is not a multi-planar format, the Format of each of srcImage and dstImage must be compatible, as defined above
• In a copy to or from a plane of a multi-planar image, the Format of the image and plane must be compatible according to the description of compatible planes for the plane being copied
• The sample count of srcImage and dstImage must match
• The srcSubresource.mipLevel member of each element of pRegions must be less than the mipLevels specified in ImageCreateInfo when srcImage was created
• The dstSubresource.mipLevel member of each element of pRegions must be less than the mipLevels specified in ImageCreateInfo when dstImage was created
• The srcSubresource.baseArrayLayer + srcSubresource.layerCount of each element of pRegions must be less than or equal to the arrayLayers specified in ImageCreateInfo when srcImage was created
• The dstSubresource.baseArrayLayer + dstSubresource.layerCount of each element of pRegions must be less than or equal to the arrayLayers specified in ImageCreateInfo when dstImage was created
• The srcOffset and extent members of each element of pRegions must respect the image transfer granularity requirements of commandBuffer’s command pool’s queue family, as described in QueueFamilyProperties
• The dstOffset and extent members of each element of pRegions must respect the image transfer granularity requirements of commandBuffer’s command pool’s queue family, as described in QueueFamilyProperties
• dstImage and srcImage must not have been created with flags containing IMAGE_CREATE_SUBSAMPLED_BIT_EXT

Valid Usage (Implicit)

• commandBuffer must be a valid CommandBuffer handle

• srcImage must be a valid Image handle
• srcImageLayout must be a valid ImageLayout value
• dstImage must be a valid Image handle
• dstImageLayout must be a valid ImageLayout value
• pRegions must be a valid pointer to an array of regionCount valid ImageCopy structures
• commandBuffer must be in the recording state
• The CommandPool that commandBuffer was allocated from must support transfer, graphics, or compute operations
• This command must only be called outside of a render pass instance
• regionCount must be greater than 0
• Each of commandBuffer, dstImage, and srcImage must have been created, allocated, or retrieved from the same Device

Host Synchronization

• Host access to commandBuffer must be externally synchronized

• Host access to the CommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties

'

See Also

CommandBuffer, Image, ImageCopy, ImageLayout

vkCmdBlitImage - Copy regions of an image, potentially performing format conversion,

Description

cmdBlitImage must not be used for multisampled source or destination images. Use cmdResolveImage 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:

  • scaleu = (xsrc1 - xsrc0) / (xdst1 - xdst0)
  • scalev = (ysrc1 - ysrc0) / (ydst1 - ydst0)
  • scalew = (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 SAMPLER_MIPMAP_MODE_NEAREST and an address mode of 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 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 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.

Valid Usage

• If commandBuffer is an unprotected command buffer, then srcImage must not be a protected image

• If commandBuffer is an unprotected command buffer, then dstImage must not be a protected image
• If commandBuffer is a protected command buffer, then dstImage must not be an unprotected image
• The source region specified by each element of pRegions must be a region that is contained within srcImage
• The destination region specified by each element of pRegions must be a region that is contained within dstImage
• The union of all destination regions, specified by the elements of pRegions, must not overlap in memory with any texel that may be sampled during the blit operation
• The format features of srcImage must contain FORMAT_FEATURE_BLIT_SRC_BIT
• srcImage must not use a format listed in ???
• srcImage must have been created with IMAGE_USAGE_TRANSFER_SRC_BIT usage flag
• If srcImage is non-sparse then it must be bound completely and contiguously to a single DeviceMemory object
• srcImageLayout must specify the layout of the image subresources of srcImage specified in pRegions at the time this command is executed on a Device
• srcImageLayout must be IMAGE_LAYOUT_SHARED_PRESENT_KHR, IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL or IMAGE_LAYOUT_GENERAL
• The format features of dstImage must contain FORMAT_FEATURE_BLIT_DST_BIT
• dstImage must not use a format listed in ???
• dstImage must have been created with IMAGE_USAGE_TRANSFER_DST_BIT usage flag
• If dstImage is non-sparse then it must be bound completely and contiguously to a single DeviceMemory object
• dstImageLayout must specify the layout of the image subresources of dstImage specified in pRegions at the time this command is executed on a Device
• dstImageLayout must be IMAGE_LAYOUT_SHARED_PRESENT_KHR, IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL or IMAGE_LAYOUT_GENERAL
• If either of srcImage or dstImage was created with a signed integer Format, the other must also have been created with a signed integer Format
• If either of srcImage or dstImage was created with an unsigned integer Format, the other must also have been created with an unsigned integer Format
• If either of srcImage or dstImage was created with a depth/stencil format, the other must have exactly the same format
• If srcImage was created with a depth/stencil format, filter must be FILTER_NEAREST
• srcImage must have been created with a samples value of SAMPLE_COUNT_1_BIT
• dstImage must have been created with a samples value of SAMPLE_COUNT_1_BIT
• If filter is FILTER_LINEAR, then the format features of srcImage must contain FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_LINEAR_BIT
• If filter is FILTER_CUBIC_EXT, then the format features of srcImage must contain FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_CUBIC_BIT_EXT
• If filter is FILTER_CUBIC_EXT, srcImage must have a ImageType of IMAGE_TYPE_2D
• The srcSubresource.mipLevel member of each element of pRegions must be less than the mipLevels specified in ImageCreateInfo when srcImage was created
• The dstSubresource.mipLevel member of each element of pRegions must be less than the mipLevels specified in ImageCreateInfo when dstImage was created
• The srcSubresource.baseArrayLayer + srcSubresource.layerCount of each element of pRegions must be less than or equal to the arrayLayers specified in ImageCreateInfo when srcImage was created
• The dstSubresource.baseArrayLayer + dstSubresource.layerCount of each element of pRegions must be less than or equal to the arrayLayers specified in ImageCreateInfo when dstImage was created
• dstImage and srcImage must not have been created with flags containing IMAGE_CREATE_SUBSAMPLED_BIT_EXT

Valid Usage (Implicit)

• commandBuffer must be a valid CommandBuffer handle

• srcImage must be a valid Image handle
• srcImageLayout must be a valid ImageLayout value
• dstImage must be a valid Image handle
• dstImageLayout must be a valid ImageLayout value
• pRegions must be a valid pointer to an array of regionCount valid ImageBlit structures
• filter must be a valid Filter value
• commandBuffer must be in the recording state
• The CommandPool that commandBuffer was allocated from must support graphics operations
• This command must only be called outside of a render pass instance
• regionCount must be greater than 0
• Each of commandBuffer, dstImage, and srcImage must have been created, allocated, or retrieved from the same Device

Host Synchronization

• Host access to commandBuffer must be externally synchronized

• Host access to the CommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties

'

See Also

CommandBuffer, Filter, Image, ImageBlit, ImageLayout

vkCmdCopyBufferToImage - Copy data from a buffer into an image

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 BufferImageCopy structure. In this case, the aspectMask of imageSubresource must be IMAGE_ASPECT_PLANE_0_BIT, IMAGE_ASPECT_PLANE_1_BIT, or IMAGE_ASPECT_PLANE_2_BIT. For the purposes of cmdCopyBufferToImage, 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 Format 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.

Valid Usage

• If commandBuffer is an unprotected command buffer, then srcBuffer must not be a protected buffer

• If commandBuffer is an unprotected command buffer, then dstImage must not be a protected image
• If commandBuffer is a protected command buffer, then dstImage must not be an unprotected image
• srcBuffer must be large enough to contain all buffer locations that are accessed according to Buffer and Image Addressing, for each element of pRegions
• The image region specified by each element of pRegions must be a region that is contained within dstImage if the dstImage’s Format is not a multi-planar format, and must be a region that is contained within the plane being copied to if the dstImage’s Format is a multi-planar format
• The union of all source regions, and the union of all destination regions, specified by the elements of pRegions, must not overlap in memory
• srcBuffer must have been created with BUFFER_USAGE_TRANSFER_SRC_BIT usage flag
• The format features of dstImage must contain FORMAT_FEATURE_TRANSFER_DST_BIT
• If srcBuffer is non-sparse then it must be bound completely and contiguously to a single DeviceMemory object
• dstImage must have been created with IMAGE_USAGE_TRANSFER_DST_BIT usage flag
• If dstImage is non-sparse then it must be bound completely and contiguously to a single DeviceMemory object
• dstImage must have a sample count equal to SAMPLE_COUNT_1_BIT
• dstImageLayout must specify the layout of the image subresources of dstImage specified in pRegions at the time this command is executed on a Device
• dstImageLayout must be IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL, IMAGE_LAYOUT_GENERAL, or IMAGE_LAYOUT_SHARED_PRESENT_KHR
• The imageSubresource.mipLevel member of each element of pRegions must be less than the mipLevels specified in ImageCreateInfo when dstImage was created
• The imageSubresource.baseArrayLayer + imageSubresource.layerCount of each element of pRegions must be less than or equal to the arrayLayers specified in ImageCreateInfo when dstImage was created
• The imageOffset and imageExtent members of each element of pRegions must respect the image transfer granularity requirements of commandBuffer’s command pool’s queue family, as described in QueueFamilyProperties
• dstImage must not have been created with flags containing IMAGE_CREATE_SUBSAMPLED_BIT_EXT
• If the queue family used to create the CommandPool which commandBuffer was allocated from does not support QUEUE_GRAPHICS_BIT or QUEUE_COMPUTE_BIT, the bufferOffset member of any element of pRegions must be a multiple of 4
• If dstImage has a depth/stencil format, the bufferOffset member of any element of pRegions must be a multiple of 4

Valid Usage (Implicit)

• commandBuffer must be a valid CommandBuffer handle

• srcBuffer must be a valid Buffer handle
• dstImage must be a valid Image handle
• dstImageLayout must be a valid ImageLayout value
• pRegions must be a valid pointer to an array of regionCount valid BufferImageCopy structures
• commandBuffer must be in the recording state
• The CommandPool that commandBuffer was allocated from must support transfer, graphics, or compute operations
• This command must only be called outside of a render pass instance
• regionCount must be greater than 0
• Each of commandBuffer, dstImage, and srcBuffer must have been created, allocated, or retrieved from the same Device

Host Synchronization

• Host access to commandBuffer must be externally synchronized

• Host access to the CommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties

'

See Also

Buffer, BufferImageCopy, CommandBuffer, Image, ImageLayout

vkCmdCopyImageToBuffer - Copy image data into a buffer

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 Format 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 BufferImageCopy structure. In this case, the aspectMask of imageSubresource must be IMAGE_ASPECT_PLANE_0_BIT, IMAGE_ASPECT_PLANE_1_BIT, or IMAGE_ASPECT_PLANE_2_BIT. For the purposes of cmdCopyBufferToImage, 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 Format 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.

Valid Usage

• If commandBuffer is an unprotected command buffer, then srcImage must not be a protected image

• If commandBuffer is an unprotected command buffer, then dstBuffer must not be a protected buffer
• If commandBuffer is a protected command buffer, then dstBuffer must not be an unprotected buffer
• The image region specified by each element of pRegions must be a region that is contained within srcImage if the srcImage’s Format is not a multi-planar format, and must be a region that is contained within the plane being copied if the srcImage’s Format is a multi-planar format
• dstBuffer must be large enough to contain all buffer locations that are accessed according to Buffer and Image Addressing, for each element of pRegions
• The union of all source regions, and the union of all destination regions, specified by the elements of pRegions, must not overlap in memory
• The format features of srcImage must contain FORMAT_FEATURE_TRANSFER_SRC_BIT
• srcImage must have been created with IMAGE_USAGE_TRANSFER_SRC_BIT usage flag
• If srcImage is non-sparse then it must be bound completely and contiguously to a single DeviceMemory object
• srcImage must have a sample count equal to SAMPLE_COUNT_1_BIT
• srcImageLayout must specify the layout of the image subresources of srcImage specified in pRegions at the time this command is executed on a Device
• srcImageLayout must be IMAGE_LAYOUT_SHARED_PRESENT_KHR, IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL or IMAGE_LAYOUT_GENERAL
• dstBuffer must have been created with BUFFER_USAGE_TRANSFER_DST_BIT usage flag
• If dstBuffer is non-sparse then it must be bound completely and contiguously to a single DeviceMemory object
• The imageSubresource.mipLevel member of each element of pRegions must be less than the mipLevels specified in ImageCreateInfo when srcImage was created
• The imageSubresource.baseArrayLayer + imageSubresource.layerCount of each element of pRegions must be less than or equal to the arrayLayers specified in ImageCreateInfo when srcImage was created
• The imageOffset and imageExtent members of each element of pRegions must respect the image transfer granularity requirements of commandBuffer’s command pool’s queue family, as described in QueueFamilyProperties
• srcImage must not have been created with flags containing IMAGE_CREATE_SUBSAMPLED_BIT_EXT
• If the queue family used to create the CommandPool which commandBuffer was allocated from does not support QUEUE_GRAPHICS_BIT or QUEUE_COMPUTE_BIT, the bufferOffset member of any element of pRegions must be a multiple of 4
• If srcImage has a depth/stencil format, the bufferOffset member of any element of pRegions must be a multiple of 4

Valid Usage (Implicit)

• commandBuffer must be a valid CommandBuffer handle

• srcImage must be a valid Image handle
• srcImageLayout must be a valid ImageLayout value
• dstBuffer must be a valid Buffer handle
• pRegions must be a valid pointer to an array of regionCount valid BufferImageCopy structures
• commandBuffer must be in the recording state
• The CommandPool that commandBuffer was allocated from must support transfer, graphics, or compute operations
• This command must only be called outside of a render pass instance
• regionCount must be greater than 0
• Each of commandBuffer, dstBuffer, and srcImage must have been created, allocated, or retrieved from the same Device

Host Synchronization

• Host access to commandBuffer must be externally synchronized

• Host access to the CommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties

'

See Also

Buffer, BufferImageCopy, CommandBuffer, Image, ImageLayout

vkCmdUpdateBuffer - Update a buffer’s contents from host memory

Description

dataSize must be less than or equal to 65536 bytes. For larger updates, applications can use buffer to buffer copies.

Note

Buffer updates performed with cmdUpdateBuffer first copy the data into command buffer memory when the command is recorded (which requires additional storage and may incur an additional allocation), and then copy the data from the command buffer into dstBuffer when the command is executed on a device.

The additional cost of this functionality compared to buffer to buffer copies means it is only recommended for very small amounts of data, and is why it is limited to only 65536 bytes.

Applications can work around this by issuing multiple cmdUpdateBuffer commands to different ranges of the same buffer, but it is strongly recommended that they should not.

The source data is copied from the user pointer to the command buffer when the command is called.

cmdUpdateBuffer is only allowed outside of a render pass. This command is treated as “transfer” operation, for the purposes of synchronization barriers. The BUFFER_USAGE_TRANSFER_DST_BIT must be specified in usage of BufferCreateInfo in order for the buffer to be compatible with cmdUpdateBuffer.

Valid Usage

• dstOffset must be less than the size of dstBuffer

• dataSize must be less than or equal to the size of dstBuffer minus dstOffset
• dstBuffer must have been created with BUFFER_USAGE_TRANSFER_DST_BIT usage flag
• If dstBuffer is non-sparse then it must be bound completely and contiguously to a single DeviceMemory object
• dstOffset must be a multiple of 4
• dataSize must be less than or equal to 65536
• dataSize must be a multiple of 4
• If commandBuffer is an unprotected command buffer, then dstBuffer must not be a protected buffer
• If commandBuffer is a protected command buffer, then dstBuffer must not be an unprotected buffer

Valid Usage (Implicit)

• commandBuffer must be a valid CommandBuffer handle

• dstBuffer must be a valid Buffer handle
• pData must be a valid pointer to an array of dataSize bytes
• commandBuffer must be in the recording state
• The CommandPool that commandBuffer was allocated from must support transfer, graphics, or compute operations
• This command must only be called outside of a render pass instance
• dataSize must be greater than 0
• Both of commandBuffer, and dstBuffer must have been created, allocated, or retrieved from the same Device

Host Synchronization

• Host access to commandBuffer must be externally synchronized

• Host access to the CommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties

'

See Also

Buffer, CommandBuffer, DeviceSize

vkCmdFillBuffer - Fill a region of a buffer with a fixed value

Description

cmdFillBuffer is treated as “transfer” operation for the purposes of synchronization barriers. The BUFFER_USAGE_TRANSFER_DST_BIT must be specified in usage of BufferCreateInfo in order for the buffer to be compatible with cmdFillBuffer.

Valid Usage

• dstOffset must be less than the size of dstBuffer

• dstOffset must be a multiple of 4
• If size is not equal to WHOLE_SIZE, size must be greater than 0
• If size is not equal to WHOLE_SIZE, size must be less than or equal to the size of dstBuffer minus dstOffset
• If size is not equal to WHOLE_SIZE, size must be a multiple of 4
• dstBuffer must have been created with BUFFER_USAGE_TRANSFER_DST_BIT usage flag
• If dstBuffer is non-sparse then it must be bound completely and contiguously to a single DeviceMemory object
• If commandBuffer is an unprotected command buffer, then dstBuffer must not be a protected buffer
• If commandBuffer is a protected command buffer, then dstBuffer must not be an unprotected buffer

Valid Usage (Implicit)

• commandBuffer must be a valid CommandBuffer handle

• dstBuffer must be a valid Buffer handle
• commandBuffer must be in the recording state
• The CommandPool that commandBuffer was allocated from must support transfer, graphics or compute operations
• This command must only be called outside of a render pass instance
• Both of commandBuffer, and dstBuffer must have been created, allocated, or retrieved from the same Device

Host Synchronization

• Host access to commandBuffer must be externally synchronized

• Host access to the CommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties

'

See Also

Buffer, CommandBuffer, DeviceSize

vkCmdClearColorImage - Clear regions of a color image

Description

Each specified range in pRanges is cleared to the value specified by pColor.

Valid Usage

• The format features of image must contain FORMAT_FEATURE_TRANSFER_DST_BIT

• image must have been created with IMAGE_USAGE_TRANSFER_DST_BIT usage flag
• image must not use a format listed in https://www.khronos.org/registry/vulkan/specs/1.2-extensions/html/vkspec.html#formats-requiring-sampler-ycbcr-conversion
• If image is non-sparse then it must be bound completely and contiguously to a single DeviceMemory object
• imageLayout must specify the layout of the image subresource ranges of image specified in pRanges at the time this command is executed on a Device
• imageLayout must be IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL, IMAGE_LAYOUT_GENERAL, or IMAGE_LAYOUT_SHARED_PRESENT_KHR
• The ImageSubresourceRange::aspectMask members of the elements of the pRanges array must each only include IMAGE_ASPECT_COLOR_BIT
• The ImageSubresourceRange::baseMipLevel members of the elements of the pRanges array must each be less than the mipLevels specified in ImageCreateInfo when image was created
• For each ImageSubresourceRange element of pRanges, if the levelCount member is not REMAINING_MIP_LEVELS, then baseMipLevel + levelCount must be less than the mipLevels specified in ImageCreateInfo when image was created
• The ImageSubresourceRange::baseArrayLayer members of the elements of the pRanges array must each be less than the arrayLayers specified in ImageCreateInfo when image was created
• For each ImageSubresourceRange element of pRanges, if the layerCount member is not REMAINING_ARRAY_LAYERS, then baseArrayLayer + layerCount must be less than the arrayLayers specified in ImageCreateInfo when image was created
• image must not have a compressed or depth/stencil format
• If commandBuffer is an unprotected command buffer, then image must not be a protected image
• If commandBuffer is a protected command buffer, then image must not be an unprotected image

Valid Usage (Implicit)

• commandBuffer must be a valid CommandBuffer handle

• image must be a valid Image handle
• imageLayout must be a valid ImageLayout value
• pColor must be a valid pointer to a valid ClearColorValue union
• pRanges must be a valid pointer to an array of rangeCount valid ImageSubresourceRange structures
• commandBuffer must be in the recording state
• The CommandPool that commandBuffer was allocated from must support graphics, or compute operations
• This command must only be called outside of a render pass instance
• rangeCount must be greater than 0
• Both of commandBuffer, and image must have been created, allocated, or retrieved from the same Device

Host Synchronization

• Host access to commandBuffer must be externally synchronized

• Host access to the CommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties

'

See Also

ClearColorValue, CommandBuffer, Image, ImageLayout, ImageSubresourceRange

vkCmdClearDepthStencilImage - Fill regions of a combined depth/stencil image

Valid Usage

• The format features of image must contain FORMAT_FEATURE_TRANSFER_DST_BIT

• If the aspect member of any element of pRanges includes IMAGE_ASPECT_STENCIL_BIT, and image was created with separate stencil usage, IMAGE_USAGE_TRANSFER_DST_BIT must have been included in the ImageStencilUsageCreateInfo::stencilUsage used to create image
• If the aspect member of any element of pRanges includes IMAGE_ASPECT_STENCIL_BIT, and image was not created with separate stencil usage, IMAGE_USAGE_TRANSFER_DST_BIT must have been included in the ImageCreateInfo::usage used to create image
• If the aspect member of any element of pRanges includes IMAGE_ASPECT_DEPTH_BIT, IMAGE_USAGE_TRANSFER_DST_BIT must have been included in the ImageCreateInfo::usage used to create image
• If image is non-sparse then it must be bound completely and contiguously to a single DeviceMemory object
• imageLayout must specify the layout of the image subresource ranges of image specified in pRanges at the time this command is executed on a Device
• imageLayout must be either of IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL or IMAGE_LAYOUT_GENERAL
• The ImageSubresourceRange::aspectMask member of each element of the pRanges array must not include bits other than IMAGE_ASPECT_DEPTH_BIT or IMAGE_ASPECT_STENCIL_BIT
• If the image’s format does not have a stencil component, then the ImageSubresourceRange::aspectMask member of each element of the pRanges array must not include the IMAGE_ASPECT_STENCIL_BIT bit
• If the image’s format does not have a depth component, then the ImageSubresourceRange::aspectMask member of each element of the pRanges array must not include the IMAGE_ASPECT_DEPTH_BIT bit
• The ImageSubresourceRange::baseMipLevel members of the elements of the pRanges array must each be less than the mipLevels specified in ImageCreateInfo when image was created
• For each ImageSubresourceRange element of pRanges, if the levelCount member is not REMAINING_MIP_LEVELS, then baseMipLevel + levelCount must be less than the mipLevels specified in ImageCreateInfo when image was created
• The ImageSubresourceRange::baseArrayLayer members of the elements of the pRanges array must each be less than the arrayLayers specified in ImageCreateInfo when image was created
• For each ImageSubresourceRange element of pRanges, if the layerCount member is not REMAINING_ARRAY_LAYERS, then baseArrayLayer + layerCount must be less than the arrayLayers specified in ImageCreateInfo when image was created
• image must have a depth/stencil format
• If commandBuffer is an unprotected command buffer, then image must not be a protected image
• If commandBuffer is a protected command buffer, then image must not be an unprotected image

Valid Usage (Implicit)

• commandBuffer must be a valid CommandBuffer handle

• image must be a valid Image handle
• imageLayout must be a valid ImageLayout value
• pDepthStencil must be a valid pointer to a valid ClearDepthStencilValue structure
• pRanges must be a valid pointer to an array of rangeCount valid ImageSubresourceRange structures
• commandBuffer must be in the recording state
• The CommandPool that commandBuffer was allocated from must support graphics operations
• This command must only be called outside of a render pass instance
• rangeCount must be greater than 0
• Both of commandBuffer, and image must have been created, allocated, or retrieved from the same Device

Host Synchronization

• Host access to commandBuffer must be externally synchronized

• Host access to the CommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties

'

See Also

ClearDepthStencilValue, CommandBuffer, Image, ImageLayout, ImageSubresourceRange

vkCmdClearAttachments - Clear regions within bound framebuffer attachments

Description

cmdClearAttachments 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, cmdClearAttachments 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 PIPELINE_STAGE_COLOR_ATTACHMENT_OUTPUT_BIT stage. Clears to depth/stencil attachments are executed as depth writes and writes by the PIPELINE_STAGE_EARLY_FRAGMENT_TESTS_BIT and PIPELINE_STAGE_LATE_FRAGMENT_TESTS_BIT stages.

Valid Usage

• If the aspectMask member of any element of pAttachments contains IMAGE_ASPECT_COLOR_BIT, then the colorAttachment member of that element must either refer to a color attachment which is ATTACHMENT_UNUSED, or must be a valid color attachment

• If the aspectMask member of any element of pAttachments contains IMAGE_ASPECT_DEPTH_BIT, then the current subpass' depth/stencil attachment must either be ATTACHMENT_UNUSED, or must have a depth component
• If the aspectMask member of any element of pAttachments contains IMAGE_ASPECT_STENCIL_BIT, then the current subpass' depth/stencil attachment must either be ATTACHMENT_UNUSED, or must have a stencil component
• The rect member of each element of pRects must have an extent.width greater than 0
• The rect member of each element of pRects must have an extent.height greater than 0
• The rectangular region specified by each element of pRects must be contained within the render area of the current render pass instance
• The layers specified by each element of pRects must be contained within every attachment that pAttachments refers to
• The layerCount member of each element of pRects must not be 0
• If commandBuffer is an unprotected command buffer, then each attachment to be cleared must not be a protected image
• If commandBuffer is a protected command buffer, then each attachment to be cleared must not be an unprotected image
• If the render pass instance this is recorded in uses multiview, then baseArrayLayer must be zero and layerCount must be one

Valid Usage (Implicit)

• commandBuffer must be a valid CommandBuffer handle

• pAttachments must be a valid pointer to an array of attachmentCount valid ClearAttachment structures
• pRects must be a valid pointer to an array of rectCount ClearRect structures
• commandBuffer must be in the recording state
• The CommandPool that commandBuffer was allocated from must support graphics operations
• This command must only be called inside of a render pass instance
• attachmentCount must be greater than 0
• rectCount must be greater than 0

Host Synchronization

• Host access to commandBuffer must be externally synchronized

• Host access to the CommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties

'

See Also

ClearAttachment, ClearRect, CommandBuffer