Safe Haskell | None |
---|---|
Language | Haskell2010 |
Vulkan.Core10.CommandBufferBuilding
Synopsis
- cmdBindPipeline :: forall io. MonadIO io => CommandBuffer -> PipelineBindPoint -> Pipeline -> io ()
- cmdSetViewport :: forall io. MonadIO io => CommandBuffer -> ("firstViewport" ::: Word32) -> ("viewports" ::: Vector Viewport) -> io ()
- cmdSetScissor :: forall io. MonadIO io => CommandBuffer -> ("firstScissor" ::: Word32) -> ("scissors" ::: Vector Rect2D) -> io ()
- cmdSetLineWidth :: forall io. MonadIO io => CommandBuffer -> ("lineWidth" ::: Float) -> io ()
- cmdSetDepthBias :: forall io. MonadIO io => CommandBuffer -> ("depthBiasConstantFactor" ::: Float) -> ("depthBiasClamp" ::: Float) -> ("depthBiasSlopeFactor" ::: Float) -> io ()
- cmdSetBlendConstants :: forall io. MonadIO io => CommandBuffer -> ("blendConstants" ::: (Float, Float, Float, Float)) -> io ()
- cmdSetDepthBounds :: forall io. MonadIO io => CommandBuffer -> ("minDepthBounds" ::: Float) -> ("maxDepthBounds" ::: Float) -> io ()
- cmdSetStencilCompareMask :: forall io. MonadIO io => CommandBuffer -> ("faceMask" ::: StencilFaceFlags) -> ("compareMask" ::: Word32) -> io ()
- cmdSetStencilWriteMask :: forall io. MonadIO io => CommandBuffer -> ("faceMask" ::: StencilFaceFlags) -> ("writeMask" ::: Word32) -> io ()
- cmdSetStencilReference :: forall io. MonadIO io => CommandBuffer -> ("faceMask" ::: StencilFaceFlags) -> ("reference" ::: Word32) -> io ()
- cmdBindDescriptorSets :: forall io. MonadIO io => CommandBuffer -> PipelineBindPoint -> PipelineLayout -> ("firstSet" ::: Word32) -> ("descriptorSets" ::: Vector DescriptorSet) -> ("dynamicOffsets" ::: Vector Word32) -> io ()
- cmdBindIndexBuffer :: forall io. MonadIO io => CommandBuffer -> Buffer -> ("offset" ::: DeviceSize) -> IndexType -> io ()
- cmdBindVertexBuffers :: forall io. MonadIO io => CommandBuffer -> ("firstBinding" ::: Word32) -> ("buffers" ::: Vector Buffer) -> ("offsets" ::: Vector DeviceSize) -> io ()
- cmdDraw :: forall io. MonadIO io => CommandBuffer -> ("vertexCount" ::: Word32) -> ("instanceCount" ::: Word32) -> ("firstVertex" ::: Word32) -> ("firstInstance" ::: Word32) -> io ()
- cmdDrawIndexed :: forall io. MonadIO io => CommandBuffer -> ("indexCount" ::: Word32) -> ("instanceCount" ::: Word32) -> ("firstIndex" ::: Word32) -> ("vertexOffset" ::: Int32) -> ("firstInstance" ::: Word32) -> io ()
- cmdDrawIndirect :: forall io. MonadIO io => CommandBuffer -> Buffer -> ("offset" ::: DeviceSize) -> ("drawCount" ::: Word32) -> ("stride" ::: Word32) -> io ()
- cmdDrawIndexedIndirect :: forall io. MonadIO io => CommandBuffer -> Buffer -> ("offset" ::: DeviceSize) -> ("drawCount" ::: Word32) -> ("stride" ::: Word32) -> io ()
- cmdDispatch :: forall io. MonadIO io => CommandBuffer -> ("groupCountX" ::: Word32) -> ("groupCountY" ::: Word32) -> ("groupCountZ" ::: Word32) -> io ()
- cmdDispatchIndirect :: forall io. MonadIO io => CommandBuffer -> Buffer -> ("offset" ::: DeviceSize) -> io ()
- cmdCopyBuffer :: forall io. MonadIO io => CommandBuffer -> ("srcBuffer" ::: Buffer) -> ("dstBuffer" ::: Buffer) -> ("regions" ::: Vector BufferCopy) -> io ()
- cmdCopyImage :: forall io. MonadIO io => CommandBuffer -> ("srcImage" ::: Image) -> ("srcImageLayout" ::: ImageLayout) -> ("dstImage" ::: Image) -> ("dstImageLayout" ::: ImageLayout) -> ("regions" ::: Vector ImageCopy) -> io ()
- cmdBlitImage :: forall io. MonadIO io => CommandBuffer -> ("srcImage" ::: Image) -> ("srcImageLayout" ::: ImageLayout) -> ("dstImage" ::: Image) -> ("dstImageLayout" ::: ImageLayout) -> ("regions" ::: Vector ImageBlit) -> Filter -> io ()
- cmdCopyBufferToImage :: forall io. MonadIO io => CommandBuffer -> ("srcBuffer" ::: Buffer) -> ("dstImage" ::: Image) -> ("dstImageLayout" ::: ImageLayout) -> ("regions" ::: Vector BufferImageCopy) -> io ()
- cmdCopyImageToBuffer :: forall io. MonadIO io => CommandBuffer -> ("srcImage" ::: Image) -> ("srcImageLayout" ::: ImageLayout) -> ("dstBuffer" ::: Buffer) -> ("regions" ::: Vector BufferImageCopy) -> io ()
- cmdUpdateBuffer :: forall io. MonadIO io => CommandBuffer -> ("dstBuffer" ::: Buffer) -> ("dstOffset" ::: DeviceSize) -> ("dataSize" ::: DeviceSize) -> ("data" ::: Ptr ()) -> io ()
- cmdFillBuffer :: forall io. MonadIO io => CommandBuffer -> ("dstBuffer" ::: Buffer) -> ("dstOffset" ::: DeviceSize) -> DeviceSize -> ("data" ::: Word32) -> io ()
- cmdClearColorImage :: forall io. MonadIO io => CommandBuffer -> Image -> ImageLayout -> ClearColorValue -> ("ranges" ::: Vector ImageSubresourceRange) -> io ()
- cmdClearDepthStencilImage :: forall io. MonadIO io => CommandBuffer -> Image -> ImageLayout -> ClearDepthStencilValue -> ("ranges" ::: Vector ImageSubresourceRange) -> io ()
- cmdClearAttachments :: forall io. MonadIO io => CommandBuffer -> ("attachments" ::: Vector ClearAttachment) -> ("rects" ::: Vector ClearRect) -> io ()
- cmdResolveImage :: forall io. MonadIO io => CommandBuffer -> ("srcImage" ::: Image) -> ("srcImageLayout" ::: ImageLayout) -> ("dstImage" ::: Image) -> ("dstImageLayout" ::: ImageLayout) -> ("regions" ::: Vector ImageResolve) -> io ()
- cmdSetEvent :: forall io. MonadIO io => CommandBuffer -> Event -> ("stageMask" ::: PipelineStageFlags) -> io ()
- cmdResetEvent :: forall io. MonadIO io => CommandBuffer -> Event -> ("stageMask" ::: PipelineStageFlags) -> io ()
- cmdWaitEvents :: forall io. MonadIO io => CommandBuffer -> ("events" ::: Vector Event) -> ("srcStageMask" ::: PipelineStageFlags) -> ("dstStageMask" ::: PipelineStageFlags) -> ("memoryBarriers" ::: Vector MemoryBarrier) -> ("bufferMemoryBarriers" ::: Vector BufferMemoryBarrier) -> ("imageMemoryBarriers" ::: Vector (SomeStruct ImageMemoryBarrier)) -> io ()
- cmdWaitEventsSafe :: forall io. MonadIO io => CommandBuffer -> ("events" ::: Vector Event) -> ("srcStageMask" ::: PipelineStageFlags) -> ("dstStageMask" ::: PipelineStageFlags) -> ("memoryBarriers" ::: Vector MemoryBarrier) -> ("bufferMemoryBarriers" ::: Vector BufferMemoryBarrier) -> ("imageMemoryBarriers" ::: Vector (SomeStruct ImageMemoryBarrier)) -> io ()
- cmdPipelineBarrier :: forall io. MonadIO io => CommandBuffer -> ("srcStageMask" ::: PipelineStageFlags) -> ("dstStageMask" ::: PipelineStageFlags) -> DependencyFlags -> ("memoryBarriers" ::: Vector MemoryBarrier) -> ("bufferMemoryBarriers" ::: Vector BufferMemoryBarrier) -> ("imageMemoryBarriers" ::: Vector (SomeStruct ImageMemoryBarrier)) -> io ()
- cmdBeginQuery :: forall io. MonadIO io => CommandBuffer -> QueryPool -> ("query" ::: Word32) -> QueryControlFlags -> io ()
- cmdUseQuery :: forall io r. MonadIO io => CommandBuffer -> QueryPool -> Word32 -> QueryControlFlags -> io r -> io r
- cmdEndQuery :: forall io. MonadIO io => CommandBuffer -> QueryPool -> ("query" ::: Word32) -> io ()
- cmdResetQueryPool :: forall io. MonadIO io => CommandBuffer -> QueryPool -> ("firstQuery" ::: Word32) -> ("queryCount" ::: Word32) -> io ()
- cmdWriteTimestamp :: forall io. MonadIO io => CommandBuffer -> PipelineStageFlagBits -> QueryPool -> ("query" ::: Word32) -> io ()
- cmdCopyQueryPoolResults :: forall io. MonadIO io => CommandBuffer -> QueryPool -> ("firstQuery" ::: Word32) -> ("queryCount" ::: Word32) -> ("dstBuffer" ::: Buffer) -> ("dstOffset" ::: DeviceSize) -> ("stride" ::: DeviceSize) -> QueryResultFlags -> io ()
- cmdPushConstants :: forall io. MonadIO io => CommandBuffer -> PipelineLayout -> ShaderStageFlags -> ("offset" ::: Word32) -> ("size" ::: Word32) -> ("values" ::: Ptr ()) -> io ()
- cmdBeginRenderPass :: forall a io. (Extendss RenderPassBeginInfo a, PokeChain a, MonadIO io) => CommandBuffer -> RenderPassBeginInfo a -> SubpassContents -> io ()
- cmdUseRenderPass :: forall a io r. (Extendss RenderPassBeginInfo a, PokeChain a, MonadIO io) => CommandBuffer -> RenderPassBeginInfo a -> SubpassContents -> io r -> io r
- cmdNextSubpass :: forall io. MonadIO io => CommandBuffer -> SubpassContents -> io ()
- cmdEndRenderPass :: forall io. MonadIO io => CommandBuffer -> io ()
- cmdExecuteCommands :: forall io. MonadIO io => CommandBuffer -> ("commandBuffers" ::: Vector CommandBuffer) -> io ()
- data ClearRect = ClearRect {
- rect :: Rect2D
- baseArrayLayer :: Word32
- layerCount :: Word32
- data ImageSubresourceLayers = ImageSubresourceLayers {}
- data BufferCopy = BufferCopy {}
- data ImageCopy = ImageCopy {}
- data ImageBlit = ImageBlit {}
- data BufferImageCopy = BufferImageCopy {}
- data ImageResolve = ImageResolve {}
- data RenderPassBeginInfo (es :: [Type]) = RenderPassBeginInfo {
- next :: Chain es
- renderPass :: RenderPass
- framebuffer :: Framebuffer
- renderArea :: Rect2D
- clearValues :: Vector ClearValue
- data ClearDepthStencilValue = ClearDepthStencilValue {}
- data ClearAttachment = ClearAttachment {}
- data ClearColorValue
- data ClearValue
- newtype IndexType where
- IndexType Int32
- pattern INDEX_TYPE_UINT16 :: IndexType
- pattern INDEX_TYPE_UINT32 :: IndexType
- pattern INDEX_TYPE_UINT8_EXT :: IndexType
- pattern INDEX_TYPE_NONE_KHR :: IndexType
- newtype SubpassContents where
- newtype StencilFaceFlagBits where
- type StencilFaceFlags = StencilFaceFlagBits
Documentation
Arguments
:: forall io. MonadIO io | |
=> CommandBuffer |
|
-> PipelineBindPoint |
|
-> Pipeline |
|
-> io () |
vkCmdBindPipeline - Bind a pipeline object to a command buffer
Description
Once bound, a pipeline binding affects subsequent commands that interact with the given pipeline type in the command buffer until a different pipeline of the same type is bound to the bind point. Commands that do not interact with the given pipeline type must not be affected by the pipeline state.
- The pipeline bound to
PIPELINE_BIND_POINT_COMPUTE
controls the behavior of all dispatching commands. - 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 ofcmdTraceRaysKHR
andcmdTraceRaysIndirectKHR
.
Valid Usage
- If
pipelineBindPoint
isPIPELINE_BIND_POINT_COMPUTE
, theCommandPool
thatcommandBuffer
was allocated from must support compute operations
- If
pipelineBindPoint
isPIPELINE_BIND_POINT_GRAPHICS
, theCommandPool
thatcommandBuffer
was allocated from must support graphics operations - If
pipelineBindPoint
isPIPELINE_BIND_POINT_COMPUTE
,pipeline
must be a compute pipeline - If
pipelineBindPoint
isPIPELINE_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
isFALSE
, andpipeline
is a graphics pipeline created with aPipelineSampleLocationsStateCreateInfoEXT
structure having itssampleLocationsEnable
member set toTRUE
but withoutDYNAMIC_STATE_SAMPLE_LOCATIONS_EXT
enabled then the current render pass instance must have been begun by specifying aRenderPassSampleLocationsBeginInfoEXT
structure whosepPostSubpassSampleLocations
member contains an element with asubpassIndex
matching the current subpass index and thesampleLocationsInfo
member of that element must match thesampleLocationsInfo
specified inPipelineSampleLocationsStateCreateInfoEXT
when the pipeline was created - This command must not be recorded when transform feedback is active
- If
pipelineBindPoint
isPIPELINE_BIND_POINT_RAY_TRACING_KHR
, theCommandPool
thatcommandBuffer
was allocated from must support compute operations - If
pipelineBindPoint
isPIPELINE_BIND_POINT_RAY_TRACING_KHR
, thepipeline
must be a ray tracing pipeline - The
pipeline
must not have been created withPIPELINE_CREATE_LIBRARY_BIT_KHR
set
Valid Usage (Implicit)
commandBuffer
must be a validCommandBuffer
handle
pipelineBindPoint
must be a validPipelineBindPoint
valuepipeline
must be a validPipeline
handlecommandBuffer
must be in the recording state- The
CommandPool
thatcommandBuffer
was allocated from must support graphics, or compute operations - Both of
commandBuffer
, andpipeline
must have been created, allocated, or retrieved from the sameDevice
Host Synchronization
- Host access to
commandBuffer
must be externally synchronized
- Host access to the
CommandPool
thatcommandBuffer
was allocated from must be externally synchronized
Command Properties
'
Command Buffer Levels | Render Pass Scope | Supported Queue Types | Pipeline Type |
---|---|---|---|
Primary Secondary | Both | Graphics Compute |
See Also
Arguments
:: forall io. MonadIO io | |
=> CommandBuffer |
|
-> ("firstViewport" ::: Word32) |
|
-> ("viewports" ::: Vector Viewport) |
|
-> io () |
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 thanPhysicalDeviceLimits
::maxViewports
- The sum of
firstViewport
andviewportCount
must be between1
andPhysicalDeviceLimits
::maxViewports
, inclusive - If the
multiple viewports
feature is not enabled,
firstViewport
must be0
- If the
multiple viewports
feature is not enabled,
viewportCount
must be1
Valid Usage (Implicit)
commandBuffer
must be a validCommandBuffer
handle
pViewports
must be a valid pointer to an array ofviewportCount
validViewport
structurescommandBuffer
must be in the recording state- The
CommandPool
thatcommandBuffer
was allocated from must support graphics operations viewportCount
must be greater than0
Host Synchronization
- Host access to
commandBuffer
must be externally synchronized
- Host access to the
CommandPool
thatcommandBuffer
was allocated from must be externally synchronized
Command Properties
'
Command Buffer Levels | Render Pass Scope | Supported Queue Types | Pipeline Type |
---|---|---|---|
Primary Secondary | Both | Graphics |
See Also
Arguments
:: forall io. MonadIO io | |
=> CommandBuffer |
|
-> ("firstScissor" ::: Word32) |
|
-> ("scissors" ::: Vector Rect2D) |
|
-> io () |
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 thanPhysicalDeviceLimits
::maxViewports
- The sum of
firstScissor
andscissorCount
must be between1
andPhysicalDeviceLimits
::maxViewports
, inclusive - If the
multiple viewports
feature is not enabled,
firstScissor
must be0
- If the
multiple viewports
feature is not enabled,
scissorCount
must be1
- The
x
andy
members ofoffset
member of any element ofpScissors
must be greater than or equal to0
- Evaluation of (
offset.x
+extent.width
) must not cause a signed integer addition overflow for any element ofpScissors
- Evaluation of (
offset.y
+extent.height
) must not cause a signed integer addition overflow for any element ofpScissors
Valid Usage (Implicit)
commandBuffer
must be a validCommandBuffer
handle
pScissors
must be a valid pointer to an array ofscissorCount
Rect2D
structurescommandBuffer
must be in the recording state- The
CommandPool
thatcommandBuffer
was allocated from must support graphics operations scissorCount
must be greater than0
Host Synchronization
- Host access to
commandBuffer
must be externally synchronized
- Host access to the
CommandPool
thatcommandBuffer
was allocated from must be externally synchronized
Command Properties
'
Command Buffer Levels | Render Pass Scope | Supported Queue Types | Pipeline Type |
---|---|---|---|
Primary Secondary | Both | Graphics |
See Also
Arguments
:: forall io. MonadIO io | |
=> CommandBuffer |
|
-> ("lineWidth" ::: Float) |
|
-> io () |
vkCmdSetLineWidth - Set the dynamic line width state
Valid Usage
- If the
wide lines
feature is not enabled,
lineWidth
must be1.0
Valid Usage (Implicit)
commandBuffer
must be a validCommandBuffer
handle
commandBuffer
must be in the recording state- The
CommandPool
thatcommandBuffer
was allocated from must support graphics operations
Host Synchronization
- Host access to
commandBuffer
must be externally synchronized
- Host access to the
CommandPool
thatcommandBuffer
was allocated from must be externally synchronized
Command Properties
'
Command Buffer Levels | Render Pass Scope | Supported Queue Types | Pipeline Type |
---|---|---|---|
Primary Secondary | Both | Graphics |
See Also
Arguments
:: forall io. MonadIO io | |
=> CommandBuffer |
|
-> ("depthBiasConstantFactor" ::: Float) |
|
-> ("depthBiasClamp" ::: Float) |
|
-> ("depthBiasSlopeFactor" ::: Float) |
|
-> io () |
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 z
f 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
Arguments
:: forall io. MonadIO io | |
=> CommandBuffer |
|
-> ("blendConstants" ::: (Float, Float, Float, Float)) |
|
-> io () |
vkCmdSetBlendConstants - Set the values of blend constants
Valid Usage (Implicit)
commandBuffer
must be a validCommandBuffer
handle
commandBuffer
must be in the recording state- The
CommandPool
thatcommandBuffer
was allocated from must support graphics operations
Host Synchronization
- Host access to
commandBuffer
must be externally synchronized
- Host access to the
CommandPool
thatcommandBuffer
was allocated from must be externally synchronized
Command Properties
'
Command Buffer Levels | Render Pass Scope | Supported Queue Types | Pipeline Type |
---|---|---|---|
Primary Secondary | Both | Graphics |
See Also
Arguments
:: forall io. MonadIO io | |
=> CommandBuffer |
|
-> ("minDepthBounds" ::: Float) |
|
-> ("maxDepthBounds" ::: Float) |
|
-> io () |
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 enabledminDepthBounds
must be between0.0
and1.0
, inclusive
- Unless the
VK_EXT_depth_range_unrestricted
extension is enabledmaxDepthBounds
must be between0.0
and1.0
, inclusive
Valid Usage (Implicit)
commandBuffer
must be a validCommandBuffer
handle
commandBuffer
must be in the recording state- The
CommandPool
thatcommandBuffer
was allocated from must support graphics operations
Host Synchronization
- Host access to
commandBuffer
must be externally synchronized
- Host access to the
CommandPool
thatcommandBuffer
was allocated from must be externally synchronized
Command Properties
'
Command Buffer Levels | Render Pass Scope | Supported Queue Types | Pipeline Type |
---|---|---|---|
Primary Secondary | Both | Graphics |
See Also
cmdSetStencilCompareMask Source #
Arguments
:: forall io. MonadIO io | |
=> CommandBuffer |
|
-> ("faceMask" ::: StencilFaceFlags) |
|
-> ("compareMask" ::: Word32) |
|
-> io () |
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 validCommandBuffer
handle
faceMask
must be a valid combination ofStencilFaceFlagBits
valuesfaceMask
must not be0
commandBuffer
must be in the recording state- The
CommandPool
thatcommandBuffer
was allocated from must support graphics operations
Host Synchronization
- Host access to
commandBuffer
must be externally synchronized
- Host access to the
CommandPool
thatcommandBuffer
was allocated from must be externally synchronized
Command Properties
'
Command Buffer Levels | Render Pass Scope | Supported Queue Types | Pipeline Type |
---|---|---|---|
Primary Secondary | Both | Graphics |
See Also
cmdSetStencilWriteMask Source #
Arguments
:: forall io. MonadIO io | |
=> CommandBuffer |
|
-> ("faceMask" ::: StencilFaceFlags) |
|
-> ("writeMask" ::: Word32) |
|
-> io () |
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 validCommandBuffer
handle
faceMask
must be a valid combination ofStencilFaceFlagBits
valuesfaceMask
must not be0
commandBuffer
must be in the recording state- The
CommandPool
thatcommandBuffer
was allocated from must support graphics operations
Host Synchronization
- Host access to
commandBuffer
must be externally synchronized
- Host access to the
CommandPool
thatcommandBuffer
was allocated from must be externally synchronized
Command Properties
'
Command Buffer Levels | Render Pass Scope | Supported Queue Types | Pipeline Type |
---|---|---|---|
Primary Secondary | Both | Graphics |
See Also
cmdSetStencilReference Source #
Arguments
:: forall io. MonadIO io | |
=> CommandBuffer |
|
-> ("faceMask" ::: StencilFaceFlags) |
|
-> ("reference" ::: Word32) |
|
-> io () |
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 validCommandBuffer
handle
faceMask
must be a valid combination ofStencilFaceFlagBits
valuesfaceMask
must not be0
commandBuffer
must be in the recording state- The
CommandPool
thatcommandBuffer
was allocated from must support graphics operations
Host Synchronization
- Host access to
commandBuffer
must be externally synchronized
- Host access to the
CommandPool
thatcommandBuffer
was allocated from must be externally synchronized
Command Properties
'
Command Buffer Levels | Render Pass Scope | Supported Queue Types | Pipeline Type |
---|---|---|---|
Primary Secondary | Both | Graphics |
See Also
cmdBindDescriptorSets Source #
Arguments
:: forall io. MonadIO io | |
=> CommandBuffer |
|
-> PipelineBindPoint |
|
-> PipelineLayout |
|
-> ("firstSet" ::: Word32) |
|
-> ("descriptorSets" ::: Vector DescriptorSet) |
|
-> ("dynamicOffsets" ::: Vector Word32) |
|
-> io () |
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
bound pipeline commands
set by pipelineBindPoint
. Any bindings that were previously applied
via these sets are no longer valid.
Once bound, a descriptor set affects rendering of subsequent commands that interact with the given pipeline type in the command buffer until either a different set is bound to the same set number, or 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
bound pipeline commands
with that pipeline type, 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 aDescriptorSetLayout
that matches (is the same as, or identically defined as) theDescriptorSetLayout
at set n inlayout
, where n is the sum offirstSet
and the index intopDescriptorSets
dynamicOffsetCount
must be equal to the total number of dynamic descriptors inpDescriptorSets
- The sum of
firstSet
anddescriptorSetCount
must be less than or equal toPipelineLayoutCreateInfo
::setLayoutCount
provided whenlayout
was created pipelineBindPoint
must be supported by thecommandBuffer
’s parentCommandPool
’s queue family- Each element of
pDynamicOffsets
which corresponds to a descriptor binding with typeDESCRIPTOR_TYPE_UNIFORM_BUFFER_DYNAMIC
must be a multiple ofPhysicalDeviceLimits
::minUniformBufferOffsetAlignment
- Each element of
pDynamicOffsets
which corresponds to a descriptor binding with typeDESCRIPTOR_TYPE_STORAGE_BUFFER_DYNAMIC
must be a multiple ofPhysicalDeviceLimits
::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 validCommandBuffer
handle
pipelineBindPoint
must be a validPipelineBindPoint
valuelayout
must be a validPipelineLayout
handlepDescriptorSets
must be a valid pointer to an array ofdescriptorSetCount
validDescriptorSet
handles- If
dynamicOffsetCount
is not0
,pDynamicOffsets
must be a valid pointer to an array ofdynamicOffsetCount
uint32_t
values commandBuffer
must be in the recording state- The
CommandPool
thatcommandBuffer
was allocated from must support graphics, or compute operations descriptorSetCount
must be greater than0
- Each of
commandBuffer
,layout
, and the elements ofpDescriptorSets
must have been created, allocated, or retrieved from the sameDevice
Host Synchronization
- Host access to
commandBuffer
must be externally synchronized
- Host access to the
CommandPool
thatcommandBuffer
was allocated from must be externally synchronized
Command Properties
'
Command Buffer Levels | Render Pass Scope | Supported Queue Types | Pipeline Type |
---|---|---|---|
Primary Secondary | Both | Graphics Compute |
See Also
CommandBuffer
,
DescriptorSet
,
PipelineBindPoint
,
PipelineLayout
Arguments
:: forall io. MonadIO io | |
=> CommandBuffer |
|
-> Buffer |
|
-> ("offset" ::: DeviceSize) |
|
-> IndexType |
|
-> io () |
vkCmdBindIndexBuffer - Bind an index buffer to a command buffer
Valid Usage
offset
must be less than the size ofbuffer
- The sum of
offset
and the address of the range ofDeviceMemory
object that is backingbuffer
, must be a multiple of the type indicated byindexType
buffer
must have been created with theBUFFER_USAGE_INDEX_BUFFER_BIT
flag- If
buffer
is non-sparse then it must be bound completely and contiguously to a singleDeviceMemory
object indexType
must not beINDEX_TYPE_NONE_KHR
- If
indexType
isINDEX_TYPE_UINT8_EXT
, the indexTypeUint8 feature must be enabled
Valid Usage (Implicit)
commandBuffer
must be a validCommandBuffer
handle
buffer
must be a validBuffer
handleindexType
must be a validIndexType
valuecommandBuffer
must be in the recording state- The
CommandPool
thatcommandBuffer
was allocated from must support graphics operations - Both of
buffer
, andcommandBuffer
must have been created, allocated, or retrieved from the sameDevice
Host Synchronization
- Host access to
commandBuffer
must be externally synchronized
- Host access to the
CommandPool
thatcommandBuffer
was allocated from must be externally synchronized
Command Properties
'
Command Buffer Levels | Render Pass Scope | Supported Queue Types | Pipeline Type |
---|---|---|---|
Primary Secondary | Both | Graphics |
See Also
Arguments
:: forall io. MonadIO io | |
=> CommandBuffer |
|
-> ("firstBinding" ::: Word32) |
|
-> ("buffers" ::: Vector Buffer) |
|
-> ("offsets" ::: Vector DeviceSize) |
|
-> io () |
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 thanPhysicalDeviceLimits
::maxVertexInputBindings
- The sum of
firstBinding
andbindingCount
must be less than or equal toPhysicalDeviceLimits
::maxVertexInputBindings
- All elements of
pOffsets
must be less than the size of the corresponding element inpBuffers
- All elements of
pBuffers
must have been created with theBUFFER_USAGE_VERTEX_BUFFER_BIT
flag - Each element of
pBuffers
that is non-sparse must be bound completely and contiguously to a singleDeviceMemory
object - If the
nullDescriptor
feature is not enabled, all elements of
pBuffers
must not beNULL_HANDLE
- If an element of
pBuffers
isNULL_HANDLE
, then the corresponding element ofpOffsets
must be zero
Valid Usage (Implicit)
commandBuffer
must be a validCommandBuffer
handle
pBuffers
must be a valid pointer to an array ofbindingCount
valid orNULL_HANDLE
Buffer
handlespOffsets
must be a valid pointer to an array ofbindingCount
DeviceSize
valuescommandBuffer
must be in the recording state- The
CommandPool
thatcommandBuffer
was allocated from must support graphics operations bindingCount
must be greater than0
- Both of
commandBuffer
, and the elements ofpBuffers
that are valid handles of non-ignored parameters must have been created, allocated, or retrieved from the sameDevice
Host Synchronization
- Host access to
commandBuffer
must be externally synchronized
- Host access to the
CommandPool
thatcommandBuffer
was allocated from must be externally synchronized
Command Properties
'
Command Buffer Levels | Render Pass Scope | Supported Queue Types | Pipeline Type |
---|---|---|---|
Primary Secondary | Both | Graphics |
See Also
Arguments
:: forall io. MonadIO io | |
=> CommandBuffer |
|
-> ("vertexCount" ::: Word32) |
|
-> ("instanceCount" ::: Word32) |
|
-> ("firstVertex" ::: Word32) |
|
-> ("firstInstance" ::: Word32) |
|
-> io () |
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
Sampler
created withmagFilter
orminFilter
equal toFILTER_LINEAR
andcompareEnable
equal toFALSE
is used to sample aImageView
as a result of this command, then the image view’s format features must containFORMAT_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 containFORMAT_FEATURE_STORAGE_IMAGE_ATOMIC_BIT
- If a
ImageView
is sampled withFILTER_CUBIC_EXT
as a result of this command, then the image view’s format features must containFORMAT_FEATURE_SAMPLED_IMAGE_FILTER_CUBIC_BIT_EXT
- Any
ImageView
being sampled withFILTER_CUBIC_EXT
as a result of this command must have aImageViewType
and format that supports cubic filtering, as specified byFilterCubicImageViewImageFormatPropertiesEXT
::filterCubic
returned bygetPhysicalDeviceImageFormatProperties2
- Any
ImageView
being sampled withFILTER_CUBIC_EXT
with a reduction mode of eitherSAMPLER_REDUCTION_MODE_MIN
orSAMPLER_REDUCTION_MODE_MAX
as a result of this command must have aImageViewType
and format that supports cubic filtering together with minmax filtering, as specified byFilterCubicImageViewImageFormatPropertiesEXT
::filterCubicMinmax
returned bygetPhysicalDeviceImageFormatProperties2
- Any
Image
created with aImageCreateInfo
::flags
containingIMAGE_CREATE_CORNER_SAMPLED_BIT_NV
sampled as a result of this command must only be sampled using aSamplerAddressMode
ofSAMPLER_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 aPipelineLayout
that is compatible for set n, with thePipelineLayout
used to create the currentPipeline
, 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 aPipelineLayout
that is compatible for push constants, with thePipelineLayout
used to create the currentPipeline
, as described in ??? - Descriptors in each bound descriptor set, specified via
cmdBindDescriptorSets
, must be valid if they are statically used by thePipeline
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 forcommandBuffer
, 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 aSampler
object that uses unnormalized coordinates, that sampler must not be used to sample from anyImage
with aImageView
of the typeIMAGE_VIEW_TYPE_3D
,IMAGE_VIEW_TYPE_CUBE
,IMAGE_VIEW_TYPE_1D_ARRAY
,IMAGE_VIEW_TYPE_2D_ARRAY
orIMAGE_VIEW_TYPE_CUBE_ARRAY
, in any shader stage - If the
Pipeline
object bound to the pipeline bind point used by this command accesses aSampler
object that uses unnormalized coordinates, that sampler must not be used with any of the SPIR-VOpImageSample*
orOpImageSparseSample*
instructions withImplicitLod
,Dref
orProj
in their name, in any shader stage - If the
Pipeline
object bound to the pipeline bind point used by this command accesses aSampler
object that uses unnormalized coordinates, that sampler must not be used with any of the SPIR-VOpImageSample*
orOpImageSparseSample*
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 thePipeline
object bound to the pipeline bind point used by this command must not be a protected resource - If a
ImageView
is accessed usingOpImageWrite
as a result of this command, then theType
of theTexel
operand of that instruction must have at least as many components as the image view’s format. - If a
BufferView
is accessed usingOpImageWrite
as a result of this command, then theType
of theTexel
operand of that instruction must have at least as many components as the image view’s format. - If a
ImageView
with aFormat
that has a 64-bit channel width is accessed as a result of this command, theSampledType
of theOpTypeImage
operand of that instruction must have aWidth
of 64. - If a
ImageView
with aFormat
that has a channel width less than 64-bit is accessed as a result of this command, theSampledType
of theOpTypeImage
operand of that instruction must have aWidth
of 32. - If a
BufferView
with aFormat
that has a 64-bit channel width is accessed as a result of this command, theSampledType
of theOpTypeImage
operand of that instruction must have aWidth
of 64. - If a
BufferView
with aFormat
that has a channel width less than 64-bit is accessed as a result of this command, theSampledType
of theOpTypeImage
operand of that instruction must have aWidth
of 32. - If the
sparseImageInt64Atomics
feature is not enabled,
Image
objects created with theIMAGE_CREATE_SPARSE_RESIDENCY_BIT
flag must not be accessed by atomic instructions through anOpTypeImage
with aSampledType
with aWidth
of 64 by this command. - If the
sparseImageInt64Atomics
feature is not enabled,
Buffer
objects created with theBUFFER_CREATE_SPARSE_RESIDENCY_BIT
flag must not be accessed by atomic instructions through anOpTypeImage
with aSampledType
with aWidth
of 64 by this command. - The current render pass must be
compatible
with the
renderPass
member of theGraphicsPipelineCreateInfo
structure specified when creating thePipeline
bound toPIPELINE_BIND_POINT_GRAPHICS
- The subpass index of the current render pass must be equal to the
subpass
member of theGraphicsPipelineCreateInfo
structure specified when creating thePipeline
bound toPIPELINE_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 toTRUE
and the current subpass has a depth/stencil attachment, then that attachment must have been created with theIMAGE_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 theDYNAMIC_STATE_SCISSOR_WITH_COUNT_EXT
dynamic state enabled, thencmdSetViewportWithCountEXT
must have been called in the current command buffer prior to this draw command, and theviewportCount
parameter ofcmdSetViewportWithCountEXT
must match thePipelineViewportStateCreateInfo
::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 theDYNAMIC_STATE_VIEWPORT_WITH_COUNT_EXT
dynamic state enabled, thencmdSetScissorWithCountEXT
must have been called in the current command buffer prior to this draw command, and thescissorCount
parameter ofcmdSetScissorWithCountEXT
must match thePipelineViewportStateCreateInfo
::viewportCount
of the pipeline - If the bound graphics pipeline state was created with both the
DYNAMIC_STATE_SCISSOR_WITH_COUNT_EXT
andDYNAMIC_STATE_VIEWPORT_WITH_COUNT_EXT
dynamic states enabled then bothcmdSetViewportWithCountEXT
andcmdSetScissorWithCountEXT
must have been called in the current command buffer prior to this draw command, and theviewportCount
parameter ofcmdSetViewportWithCountEXT
must match thescissorCount
parameter ofcmdSetScissorWithCountEXT
- If the bound graphics pipeline state was created with the
DYNAMIC_STATE_VIEWPORT_WITH_COUNT_EXT
dynamic state enabled, but not theDYNAMIC_STATE_VIEWPORT_W_SCALING_NV
dynamic state enabled, then the bound graphics pipeline must have been created withPipelineViewportWScalingStateCreateInfoNV
::viewportCount
greater or equal to theviewportCount
parameter in the last call tocmdSetViewportWithCountEXT
- If the bound graphics pipeline state was created with the
DYNAMIC_STATE_VIEWPORT_WITH_COUNT_EXT
andDYNAMIC_STATE_VIEWPORT_W_SCALING_NV
dynamic states enabled then theviewportCount
parameter in the last call tocmdSetViewportWScalingNV
must be greater than or equal to theviewportCount
parameter in the last call tocmdSetViewportWithCountEXT
- If the bound graphics pipeline state was created with the
DYNAMIC_STATE_VIEWPORT_WITH_COUNT_EXT
dynamic state enabled, but not theDYNAMIC_STATE_VIEWPORT_SHADING_RATE_PALETTE_NV
dynamic state enabled, then the bound graphics pipeline must have been created withPipelineViewportShadingRateImageStateCreateInfoNV
::viewportCount
greater or equal to theviewportCount
parameter in the last call tocmdSetViewportWithCountEXT
- If the bound graphics pipeline state was created with the
DYNAMIC_STATE_VIEWPORT_WITH_COUNT_EXT
andDYNAMIC_STATE_VIEWPORT_SHADING_RATE_PALETTE_NV
dynamic states enabled then theviewportCount
parameter in the last call tocmdSetViewportShadingRatePaletteNV
must be greater than or equal to theviewportCount
parameter in the last call tocmdSetViewportWithCountEXT
- If the bound graphics pipeline state was created with the
DYNAMIC_STATE_VIEWPORT_WITH_COUNT_EXT
dynamic state enabled and an instance ofPipelineViewportSwizzleStateCreateInfoNV
chained fromVkPipelineVieportCreateInfo
, then the bound graphics pipeline must have been created withPipelineViewportSwizzleStateCreateInfoNV
::viewportCount
greater or equal to theviewportCount
parameter in the last call tocmdSetViewportWithCountEXT
- If the bound graphics pipeline state was created with the
DYNAMIC_STATE_VIEWPORT_WITH_COUNT_EXT
dynamic state enabled and an instance ofPipelineViewportExclusiveScissorStateCreateInfoNV
chained fromVkPipelineVieportCreateInfo
, then the bound graphics pipeline must have been created withPipelineViewportExclusiveScissorStateCreateInfoNV
::exclusiveScissorCount
greater or equal to theviewportCount
parameter in the last call tocmdSetViewportWithCountEXT
- If the bound graphics pipeline state was created with the
DYNAMIC_STATE_PRIMITIVE_TOPOLOGY_EXT
dynamic state enabled thencmdSetPrimitiveTopologyEXT
must have been called in the current command buffer prior to this draw command, and theprimitiveTopology
parameter ofcmdSetPrimitiveTopologyEXT
must be of the same topology class as the pipelinePipelineInputAssemblyStateCreateInfo
::topology
state - If the
primitiveFragmentShadingRateWithMultipleViewports
limit is not supported, the bound graphics pipeline was created with
the
DYNAMIC_STATE_VIEWPORT_WITH_COUNT_EXT
dynamic state enabled, and any of the shader stages of the bound graphics pipeline write to thePrimitiveShadingRateKHR
built-in, thencmdSetViewportWithCountEXT
must have been called in the current command buffer prior to this draw command, and theviewportCount
parameter ofcmdSetViewportWithCountEXT
must be1
- If
commandBuffer
is a protected command buffer, any resource written to by thePipeline
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 thePipeline
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 validCommandBuffer
handle
commandBuffer
must be in the recording state- The
CommandPool
thatcommandBuffer
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
thatcommandBuffer
was allocated from must be externally synchronized
Command Properties
'
Command Buffer Levels | Render Pass Scope | Supported Queue Types | Pipeline Type |
---|---|---|---|
Primary Secondary | Inside | Graphics | Graphics |
See Also
Arguments
:: forall io. MonadIO io | |
=> CommandBuffer |
|
-> ("indexCount" ::: Word32) |
|
-> ("instanceCount" ::: Word32) |
|
-> ("firstIndex" ::: Word32) |
|
-> ("vertexOffset" ::: Int32) |
|
-> ("firstInstance" ::: Word32) |
|
-> io () |
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
Sampler
created withmagFilter
orminFilter
equal toFILTER_LINEAR
andcompareEnable
equal toFALSE
is used to sample aImageView
as a result of this command, then the image view’s format features must containFORMAT_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 containFORMAT_FEATURE_STORAGE_IMAGE_ATOMIC_BIT
- If a
ImageView
is sampled withFILTER_CUBIC_EXT
as a result of this command, then the image view’s format features must containFORMAT_FEATURE_SAMPLED_IMAGE_FILTER_CUBIC_BIT_EXT
- Any
ImageView
being sampled withFILTER_CUBIC_EXT
as a result of this command must have aImageViewType
and format that supports cubic filtering, as specified byFilterCubicImageViewImageFormatPropertiesEXT
::filterCubic
returned bygetPhysicalDeviceImageFormatProperties2
- Any
ImageView
being sampled withFILTER_CUBIC_EXT
with a reduction mode of eitherSAMPLER_REDUCTION_MODE_MIN
orSAMPLER_REDUCTION_MODE_MAX
as a result of this command must have aImageViewType
and format that supports cubic filtering together with minmax filtering, as specified byFilterCubicImageViewImageFormatPropertiesEXT
::filterCubicMinmax
returned bygetPhysicalDeviceImageFormatProperties2
- Any
Image
created with aImageCreateInfo
::flags
containingIMAGE_CREATE_CORNER_SAMPLED_BIT_NV
sampled as a result of this command must only be sampled using aSamplerAddressMode
ofSAMPLER_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 aPipelineLayout
that is compatible for set n, with thePipelineLayout
used to create the currentPipeline
, 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 aPipelineLayout
that is compatible for push constants, with thePipelineLayout
used to create the currentPipeline
, as described in ??? - Descriptors in each bound descriptor set, specified via
cmdBindDescriptorSets
, must be valid if they are statically used by thePipeline
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 forcommandBuffer
, 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 aSampler
object that uses unnormalized coordinates, that sampler must not be used to sample from anyImage
with aImageView
of the typeIMAGE_VIEW_TYPE_3D
,IMAGE_VIEW_TYPE_CUBE
,IMAGE_VIEW_TYPE_1D_ARRAY
,IMAGE_VIEW_TYPE_2D_ARRAY
orIMAGE_VIEW_TYPE_CUBE_ARRAY
, in any shader stage - If the
Pipeline
object bound to the pipeline bind point used by this command accesses aSampler
object that uses unnormalized coordinates, that sampler must not be used with any of the SPIR-VOpImageSample*
orOpImageSparseSample*
instructions withImplicitLod
,Dref
orProj
in their name, in any shader stage - If the
Pipeline
object bound to the pipeline bind point used by this command accesses aSampler
object that uses unnormalized coordinates, that sampler must not be used with any of the SPIR-VOpImageSample*
orOpImageSparseSample*
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 thePipeline
object bound to the pipeline bind point used by this command must not be a protected resource - If a
ImageView
is accessed usingOpImageWrite
as a result of this command, then theType
of theTexel
operand of that instruction must have at least as many components as the image view’s format. - If a
BufferView
is accessed usingOpImageWrite
as a result of this command, then theType
of theTexel
operand of that instruction must have at least as many components as the image view’s format. - If a
ImageView
with aFormat
that has a 64-bit channel width is accessed as a result of this command, theSampledType
of theOpTypeImage
operand of that instruction must have aWidth
of 64. - If a
ImageView
with aFormat
that has a channel width less than 64-bit is accessed as a result of this command, theSampledType
of theOpTypeImage
operand of that instruction must have aWidth
of 32. - If a
BufferView
with aFormat
that has a 64-bit channel width is accessed as a result of this command, theSampledType
of theOpTypeImage
operand of that instruction must have aWidth
of 64. - If a
BufferView
with aFormat
that has a channel width less than 64-bit is accessed as a result of this command, theSampledType
of theOpTypeImage
operand of that instruction must have aWidth
of 32. - If the
sparseImageInt64Atomics
feature is not enabled,
Image
objects created with theIMAGE_CREATE_SPARSE_RESIDENCY_BIT
flag must not be accessed by atomic instructions through anOpTypeImage
with aSampledType
with aWidth
of 64 by this command. - If the
sparseImageInt64Atomics
feature is not enabled,
Buffer
objects created with theBUFFER_CREATE_SPARSE_RESIDENCY_BIT
flag must not be accessed by atomic instructions through anOpTypeImage
with aSampledType
with aWidth
of 64 by this command. - The current render pass must be
compatible
with the
renderPass
member of theGraphicsPipelineCreateInfo
structure specified when creating thePipeline
bound toPIPELINE_BIND_POINT_GRAPHICS
- The subpass index of the current render pass must be equal to the
subpass
member of theGraphicsPipelineCreateInfo
structure specified when creating thePipeline
bound toPIPELINE_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 toTRUE
and the current subpass has a depth/stencil attachment, then that attachment must have been created with theIMAGE_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 theDYNAMIC_STATE_SCISSOR_WITH_COUNT_EXT
dynamic state enabled, thencmdSetViewportWithCountEXT
must have been called in the current command buffer prior to this draw command, and theviewportCount
parameter ofcmdSetViewportWithCountEXT
must match thePipelineViewportStateCreateInfo
::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 theDYNAMIC_STATE_VIEWPORT_WITH_COUNT_EXT
dynamic state enabled, thencmdSetScissorWithCountEXT
must have been called in the current command buffer prior to this draw command, and thescissorCount
parameter ofcmdSetScissorWithCountEXT
must match thePipelineViewportStateCreateInfo
::viewportCount
of the pipeline - If the bound graphics pipeline state was created with both the
DYNAMIC_STATE_SCISSOR_WITH_COUNT_EXT
andDYNAMIC_STATE_VIEWPORT_WITH_COUNT_EXT
dynamic states enabled then bothcmdSetViewportWithCountEXT
andcmdSetScissorWithCountEXT
must have been called in the current command buffer prior to this draw command, and theviewportCount
parameter ofcmdSetViewportWithCountEXT
must match thescissorCount
parameter ofcmdSetScissorWithCountEXT
- If the bound graphics pipeline state was created with the
DYNAMIC_STATE_VIEWPORT_WITH_COUNT_EXT
dynamic state enabled, but not theDYNAMIC_STATE_VIEWPORT_W_SCALING_NV
dynamic state enabled, then the bound graphics pipeline must have been created withPipelineViewportWScalingStateCreateInfoNV
::viewportCount
greater or equal to theviewportCount
parameter in the last call tocmdSetViewportWithCountEXT
- If the bound graphics pipeline state was created with the
DYNAMIC_STATE_VIEWPORT_WITH_COUNT_EXT
andDYNAMIC_STATE_VIEWPORT_W_SCALING_NV
dynamic states enabled then theviewportCount
parameter in the last call tocmdSetViewportWScalingNV
must be greater than or equal to theviewportCount
parameter in the last call tocmdSetViewportWithCountEXT
- If the bound graphics pipeline state was created with the
DYNAMIC_STATE_VIEWPORT_WITH_COUNT_EXT
dynamic state enabled, but not theDYNAMIC_STATE_VIEWPORT_SHADING_RATE_PALETTE_NV
dynamic state enabled, then the bound graphics pipeline must have been created withPipelineViewportShadingRateImageStateCreateInfoNV
::viewportCount
greater or equal to theviewportCount
parameter in the last call tocmdSetViewportWithCountEXT
- If the bound graphics pipeline state was created with the
DYNAMIC_STATE_VIEWPORT_WITH_COUNT_EXT
andDYNAMIC_STATE_VIEWPORT_SHADING_RATE_PALETTE_NV
dynamic states enabled then theviewportCount
parameter in the last call tocmdSetViewportShadingRatePaletteNV
must be greater than or equal to theviewportCount
parameter in the last call tocmdSetViewportWithCountEXT
- If the bound graphics pipeline state was created with the
DYNAMIC_STATE_VIEWPORT_WITH_COUNT_EXT
dynamic state enabled and an instance ofPipelineViewportSwizzleStateCreateInfoNV
chained fromVkPipelineVieportCreateInfo
, then the bound graphics pipeline must have been created withPipelineViewportSwizzleStateCreateInfoNV
::viewportCount
greater or equal to theviewportCount
parameter in the last call tocmdSetViewportWithCountEXT
- If the bound graphics pipeline state was created with the
DYNAMIC_STATE_VIEWPORT_WITH_COUNT_EXT
dynamic state enabled and an instance ofPipelineViewportExclusiveScissorStateCreateInfoNV
chained fromVkPipelineVieportCreateInfo
, then the bound graphics pipeline must have been created withPipelineViewportExclusiveScissorStateCreateInfoNV
::exclusiveScissorCount
greater or equal to theviewportCount
parameter in the last call tocmdSetViewportWithCountEXT
- If the bound graphics pipeline state was created with the
DYNAMIC_STATE_PRIMITIVE_TOPOLOGY_EXT
dynamic state enabled thencmdSetPrimitiveTopologyEXT
must have been called in the current command buffer prior to this draw command, and theprimitiveTopology
parameter ofcmdSetPrimitiveTopologyEXT
must be of the same topology class as the pipelinePipelineInputAssemblyStateCreateInfo
::topology
state - If the
primitiveFragmentShadingRateWithMultipleViewports
limit is not supported, the bound graphics pipeline was created with
the
DYNAMIC_STATE_VIEWPORT_WITH_COUNT_EXT
dynamic state enabled, and any of the shader stages of the bound graphics pipeline write to thePrimitiveShadingRateKHR
built-in, thencmdSetViewportWithCountEXT
must have been called in the current command buffer prior to this draw command, and theviewportCount
parameter ofcmdSetViewportWithCountEXT
must be1
- If
commandBuffer
is a protected command buffer, any resource written to by thePipeline
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 thePipeline
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, withindexSize
being based on the type specified byindexType
, where the index buffer,indexType
, andoffset
are specified viacmdBindIndexBuffer
Valid Usage (Implicit)
commandBuffer
must be a validCommandBuffer
handle
commandBuffer
must be in the recording state- The
CommandPool
thatcommandBuffer
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
thatcommandBuffer
was allocated from must be externally synchronized
Command Properties
'
Command Buffer Levels | Render Pass Scope | Supported Queue Types | Pipeline Type |
---|---|---|---|
Primary Secondary | Inside | Graphics | Graphics |
See Also
Arguments
:: forall io. MonadIO io | |
=> CommandBuffer |
|
-> Buffer |
|
-> ("offset" ::: DeviceSize) |
|
-> ("drawCount" ::: Word32) |
|
-> ("stride" ::: Word32) |
|
-> io () |
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
Sampler
created withmagFilter
orminFilter
equal toFILTER_LINEAR
andcompareEnable
equal toFALSE
is used to sample aImageView
as a result of this command, then the image view’s format features must containFORMAT_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 containFORMAT_FEATURE_STORAGE_IMAGE_ATOMIC_BIT
- If a
ImageView
is sampled withFILTER_CUBIC_EXT
as a result of this command, then the image view’s format features must containFORMAT_FEATURE_SAMPLED_IMAGE_FILTER_CUBIC_BIT_EXT
- Any
ImageView
being sampled withFILTER_CUBIC_EXT
as a result of this command must have aImageViewType
and format that supports cubic filtering, as specified byFilterCubicImageViewImageFormatPropertiesEXT
::filterCubic
returned bygetPhysicalDeviceImageFormatProperties2
- Any
ImageView
being sampled withFILTER_CUBIC_EXT
with a reduction mode of eitherSAMPLER_REDUCTION_MODE_MIN
orSAMPLER_REDUCTION_MODE_MAX
as a result of this command must have aImageViewType
and format that supports cubic filtering together with minmax filtering, as specified byFilterCubicImageViewImageFormatPropertiesEXT
::filterCubicMinmax
returned bygetPhysicalDeviceImageFormatProperties2
- Any
Image
created with aImageCreateInfo
::flags
containingIMAGE_CREATE_CORNER_SAMPLED_BIT_NV
sampled as a result of this command must only be sampled using aSamplerAddressMode
ofSAMPLER_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 aPipelineLayout
that is compatible for set n, with thePipelineLayout
used to create the currentPipeline
, 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 aPipelineLayout
that is compatible for push constants, with thePipelineLayout
used to create the currentPipeline
, as described in ??? - Descriptors in each bound descriptor set, specified via
cmdBindDescriptorSets
, must be valid if they are statically used by thePipeline
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 forcommandBuffer
, 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 aSampler
object that uses unnormalized coordinates, that sampler must not be used to sample from anyImage
with aImageView
of the typeIMAGE_VIEW_TYPE_3D
,IMAGE_VIEW_TYPE_CUBE
,IMAGE_VIEW_TYPE_1D_ARRAY
,IMAGE_VIEW_TYPE_2D_ARRAY
orIMAGE_VIEW_TYPE_CUBE_ARRAY
, in any shader stage - If the
Pipeline
object bound to the pipeline bind point used by this command accesses aSampler
object that uses unnormalized coordinates, that sampler must not be used with any of the SPIR-VOpImageSample*
orOpImageSparseSample*
instructions withImplicitLod
,Dref
orProj
in their name, in any shader stage - If the
Pipeline
object bound to the pipeline bind point used by this command accesses aSampler
object that uses unnormalized coordinates, that sampler must not be used with any of the SPIR-VOpImageSample*
orOpImageSparseSample*
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 thePipeline
object bound to the pipeline bind point used by this command must not be a protected resource - If a
ImageView
is accessed usingOpImageWrite
as a result of this command, then theType
of theTexel
operand of that instruction must have at least as many components as the image view’s format. - If a
BufferView
is accessed usingOpImageWrite
as a result of this command, then theType
of theTexel
operand of that instruction must have at least as many components as the image view’s format. - If a
ImageView
with aFormat
that has a 64-bit channel width is accessed as a result of this command, theSampledType
of theOpTypeImage
operand of that instruction must have aWidth
of 64. - If a
ImageView
with aFormat
that has a channel width less than 64-bit is accessed as a result of this command, theSampledType
of theOpTypeImage
operand of that instruction must have aWidth
of 32. - If a
BufferView
with aFormat
that has a 64-bit channel width is accessed as a result of this command, theSampledType
of theOpTypeImage
operand of that instruction must have aWidth
of 64. - If a
BufferView
with aFormat
that has a channel width less than 64-bit is accessed as a result of this command, theSampledType
of theOpTypeImage
operand of that instruction must have aWidth
of 32. - If the
sparseImageInt64Atomics
feature is not enabled,
Image
objects created with theIMAGE_CREATE_SPARSE_RESIDENCY_BIT
flag must not be accessed by atomic instructions through anOpTypeImage
with aSampledType
with aWidth
of 64 by this command. - If the
sparseImageInt64Atomics
feature is not enabled,
Buffer
objects created with theBUFFER_CREATE_SPARSE_RESIDENCY_BIT
flag must not be accessed by atomic instructions through anOpTypeImage
with aSampledType
with aWidth
of 64 by this command. - The current render pass must be
compatible
with the
renderPass
member of theGraphicsPipelineCreateInfo
structure specified when creating thePipeline
bound toPIPELINE_BIND_POINT_GRAPHICS
- The subpass index of the current render pass must be equal to the
subpass
member of theGraphicsPipelineCreateInfo
structure specified when creating thePipeline
bound toPIPELINE_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 toTRUE
and the current subpass has a depth/stencil attachment, then that attachment must have been created with theIMAGE_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 theDYNAMIC_STATE_SCISSOR_WITH_COUNT_EXT
dynamic state enabled, thencmdSetViewportWithCountEXT
must have been called in the current command buffer prior to this draw command, and theviewportCount
parameter ofcmdSetViewportWithCountEXT
must match thePipelineViewportStateCreateInfo
::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 theDYNAMIC_STATE_VIEWPORT_WITH_COUNT_EXT
dynamic state enabled, thencmdSetScissorWithCountEXT
must have been called in the current command buffer prior to this draw command, and thescissorCount
parameter ofcmdSetScissorWithCountEXT
must match thePipelineViewportStateCreateInfo
::viewportCount
of the pipeline - If the bound graphics pipeline state was created with both the
DYNAMIC_STATE_SCISSOR_WITH_COUNT_EXT
andDYNAMIC_STATE_VIEWPORT_WITH_COUNT_EXT
dynamic states enabled then bothcmdSetViewportWithCountEXT
andcmdSetScissorWithCountEXT
must have been called in the current command buffer prior to this draw command, and theviewportCount
parameter ofcmdSetViewportWithCountEXT
must match thescissorCount
parameter ofcmdSetScissorWithCountEXT
- If the bound graphics pipeline state was created with the
DYNAMIC_STATE_VIEWPORT_WITH_COUNT_EXT
dynamic state enabled, but not theDYNAMIC_STATE_VIEWPORT_W_SCALING_NV
dynamic state enabled, then the bound graphics pipeline must have been created withPipelineViewportWScalingStateCreateInfoNV
::viewportCount
greater or equal to theviewportCount
parameter in the last call tocmdSetViewportWithCountEXT
- If the bound graphics pipeline state was created with the
DYNAMIC_STATE_VIEWPORT_WITH_COUNT_EXT
andDYNAMIC_STATE_VIEWPORT_W_SCALING_NV
dynamic states enabled then theviewportCount
parameter in the last call tocmdSetViewportWScalingNV
must be greater than or equal to theviewportCount
parameter in the last call tocmdSetViewportWithCountEXT
- If the bound graphics pipeline state was created with the
DYNAMIC_STATE_VIEWPORT_WITH_COUNT_EXT
dynamic state enabled, but not theDYNAMIC_STATE_VIEWPORT_SHADING_RATE_PALETTE_NV
dynamic state enabled, then the bound graphics pipeline must have been created withPipelineViewportShadingRateImageStateCreateInfoNV
::viewportCount
greater or equal to theviewportCount
parameter in the last call tocmdSetViewportWithCountEXT
- If the bound graphics pipeline state was created with the
DYNAMIC_STATE_VIEWPORT_WITH_COUNT_EXT
andDYNAMIC_STATE_VIEWPORT_SHADING_RATE_PALETTE_NV
dynamic states enabled then theviewportCount
parameter in the last call tocmdSetViewportShadingRatePaletteNV
must be greater than or equal to theviewportCount
parameter in the last call tocmdSetViewportWithCountEXT
- If the bound graphics pipeline state was created with the
DYNAMIC_STATE_VIEWPORT_WITH_COUNT_EXT
dynamic state enabled and an instance ofPipelineViewportSwizzleStateCreateInfoNV
chained fromVkPipelineVieportCreateInfo
, then the bound graphics pipeline must have been created withPipelineViewportSwizzleStateCreateInfoNV
::viewportCount
greater or equal to theviewportCount
parameter in the last call tocmdSetViewportWithCountEXT
- If the bound graphics pipeline state was created with the
DYNAMIC_STATE_VIEWPORT_WITH_COUNT_EXT
dynamic state enabled and an instance ofPipelineViewportExclusiveScissorStateCreateInfoNV
chained fromVkPipelineVieportCreateInfo
, then the bound graphics pipeline must have been created withPipelineViewportExclusiveScissorStateCreateInfoNV
::exclusiveScissorCount
greater or equal to theviewportCount
parameter in the last call tocmdSetViewportWithCountEXT
- If the bound graphics pipeline state was created with the
DYNAMIC_STATE_PRIMITIVE_TOPOLOGY_EXT
dynamic state enabled thencmdSetPrimitiveTopologyEXT
must have been called in the current command buffer prior to this draw command, and theprimitiveTopology
parameter ofcmdSetPrimitiveTopologyEXT
must be of the same topology class as the pipelinePipelineInputAssemblyStateCreateInfo
::topology
state - If the
primitiveFragmentShadingRateWithMultipleViewports
limit is not supported, the bound graphics pipeline was created with
the
DYNAMIC_STATE_VIEWPORT_WITH_COUNT_EXT
dynamic state enabled, and any of the shader stages of the bound graphics pipeline write to thePrimitiveShadingRateKHR
built-in, thencmdSetViewportWithCountEXT
must have been called in the current command buffer prior to this draw command, and theviewportCount
parameter ofcmdSetViewportWithCountEXT
must be1
- 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 singleDeviceMemory
object buffer
must have been created with theBUFFER_USAGE_INDIRECT_BUFFER_BIT
bit setoffset
must be a multiple of4
commandBuffer
must not be a protected command buffer- If the
multi-draw indirect
feature is not enabled,
drawCount
must be0
or1
drawCount
must be less than or equal toPhysicalDeviceLimits
::maxDrawIndirectCount
- If the
drawIndirectFirstInstance
feature is not enabled, all the
firstInstance
members of theDrawIndirectCommand
structures accessed by this command must be0
- If
drawCount
is greater than1
,stride
must be a multiple of4
and must be greater than or equal tosizeof
(DrawIndirectCommand
) - If
drawCount
is equal to1
, (offset
+sizeof
(DrawIndirectCommand
)) must be less than or equal to the size ofbuffer
- If
drawCount
is greater than1
, (stride
× (drawCount
- 1) +offset
+sizeof
(DrawIndirectCommand
)) must be less than or equal to the size ofbuffer
Valid Usage (Implicit)
commandBuffer
must be a validCommandBuffer
handle
buffer
must be a validBuffer
handlecommandBuffer
must be in the recording state- The
CommandPool
thatcommandBuffer
was allocated from must support graphics operations - This command must only be called inside of a render pass instance
- Both of
buffer
, andcommandBuffer
must have been created, allocated, or retrieved from the sameDevice
Host Synchronization
- Host access to
commandBuffer
must be externally synchronized
- Host access to the
CommandPool
thatcommandBuffer
was allocated from must be externally synchronized
Command Properties
'
Command Buffer Levels | Render Pass Scope | Supported Queue Types | Pipeline Type |
---|---|---|---|
Primary Secondary | Inside | Graphics | Graphics |
See Also
cmdDrawIndexedIndirect Source #
Arguments
:: forall io. MonadIO io | |
=> CommandBuffer |
|
-> Buffer |
|
-> ("offset" ::: DeviceSize) |
|
-> ("drawCount" ::: Word32) |
|
-> ("stride" ::: Word32) |
|
-> io () |
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
Sampler
created withmagFilter
orminFilter
equal toFILTER_LINEAR
andcompareEnable
equal toFALSE
is used to sample aImageView
as a result of this command, then the image view’s format features must containFORMAT_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 containFORMAT_FEATURE_STORAGE_IMAGE_ATOMIC_BIT
- If a
ImageView
is sampled withFILTER_CUBIC_EXT
as a result of this command, then the image view’s format features must containFORMAT_FEATURE_SAMPLED_IMAGE_FILTER_CUBIC_BIT_EXT
- Any
ImageView
being sampled withFILTER_CUBIC_EXT
as a result of this command must have aImageViewType
and format that supports cubic filtering, as specified byFilterCubicImageViewImageFormatPropertiesEXT
::filterCubic
returned bygetPhysicalDeviceImageFormatProperties2
- Any
ImageView
being sampled withFILTER_CUBIC_EXT
with a reduction mode of eitherSAMPLER_REDUCTION_MODE_MIN
orSAMPLER_REDUCTION_MODE_MAX
as a result of this command must have aImageViewType
and format that supports cubic filtering together with minmax filtering, as specified byFilterCubicImageViewImageFormatPropertiesEXT
::filterCubicMinmax
returned bygetPhysicalDeviceImageFormatProperties2
- Any
Image
created with aImageCreateInfo
::flags
containingIMAGE_CREATE_CORNER_SAMPLED_BIT_NV
sampled as a result of this command must only be sampled using aSamplerAddressMode
ofSAMPLER_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 aPipelineLayout
that is compatible for set n, with thePipelineLayout
used to create the currentPipeline
, 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 aPipelineLayout
that is compatible for push constants, with thePipelineLayout
used to create the currentPipeline
, as described in ??? - Descriptors in each bound descriptor set, specified via
cmdBindDescriptorSets
, must be valid if they are statically used by thePipeline
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 forcommandBuffer
, 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 aSampler
object that uses unnormalized coordinates, that sampler must not be used to sample from anyImage
with aImageView
of the typeIMAGE_VIEW_TYPE_3D
,IMAGE_VIEW_TYPE_CUBE
,IMAGE_VIEW_TYPE_1D_ARRAY
,IMAGE_VIEW_TYPE_2D_ARRAY
orIMAGE_VIEW_TYPE_CUBE_ARRAY
, in any shader stage - If the
Pipeline
object bound to the pipeline bind point used by this command accesses aSampler
object that uses unnormalized coordinates, that sampler must not be used with any of the SPIR-VOpImageSample*
orOpImageSparseSample*
instructions withImplicitLod
,Dref
orProj
in their name, in any shader stage - If the
Pipeline
object bound to the pipeline bind point used by this command accesses aSampler
object that uses unnormalized coordinates, that sampler must not be used with any of the SPIR-VOpImageSample*
orOpImageSparseSample*
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 thePipeline
object bound to the pipeline bind point used by this command must not be a protected resource - If a
ImageView
is accessed usingOpImageWrite
as a result of this command, then theType
of theTexel
operand of that instruction must have at least as many components as the image view’s format. - If a
BufferView
is accessed usingOpImageWrite
as a result of this command, then theType
of theTexel
operand of that instruction must have at least as many components as the image view’s format. - If a
ImageView
with aFormat
that has a 64-bit channel width is accessed as a result of this command, theSampledType
of theOpTypeImage
operand of that instruction must have aWidth
of 64. - If a
ImageView
with aFormat
that has a channel width less than 64-bit is accessed as a result of this command, theSampledType
of theOpTypeImage
operand of that instruction must have aWidth
of 32. - If a
BufferView
with aFormat
that has a 64-bit channel width is accessed as a result of this command, theSampledType
of theOpTypeImage
operand of that instruction must have aWidth
of 64. - If a
BufferView
with aFormat
that has a channel width less than 64-bit is accessed as a result of this command, theSampledType
of theOpTypeImage
operand of that instruction must have aWidth
of 32. - If the
sparseImageInt64Atomics
feature is not enabled,
Image
objects created with theIMAGE_CREATE_SPARSE_RESIDENCY_BIT
flag must not be accessed by atomic instructions through anOpTypeImage
with aSampledType
with aWidth
of 64 by this command. - If the
sparseImageInt64Atomics
feature is not enabled,
Buffer
objects created with theBUFFER_CREATE_SPARSE_RESIDENCY_BIT
flag must not be accessed by atomic instructions through anOpTypeImage
with aSampledType
with aWidth
of 64 by this command. - The current render pass must be
compatible
with the
renderPass
member of theGraphicsPipelineCreateInfo
structure specified when creating thePipeline
bound toPIPELINE_BIND_POINT_GRAPHICS
- The subpass index of the current render pass must be equal to the
subpass
member of theGraphicsPipelineCreateInfo
structure specified when creating thePipeline
bound toPIPELINE_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 toTRUE
and the current subpass has a depth/stencil attachment, then that attachment must have been created with theIMAGE_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 theDYNAMIC_STATE_SCISSOR_WITH_COUNT_EXT
dynamic state enabled, thencmdSetViewportWithCountEXT
must have been called in the current command buffer prior to this draw command, and theviewportCount
parameter ofcmdSetViewportWithCountEXT
must match thePipelineViewportStateCreateInfo
::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 theDYNAMIC_STATE_VIEWPORT_WITH_COUNT_EXT
dynamic state enabled, thencmdSetScissorWithCountEXT
must have been called in the current command buffer prior to this draw command, and thescissorCount
parameter ofcmdSetScissorWithCountEXT
must match thePipelineViewportStateCreateInfo
::viewportCount
of the pipeline - If the bound graphics pipeline state was created with both the
DYNAMIC_STATE_SCISSOR_WITH_COUNT_EXT
andDYNAMIC_STATE_VIEWPORT_WITH_COUNT_EXT
dynamic states enabled then bothcmdSetViewportWithCountEXT
andcmdSetScissorWithCountEXT
must have been called in the current command buffer prior to this draw command, and theviewportCount
parameter ofcmdSetViewportWithCountEXT
must match thescissorCount
parameter ofcmdSetScissorWithCountEXT
- If the bound graphics pipeline state was created with the
DYNAMIC_STATE_VIEWPORT_WITH_COUNT_EXT
dynamic state enabled, but not theDYNAMIC_STATE_VIEWPORT_W_SCALING_NV
dynamic state enabled, then the bound graphics pipeline must have been created withPipelineViewportWScalingStateCreateInfoNV
::viewportCount
greater or equal to theviewportCount
parameter in the last call tocmdSetViewportWithCountEXT
- If the bound graphics pipeline state was created with the
DYNAMIC_STATE_VIEWPORT_WITH_COUNT_EXT
andDYNAMIC_STATE_VIEWPORT_W_SCALING_NV
dynamic states enabled then theviewportCount
parameter in the last call tocmdSetViewportWScalingNV
must be greater than or equal to theviewportCount
parameter in the last call tocmdSetViewportWithCountEXT
- If the bound graphics pipeline state was created with the
DYNAMIC_STATE_VIEWPORT_WITH_COUNT_EXT
dynamic state enabled, but not theDYNAMIC_STATE_VIEWPORT_SHADING_RATE_PALETTE_NV
dynamic state enabled, then the bound graphics pipeline must have been created withPipelineViewportShadingRateImageStateCreateInfoNV
::viewportCount
greater or equal to theviewportCount
parameter in the last call tocmdSetViewportWithCountEXT
- If the bound graphics pipeline state was created with the
DYNAMIC_STATE_VIEWPORT_WITH_COUNT_EXT
andDYNAMIC_STATE_VIEWPORT_SHADING_RATE_PALETTE_NV
dynamic states enabled then theviewportCount
parameter in the last call tocmdSetViewportShadingRatePaletteNV
must be greater than or equal to theviewportCount
parameter in the last call tocmdSetViewportWithCountEXT
- If the bound graphics pipeline state was created with the
DYNAMIC_STATE_VIEWPORT_WITH_COUNT_EXT
dynamic state enabled and an instance ofPipelineViewportSwizzleStateCreateInfoNV
chained fromVkPipelineVieportCreateInfo
, then the bound graphics pipeline must have been created withPipelineViewportSwizzleStateCreateInfoNV
::viewportCount
greater or equal to theviewportCount
parameter in the last call tocmdSetViewportWithCountEXT
- If the bound graphics pipeline state was created with the
DYNAMIC_STATE_VIEWPORT_WITH_COUNT_EXT
dynamic state enabled and an instance ofPipelineViewportExclusiveScissorStateCreateInfoNV
chained fromVkPipelineVieportCreateInfo
, then the bound graphics pipeline must have been created withPipelineViewportExclusiveScissorStateCreateInfoNV
::exclusiveScissorCount
greater or equal to theviewportCount
parameter in the last call tocmdSetViewportWithCountEXT
- If the bound graphics pipeline state was created with the
DYNAMIC_STATE_PRIMITIVE_TOPOLOGY_EXT
dynamic state enabled thencmdSetPrimitiveTopologyEXT
must have been called in the current command buffer prior to this draw command, and theprimitiveTopology
parameter ofcmdSetPrimitiveTopologyEXT
must be of the same topology class as the pipelinePipelineInputAssemblyStateCreateInfo
::topology
state - If the
primitiveFragmentShadingRateWithMultipleViewports
limit is not supported, the bound graphics pipeline was created with
the
DYNAMIC_STATE_VIEWPORT_WITH_COUNT_EXT
dynamic state enabled, and any of the shader stages of the bound graphics pipeline write to thePrimitiveShadingRateKHR
built-in, thencmdSetViewportWithCountEXT
must have been called in the current command buffer prior to this draw command, and theviewportCount
parameter ofcmdSetViewportWithCountEXT
must be1
- 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 singleDeviceMemory
object buffer
must have been created with theBUFFER_USAGE_INDIRECT_BUFFER_BIT
bit setoffset
must be a multiple of4
commandBuffer
must not be a protected command buffer- If the
multi-draw indirect
feature is not enabled,
drawCount
must be0
or1
drawCount
must be less than or equal toPhysicalDeviceLimits
::maxDrawIndirectCount
- If
drawCount
is greater than1
,stride
must be a multiple of4
and must be greater than or equal tosizeof
(DrawIndexedIndirectCommand
) - If the
drawIndirectFirstInstance
feature is not enabled, all the
firstInstance
members of theDrawIndexedIndirectCommand
structures accessed by this command must be0
- If
drawCount
is equal to1
, (offset
+sizeof
(DrawIndexedIndirectCommand
)) must be less than or equal to the size ofbuffer
- If
drawCount
is greater than1
, (stride
× (drawCount
- 1) +offset
+sizeof
(DrawIndexedIndirectCommand
)) must be less than or equal to the size ofbuffer
Valid Usage (Implicit)
commandBuffer
must be a validCommandBuffer
handle
buffer
must be a validBuffer
handlecommandBuffer
must be in the recording state- The
CommandPool
thatcommandBuffer
was allocated from must support graphics operations - This command must only be called inside of a render pass instance
- Both of
buffer
, andcommandBuffer
must have been created, allocated, or retrieved from the sameDevice
Host Synchronization
- Host access to
commandBuffer
must be externally synchronized
- Host access to the
CommandPool
thatcommandBuffer
was allocated from must be externally synchronized
Command Properties
'
Command Buffer Levels | Render Pass Scope | Supported Queue Types | Pipeline Type |
---|---|---|---|
Primary Secondary | Inside | Graphics | Graphics |
See Also
Arguments
:: forall io. MonadIO io | |
=> CommandBuffer |
|
-> ("groupCountX" ::: Word32) |
|
-> ("groupCountY" ::: Word32) |
|
-> ("groupCountZ" ::: Word32) |
|
-> io () |
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
Sampler
created withmagFilter
orminFilter
equal toFILTER_LINEAR
andcompareEnable
equal toFALSE
is used to sample aImageView
as a result of this command, then the image view’s format features must containFORMAT_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 containFORMAT_FEATURE_STORAGE_IMAGE_ATOMIC_BIT
- If a
ImageView
is sampled withFILTER_CUBIC_EXT
as a result of this command, then the image view’s format features must containFORMAT_FEATURE_SAMPLED_IMAGE_FILTER_CUBIC_BIT_EXT
- Any
ImageView
being sampled withFILTER_CUBIC_EXT
as a result of this command must have aImageViewType
and format that supports cubic filtering, as specified byFilterCubicImageViewImageFormatPropertiesEXT
::filterCubic
returned bygetPhysicalDeviceImageFormatProperties2
- Any
ImageView
being sampled withFILTER_CUBIC_EXT
with a reduction mode of eitherSAMPLER_REDUCTION_MODE_MIN
orSAMPLER_REDUCTION_MODE_MAX
as a result of this command must have aImageViewType
and format that supports cubic filtering together with minmax filtering, as specified byFilterCubicImageViewImageFormatPropertiesEXT
::filterCubicMinmax
returned bygetPhysicalDeviceImageFormatProperties2
- Any
Image
created with aImageCreateInfo
::flags
containingIMAGE_CREATE_CORNER_SAMPLED_BIT_NV
sampled as a result of this command must only be sampled using aSamplerAddressMode
ofSAMPLER_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 aPipelineLayout
that is compatible for set n, with thePipelineLayout
used to create the currentPipeline
, 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 aPipelineLayout
that is compatible for push constants, with thePipelineLayout
used to create the currentPipeline
, as described in ??? - Descriptors in each bound descriptor set, specified via
cmdBindDescriptorSets
, must be valid if they are statically used by thePipeline
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 forcommandBuffer
, 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 aSampler
object that uses unnormalized coordinates, that sampler must not be used to sample from anyImage
with aImageView
of the typeIMAGE_VIEW_TYPE_3D
,IMAGE_VIEW_TYPE_CUBE
,IMAGE_VIEW_TYPE_1D_ARRAY
,IMAGE_VIEW_TYPE_2D_ARRAY
orIMAGE_VIEW_TYPE_CUBE_ARRAY
, in any shader stage - If the
Pipeline
object bound to the pipeline bind point used by this command accesses aSampler
object that uses unnormalized coordinates, that sampler must not be used with any of the SPIR-VOpImageSample*
orOpImageSparseSample*
instructions withImplicitLod
,Dref
orProj
in their name, in any shader stage - If the
Pipeline
object bound to the pipeline bind point used by this command accesses aSampler
object that uses unnormalized coordinates, that sampler must not be used with any of the SPIR-VOpImageSample*
orOpImageSparseSample*
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 thePipeline
object bound to the pipeline bind point used by this command must not be a protected resource - If a
ImageView
is accessed usingOpImageWrite
as a result of this command, then theType
of theTexel
operand of that instruction must have at least as many components as the image view’s format. - If a
BufferView
is accessed usingOpImageWrite
as a result of this command, then theType
of theTexel
operand of that instruction must have at least as many components as the image view’s format. - If a
ImageView
with aFormat
that has a 64-bit channel width is accessed as a result of this command, theSampledType
of theOpTypeImage
operand of that instruction must have aWidth
of 64. - If a
ImageView
with aFormat
that has a channel width less than 64-bit is accessed as a result of this command, theSampledType
of theOpTypeImage
operand of that instruction must have aWidth
of 32. - If a
BufferView
with aFormat
that has a 64-bit channel width is accessed as a result of this command, theSampledType
of theOpTypeImage
operand of that instruction must have aWidth
of 64. - If a
BufferView
with aFormat
that has a channel width less than 64-bit is accessed as a result of this command, theSampledType
of theOpTypeImage
operand of that instruction must have aWidth
of 32. - If the
sparseImageInt64Atomics
feature is not enabled,
Image
objects created with theIMAGE_CREATE_SPARSE_RESIDENCY_BIT
flag must not be accessed by atomic instructions through anOpTypeImage
with aSampledType
with aWidth
of 64 by this command. - If the
sparseImageInt64Atomics
feature is not enabled,
Buffer
objects created with theBUFFER_CREATE_SPARSE_RESIDENCY_BIT
flag must not be accessed by atomic instructions through anOpTypeImage
with aSampledType
with aWidth
of 64 by this command. - If
commandBuffer
is a protected command buffer, any resource written to by thePipeline
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 thePipeline
object bound to the pipeline bind point must not write to any resource groupCountX
must be less than or equal toPhysicalDeviceLimits
::maxComputeWorkGroupCount
[0]groupCountY
must be less than or equal toPhysicalDeviceLimits
::maxComputeWorkGroupCount
[1]groupCountZ
must be less than or equal toPhysicalDeviceLimits
::maxComputeWorkGroupCount
[2]
Valid Usage (Implicit)
commandBuffer
must be a validCommandBuffer
handle
commandBuffer
must be in the recording state- The
CommandPool
thatcommandBuffer
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
thatcommandBuffer
was allocated from must be externally synchronized
Command Properties
'
Command Buffer Levels | Render Pass Scope | Supported Queue Types | Pipeline Type |
---|---|---|---|
Primary Secondary | Outside | Compute | Compute |
See Also
Arguments
:: forall io. MonadIO io | |
=> CommandBuffer |
|
-> Buffer |
|
-> ("offset" ::: DeviceSize) |
|
-> io () |
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
Sampler
created withmagFilter
orminFilter
equal toFILTER_LINEAR
andcompareEnable
equal toFALSE
is used to sample aImageView
as a result of this command, then the image view’s format features must containFORMAT_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 containFORMAT_FEATURE_STORAGE_IMAGE_ATOMIC_BIT
- If a
ImageView
is sampled withFILTER_CUBIC_EXT
as a result of this command, then the image view’s format features must containFORMAT_FEATURE_SAMPLED_IMAGE_FILTER_CUBIC_BIT_EXT
- Any
ImageView
being sampled withFILTER_CUBIC_EXT
as a result of this command must have aImageViewType
and format that supports cubic filtering, as specified byFilterCubicImageViewImageFormatPropertiesEXT
::filterCubic
returned bygetPhysicalDeviceImageFormatProperties2
- Any
ImageView
being sampled withFILTER_CUBIC_EXT
with a reduction mode of eitherSAMPLER_REDUCTION_MODE_MIN
orSAMPLER_REDUCTION_MODE_MAX
as a result of this command must have aImageViewType
and format that supports cubic filtering together with minmax filtering, as specified byFilterCubicImageViewImageFormatPropertiesEXT
::filterCubicMinmax
returned bygetPhysicalDeviceImageFormatProperties2
- Any
Image
created with aImageCreateInfo
::flags
containingIMAGE_CREATE_CORNER_SAMPLED_BIT_NV
sampled as a result of this command must only be sampled using aSamplerAddressMode
ofSAMPLER_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 aPipelineLayout
that is compatible for set n, with thePipelineLayout
used to create the currentPipeline
, 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 aPipelineLayout
that is compatible for push constants, with thePipelineLayout
used to create the currentPipeline
, as described in ??? - Descriptors in each bound descriptor set, specified via
cmdBindDescriptorSets
, must be valid if they are statically used by thePipeline
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 forcommandBuffer
, 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 aSampler
object that uses unnormalized coordinates, that sampler must not be used to sample from anyImage
with aImageView
of the typeIMAGE_VIEW_TYPE_3D
,IMAGE_VIEW_TYPE_CUBE
,IMAGE_VIEW_TYPE_1D_ARRAY
,IMAGE_VIEW_TYPE_2D_ARRAY
orIMAGE_VIEW_TYPE_CUBE_ARRAY
, in any shader stage - If the
Pipeline
object bound to the pipeline bind point used by this command accesses aSampler
object that uses unnormalized coordinates, that sampler must not be used with any of the SPIR-VOpImageSample*
orOpImageSparseSample*
instructions withImplicitLod
,Dref
orProj
in their name, in any shader stage - If the
Pipeline
object bound to the pipeline bind point used by this command accesses aSampler
object that uses unnormalized coordinates, that sampler must not be used with any of the SPIR-VOpImageSample*
orOpImageSparseSample*
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 thePipeline
object bound to the pipeline bind point used by this command must not be a protected resource - If a
ImageView
is accessed usingOpImageWrite
as a result of this command, then theType
of theTexel
operand of that instruction must have at least as many components as the image view’s format. - If a
BufferView
is accessed usingOpImageWrite
as a result of this command, then theType
of theTexel
operand of that instruction must have at least as many components as the image view’s format. - If a
ImageView
with aFormat
that has a 64-bit channel width is accessed as a result of this command, theSampledType
of theOpTypeImage
operand of that instruction must have aWidth
of 64. - If a
ImageView
with aFormat
that has a channel width less than 64-bit is accessed as a result of this command, theSampledType
of theOpTypeImage
operand of that instruction must have aWidth
of 32. - If a
BufferView
with aFormat
that has a 64-bit channel width is accessed as a result of this command, theSampledType
of theOpTypeImage
operand of that instruction must have aWidth
of 64. - If a
BufferView
with aFormat
that has a channel width less than 64-bit is accessed as a result of this command, theSampledType
of theOpTypeImage
operand of that instruction must have aWidth
of 32. - If the
sparseImageInt64Atomics
feature is not enabled,
Image
objects created with theIMAGE_CREATE_SPARSE_RESIDENCY_BIT
flag must not be accessed by atomic instructions through anOpTypeImage
with aSampledType
with aWidth
of 64 by this command. - If the
sparseImageInt64Atomics
feature is not enabled,
Buffer
objects created with theBUFFER_CREATE_SPARSE_RESIDENCY_BIT
flag must not be accessed by atomic instructions through anOpTypeImage
with aSampledType
with aWidth
of 64 by this command. - If
buffer
is non-sparse then it must be bound completely and contiguously to a singleDeviceMemory
object buffer
must have been created with theBUFFER_USAGE_INDIRECT_BUFFER_BIT
bit setoffset
must be a multiple of4
commandBuffer
must not be a protected command buffer- The sum of
offset
and the size ofDispatchIndirectCommand
must be less than or equal to the size ofbuffer
Valid Usage (Implicit)
commandBuffer
must be a validCommandBuffer
handle
buffer
must be a validBuffer
handlecommandBuffer
must be in the recording state- The
CommandPool
thatcommandBuffer
was allocated from must support compute operations - This command must only be called outside of a render pass instance
- Both of
buffer
, andcommandBuffer
must have been created, allocated, or retrieved from the sameDevice
Host Synchronization
- Host access to
commandBuffer
must be externally synchronized
- Host access to the
CommandPool
thatcommandBuffer
was allocated from must be externally synchronized
Command Properties
'
Command Buffer Levels | Render Pass Scope | Supported Queue Types | Pipeline Type |
---|---|---|---|
Primary Secondary | Outside | Compute | Compute |
See Also
Arguments
:: forall io. MonadIO io | |
=> CommandBuffer |
|
-> ("srcBuffer" ::: Buffer) |
|
-> ("dstBuffer" ::: Buffer) |
|
-> ("regions" ::: Vector BufferCopy) |
|
-> io () |
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, thensrcBuffer
must not be a protected buffer
- If
commandBuffer
is an unprotected command buffer, thendstBuffer
must not be a protected buffer - If
commandBuffer
is a protected command buffer, thendstBuffer
must not be an unprotected buffer - The
srcOffset
member of each element ofpRegions
must be less than the size ofsrcBuffer
- The
dstOffset
member of each element ofpRegions
must be less than the size ofdstBuffer
- The
size
member of each element ofpRegions
must be less than or equal to the size ofsrcBuffer
minussrcOffset
- The
size
member of each element ofpRegions
must be less than or equal to the size ofdstBuffer
minusdstOffset
- 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 withBUFFER_USAGE_TRANSFER_SRC_BIT
usage flag- If
srcBuffer
is non-sparse then it must be bound completely and contiguously to a singleDeviceMemory
object dstBuffer
must have been created withBUFFER_USAGE_TRANSFER_DST_BIT
usage flag- If
dstBuffer
is non-sparse then it must be bound completely and contiguously to a singleDeviceMemory
object
Valid Usage (Implicit)
commandBuffer
must be a validCommandBuffer
handle
srcBuffer
must be a validBuffer
handledstBuffer
must be a validBuffer
handlepRegions
must be a valid pointer to an array ofregionCount
validBufferCopy
structurescommandBuffer
must be in the recording state- The
CommandPool
thatcommandBuffer
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 than0
- Each of
commandBuffer
,dstBuffer
, andsrcBuffer
must have been created, allocated, or retrieved from the sameDevice
Host Synchronization
- Host access to
commandBuffer
must be externally synchronized
- Host access to the
CommandPool
thatcommandBuffer
was allocated from must be externally synchronized
Command Properties
'
Command Buffer Levels | Render Pass Scope | Supported Queue Types | Pipeline Type |
---|---|---|---|
Primary Secondary | Outside | Transfer Graphics Compute | Transfer |
See Also
Arguments
:: forall io. MonadIO io | |
=> CommandBuffer |
|
-> ("srcImage" ::: Image) |
|
-> ("srcImageLayout" ::: ImageLayout) |
|
-> ("dstImage" ::: Image) |
|
-> ("dstImageLayout" ::: ImageLayout) |
|
-> ("regions" ::: Vector ImageCopy) |
|
-> io () |
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, thensrcImage
must not be a protected image
- If
commandBuffer
is an unprotected command buffer, thendstImage
must not be a protected image - If
commandBuffer
is a protected command buffer, thendstImage
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 containFORMAT_FEATURE_TRANSFER_SRC_BIT
srcImage
must have been created withIMAGE_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 singleDeviceMemory
object srcImageLayout
must specify the layout of the image subresources ofsrcImage
specified inpRegions
at the time this command is executed on aDevice
srcImageLayout
must beIMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL
,IMAGE_LAYOUT_GENERAL
, orIMAGE_LAYOUT_SHARED_PRESENT_KHR
- The
format features
of
dstImage
must containFORMAT_FEATURE_TRANSFER_DST_BIT
dstImage
must have been created withIMAGE_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 singleDeviceMemory
object dstImageLayout
must specify the layout of the image subresources ofdstImage
specified inpRegions
at the time this command is executed on aDevice
dstImageLayout
must beIMAGE_LAYOUT_TRANSFER_DST_OPTIMAL
,IMAGE_LAYOUT_GENERAL
, orIMAGE_LAYOUT_SHARED_PRESENT_KHR
- If the
Format
of each ofsrcImage
anddstImage
is not a multi-planar format, theFormat
of each ofsrcImage
anddstImage
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
anddstImage
must match - The
srcSubresource.mipLevel
member of each element ofpRegions
must be less than themipLevels
specified inImageCreateInfo
whensrcImage
was created - The
dstSubresource.mipLevel
member of each element ofpRegions
must be less than themipLevels
specified inImageCreateInfo
whendstImage
was created - The
srcSubresource.baseArrayLayer
+srcSubresource.layerCount
of each element ofpRegions
must be less than or equal to thearrayLayers
specified inImageCreateInfo
whensrcImage
was created - The
dstSubresource.baseArrayLayer
+dstSubresource.layerCount
of each element ofpRegions
must be less than or equal to thearrayLayers
specified inImageCreateInfo
whendstImage
was created - The
srcOffset
andextent
members of each element ofpRegions
must respect the image transfer granularity requirements ofcommandBuffer
’s command pool’s queue family, as described inQueueFamilyProperties
- The
dstOffset
andextent
members of each element ofpRegions
must respect the image transfer granularity requirements ofcommandBuffer
’s command pool’s queue family, as described inQueueFamilyProperties
dstImage
andsrcImage
must not have been created withflags
containingIMAGE_CREATE_SUBSAMPLED_BIT_EXT
- If neither
srcImage
nordstImage
has a multi-planar image format then for each element ofpRegions
,srcSubresource.aspectMask
anddstSubresource.aspectMask
must match - If
srcImage
has aFormat
with two planes then for each element ofpRegions
,srcSubresource.aspectMask
must beIMAGE_ASPECT_PLANE_0_BIT
orIMAGE_ASPECT_PLANE_1_BIT
- If
srcImage
has aFormat
with three planes then for each element ofpRegions
,srcSubresource.aspectMask
must beIMAGE_ASPECT_PLANE_0_BIT
,IMAGE_ASPECT_PLANE_1_BIT
, orIMAGE_ASPECT_PLANE_2_BIT
- If
dstImage
has aFormat
with two planes then for each element ofpRegions
,dstSubresource.aspectMask
must beIMAGE_ASPECT_PLANE_0_BIT
orIMAGE_ASPECT_PLANE_1_BIT
- If
dstImage
has aFormat
with three planes then for each element ofpRegions
,dstSubresource.aspectMask
must beIMAGE_ASPECT_PLANE_0_BIT
,IMAGE_ASPECT_PLANE_1_BIT
, orIMAGE_ASPECT_PLANE_2_BIT
- If
srcImage
has a multi-planar image format and thedstImage
does not have a multi-planar image format, then for each element ofpRegions
,dstSubresource.aspectMask
must beIMAGE_ASPECT_COLOR_BIT
- If
dstImage
has a multi-planar image format and thesrcImage
does not have a multi-planar image format, then for each element ofpRegions
,srcSubresource.aspectMask
must beIMAGE_ASPECT_COLOR_BIT
- If
srcImage
is of typeIMAGE_TYPE_3D
, then for each element ofpRegions
,srcSubresource.baseArrayLayer
must be0
and andsrcSubresource.layerCount
must be1
- If
dstImage
is of typeIMAGE_TYPE_3D
, then for each element ofpRegions
,dstSubresource.baseArrayLayer
must be0
and anddstSubresource.layerCount
must be1
- For each element of
pRegions
,srcSubresource.aspectMask
must specify aspects present insrcImage
- For each element of
pRegions
,dstSubresource.aspectMask
must specify aspects present indstImage
- For each element of
pRegions
,srcOffset.x
and (extent.width
+srcOffset.x
) must both be greater than or equal to0
and less than or equal to the width of the specifiedsrcSubresource
ofsrcImage
- For each element of
pRegions
,srcOffset.y
and (extent.height
+srcOffset.y
) must both be greater than or equal to0
and less than or equal to the height of the specifiedsrcSubresource
ofsrcImage
- If
srcImage
is of typeIMAGE_TYPE_1D
, then for each element ofpRegions
,srcOffset.y
must be0
andextent.height
must be1
- For each element of
pRegions
,srcOffset.z
and (extent.depth
+srcOffset.z
) must both be greater than or equal to0
and less than or equal to the depth of the specifiedsrcSubresource
ofsrcImage
- If
srcImage
is of typeIMAGE_TYPE_1D
, then for each element ofpRegions
,srcOffset.z
must be0
andextent.depth
must be1
- If
dstImage
is of typeIMAGE_TYPE_1D
, then for each element ofpRegions
,dstOffset.z
must be0
andextent.depth
must be1
- If
srcImage
is of typeIMAGE_TYPE_2D
, then for each element ofpRegions
,srcOffset.z
must be0
- If
dstImage
is of typeIMAGE_TYPE_2D
, then for each element ofpRegions
,dstOffset.z
must be0
- If
srcImage
anddstImage
are both of typeIMAGE_TYPE_2D
, then for each element ofpRegions
,extent.depth
must be1
- If
srcImage
is of typeIMAGE_TYPE_2D
, anddstImage
is of typeIMAGE_TYPE_3D
, then for each element ofpRegions
,extent.depth
must equalsrcSubresource.layerCount
- If
dstImage
is of typeIMAGE_TYPE_2D
, andsrcImage
is of typeIMAGE_TYPE_3D
, then for each element ofpRegions
,extent.depth
must equaldstSubresource.layerCount
- For each element of
pRegions
,dstOffset.x
and (extent.width
+dstOffset.x
) must both be greater than or equal to0
and less than or equal to the width of the specifieddstSubresource
ofdstImage
- For each element of
pRegions
,dstOffset.y
and (extent.height
+dstOffset.y
) must both be greater than or equal to0
and less than or equal to the height of the specifieddstSubresource
ofdstImage
- If
dstImage
is of typeIMAGE_TYPE_1D
, then for each element ofpRegions
,dstOffset.y
must be0
andextent.height
must be1
- For each element of
pRegions
,dstOffset.z
and (extent.depth
+dstOffset.z
) must both be greater than or equal to0
and less than or equal to the depth of the specifieddstSubresource
ofdstImage
- If
srcImage
is a blocked image, then for each element ofpRegions
, all members ofsrcOffset
must be a multiple of the corresponding dimensions of the compressed texel block - If
srcImage
is a blocked image, then for each element ofpRegions
,extent.width
must be a multiple of the compressed texel block width or (extent.width
+srcOffset.x
) must equal the width of the specifiedsrcSubresource
ofsrcImage
- If
srcImage
is a blocked image, then for each element ofpRegions
,extent.height
must be a multiple of the compressed texel block height or (extent.height
+srcOffset.y
) must equal the height of the specifiedsrcSubresource
ofsrcImage
- If
srcImage
is a blocked image, then for each element ofpRegions
,extent.depth
must be a multiple of the compressed texel block depth or (extent.depth
+srcOffset.z
) must equal the depth of the specifiedsrcSubresource
ofsrcImage
- If
dstImage
is a blocked image, then for each element ofpRegions
, all members ofdstOffset
must be a multiple of the corresponding dimensions of the compressed texel block - If
dstImage
is a blocked image, then for each element ofpRegions
,extent.width
must be a multiple of the compressed texel block width or (extent.width
+dstOffset.x
) must equal the width of the specifieddstSubresource
ofdstImage
- If
dstImage
is a blocked image, then for each element ofpRegions
,extent.height
must be a multiple of the compressed texel block height or (extent.height
+dstOffset.y
) must equal the height of the specifieddstSubresource
ofdstImage
- If
dstImage
is a blocked image, then for each element ofpRegions
,extent.depth
must be a multiple of the compressed texel block depth or (extent.depth
+dstOffset.z
) must equal the depth of the specifieddstSubresource
ofdstImage
Valid Usage (Implicit)
commandBuffer
must be a validCommandBuffer
handle
srcImage
must be a validImage
handlesrcImageLayout
must be a validImageLayout
valuedstImage
must be a validImage
handledstImageLayout
must be a validImageLayout
valuepRegions
must be a valid pointer to an array ofregionCount
validImageCopy
structurescommandBuffer
must be in the recording state- The
CommandPool
thatcommandBuffer
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 than0
- Each of
commandBuffer
,dstImage
, andsrcImage
must have been created, allocated, or retrieved from the sameDevice
Host Synchronization
- Host access to
commandBuffer
must be externally synchronized
- Host access to the
CommandPool
thatcommandBuffer
was allocated from must be externally synchronized
Command Properties
'
Command Buffer Levels | Render Pass Scope | Supported Queue Types | Pipeline Type |
---|---|---|---|
Primary Secondary | Outside | Transfer Graphics Compute | Transfer |
See Also
Arguments
:: forall io. MonadIO io | |
=> CommandBuffer |
|
-> ("srcImage" ::: Image) |
|
-> ("srcImageLayout" ::: ImageLayout) |
|
-> ("dstImage" ::: Image) |
|
-> ("dstImageLayout" ::: ImageLayout) |
|
-> ("regions" ::: Vector ImageBlit) |
|
-> Filter |
|
-> io () |
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 -
baseArrayCount
dst
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 +
baseArrayCount
src
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.
When blitting 3D textures, slices in the destination region bounded by
dstOffsets
[0].z and dstOffsets
[1].z are sampled from slices in the
source region bounded by 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 represented by w
in the previous equations. If the 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, thensrcImage
must not be a protected image
- If
commandBuffer
is an unprotected command buffer, thendstImage
must not be a protected image - If
commandBuffer
is a protected command buffer, thendstImage
must not be an unprotected image - The source region specified by each element of
pRegions
must be a region that is contained withinsrcImage
- The destination region specified by each element of
pRegions
must be a region that is contained withindstImage
- 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 containFORMAT_FEATURE_BLIT_SRC_BIT
srcImage
must not use a format listed in ???srcImage
must have been created withIMAGE_USAGE_TRANSFER_SRC_BIT
usage flag- If
srcImage
is non-sparse then it must be bound completely and contiguously to a singleDeviceMemory
object srcImageLayout
must specify the layout of the image subresources ofsrcImage
specified inpRegions
at the time this command is executed on aDevice
srcImageLayout
must beIMAGE_LAYOUT_SHARED_PRESENT_KHR
,IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL
orIMAGE_LAYOUT_GENERAL
- The
format features
of
dstImage
must containFORMAT_FEATURE_BLIT_DST_BIT
dstImage
must not use a format listed in ???dstImage
must have been created withIMAGE_USAGE_TRANSFER_DST_BIT
usage flag- If
dstImage
is non-sparse then it must be bound completely and contiguously to a singleDeviceMemory
object dstImageLayout
must specify the layout of the image subresources ofdstImage
specified inpRegions
at the time this command is executed on aDevice
dstImageLayout
must beIMAGE_LAYOUT_SHARED_PRESENT_KHR
,IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL
orIMAGE_LAYOUT_GENERAL
- If either of
srcImage
ordstImage
was created with a signed integerFormat
, the other must also have been created with a signed integerFormat
- If either of
srcImage
ordstImage
was created with an unsigned integerFormat
, the other must also have been created with an unsigned integerFormat
- If either of
srcImage
ordstImage
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 beFILTER_NEAREST
srcImage
must have been created with asamples
value ofSAMPLE_COUNT_1_BIT
dstImage
must have been created with asamples
value ofSAMPLE_COUNT_1_BIT
- If
filter
isFILTER_LINEAR
, then the format features ofsrcImage
must containFORMAT_FEATURE_SAMPLED_IMAGE_FILTER_LINEAR_BIT
- If
filter
isFILTER_CUBIC_EXT
, then the format features ofsrcImage
must containFORMAT_FEATURE_SAMPLED_IMAGE_FILTER_CUBIC_BIT_EXT
- If
filter
isFILTER_CUBIC_EXT
,srcImage
must be of typeIMAGE_TYPE_2D
- The
srcSubresource.mipLevel
member of each element ofpRegions
must be less than themipLevels
specified inImageCreateInfo
whensrcImage
was created - The
dstSubresource.mipLevel
member of each element ofpRegions
must be less than themipLevels
specified inImageCreateInfo
whendstImage
was created - The
srcSubresource.baseArrayLayer
+srcSubresource.layerCount
of each element ofpRegions
must be less than or equal to thearrayLayers
specified inImageCreateInfo
whensrcImage
was created - The
dstSubresource.baseArrayLayer
+dstSubresource.layerCount
of each element ofpRegions
must be less than or equal to thearrayLayers
specified inImageCreateInfo
whendstImage
was created dstImage
andsrcImage
must not have been created withflags
containingIMAGE_CREATE_SUBSAMPLED_BIT_EXT
- If either
srcImage
ordstImage
is of typeIMAGE_TYPE_3D
, then for each element ofpRegions
,srcSubresource.baseArrayLayer
anddstSubresource.baseArrayLayer
must each be0
, andsrcSubresource.layerCount
anddstSubresource.layerCount
must each be1
. - For each element of
pRegions
,srcSubresource.aspectMask
must specify aspects present insrcImage
- For each element of
pRegions
,dstSubresource.aspectMask
must specify aspects present indstImage
- For each element of
pRegions
,srcOffset
[0].x andsrcOffset
[1].x must both be greater than or equal to0
and less than or equal to the width of the specifiedsrcSubresource
ofsrcImage
- For each element of
pRegions
,srcOffset
[0].y andsrcOffset
[1].y must both be greater than or equal to0
and less than or equal to the height of the specifiedsrcSubresource
ofsrcImage
- If
srcImage
is of typeIMAGE_TYPE_1D
, then for each element ofpRegions
,srcOffset
[0].y must be0
andsrcOffset
[1].y must be1
- For each element of
pRegions
,srcOffset
[0].z andsrcOffset
[1].z must both be greater than or equal to0
and less than or equal to the depth of the specifiedsrcSubresource
ofsrcImage
- If
srcImage
is of typeIMAGE_TYPE_1D
orIMAGE_TYPE_2D
, then for each element ofpRegions
,srcOffset
[0].z must be0
andsrcOffset
[1].z must be1
- For each element of
pRegions
,dstOffset
[0].x anddstOffset
[1].x must both be greater than or equal to0
and less than or equal to the width of the specifieddstSubresource
ofdstImage
- For each element of
pRegions
,dstOffset
[0].y anddstOffset
[1].y must both be greater than or equal to0
and less than or equal to the height of the specifieddstSubresource
ofdstImage
- If
dstImage
is of typeIMAGE_TYPE_1D
, then for each element ofpRegions
,dstOffset
[0].y must be0
anddstOffset
[1].y must be1
- For each element of
pRegions
,dstOffset
[0].z anddstOffset
[1].z must both be greater than or equal to0
and less than or equal to the depth of the specifieddstSubresource
ofdstImage
- If
dstImage
is of typeIMAGE_TYPE_1D
orIMAGE_TYPE_2D
, then for each element ofpRegions
,dstOffset
[0].z must be0
anddstOffset
[1].z must be1
Valid Usage (Implicit)
commandBuffer
must be a validCommandBuffer
handle
srcImage
must be a validImage
handlesrcImageLayout
must be a validImageLayout
valuedstImage
must be a validImage
handledstImageLayout
must be a validImageLayout
valuepRegions
must be a valid pointer to an array ofregionCount
validImageBlit
structuresfilter
must be a validFilter
valuecommandBuffer
must be in the recording state- The
CommandPool
thatcommandBuffer
was allocated from must support graphics operations - This command must only be called outside of a render pass instance
regionCount
must be greater than0
- Each of
commandBuffer
,dstImage
, andsrcImage
must have been created, allocated, or retrieved from the sameDevice
Host Synchronization
- Host access to
commandBuffer
must be externally synchronized
- Host access to the
CommandPool
thatcommandBuffer
was allocated from must be externally synchronized
Command Properties
'
Command Buffer Levels | Render Pass Scope | Supported Queue Types | Pipeline Type |
---|---|---|---|
Primary Secondary | Outside | Graphics | Transfer |
See Also
Arguments
:: forall io. MonadIO io | |
=> CommandBuffer |
|
-> ("srcBuffer" ::: Buffer) |
|
-> ("dstImage" ::: Image) |
|
-> ("dstImageLayout" ::: ImageLayout) |
|
-> ("regions" ::: Vector BufferImageCopy) |
|
-> io () |
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, thensrcBuffer
must not be a protected buffer
- If
commandBuffer
is an unprotected command buffer, thendstImage
must not be a protected image - If
commandBuffer
is a protected command buffer, thendstImage
must not be an unprotected image - The image region specified by each element of
pRegions
must be a region that is contained withindstImage
if thedstImage
’sFormat
is not a multi-planar format, and must be a region that is contained within the plane being copied to if thedstImage
’sFormat
is a multi-planar format srcBuffer
must be large enough to contain all buffer locations that are accessed according to Buffer and Image Addressing, for each element ofpRegions
- 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 withBUFFER_USAGE_TRANSFER_SRC_BIT
usage flag- The
format features
of
dstImage
must containFORMAT_FEATURE_TRANSFER_DST_BIT
- If
srcBuffer
is non-sparse then it must be bound completely and contiguously to a singleDeviceMemory
object dstImage
must have been created withIMAGE_USAGE_TRANSFER_DST_BIT
usage flag- If
dstImage
is non-sparse then it must be bound completely and contiguously to a singleDeviceMemory
object dstImage
must have a sample count equal toSAMPLE_COUNT_1_BIT
dstImageLayout
must specify the layout of the image subresources ofdstImage
specified inpRegions
at the time this command is executed on aDevice
dstImageLayout
must beIMAGE_LAYOUT_TRANSFER_DST_OPTIMAL
,IMAGE_LAYOUT_GENERAL
, orIMAGE_LAYOUT_SHARED_PRESENT_KHR
- The
imageSubresource.mipLevel
member of each element ofpRegions
must be less than themipLevels
specified inImageCreateInfo
whendstImage
was created - The
imageSubresource.baseArrayLayer
+imageSubresource.layerCount
of each element ofpRegions
must be less than or equal to thearrayLayers
specified inImageCreateInfo
whendstImage
was created - The
imageOffset
andimageExtent
members of each element ofpRegions
must respect the image transfer granularity requirements ofcommandBuffer
’s command pool’s queue family, as described inQueueFamilyProperties
dstImage
must not have been created withflags
containingIMAGE_CREATE_SUBSAMPLED_BIT_EXT
- If the queue family used to create the
CommandPool
whichcommandBuffer
was allocated from does not supportQUEUE_GRAPHICS_BIT
orQUEUE_COMPUTE_BIT
, thebufferOffset
member of any element ofpRegions
must be a multiple of4
- If
dstImage
has a depth/stencil format, thebufferOffset
member of any element ofpRegions
must be a multiple of4
- If the queue family used to create the
CommandPool
whichcommandBuffer
was allocated from does not supportQUEUE_GRAPHICS_BIT
, for each element ofpRegions
, theaspectMask
member ofimageSubresource
must not beIMAGE_ASPECT_DEPTH_BIT
orIMAGE_ASPECT_STENCIL_BIT
. - For each element of
pRegions
,imageOffset.x
and (imageExtent.width
+imageOffset.x
) must both be greater than or equal to0
and less than or equal to the width of the specifiedimageSubresource
ofdstImage
where this refers to the width of the plane of the image involved in the copy in the case of a multi-planar format - For each element of
pRegions
,imageOffset.y
and (imageExtent.height +imageOffset.y
) must both be greater than or equal to0
and less than or equal to the height of the specifiedimageSubresource
ofdstImage
where this refers to the height of the plane of the image involved in the copy in the case of a multi-planar format - If
dstImage
does not have either a depth/stencil or a multi-planar format, then for each element ofpRegions
,bufferOffset
must be a multiple of the format’s texel block size - If
dstImage
has a multi-planar format, then for each element ofpRegions
,bufferOffset
must be a multiple of the element size of the compatible format for the format and theaspectMask
of theimageSubresource
as defined in ??? - If
dstImage
is of typeIMAGE_TYPE_1D
, then for each element ofpRegions
,imageOffset.y
must be0
andimageExtent.height
must be1
- For each element of
pRegions
,imageOffset.z
and (imageExtent.depth +imageOffset.z
) must both be greater than or equal to0
and less than or equal to the depth of the specifiedimageSubresource
ofdstImage
- If
dstImage
is of typeIMAGE_TYPE_1D
orIMAGE_TYPE_2D
, then for each element ofpRegions
,imageOffset.z
must be0
andimageExtent.depth
must be1
- If
dstImage
is a blocked image, for each element ofpRegions
,bufferRowLength
must be a multiple of the compressed texel block width - If
dstImage
is a blocked image, for each element ofpRegions
,bufferImageHeight
must be a multiple of the compressed texel block height - If
dstImage
is a blocked image, for each element ofpRegions
, all members ofimageOffset
must be a multiple of the corresponding dimensions of the compressed texel block - If
dstImage
is a blocked image, for each element ofpRegions
,bufferOffset
must be a multiple of the compressed texel block size in bytes - If
dstImage
is a blocked image, for each element ofpRegions
,imageExtent.width
must be a multiple of the compressed texel block width or (imageExtent.width
+imageOffset.x
) must equal the width of the specifiedimageSubresource
ofdstImage
- If
dstImage
is a blocked image, for each element ofpRegions
,imageExtent.height
must be a multiple of the compressed texel block height or (imageExtent.height
+imageOffset.y
) must equal the height of the specifiedimageSubresource
ofdstImage
- If
dstImage
is a blocked image, for each element ofpRegions
,imageExtent.depth
must be a multiple of the compressed texel block depth or (imageExtent.depth
+imageOffset.z
) must equal the depth of the specifiedimageSubresource
ofdstImage
- For each element of
pRegions
,imageSubresource.aspectMask
must specify aspects present indstImage
- If
dstImage
has a multi-planar format, then for each element ofpRegions
,imageSubresource.aspectMask
must beIMAGE_ASPECT_PLANE_0_BIT
,IMAGE_ASPECT_PLANE_1_BIT
, orIMAGE_ASPECT_PLANE_2_BIT
(withIMAGE_ASPECT_PLANE_2_BIT
valid only for image formats with three planes) - If
dstImage
is of typeIMAGE_TYPE_3D
, for each element ofpRegions
,imageSubresource.baseArrayLayer
must be0
andimageSubresource.layerCount
must be1
Valid Usage (Implicit)
commandBuffer
must be a validCommandBuffer
handle
srcBuffer
must be a validBuffer
handledstImage
must be a validImage
handledstImageLayout
must be a validImageLayout
valuepRegions
must be a valid pointer to an array ofregionCount
validBufferImageCopy
structurescommandBuffer
must be in the recording state- The
CommandPool
thatcommandBuffer
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 than0
- Each of
commandBuffer
,dstImage
, andsrcBuffer
must have been created, allocated, or retrieved from the sameDevice
Host Synchronization
- Host access to
commandBuffer
must be externally synchronized
- Host access to the
CommandPool
thatcommandBuffer
was allocated from must be externally synchronized
Command Properties
'
Command Buffer Levels | Render Pass Scope | Supported Queue Types | Pipeline Type |
---|---|---|---|
Primary Secondary | Outside | Transfer Graphics Compute | Transfer |
See Also
Arguments
:: forall io. MonadIO io | |
=> CommandBuffer |
|
-> ("srcImage" ::: Image) |
|
-> ("srcImageLayout" ::: ImageLayout) |
|
-> ("dstBuffer" ::: Buffer) |
|
-> ("regions" ::: Vector BufferImageCopy) |
|
-> io () |
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, thensrcImage
must not be a protected image
- If
commandBuffer
is an unprotected command buffer, thendstBuffer
must not be a protected buffer - If
commandBuffer
is a protected command buffer, thendstBuffer
must not be an unprotected buffer - The image region specified by each element of
pRegions
must be a region that is contained withinsrcImage
if thesrcImage
’sFormat
is not a multi-planar format, and must be a region that is contained within the plane being copied if thesrcImage
’sFormat
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 ofpRegions
- The union of all source regions, and the union of all destination
regions, specified by the elements of
pRegions
, must not overlap in memory srcImage
must have been created withIMAGE_USAGE_TRANSFER_SRC_BIT
usage flag- The
format features
of
srcImage
must containFORMAT_FEATURE_TRANSFER_SRC_BIT
- If
srcImage
is non-sparse then it must be bound completely and contiguously to a singleDeviceMemory
object dstBuffer
must have been created withBUFFER_USAGE_TRANSFER_DST_BIT
usage flag- If
dstBuffer
is non-sparse then it must be bound completely and contiguously to a singleDeviceMemory
object srcImage
must have a sample count equal toSAMPLE_COUNT_1_BIT
srcImageLayout
must specify the layout of the image subresources ofsrcImage
specified inpRegions
at the time this command is executed on aDevice
srcImageLayout
must beIMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL
,IMAGE_LAYOUT_GENERAL
, orIMAGE_LAYOUT_SHARED_PRESENT_KHR
- The
imageSubresource.mipLevel
member of each element ofpRegions
must be less than themipLevels
specified inImageCreateInfo
whensrcImage
was created - The
imageSubresource.baseArrayLayer
+imageSubresource.layerCount
of each element ofpRegions
must be less than or equal to thearrayLayers
specified inImageCreateInfo
whensrcImage
was created - The
imageOffset
andimageExtent
members of each element ofpRegions
must respect the image transfer granularity requirements ofcommandBuffer
’s command pool’s queue family, as described inQueueFamilyProperties
srcImage
must not have been created withflags
containingIMAGE_CREATE_SUBSAMPLED_BIT_EXT
- If the queue family used to create the
CommandPool
whichcommandBuffer
was allocated from does not supportQUEUE_GRAPHICS_BIT
orQUEUE_COMPUTE_BIT
, thebufferOffset
member of any element ofpRegions
must be a multiple of4
- If
srcImage
has a depth/stencil format, thebufferOffset
member of any element ofpRegions
must be a multiple of4
- For each element of
pRegions
,imageOffset.x
and (imageExtent.width
+imageOffset.x
) must both be greater than or equal to0
and less than or equal to the width of the specifiedimageSubresource
ofsrcImage
where this refers to the width of the plane of the image involved in the copy in the case of a multi-planar format - For each element of
pRegions
,imageOffset.y
and (imageExtent.height +imageOffset.y
) must both be greater than or equal to0
and less than or equal to the height of the specifiedimageSubresource
ofsrcImage
where this refers to the height of the plane of the image involved in the copy in the case of a multi-planar format - If
srcImage
does not have either a depth/stencil or a multi-planar format, then for each element ofpRegions
,bufferOffset
must be a multiple of the format’s texel block size - If
srcImage
has a multi-planar format, then for each element ofpRegions
,bufferOffset
must be a multiple of the element size of the compatible format for the format and theaspectMask
of theimageSubresource
as defined in ??? - If
srcImage
is of typeIMAGE_TYPE_1D
, then for each element ofpRegions
,imageOffset.y
must be0
andimageExtent.height
must be1
- For each element of
pRegions
,imageOffset.z
and (imageExtent.depth +imageOffset.z
) must both be greater than or equal to0
and less than or equal to the depth of the specifiedimageSubresource
ofsrcImage
- If
srcImage
is of typeIMAGE_TYPE_1D
orIMAGE_TYPE_2D
, then for each element ofpRegions
,imageOffset.z
must be0
andimageExtent.depth
must be1
- If
srcImage
is a blocked image, for each element ofpRegions
,bufferRowLength
must be a multiple of the compressed texel block width - If
srcImage
is a blocked image, for each element ofpRegions
,bufferImageHeight
must be a multiple of the compressed texel block height - If
srcImage
is a blocked image, for each element ofpRegions
, all members ofimageOffset
must be a multiple of the corresponding dimensions of the compressed texel block - If
srcImage
is a blocked image, for each element ofpRegions
,bufferOffset
must be a multiple of the compressed texel block size in bytes - If
srcImage
is a blocked image, for each element ofpRegions
,imageExtent.width
must be a multiple of the compressed texel block width or (imageExtent.width
+imageOffset.x
) must equal the width of the specifiedimageSubresource
ofsrcImage
- If
srcImage
is a blocked image, for each element ofpRegions
,imageExtent.height
must be a multiple of the compressed texel block height or (imageExtent.height
+imageOffset.y
) must equal the height of the specifiedimageSubresource
ofsrcImage
- If
srcImage
is a blocked image, for each element ofpRegions
,imageExtent.depth
must be a multiple of the compressed texel block depth or (imageExtent.depth
+imageOffset.z
) must equal the depth of the specifiedimageSubresource
ofsrcImage
- For each element of
pRegions
,imageSubresource.aspectMask
must specify aspects present insrcImage
- If
srcImage
has a multi-planar format, then for each element ofpRegions
,imageSubresource.aspectMask
must beIMAGE_ASPECT_PLANE_0_BIT
,IMAGE_ASPECT_PLANE_1_BIT
, orIMAGE_ASPECT_PLANE_2_BIT
(withIMAGE_ASPECT_PLANE_2_BIT
valid only for image formats with three planes) - If
srcImage
is of typeIMAGE_TYPE_3D
, for each element ofpRegions
,imageSubresource.baseArrayLayer
must be0
andimageSubresource.layerCount
must be1
Valid Usage (Implicit)
commandBuffer
must be a validCommandBuffer
handle
srcImage
must be a validImage
handlesrcImageLayout
must be a validImageLayout
valuedstBuffer
must be a validBuffer
handlepRegions
must be a valid pointer to an array ofregionCount
validBufferImageCopy
structurescommandBuffer
must be in the recording state- The
CommandPool
thatcommandBuffer
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 than0
- Each of
commandBuffer
,dstBuffer
, andsrcImage
must have been created, allocated, or retrieved from the sameDevice
Host Synchronization
- Host access to
commandBuffer
must be externally synchronized
- Host access to the
CommandPool
thatcommandBuffer
was allocated from must be externally synchronized
Command Properties
'
Command Buffer Levels | Render Pass Scope | Supported Queue Types | Pipeline Type |
---|---|---|---|
Primary Secondary | Outside | Transfer Graphics Compute | Transfer |
See Also
Arguments
:: forall io. MonadIO io | |
=> CommandBuffer |
|
-> ("dstBuffer" ::: Buffer) |
|
-> ("dstOffset" ::: DeviceSize) |
|
-> ("dataSize" ::: DeviceSize) |
|
-> ("data" ::: Ptr ()) |
|
-> io () |
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 ofdstBuffer
dataSize
must be less than or equal to the size ofdstBuffer
minusdstOffset
dstBuffer
must have been created withBUFFER_USAGE_TRANSFER_DST_BIT
usage flag- If
dstBuffer
is non-sparse then it must be bound completely and contiguously to a singleDeviceMemory
object dstOffset
must be a multiple of4
dataSize
must be less than or equal to65536
dataSize
must be a multiple of4
- If
commandBuffer
is an unprotected command buffer, thendstBuffer
must not be a protected buffer - If
commandBuffer
is a protected command buffer, thendstBuffer
must not be an unprotected buffer
Valid Usage (Implicit)
commandBuffer
must be a validCommandBuffer
handle
dstBuffer
must be a validBuffer
handlepData
must be a valid pointer to an array ofdataSize
bytescommandBuffer
must be in the recording state- The
CommandPool
thatcommandBuffer
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 than0
- Both of
commandBuffer
, anddstBuffer
must have been created, allocated, or retrieved from the sameDevice
Host Synchronization
- Host access to
commandBuffer
must be externally synchronized
- Host access to the
CommandPool
thatcommandBuffer
was allocated from must be externally synchronized
Command Properties
'
Command Buffer Levels | Render Pass Scope | Supported Queue Types | Pipeline Type |
---|---|---|---|
Primary Secondary | Outside | Transfer Graphics Compute | Transfer |
See Also
Arguments
:: forall io. MonadIO io | |
=> CommandBuffer |
|
-> ("dstBuffer" ::: Buffer) |
|
-> ("dstOffset" ::: DeviceSize) |
|
-> DeviceSize |
|
-> ("data" ::: Word32) |
|
-> io () |
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 ofdstBuffer
dstOffset
must be a multiple of4
- If
size
is not equal toWHOLE_SIZE
,size
must be greater than0
- If
size
is not equal toWHOLE_SIZE
,size
must be less than or equal to the size ofdstBuffer
minusdstOffset
- If
size
is not equal toWHOLE_SIZE
,size
must be a multiple of4
dstBuffer
must have been created withBUFFER_USAGE_TRANSFER_DST_BIT
usage flag- If
dstBuffer
is non-sparse then it must be bound completely and contiguously to a singleDeviceMemory
object - If
commandBuffer
is an unprotected command buffer, thendstBuffer
must not be a protected buffer - If
commandBuffer
is a protected command buffer, thendstBuffer
must not be an unprotected buffer
Valid Usage (Implicit)
commandBuffer
must be a validCommandBuffer
handle
dstBuffer
must be a validBuffer
handlecommandBuffer
must be in the recording state- The
CommandPool
thatcommandBuffer
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
, anddstBuffer
must have been created, allocated, or retrieved from the sameDevice
Host Synchronization
- Host access to
commandBuffer
must be externally synchronized
- Host access to the
CommandPool
thatcommandBuffer
was allocated from must be externally synchronized
Command Properties
'
Command Buffer Levels | Render Pass Scope | Supported Queue Types | Pipeline Type |
---|---|---|---|
Primary Secondary | Outside | Transfer Graphics Compute | Transfer |
See Also
Arguments
:: forall io. MonadIO io | |
=> CommandBuffer |
|
-> Image |
|
-> ImageLayout |
|
-> ClearColorValue |
|
-> ("ranges" ::: Vector ImageSubresourceRange) |
|
-> io () |
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 containFORMAT_FEATURE_TRANSFER_DST_BIT
image
must have been created withIMAGE_USAGE_TRANSFER_DST_BIT
usage flagimage
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 singleDeviceMemory
object imageLayout
must specify the layout of the image subresource ranges ofimage
specified inpRanges
at the time this command is executed on aDevice
imageLayout
must beIMAGE_LAYOUT_TRANSFER_DST_OPTIMAL
,IMAGE_LAYOUT_GENERAL
, orIMAGE_LAYOUT_SHARED_PRESENT_KHR
- The
ImageSubresourceRange
::aspectMask
members of the elements of thepRanges
array must each only includeIMAGE_ASPECT_COLOR_BIT
- The
ImageSubresourceRange
::baseMipLevel
members of the elements of thepRanges
array must each be less than themipLevels
specified inImageCreateInfo
whenimage
was created - For each
ImageSubresourceRange
element ofpRanges
, if thelevelCount
member is notREMAINING_MIP_LEVELS
, thenbaseMipLevel
+levelCount
must be less than themipLevels
specified inImageCreateInfo
whenimage
was created - The
ImageSubresourceRange
::baseArrayLayer
members of the elements of thepRanges
array must each be less than thearrayLayers
specified inImageCreateInfo
whenimage
was created - For each
ImageSubresourceRange
element ofpRanges
, if thelayerCount
member is notREMAINING_ARRAY_LAYERS
, thenbaseArrayLayer
+layerCount
must be less than thearrayLayers
specified inImageCreateInfo
whenimage
was created image
must not have a compressed or depth/stencil format- If
commandBuffer
is an unprotected command buffer, thenimage
must not be a protected image - If
commandBuffer
is a protected command buffer, thenimage
must not be an unprotected image
Valid Usage (Implicit)
commandBuffer
must be a validCommandBuffer
handle
image
must be a validImage
handleimageLayout
must be a validImageLayout
valuepColor
must be a valid pointer to a validClearColorValue
unionpRanges
must be a valid pointer to an array ofrangeCount
validImageSubresourceRange
structurescommandBuffer
must be in the recording state- The
CommandPool
thatcommandBuffer
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 than0
- Both of
commandBuffer
, andimage
must have been created, allocated, or retrieved from the sameDevice
Host Synchronization
- Host access to
commandBuffer
must be externally synchronized
- Host access to the
CommandPool
thatcommandBuffer
was allocated from must be externally synchronized
Command Properties
'
Command Buffer Levels | Render Pass Scope | Supported Queue Types | Pipeline Type |
---|---|---|---|
Primary Secondary | Outside | Graphics Compute | Transfer |
See Also
ClearColorValue
, CommandBuffer
,
Image
,
ImageLayout
,
ImageSubresourceRange
cmdClearDepthStencilImage Source #
Arguments
:: forall io. MonadIO io | |
=> CommandBuffer |
|
-> Image |
|
-> ImageLayout |
|
-> ClearDepthStencilValue |
|
-> ("ranges" ::: Vector ImageSubresourceRange) |
|
-> io () |
vkCmdClearDepthStencilImage - Fill regions of a combined depth/stencil image
Valid Usage
- The
format features
of
image
must containFORMAT_FEATURE_TRANSFER_DST_BIT
- If the
aspect
member of any element ofpRanges
includesIMAGE_ASPECT_STENCIL_BIT
, andimage
was created with separate stencil usage,IMAGE_USAGE_TRANSFER_DST_BIT
must have been included in theImageStencilUsageCreateInfo
::stencilUsage
used to createimage
- If the
aspect
member of any element ofpRanges
includesIMAGE_ASPECT_STENCIL_BIT
, andimage
was not created with separate stencil usage,IMAGE_USAGE_TRANSFER_DST_BIT
must have been included in theImageCreateInfo
::usage
used to createimage
- If the
aspect
member of any element ofpRanges
includesIMAGE_ASPECT_DEPTH_BIT
,IMAGE_USAGE_TRANSFER_DST_BIT
must have been included in theImageCreateInfo
::usage
used to createimage
- If
image
is non-sparse then it must be bound completely and contiguously to a singleDeviceMemory
object imageLayout
must specify the layout of the image subresource ranges ofimage
specified inpRanges
at the time this command is executed on aDevice
imageLayout
must be either ofIMAGE_LAYOUT_TRANSFER_DST_OPTIMAL
orIMAGE_LAYOUT_GENERAL
- The
ImageSubresourceRange
::aspectMask
member of each element of thepRanges
array must not include bits other thanIMAGE_ASPECT_DEPTH_BIT
orIMAGE_ASPECT_STENCIL_BIT
- If the
image
’s format does not have a stencil component, then theImageSubresourceRange
::aspectMask
member of each element of thepRanges
array must not include theIMAGE_ASPECT_STENCIL_BIT
bit - If the
image
’s format does not have a depth component, then theImageSubresourceRange
::aspectMask
member of each element of thepRanges
array must not include theIMAGE_ASPECT_DEPTH_BIT
bit - The
ImageSubresourceRange
::baseMipLevel
members of the elements of thepRanges
array must each be less than themipLevels
specified inImageCreateInfo
whenimage
was created - For each
ImageSubresourceRange
element ofpRanges
, if thelevelCount
member is notREMAINING_MIP_LEVELS
, thenbaseMipLevel
+levelCount
must be less than themipLevels
specified inImageCreateInfo
whenimage
was created - The
ImageSubresourceRange
::baseArrayLayer
members of the elements of thepRanges
array must each be less than thearrayLayers
specified inImageCreateInfo
whenimage
was created - For each
ImageSubresourceRange
element ofpRanges
, if thelayerCount
member is notREMAINING_ARRAY_LAYERS
, thenbaseArrayLayer
+layerCount
must be less than thearrayLayers
specified inImageCreateInfo
whenimage
was created image
must have a depth/stencil format- If
commandBuffer
is an unprotected command buffer, thenimage
must not be a protected image - If
commandBuffer
is a protected command buffer, thenimage
must not be an unprotected image
Valid Usage (Implicit)
commandBuffer
must be a validCommandBuffer
handle
image
must be a validImage
handleimageLayout
must be a validImageLayout
valuepDepthStencil
must be a valid pointer to a validClearDepthStencilValue
structurepRanges
must be a valid pointer to an array ofrangeCount
validImageSubresourceRange
structurescommandBuffer
must be in the recording state- The
CommandPool
thatcommandBuffer
was allocated from must support graphics operations - This command must only be called outside of a render pass instance
rangeCount
must be greater than0
- Both of
commandBuffer
, andimage
must have been created, allocated, or retrieved from the sameDevice
Host Synchronization
- Host access to
commandBuffer
must be externally synchronized
- Host access to the
CommandPool
thatcommandBuffer
was allocated from must be externally synchronized
Command Properties
'
Command Buffer Levels | Render Pass Scope | Supported Queue Types | Pipeline Type |
---|---|---|---|
Primary Secondary | Outside | Graphics | Transfer |
See Also
ClearDepthStencilValue
, CommandBuffer
,
Image
,
ImageLayout
,
ImageSubresourceRange
Arguments
:: forall io. MonadIO io | |
=> CommandBuffer |
|
-> ("attachments" ::: Vector ClearAttachment) |
|
-> ("rects" ::: Vector ClearRect) |
|
-> io () |
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 ofpAttachments
containsIMAGE_ASPECT_COLOR_BIT
, then thecolorAttachment
member of that element must either refer to a color attachment which isATTACHMENT_UNUSED
, or must be a valid color attachment
- If the
aspectMask
member of any element ofpAttachments
containsIMAGE_ASPECT_DEPTH_BIT
, then the current subpass' depth/stencil attachment must either beATTACHMENT_UNUSED
, or must have a depth component - If the
aspectMask
member of any element ofpAttachments
containsIMAGE_ASPECT_STENCIL_BIT
, then the current subpass' depth/stencil attachment must either beATTACHMENT_UNUSED
, or must have a stencil component - The
rect
member of each element ofpRects
must have anextent.width
greater than0
- The
rect
member of each element ofpRects
must have anextent.height
greater than0
- 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 thatpAttachments
refers to - The
layerCount
member of each element ofpRects
must not be0
- 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 andlayerCount
must be one
Valid Usage (Implicit)
commandBuffer
must be a validCommandBuffer
handle
pAttachments
must be a valid pointer to an array ofattachmentCount
validClearAttachment
structurespRects
must be a valid pointer to an array ofrectCount
ClearRect
structurescommandBuffer
must be in the recording state- The
CommandPool
thatcommandBuffer
was allocated from must support graphics operations - This command must only be called inside of a render pass instance
attachmentCount
must be greater than0
rectCount
must be greater than0
Host Synchronization
- Host access to
commandBuffer
must be externally synchronized
- Host access to the
CommandPool
thatcommandBuffer
was allocated from must be externally synchronized
Command Properties
'
Command Buffer Levels | Render Pass Scope | Supported Queue Types | Pipeline Type |
---|---|---|---|
Primary Secondary | Inside | Graphics | Graphics |
See Also
Arguments
:: forall io. MonadIO io | |
=> CommandBuffer |
|
-> ("srcImage" ::: Image) |
|
-> ("srcImageLayout" ::: ImageLayout) |
|
-> ("dstImage" ::: Image) |
|
-> ("dstImageLayout" ::: ImageLayout) |
|
-> ("regions" ::: Vector ImageResolve) |
|
-> io () |
vkCmdResolveImage - Resolve regions of an image
Description
During the resolve the samples corresponding to each pixel location in the source are converted to a single sample before being written to the destination. If the source formats are floating-point or normalized types, the sample values for each pixel are resolved in an implementation-dependent manner. If the source formats are integer types, a single sample’s value is selected for each pixel.
srcOffset
and dstOffset
select the initial x
, y
, and z
offsets
in texels of the sub-regions of the source and destination image data.
extent
is the size in texels of the source image to resolve in
width
, height
and depth
. Each element of pRegions
must be a
region that is contained within its corresponding image.
Resolves are done layer by layer starting with baseArrayLayer
member
of srcSubresource
for the source and dstSubresource
for the
destination. layerCount
layers are resolved to the destination image.
Valid Usage
- If
commandBuffer
is an unprotected command buffer, thensrcImage
must not be a protected image
- If
commandBuffer
is an unprotected command buffer, thendstImage
must not be a protected image - If
commandBuffer
is a protected command buffer, thendstImage
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 - If
srcImage
is non-sparse then it must be bound completely and contiguously to a singleDeviceMemory
object srcImage
must have a sample count equal to any valid sample count value other thanSAMPLE_COUNT_1_BIT
- If
dstImage
is non-sparse then it must be bound completely and contiguously to a singleDeviceMemory
object dstImage
must have a sample count equal toSAMPLE_COUNT_1_BIT
srcImageLayout
must specify the layout of the image subresources ofsrcImage
specified inpRegions
at the time this command is executed on aDevice
srcImageLayout
must beIMAGE_LAYOUT_SHARED_PRESENT_KHR
,IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL
orIMAGE_LAYOUT_GENERAL
dstImageLayout
must specify the layout of the image subresources ofdstImage
specified inpRegions
at the time this command is executed on aDevice
dstImageLayout
must beIMAGE_LAYOUT_SHARED_PRESENT_KHR
,IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL
orIMAGE_LAYOUT_GENERAL
- The
format features
of
dstImage
must containFORMAT_FEATURE_COLOR_ATTACHMENT_BIT
srcImage
anddstImage
must have been created with the same image format- The
srcSubresource.mipLevel
member of each element ofpRegions
must be less than themipLevels
specified inImageCreateInfo
whensrcImage
was created - The
dstSubresource.mipLevel
member of each element ofpRegions
must be less than themipLevels
specified inImageCreateInfo
whendstImage
was created - The
srcSubresource.baseArrayLayer
+srcSubresource.layerCount
of each element ofpRegions
must be less than or equal to thearrayLayers
specified inImageCreateInfo
whensrcImage
was created - The
dstSubresource.baseArrayLayer
+dstSubresource.layerCount
of each element ofpRegions
must be less than or equal to thearrayLayers
specified inImageCreateInfo
whendstImage
was created dstImage
andsrcImage
must not have been created withflags
containingIMAGE_CREATE_SUBSAMPLED_BIT_EXT
- If either
srcImage
ordstImage
are of typeIMAGE_TYPE_3D
, then for each element ofpRegions
,srcSubresource.baseArrayLayer
must be0
andsrcSubresource.layerCount
must be1
- If either
srcImage
ordstImage
are of typeIMAGE_TYPE_3D
, then for each element ofpRegions
,dstSubresource.baseArrayLayer
must be0
anddstSubresource.layerCount
must be1
- For each element of
pRegions
,srcOffset.x
and (extent.width
+srcOffset.x
) must both be greater than or equal to0
and less than or equal to the width of the specifiedsrcSubresource
ofsrcImage
- For each element of
pRegions
,srcOffset.y
and (extent.height
+srcOffset.y
) must both be greater than or equal to0
and less than or equal to the height of the specifiedsrcSubresource
ofsrcImage
- If
srcImage
is of typeIMAGE_TYPE_1D
, then for each element ofpRegions
,srcOffset.y
must be0
andextent.height
must be1
- For each element of
pRegions
,srcOffset.z
and (extent.depth
+srcOffset.z
) must both be greater than or equal to0
and less than or equal to the depth of the specifiedsrcSubresource
ofsrcImage
- If
srcImage
is of typeIMAGE_TYPE_1D
orIMAGE_TYPE_2D
, then for each element ofpRegions
,srcOffset.z
must be0
andextent.depth
must be1
- For each element of
pRegions
,dstOffset.x
and (extent.width
+dstOffset.x
) must both be greater than or equal to0
and less than or equal to the width of the specifieddstSubresource
ofdstImage
- For each element of
pRegions
,dstOffset.y
and (extent.height
+dstOffset.y
) must both be greater than or equal to0
and less than or equal to the height of the specifieddstSubresource
ofdstImage
- If
dstImage
is of typeIMAGE_TYPE_1D
, then for each element ofpRegions
,dstOffset.y
must be0
andextent.height
must be1
- For each element of
pRegions
,dstOffset.z
and (extent.depth
+dstOffset.z
) must both be greater than or equal to0
and less than or equal to the depth of the specifieddstSubresource
ofdstImage
- If
dstImage
is of typeIMAGE_TYPE_1D
orIMAGE_TYPE_2D
, then for each element ofpRegions
,dstOffset.z
must be0
andextent.depth
must be1
Valid Usage (Implicit)
commandBuffer
must be a validCommandBuffer
handle
srcImage
must be a validImage
handlesrcImageLayout
must be a validImageLayout
valuedstImage
must be a validImage
handledstImageLayout
must be a validImageLayout
valuepRegions
must be a valid pointer to an array ofregionCount
validImageResolve
structurescommandBuffer
must be in the recording state- The
CommandPool
thatcommandBuffer
was allocated from must support graphics operations - This command must only be called outside of a render pass instance
regionCount
must be greater than0
- Each of
commandBuffer
,dstImage
, andsrcImage
must have been created, allocated, or retrieved from the sameDevice
Host Synchronization
- Host access to
commandBuffer
must be externally synchronized
- Host access to the
CommandPool
thatcommandBuffer
was allocated from must be externally synchronized
Command Properties
'
Command Buffer Levels | Render Pass Scope | Supported Queue Types | Pipeline Type |
---|---|---|---|
Primary Secondary | Outside | Graphics | Transfer |
See Also
Arguments
:: forall io. MonadIO io | |
=> CommandBuffer |
|
-> Event |
|
-> ("stageMask" ::: PipelineStageFlags) |
|
-> io () |
vkCmdSetEvent - Set an event object to signaled state
Description
When cmdSetEvent
is submitted to a queue, it defines an execution
dependency on commands that were submitted before it, and defines an
event signal operation which sets the event to the signaled state.
The first
synchronization scope
includes all commands that occur earlier in
submission order.
The synchronization scope is limited to operations on the pipeline
stages determined by the
source stage mask
specified by stageMask
.
The second synchronization scope includes only the event signal operation.
If event
is already in the signaled state when cmdSetEvent
is
executed on the device, then cmdSetEvent
has no effect, no event
signal operation occurs, and no execution dependency is generated.
Valid Usage
- If the
geometry shaders
feature is not enabled,
stageMask
must not containPIPELINE_STAGE_GEOMETRY_SHADER_BIT
- If the
tessellation shaders
feature is not enabled,
stageMask
must not containPIPELINE_STAGE_TESSELLATION_CONTROL_SHADER_BIT
orPIPELINE_STAGE_TESSELLATION_EVALUATION_SHADER_BIT
- If the
conditional rendering
feature is not enabled,
stageMask
must not containPIPELINE_STAGE_CONDITIONAL_RENDERING_BIT_EXT
- If the
fragment density map
feature is not enabled,
stageMask
must not containPIPELINE_STAGE_FRAGMENT_DENSITY_PROCESS_BIT_EXT
- If the
transform feedback
feature is not enabled,
stageMask
must not containPIPELINE_STAGE_TRANSFORM_FEEDBACK_BIT_EXT
- If the
mesh shaders
feature is not enabled,
stageMask
must not containPIPELINE_STAGE_MESH_SHADER_BIT_NV
- If the
task shaders
feature is not enabled,
stageMask
must not containPIPELINE_STAGE_TASK_SHADER_BIT_NV
- If the
shading rate image
feature is not enabled,
stageMask
must not containPIPELINE_STAGE_SHADING_RATE_IMAGE_BIT_NV
- Any pipeline stage included in
stageMask
must be supported by the capabilities of the queue family specified by thequeueFamilyIndex
member of theCommandPoolCreateInfo
structure that was used to create theCommandPool
thatcommandBuffer
was allocated from, as specified in the table of supported pipeline stages stageMask
must not includePIPELINE_STAGE_HOST_BIT
commandBuffer
’s current device mask must include exactly one physical device
Valid Usage (Implicit)
commandBuffer
must be a validCommandBuffer
handle
event
must be a validEvent
handlestageMask
must be a valid combination ofPipelineStageFlagBits
valuesstageMask
must not be0
commandBuffer
must be in the recording state- The
CommandPool
thatcommandBuffer
was allocated from must support graphics, or compute operations - This command must only be called outside of a render pass instance
- Both of
commandBuffer
, andevent
must have been created, allocated, or retrieved from the sameDevice
Host Synchronization
- Host access to
commandBuffer
must be externally synchronized
- Host access to the
CommandPool
thatcommandBuffer
was allocated from must be externally synchronized
Command Properties
'
Command Buffer Levels | Render Pass Scope | Supported Queue Types | Pipeline Type |
---|---|---|---|
Primary Secondary | Outside | Graphics Compute |
See Also
Arguments
:: forall io. MonadIO io | |
=> CommandBuffer |
|
-> Event |
|
-> ("stageMask" ::: PipelineStageFlags) |
|
-> io () |
vkCmdResetEvent - Reset an event object to non-signaled state
Description
When cmdResetEvent
is submitted to a queue, it defines an execution
dependency on commands that were submitted before it, and defines an
event unsignal operation which resets the event to the unsignaled state.
The first
synchronization scope
includes all commands that occur earlier in
submission order.
The synchronization scope is limited to operations on the pipeline
stages determined by the
source stage mask
specified by stageMask
.
The second synchronization scope includes only the event unsignal operation.
If event
is already in the unsignaled state when cmdResetEvent
is
executed on the device, then cmdResetEvent
has no effect, no event
unsignal operation occurs, and no execution dependency is generated.
Valid Usage
- If the
geometry shaders
feature is not enabled,
stageMask
must not containPIPELINE_STAGE_GEOMETRY_SHADER_BIT
- If the
tessellation shaders
feature is not enabled,
stageMask
must not containPIPELINE_STAGE_TESSELLATION_CONTROL_SHADER_BIT
orPIPELINE_STAGE_TESSELLATION_EVALUATION_SHADER_BIT
- If the
conditional rendering
feature is not enabled,
stageMask
must not containPIPELINE_STAGE_CONDITIONAL_RENDERING_BIT_EXT
- If the
fragment density map
feature is not enabled,
stageMask
must not containPIPELINE_STAGE_FRAGMENT_DENSITY_PROCESS_BIT_EXT
- If the
transform feedback
feature is not enabled,
stageMask
must not containPIPELINE_STAGE_TRANSFORM_FEEDBACK_BIT_EXT
- If the
mesh shaders
feature is not enabled,
stageMask
must not containPIPELINE_STAGE_MESH_SHADER_BIT_NV
- If the
task shaders
feature is not enabled,
stageMask
must not containPIPELINE_STAGE_TASK_SHADER_BIT_NV
- If the
shading rate image
feature is not enabled,
stageMask
must not containPIPELINE_STAGE_SHADING_RATE_IMAGE_BIT_NV
- Any pipeline stage included in
stageMask
must be supported by the capabilities of the queue family specified by thequeueFamilyIndex
member of theCommandPoolCreateInfo
structure that was used to create theCommandPool
thatcommandBuffer
was allocated from, as specified in the table of supported pipeline stages stageMask
must not includePIPELINE_STAGE_HOST_BIT
- When this command executes,
event
must not be waited on by acmdWaitEvents
command that is currently executing commandBuffer
’s current device mask must include exactly one physical device
Valid Usage (Implicit)
commandBuffer
must be a validCommandBuffer
handle
event
must be a validEvent
handlestageMask
must be a valid combination ofPipelineStageFlagBits
valuesstageMask
must not be0
commandBuffer
must be in the recording state- The
CommandPool
thatcommandBuffer
was allocated from must support graphics, or compute operations - This command must only be called outside of a render pass instance
- Both of
commandBuffer
, andevent
must have been created, allocated, or retrieved from the sameDevice
Host Synchronization
- Host access to
commandBuffer
must be externally synchronized
- Host access to the
CommandPool
thatcommandBuffer
was allocated from must be externally synchronized
Command Properties
'
Command Buffer Levels | Render Pass Scope | Supported Queue Types | Pipeline Type |
---|---|---|---|
Primary Secondary | Outside | Graphics Compute |
See Also
Arguments
:: forall io. MonadIO io | |
=> CommandBuffer |
|
-> ("events" ::: Vector Event) |
|
-> ("srcStageMask" ::: PipelineStageFlags) |
|
-> ("dstStageMask" ::: PipelineStageFlags) |
|
-> ("memoryBarriers" ::: Vector MemoryBarrier) |
|
-> ("bufferMemoryBarriers" ::: Vector BufferMemoryBarrier) |
|
-> ("imageMemoryBarriers" ::: Vector (SomeStruct ImageMemoryBarrier)) |
|
-> io () |
vkCmdWaitEvents - Wait for one or more events and insert a set of memory
Description
When cmdWaitEvents
is submitted to a queue, it defines a memory
dependency between prior event signal operations on the same queue or
the host, and subsequent commands. cmdWaitEvents
must not be used to
wait on event signal operations occurring on other queues.
The first synchronization scope only includes event signal operations
that operate on members of pEvents
, and the operations that
happened-before the event signal operations. Event signal operations
performed by cmdSetEvent
that occur earlier in
submission order
are included in the first synchronization scope, if the
logically latest
pipeline stage in their stageMask
parameter is
logically earlier
than or equal to the
logically latest
pipeline stage in srcStageMask
. Event signal operations performed by
setEvent
are only included in the first
synchronization scope if
PIPELINE_STAGE_HOST_BIT
is
included in srcStageMask
.
The second
synchronization scope
includes all commands that occur later in
submission order.
The second synchronization scope is limited to operations on the
pipeline stages determined by the
destination stage mask
specified by dstStageMask
.
The first
access scope
is limited to access in the pipeline stages determined by the
source stage mask
specified by srcStageMask
. Within that, the first access scope only
includes the first access scopes defined by elements of the
pMemoryBarriers
, pBufferMemoryBarriers
and pImageMemoryBarriers
arrays, which each define a set of
memory barriers.
If no memory barriers are specified, then the first access scope
includes no accesses.
The second
access scope
is limited to access in the pipeline stages determined by the
destination stage mask
specified by dstStageMask
. Within that, the second access scope only
includes the second access scopes defined by elements of the
pMemoryBarriers
, pBufferMemoryBarriers
and pImageMemoryBarriers
arrays, which each define a set of
memory barriers.
If no memory barriers are specified, then the second access scope
includes no accesses.
Note
cmdWaitEvents
is used with cmdSetEvent
to define a memory dependency
between two sets of action commands, roughly in the same way as pipeline
barriers, but split into two commands such that work between the two
may execute unhindered.
Unlike cmdPipelineBarrier
, a
queue family ownership transfer
cannot be performed using cmdWaitEvents
.
Note
Applications should be careful to avoid race conditions when using
events. There is no direct ordering guarantee between a cmdResetEvent
command and a cmdWaitEvents
command submitted after it. Another
execution dependency (e.g. a pipeline barrier or semaphore with
PIPELINE_STAGE_ALL_COMMANDS_BIT
)
is needed to prevent such a race condition.
Valid Usage
- If the
geometry shaders
feature is not enabled,
srcStageMask
must not containPIPELINE_STAGE_GEOMETRY_SHADER_BIT
- If the
tessellation shaders
feature is not enabled,
srcStageMask
must not containPIPELINE_STAGE_TESSELLATION_CONTROL_SHADER_BIT
orPIPELINE_STAGE_TESSELLATION_EVALUATION_SHADER_BIT
- If the
conditional rendering
feature is not enabled,
srcStageMask
must not containPIPELINE_STAGE_CONDITIONAL_RENDERING_BIT_EXT
- If the
fragment density map
feature is not enabled,
srcStageMask
must not containPIPELINE_STAGE_FRAGMENT_DENSITY_PROCESS_BIT_EXT
- If the
transform feedback
feature is not enabled,
srcStageMask
must not containPIPELINE_STAGE_TRANSFORM_FEEDBACK_BIT_EXT
- If the
mesh shaders
feature is not enabled,
srcStageMask
must not containPIPELINE_STAGE_MESH_SHADER_BIT_NV
- If the
task shaders
feature is not enabled,
srcStageMask
must not containPIPELINE_STAGE_TASK_SHADER_BIT_NV
- If the
shading rate image
feature is not enabled,
srcStageMask
must not containPIPELINE_STAGE_SHADING_RATE_IMAGE_BIT_NV
- Any pipeline stage included in
srcStageMask
must be supported by the capabilities of the queue family specified by thequeueFamilyIndex
member of theCommandPoolCreateInfo
structure that was used to create theCommandPool
thatcommandBuffer
was allocated from, as specified in the table of supported pipeline stages - If the
geometry shaders
feature is not enabled,
dstStageMask
must not containPIPELINE_STAGE_GEOMETRY_SHADER_BIT
- If the
tessellation shaders
feature is not enabled,
dstStageMask
must not containPIPELINE_STAGE_TESSELLATION_CONTROL_SHADER_BIT
orPIPELINE_STAGE_TESSELLATION_EVALUATION_SHADER_BIT
- If the
conditional rendering
feature is not enabled,
dstStageMask
must not containPIPELINE_STAGE_CONDITIONAL_RENDERING_BIT_EXT
- If the
fragment density map
feature is not enabled,
dstStageMask
must not containPIPELINE_STAGE_FRAGMENT_DENSITY_PROCESS_BIT_EXT
- If the
transform feedback
feature is not enabled,
dstStageMask
must not containPIPELINE_STAGE_TRANSFORM_FEEDBACK_BIT_EXT
- If the
mesh shaders
feature is not enabled,
dstStageMask
must not containPIPELINE_STAGE_MESH_SHADER_BIT_NV
- If the
task shaders
feature is not enabled,
dstStageMask
must not containPIPELINE_STAGE_TASK_SHADER_BIT_NV
- If the
shading rate image
feature is not enabled,
dstStageMask
must not containPIPELINE_STAGE_SHADING_RATE_IMAGE_BIT_NV
- Any pipeline stage included in
dstStageMask
must be supported by the capabilities of the queue family specified by thequeueFamilyIndex
member of theCommandPoolCreateInfo
structure that was used to create theCommandPool
thatcommandBuffer
was allocated from, as specified in the table of supported pipeline stages - The
srcAccessMask
member of each element ofpMemoryBarriers
must only include access flags that are supported by one or more of the pipeline stages insrcStageMask
, as specified in the table of supported access types - The
dstAccessMask
member of each element ofpMemoryBarriers
must only include access flags that are supported by one or more of the pipeline stages indstStageMask
, as specified in the table of supported access types - For any element of
pBufferMemoryBarriers
, if itssrcQueueFamilyIndex
anddstQueueFamilyIndex
members are equal, or if itssrcQueueFamilyIndex
is the queue family index that was used to create the command pool thatcommandBuffer
was allocated from, then itssrcAccessMask
member must only contain access flags that are supported by one or more of the pipeline stages insrcStageMask
, as specified in the table of supported access types - For any element of
pBufferMemoryBarriers
, if itssrcQueueFamilyIndex
anddstQueueFamilyIndex
members are equal, or if itsdstQueueFamilyIndex
is the queue family index that was used to create the command pool thatcommandBuffer
was allocated from, then itsdstAccessMask
member must only contain access flags that are supported by one or more of the pipeline stages indstStageMask
, as specified in the table of supported access types - For any element of
pImageMemoryBarriers
, if itssrcQueueFamilyIndex
anddstQueueFamilyIndex
members are equal, or if itssrcQueueFamilyIndex
is the queue family index that was used to create the command pool thatcommandBuffer
was allocated from, then itssrcAccessMask
member must only contain access flags that are supported by one or more of the pipeline stages insrcStageMask
, as specified in the table of supported access types - For any element of
pImageMemoryBarriers
, if itssrcQueueFamilyIndex
anddstQueueFamilyIndex
members are equal, or if itsdstQueueFamilyIndex
is the queue family index that was used to create the command pool thatcommandBuffer
was allocated from, then itsdstAccessMask
member must only contain access flags that are supported by one or more of the pipeline stages indstStageMask
, as specified in the table of supported access types srcStageMask
must be the bitwise OR of thestageMask
parameter used in previous calls tocmdSetEvent
with any of the members ofpEvents
andPIPELINE_STAGE_HOST_BIT
if any of the members ofpEvents
was set usingsetEvent
- If
pEvents
includes one or more events that will be signaled bysetEvent
aftercommandBuffer
has been submitted to a queue, thencmdWaitEvents
must not be called inside a render pass instance - The
srcQueueFamilyIndex
anddstQueueFamilyIndex
members of any element ofpBufferMemoryBarriers
orpImageMemoryBarriers
must be equal commandBuffer
’s current device mask must include exactly one physical device
Valid Usage (Implicit)
commandBuffer
must be a validCommandBuffer
handle
pEvents
must be a valid pointer to an array ofeventCount
validEvent
handlessrcStageMask
must be a valid combination ofPipelineStageFlagBits
valuessrcStageMask
must not be0
dstStageMask
must be a valid combination ofPipelineStageFlagBits
valuesdstStageMask
must not be0
- If
memoryBarrierCount
is not0
,pMemoryBarriers
must be a valid pointer to an array ofmemoryBarrierCount
validMemoryBarrier
structures - If
bufferMemoryBarrierCount
is not0
,pBufferMemoryBarriers
must be a valid pointer to an array ofbufferMemoryBarrierCount
validBufferMemoryBarrier
structures - If
imageMemoryBarrierCount
is not0
,pImageMemoryBarriers
must be a valid pointer to an array ofimageMemoryBarrierCount
validImageMemoryBarrier
structures commandBuffer
must be in the recording state- The
CommandPool
thatcommandBuffer
was allocated from must support graphics, or compute operations eventCount
must be greater than0
- Both of
commandBuffer
, and the elements ofpEvents
must have been created, allocated, or retrieved from the sameDevice
Host Synchronization
- Host access to
commandBuffer
must be externally synchronized
- Host access to the
CommandPool
thatcommandBuffer
was allocated from must be externally synchronized
Command Properties
'
Command Buffer Levels | Render Pass Scope | Supported Queue Types | Pipeline Type |
---|---|---|---|
Primary Secondary | Both | Graphics Compute |
See Also
BufferMemoryBarrier
,
CommandBuffer
, Event
,
ImageMemoryBarrier
,
MemoryBarrier
,
PipelineStageFlags
Arguments
:: forall io. MonadIO io | |
=> CommandBuffer |
|
-> ("events" ::: Vector Event) |
|
-> ("srcStageMask" ::: PipelineStageFlags) |
|
-> ("dstStageMask" ::: PipelineStageFlags) |
|
-> ("memoryBarriers" ::: Vector MemoryBarrier) |
|
-> ("bufferMemoryBarriers" ::: Vector BufferMemoryBarrier) |
|
-> ("imageMemoryBarriers" ::: Vector (SomeStruct ImageMemoryBarrier)) |
|
-> io () |
A variant of cmdWaitEvents
which makes a *safe* FFI call
Arguments
:: forall io. MonadIO io | |
=> CommandBuffer |
|
-> ("srcStageMask" ::: PipelineStageFlags) |
|
-> ("dstStageMask" ::: PipelineStageFlags) |
|
-> DependencyFlags |
|
-> ("memoryBarriers" ::: Vector MemoryBarrier) |
|
-> ("bufferMemoryBarriers" ::: Vector BufferMemoryBarrier) |
|
-> ("imageMemoryBarriers" ::: Vector (SomeStruct ImageMemoryBarrier)) |
|
-> io () |
vkCmdPipelineBarrier - Insert a memory dependency
Description
When cmdPipelineBarrier
is submitted to a queue, it defines a memory
dependency between commands that were submitted before it, and those
submitted after it.
If cmdPipelineBarrier
was recorded outside a render pass instance, the
first
synchronization scope
includes all commands that occur earlier in
submission order.
If cmdPipelineBarrier
was recorded inside a render pass instance, the
first synchronization scope includes only commands that occur earlier in
submission order
within the same subpass. In either case, the first synchronization scope
is limited to operations on the pipeline stages determined by the
source stage mask
specified by srcStageMask
.
If cmdPipelineBarrier
was recorded outside a render pass instance, the
second
synchronization scope
includes all commands that occur later in
submission order.
If cmdPipelineBarrier
was recorded inside a render pass instance, the
second synchronization scope includes only commands that occur later in
submission order
within the same subpass. In either case, the second synchronization
scope is limited to operations on the pipeline stages determined by the
destination stage mask
specified by dstStageMask
.
The first
access scope
is limited to access in the pipeline stages determined by the
source stage mask
specified by srcStageMask
. Within that, the first access scope only
includes the first access scopes defined by elements of the
pMemoryBarriers
, pBufferMemoryBarriers
and pImageMemoryBarriers
arrays, which each define a set of
memory barriers.
If no memory barriers are specified, then the first access scope
includes no accesses.
The second
access scope
is limited to access in the pipeline stages determined by the
destination stage mask
specified by dstStageMask
. Within that, the second access scope only
includes the second access scopes defined by elements of the
pMemoryBarriers
, pBufferMemoryBarriers
and pImageMemoryBarriers
arrays, which each define a set of
memory barriers.
If no memory barriers are specified, then the second access scope
includes no accesses.
If dependencyFlags
includes
DEPENDENCY_BY_REGION_BIT
, then
any dependency between
framebuffer-space
pipeline stages is
framebuffer-local
- otherwise it is
framebuffer-global.
Valid Usage
- If the
geometry shaders
feature is not enabled,
srcStageMask
must not containPIPELINE_STAGE_GEOMETRY_SHADER_BIT
- If the
tessellation shaders
feature is not enabled,
srcStageMask
must not containPIPELINE_STAGE_TESSELLATION_CONTROL_SHADER_BIT
orPIPELINE_STAGE_TESSELLATION_EVALUATION_SHADER_BIT
- If the
conditional rendering
feature is not enabled,
srcStageMask
must not containPIPELINE_STAGE_CONDITIONAL_RENDERING_BIT_EXT
- If the
fragment density map
feature is not enabled,
srcStageMask
must not containPIPELINE_STAGE_FRAGMENT_DENSITY_PROCESS_BIT_EXT
- If the
transform feedback
feature is not enabled,
srcStageMask
must not containPIPELINE_STAGE_TRANSFORM_FEEDBACK_BIT_EXT
- If the
mesh shaders
feature is not enabled,
srcStageMask
must not containPIPELINE_STAGE_MESH_SHADER_BIT_NV
- If the
task shaders
feature is not enabled,
srcStageMask
must not containPIPELINE_STAGE_TASK_SHADER_BIT_NV
- If the
shading rate image
feature is not enabled,
srcStageMask
must not containPIPELINE_STAGE_SHADING_RATE_IMAGE_BIT_NV
- Any pipeline stage included in
srcStageMask
must be supported by the capabilities of the queue family specified by thequeueFamilyIndex
member of theCommandPoolCreateInfo
structure that was used to create theCommandPool
thatcommandBuffer
was allocated from, as specified in the table of supported pipeline stages - If the
geometry shaders
feature is not enabled,
dstStageMask
must not containPIPELINE_STAGE_GEOMETRY_SHADER_BIT
- If the
tessellation shaders
feature is not enabled,
dstStageMask
must not containPIPELINE_STAGE_TESSELLATION_CONTROL_SHADER_BIT
orPIPELINE_STAGE_TESSELLATION_EVALUATION_SHADER_BIT
- If the
conditional rendering
feature is not enabled,
dstStageMask
must not containPIPELINE_STAGE_CONDITIONAL_RENDERING_BIT_EXT
- If the
fragment density map
feature is not enabled,
dstStageMask
must not containPIPELINE_STAGE_FRAGMENT_DENSITY_PROCESS_BIT_EXT
- If the
transform feedback
feature is not enabled,
dstStageMask
must not containPIPELINE_STAGE_TRANSFORM_FEEDBACK_BIT_EXT
- If the
mesh shaders
feature is not enabled,
dstStageMask
must not containPIPELINE_STAGE_MESH_SHADER_BIT_NV
- If the
task shaders
feature is not enabled,
dstStageMask
must not containPIPELINE_STAGE_TASK_SHADER_BIT_NV
- If the
shading rate image
feature is not enabled,
dstStageMask
must not containPIPELINE_STAGE_SHADING_RATE_IMAGE_BIT_NV
- Any pipeline stage included in
dstStageMask
must be supported by the capabilities of the queue family specified by thequeueFamilyIndex
member of theCommandPoolCreateInfo
structure that was used to create theCommandPool
thatcommandBuffer
was allocated from, as specified in the table of supported pipeline stages - The
srcAccessMask
member of each element ofpMemoryBarriers
must only include access flags that are supported by one or more of the pipeline stages insrcStageMask
, as specified in the table of supported access types - The
dstAccessMask
member of each element ofpMemoryBarriers
must only include access flags that are supported by one or more of the pipeline stages indstStageMask
, as specified in the table of supported access types - For any element of
pBufferMemoryBarriers
, if itssrcQueueFamilyIndex
anddstQueueFamilyIndex
members are equal, or if itssrcQueueFamilyIndex
is the queue family index that was used to create the command pool thatcommandBuffer
was allocated from, then itssrcAccessMask
member must only contain access flags that are supported by one or more of the pipeline stages insrcStageMask
, as specified in the table of supported access types - For any element of
pBufferMemoryBarriers
, if itssrcQueueFamilyIndex
anddstQueueFamilyIndex
members are equal, or if itsdstQueueFamilyIndex
is the queue family index that was used to create the command pool thatcommandBuffer
was allocated from, then itsdstAccessMask
member must only contain access flags that are supported by one or more of the pipeline stages indstStageMask
, as specified in the table of supported access types - For any element of
pImageMemoryBarriers
, if itssrcQueueFamilyIndex
anddstQueueFamilyIndex
members are equal, or if itssrcQueueFamilyIndex
is the queue family index that was used to create the command pool thatcommandBuffer
was allocated from, then itssrcAccessMask
member must only contain access flags that are supported by one or more of the pipeline stages insrcStageMask
, as specified in the table of supported access types - For any element of
pImageMemoryBarriers
, if itssrcQueueFamilyIndex
anddstQueueFamilyIndex
members are equal, or if itsdstQueueFamilyIndex
is the queue family index that was used to create the command pool thatcommandBuffer
was allocated from, then itsdstAccessMask
member must only contain access flags that are supported by one or more of the pipeline stages indstStageMask
, as specified in the table of supported access types - If
cmdPipelineBarrier
is called within a render pass instance, the render pass must have been created with at least oneSubpassDependency
instance inRenderPassCreateInfo
::pDependencies
that expresses a dependency from the current subpass to itself, with synchronization scopes and access scopes that are all supersets of the scopes defined in this command - If
cmdPipelineBarrier
is called within a render pass instance, it must not include any buffer memory barriers - If
cmdPipelineBarrier
is called within a render pass instance, theimage
member of any image memory barrier included in this command must be an attachment used in the current subpass both as an input attachment, and as either a color or depth/stencil attachment - If
cmdPipelineBarrier
is called within a render pass instance, theoldLayout
andnewLayout
members of any image memory barrier included in this command must be equal - If
cmdPipelineBarrier
is called within a render pass instance, thesrcQueueFamilyIndex
anddstQueueFamilyIndex
members of any image memory barrier included in this command must be equal - If
cmdPipelineBarrier
is called outside of a render pass instance,DEPENDENCY_VIEW_LOCAL_BIT
must not be included in the dependency flags
Valid Usage (Implicit)
commandBuffer
must be a validCommandBuffer
handle
srcStageMask
must be a valid combination ofPipelineStageFlagBits
valuessrcStageMask
must not be0
dstStageMask
must be a valid combination ofPipelineStageFlagBits
valuesdstStageMask
must not be0
dependencyFlags
must be a valid combination ofDependencyFlagBits
values- If
memoryBarrierCount
is not0
,pMemoryBarriers
must be a valid pointer to an array ofmemoryBarrierCount
validMemoryBarrier
structures - If
bufferMemoryBarrierCount
is not0
,pBufferMemoryBarriers
must be a valid pointer to an array ofbufferMemoryBarrierCount
validBufferMemoryBarrier
structures - If
imageMemoryBarrierCount
is not0
,pImageMemoryBarriers
must be a valid pointer to an array ofimageMemoryBarrierCount
validImageMemoryBarrier
structures commandBuffer
must be in the recording state- The
CommandPool
thatcommandBuffer
was allocated from must support transfer, graphics, or compute operations
Host Synchronization
- Host access to
commandBuffer
must be externally synchronized
- Host access to the
CommandPool
thatcommandBuffer
was allocated from must be externally synchronized
Command Properties
'
Command Buffer Levels | Render Pass Scope | Supported Queue Types | Pipeline Type |
---|---|---|---|
Primary Secondary | Both | Transfer Graphics Compute |
See Also
BufferMemoryBarrier
,
CommandBuffer
,
DependencyFlags
,
ImageMemoryBarrier
,
MemoryBarrier
,
PipelineStageFlags
Arguments
:: forall io. MonadIO io | |
=> CommandBuffer |
|
-> QueryPool |
|
-> ("query" ::: Word32) |
|
-> QueryControlFlags |
|
-> io () |
vkCmdBeginQuery - Begin a query
Description
If the queryType
of the pool is
QUERY_TYPE_OCCLUSION
and flags
contains
QUERY_CONTROL_PRECISE_BIT
, an
implementation must return a result that matches the actual number of
samples passed. This is described in more detail in
Occlusion Queries.
Calling cmdBeginQuery
is equivalent to calling
cmdBeginQueryIndexedEXT
with the index
parameter set to zero.
After beginning a query, that query is considered active within the command buffer it was called in until that same query is ended. Queries active in a primary command buffer when secondary command buffers are executed are considered active for those secondary command buffers.
Valid Usage
queryPool
must have been created with aqueryType
that differs from that of any queries that are active withincommandBuffer
- All queries used by the command must be unavailable
- The
queryType
used to createqueryPool
must not beQUERY_TYPE_TIMESTAMP
- If the
precise occlusion queries
feature is not enabled, or the
queryType
used to createqueryPool
was notQUERY_TYPE_OCCLUSION
,flags
must not containQUERY_CONTROL_PRECISE_BIT
query
must be less than the number of queries inqueryPool
- If the
queryType
used to createqueryPool
wasQUERY_TYPE_OCCLUSION
, theCommandPool
thatcommandBuffer
was allocated from must support graphics operations - If the
queryType
used to createqueryPool
wasQUERY_TYPE_PIPELINE_STATISTICS
and any of thepipelineStatistics
indicate graphics operations, theCommandPool
thatcommandBuffer
was allocated from must support graphics operations - If the
queryType
used to createqueryPool
wasQUERY_TYPE_PIPELINE_STATISTICS
and any of thepipelineStatistics
indicate compute operations, theCommandPool
thatcommandBuffer
was allocated from must support compute operations commandBuffer
must not be a protected command buffer- If called within a render pass instance, the sum of
query
and the number of bits set in the current subpass’s view mask must be less than or equal to the number of queries inqueryPool
- If the
queryType
used to createqueryPool
wasQUERY_TYPE_TRANSFORM_FEEDBACK_STREAM_EXT
theCommandPool
thatcommandBuffer
was allocated from must support graphics operations - If the
queryType
used to createqueryPool
wasQUERY_TYPE_TRANSFORM_FEEDBACK_STREAM_EXT
thenPhysicalDeviceTransformFeedbackPropertiesEXT
::transformFeedbackQueries
must be supported - If
queryPool
was created with aqueryType
ofQUERY_TYPE_PERFORMANCE_QUERY_KHR
, the profiling lock must have been held beforebeginCommandBuffer
was called oncommandBuffer
- If
queryPool
was created with aqueryType
ofQUERY_TYPE_PERFORMANCE_QUERY_KHR
and one of the counters used to createqueryPool
wasPERFORMANCE_COUNTER_SCOPE_COMMAND_BUFFER_KHR
, the query begin must be the first recorded command incommandBuffer
- If
queryPool
was created with aqueryType
ofQUERY_TYPE_PERFORMANCE_QUERY_KHR
and one of the counters used to createqueryPool
wasPERFORMANCE_COUNTER_SCOPE_RENDER_PASS_KHR
, the begin command must not be recorded within a render pass instance - If
queryPool
was created with aqueryType
ofQUERY_TYPE_PERFORMANCE_QUERY_KHR
and another query pool with aqueryType
QUERY_TYPE_PERFORMANCE_QUERY_KHR
has been used withincommandBuffer
, its parent primary command buffer or secondary command buffer recorded within the same parent primary command buffer ascommandBuffer
, the performanceCounterMultipleQueryPools feature must be enabled - If
queryPool
was created with aqueryType
ofQUERY_TYPE_PERFORMANCE_QUERY_KHR
, this command must not be recorded in a command buffer that, either directly or through secondary command buffers, also contains acmdResetQueryPool
command affecting the same query
Valid Usage (Implicit)
commandBuffer
must be a validCommandBuffer
handle
queryPool
must be a validQueryPool
handleflags
must be a valid combination ofQueryControlFlagBits
valuescommandBuffer
must be in the recording state- The
CommandPool
thatcommandBuffer
was allocated from must support graphics, or compute operations - Both of
commandBuffer
, andqueryPool
must have been created, allocated, or retrieved from the sameDevice
Host Synchronization
- Host access to
commandBuffer
must be externally synchronized
- Host access to the
CommandPool
thatcommandBuffer
was allocated from must be externally synchronized
Command Properties
'
Command Buffer Levels | Render Pass Scope | Supported Queue Types | Pipeline Type |
---|---|---|---|
Primary Secondary | Both | Graphics Compute |
See Also
cmdUseQuery :: forall io r. MonadIO io => CommandBuffer -> QueryPool -> Word32 -> QueryControlFlags -> io r -> io r Source #
This function will call the supplied action between calls to
cmdBeginQuery
and cmdEndQuery
Note that cmdEndQuery
is *not* called if an exception is thrown by the
inner action.
Arguments
:: forall io. MonadIO io | |
=> CommandBuffer |
|
-> QueryPool |
|
-> ("query" ::: Word32) |
|
-> io () |
vkCmdEndQuery - Ends a query
Description
Calling cmdEndQuery
is equivalent to calling
cmdEndQueryIndexedEXT
with
the index
parameter set to zero.
As queries operate asynchronously, ending a query does not immediately
set the query’s status to available. A query is considered finished
when the final results of the query are ready to be retrieved by
getQueryPoolResults
and cmdCopyQueryPoolResults
,
and this is when the query’s status is set to available.
Once a query is ended the query must finish in finite time, unless the state of the query is changed using other commands, e.g. by issuing a reset of the query.
Valid Usage
- All queries used by the command must be active
query
must be less than the number of queries inqueryPool
commandBuffer
must not be a protected command buffer- If
cmdEndQuery
is called within a render pass instance, the sum ofquery
and the number of bits set in the current subpass’s view mask must be less than or equal to the number of queries inqueryPool
- If
queryPool
was created with aqueryType
ofQUERY_TYPE_PERFORMANCE_QUERY_KHR
and one or more of the counters used to createqueryPool
wasPERFORMANCE_COUNTER_SCOPE_COMMAND_BUFFER_KHR
, thecmdEndQuery
must be the last recorded command incommandBuffer
- If
queryPool
was created with aqueryType
ofQUERY_TYPE_PERFORMANCE_QUERY_KHR
and one or more of the counters used to createqueryPool
wasPERFORMANCE_COUNTER_SCOPE_RENDER_PASS_KHR
, thecmdEndQuery
must not be recorded within a render pass instance
Valid Usage (Implicit)
commandBuffer
must be a validCommandBuffer
handle
queryPool
must be a validQueryPool
handlecommandBuffer
must be in the recording state- The
CommandPool
thatcommandBuffer
was allocated from must support graphics, or compute operations - Both of
commandBuffer
, andqueryPool
must have been created, allocated, or retrieved from the sameDevice
Host Synchronization
- Host access to
commandBuffer
must be externally synchronized
- Host access to the
CommandPool
thatcommandBuffer
was allocated from must be externally synchronized
Command Properties
'
Command Buffer Levels | Render Pass Scope | Supported Queue Types | Pipeline Type |
---|---|---|---|
Primary Secondary | Both | Graphics Compute |
See Also
Arguments
:: forall io. MonadIO io | |
=> CommandBuffer |
|
-> QueryPool |
|
-> ("firstQuery" ::: Word32) |
|
-> ("queryCount" ::: Word32) |
|
-> io () |
vkCmdResetQueryPool - Reset queries in a query pool
Description
When executed on a queue, this command sets the status of query indices
[firstQuery
, firstQuery
+ queryCount
- 1] to unavailable.
If the queryType
used to create queryPool
was
QUERY_TYPE_PERFORMANCE_QUERY_KHR
, this
command sets the status of query indices [firstQuery
, firstQuery
+
queryCount
- 1] to unavailable for each pass of queryPool
, as
indicated by a call to
getPhysicalDeviceQueueFamilyPerformanceQueryPassesKHR
.
Note
Because cmdResetQueryPool
resets all the passes of the indicated
queries, applications must not record a cmdResetQueryPool
command for
a queryPool
created with
QUERY_TYPE_PERFORMANCE_QUERY_KHR
in a
command buffer that needs to be submitted multiple times as indicated by
a call to
getPhysicalDeviceQueueFamilyPerformanceQueryPassesKHR
.
Otherwise applications will never be able to complete the recorded
queries.
Valid Usage
firstQuery
must be less than the number of queries inqueryPool
- The sum of
firstQuery
andqueryCount
must be less than or equal to the number of queries inqueryPool
- All queries used by the command must not be active
- If
queryPool
was created withQUERY_TYPE_PERFORMANCE_QUERY_KHR
, this command must not be recorded in a command buffer that, either directly or through secondary command buffers, also contains begin commands for a query from the set of queries [firstQuery
,firstQuery
+queryCount
- 1]
Valid Usage (Implicit)
commandBuffer
must be a validCommandBuffer
handle
queryPool
must be a validQueryPool
handlecommandBuffer
must be in the recording state- The
CommandPool
thatcommandBuffer
was allocated from must support graphics, or compute operations - This command must only be called outside of a render pass instance
- Both of
commandBuffer
, andqueryPool
must have been created, allocated, or retrieved from the sameDevice
Host Synchronization
- Host access to
commandBuffer
must be externally synchronized
- Host access to the
CommandPool
thatcommandBuffer
was allocated from must be externally synchronized
Command Properties
'
Command Buffer Levels | Render Pass Scope | Supported Queue Types | Pipeline Type |
---|---|---|---|
Primary Secondary | Outside | Graphics Compute |
See Also
Arguments
:: forall io. MonadIO io | |
=> CommandBuffer |
|
-> PipelineStageFlagBits |
|
-> QueryPool |
|
-> ("query" ::: Word32) |
|
-> io () |
vkCmdWriteTimestamp - Write a device timestamp into a query object
Description
cmdWriteTimestamp
latches the value of the timer when all previous
commands have completed executing as far as the specified pipeline
stage, and writes the timestamp value to memory. When the timestamp
value is written, the availability status of the query is set to
available.
Note
If an implementation is unable to detect completion and latch the timer at any specific stage of the pipeline, it may instead do so at any logically later stage.
Timestamps may only be meaningfully compared if they are written by commands submitted to the same queue.
Note
An example of such a comparison is determining the execution time of a sequence of commands.
If cmdWriteTimestamp
is called while executing a render pass instance
that has multiview enabled, the timestamp uses N consecutive query
indices in the query pool (starting at query
) where N is the number of
bits set in the view mask of the subpass the command is executed in. The
resulting query values are determined by an implementation-dependent
choice of one of the following behaviors:
- The first query is a timestamp value and (if more than one bit is set in the view mask) zero is written to the remaining queries. If two timestamps are written in the same subpass, the sum of the execution time of all views between those commands is the difference between the first query written by each command.
- All N queries are timestamp values. If two timestamps are written in the same subpass, the sum of the execution time of all views between those commands is the sum of the difference between corresponding queries written by each command. The difference between corresponding queries may be the execution time of a single view.
In either case, the application can sum the differences between all N queries to determine the total execution time.
Valid Usage
pipelineStage
must be a valid stage for the queue family that was used to create the command pool thatcommandBuffer
was allocated from
- If the
geometry shaders
feature is not enabled,
pipelineStage
must not bePIPELINE_STAGE_GEOMETRY_SHADER_BIT
- If the
tessellation shaders
feature is not enabled,
pipelineStage
must not bePIPELINE_STAGE_TESSELLATION_CONTROL_SHADER_BIT
orPIPELINE_STAGE_TESSELLATION_EVALUATION_SHADER_BIT
- If the
conditional rendering
feature is not enabled,
pipelineStage
must not bePIPELINE_STAGE_CONDITIONAL_RENDERING_BIT_EXT
- If the
fragment density map
feature is not enabled,
pipelineStage
must not bePIPELINE_STAGE_FRAGMENT_DENSITY_PROCESS_BIT_EXT
- If the
transform feedback
feature is not enabled,
pipelineStage
must not bePIPELINE_STAGE_TRANSFORM_FEEDBACK_BIT_EXT
- If the
mesh shaders
feature is not enabled,
pipelineStage
must not bePIPELINE_STAGE_MESH_SHADER_BIT_NV
orPIPELINE_STAGE_TASK_SHADER_BIT_NV
- If the
shading rate image
feature is not enabled,
pipelineStage
must not bePIPELINE_STAGE_SHADING_RATE_IMAGE_BIT_NV
queryPool
must have been created with aqueryType
ofQUERY_TYPE_TIMESTAMP
- The query identified by
queryPool
andquery
must be unavailable - The command pool’s queue family must support a non-zero
timestampValidBits
- All queries used by the command must be unavailable
- If
cmdWriteTimestamp
is called within a render pass instance, the sum ofquery
and the number of bits set in the current subpass’s view mask must be less than or equal to the number of queries inqueryPool
Valid Usage (Implicit)
commandBuffer
must be a validCommandBuffer
handle
pipelineStage
must be a validPipelineStageFlagBits
valuequeryPool
must be a validQueryPool
handlecommandBuffer
must be in the recording state- The
CommandPool
thatcommandBuffer
was allocated from must support transfer, graphics, or compute operations - Both of
commandBuffer
, andqueryPool
must have been created, allocated, or retrieved from the sameDevice
Host Synchronization
- Host access to
commandBuffer
must be externally synchronized
- Host access to the
CommandPool
thatcommandBuffer
was allocated from must be externally synchronized
Command Properties
'
Command Buffer Levels | Render Pass Scope | Supported Queue Types | Pipeline Type |
---|---|---|---|
Primary Secondary | Both | Transfer Graphics Compute | Transfer |
See Also
cmdCopyQueryPoolResults Source #
Arguments
:: forall io. MonadIO io | |
=> CommandBuffer |
|
-> QueryPool |
|
-> ("firstQuery" ::: Word32) |
|
-> ("queryCount" ::: Word32) |
|
-> ("dstBuffer" ::: Buffer) |
|
-> ("dstOffset" ::: DeviceSize) |
|
-> ("stride" ::: DeviceSize) |
|
-> QueryResultFlags |
|
-> io () |
vkCmdCopyQueryPoolResults - Copy the results of queries in a query pool to a buffer object
Description
cmdCopyQueryPoolResults
is guaranteed to see the effect of previous
uses of cmdResetQueryPool
in the same queue, without any additional
synchronization. Thus, the results will always reflect the most recent
use of the query.
flags
has the same possible values described above for the flags
parameter of getQueryPoolResults
, but the
different style of execution causes some subtle behavioral differences.
Because cmdCopyQueryPoolResults
executes in order with respect to
other query commands, there is less ambiguity about which use of a query
is being requested.
Results for all requested occlusion queries, pipeline statistics
queries, transform feedback queries, and timestamp queries are written
as 64-bit unsigned integer values if
QUERY_RESULT_64_BIT
is set or
32-bit unsigned integer values otherwise. Performance queries store
results in a tightly packed array whose type is determined by the unit
member of the corresponding
PerformanceCounterKHR
.
If neither of
QUERY_RESULT_WAIT_BIT
and
QUERY_RESULT_WITH_AVAILABILITY_BIT
are set, results are only written out for queries in the available
state.
If QUERY_RESULT_WAIT_BIT
is
set, the implementation will wait for each query’s status to be in the
available state before retrieving the numerical results for that query.
This is guaranteed to reflect the most recent use of the query on the
same queue, assuming that the query is not being simultaneously used by
other queues. If the query does not become available in a finite amount
of time (e.g. due to not issuing a query since the last reset), a
ERROR_DEVICE_LOST
error may occur.
Similarly, if
QUERY_RESULT_WITH_AVAILABILITY_BIT
is set and
QUERY_RESULT_WAIT_BIT
is not
set, the availability is guaranteed to reflect the most recent use of
the query on the same queue, assuming that the query is not being
simultaneously used by other queues. As with
getQueryPoolResults
, implementations must
guarantee that if they return a non-zero availability value, then the
numerical results are valid.
If QUERY_RESULT_PARTIAL_BIT
is
set, QUERY_RESULT_WAIT_BIT
is
not set, and the query’s status is unavailable, an intermediate result
value between zero and the final result value is written for that query.
QUERY_RESULT_PARTIAL_BIT
must not be used if the pool’s queryType
is
QUERY_TYPE_TIMESTAMP
.
cmdCopyQueryPoolResults
is considered to be a transfer operation, and
its writes to buffer memory must be synchronized using
PIPELINE_STAGE_TRANSFER_BIT
and ACCESS_TRANSFER_WRITE_BIT
before using the results.
Valid Usage
dstOffset
must be less than the size ofdstBuffer
firstQuery
must be less than the number of queries inqueryPool
- The sum of
firstQuery
andqueryCount
must be less than or equal to the number of queries inqueryPool
- If
QUERY_RESULT_64_BIT
is not set inflags
thendstOffset
andstride
must be multiples of4
- If
QUERY_RESULT_64_BIT
is set inflags
thendstOffset
andstride
must be multiples of8
dstBuffer
must have enough storage, fromdstOffset
, to contain the result of each query, as described heredstBuffer
must have been created withBUFFER_USAGE_TRANSFER_DST_BIT
usage flag- If
dstBuffer
is non-sparse then it must be bound completely and contiguously to a singleDeviceMemory
object - If the
queryType
used to createqueryPool
wasQUERY_TYPE_TIMESTAMP
,flags
must not containQUERY_RESULT_PARTIAL_BIT
- If the
queryType
used to createqueryPool
wasQUERY_TYPE_PERFORMANCE_QUERY_KHR
,PhysicalDevicePerformanceQueryPropertiesKHR
::allowCommandBufferQueryCopies
must beTRUE
- If the
queryType
used to createqueryPool
wasQUERY_TYPE_PERFORMANCE_QUERY_KHR
,flags
must not containQUERY_RESULT_WITH_AVAILABILITY_BIT
,QUERY_RESULT_PARTIAL_BIT
orQUERY_RESULT_64_BIT
- If the
queryType
used to createqueryPool
wasQUERY_TYPE_PERFORMANCE_QUERY_KHR
, thequeryPool
must have been submitted once for each pass as retrieved via a call togetPhysicalDeviceQueueFamilyPerformanceQueryPassesKHR
cmdCopyQueryPoolResults
must not be called if thequeryType
used to createqueryPool
wasQUERY_TYPE_PERFORMANCE_QUERY_INTEL
Valid Usage (Implicit)
commandBuffer
must be a validCommandBuffer
handle
queryPool
must be a validQueryPool
handledstBuffer
must be a validBuffer
handleflags
must be a valid combination ofQueryResultFlagBits
valuescommandBuffer
must be in the recording state- The
CommandPool
thatcommandBuffer
was allocated from must support graphics, or compute operations - This command must only be called outside of a render pass instance
- Each of
commandBuffer
,dstBuffer
, andqueryPool
must have been created, allocated, or retrieved from the sameDevice
Host Synchronization
- Host access to
commandBuffer
must be externally synchronized
- Host access to the
CommandPool
thatcommandBuffer
was allocated from must be externally synchronized
Command Properties
'
Command Buffer Levels | Render Pass Scope | Supported Queue Types | Pipeline Type |
---|---|---|---|
Primary Secondary | Outside | Graphics Compute | Transfer |
See Also
Buffer
, CommandBuffer
,
DeviceSize
,
QueryPool
,
QueryResultFlags
Arguments
:: forall io. MonadIO io | |
=> CommandBuffer |
|
-> PipelineLayout |
|
-> ShaderStageFlags |
|
-> ("offset" ::: Word32) |
|
-> ("size" ::: Word32) |
|
-> ("values" ::: Ptr ()) |
|
-> io () |
vkCmdPushConstants - Update the values of push constants
Description
Note
As stageFlags
needs to include all flags the relevant push constant
ranges were created with, any flags that are not supported by the queue
family that the CommandPool
used to allocate
commandBuffer
was created on are ignored.
Valid Usage
- For each byte in the range specified by
offset
andsize
and for each shader stage instageFlags
, there must be a push constant range inlayout
that includes that byte and that stage
- For each byte in the range specified by
offset
andsize
and for each push constant range that overlaps that byte,stageFlags
must include all stages in that push constant range’sPushConstantRange
::stageFlags
offset
must be a multiple of4
size
must be a multiple of4
offset
must be less thanPhysicalDeviceLimits
::maxPushConstantsSize
size
must be less than or equal toPhysicalDeviceLimits
::maxPushConstantsSize
minusoffset
Valid Usage (Implicit)
commandBuffer
must be a validCommandBuffer
handle
layout
must be a validPipelineLayout
handlestageFlags
must be a valid combination ofShaderStageFlagBits
valuesstageFlags
must not be0
pValues
must be a valid pointer to an array ofsize
bytescommandBuffer
must be in the recording state- The
CommandPool
thatcommandBuffer
was allocated from must support graphics, or compute operations size
must be greater than0
- Both of
commandBuffer
, andlayout
must have been created, allocated, or retrieved from the sameDevice
Host Synchronization
- Host access to
commandBuffer
must be externally synchronized
- Host access to the
CommandPool
thatcommandBuffer
was allocated from must be externally synchronized
Command Properties
'
Command Buffer Levels | Render Pass Scope | Supported Queue Types | Pipeline Type |
---|---|---|---|
Primary Secondary | Both | Graphics Compute |
See Also
Arguments
:: forall a io. (Extendss RenderPassBeginInfo a, PokeChain a, MonadIO io) | |
=> CommandBuffer |
|
-> RenderPassBeginInfo a |
|
-> SubpassContents |
|
-> io () |
vkCmdBeginRenderPass - Begin a new render pass
Description
After beginning a render pass instance, the command buffer is ready to record the commands for the first subpass of that render pass.
Valid Usage
- If any of the
initialLayout
orfinalLayout
member of theAttachmentDescription
structures or thelayout
member of theAttachmentReference
structures specified when creating the render pass specified in therenderPass
member ofpRenderPassBegin
isIMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL
then the corresponding attachment image view of the framebuffer specified in theframebuffer
member ofpRenderPassBegin
must have been created with ausage
value includingIMAGE_USAGE_COLOR_ATTACHMENT_BIT
- If any of the
initialLayout
orfinalLayout
member of theAttachmentDescription
structures or thelayout
member of theAttachmentReference
structures specified when creating the render pass specified in therenderPass
member ofpRenderPassBegin
isIMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL
,IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL
,IMAGE_LAYOUT_DEPTH_STENCIL_ATTACHMENT_OPTIMAL
, orIMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL
then the corresponding attachment image view of the framebuffer specified in theframebuffer
member ofpRenderPassBegin
must have been created with ausage
value includingIMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT
- If any of the
initialLayout
orfinalLayout
member of theAttachmentDescription
structures or thelayout
member of theAttachmentReference
structures specified when creating the render pass specified in therenderPass
member ofpRenderPassBegin
isIMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL
, orIMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL
,IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL
, orIMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL
then the corresponding attachment image view of the framebuffer specified in theframebuffer
member ofpRenderPassBegin
must have been created with ausage
value includingIMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT
- If any of the
stencilInitialLayout
orstencilFinalLayout
member of theAttachmentDescriptionStencilLayout
structures or thestencilLayout
member of theAttachmentReferenceStencilLayout
structures specified when creating the render pass specified in therenderPass
member ofpRenderPassBegin
isIMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL
, orIMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL
then the corresponding attachment image view of the framebuffer specified in theframebuffer
member ofpRenderPassBegin
must have been created with ausage
value includingIMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT
- If any of the
initialLayout
orfinalLayout
member of theAttachmentDescription
structures or thelayout
member of theAttachmentReference
structures specified when creating the render pass specified in therenderPass
member ofpRenderPassBegin
isIMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL
then the corresponding attachment image view of the framebuffer specified in theframebuffer
member ofpRenderPassBegin
must have been created with ausage
value includingIMAGE_USAGE_SAMPLED_BIT
orIMAGE_USAGE_INPUT_ATTACHMENT_BIT
- If any of the
initialLayout
orfinalLayout
member of theAttachmentDescription
structures or thelayout
member of theAttachmentReference
structures specified when creating the render pass specified in therenderPass
member ofpRenderPassBegin
isIMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL
then the corresponding attachment image view of the framebuffer specified in theframebuffer
member ofpRenderPassBegin
must have been created with ausage
value includingIMAGE_USAGE_TRANSFER_SRC_BIT
- If any of the
initialLayout
orfinalLayout
member of theAttachmentDescription
structures or thelayout
member of theAttachmentReference
structures specified when creating the render pass specified in therenderPass
member ofpRenderPassBegin
isIMAGE_LAYOUT_TRANSFER_DST_OPTIMAL
then the corresponding attachment image view of the framebuffer specified in theframebuffer
member ofpRenderPassBegin
must have been created with ausage
value includingIMAGE_USAGE_TRANSFER_DST_BIT
- If any of the
initialLayout
members of theAttachmentDescription
structures specified when creating the render pass specified in therenderPass
member ofpRenderPassBegin
is notIMAGE_LAYOUT_UNDEFINED
, then each suchinitialLayout
must be equal to the current layout of the corresponding attachment image subresource of the framebuffer specified in theframebuffer
member ofpRenderPassBegin
- The
srcStageMask
anddstStageMask
members of any element of thepDependencies
member ofRenderPassCreateInfo
used to createrenderPass
must be supported by the capabilities of the queue family identified by thequeueFamilyIndex
member of theCommandPoolCreateInfo
used to create the command pool whichcommandBuffer
was allocated from - For any attachment in
framebuffer
that is used byrenderPass
and is bound to memory locations that are also bound to another attachment used byrenderPass
, and if at least one of those uses causes either attachment to be written to, both attachments must have had theATTACHMENT_DESCRIPTION_MAY_ALIAS_BIT
set - Each element of the
pAttachments
offramebuffer
that is referenced by any element of thepInputAttachments
of any element ofpSubpasses
ofrenderPass
must have image view format features containing at leastFORMAT_FEATURE_COLOR_ATTACHMENT_BIT
orFORMAT_FEATURE_DEPTH_STENCIL_ATTACHMENT_BIT
- Each element of the
pAttachments
offramebuffer
that is referenced by any element of thepColorAttachments
of any element ofpSubpasses
ofrenderPass
must have image view format features containingFORMAT_FEATURE_COLOR_ATTACHMENT_BIT
- Each element of the
pAttachments
offramebuffer
that is referenced by any element of thepResolveAttachments
of any element ofpSubpasses
ofrenderPass
must have image view format features containingFORMAT_FEATURE_COLOR_ATTACHMENT_BIT
- Each element of the
pAttachments
offramebuffer
that is referenced by any element of thepDepthStencilAttachment
of any element ofpSubpasses
ofrenderPass
must have image view format features containingFORMAT_FEATURE_DEPTH_STENCIL_ATTACHMENT_BIT
Valid Usage (Implicit)
commandBuffer
must be a validCommandBuffer
handle
pRenderPassBegin
must be a valid pointer to a validRenderPassBeginInfo
structurecontents
must be a validSubpassContents
valuecommandBuffer
must be in the recording state- The
CommandPool
thatcommandBuffer
was allocated from must support graphics operations - This command must only be called outside of a render pass instance
commandBuffer
must be a primaryCommandBuffer
Host Synchronization
- Host access to
commandBuffer
must be externally synchronized
- Host access to the
CommandPool
thatcommandBuffer
was allocated from must be externally synchronized
Command Properties
'
Command Buffer Levels | Render Pass Scope | Supported Queue Types | Pipeline Type |
---|---|---|---|
Primary | Outside | Graphics | Graphics |
See Also
cmdUseRenderPass :: forall a io r. (Extendss RenderPassBeginInfo a, PokeChain a, MonadIO io) => CommandBuffer -> RenderPassBeginInfo a -> SubpassContents -> io r -> io r Source #
This function will call the supplied action between calls to
cmdBeginRenderPass
and cmdEndRenderPass
Note that cmdEndRenderPass
is *not* called if an exception is thrown
by the inner action.
Arguments
:: forall io. MonadIO io | |
=> CommandBuffer |
|
-> SubpassContents |
|
-> io () |
vkCmdNextSubpass - Transition to the next subpass of a render pass
Description
The subpass index for a render pass begins at zero when
cmdBeginRenderPass
is recorded, and increments each time
cmdNextSubpass
is recorded.
Moving to the next subpass automatically performs any multisample
resolve operations in the subpass being ended. End-of-subpass
multisample resolves are treated as color attachment writes for the
purposes of synchronization. This applies to resolve operations for both
color and depth/stencil attachments. That is, they are considered to
execute in the
PIPELINE_STAGE_COLOR_ATTACHMENT_OUTPUT_BIT
pipeline stage and their writes are synchronized with
ACCESS_COLOR_ATTACHMENT_WRITE_BIT
.
Synchronization between rendering within a subpass and any resolve
operations at the end of the subpass occurs automatically, without need
for explicit dependencies or pipeline barriers. However, if the resolve
attachment is also used in a different subpass, an explicit dependency
is needed.
After transitioning to the next subpass, the application can record the commands for that subpass.
Valid Usage
- The current subpass index must be less than the number of subpasses in the render pass minus one
- This command must not be recorded when transform feedback is active
Valid Usage (Implicit)
commandBuffer
must be a validCommandBuffer
handle
contents
must be a validSubpassContents
valuecommandBuffer
must be in the recording state- The
CommandPool
thatcommandBuffer
was allocated from must support graphics operations - This command must only be called inside of a render pass instance
commandBuffer
must be a primaryCommandBuffer
Host Synchronization
- Host access to
commandBuffer
must be externally synchronized
- Host access to the
CommandPool
thatcommandBuffer
was allocated from must be externally synchronized
Command Properties
'
Command Buffer Levels | Render Pass Scope | Supported Queue Types | Pipeline Type |
---|---|---|---|
Primary | Inside | Graphics | Graphics |
See Also
Arguments
:: forall io. MonadIO io | |
=> CommandBuffer |
|
-> io () |
vkCmdEndRenderPass - End the current render pass
Description
Ending a render pass instance performs any multisample resolve operations on the final subpass.
Valid Usage
- The current subpass index must be equal to the number of subpasses in the render pass minus one
- This command must not be recorded when transform feedback is active
Valid Usage (Implicit)
commandBuffer
must be a validCommandBuffer
handle
commandBuffer
must be in the recording state- The
CommandPool
thatcommandBuffer
was allocated from must support graphics operations - This command must only be called inside of a render pass instance
commandBuffer
must be a primaryCommandBuffer
Host Synchronization
- Host access to
commandBuffer
must be externally synchronized
- Host access to the
CommandPool
thatcommandBuffer
was allocated from must be externally synchronized
Command Properties
'
Command Buffer Levels | Render Pass Scope | Supported Queue Types | Pipeline Type |
---|---|---|---|
Primary | Inside | Graphics | Graphics |
See Also
Arguments
:: forall io. MonadIO io | |
=> CommandBuffer |
|
-> ("commandBuffers" ::: Vector CommandBuffer) |
|
-> io () |
vkCmdExecuteCommands - Execute a secondary command buffer from a primary command buffer
Description
If any element of pCommandBuffers
was not recorded with the
COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT
flag, and it was recorded into any other primary command buffer which is
currently in the
executable or recording state,
that primary command buffer becomes
invalid.
Valid Usage
- Each element of
pCommandBuffers
must have been allocated with alevel
ofCOMMAND_BUFFER_LEVEL_SECONDARY
- Each element of
pCommandBuffers
must be in the pending or executable state - If any element of
pCommandBuffers
was not recorded with theCOMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT
flag, it must not be in the pending state - If any element of
pCommandBuffers
was not recorded with theCOMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT
flag, it must not have already been recorded tocommandBuffer
- If any element of
pCommandBuffers
was not recorded with theCOMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT
flag, it must not appear more than once inpCommandBuffers
- Each element of
pCommandBuffers
must have been allocated from aCommandPool
that was created for the same queue family as theCommandPool
from whichcommandBuffer
was allocated - If
cmdExecuteCommands
is being called within a render pass instance, that render pass instance must have been begun with thecontents
parameter ofcmdBeginRenderPass
set toSUBPASS_CONTENTS_SECONDARY_COMMAND_BUFFERS
- If
cmdExecuteCommands
is being called within a render pass instance, each element ofpCommandBuffers
must have been recorded with theCOMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT
- If
cmdExecuteCommands
is being called within a render pass instance, each element ofpCommandBuffers
must have been recorded withCommandBufferInheritanceInfo
::subpass
set to the index of the subpass which the given command buffer will be executed in - If
cmdExecuteCommands
is being called within a render pass instance, the render passes specified in thepBeginInfo->pInheritanceInfo->renderPass
members of thebeginCommandBuffer
commands used to begin recording each element ofpCommandBuffers
must be compatible with the current render pass - If
cmdExecuteCommands
is being called within a render pass instance, and any element ofpCommandBuffers
was recorded withCommandBufferInheritanceInfo
::framebuffer
not equal toNULL_HANDLE
, thatFramebuffer
must match theFramebuffer
used in the current render pass instance - If
cmdExecuteCommands
is being called within a render pass instance that includedRenderPassTransformBeginInfoQCOM
in thepNext
chain ofRenderPassBeginInfo
, then each element ofpCommandBuffers
must have been recorded withCommandBufferInheritanceRenderPassTransformInfoQCOM
in thepNext
chain ofCommandBufferBeginInfo
- If
cmdExecuteCommands
is being called within a render pass instance that includedRenderPassTransformBeginInfoQCOM
in thepNext
chain ofRenderPassBeginInfo
, then each element ofpCommandBuffers
must have been recorded withCommandBufferInheritanceRenderPassTransformInfoQCOM
::transform
identical toRenderPassTransformBeginInfoQCOM
::transform
- If
cmdExecuteCommands
is being called within a render pass instance that includedRenderPassTransformBeginInfoQCOM
in thepNext
chain ofRenderPassBeginInfo
, then each element ofpCommandBuffers
must have been recorded withCommandBufferInheritanceRenderPassTransformInfoQCOM
::renderArea
identical toRenderPassBeginInfo
::renderArea
- If
cmdExecuteCommands
is not being called within a render pass instance, each element ofpCommandBuffers
must not have been recorded with theCOMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT
- If the
inherited queries
feature is not enabled,
commandBuffer
must not have any queries active - If
commandBuffer
has aQUERY_TYPE_OCCLUSION
query active, then each element ofpCommandBuffers
must have been recorded withCommandBufferInheritanceInfo
::occlusionQueryEnable
set toTRUE
- If
commandBuffer
has aQUERY_TYPE_OCCLUSION
query active, then each element ofpCommandBuffers
must have been recorded withCommandBufferInheritanceInfo
::queryFlags
having all bits set that are set for the query - If
commandBuffer
has aQUERY_TYPE_PIPELINE_STATISTICS
query active, then each element ofpCommandBuffers
must have been recorded withCommandBufferInheritanceInfo
::pipelineStatistics
having all bits set that are set in theQueryPool
the query uses - Each element of
pCommandBuffers
must not begin any query types that are active incommandBuffer
- If
commandBuffer
is a protected command buffer, then each element ofpCommandBuffers
must be a protected command buffer - If
commandBuffer
is an unprotected command buffer, then each element ofpCommandBuffers
must be an unprotected command buffer - This command must not be recorded when transform feedback is active
Valid Usage (Implicit)
commandBuffer
must be a validCommandBuffer
handle
pCommandBuffers
must be a valid pointer to an array ofcommandBufferCount
validCommandBuffer
handlescommandBuffer
must be in the recording state- The
CommandPool
thatcommandBuffer
was allocated from must support transfer, graphics, or compute operations commandBuffer
must be a primaryCommandBuffer
commandBufferCount
must be greater than0
- Both of
commandBuffer
, and the elements ofpCommandBuffers
must have been created, allocated, or retrieved from the sameDevice
Host Synchronization
- Host access to
commandBuffer
must be externally synchronized
- Host access to the
CommandPool
thatcommandBuffer
was allocated from must be externally synchronized
Command Properties
'
Command Buffer Levels | Render Pass Scope | Supported Queue Types | Pipeline Type |
---|---|---|---|
Primary | Both | Transfer Graphics Compute |
See Also
VkClearRect - Structure specifying a clear rectangle
Description
The layers [baseArrayLayer
, baseArrayLayer
+ layerCount
) counting
from the base layer of the attachment image view are cleared.
See Also
Constructors
ClearRect | |
Fields
|
Instances
Show ClearRect Source # | |
FromCStruct ClearRect Source # | |
Defined in Vulkan.Core10.CommandBufferBuilding | |
ToCStruct ClearRect Source # | |
Defined in Vulkan.Core10.CommandBufferBuilding | |
Zero ClearRect Source # | |
Defined in Vulkan.Core10.CommandBufferBuilding |
data ImageSubresourceLayers Source #
VkImageSubresourceLayers - Structure specifying an image subresource layers
Valid Usage
- If
aspectMask
containsIMAGE_ASPECT_COLOR_BIT
, it must not contain either ofIMAGE_ASPECT_DEPTH_BIT
orIMAGE_ASPECT_STENCIL_BIT
aspectMask
must not containIMAGE_ASPECT_METADATA_BIT
aspectMask
must not includeVK_IMAGE_ASPECT_MEMORY_PLANE_i_BIT_EXT
for any indexi
layerCount
must be greater than 0
Valid Usage (Implicit)
aspectMask
must be a valid combination ofImageAspectFlagBits
values
aspectMask
must not be0
See Also
BufferImageCopy
,
BufferImageCopy2KHR
,
ImageAspectFlags
, ImageBlit
,
ImageBlit2KHR
, ImageCopy
,
ImageCopy2KHR
, ImageResolve
,
ImageResolve2KHR
Constructors
ImageSubresourceLayers | |
Fields
|
Instances
data BufferCopy Source #
VkBufferCopy - Structure specifying a buffer copy operation
Valid Usage
- The
size
must be greater than0
See Also
Constructors
BufferCopy | |
Fields
|
Instances
VkImageCopy - Structure specifying an image copy operation
Description
For IMAGE_TYPE_3D
images, copies are
performed slice by slice starting with the z
member of the srcOffset
or dstOffset
, and copying depth
slices. For images with multiple
layers, copies are performed layer by layer starting with the
baseArrayLayer
member of the srcSubresource
or dstSubresource
and
copying layerCount
layers. Image data can be copied between images
with different image types. If one image is
IMAGE_TYPE_3D
and the other image is
IMAGE_TYPE_2D
with multiple layers, then
each slice is copied to or from a different layer.
Copies involving a
multi-planar image format
specify the region to be copied in terms of the plane to be copied,
not the coordinates of the multi-planar image. This means that copies
accessing the R/B planes of “_422
” format images must fit the
copied region within half the width
of the parent image, and that
copies accessing the R/B planes of “_420
” format images must fit
the copied region within half the width
and height
of the parent
image.
Valid Usage
- The number of slices of the
extent
(for 3D) or layers of thesrcSubresource
(for non-3D) must match the number of slices of theextent
(for 3D) or layers of thedstSubresource
(for non-3D)
Valid Usage (Implicit)
srcSubresource
must be a validImageSubresourceLayers
structure
dstSubresource
must be a validImageSubresourceLayers
structure
See Also
Constructors
ImageCopy | |
Fields
|
Instances
Show ImageCopy Source # | |
FromCStruct ImageCopy Source # | |
Defined in Vulkan.Core10.CommandBufferBuilding | |
ToCStruct ImageCopy Source # | |
Defined in Vulkan.Core10.CommandBufferBuilding | |
Zero ImageCopy Source # | |
Defined in Vulkan.Core10.CommandBufferBuilding |
VkImageBlit - Structure specifying an image blit operation
Description
For each element of the pRegions
array, a blit operation is performed
the specified source and destination regions.
Valid Usage
- The
aspectMask
member ofsrcSubresource
anddstSubresource
must match
- The
layerCount
member ofsrcSubresource
anddstSubresource
must match
Valid Usage (Implicit)
srcSubresource
must be a validImageSubresourceLayers
structure
dstSubresource
must be a validImageSubresourceLayers
structure
See Also
Constructors
ImageBlit | |
Fields
|
Instances
Show ImageBlit Source # | |
FromCStruct ImageBlit Source # | |
Defined in Vulkan.Core10.CommandBufferBuilding | |
ToCStruct ImageBlit Source # | |
Defined in Vulkan.Core10.CommandBufferBuilding | |
Zero ImageBlit Source # | |
Defined in Vulkan.Core10.CommandBufferBuilding |
data BufferImageCopy Source #
VkBufferImageCopy - Structure specifying a buffer image copy operation
Description
When copying to or from a depth or stencil aspect, the data in buffer memory uses a layout that is a (mostly) tightly packed representation of the depth or stencil data. Specifically:
- data copied to or from the stencil aspect of any depth/stencil
format is tightly packed with one
FORMAT_S8_UINT
value per texel. - data copied to or from the depth aspect of a
FORMAT_D16_UNORM
orFORMAT_D16_UNORM_S8_UINT
format is tightly packed with oneFORMAT_D16_UNORM
value per texel. - data copied to or from the depth aspect of a
FORMAT_D32_SFLOAT
orFORMAT_D32_SFLOAT_S8_UINT
format is tightly packed with oneFORMAT_D32_SFLOAT
value per texel. - data copied to or from the depth aspect of a
FORMAT_X8_D24_UNORM_PACK32
orFORMAT_D24_UNORM_S8_UINT
format is packed with one 32-bit word per texel with the D24 value in the LSBs of the word, and undefined values in the eight MSBs.
Note
To copy both the depth and stencil aspects of a depth/stencil format,
two entries in pRegions
can be used, where one specifies the depth
aspect in imageSubresource
, and the other specifies the stencil
aspect.
Because depth or stencil aspect buffer to image copies may require format conversions on some implementations, they are not supported on queues that do not support graphics.
When copying to a depth aspect, and the
VK_EXT_depth_range_unrestricted
extension is not enabled, the data in
buffer memory must be in the range [0,1], or the resulting values are
undefined.
Copies are done layer by layer starting with image layer
baseArrayLayer
member of imageSubresource
. layerCount
layers are
copied from the source image or to the destination image.
For purpose of valid usage statements here and in related copy commands, a blocked image is defined as:
- a image with a single-plane, “
_422
” format, which is treated as a format with a 2 × 1 compressed texel block, or - a compressed image.
Valid Usage
bufferRowLength
must be0
, or greater than or equal to thewidth
member ofimageExtent
bufferImageHeight
must be0
, or greater than or equal to theheight
member ofimageExtent
- The
aspectMask
member ofimageSubresource
must only have a single bit set
Valid Usage (Implicit)
imageSubresource
must be a validImageSubresourceLayers
structure
See Also
DeviceSize
,
Extent3D
, ImageSubresourceLayers
,
Offset3D
, cmdCopyBufferToImage
,
cmdCopyImageToBuffer
Constructors
BufferImageCopy | |
Fields
|
Instances
Show BufferImageCopy Source # | |
Defined in Vulkan.Core10.CommandBufferBuilding Methods showsPrec :: Int -> BufferImageCopy -> ShowS # show :: BufferImageCopy -> String # showList :: [BufferImageCopy] -> ShowS # | |
FromCStruct BufferImageCopy Source # | |
Defined in Vulkan.Core10.CommandBufferBuilding Methods peekCStruct :: Ptr BufferImageCopy -> IO BufferImageCopy Source # | |
ToCStruct BufferImageCopy Source # | |
Defined in Vulkan.Core10.CommandBufferBuilding Methods withCStruct :: BufferImageCopy -> (Ptr BufferImageCopy -> IO b) -> IO b Source # pokeCStruct :: Ptr BufferImageCopy -> BufferImageCopy -> IO b -> IO b Source # withZeroCStruct :: (Ptr BufferImageCopy -> IO b) -> IO b Source # pokeZeroCStruct :: Ptr BufferImageCopy -> IO b -> IO b Source # cStructSize :: Int Source # | |
Zero BufferImageCopy Source # | |
Defined in Vulkan.Core10.CommandBufferBuilding Methods |
data ImageResolve Source #
VkImageResolve - Structure specifying an image resolve operation
Valid Usage
- The
aspectMask
member ofsrcSubresource
anddstSubresource
must only containIMAGE_ASPECT_COLOR_BIT
- The
layerCount
member ofsrcSubresource
anddstSubresource
must match
Valid Usage (Implicit)
srcSubresource
must be a validImageSubresourceLayers
structure
dstSubresource
must be a validImageSubresourceLayers
structure
See Also
Constructors
ImageResolve | |
Fields
|
Instances
Show ImageResolve Source # | |
Defined in Vulkan.Core10.CommandBufferBuilding Methods showsPrec :: Int -> ImageResolve -> ShowS # show :: ImageResolve -> String # showList :: [ImageResolve] -> ShowS # | |
FromCStruct ImageResolve Source # | |
Defined in Vulkan.Core10.CommandBufferBuilding Methods peekCStruct :: Ptr ImageResolve -> IO ImageResolve Source # | |
ToCStruct ImageResolve Source # | |
Defined in Vulkan.Core10.CommandBufferBuilding Methods withCStruct :: ImageResolve -> (Ptr ImageResolve -> IO b) -> IO b Source # pokeCStruct :: Ptr ImageResolve -> ImageResolve -> IO b -> IO b Source # withZeroCStruct :: (Ptr ImageResolve -> IO b) -> IO b Source # pokeZeroCStruct :: Ptr ImageResolve -> IO b -> IO b Source # cStructSize :: Int Source # | |
Zero ImageResolve Source # | |
Defined in Vulkan.Core10.CommandBufferBuilding Methods zero :: ImageResolve Source # |
data RenderPassBeginInfo (es :: [Type]) Source #
VkRenderPassBeginInfo - Structure specifying render pass begin info
Description
renderArea
is the render area that is affected by the render pass
instance. The effects of attachment load, store and multisample resolve
operations are restricted to the pixels whose x and y coordinates fall
within the render area on all attachments. The render area extends to
all layers of framebuffer
. The application must ensure (using
scissor if necessary) that all rendering is contained within the render
area. The render area, after any transform specified by
RenderPassTransformBeginInfoQCOM
::transform
is applied, must be contained within the framebuffer dimensions.
If
render pass transform
is enabled, then renderArea
must equal the framebuffer
pre-transformed dimensions. After renderArea
has been transformed by
RenderPassTransformBeginInfoQCOM
::transform
,
the resulting render area must be equal to the framebuffer dimensions.
When multiview is enabled, the resolve operation at the end of a subpass applies to all views in the view mask.
Note
There may be a performance cost for using a render area smaller than the framebuffer, unless it matches the render area granularity for the render pass.
Valid Usage
clearValueCount
must be greater than the largest attachment index inrenderPass
that specifies aloadOp
(orstencilLoadOp
, if the attachment has a depth/stencil format) ofATTACHMENT_LOAD_OP_CLEAR
renderPass
must be compatible with therenderPass
member of theFramebufferCreateInfo
structure specified when creatingframebuffer
- If the
pNext
chain does not containDeviceGroupRenderPassBeginInfo
or itsdeviceRenderAreaCount
member is equal to 0,renderArea.offset.x
must be greater than or equal to 0 - If the
pNext
chain does not containDeviceGroupRenderPassBeginInfo
or itsdeviceRenderAreaCount
member is equal to 0,renderArea.offset.y
must be greater than or equal to 0 - If the
pNext
chain does not containDeviceGroupRenderPassBeginInfo
or itsdeviceRenderAreaCount
member is equal to 0,renderArea.offset.x
+renderArea.offset.width
must be less than or equal toFramebufferCreateInfo
::width
theframebuffer
was created with - If the
pNext
chain does not containDeviceGroupRenderPassBeginInfo
or itsdeviceRenderAreaCount
member is equal to 0,renderArea.offset.y
+renderArea.offset.height
must be less than or equal toFramebufferCreateInfo
::height
theframebuffer
was created with - If the
pNext
chain containsDeviceGroupRenderPassBeginInfo
, theoffset.x
member of each element ofpDeviceRenderAreas
must be greater than or equal to 0 - If the
pNext
chain containsDeviceGroupRenderPassBeginInfo
, theoffset.y
member of each element ofpDeviceRenderAreas
must be greater than or equal to 0 - If the
pNext
chain containsDeviceGroupRenderPassBeginInfo
,offset.x
+offset.width
of each element ofpDeviceRenderAreas
must be less than or equal toFramebufferCreateInfo
::width
theframebuffer
was created with - If the
pNext
chain containsDeviceGroupRenderPassBeginInfo
,offset.y
+offset.height
of each element ofpDeviceRenderAreas
must be less than or equal toFramebufferCreateInfo
::height
theframebuffer
was created with - If
framebuffer
was created with aFramebufferCreateInfo
::flags
value that did not includeFRAMEBUFFER_CREATE_IMAGELESS_BIT
, and thepNext
chain includes aRenderPassAttachmentBeginInfo
structure, itsattachmentCount
must be zero - If
framebuffer
was created with aFramebufferCreateInfo
::flags
value that includedFRAMEBUFFER_CREATE_IMAGELESS_BIT
, theattachmentCount
of aRenderPassAttachmentBeginInfo
structure included in thepNext
chain must be equal to the value ofFramebufferAttachmentsCreateInfo
::attachmentImageInfoCount
used to createframebuffer
- If
framebuffer
was created with aFramebufferCreateInfo
::flags
value that includedFRAMEBUFFER_CREATE_IMAGELESS_BIT
, each element of thepAttachments
member of aRenderPassAttachmentBeginInfo
structure included in thepNext
chain must have been created on the sameDevice
asframebuffer
andrenderPass
- If
framebuffer
was created with aFramebufferCreateInfo
::flags
value that includedFRAMEBUFFER_CREATE_IMAGELESS_BIT
, each element of thepAttachments
member of aRenderPassAttachmentBeginInfo
structure included in thepNext
chain must be aImageView
of an image created with a value ofImageCreateInfo
::flags
equal to theflags
member of the corresponding element ofFramebufferAttachmentsCreateInfo
::pAttachments
used to createframebuffer
- If
framebuffer
was created with aFramebufferCreateInfo
::flags
value that includedFRAMEBUFFER_CREATE_IMAGELESS_BIT
, each element of thepAttachments
member of aRenderPassAttachmentBeginInfo
structure included in thepNext
chain must be aImageView
of an image created with a value ofImageCreateInfo
::usage
equal to theusage
member of the corresponding element ofFramebufferAttachmentsCreateInfo
::pAttachments
used to createframebuffer
- If
framebuffer
was created with aFramebufferCreateInfo
::flags
value that includedFRAMEBUFFER_CREATE_IMAGELESS_BIT
, each element of thepAttachments
member of aRenderPassAttachmentBeginInfo
structure included in thepNext
chain must be aImageView
with a width equal to thewidth
member of the corresponding element ofFramebufferAttachmentsCreateInfo
::pAttachments
used to createframebuffer
- If
framebuffer
was created with aFramebufferCreateInfo
::flags
value that includedFRAMEBUFFER_CREATE_IMAGELESS_BIT
, each element of thepAttachments
member of aRenderPassAttachmentBeginInfo
structure included in thepNext
chain must be aImageView
with a height equal to theheight
member of the corresponding element ofFramebufferAttachmentsCreateInfo
::pAttachments
used to createframebuffer
- If
framebuffer
was created with aFramebufferCreateInfo
::flags
value that includedFRAMEBUFFER_CREATE_IMAGELESS_BIT
, each element of thepAttachments
member of aRenderPassAttachmentBeginInfo
structure included in thepNext
chain must be aImageView
of an image created with a value ofImageViewCreateInfo
::subresourceRange.layerCount
equal to thelayerCount
member of the corresponding element ofFramebufferAttachmentsCreateInfo
::pAttachments
used to createframebuffer
- If
framebuffer
was created with aFramebufferCreateInfo
::flags
value that includedFRAMEBUFFER_CREATE_IMAGELESS_BIT
, each element of thepAttachments
member of aRenderPassAttachmentBeginInfo
structure included in thepNext
chain must be aImageView
of an image created with a value ofImageFormatListCreateInfo
::viewFormatCount
equal to theviewFormatCount
member of the corresponding element ofFramebufferAttachmentsCreateInfo
::pAttachments
used to createframebuffer
- If
framebuffer
was created with aFramebufferCreateInfo
::flags
value that includedFRAMEBUFFER_CREATE_IMAGELESS_BIT
, each element of thepAttachments
member of aRenderPassAttachmentBeginInfo
structure included in thepNext
chain must be aImageView
of an image created with a set of elements inImageFormatListCreateInfo
::pViewFormats
equal to the set of elements in thepViewFormats
member of the corresponding element ofFramebufferAttachmentsCreateInfo
::pAttachments
used to createframebuffer
- If
framebuffer
was created with aFramebufferCreateInfo
::flags
value that includedFRAMEBUFFER_CREATE_IMAGELESS_BIT
, each element of thepAttachments
member of aRenderPassAttachmentBeginInfo
structure included in thepNext
chain must be aImageView
of an image created with a value ofImageViewCreateInfo
::format
equal to the corresponding value ofAttachmentDescription
::format
inrenderPass
- If
framebuffer
was created with aFramebufferCreateInfo
::flags
value that includedFRAMEBUFFER_CREATE_IMAGELESS_BIT
, each element of thepAttachments
member of aRenderPassAttachmentBeginInfo
structure included in thepNext
chain must be aImageView
of an image created with a value ofImageCreateInfo
::samples
equal to the corresponding value ofAttachmentDescription
::samples
inrenderPass
- If the
pNext
chain includesRenderPassTransformBeginInfoQCOM
,renderArea.offset
must equal (0,0) - If the
pNext
chain includesRenderPassTransformBeginInfoQCOM
,renderArea.extent
transformed byRenderPassTransformBeginInfoQCOM
::transform
must equal theframebuffer
dimensions
Valid Usage (Implicit)
sType
must beSTRUCTURE_TYPE_RENDER_PASS_BEGIN_INFO
- Each
pNext
member of any structure (including this one) in thepNext
chain must be eitherNULL
or a pointer to a valid instance ofDeviceGroupRenderPassBeginInfo
,RenderPassAttachmentBeginInfo
,RenderPassSampleLocationsBeginInfoEXT
, orRenderPassTransformBeginInfoQCOM
- The
sType
value of each struct in thepNext
chain must be unique renderPass
must be a validRenderPass
handleframebuffer
must be a validFramebuffer
handle- If
clearValueCount
is not0
,pClearValues
must be a valid pointer to an array ofclearValueCount
ClearValue
unions - Both of
framebuffer
, andrenderPass
must have been created, allocated, or retrieved from the sameDevice
See Also
ClearValue
, Framebuffer
,
Rect2D
,
RenderPass
,
StructureType
, cmdBeginRenderPass
,
cmdBeginRenderPass2
,
cmdBeginRenderPass2KHR
Constructors
RenderPassBeginInfo | |
Fields
|
Instances
data ClearDepthStencilValue Source #
VkClearDepthStencilValue - Structure specifying a clear depth stencil value
Valid Usage
- Unless the
VK_EXT_depth_range_unrestricted
extension is enableddepth
must be between0.0
and1.0
, inclusive
See Also
Constructors
ClearDepthStencilValue | |
Fields
|
Instances
data ClearAttachment Source #
VkClearAttachment - Structure specifying a clear attachment
Description
No memory barriers are needed between cmdClearAttachments
and
preceding or subsequent draw or attachment clear commands in the same
subpass.
The cmdClearAttachments
command is not affected by the bound pipeline
state.
Attachments can also be cleared at the beginning of a render pass
instance by setting loadOp
(or stencilLoadOp
) of
AttachmentDescription
to
ATTACHMENT_LOAD_OP_CLEAR
, as
described for createRenderPass
.
Valid Usage
- If
aspectMask
includesIMAGE_ASPECT_COLOR_BIT
, it must not includeIMAGE_ASPECT_DEPTH_BIT
orIMAGE_ASPECT_STENCIL_BIT
aspectMask
must not includeIMAGE_ASPECT_METADATA_BIT
aspectMask
must not includeVK_IMAGE_ASPECT_MEMORY_PLANE_i_BIT_EXT
for any indexi
clearValue
must be a validClearValue
union
Valid Usage (Implicit)
aspectMask
must be a valid combination ofImageAspectFlagBits
values
aspectMask
must not be0
See Also
Constructors
ClearAttachment | |
Fields
|
Instances
Show ClearAttachment Source # | |
Defined in Vulkan.Core10.CommandBufferBuilding Methods showsPrec :: Int -> ClearAttachment -> ShowS # show :: ClearAttachment -> String # showList :: [ClearAttachment] -> ShowS # | |
ToCStruct ClearAttachment Source # | |
Defined in Vulkan.Core10.CommandBufferBuilding Methods withCStruct :: ClearAttachment -> (Ptr ClearAttachment -> IO b) -> IO b Source # pokeCStruct :: Ptr ClearAttachment -> ClearAttachment -> IO b -> IO b Source # withZeroCStruct :: (Ptr ClearAttachment -> IO b) -> IO b Source # pokeZeroCStruct :: Ptr ClearAttachment -> IO b -> IO b Source # cStructSize :: Int Source # | |
Zero ClearAttachment Source # | |
Defined in Vulkan.Core10.CommandBufferBuilding Methods |
data ClearColorValue Source #
Constructors
Float32 (Float, Float, Float, Float) | |
Int32 (Int32, Int32, Int32, Int32) | |
Uint32 (Word32, Word32, Word32, Word32) |
Instances
Show ClearColorValue Source # | |
Defined in Vulkan.Core10.CommandBufferBuilding Methods showsPrec :: Int -> ClearColorValue -> ShowS # show :: ClearColorValue -> String # showList :: [ClearColorValue] -> ShowS # | |
ToCStruct ClearColorValue Source # | |
Defined in Vulkan.Core10.CommandBufferBuilding Methods withCStruct :: ClearColorValue -> (Ptr ClearColorValue -> IO b) -> IO b Source # pokeCStruct :: Ptr ClearColorValue -> ClearColorValue -> IO b -> IO b Source # withZeroCStruct :: (Ptr ClearColorValue -> IO b) -> IO b Source # pokeZeroCStruct :: Ptr ClearColorValue -> IO b -> IO b Source # cStructSize :: Int Source # | |
Zero ClearColorValue Source # | |
Defined in Vulkan.Core10.CommandBufferBuilding Methods |
data ClearValue Source #
Constructors
Color ClearColorValue | |
DepthStencil ClearDepthStencilValue |
Instances
Show ClearValue Source # | |
Defined in Vulkan.Core10.CommandBufferBuilding Methods showsPrec :: Int -> ClearValue -> ShowS # show :: ClearValue -> String # showList :: [ClearValue] -> ShowS # | |
ToCStruct ClearValue Source # | |
Defined in Vulkan.Core10.CommandBufferBuilding Methods withCStruct :: ClearValue -> (Ptr ClearValue -> IO b) -> IO b Source # pokeCStruct :: Ptr ClearValue -> ClearValue -> IO b -> IO b Source # withZeroCStruct :: (Ptr ClearValue -> IO b) -> IO b Source # pokeZeroCStruct :: Ptr ClearValue -> IO b -> IO b Source # cStructSize :: Int Source # | |
Zero ClearValue Source # | |
Defined in Vulkan.Core10.CommandBufferBuilding Methods zero :: ClearValue Source # |
VkIndexType - Type of index buffer indices
See Also
AccelerationStructureCreateGeometryTypeInfoKHR
,
AccelerationStructureGeometryTrianglesDataKHR
,
BindIndexBufferIndirectCommandNV
,
GeometryTrianglesNV
,
IndirectCommandsLayoutTokenNV
,
cmdBindIndexBuffer
Bundled Patterns
pattern INDEX_TYPE_UINT16 :: IndexType |
|
pattern INDEX_TYPE_UINT32 :: IndexType |
|
pattern INDEX_TYPE_UINT8_EXT :: IndexType |
|
pattern INDEX_TYPE_NONE_KHR :: IndexType |
|
Instances
Eq IndexType Source # | |
Ord IndexType Source # | |
Read IndexType Source # | |
Show IndexType Source # | |
Storable IndexType Source # | |
Defined in Vulkan.Core10.Enums.IndexType | |
Zero IndexType Source # | |
Defined in Vulkan.Core10.Enums.IndexType |
newtype SubpassContents Source #
VkSubpassContents - Specify how commands in the first subpass of a render pass are provided
See Also
Constructors
SubpassContents Int32 |
Bundled Patterns
pattern SUBPASS_CONTENTS_INLINE :: SubpassContents |
|
pattern SUBPASS_CONTENTS_SECONDARY_COMMAND_BUFFERS :: SubpassContents |
|
Instances
newtype StencilFaceFlagBits Source #
VkStencilFaceFlagBits - Bitmask specifying sets of stencil state for which to update the compare mask
See Also
Constructors
StencilFaceFlagBits Flags |
Bundled Patterns
pattern STENCIL_FACE_FRONT_BIT :: StencilFaceFlagBits |
|
pattern STENCIL_FACE_BACK_BIT :: StencilFaceFlagBits |
|
pattern STENCIL_FACE_FRONT_AND_BACK :: StencilFaceFlagBits |
|