vulkan-3.26.1: Bindings to the Vulkan graphics API.
Safe HaskellSafe-Inferred
LanguageHaskell2010

Vulkan.Core10.CommandBufferBuilding

Synopsis

Documentation

cmdBindPipeline Source #

Arguments

:: forall io. MonadIO io 
=> CommandBuffer

commandBuffer is the command buffer that the pipeline will be bound to.

-> PipelineBindPoint

pipelineBindPoint is a PipelineBindPoint value specifying to which bind point the pipeline is bound. Binding one does not disturb the others.

-> Pipeline

pipeline is the pipeline to be bound.

-> 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, or until the pipeline bind point is disturbed by binding a shader object as described in Interaction with Pipelines. Commands that do not interact with the given pipeline type must not be affected by the pipeline state.

Valid Usage

Valid Usage (Implicit)

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

Host Synchronization

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

Command Properties

'

Command Buffer LevelsRender Pass ScopeVideo Coding ScopeSupported Queue TypesCommand Type
Primary SecondaryBoth Outside Graphics ComputeState

See Also

VK_VERSION_1_0, CommandBuffer, Pipeline, PipelineBindPoint

cmdSetViewport Source #

Arguments

:: forall io. MonadIO io 
=> CommandBuffer

commandBuffer is the command buffer into which the command will be recorded.

-> ("firstViewport" ::: Word32)

firstViewport is the index of the first viewport whose parameters are updated by the command.

-> ("viewports" ::: Vector Viewport)

pViewports is a pointer to an array of Viewport structures specifying viewport parameters.

-> io () 

vkCmdSetViewport - Set the viewport dynamically for a command buffer

Description

This command sets the viewport transformation parameters state for subsequent drawing commands when drawing using shader objects, or when the graphics pipeline is created with DYNAMIC_STATE_VIEWPORT set in PipelineDynamicStateCreateInfo::pDynamicStates. Otherwise, this state is specified by the PipelineViewportStateCreateInfo::pViewports values used to create the currently active pipeline.

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

  • The sum of firstViewport and viewportCount must be between 1 and PhysicalDeviceLimits::maxViewports, inclusive

Valid Usage (Implicit)

  • pViewports must be a valid pointer to an array of viewportCount valid Viewport structures
  • commandBuffer must be in the recording state
  • The CommandPool that commandBuffer was allocated from must support graphics operations
  • This command must only be called outside of a video coding scope
  • viewportCount must be greater than 0

Host Synchronization

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

Command Properties

'

Command Buffer LevelsRender Pass ScopeVideo Coding ScopeSupported Queue TypesCommand Type
Primary SecondaryBoth Outside Graphics State

See Also

VK_VERSION_1_0, CommandBuffer, Viewport

cmdSetScissor Source #

Arguments

:: forall io. MonadIO io 
=> CommandBuffer

commandBuffer is the command buffer into which the command will be recorded.

-> ("firstScissor" ::: Word32)

firstScissor is the index of the first scissor whose state is updated by the command.

-> ("scissors" ::: Vector Rect2D)

pScissors is a pointer to an array of Rect2D structures defining scissor rectangles.

-> io () 

vkCmdSetScissor - Set scissor rectangles dynamically for 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 scissor rectangles for subsequent drawing commands when drawing using shader objects, or when the graphics pipeline is created with DYNAMIC_STATE_SCISSOR set in PipelineDynamicStateCreateInfo::pDynamicStates. Otherwise, this state is specified by the PipelineViewportStateCreateInfo::pScissors values used to create the currently active pipeline.

Valid Usage

  • The sum of firstScissor and scissorCount must be between 1 and PhysicalDeviceLimits::maxViewports, inclusive
  • If the multiViewport feature is not enabled, firstScissor must be 0
  • If the multiViewport feature is not enabled, scissorCount must be 1
  • The x and y members of offset member of any element of pScissors must be greater than or equal to 0
  • Evaluation of (offset.x + extent.width) must not cause a signed integer addition overflow for any element of pScissors
  • Evaluation of (offset.y + extent.height) must not cause a signed integer addition overflow for any element of pScissors
  • If this command is recorded in a secondary command buffer with CommandBufferInheritanceViewportScissorInfoNV::viewportScissor2D enabled, then this function must not be called

Valid Usage (Implicit)

  • pScissors must be a valid pointer to an array of scissorCount Rect2D structures
  • commandBuffer must be in the recording state
  • The CommandPool that commandBuffer was allocated from must support graphics operations
  • This command must only be called outside of a video coding scope
  • scissorCount must be greater than 0

Host Synchronization

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

Command Properties

'

Command Buffer LevelsRender Pass ScopeVideo Coding ScopeSupported Queue TypesCommand Type
Primary SecondaryBoth Outside Graphics State

See Also

VK_VERSION_1_0, CommandBuffer, Rect2D

cmdSetLineWidth Source #

Arguments

:: forall io. MonadIO io 
=> CommandBuffer

commandBuffer is the command buffer into which the command will be recorded.

-> ("lineWidth" ::: Float)

lineWidth is the width of rasterized line segments.

-> io () 

vkCmdSetLineWidth - Set line width dynamically for a command buffer

Description

This command sets the line width for subsequent drawing commands when drawing using shader objects, or when the graphics pipeline is created with DYNAMIC_STATE_LINE_WIDTH set in PipelineDynamicStateCreateInfo::pDynamicStates. Otherwise, this state is specified by the PipelineRasterizationStateCreateInfo::lineWidth value used to create the currently active pipeline.

Valid Usage

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

Valid Usage (Implicit)

  • commandBuffer must be in the recording state
  • The CommandPool that commandBuffer was allocated from must support graphics operations
  • This command must only be called outside of a video coding scope

Host Synchronization

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

Command Properties

'

Command Buffer LevelsRender Pass ScopeVideo Coding ScopeSupported Queue TypesCommand Type
Primary SecondaryBoth Outside Graphics State

See Also

VK_VERSION_1_0, CommandBuffer

cmdSetDepthBias Source #

Arguments

:: forall io. MonadIO io 
=> CommandBuffer

commandBuffer is the command buffer into which the command will be recorded.

-> ("depthBiasConstantFactor" ::: Float)

depthBiasConstantFactor is a scalar factor controlling the constant depth value added to each fragment.

-> ("depthBiasClamp" ::: Float)

depthBiasClamp is the maximum (or minimum) depth bias of a fragment.

-> ("depthBiasSlopeFactor" ::: Float)

depthBiasSlopeFactor is a scalar factor applied to a fragment’s slope in depth bias calculations.

-> io () 

vkCmdSetDepthBias - Set depth bias factors and clamp dynamically for a command buffer

Description

This command sets the depth bias parameters for subsequent drawing commands when drawing using shader objects, or when the graphics pipeline is created with DYNAMIC_STATE_DEPTH_BIAS set in PipelineDynamicStateCreateInfo::pDynamicStates. Otherwise, this state is specified by the corresponding PipelineRasterizationStateCreateInfo::depthBiasConstantFactor, depthBiasClamp, and depthBiasSlopeFactor values used to create the currently active pipeline.

Calling this function is equivalent to calling cmdSetDepthBias2EXT without a DepthBiasRepresentationInfoEXT in the pNext chain of DepthBiasInfoEXT.

Valid Usage

  • If the depthBiasClamp feature is not enabled, depthBiasClamp must be 0.0

Valid Usage (Implicit)

  • commandBuffer must be in the recording state
  • The CommandPool that commandBuffer was allocated from must support graphics operations
  • This command must only be called outside of a video coding scope

Host Synchronization

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

Command Properties

'

Command Buffer LevelsRender Pass ScopeVideo Coding ScopeSupported Queue TypesCommand Type
Primary SecondaryBoth Outside Graphics State

See Also

VK_VERSION_1_0, CommandBuffer

cmdSetBlendConstants Source #

Arguments

:: forall io. MonadIO io 
=> CommandBuffer

commandBuffer is the command buffer into which the command will be recorded.

-> ("blendConstants" ::: (Float, Float, Float, Float))

blendConstants is a pointer to an array of four values specifying the Rc, Gc, Bc, and Ac components of the blend constant color used in blending, depending on the blend factor.

-> io () 

vkCmdSetBlendConstants - Set the values of blend constants

Description

This command sets blend constants for subsequent drawing commands when when drawing using shader objects, or the graphics pipeline is created with DYNAMIC_STATE_BLEND_CONSTANTS set in PipelineDynamicStateCreateInfo::pDynamicStates. Otherwise, this state is specified by the PipelineColorBlendStateCreateInfo::blendConstants values used to create the currently active pipeline.

Valid Usage (Implicit)

  • commandBuffer must be in the recording state
  • The CommandPool that commandBuffer was allocated from must support graphics operations
  • This command must only be called outside of a video coding scope

Host Synchronization

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

Command Properties

'

Command Buffer LevelsRender Pass ScopeVideo Coding ScopeSupported Queue TypesCommand Type
Primary SecondaryBoth Outside Graphics State

See Also

VK_VERSION_1_0, CommandBuffer

cmdSetDepthBounds Source #

Arguments

:: forall io. MonadIO io 
=> CommandBuffer

commandBuffer is the command buffer into which the command will be recorded.

-> ("minDepthBounds" ::: Float)

minDepthBounds is the minimum depth bound.

-> ("maxDepthBounds" ::: Float)

maxDepthBounds is the maximum depth bound.

-> io () 

vkCmdSetDepthBounds - Set depth bounds range dynamically for a command buffer

Description

This command sets the depth bounds range for subsequent drawing commands when drawing using shader objects, or when the graphics pipeline is created with DYNAMIC_STATE_DEPTH_BOUNDS set in PipelineDynamicStateCreateInfo::pDynamicStates. Otherwise, this state is specified by the PipelineDepthStencilStateCreateInfo::minDepthBounds and PipelineDepthStencilStateCreateInfo::maxDepthBounds values used to create the currently active pipeline.

Valid Usage

  • If the VK_EXT_depth_range_unrestricted extension is not enabled minDepthBounds must be between 0.0 and 1.0, inclusive
  • If the VK_EXT_depth_range_unrestricted extension is not enabled maxDepthBounds must be between 0.0 and 1.0, inclusive

Valid Usage (Implicit)

  • commandBuffer must be in the recording state
  • The CommandPool that commandBuffer was allocated from must support graphics operations
  • This command must only be called outside of a video coding scope

Host Synchronization

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

Command Properties

'

Command Buffer LevelsRender Pass ScopeVideo Coding ScopeSupported Queue TypesCommand Type
Primary SecondaryBoth Outside Graphics State

See Also

VK_VERSION_1_0, CommandBuffer

cmdSetStencilCompareMask Source #

Arguments

:: forall io. MonadIO io 
=> CommandBuffer

commandBuffer is the command buffer into which the command will be recorded.

-> ("faceMask" ::: StencilFaceFlags)

faceMask is a bitmask of StencilFaceFlagBits specifying the set of stencil state for which to update the compare mask.

-> ("compareMask" ::: Word32)

compareMask is the new value to use as the stencil compare mask.

-> io () 

vkCmdSetStencilCompareMask - Set stencil compare mask dynamically for a command buffer

Description

This command sets the stencil compare mask for subsequent drawing commands when drawing using shader objects, or when the graphics pipeline is created with DYNAMIC_STATE_STENCIL_COMPARE_MASK set in PipelineDynamicStateCreateInfo::pDynamicStates. Otherwise, this state is specified by the StencilOpState::compareMask value used to create the currently active pipeline, for both front and back faces.

Valid Usage (Implicit)

  • faceMask must be a valid combination of StencilFaceFlagBits values
  • faceMask must not be 0
  • commandBuffer must be in the recording state
  • The CommandPool that commandBuffer was allocated from must support graphics operations
  • This command must only be called outside of a video coding scope

Host Synchronization

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

Command Properties

'

Command Buffer LevelsRender Pass ScopeVideo Coding ScopeSupported Queue TypesCommand Type
Primary SecondaryBoth Outside Graphics State

See Also

VK_VERSION_1_0, CommandBuffer, StencilFaceFlags

cmdSetStencilWriteMask Source #

Arguments

:: forall io. MonadIO io 
=> CommandBuffer

commandBuffer is the command buffer into which the command will be recorded.

-> ("faceMask" ::: StencilFaceFlags)

faceMask is a bitmask of StencilFaceFlagBits specifying the set of stencil state for which to update the write mask, as described above for cmdSetStencilCompareMask.

-> ("writeMask" ::: Word32)

writeMask is the new value to use as the stencil write mask.

-> io () 

vkCmdSetStencilWriteMask - Set stencil write mask dynamically for a command buffer

Description

This command sets the stencil write mask for subsequent drawing commands when drawing using shader objects, or when the graphics pipeline is created with DYNAMIC_STATE_STENCIL_WRITE_MASK set in PipelineDynamicStateCreateInfo::pDynamicStates. Otherwise, this state is specified by the writeMask value used to create the currently active pipeline, for both PipelineDepthStencilStateCreateInfo::front and PipelineDepthStencilStateCreateInfo::back faces.

Valid Usage (Implicit)

  • faceMask must be a valid combination of StencilFaceFlagBits values
  • faceMask must not be 0
  • commandBuffer must be in the recording state
  • The CommandPool that commandBuffer was allocated from must support graphics operations
  • This command must only be called outside of a video coding scope

Host Synchronization

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

Command Properties

'

Command Buffer LevelsRender Pass ScopeVideo Coding ScopeSupported Queue TypesCommand Type
Primary SecondaryBoth Outside Graphics State

See Also

VK_VERSION_1_0, CommandBuffer, StencilFaceFlags

cmdSetStencilReference Source #

Arguments

:: forall io. MonadIO io 
=> CommandBuffer

commandBuffer is the command buffer into which the command will be recorded.

-> ("faceMask" ::: StencilFaceFlags)

faceMask is a bitmask of StencilFaceFlagBits specifying the set of stencil state for which to update the reference value, as described above for cmdSetStencilCompareMask.

-> ("reference" ::: Word32)

reference is the new value to use as the stencil reference value.

-> io () 

vkCmdSetStencilReference - Set stencil reference value dynamically for a command buffer

Description

This command sets the stencil reference value for subsequent drawing commands when drawing using shader objects, or when the graphics pipeline is created with DYNAMIC_STATE_STENCIL_REFERENCE set in PipelineDynamicStateCreateInfo::pDynamicStates. Otherwise, this state is specified by the PipelineDepthStencilStateCreateInfo::reference value used to create the currently active pipeline, for both front and back faces.

Valid Usage (Implicit)

  • faceMask must be a valid combination of StencilFaceFlagBits values
  • faceMask must not be 0
  • commandBuffer must be in the recording state
  • The CommandPool that commandBuffer was allocated from must support graphics operations
  • This command must only be called outside of a video coding scope

Host Synchronization

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

Command Properties

'

Command Buffer LevelsRender Pass ScopeVideo Coding ScopeSupported Queue TypesCommand Type
Primary SecondaryBoth Outside Graphics State

See Also

VK_VERSION_1_0, CommandBuffer, StencilFaceFlags

cmdBindDescriptorSets Source #

Arguments

:: forall io. MonadIO io 
=> CommandBuffer

commandBuffer is the command buffer that the descriptor sets will be bound to.

-> PipelineBindPoint

pipelineBindPoint is a PipelineBindPoint indicating the type of the pipeline that will use the descriptors. There is a separate set of bind points for each pipeline type, so binding one does not disturb the others.

-> PipelineLayout

layout is a PipelineLayout object used to program the bindings.

-> ("firstSet" ::: Word32)

firstSet is the set number of the first descriptor set to be bound.

-> ("descriptorSets" ::: Vector DescriptorSet)

pDescriptorSets is a pointer to an array of handles to DescriptorSet objects describing the descriptor sets to bind to.

-> ("dynamicOffsets" ::: Vector Word32)

pDynamicOffsets is a pointer to an array of uint32_t values specifying dynamic offsets.

-> io () 

vkCmdBindDescriptorSets - Binds descriptor sets to a command buffer

Description

cmdBindDescriptorSets binds descriptor sets pDescriptorSets[0..descriptorSetCount-1] to set numbers [firstSet..firstSet+descriptorSetCount-1] for subsequent bound pipeline commands set by pipelineBindPoint. Any bindings that were previously applied via these sets , or calls to cmdSetDescriptorBufferOffsetsEXT or cmdBindDescriptorBufferEmbeddedSamplersEXT, 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 drawing or dispatching 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.

When consuming a descriptor, a descriptor is considered valid if the descriptor is not undefined as described by descriptor set allocation. If the nullDescriptor feature is enabled, a null descriptor is also considered valid. A descriptor that was disturbed by Pipeline Layout Compatibility, or was never bound by cmdBindDescriptorSets is not considered valid. If a pipeline accesses a descriptor either statically or dynamically depending on the DescriptorBindingFlagBits, the consuming descriptor type in the pipeline must match the DescriptorType in DescriptorSetLayoutCreateInfo for the descriptor to be considered valid. If a descriptor is a mutable descriptor, the consuming descriptor type in the pipeline must match the active descriptor type for the descriptor to be considered valid.

Note

Further validation may be carried out beyond validation for descriptor types, e.g. Texel Input Validation.

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 a DescriptorSetLayout that matches (is the same as, or identically defined as) the DescriptorSetLayout at set n in layout, where n is the sum of firstSet and the index into pDescriptorSets

Valid Usage (Implicit)

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

Host Synchronization

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

Command Properties

'

Command Buffer LevelsRender Pass ScopeVideo Coding ScopeSupported Queue TypesCommand Type
Primary SecondaryBoth Outside Graphics ComputeState

See Also

VK_VERSION_1_0, CommandBuffer, DescriptorSet, PipelineBindPoint, PipelineLayout

cmdBindIndexBuffer Source #

Arguments

:: forall io. MonadIO io 
=> CommandBuffer

commandBuffer is the command buffer into which the command is recorded.

-> Buffer

buffer is the buffer being bound.

-> ("offset" ::: DeviceSize)

offset is the starting offset in bytes within buffer used in index buffer address calculations.

-> IndexType

indexType is a IndexType value specifying the size of the indices.

-> io () 

vkCmdBindIndexBuffer - Bind an index buffer to a command buffer

Valid Usage

  • offset must be less than the size of buffer

Valid Usage (Implicit)

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

Host Synchronization

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

Command Properties

'

Command Buffer LevelsRender Pass ScopeVideo Coding ScopeSupported Queue TypesCommand Type
Primary SecondaryBoth Outside Graphics State

See Also

VK_VERSION_1_0, Buffer, CommandBuffer, DeviceSize, IndexType

cmdBindVertexBuffers Source #

Arguments

:: forall io. MonadIO io 
=> CommandBuffer

commandBuffer is the command buffer into which the command is recorded.

-> ("firstBinding" ::: Word32)

firstBinding is the index of the first vertex input binding whose state is updated by the command.

-> ("buffers" ::: Vector Buffer)

pBuffers is a pointer to an array of buffer handles.

-> ("offsets" ::: Vector DeviceSize)

pOffsets is a pointer to an array of buffer offsets.

-> 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 drawing 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

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

Valid Usage (Implicit)

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

Host Synchronization

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

Command Properties

'

Command Buffer LevelsRender Pass ScopeVideo Coding ScopeSupported Queue TypesCommand Type
Primary SecondaryBoth Outside Graphics State

See Also

VK_VERSION_1_0, Buffer, CommandBuffer, DeviceSize

cmdDraw Source #

Arguments

:: forall io. MonadIO io 
=> CommandBuffer

commandBuffer is the command buffer into which the command is recorded.

-> ("vertexCount" ::: Word32)

vertexCount is the number of vertices to draw.

-> ("instanceCount" ::: Word32)

instanceCount is the number of instances to draw.

-> ("firstVertex" ::: Word32)

firstVertex is the index of the first vertex to draw.

-> ("firstInstance" ::: Word32)

firstInstance is the instance ID of the first instance to draw.

-> 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

Valid Usage (Implicit)

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

Host Synchronization

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

Command Properties

'

Command Buffer LevelsRender Pass ScopeVideo Coding ScopeSupported Queue TypesCommand Type
Primary SecondaryInside Outside Graphics Action

See Also

VK_VERSION_1_0, CommandBuffer

cmdDrawIndexed Source #

Arguments

:: forall io. MonadIO io 
=> CommandBuffer

commandBuffer is the command buffer into which the command is recorded.

-> ("indexCount" ::: Word32)

indexCount is the number of vertices to draw.

-> ("instanceCount" ::: Word32)

instanceCount is the number of instances to draw.

-> ("firstIndex" ::: Word32)

firstIndex is the base index within the index buffer.

-> ("vertexOffset" ::: Int32)

vertexOffset is the value added to the vertex index before indexing into the vertex buffer.

-> ("firstInstance" ::: Word32)

firstInstance is the instance ID of the first instance to draw.

-> io () 

vkCmdDrawIndexed - Draw primitives with indexed vertices

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 cmdBindIndexBuffer2KHR::indexType or 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 or cmdBindIndexBuffer2KHR, 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

Valid Usage (Implicit)

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

Host Synchronization

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

Command Properties

'

Command Buffer LevelsRender Pass ScopeVideo Coding ScopeSupported Queue TypesCommand Type
Primary SecondaryInside Outside Graphics Action

See Also

VK_VERSION_1_0, CommandBuffer

cmdDrawIndirect Source #

Arguments

:: forall io. MonadIO io 
=> CommandBuffer

commandBuffer is the command buffer into which the command is recorded.

-> Buffer

buffer is the buffer containing draw parameters.

-> ("offset" ::: DeviceSize)

offset is the byte offset into buffer where parameters begin.

-> ("drawCount" ::: Word32)

drawCount is the number of draws to execute, and can be zero.

-> ("stride" ::: Word32)

stride is the byte stride between successive sets of draw parameters.

-> io () 

vkCmdDrawIndirect - Draw primitives with indirect parameters

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

Valid Usage (Implicit)

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

Host Synchronization

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

Command Properties

'

Command Buffer LevelsRender Pass ScopeVideo Coding ScopeSupported Queue TypesCommand Type
Primary SecondaryInside Outside Graphics Action

See Also

VK_VERSION_1_0, Buffer, CommandBuffer, DeviceSize

cmdDrawIndexedIndirect Source #

Arguments

:: forall io. MonadIO io 
=> CommandBuffer

commandBuffer is the command buffer into which the command is recorded.

-> Buffer

buffer is the buffer containing draw parameters.

-> ("offset" ::: DeviceSize)

offset is the byte offset into buffer where parameters begin.

-> ("drawCount" ::: Word32)

drawCount is the number of draws to execute, and can be zero.

-> ("stride" ::: Word32)

stride is the byte stride between successive sets of draw parameters.

-> io () 

vkCmdDrawIndexedIndirect - Draw primitives with indirect parameters and indexed vertices

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

Valid Usage (Implicit)

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

Host Synchronization

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

Command Properties

'

Command Buffer LevelsRender Pass ScopeVideo Coding ScopeSupported Queue TypesCommand Type
Primary SecondaryInside Outside Graphics Action

See Also

VK_VERSION_1_0, Buffer, CommandBuffer, DeviceSize

cmdDispatch Source #

Arguments

:: forall io. MonadIO io 
=> CommandBuffer

commandBuffer is the command buffer into which the command will be recorded.

-> ("groupCountX" ::: Word32)

groupCountX is the number of local workgroups to dispatch in the X dimension.

-> ("groupCountY" ::: Word32)

groupCountY is the number of local workgroups to dispatch in the Y dimension.

-> ("groupCountZ" ::: Word32)

groupCountZ is the number of local workgroups to dispatch in the Z dimension.

-> 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

Valid Usage (Implicit)

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

Host Synchronization

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

Command Properties

'

Command Buffer LevelsRender Pass ScopeVideo Coding ScopeSupported Queue TypesCommand Type
Primary SecondaryOutside Outside Compute Action

See Also

VK_VERSION_1_0, CommandBuffer

cmdDispatchIndirect Source #

Arguments

:: forall io. MonadIO io 
=> CommandBuffer

commandBuffer is the command buffer into which the command will be recorded.

-> Buffer

buffer is the buffer containing dispatch parameters.

-> ("offset" ::: DeviceSize)

offset is the byte offset into buffer where parameters begin.

-> io () 

vkCmdDispatchIndirect - Dispatch compute work items with 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

Valid Usage (Implicit)

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

Host Synchronization

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

Command Properties

'

Command Buffer LevelsRender Pass ScopeVideo Coding ScopeSupported Queue TypesCommand Type
Primary SecondaryOutside Outside Compute Action

See Also

VK_VERSION_1_0, Buffer, CommandBuffer, DeviceSize

cmdCopyBuffer Source #

Arguments

:: forall io. MonadIO io 
=> CommandBuffer

commandBuffer is the command buffer into which the command will be recorded.

-> ("srcBuffer" ::: Buffer)

srcBuffer is the source buffer.

-> ("dstBuffer" ::: Buffer)

dstBuffer is the destination buffer.

-> ("regions" ::: Vector BufferCopy)

pRegions is a pointer to an array of BufferCopy structures specifying the regions to copy.

-> io () 

vkCmdCopyBuffer - Copy data between buffer regions

Description

Each source region specified by pRegions is copied from the source buffer to the destination region of the destination buffer. If any of the specified regions in srcBuffer overlaps in memory with any of the specified regions in dstBuffer, values read from those overlapping regions are undefined.

Valid Usage

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

Valid Usage (Implicit)

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

Host Synchronization

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

Command Properties

'

Command Buffer LevelsRender Pass ScopeVideo Coding ScopeSupported Queue TypesCommand Type
Primary Secondary Outside Outside Transfer Graphics ComputeAction

See Also

VK_VERSION_1_0, Buffer, BufferCopy, CommandBuffer

cmdCopyImage Source #

Arguments

:: forall io. MonadIO io 
=> CommandBuffer

commandBuffer is the command buffer into which the command will be recorded.

-> ("srcImage" ::: Image)

srcImage is the source image.

-> ("srcImageLayout" ::: ImageLayout)

srcImageLayout is the current layout of the source image subresource.

-> ("dstImage" ::: Image)

dstImage is the destination image.

-> ("dstImageLayout" ::: ImageLayout)

dstImageLayout is the current layout of the destination image subresource.

-> ("regions" ::: Vector ImageCopy)

pRegions is a pointer to an array of ImageCopy structures specifying the regions to copy.

-> io () 

vkCmdCopyImage - Copy data between images

Description

Each source region specified by pRegions is copied from the source image to the destination region of the destination image. If any of the specified regions in srcImage overlaps in memory with any of the specified regions in dstImage, values read from those overlapping regions are undefined.

Multi-planar images can only be copied on a per-plane basis, and the subresources used in each region when copying to or from such images must specify only one plane, though different regions can specify different planes. When copying planes of multi-planar images, the format considered is the compatible format for that plane, rather than the format of the multi-planar image.

If the format of the destination image has a different block extent than the source image (e.g. one is a compressed format), the offset and extent for each of the regions specified is scaled according to the block extents of each format to match in size. Copy regions for each image must be aligned to a multiple of the texel block extent in each dimension, except at the edges of the image, where region extents must match the edge of the image.

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; depth slices in the 3D image correspond to layerCount layers in the 2D image, with an effective depth of 1 used for the 2D image. If maintenance5 is enabled, all other combinations are allowed and function as if 1D images are 2D images with a height of 1. Otherwise, other combinations of image types are disallowed.

Valid Usage

  • If commandBuffer is an unprotected command buffer and protectedNoFault is not supported, srcImage must not be a protected image
  • If commandBuffer is an unprotected command buffer and protectedNoFault is not supported, dstImage must not be a protected image
  • If commandBuffer is a protected command buffer and protectedNoFault is not supported, dstImage must not be an unprotected image
  • The union of all source regions, and the union of all destination regions, specified by the elements of pRegions, must not overlap in memory
  • The format features of srcImage must contain FORMAT_FEATURE_TRANSFER_SRC_BIT
  • srcImageLayout must specify the layout of the image subresources of srcImage specified in pRegions at the time this command is executed on a Device
  • srcImageLayout must be IMAGE_LAYOUT_SHARED_PRESENT_KHR, IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL, or IMAGE_LAYOUT_GENERAL
  • The format features of dstImage must contain FORMAT_FEATURE_TRANSFER_DST_BIT
  • dstImageLayout must specify the layout of the image subresources of dstImage specified in pRegions at the time this command is executed on a Device
  • dstImageLayout must be IMAGE_LAYOUT_SHARED_PRESENT_KHR, IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL, or IMAGE_LAYOUT_GENERAL
  • If the Format of each of srcImage and dstImage is not a multi-planar format, the Format of each of srcImage and dstImage must be size-compatible
  • 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
  • If the Format of each of srcImage and dstImage is a compressed image format, the formats must have the same texel block extent
  • The sample count of srcImage and dstImage must match
  • The srcOffset and extent members of each element of pRegions must respect the image transfer granularity requirements of commandBuffer’s command pool’s queue family, as described in QueueFamilyProperties
  • The dstOffset and extent members of each element of pRegions must respect the image transfer granularity requirements of commandBuffer’s command pool’s queue family, as described in QueueFamilyProperties
  • If neither srcImage nor dstImage has a multi-planar image format then for each element of pRegions, srcSubresource.aspectMask and dstSubresource.aspectMask must match
  • If srcImage has a multi-planar image format, then for each element of pRegions, srcSubresource.aspectMask must be a single valid multi-planar aspect mask bit
  • If dstImage has a multi-planar image format, then for each element of pRegions, dstSubresource.aspectMask must be a single valid multi-planar aspect mask bit
  • If srcImage has a multi-planar image format and the dstImage does not have a multi-planar image format, then for each element of pRegions, dstSubresource.aspectMask must be IMAGE_ASPECT_COLOR_BIT
  • If dstImage has a multi-planar image format and the srcImage does not have a multi-planar image format, then for each element of pRegions, srcSubresource.aspectMask must be IMAGE_ASPECT_COLOR_BIT
  • If the VK_KHR_maintenance1 extension is not enabled, or PhysicalDeviceProperties::apiVersion is less than Vulkan 1.1, and either srcImage or dstImage is of type IMAGE_TYPE_3D, then for each element of pRegions, srcSubresource.baseArrayLayer and dstSubresource.baseArrayLayer must both be 0, and srcSubresource.layerCount and dstSubresource.layerCount must both be 1
  • If srcImage is of type IMAGE_TYPE_3D, then for each element of pRegions, srcSubresource.baseArrayLayer must be 0 and srcSubresource.layerCount must be 1
  • If dstImage is of type IMAGE_TYPE_3D, then for each element of pRegions, dstSubresource.baseArrayLayer must be 0 and dstSubresource.layerCount must be 1
  • For each element of pRegions, srcSubresource.aspectMask must specify aspects present in srcImage
  • For each element of pRegions, dstSubresource.aspectMask must specify aspects present in dstImage
  • For each element of pRegions, srcOffset.x and (extent.width + srcOffset.x) must both be greater than or equal to 0 and less than or equal to the width of the specified srcSubresource of srcImage
  • For each element of pRegions, srcOffset.y and (extent.height + srcOffset.y) must both be greater than or equal to 0 and less than or equal to the height of the specified srcSubresource of srcImage
  • If srcImage is of type IMAGE_TYPE_1D, then for each element of pRegions, srcOffset.y must be 0 and extent.height must be 1
  • If srcImage is of type IMAGE_TYPE_3D, then for each element of pRegions, srcOffset.z and (extent.depth + srcOffset.z) must both be greater than or equal to 0 and less than or equal to the depth of the specified srcSubresource of srcImage
  • If srcImage is of type IMAGE_TYPE_1D, then for each element of pRegions, srcOffset.z must be 0 and extent.depth must be 1
  • If dstImage is of type IMAGE_TYPE_1D, then for each element of pRegions, dstOffset.z must be 0 and extent.depth must be 1
  • If srcImage is of type IMAGE_TYPE_2D, then for each element of pRegions, srcOffset.z must be 0
  • If dstImage is of type IMAGE_TYPE_2D, then for each element of pRegions, dstOffset.z must be 0
  • If the VK_KHR_maintenance1 extension is not enabled, and PhysicalDeviceProperties::apiVersion is less than Vulkan 1.1, srcImage and dstImage must have the same ImageType
  • If the VK_KHR_maintenance1 extension is not enabled, and PhysicalDeviceProperties::apiVersion is less than Vulkan 1.1, srcImage or dstImage is of type IMAGE_TYPE_2D, then for each element of pRegions, extent.depth must be 1
  • If srcImage and dstImage have a different ImageType, and maintenance5 is not enabled, one must be IMAGE_TYPE_3D and the other must be IMAGE_TYPE_2D
  • If srcImage and dstImage have the same ImageType, for each element of pRegions, if neither of the layerCount members of srcSubresource or dstSubresource are REMAINING_ARRAY_LAYERS, the layerCount members of srcSubresource or dstSubresource must match
  • If the maintenance5 feature is not enabled, the layerCount member of srcSubresource or dstSubresource must not be REMAINING_ARRAY_LAYERS
  • If srcImage and dstImage have the same ImageType, and one of the layerCount members of srcSubresource or dstSubresource is REMAINING_ARRAY_LAYERS, the other member must be either REMAINING_ARRAY_LAYERS or equal to the arrayLayers member of the ImageCreateInfo used to create the image minus baseArrayLayer
  • If srcImage and dstImage are both of type IMAGE_TYPE_2D, then for each element of pRegions, extent.depth must be 1
  • If srcImage is of type IMAGE_TYPE_2D, and dstImage is of type IMAGE_TYPE_3D, then for each element of pRegions, extent.depth must equal srcSubresource.layerCount
  • If dstImage is of type IMAGE_TYPE_2D, and srcImage is of type IMAGE_TYPE_3D, then for each element of pRegions, extent.depth must equal dstSubresource.layerCount
  • For each element of pRegions, dstOffset.x and (extent.width + dstOffset.x) must both be greater than or equal to 0 and less than or equal to the width of the specified dstSubresource of dstImage
  • For each element of pRegions, dstOffset.y and (extent.height + dstOffset.y) must both be greater than or equal to 0 and less than or equal to the height of the specified dstSubresource of dstImage
  • If dstImage is of type IMAGE_TYPE_1D, then for each element of pRegions, dstOffset.y must be 0 and extent.height must be 1
  • If dstImage is of type IMAGE_TYPE_3D, then for each element of pRegions, dstOffset.z and (extent.depth + dstOffset.z) must both be greater than or equal to 0 and less than or equal to the depth of the specified dstSubresource of dstImage
  • For each element of pRegions, srcOffset.x must be a multiple of the texel block extent width of the Format of srcImage
  • For each element of pRegions, srcOffset.y must be a multiple of the texel block extent height of the Format of srcImage
  • For each element of pRegions, srcOffset.z must be a multiple of the texel block extent depth of the Format of srcImage
  • For each element of pRegions, dstOffset.x must be a multiple of the texel block extent width of the Format of dstImage
  • For each element of pRegions, dstOffset.y must be a multiple of the texel block extent height of the Format of dstImage
  • For each element of pRegions, dstOffset.z must be a multiple of the texel block extent depth of the Format of dstImage
  • For each element of pRegions, if the sum of srcOffset.x and extent.width does not equal the width of the subresource specified by srcSubresource, extent.width must be a multiple of the texel block extent width of the Format of srcImage
  • For each element of pRegions, if the sum of srcOffset.y and extent.height does not equal the height of the subresource specified by srcSubresource, extent.height must be a multiple of the texel block extent height of the Format of srcImage
  • For each element of pRegions, if the sum of srcOffset.z and extent.depth does not equal the depth of the subresource specified by srcSubresource, extent.depth must be a multiple of the texel block extent depth of the Format of srcImage
  • For each element of pRegions, if the sum of dstOffset.x and extent.width does not equal the width of the subresource specified by dstSubresource, extent.width must be a multiple of the texel block extent width of the Format of dstImage
  • For each element of pRegions, if the sum of dstOffset.y and extent.height does not equal the height of the subresource specified by dstSubresource, extent.height must be a multiple of the texel block extent height of the Format of dstImage
  • For each element of pRegions, if the sum of dstOffset.z and extent.depth does not equal the depth of the subresource specified by dstSubresource, extent.depth must be a multiple of the texel block extent depth of the Format of dstImage
  • If the aspect member of any element of pRegions includes any flag other than IMAGE_ASPECT_STENCIL_BIT or srcImage was not created with separate stencil usage, IMAGE_USAGE_TRANSFER_SRC_BIT must have been included in the ImageCreateInfo::usage used to create srcImage
  • If the aspect member of any element of pRegions includes any flag other than IMAGE_ASPECT_STENCIL_BIT or dstImage was not created with separate stencil usage, IMAGE_USAGE_TRANSFER_DST_BIT must have been included in the ImageCreateInfo::usage used to create dstImage
  • If the aspect member of any element of pRegions includes IMAGE_ASPECT_STENCIL_BIT, and srcImage was created with separate stencil usage, IMAGE_USAGE_TRANSFER_SRC_BIT must have been included in the ImageStencilUsageCreateInfo::stencilUsage used to create srcImage
  • If the aspect member of any element of pRegions includes IMAGE_ASPECT_STENCIL_BIT, and dstImage was created with separate stencil usage, IMAGE_USAGE_TRANSFER_DST_BIT must have been included in the ImageStencilUsageCreateInfo::stencilUsage used to create dstImage
  • If srcImage is non-sparse then the image or the specified disjoint plane must be bound completely and contiguously to a single DeviceMemory object
  • The srcSubresource.mipLevel member of each element of pRegions must be less than the mipLevels specified in ImageCreateInfo when srcImage was created
  • If srcSubresource.layerCount is not REMAINING_ARRAY_LAYERS, srcSubresource.baseArrayLayer + srcSubresource.layerCount of each element of pRegions must be less than or equal to the arrayLayers specified in ImageCreateInfo when srcImage was created
  • srcImage must not have been created with flags containing IMAGE_CREATE_SUBSAMPLED_BIT_EXT
  • If dstImage is non-sparse then the image or the specified disjoint plane must be bound completely and contiguously to a single DeviceMemory object
  • The dstSubresource.mipLevel member of each element of pRegions must be less than the mipLevels specified in ImageCreateInfo when dstImage was created
  • If dstSubresource.layerCount is not REMAINING_ARRAY_LAYERS, dstSubresource.baseArrayLayer + dstSubresource.layerCount of each element of pRegions must be less than or equal to the arrayLayers specified in ImageCreateInfo when dstImage was created
  • dstImage must not have been created with flags containing IMAGE_CREATE_SUBSAMPLED_BIT_EXT

Valid Usage (Implicit)

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

Host Synchronization

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

Command Properties

'

Command Buffer LevelsRender Pass ScopeVideo Coding ScopeSupported Queue TypesCommand Type
Primary Secondary Outside Outside Transfer Graphics ComputeAction

See Also

VK_VERSION_1_0, CommandBuffer, Image, ImageCopy, ImageLayout

cmdBlitImage Source #

Arguments

:: forall io. MonadIO io 
=> CommandBuffer

commandBuffer is the command buffer into which the command will be recorded.

-> ("srcImage" ::: Image)

srcImage is the source image.

-> ("srcImageLayout" ::: ImageLayout)

srcImageLayout is the layout of the source image subresources for the blit.

-> ("dstImage" ::: Image)

dstImage is the destination image.

-> ("dstImageLayout" ::: ImageLayout)

dstImageLayout is the layout of the destination image subresources for the blit.

-> ("regions" ::: Vector ImageBlit)

pRegions is a pointer to an array of ImageBlit structures specifying the regions to blit.

-> Filter

filter is a Filter specifying the filter to apply if the blits require scaling.

-> 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 - baseArrayCountdst
  • The scale is determined from the source and destination regions, and applied to the offset coordinates:

    • scaleu = (xsrc1 - xsrc0) / (xdst1 - xdst0)
    • scalev = (ysrc1 - ysrc0) / (ydst1 - ydst0)
    • scalew = (zsrc1 - zsrc0) / (zdst1 - zdst0)
    • uscaled = uoffset × scaleu
    • vscaled = voffset × scalev
    • wscaled = woffset × scalew
  • Finally the source offset is added to the scaled coordinates, to determine the final unnormalized coordinates used to sample from srcImage:

    • u = uscaled + xsrc0
    • v = vscaled + ysrc0
    • w = wscaled + zsrc0
    • q = mipLevel
    • a = aoffset + baseArrayCountsrc

These coordinates are used to sample from the source image, as described in Image Operations chapter, with the filter mode equal to that of filter, a mipmap mode of SAMPLER_MIPMAP_MODE_NEAREST and an address mode of SAMPLER_ADDRESS_MODE_CLAMP_TO_EDGE. Implementations must clamp at the edge of the source image, and may additionally clamp to the edge of the source region.

Note

Due to allowable rounding errors in the generation of the source texture coordinates, it is not always possible to guarantee exactly which source texels will be sampled for a given blit. As rounding errors are implementation-dependent, the exact results of a blitting operation are also implementation-dependent.

Blits are done layer by layer starting with the baseArrayLayer member of srcSubresource for the source and dstSubresource for the destination. layerCount layers are blitted to the destination image.

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, scaled 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 and protectedNoFault is not supported, srcImage must not be a protected image
  • If commandBuffer is an unprotected command buffer and protectedNoFault is not supported, dstImage must not be a protected image
  • If commandBuffer is a protected command buffer and protectedNoFault is not supported, dstImage must not be an unprotected image
  • The source region specified by each element of pRegions must be a region that is contained within srcImage
  • The destination region specified by each element of pRegions must be a region that is contained within dstImage
  • The union of all destination regions, specified by the elements of pRegions, must not overlap in memory with any texel that may be sampled during the blit operation
  • The format features of srcImage must contain FORMAT_FEATURE_BLIT_SRC_BIT
  • srcImage must not use a format that requires a sampler Y′CBCR conversion
  • srcImage must have been created with IMAGE_USAGE_TRANSFER_SRC_BIT usage flag
  • If srcImage is non-sparse then it must be bound completely and contiguously to a single DeviceMemory object
  • srcImageLayout must specify the layout of the image subresources of srcImage specified in pRegions at the time this command is executed on a Device
  • srcImageLayout must be IMAGE_LAYOUT_SHARED_PRESENT_KHR, IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL or IMAGE_LAYOUT_GENERAL
  • The format features of dstImage must contain FORMAT_FEATURE_BLIT_DST_BIT
  • dstImage must not use a format that requires a sampler Y′CBCR conversion
  • dstImage must have been created with IMAGE_USAGE_TRANSFER_DST_BIT usage flag
  • If dstImage is non-sparse then it must be bound completely and contiguously to a single DeviceMemory object
  • dstImageLayout must specify the layout of the image subresources of dstImage specified in pRegions at the time this command is executed on a Device
  • dstImageLayout must be IMAGE_LAYOUT_SHARED_PRESENT_KHR, IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL or IMAGE_LAYOUT_GENERAL
  • If either of srcImage or dstImage was created with a signed integer Format, the other must also have been created with a signed integer Format
  • If either of srcImage or dstImage was created with an unsigned integer Format, the other must also have been created with an unsigned integer Format
  • If either of srcImage or dstImage was created with a depth/stencil format, the other must have exactly the same format
  • If srcImage was created with a depth/stencil format, filter must be FILTER_NEAREST
  • srcImage must have been created with a samples value of SAMPLE_COUNT_1_BIT
  • dstImage must have been created with a samples value of SAMPLE_COUNT_1_BIT
  • If filter is FILTER_LINEAR, then the format features of srcImage must contain FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_LINEAR_BIT
  • If filter is FILTER_CUBIC_EXT, then the format features of srcImage must contain FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_CUBIC_BIT_EXT
  • If filter is FILTER_CUBIC_EXT, srcImage must be of type IMAGE_TYPE_2D
  • The srcSubresource.mipLevel member of each element of pRegions must be less than the mipLevels specified in ImageCreateInfo when srcImage was created
  • The dstSubresource.mipLevel member of each element of pRegions must be less than the mipLevels specified in ImageCreateInfo when dstImage was created
  • If srcSubresource.layerCount is not REMAINING_ARRAY_LAYERS, srcSubresource.baseArrayLayer + srcSubresource.layerCount of each element of pRegions must be less than or equal to the arrayLayers specified in ImageCreateInfo when srcImage was created
  • If srcSubresource.layerCount is not REMAINING_ARRAY_LAYERS, dstSubresource.baseArrayLayer + dstSubresource.layerCount of each element of pRegions must be less than or equal to the arrayLayers specified in ImageCreateInfo when dstImage was created
  • dstImage and srcImage must not have been created with flags containing IMAGE_CREATE_SUBSAMPLED_BIT_EXT
  • If either srcImage or dstImage is of type IMAGE_TYPE_3D, then for each element of pRegions, srcSubresource.baseArrayLayer and dstSubresource.baseArrayLayer must each be 0, and srcSubresource.layerCount and dstSubresource.layerCount must each be 1
  • For each element of pRegions, srcSubresource.aspectMask must specify aspects present in srcImage
  • For each element of pRegions, dstSubresource.aspectMask must specify aspects present in dstImage
  • For each element of pRegions, srcOffsets[0].x and srcOffsets[1].x must both be greater than or equal to 0 and less than or equal to the width of the specified srcSubresource of srcImage
  • For each element of pRegions, srcOffsets[0].y and srcOffsets[1].y must both be greater than or equal to 0 and less than or equal to the height of the specified srcSubresource of srcImage
  • If srcImage is of type IMAGE_TYPE_1D, then for each element of pRegions, srcOffsets[0].y must be 0 and srcOffsets[1].y must be 1
  • For each element of pRegions, srcOffsets[0].z and srcOffsets[1].z must both be greater than or equal to 0 and less than or equal to the depth of the specified srcSubresource of srcImage
  • If srcImage is of type IMAGE_TYPE_1D or IMAGE_TYPE_2D, then for each element of pRegions, srcOffsets[0].z must be 0 and srcOffsets[1].z must be 1
  • For each element of pRegions, dstOffsets[0].x and dstOffsets[1].x must both be greater than or equal to 0 and less than or equal to the width of the specified dstSubresource of dstImage
  • For each element of pRegions, dstOffsets[0].y and dstOffsets[1].y must both be greater than or equal to 0 and less than or equal to the height of the specified dstSubresource of dstImage
  • If dstImage is of type IMAGE_TYPE_1D, then for each element of pRegions, dstOffsets[0].y must be 0 and dstOffsets[1].y must be 1
  • For each element of pRegions, dstOffsets[0].z and dstOffsets[1].z must both be greater than or equal to 0 and less than or equal to the depth of the specified dstSubresource of dstImage
  • If dstImage is of type IMAGE_TYPE_1D or IMAGE_TYPE_2D, then for each element of pRegions, dstOffsets[0].z must be 0 and dstOffsets[1].z must be 1

Valid Usage (Implicit)

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

Host Synchronization

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

Command Properties

'

Command Buffer LevelsRender Pass ScopeVideo Coding ScopeSupported Queue TypesCommand Type
Primary SecondaryOutside Outside Graphics Action

See Also

VK_VERSION_1_0, CommandBuffer, Filter, Image, ImageBlit, ImageLayout

cmdCopyBufferToImage Source #

Arguments

:: forall io. MonadIO io 
=> CommandBuffer

commandBuffer is the command buffer into which the command will be recorded.

-> ("srcBuffer" ::: Buffer)

srcBuffer is the source buffer.

-> ("dstImage" ::: Image)

dstImage is the destination image.

-> ("dstImageLayout" ::: ImageLayout)

dstImageLayout is the layout of the destination image subresources for the copy.

-> ("regions" ::: Vector BufferImageCopy)

pRegions is a pointer to an array of BufferImageCopy structures specifying the regions to copy.

-> io () 

vkCmdCopyBufferToImage - Copy data from a buffer into an image

Description

Each source region specified by pRegions is copied from the source buffer to the destination region of the destination image according to the addressing calculations for each resource. If any of the specified regions in srcBuffer overlaps in memory with any of the specified regions in dstImage, values read from those overlapping regions are undefined. If any region accesses a depth aspect in dstImage and the VK_EXT_depth_range_unrestricted extension is not enabled, values copied from srcBuffer outside of the range [0,1] will be be written as undefined values to the destination image.

Copy regions for the image must be aligned to a multiple of the texel block extent in each dimension, except at the edges of the image, where region extents must match the edge of the image.

Valid Usage

  • If dstImage is non-sparse then the image or the specified disjoint plane must be bound completely and contiguously to a single DeviceMemory object
  • The imageSubresource.mipLevel member of each element of pRegions must be less than the mipLevels specified in ImageCreateInfo when dstImage was created
  • If imageSubresource.layerCount is not REMAINING_ARRAY_LAYERS, imageSubresource.baseArrayLayer + imageSubresource.layerCount of each element of pRegions must be less than or equal to the arrayLayers specified in ImageCreateInfo when dstImage was created
  • dstImage must not have been created with flags containing IMAGE_CREATE_SUBSAMPLED_BIT_EXT
  • The image region specified by each element of pRegions must be contained within the specified imageSubresource of dstImage
  • For each element of pRegions, imageOffset.x and (imageExtent.width + imageOffset.x) must both be greater than or equal to 0 and less than or equal to the width of the specified imageSubresource of dstImage
  • For each element of pRegions, imageOffset.y and (imageExtent.height + imageOffset.y) must both be greater than or equal to 0 and less than or equal to the height of the specified imageSubresource of dstImage
  • dstImage must have a sample count equal to SAMPLE_COUNT_1_BIT
  • If commandBuffer is an unprotected command buffer and protectedNoFault is not supported, srcBuffer must not be a protected buffer
  • If commandBuffer is an unprotected command buffer and protectedNoFault is not supported, dstImage must not be a protected image
  • If commandBuffer is a protected command buffer and protectedNoFault is not supported, dstImage must not be an unprotected image
  • If the queue family used to create the CommandPool which commandBuffer was allocated from does not support QUEUE_GRAPHICS_BIT or QUEUE_COMPUTE_BIT, the bufferOffset member of any element of pRegions must be a multiple of 4
  • The imageOffset and imageExtent members of each element of pRegions must respect the image transfer granularity requirements of commandBuffer’s command pool’s queue family, as described in QueueFamilyProperties
  • If the queue family used to create the CommandPool which commandBuffer was allocated from does not support QUEUE_GRAPHICS_BIT, for each element of pRegions, the aspectMask member of imageSubresource must not be IMAGE_ASPECT_DEPTH_BIT or IMAGE_ASPECT_STENCIL_BIT
  • srcBuffer must be large enough to contain all buffer locations that are accessed according to Buffer and Image Addressing, for each element of pRegions
  • The union of all source regions, and the union of all destination regions, specified by the elements of pRegions, must not overlap in memory
  • srcBuffer must have been created with BUFFER_USAGE_TRANSFER_SRC_BIT usage flag
  • The format features of dstImage must contain FORMAT_FEATURE_TRANSFER_DST_BIT
  • If srcBuffer is non-sparse then it must be bound completely and contiguously to a single DeviceMemory object
  • dstImage must have been created with IMAGE_USAGE_TRANSFER_DST_BIT usage flag
  • dstImageLayout must specify the layout of the image subresources of dstImage specified in pRegions at the time this command is executed on a Device
  • dstImageLayout must be IMAGE_LAYOUT_SHARED_PRESENT_KHR, IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL, or IMAGE_LAYOUT_GENERAL
  • If VK_EXT_depth_range_unrestricted is not enabled, for each element of pRegions whose imageSubresource contains a depth aspect, the data in srcBuffer must be in the range [0,1]
  • If dstImage is of type IMAGE_TYPE_1D, then for each element of pRegions, imageOffset.y must be 0 and imageExtent.height must be 1
  • For each element of pRegions, imageOffset.z and (imageExtent.depth + imageOffset.z) must both be greater than or equal to 0 and less than or equal to the depth of the specified imageSubresource of dstImage
  • If dstImage is of type IMAGE_TYPE_1D or IMAGE_TYPE_2D, then for each element of pRegions, imageOffset.z must be 0 and imageExtent.depth must be 1
  • For each element of pRegions, imageOffset.x must be a multiple of the texel block extent width of the Format of dstImage
  • For each element of pRegions, imageOffset.y must be a multiple of the texel block extent height of the Format of dstImage
  • For each element of pRegions, imageOffset.z must be a multiple of the texel block extent depth of the Format of dstImage
  • For each element of pRegions, if the sum of imageOffset.x and extent.width does not equal the width of the subresource specified by srcSubresource, extent.width must be a multiple of the texel block extent width of the Format of dstImage
  • For each element of pRegions, if the sum of imageOffset.y and extent.height does not equal the height of the subresource specified by srcSubresource, extent.height must be a multiple of the texel block extent height of the Format of dstImage
  • For each element of pRegions, if the sum of imageOffset.z and extent.depth does not equal the depth of the subresource specified by srcSubresource, extent.depth must be a multiple of the texel block extent depth of the Format of dstImage
  • For each element of pRegions, imageSubresource.aspectMask must specify aspects present in dstImage
  • If dstImage has a multi-planar image format, then for each element of pRegions, imageSubresource.aspectMask must be a single valid multi-planar aspect mask bit
  • If dstImage is of type IMAGE_TYPE_3D, for each element of pRegions, imageSubresource.baseArrayLayer must be 0 and imageSubresource.layerCount must be 1
  • For each element of pRegions, bufferRowLength must be a multiple of the texel block extent width of the Format of dstImage
  • For each element of pRegions, bufferImageHeight must be a multiple of the texel block extent height of the Format of dstImage
  • For each element of pRegions, bufferRowLength divided by the texel block extent width and then multiplied by the texel block size of dstImage must be less than or equal to 231-1
  • If dstImage does not have either a depth/stencil format or a multi-planar format, then for each element of pRegions, bufferOffset must be a multiple of the texel block size
  • If dstImage has a multi-planar format, then for each element of pRegions, bufferOffset must be a multiple of the element size of the compatible format for the format and the aspectMask of the imageSubresource as defined in ???
  • If dstImage has a depth/stencil format, the bufferOffset member of any element of pRegions must be a multiple of 4

Valid Usage (Implicit)

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

Host Synchronization

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

Command Properties

'

Command Buffer LevelsRender Pass ScopeVideo Coding ScopeSupported Queue TypesCommand Type
Primary Secondary Outside Outside Transfer Graphics ComputeAction

See Also

VK_VERSION_1_0, Buffer, BufferImageCopy, CommandBuffer, Image, ImageLayout

cmdCopyImageToBuffer Source #

Arguments

:: forall io. MonadIO io 
=> CommandBuffer

commandBuffer is the command buffer into which the command will be recorded.

-> ("srcImage" ::: Image)

srcImage is the source image.

-> ("srcImageLayout" ::: ImageLayout)

srcImageLayout is the layout of the source image subresources for the copy.

-> ("dstBuffer" ::: Buffer)

dstBuffer is the destination buffer.

-> ("regions" ::: Vector BufferImageCopy)

pRegions is a pointer to an array of BufferImageCopy structures specifying the regions to copy.

-> io () 

vkCmdCopyImageToBuffer - Copy image data into a buffer

Description

Each source region specified by pRegions is copied from the source image to the destination region of the destination buffer according to the addressing calculations for each resource. If any of the specified regions in srcImage overlaps in memory with any of the specified regions in dstBuffer, values read from those overlapping regions are undefined.

Copy regions for the image must be aligned to a multiple of the texel block extent in each dimension, except at the edges of the image, where region extents must match the edge of the image.

Valid Usage

  • If srcImage is non-sparse then the image or the specified disjoint plane must be bound completely and contiguously to a single DeviceMemory object
  • The imageSubresource.mipLevel member of each element of pRegions must be less than the mipLevels specified in ImageCreateInfo when srcImage was created
  • If imageSubresource.layerCount is not REMAINING_ARRAY_LAYERS, imageSubresource.baseArrayLayer + imageSubresource.layerCount of each element of pRegions must be less than or equal to the arrayLayers specified in ImageCreateInfo when srcImage was created
  • srcImage must not have been created with flags containing IMAGE_CREATE_SUBSAMPLED_BIT_EXT
  • The image region specified by each element of pRegions must be contained within the specified imageSubresource of srcImage
  • For each element of pRegions, imageOffset.x and (imageExtent.width + imageOffset.x) must both be greater than or equal to 0 and less than or equal to the width of the specified imageSubresource of srcImage
  • For each element of pRegions, imageOffset.y and (imageExtent.height + imageOffset.y) must both be greater than or equal to 0 and less than or equal to the height of the specified imageSubresource of srcImage
  • srcImage must have a sample count equal to SAMPLE_COUNT_1_BIT
  • If commandBuffer is an unprotected command buffer and protectedNoFault is not supported, srcImage must not be a protected image
  • If commandBuffer is an unprotected command buffer and protectedNoFault is not supported, dstBuffer must not be a protected buffer
  • If commandBuffer is a protected command buffer and protectedNoFault is not supported, dstBuffer must not be an unprotected buffer
  • If the queue family used to create the CommandPool which commandBuffer was allocated from does not support QUEUE_GRAPHICS_BIT or QUEUE_COMPUTE_BIT, the bufferOffset member of any element of pRegions must be a multiple of 4
  • The imageOffset and imageExtent members of each element of pRegions must respect the image transfer granularity requirements of commandBuffer’s command pool’s queue family, as described in QueueFamilyProperties
  • dstBuffer must be large enough to contain all buffer locations that are accessed according to Buffer and Image Addressing, for each element of pRegions
  • The union of all source regions, and the union of all destination regions, specified by the elements of pRegions, must not overlap in memory
  • srcImage must have been created with IMAGE_USAGE_TRANSFER_SRC_BIT usage flag
  • The format features of srcImage must contain FORMAT_FEATURE_TRANSFER_SRC_BIT
  • dstBuffer must have been created with BUFFER_USAGE_TRANSFER_DST_BIT usage flag
  • If dstBuffer is non-sparse then it must be bound completely and contiguously to a single DeviceMemory object
  • srcImageLayout must specify the layout of the image subresources of srcImage specified in pRegions at the time this command is executed on a Device
  • srcImageLayout must be IMAGE_LAYOUT_SHARED_PRESENT_KHR, IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL, or IMAGE_LAYOUT_GENERAL
  • If srcImage is of type IMAGE_TYPE_1D, then for each element of pRegions, imageOffset.y must be 0 and imageExtent.height must be 1
  • For each element of pRegions, imageOffset.z and (imageExtent.depth + imageOffset.z) must both be greater than or equal to 0 and less than or equal to the depth of the specified imageSubresource of srcImage
  • If srcImage is of type IMAGE_TYPE_1D or IMAGE_TYPE_2D, then for each element of pRegions, imageOffset.z must be 0 and imageExtent.depth must be 1
  • For each element of pRegions, imageOffset.x must be a multiple of the texel block extent width of the Format of srcImage
  • For each element of pRegions, imageOffset.y must be a multiple of the texel block extent height of the Format of srcImage
  • For each element of pRegions, imageOffset.z must be a multiple of the texel block extent depth of the Format of srcImage
  • For each element of pRegions, if the sum of imageOffset.x and extent.width does not equal the width of the subresource specified by srcSubresource, extent.width must be a multiple of the texel block extent width of the Format of srcImage
  • For each element of pRegions, if the sum of imageOffset.y and extent.height does not equal the height of the subresource specified by srcSubresource, extent.height must be a multiple of the texel block extent height of the Format of srcImage
  • For each element of pRegions, if the sum of imageOffset.z and extent.depth does not equal the depth of the subresource specified by srcSubresource, extent.depth must be a multiple of the texel block extent depth of the Format of srcImage
  • For each element of pRegions, imageSubresource.aspectMask must specify aspects present in srcImage
  • If srcImage has a multi-planar image format, then for each element of pRegions, imageSubresource.aspectMask must be a single valid multi-planar aspect mask bit
  • If srcImage is of type IMAGE_TYPE_3D, for each element of pRegions, imageSubresource.baseArrayLayer must be 0 and imageSubresource.layerCount must be 1
  • For each element of pRegions, bufferRowLength must be a multiple of the texel block extent width of the Format of srcImage
  • For each element of pRegions, bufferImageHeight must be a multiple of the texel block extent height of the Format of srcImage
  • For each element of pRegions, bufferRowLength divided by the texel block extent width and then multiplied by the texel block size of srcImage must be less than or equal to 231-1
  • If srcImage does not have either a depth/stencil format or a multi-planar format, then for each element of pRegions, bufferOffset must be a multiple of the texel block size
  • If srcImage has a multi-planar format, then for each element of pRegions, bufferOffset must be a multiple of the element size of the compatible format for the format and the aspectMask of the imageSubresource as defined in ???
  • If srcImage has a depth/stencil format, the bufferOffset member of any element of pRegions must be a multiple of 4

Valid Usage (Implicit)

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

Host Synchronization

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

Command Properties

'

Command Buffer LevelsRender Pass ScopeVideo Coding ScopeSupported Queue TypesCommand Type
Primary Secondary Outside Outside Transfer Graphics ComputeAction

See Also

VK_VERSION_1_0, Buffer, BufferImageCopy, CommandBuffer, Image, ImageLayout

cmdUpdateBuffer Source #

Arguments

:: forall io. MonadIO io 
=> CommandBuffer

commandBuffer is the command buffer into which the command will be recorded.

-> ("dstBuffer" ::: Buffer)

dstBuffer is a handle to the buffer to be updated.

-> ("dstOffset" ::: DeviceSize)

dstOffset is the byte offset into the buffer to start updating, and must be a multiple of 4.

-> ("dataSize" ::: DeviceSize)

dataSize is the number of bytes to update, and must be a multiple of 4.

-> ("data" ::: Ptr ())

pData is a pointer to the source data for the buffer update, and must be at least dataSize bytes in size.

-> 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 a “transfer” operation for the purposes of synchronization barriers. The BUFFER_USAGE_TRANSFER_DST_BIT must be specified in usage of BufferCreateInfo in order for the buffer to be compatible with cmdUpdateBuffer.

Valid Usage

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

Valid Usage (Implicit)

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

Host Synchronization

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

Command Properties

'

Command Buffer LevelsRender Pass ScopeVideo Coding ScopeSupported Queue TypesCommand Type
Primary Secondary Outside Outside Transfer Graphics ComputeAction

See Also

VK_VERSION_1_0, Buffer, CommandBuffer, DeviceSize

cmdFillBuffer Source #

Arguments

:: forall io. MonadIO io 
=> CommandBuffer

commandBuffer is the command buffer into which the command will be recorded.

-> ("dstBuffer" ::: Buffer)

dstBuffer is the buffer to be filled.

-> ("dstOffset" ::: DeviceSize)

dstOffset is the byte offset into the buffer at which to start filling, and must be a multiple of 4.

-> DeviceSize

size is the number of bytes to fill, and must be either a multiple of 4, or WHOLE_SIZE to fill the range from offset to the end of the buffer. If WHOLE_SIZE is used and the remaining size of the buffer is not a multiple of 4, then the nearest smaller multiple is used.

-> ("data" ::: Word32)

data is the 4-byte word written repeatedly to the buffer to fill size bytes of data. The data word is written to memory according to the host endianness.

-> io () 

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

Description

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

Valid Usage

  • dstOffset must be less than the size of dstBuffer
  • dstOffset must be a multiple of 4
  • If size is not equal to WHOLE_SIZE, size must be greater than 0
  • If size is not equal to WHOLE_SIZE, size must be less than or equal to the size of dstBuffer minus dstOffset
  • If size is not equal to WHOLE_SIZE, size must be a multiple of 4
  • dstBuffer must have been created with BUFFER_USAGE_TRANSFER_DST_BIT usage flag
  • If the VK_KHR_maintenance1 extension is not enabled and PhysicalDeviceProperties::apiVersion is less than Vulkan 1.1, the CommandPool that commandBuffer was allocated from must support graphics or compute operations
  • If dstBuffer is non-sparse then it must be bound completely and contiguously to a single DeviceMemory object
  • If commandBuffer is an unprotected command buffer and protectedNoFault is not supported, dstBuffer must not be a protected buffer
  • If commandBuffer is a protected command buffer and protectedNoFault is not supported, dstBuffer must not be an unprotected buffer

Valid Usage (Implicit)

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

Host Synchronization

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

Command Properties

'

Command Buffer LevelsRender Pass ScopeVideo Coding ScopeSupported Queue TypesCommand Type
Primary Secondary Outside Outside Transfer Graphics ComputeAction

See Also

VK_VERSION_1_0, Buffer, CommandBuffer, DeviceSize

cmdClearColorImage Source #

Arguments

:: forall io. MonadIO io 
=> CommandBuffer

commandBuffer is the command buffer into which the command will be recorded.

-> Image

image is the image to be cleared.

-> ImageLayout

imageLayout specifies the current layout of the image subresource ranges to be cleared, and must be IMAGE_LAYOUT_SHARED_PRESENT_KHR, IMAGE_LAYOUT_GENERAL or IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL.

-> ClearColorValue

pColor is a pointer to a ClearColorValue structure containing the values that the image subresource ranges will be cleared to (see https://registry.khronos.org/vulkan/specs/1.3-extensions/html/vkspec.html#clears-values below).

-> ("ranges" ::: Vector ImageSubresourceRange)

pRanges is a pointer to an array of ImageSubresourceRange structures describing a range of mipmap levels, array layers, and aspects to be cleared, as described in Image Views.

-> io () 

vkCmdClearColorImage - Clear regions of a color image

Description

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

Valid Usage

Valid Usage (Implicit)

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

Host Synchronization

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

Command Properties

'

Command Buffer LevelsRender Pass ScopeVideo Coding ScopeSupported Queue TypesCommand Type
Primary SecondaryOutside Outside Graphics ComputeAction

See Also

VK_VERSION_1_0, ClearColorValue, CommandBuffer, Image, ImageLayout, ImageSubresourceRange

cmdClearDepthStencilImage Source #

Arguments

:: forall io. MonadIO io 
=> CommandBuffer

commandBuffer is the command buffer into which the command will be recorded.

-> Image

image is the image to be cleared.

-> ImageLayout

imageLayout specifies the current layout of the image subresource ranges to be cleared, and must be IMAGE_LAYOUT_GENERAL or IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL.

-> ClearDepthStencilValue

pDepthStencil is a pointer to a ClearDepthStencilValue structure containing the values that the depth and stencil image subresource ranges will be cleared to (see https://registry.khronos.org/vulkan/specs/1.3-extensions/html/vkspec.html#clears-values below).

-> ("ranges" ::: Vector ImageSubresourceRange)

pRanges is a pointer to an array of ImageSubresourceRange structures describing a range of mipmap levels, array layers, and aspects to be cleared, as described in Image Views.

-> io () 

vkCmdClearDepthStencilImage - Fill regions of a combined depth/stencil image

Valid Usage

Valid Usage (Implicit)

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

Host Synchronization

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

Command Properties

'

Command Buffer LevelsRender Pass ScopeVideo Coding ScopeSupported Queue TypesCommand Type
Primary SecondaryOutside Outside Graphics Action

See Also

VK_VERSION_1_0, ClearDepthStencilValue, CommandBuffer, Image, ImageLayout, ImageSubresourceRange

cmdClearAttachments Source #

Arguments

:: forall io. MonadIO io 
=> CommandBuffer

commandBuffer is the command buffer into which the command will be recorded.

-> ("attachments" ::: Vector ClearAttachment)

pAttachments is a pointer to an array of ClearAttachment structures defining the attachments to clear and the clear values to use.

-> ("rects" ::: Vector ClearRect)

pRects is a pointer to an array of ClearRect structures defining regions within each selected attachment to clear.

-> io () 

vkCmdClearAttachments - Clear regions within bound framebuffer attachments

Description

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 is not a transfer command. It performs its operations in rasterization order. For color attachments, the operations are executed as color attachment writes, by the PIPELINE_STAGE_COLOR_ATTACHMENT_OUTPUT_BIT stage. For depth/stencil attachments, the operations are executed as depth writes and stencil writes by the PIPELINE_STAGE_EARLY_FRAGMENT_TESTS_BIT and PIPELINE_STAGE_LATE_FRAGMENT_TESTS_BIT stages.

cmdClearAttachments is not affected by the bound pipeline state.

Note

It is generally preferable to clear attachments by using the ATTACHMENT_LOAD_OP_CLEAR load operation at the start of rendering, as it is more efficient on some implementations.

If any attachment’s aspectMask to be cleared is not backed by an image view, the clear has no effect on that aspect.

If an attachment being cleared refers to an image view created with an aspectMask equal to one of IMAGE_ASPECT_PLANE_0_BIT, IMAGE_ASPECT_PLANE_1_BIT or IMAGE_ASPECT_PLANE_2_BIT, it is considered to be IMAGE_ASPECT_COLOR_BIT for purposes of this command, and must be cleared with the IMAGE_ASPECT_COLOR_BIT aspect as specified by image view creation.

Valid Usage

  • If the current render pass instance does not use dynamic rendering, and the aspectMask member of any element of pAttachments contains IMAGE_ASPECT_DEPTH_BIT, the current subpass instance’s depth-stencil attachment must be either ATTACHMENT_UNUSED or the attachment format must contain a depth component
  • If the current render pass instance does not use dynamic rendering, and the aspectMask member of any element of pAttachments contains IMAGE_ASPECT_STENCIL_BIT, the current subpass instance’s depth-stencil attachment must be either ATTACHMENT_UNUSED or the attachment format must contain a stencil component
  • If the aspectMask member of any element of pAttachments contains IMAGE_ASPECT_COLOR_BIT, the colorAttachment must be a valid color attachment index in the current render pass instance
  • The rect member of each element of pRects must have an extent.width greater than 0
  • The rect member of each element of pRects must have an extent.height greater than 0
  • The rectangular region specified by each element of pRects must be contained within the render area of the current render pass instance
  • The layers specified by each element of pRects must be contained within every attachment that pAttachments refers to, i.e. for each element of pRects, ClearRect::baseArrayLayer + ClearRect::layerCount must be less than or equal to the number of layers rendered to in the current render pass instance
  • The layerCount member of each element of pRects must not be 0
  • If commandBuffer is an unprotected command buffer and protectedNoFault is not supported, each attachment to be cleared must not be a protected image
  • If commandBuffer is a protected command buffer and protectedNoFault is not supported, each attachment to be cleared must not be an unprotected image
  • If the render pass instance this is recorded in uses multiview, then baseArrayLayer must be zero and layerCount must be one
  • If the subpass this is recorded in performs an external format resolve, the aspectMask member of any element of pAttachments must not include VK_IMAGE_ASPECT_PLANE_i_BIT for any index i

Valid Usage (Implicit)

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

Host Synchronization

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

Command Properties

'

Command Buffer LevelsRender Pass ScopeVideo Coding ScopeSupported Queue TypesCommand Type
Primary SecondaryInside Outside Graphics Action

See Also

VK_VERSION_1_0, ClearAttachment, ClearRect, CommandBuffer

cmdResolveImage Source #

Arguments

:: forall io. MonadIO io 
=> CommandBuffer

commandBuffer is the command buffer into which the command will be recorded.

-> ("srcImage" ::: Image)

srcImage is the source image.

-> ("srcImageLayout" ::: ImageLayout)

srcImageLayout is the layout of the source image subresources for the resolve.

-> ("dstImage" ::: Image)

dstImage is the destination image.

-> ("dstImageLayout" ::: ImageLayout)

dstImageLayout is the layout of the destination image subresources for the resolve.

-> ("regions" ::: Vector ImageResolve)

pRegions is a pointer to an array of ImageResolve structures specifying the regions to resolve.

-> 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 and protectedNoFault is not supported, srcImage must not be a protected image
  • If commandBuffer is an unprotected command buffer and protectedNoFault is not supported, dstImage must not be a protected image
  • If commandBuffer is a protected command buffer and protectedNoFault is not supported, dstImage must not be an unprotected image
  • The union of all source regions, and the union of all destination regions, specified by the elements of pRegions, must not overlap in memory
  • If srcImage is non-sparse then it must be bound completely and contiguously to a single DeviceMemory object
  • srcImage must have a sample count equal to any valid sample count value other than SAMPLE_COUNT_1_BIT
  • If dstImage is non-sparse then it must be bound completely and contiguously to a single DeviceMemory object
  • dstImage must have a sample count equal to SAMPLE_COUNT_1_BIT
  • srcImageLayout must specify the layout of the image subresources of srcImage specified in pRegions at the time this command is executed on a Device
  • srcImageLayout must be IMAGE_LAYOUT_SHARED_PRESENT_KHR, IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL or IMAGE_LAYOUT_GENERAL
  • dstImageLayout must specify the layout of the image subresources of dstImage specified in pRegions at the time this command is executed on a Device
  • dstImageLayout must be IMAGE_LAYOUT_SHARED_PRESENT_KHR, IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL or IMAGE_LAYOUT_GENERAL
  • The format features of dstImage must contain FORMAT_FEATURE_COLOR_ATTACHMENT_BIT
  • If the linearColorAttachment feature is enabled and the image is created with IMAGE_TILING_LINEAR, the format features of dstImage must contain FORMAT_FEATURE_2_LINEAR_COLOR_ATTACHMENT_BIT_NV
  • srcImage and dstImage must have been created with the same image format
  • The srcSubresource.mipLevel member of each element of pRegions must be less than the mipLevels specified in ImageCreateInfo when srcImage was created
  • The dstSubresource.mipLevel member of each element of pRegions must be less than the mipLevels specified in ImageCreateInfo when dstImage was created
  • If srcSubresource.layerCount is not REMAINING_ARRAY_LAYERS, srcSubresource.baseArrayLayer + srcSubresource.layerCount of each element of pRegions must be less than or equal to the arrayLayers specified in ImageCreateInfo when srcImage was created
  • If dstSubresource.layerCount is not REMAINING_ARRAY_LAYERS, dstSubresource.baseArrayLayer + dstSubresource.layerCount of each element of pRegions must be less than or equal to the arrayLayers specified in ImageCreateInfo when dstImage was created
  • dstImage and srcImage must not have been created with flags containing IMAGE_CREATE_SUBSAMPLED_BIT_EXT
  • If dstImage is of type IMAGE_TYPE_3D, then for each element of pRegions, srcSubresource.layerCount must be 1
  • If dstImage is of type IMAGE_TYPE_3D, then for each element of pRegions, dstSubresource.baseArrayLayer must be 0 and dstSubresource.layerCount must be 1
  • For each element of pRegions, srcOffset.x and (extent.width + srcOffset.x) must both be greater than or equal to 0 and less than or equal to the width of the specified srcSubresource of srcImage
  • For each element of pRegions, srcOffset.y and (extent.height + srcOffset.y) must both be greater than or equal to 0 and less than or equal to the height of the specified srcSubresource of srcImage
  • If srcImage is of type IMAGE_TYPE_1D, then for each element of pRegions, srcOffset.y must be 0 and extent.height must be 1
  • For each element of pRegions, srcOffset.z and (extent.depth + srcOffset.z) must both be greater than or equal to 0 and less than or equal to the depth of the specified srcSubresource of srcImage
  • If srcImage is of type IMAGE_TYPE_1D or IMAGE_TYPE_2D, then for each element of pRegions, srcOffset.z must be 0 and extent.depth must be 1
  • For each element of pRegions, dstOffset.x and (extent.width + dstOffset.x) must both be greater than or equal to 0 and less than or equal to the width of the specified dstSubresource of dstImage
  • For each element of pRegions, dstOffset.y and (extent.height + dstOffset.y) must both be greater than or equal to 0 and less than or equal to the height of the specified dstSubresource of dstImage
  • If dstImage is of type IMAGE_TYPE_1D, then for each element of pRegions, dstOffset.y must be 0 and extent.height must be 1
  • For each element of pRegions, dstOffset.z and (extent.depth + dstOffset.z) must both be greater than or equal to 0 and less than or equal to the depth of the specified dstSubresource of dstImage
  • If dstImage is of type IMAGE_TYPE_1D or IMAGE_TYPE_2D, then for each element of pRegions, dstOffset.z must be 0 and extent.depth must be 1
  • srcImage must have been created with IMAGE_USAGE_TRANSFER_SRC_BIT usage flag
  • The format features of srcImage must contain FORMAT_FEATURE_TRANSFER_SRC_BIT
  • dstImage must have been created with IMAGE_USAGE_TRANSFER_DST_BIT usage flag
  • The format features of dstImage must contain FORMAT_FEATURE_TRANSFER_DST_BIT

Valid Usage (Implicit)

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

Host Synchronization

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

Command Properties

'

Command Buffer LevelsRender Pass ScopeVideo Coding ScopeSupported Queue TypesCommand Type
Primary SecondaryOutside Outside Graphics Action

See Also

VK_VERSION_1_0, CommandBuffer, Image, ImageLayout, ImageResolve

cmdSetEvent Source #

Arguments

:: forall io. MonadIO io 
=> CommandBuffer

commandBuffer is the command buffer into which the command is recorded.

-> Event

event is the event that will be signaled.

-> ("stageMask" ::: PipelineStageFlags)

stageMask specifies the source stage mask used to determine the first synchronization scope.

-> io () 

vkCmdSetEvent - Set an event object to signaled state

Description

cmdSetEvent behaves identically to cmdSetEvent2, except that it does not define an access scope, and must only be used with cmdWaitEvents, not cmdWaitEvents2.

Valid Usage

Valid Usage (Implicit)

  • event must be a valid Event handle
  • stageMask must be a valid combination of PipelineStageFlagBits values
  • commandBuffer must be in the recording state
  • The CommandPool that commandBuffer was allocated from must support graphics, compute, decode, or encode operations
  • This command must only be called outside of a render pass instance
  • Both of commandBuffer, and event must have been created, allocated, or retrieved from the same Device

Host Synchronization

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

Command Properties

'

Command Buffer LevelsRender Pass ScopeVideo Coding ScopeSupported Queue TypesCommand Type
Primary Secondary Outside Both Graphics Compute Decode EncodeSynchronization

See Also

VK_VERSION_1_0, CommandBuffer, Event, PipelineStageFlags

cmdResetEvent Source #

Arguments

:: forall io. MonadIO io 
=> CommandBuffer

commandBuffer is the command buffer into which the command is recorded.

-> Event

event is the event that will be unsignaled.

-> ("stageMask" ::: PipelineStageFlags)

stageMask is a bitmask of PipelineStageFlagBits specifying the source stage mask used to determine when the event is unsignaled.

-> io () 

vkCmdResetEvent - Reset an event object to non-signaled state

Description

cmdResetEvent behaves identically to cmdResetEvent2.

Valid Usage

Valid Usage (Implicit)

  • event must be a valid Event handle
  • stageMask must be a valid combination of PipelineStageFlagBits values
  • commandBuffer must be in the recording state
  • The CommandPool that commandBuffer was allocated from must support graphics, compute, decode, or encode operations
  • This command must only be called outside of a render pass instance
  • Both of commandBuffer, and event must have been created, allocated, or retrieved from the same Device

Host Synchronization

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

Command Properties

'

Command Buffer LevelsRender Pass ScopeVideo Coding ScopeSupported Queue TypesCommand Type
Primary Secondary Outside Both Graphics Compute Decode EncodeSynchronization

See Also

VK_VERSION_1_0, CommandBuffer, Event, PipelineStageFlags

cmdWaitEvents Source #

Arguments

:: forall io. MonadIO io 
=> CommandBuffer

commandBuffer is the command buffer into which the command is recorded.

-> ("events" ::: Vector Event)

pEvents is a pointer to an array of event object handles to wait on.

-> ("srcStageMask" ::: PipelineStageFlags)

srcStageMask is a bitmask of PipelineStageFlagBits specifying the source stage mask.

-> ("dstStageMask" ::: PipelineStageFlags)

dstStageMask is a bitmask of PipelineStageFlagBits specifying the destination stage mask.

-> ("memoryBarriers" ::: Vector MemoryBarrier)

pMemoryBarriers is a pointer to an array of MemoryBarrier structures.

-> ("bufferMemoryBarriers" ::: Vector (SomeStruct BufferMemoryBarrier))

pBufferMemoryBarriers is a pointer to an array of BufferMemoryBarrier structures.

-> ("imageMemoryBarriers" ::: Vector (SomeStruct ImageMemoryBarrier))

pImageMemoryBarriers is a pointer to an array of ImageMemoryBarrier structures.

-> io () 

vkCmdWaitEvents - Wait for one or more events and insert a set of memory

Description

cmdWaitEvents is largely similar to cmdWaitEvents2, but can only wait on signal operations defined by cmdSetEvent. As cmdSetEvent does not define any access scopes, cmdWaitEvents defines the first access scope for each event signal operation in addition to its own access scopes.

Note

Since cmdSetEvent does not have any dependency information beyond a stage mask, implementations do not have the same opportunity to perform availability and visibility operations or image layout transitions in advance as they do with cmdSetEvent2 and cmdWaitEvents2.

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 accesses 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 accesses 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.

Valid Usage

Valid Usage (Implicit)

  • pEvents must be a valid pointer to an array of eventCount valid Event handles
  • srcStageMask must be a valid combination of PipelineStageFlagBits values
  • dstStageMask must be a valid combination of PipelineStageFlagBits values
  • If memoryBarrierCount is not 0, pMemoryBarriers must be a valid pointer to an array of memoryBarrierCount valid MemoryBarrier structures
  • If bufferMemoryBarrierCount is not 0, pBufferMemoryBarriers must be a valid pointer to an array of bufferMemoryBarrierCount valid BufferMemoryBarrier structures
  • If imageMemoryBarrierCount is not 0, pImageMemoryBarriers must be a valid pointer to an array of imageMemoryBarrierCount valid ImageMemoryBarrier structures
  • commandBuffer must be in the recording state
  • The CommandPool that commandBuffer was allocated from must support graphics, compute, decode, or encode operations
  • eventCount must be greater than 0
  • Both of commandBuffer, and the elements of pEvents must have been created, allocated, or retrieved from the same Device

Host Synchronization

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

Command Properties

'

Command Buffer LevelsRender Pass ScopeVideo Coding ScopeSupported Queue TypesCommand Type
Primary Secondary Both Both Graphics Compute Decode EncodeSynchronization

See Also

VK_VERSION_1_0, BufferMemoryBarrier, CommandBuffer, Event, ImageMemoryBarrier, MemoryBarrier, PipelineStageFlags

cmdWaitEventsSafe Source #

Arguments

:: forall io. MonadIO io 
=> CommandBuffer

commandBuffer is the command buffer into which the command is recorded.

-> ("events" ::: Vector Event)

pEvents is a pointer to an array of event object handles to wait on.

-> ("srcStageMask" ::: PipelineStageFlags)

srcStageMask is a bitmask of PipelineStageFlagBits specifying the source stage mask.

-> ("dstStageMask" ::: PipelineStageFlags)

dstStageMask is a bitmask of PipelineStageFlagBits specifying the destination stage mask.

-> ("memoryBarriers" ::: Vector MemoryBarrier)

pMemoryBarriers is a pointer to an array of MemoryBarrier structures.

-> ("bufferMemoryBarriers" ::: Vector (SomeStruct BufferMemoryBarrier))

pBufferMemoryBarriers is a pointer to an array of BufferMemoryBarrier structures.

-> ("imageMemoryBarriers" ::: Vector (SomeStruct ImageMemoryBarrier))

pImageMemoryBarriers is a pointer to an array of ImageMemoryBarrier structures.

-> io () 

A variant of cmdWaitEvents which makes a *safe* FFI call

cmdPipelineBarrier Source #

Arguments

:: forall io. MonadIO io 
=> CommandBuffer

commandBuffer is the command buffer into which the command is recorded.

-> ("srcStageMask" ::: PipelineStageFlags)

srcStageMask is a bitmask of PipelineStageFlagBits specifying the source stages.

-> ("dstStageMask" ::: PipelineStageFlags)

dstStageMask is a bitmask of PipelineStageFlagBits specifying the destination stages.

-> DependencyFlags

dependencyFlags is a bitmask of DependencyFlagBits specifying how execution and memory dependencies are formed.

-> ("memoryBarriers" ::: Vector MemoryBarrier)

pMemoryBarriers is a pointer to an array of MemoryBarrier structures.

-> ("bufferMemoryBarriers" ::: Vector (SomeStruct BufferMemoryBarrier))

pBufferMemoryBarriers is a pointer to an array of BufferMemoryBarrier structures.

-> ("imageMemoryBarriers" ::: Vector (SomeStruct ImageMemoryBarrier))

pImageMemoryBarriers is a pointer to an array of ImageMemoryBarrier structures.

-> io () 

vkCmdPipelineBarrier - Insert a memory dependency

Description

cmdPipelineBarrier operates almost identically to cmdPipelineBarrier2, except that the scopes and barriers are defined as direct parameters rather than being defined by an DependencyInfo.

When cmdPipelineBarrier is submitted to a queue, it defines a memory dependency between commands that were submitted to the same queue before it, and those submitted to the same queue 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 accesses 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 accesses 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

Valid Usage (Implicit)

  • srcStageMask must be a valid combination of PipelineStageFlagBits values
  • dstStageMask must be a valid combination of PipelineStageFlagBits values
  • dependencyFlags must be a valid combination of DependencyFlagBits values
  • If memoryBarrierCount is not 0, pMemoryBarriers must be a valid pointer to an array of memoryBarrierCount valid MemoryBarrier structures
  • If bufferMemoryBarrierCount is not 0, pBufferMemoryBarriers must be a valid pointer to an array of bufferMemoryBarrierCount valid BufferMemoryBarrier structures
  • If imageMemoryBarrierCount is not 0, pImageMemoryBarriers must be a valid pointer to an array of imageMemoryBarrierCount valid ImageMemoryBarrier structures
  • commandBuffer must be in the recording state
  • The CommandPool that commandBuffer was allocated from must support transfer, graphics, compute, decode, or encode operations

Host Synchronization

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

Command Properties

'

Command Buffer LevelsRender Pass ScopeVideo Coding ScopeSupported Queue TypesCommand Type
Primary Secondary Both Both Transfer Graphics Compute Decode EncodeSynchronization

See Also

VK_VERSION_1_0, BufferMemoryBarrier, CommandBuffer, DependencyFlags, ImageMemoryBarrier, MemoryBarrier, PipelineStageFlags

cmdBeginQuery Source #

Arguments

:: forall io. MonadIO io 
=> CommandBuffer

commandBuffer is the command buffer into which this command will be recorded.

-> QueryPool

queryPool is the query pool that will manage the results of the query.

-> ("query" ::: Word32)

query is the query index within the query pool that will contain the results.

-> QueryControlFlags

flags is a bitmask of QueryControlFlagBits specifying constraints on the types of queries that can be performed.

-> 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.

Furthermore, if the query is started within a video coding scope, the following command buffer states are initialized for the query type:

  • The active_query_index is set to the value specified by query.
  • The /last activatable query index/ is also set to the value specified by query.

Each video coding operation stores a result to the query corresponding to the current active query index, followed by incrementing the active query index. If the active query index gets incremented past the last activatable query index, issuing any further video coding operations results in undefined behavior.

Note

In practice, this means that currently no more than a single video coding operation must be issued between a begin and end query pair.

This command defines an execution dependency between other query commands that reference the same query.

The first synchronization scope includes all commands which reference the queries in queryPool indicated by query that occur earlier in submission order.

The second synchronization scope includes all commands which reference the queries in queryPool indicated by query that occur later in submission order.

The operation of this command happens after the first scope and happens before the second scope.

Valid Usage

  • All queries used by the command must be unavailable

Valid Usage (Implicit)

  • queryPool must be a valid QueryPool handle
  • flags must be a valid combination of QueryControlFlagBits values
  • commandBuffer must be in the recording state
  • The CommandPool that commandBuffer was allocated from must support graphics, compute, decode, or encode operations
  • Both of commandBuffer, and queryPool must have been created, allocated, or retrieved from the same Device

Host Synchronization

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

Command Properties

'

Command Buffer LevelsRender Pass ScopeVideo Coding ScopeSupported Queue TypesCommand Type
Primary Secondary Both Both Graphics Compute Decode EncodeAction State

See Also

VK_VERSION_1_0, CommandBuffer, QueryControlFlags, QueryPool, cmdBeginQueryIndexedEXT, cmdEndQuery, cmdEndQueryIndexedEXT

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.

cmdEndQuery Source #

Arguments

:: forall io. MonadIO io 
=> CommandBuffer

commandBuffer is the command buffer into which this command will be recorded.

-> QueryPool

queryPool is the query pool that is managing the results of the query.

-> ("query" ::: Word32)

query is the query index within the query pool where the result is stored.

-> io () 

vkCmdEndQuery - Ends a query

Description

The command completes the query in queryPool identified by query, and marks it as available.

This command defines an execution dependency between other query commands that reference the same query.

The first synchronization scope includes all commands which reference the queries in queryPool indicated by query that occur earlier in submission order.

The second synchronization scope includes only the operation of this command.

Calling cmdEndQuery is equivalent to calling cmdEndQueryIndexedEXT with the index parameter set to zero.

Valid Usage

  • All queries used by the command must be active
  • query must be less than the number of queries in queryPool
  • commandBuffer must not be a protected command buffer
  • If cmdEndQuery is 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 in queryPool
  • If queryPool was created with a queryType of QUERY_TYPE_PERFORMANCE_QUERY_KHR and one or more of the counters used to create queryPool was PERFORMANCE_COUNTER_SCOPE_COMMAND_BUFFER_KHR, the cmdEndQuery must be the last recorded command in commandBuffer
  • If queryPool was created with a queryType of QUERY_TYPE_PERFORMANCE_QUERY_KHR and one or more of the counters used to create queryPool was PERFORMANCE_COUNTER_SCOPE_RENDER_PASS_KHR, the cmdEndQuery must not be recorded within a render pass instance
  • If called within a subpass of a render pass instance, the corresponding cmdBeginQuery* command must have been called previously within the same subpass
  • If called outside of a render pass instance, the corresponding cmdBeginQuery* command must have been called outside of a render pass instance

Valid Usage (Implicit)

  • queryPool must be a valid QueryPool handle
  • commandBuffer must be in the recording state
  • The CommandPool that commandBuffer was allocated from must support graphics, compute, decode, or encode operations
  • Both of commandBuffer, and queryPool must have been created, allocated, or retrieved from the same Device

Host Synchronization

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

Command Properties

'

Command Buffer LevelsRender Pass ScopeVideo Coding ScopeSupported Queue TypesCommand Type
Primary Secondary Both Both Graphics Compute Decode EncodeAction State

See Also

VK_VERSION_1_0, CommandBuffer, QueryPool, cmdBeginQuery, cmdBeginQueryIndexedEXT, cmdEndQueryIndexedEXT

cmdResetQueryPool Source #

Arguments

:: forall io. MonadIO io 
=> CommandBuffer

commandBuffer is the command buffer into which this command will be recorded.

-> QueryPool

queryPool is the handle of the query pool managing the queries being reset.

-> ("firstQuery" ::: Word32)

firstQuery is the initial query index to reset.

-> ("queryCount" ::: Word32)

queryCount is the number of queries to reset.

-> 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.

This command defines an execution dependency between other query commands that reference the same query.

The first synchronization scope includes all commands which reference the queries in queryPool indicated by firstQuery and queryCount that occur earlier in submission order.

The second synchronization scope includes all commands which reference the queries in queryPool indicated by firstQuery and queryCount that occur later in submission order.

The operation of this command happens after the first scope and happens before the second scope.

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 in queryPool
  • The sum of firstQuery and queryCount must be less than or equal to the number of queries in queryPool
  • All queries used by the command must not be active
  • If queryPool was created with QUERY_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)

  • queryPool must be a valid QueryPool handle
  • commandBuffer must be in the recording state
  • The CommandPool that commandBuffer was allocated from must support graphics, compute, decode, encode, or optical flow operations
  • This command must only be called outside of a render pass instance
  • This command must only be called outside of a video coding scope
  • Both of commandBuffer, and queryPool must have been created, allocated, or retrieved from the same Device

Host Synchronization

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

Command Properties

'

Command Buffer LevelsRender Pass ScopeVideo Coding ScopeSupported Queue TypesCommand Type
Primary Secondary Outside Outside Graphics Compute Decode Encode OpticalflowAction

See Also

VK_VERSION_1_0, CommandBuffer, QueryPool

cmdWriteTimestamp Source #

Arguments

:: forall io. MonadIO io 
=> CommandBuffer

commandBuffer is the command buffer into which the command will be recorded.

-> PipelineStageFlagBits

pipelineStage is a PipelineStageFlagBits value, specifying a stage of the pipeline.

-> QueryPool

queryPool is the query pool that will manage the timestamp.

-> ("query" ::: Word32)

query is the query within the query pool that will contain the timestamp.

-> io () 

vkCmdWriteTimestamp - Write a device timestamp into a query object

Description

When cmdWriteTimestamp is submitted to a queue, it defines an execution dependency on commands that were submitted before it, and writes a timestamp to a query pool.

The first synchronization scope includes all commands that occur earlier in submission order. The synchronization scope is limited to operations on the pipeline stage specified by pipelineStage.

The second synchronization scope includes only the timestamp write operation.

Note

Implementations may write the timestamp at any stage that is logically later than stage.

Any timestamp write that happens-after another timestamp write in the same submission must not have a lower value unless its value overflows the maximum supported integer bit width of the query. If VK_EXT_calibrated_timestamps is enabled, this extends to timestamp writes across all submissions on the same logical device: any timestamp write that happens-after another must not have a lower value unless its value overflows the maximum supported integer bit width of the query. Timestamps written by this command must be in the TIME_DOMAIN_DEVICE_EXT time domain. If an overflow occurs, the timestamp value must wrap back to zero.

Note

Comparisons between timestamps should be done between timestamps where they are guaranteed to not decrease. For example, subtracting an older timestamp from a newer one to determine the execution time of a sequence of commands is only a reliable measurement if the two timestamp writes were performed in the same submission, or if the writes were performed on the same logical device and VK_EXT_calibrated_timestamps is enabled.

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 that commandBuffer was allocated from

Valid Usage (Implicit)

  • pipelineStage must be a valid PipelineStageFlagBits value
  • queryPool must be a valid QueryPool handle
  • commandBuffer must be in the recording state
  • The CommandPool that commandBuffer was allocated from must support transfer, graphics, compute, decode, encode, or optical flow operations
  • Both of commandBuffer, and queryPool must have been created, allocated, or retrieved from the same Device

Host Synchronization

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

Command Properties

'

Command Buffer LevelsRender Pass ScopeVideo Coding ScopeSupported Queue TypesCommand Type
Primary Secondary Both Both Transfer Graphics Compute Decode Encode OpticalflowAction

See Also

VK_VERSION_1_0, CommandBuffer, PipelineStageFlagBits, QueryPool

cmdCopyQueryPoolResults Source #

Arguments

:: forall io. MonadIO io 
=> CommandBuffer

commandBuffer is the command buffer into which this command will be recorded.

-> QueryPool

queryPool is the query pool managing the queries containing the desired results.

-> ("firstQuery" ::: Word32)

firstQuery is the initial query index.

-> ("queryCount" ::: Word32)

queryCount is the number of queries. firstQuery and queryCount together define a range of queries.

-> ("dstBuffer" ::: Buffer)

dstBuffer is a Buffer object that will receive the results of the copy command.

-> ("dstOffset" ::: DeviceSize)

dstOffset is an offset into dstBuffer.

-> ("stride" ::: DeviceSize)

stride is the stride in bytes between results for individual queries within dstBuffer. The required size of the backing memory for dstBuffer is determined as described above for getQueryPoolResults.

-> QueryResultFlags

flags is a bitmask of QueryResultFlagBits specifying how and when results are returned.

-> io () 

vkCmdCopyQueryPoolResults - Copy the results of queries in a query pool to a buffer object

Description

Any results written for a query are written according to a layout dependent on the query type.

Results for any query in queryPool identified by firstQuery and queryCount that is available are copied to dstBuffer.

If QUERY_RESULT_WITH_AVAILABILITY_BIT is set, results for all queries in queryPool identified by firstQuery and queryCount are copied to dstBuffer, along with an extra availability value written directly after the results of each query and interpreted as an unsigned integer. A value of zero indicates that the results are not yet available, otherwise the query is complete and results are available.

If VK_QUERY_RESULT_WITH_STATUS_BIT_KHR is set, results for all queries in queryPool identified by firstQuery and queryCount are copied to dstBuffer, along with an extra status value written directly after the results of each query and interpreted as a signed integer. A value of zero indicates that the results are not yet available. Positive values indicate that the operations within the query completed successfully, and the query results are valid. Negative values indicate that the operations within the query completed unsuccessfully.

VkQueryResultStatusKHR defines specific meaning for values returned here, though implementations are free to return other values.

Results for any available query written by this command are final and represent the final result of the query. If QUERY_RESULT_PARTIAL_BIT is set, then for any query that is unavailable, an intermediate result between zero and the final result value is written for that query. Otherwise, any result written by this command is undefined.

If QUERY_RESULT_64_BIT is set, results and availability or status values for all queries are written as an array of 64-bit values. If the queryPool was created with QUERY_TYPE_PERFORMANCE_QUERY_KHR, results for each query are written as an array of the type indicated by PerformanceCounterKHR::storage for the counter being queried. Otherwise, results and availability or status values are written as an array of 32-bit values. If an unsigned integer query’s value overflows the result type, the value may either wrap or saturate. If a signed integer query’s value overflows the result type, the value is undefined. If a floating point query’s value is not representable as the result type, the value is undefined.

This command defines an execution dependency between other query commands that reference the same query.

The first synchronization scope includes all commands which reference the queries in queryPool indicated by query that occur earlier in submission order. If flags does not include QUERY_RESULT_WAIT_BIT, cmdEndQueryIndexedEXT, cmdWriteTimestamp2, cmdEndQuery, and cmdWriteTimestamp are excluded from this scope.

The second synchronization scope includes all commands which reference the queries in queryPool indicated by query that occur later in submission order.

The operation of this command happens after the first scope and happens before the second scope.

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

  • All queries used by the command must not be uninitialized when the command is executed

Valid Usage (Implicit)

  • queryPool must be a valid QueryPool handle
  • dstBuffer must be a valid Buffer handle
  • flags must be a valid combination of QueryResultFlagBits values
  • commandBuffer must be in the recording state
  • The CommandPool that commandBuffer was allocated from must support graphics, or compute operations
  • This command must only be called outside of a render pass instance
  • This command must only be called outside of a video coding scope
  • Each of commandBuffer, dstBuffer, and queryPool must have been created, allocated, or retrieved from the same Device

Host Synchronization

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

Command Properties

'

Command Buffer LevelsRender Pass ScopeVideo Coding ScopeSupported Queue TypesCommand Type
Primary SecondaryOutside Outside Graphics ComputeAction

See Also

VK_VERSION_1_0, Buffer, CommandBuffer, DeviceSize, QueryPool, QueryResultFlags

cmdPushConstants Source #

Arguments

:: forall io. MonadIO io 
=> CommandBuffer

commandBuffer is the command buffer in which the push constant update will be recorded.

-> PipelineLayout

layout is the pipeline layout used to program the push constant updates.

-> ShaderStageFlags

stageFlags is a bitmask of ShaderStageFlagBits specifying the shader stages that will use the push constants in the updated range.

-> ("offset" ::: Word32)

offset is the start offset of the push constant range to update, in units of bytes.

-> ("size" ::: Word32)

size is the size of the push constant range to update, in units of bytes.

-> ("values" ::: Ptr ())

pValues is a pointer to an array of size bytes containing the new push constant values.

-> io () 

vkCmdPushConstants - Update the values of push constants

Description

When a command buffer begins recording, all push constant values are undefined. Reads of undefined push constant values by the executing shader return undefined values.

Push constant values can be updated incrementally, causing shader stages in stageFlags to read the new data from pValues for push constants modified by this command, while still reading the previous data for push constants not modified by this command. When a bound pipeline command is issued, the bound pipeline’s layout must be compatible with the layouts used to set the values of all push constants in the pipeline layout’s push constant ranges, as described in Pipeline Layout Compatibility. Binding a pipeline with a layout that is not compatible with the push constant layout does not disturb the push constant values.

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 and size and for each shader stage in stageFlags, there must be a push constant range in layout that includes that byte and that stage
  • For each byte in the range specified by offset and size and for each push constant range that overlaps that byte, stageFlags must include all stages in that push constant range’s PushConstantRange::stageFlags
  • offset must be a multiple of 4
  • size must be a multiple of 4
  • offset must be less than PhysicalDeviceLimits::maxPushConstantsSize
  • size must be less than or equal to PhysicalDeviceLimits::maxPushConstantsSize minus offset

Valid Usage (Implicit)

  • layout must be a valid PipelineLayout handle
  • stageFlags must be a valid combination of ShaderStageFlagBits values
  • stageFlags must not be 0
  • pValues must be a valid pointer to an array of size bytes
  • commandBuffer must be in the recording state
  • The CommandPool that commandBuffer was allocated from must support graphics, or compute operations
  • This command must only be called outside of a video coding scope
  • size must be greater than 0
  • Both of commandBuffer, and layout must have been created, allocated, or retrieved from the same Device

Host Synchronization

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

Command Properties

'

Command Buffer LevelsRender Pass ScopeVideo Coding ScopeSupported Queue TypesCommand Type
Primary SecondaryBoth Outside Graphics ComputeState

See Also

VK_VERSION_1_0, CommandBuffer, PipelineLayout, ShaderStageFlags

cmdBeginRenderPass Source #

Arguments

:: forall a io. (Extendss RenderPassBeginInfo a, PokeChain a, MonadIO io) 
=> CommandBuffer

commandBuffer is the command buffer in which to record the command.

-> RenderPassBeginInfo a

pRenderPassBegin is a pointer to a RenderPassBeginInfo structure specifying the render pass to begin an instance of, and the framebuffer the instance uses.

-> SubpassContents

contents is a SubpassContents value specifying how the commands in the first subpass will be provided.

-> 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

Valid Usage (Implicit)

  • pRenderPassBegin must be a valid pointer to a valid RenderPassBeginInfo structure
  • contents must be a valid SubpassContents value
  • commandBuffer must be in the recording state
  • The CommandPool that commandBuffer was allocated from must support graphics operations
  • This command must only be called outside of a render pass instance
  • This command must only be called outside of a video coding scope
  • commandBuffer must be a primary CommandBuffer

Host Synchronization

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

Command Properties

'

Command Buffer LevelsRender Pass ScopeVideo Coding ScopeSupported Queue TypesCommand Type
Primary Outside Outside Graphics Action State Synchronization

See Also

VK_VERSION_1_0, CommandBuffer, RenderPassBeginInfo, SubpassContents

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.

cmdNextSubpass Source #

Arguments

:: forall io. MonadIO io 
=> CommandBuffer

commandBuffer is the command buffer in which to record the command.

-> SubpassContents

contents specifies how the commands in the next subpass will be provided, in the same fashion as the corresponding parameter of cmdBeginRenderPass.

-> 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.

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)

  • contents must be a valid SubpassContents value
  • commandBuffer must be in the recording state
  • The CommandPool that commandBuffer was allocated from must support graphics operations
  • This command must only be called inside of a render pass instance
  • This command must only be called outside of a video coding scope
  • commandBuffer must be a primary CommandBuffer

Host Synchronization

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

Command Properties

'

Command Buffer LevelsRender Pass ScopeVideo Coding ScopeSupported Queue TypesCommand Type
Primary Inside Outside Graphics Action State Synchronization

See Also

VK_VERSION_1_0, CommandBuffer, SubpassContents

cmdEndRenderPass Source #

Arguments

:: forall io. MonadIO io 
=> CommandBuffer

commandBuffer is the command buffer in which to end the current render pass instance.

-> 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
  • The current render pass instance must not have been begun with cmdBeginRendering
  • If cmdBeginQuery* was called within a subpass of the render pass, the corresponding cmdEndQuery* must have been called subsequently within the same subpass

Valid Usage (Implicit)

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

Host Synchronization

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

Command Properties

'

Command Buffer LevelsRender Pass ScopeVideo Coding ScopeSupported Queue TypesCommand Type
Primary Inside Outside Graphics Action State Synchronization

See Also

VK_VERSION_1_0, CommandBuffer

cmdExecuteCommands Source #

Arguments

:: forall io. MonadIO io 
=> CommandBuffer

commandBuffer is a handle to a primary command buffer that the secondary command buffers are executed in.

-> ("commandBuffers" ::: Vector CommandBuffer)

pCommandBuffers is a pointer to an array of commandBufferCount secondary command buffer handles, which are recorded to execute in the primary command buffer in the order they are listed in the array.

-> 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.

If the nestedCommandBuffer feature is enabled it is valid usage for cmdExecuteCommands to also be recorded to a secondary command buffer.

Valid Usage

Valid Usage (Implicit)

  • pCommandBuffers must be a valid pointer to an array of commandBufferCount valid CommandBuffer handles
  • commandBuffer must be in the recording state
  • The CommandPool that commandBuffer was allocated from must support transfer, graphics, or compute operations
  • This command must only be called outside of a video coding scope
  • commandBufferCount must be greater than 0
  • Both of commandBuffer, and the elements of pCommandBuffers must have been created, allocated, or retrieved from the same Device

Host Synchronization

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

Command Properties

'

Command Buffer LevelsRender Pass ScopeVideo Coding ScopeSupported Queue TypesCommand Type
Primary Secondary Both Outside Transfer Graphics ComputeIndirection

See Also

VK_VERSION_1_0, CommandBuffer

data ClearRect Source #

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

VK_VERSION_1_0, Rect2D, cmdClearAttachments

Constructors

ClearRect 

Fields

data ImageSubresourceLayers Source #

VkImageSubresourceLayers - Structure specifying an image subresource layers

Valid Usage

Valid Usage (Implicit)

  • aspectMask must not be 0

See Also

VK_VERSION_1_0, BufferImageCopy, BufferImageCopy2, CopyMemoryToImageIndirectCommandNV, ImageAspectFlags, ImageBlit, ImageBlit2, ImageCopy, ImageCopy2, ImageResolve, ImageResolve2, ImageToMemoryCopyEXT, MemoryToImageCopyEXT, cmdCopyMemoryToImageIndirectNV

Constructors

ImageSubresourceLayers 

Fields

Instances

Instances details
Storable ImageSubresourceLayers Source # 
Instance details

Defined in Vulkan.Core10.CommandBufferBuilding

Show ImageSubresourceLayers Source # 
Instance details

Defined in Vulkan.Core10.CommandBufferBuilding

Eq ImageSubresourceLayers Source # 
Instance details

Defined in Vulkan.Core10.CommandBufferBuilding

FromCStruct ImageSubresourceLayers Source # 
Instance details

Defined in Vulkan.Core10.CommandBufferBuilding

ToCStruct ImageSubresourceLayers Source # 
Instance details

Defined in Vulkan.Core10.CommandBufferBuilding

Zero ImageSubresourceLayers Source # 
Instance details

Defined in Vulkan.Core10.CommandBufferBuilding

data BufferCopy Source #

VkBufferCopy - Structure specifying a buffer copy operation

Valid Usage

  • The size must be greater than 0

See Also

VK_VERSION_1_0, DeviceSize, cmdCopyBuffer

Constructors

BufferCopy 

Fields

Instances

Instances details
Storable BufferCopy Source # 
Instance details

Defined in Vulkan.Core10.CommandBufferBuilding

Show BufferCopy Source # 
Instance details

Defined in Vulkan.Core10.CommandBufferBuilding

Eq BufferCopy Source # 
Instance details

Defined in Vulkan.Core10.CommandBufferBuilding

FromCStruct BufferCopy Source # 
Instance details

Defined in Vulkan.Core10.CommandBufferBuilding

ToCStruct BufferCopy Source # 
Instance details

Defined in Vulkan.Core10.CommandBufferBuilding

Zero BufferCopy Source # 
Instance details

Defined in Vulkan.Core10.CommandBufferBuilding

data ImageCopy Source #

VkImageCopy - Structure specifying an image copy operation

Valid Usage

  • If the VK_KHR_maintenance1 extension is not enabled, and PhysicalDeviceProperties::apiVersion is less than Vulkan 1.1, the layerCount member of srcSubresource and dstSubresource must match
  • extent.width must not be 0
  • extent.height must not be 0
  • extent.depth must not be 0

Valid Usage (Implicit)

See Also

VK_VERSION_1_0, Extent3D, ImageSubresourceLayers, Offset3D, cmdCopyImage

Constructors

ImageCopy 

Fields

data ImageBlit Source #

VkImageBlit - Structure specifying an image blit operation

Description

For each element of the pRegions array, a blit operation is performed for the specified source and destination regions.

Valid Usage

  • The aspectMask member of srcSubresource and dstSubresource must match

Valid Usage (Implicit)

See Also

VK_VERSION_1_0, ImageSubresourceLayers, Offset3D, cmdBlitImage

Constructors

ImageBlit 

Fields

data BufferImageCopy Source #

VkBufferImageCopy - Structure specifying a buffer image copy operation

Valid Usage

  • bufferRowLength must be 0, or greater than or equal to the width member of imageExtent
  • bufferImageHeight must be 0, or greater than or equal to the height member of imageExtent
  • The aspectMask member of imageSubresource must only have a single bit set
  • imageExtent.width must not be 0
  • imageExtent.height must not be 0
  • imageExtent.depth must not be 0

Valid Usage (Implicit)

See Also

VK_VERSION_1_0, DeviceSize, Extent3D, ImageSubresourceLayers, Offset3D, cmdCopyBufferToImage, cmdCopyImageToBuffer

Constructors

BufferImageCopy 

Fields

  • bufferOffset :: DeviceSize

    bufferOffset is the offset in bytes from the start of the buffer object where the image data is copied from or to.

  • bufferRowLength :: Word32

    bufferRowLength and bufferImageHeight specify in texels a subregion of a larger two- or three-dimensional image in buffer memory, and control the addressing calculations. If either of these values is zero, that aspect of the buffer memory is considered to be tightly packed according to the imageExtent.

  • bufferImageHeight :: Word32
     
  • imageSubresource :: ImageSubresourceLayers

    imageSubresource is a ImageSubresourceLayers used to specify the specific image subresources of the image used for the source or destination image data.

  • imageOffset :: Offset3D

    imageOffset selects the initial x, y, z offsets in texels of the sub-region of the source or destination image data.

  • imageExtent :: Extent3D

    imageExtent is the size in texels of the image to copy in width, height and depth.

Instances

Instances details
Storable BufferImageCopy Source # 
Instance details

Defined in Vulkan.Core10.CommandBufferBuilding

Show BufferImageCopy Source # 
Instance details

Defined in Vulkan.Core10.CommandBufferBuilding

FromCStruct BufferImageCopy Source # 
Instance details

Defined in Vulkan.Core10.CommandBufferBuilding

ToCStruct BufferImageCopy Source # 
Instance details

Defined in Vulkan.Core10.CommandBufferBuilding

Zero BufferImageCopy Source # 
Instance details

Defined in Vulkan.Core10.CommandBufferBuilding

data ImageResolve Source #

VkImageResolve - Structure specifying an image resolve operation

Valid Usage

Valid Usage (Implicit)

See Also

VK_VERSION_1_0, Extent3D, ImageSubresourceLayers, Offset3D, cmdResolveImage

Constructors

ImageResolve 

Fields

data RenderPassBeginInfo (es :: [Type]) Source #

VkRenderPassBeginInfo - Structure specifying render pass begin information

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.

If multiview is enabled in renderPass, and multiviewPerViewRenderAreas feature is enabled, and there is an instance of MultiviewPerViewRenderAreasRenderPassBeginInfoQCOM included in the pNext chain with perViewRenderAreaCount not equal to 0, then the elements of MultiviewPerViewRenderAreasRenderPassBeginInfoQCOM::pPerViewRenderAreas override renderArea and define a render area for each view. In this case, renderArea must be set to an area at least as large as the union of all the per-view render areas.

If the subpassShading feature is enabled, then renderArea must equal the framebuffer dimensions.

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 in renderPass specifying a loadOp (or stencilLoadOp, if the attachment has a depth/stencil format) of ATTACHMENT_LOAD_OP_CLEAR

Valid Usage (Implicit)

See Also

VK_VERSION_1_0, ClearValue, Framebuffer, Rect2D, RenderPass, StructureType, cmdBeginRenderPass, cmdBeginRenderPass2, cmdBeginRenderPass2KHR

Constructors

RenderPassBeginInfo 

Fields

  • next :: Chain es

    pNext is NULL or a pointer to a structure extending this structure.

  • renderPass :: RenderPass

    renderPass is the render pass to begin an instance of.

  • framebuffer :: Framebuffer

    framebuffer is the framebuffer containing the attachments that are used with the render pass.

  • renderArea :: Rect2D

    renderArea is the render area that is affected by the render pass instance, and is described in more detail below.

  • clearValues :: Vector ClearValue

    pClearValues is a pointer to an array of clearValueCount ClearValue structures containing clear values for each attachment, if the attachment uses a loadOp value of ATTACHMENT_LOAD_OP_CLEAR or if the attachment has a depth/stencil format and uses a stencilLoadOp value of ATTACHMENT_LOAD_OP_CLEAR. The array is indexed by attachment number. Only elements corresponding to cleared attachments are used. Other elements of pClearValues are ignored.

data ClearDepthStencilValue Source #

VkClearDepthStencilValue - Structure specifying a clear depth stencil value

Valid Usage

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

See Also

VK_VERSION_1_0, ClearValue, cmdClearDepthStencilImage

Constructors

ClearDepthStencilValue 

Fields

  • depth :: Float

    depth is the clear value for the depth aspect of the depth/stencil attachment. It is a floating-point value which is automatically converted to the attachment’s format.

  • stencil :: Word32

    stencil is the clear value for the stencil aspect of the depth/stencil attachment. It is a 32-bit integer value which is converted to the attachment’s format by taking the appropriate number of LSBs.

Instances

Instances details
Storable ClearDepthStencilValue Source # 
Instance details

Defined in Vulkan.Core10.CommandBufferBuilding

Show ClearDepthStencilValue Source # 
Instance details

Defined in Vulkan.Core10.CommandBufferBuilding

Eq ClearDepthStencilValue Source # 
Instance details

Defined in Vulkan.Core10.CommandBufferBuilding

FromCStruct ClearDepthStencilValue Source # 
Instance details

Defined in Vulkan.Core10.CommandBufferBuilding

ToCStruct ClearDepthStencilValue Source # 
Instance details

Defined in Vulkan.Core10.CommandBufferBuilding

Zero ClearDepthStencilValue Source # 
Instance details

Defined in Vulkan.Core10.CommandBufferBuilding

data ClearAttachment Source #

VkClearAttachment - Structure specifying a clear attachment

Valid Usage

  • aspectMask must not include IMAGE_ASPECT_METADATA_BIT
  • aspectMask must not include VK_IMAGE_ASPECT_MEMORY_PLANE_i_BIT_EXT for any index i

Valid Usage (Implicit)

  • aspectMask must not be 0

See Also

VK_VERSION_1_0, ClearValue, ImageAspectFlags, cmdClearAttachments

Constructors

ClearAttachment 

Fields

newtype IndexType Source #

Constructors

IndexType Int32 

Bundled Patterns

pattern INDEX_TYPE_UINT16 :: IndexType

INDEX_TYPE_UINT16 specifies that indices are 16-bit unsigned integer values.

pattern INDEX_TYPE_UINT32 :: IndexType

INDEX_TYPE_UINT32 specifies that indices are 32-bit unsigned integer values.

pattern INDEX_TYPE_UINT8_EXT :: IndexType

INDEX_TYPE_UINT8_EXT specifies that indices are 8-bit unsigned integer values.

pattern INDEX_TYPE_NONE_KHR :: IndexType

INDEX_TYPE_NONE_KHR specifies that no indices are provided.

Instances

Instances details
Storable IndexType Source # 
Instance details

Defined in Vulkan.Core10.Enums.IndexType

Read IndexType Source # 
Instance details

Defined in Vulkan.Core10.Enums.IndexType

Show IndexType Source # 
Instance details

Defined in Vulkan.Core10.Enums.IndexType

Eq IndexType Source # 
Instance details

Defined in Vulkan.Core10.Enums.IndexType

Ord IndexType Source # 
Instance details

Defined in Vulkan.Core10.Enums.IndexType

Zero IndexType Source # 
Instance details

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

VK_VERSION_1_0, SubpassBeginInfo, cmdBeginRenderPass, cmdNextSubpass

Constructors

SubpassContents Int32 

Bundled Patterns

pattern SUBPASS_CONTENTS_INLINE :: SubpassContents

SUBPASS_CONTENTS_INLINE specifies that the contents of the subpass will be recorded inline in the primary command buffer, and secondary command buffers must not be executed within the subpass.

pattern SUBPASS_CONTENTS_SECONDARY_COMMAND_BUFFERS :: SubpassContents

SUBPASS_CONTENTS_SECONDARY_COMMAND_BUFFERS specifies that the contents are recorded in secondary command buffers that will be called from the primary command buffer, and cmdExecuteCommands is the only valid command in the command buffer until cmdNextSubpass or cmdEndRenderPass.

pattern SUBPASS_CONTENTS_INLINE_AND_SECONDARY_COMMAND_BUFFERS_EXT :: SubpassContents

SUBPASS_CONTENTS_INLINE_AND_SECONDARY_COMMAND_BUFFERS_EXT specifies that the contents of the subpass can be recorded both inline and in secondary command buffers executed from this command buffer with cmdExecuteCommands.

Instances

Instances details
Storable SubpassContents Source # 
Instance details

Defined in Vulkan.Core10.Enums.SubpassContents

Read SubpassContents Source # 
Instance details

Defined in Vulkan.Core10.Enums.SubpassContents

Show SubpassContents Source # 
Instance details

Defined in Vulkan.Core10.Enums.SubpassContents

Eq SubpassContents Source # 
Instance details

Defined in Vulkan.Core10.Enums.SubpassContents

Ord SubpassContents Source # 
Instance details

Defined in Vulkan.Core10.Enums.SubpassContents

Zero SubpassContents Source # 
Instance details

Defined in Vulkan.Core10.Enums.SubpassContents

newtype StencilFaceFlagBits Source #

VkStencilFaceFlagBits - Bitmask specifying sets of stencil state for which to update the compare mask

See Also

VK_VERSION_1_0, StencilFaceFlags

Bundled Patterns

pattern STENCIL_FACE_FRONT_BIT :: StencilFaceFlagBits

STENCIL_FACE_FRONT_BIT specifies that only the front set of stencil state is updated.

pattern STENCIL_FACE_BACK_BIT :: StencilFaceFlagBits

STENCIL_FACE_BACK_BIT specifies that only the back set of stencil state is updated.

pattern STENCIL_FACE_FRONT_AND_BACK :: StencilFaceFlagBits

STENCIL_FACE_FRONT_AND_BACK is the combination of STENCIL_FACE_FRONT_BIT and STENCIL_FACE_BACK_BIT, and specifies that both sets of stencil state are updated.

Instances

Instances details
Storable StencilFaceFlagBits Source # 
Instance details

Defined in Vulkan.Core10.Enums.StencilFaceFlagBits

Bits StencilFaceFlagBits Source # 
Instance details

Defined in Vulkan.Core10.Enums.StencilFaceFlagBits

FiniteBits StencilFaceFlagBits Source # 
Instance details

Defined in Vulkan.Core10.Enums.StencilFaceFlagBits

Read StencilFaceFlagBits Source # 
Instance details

Defined in Vulkan.Core10.Enums.StencilFaceFlagBits

Show StencilFaceFlagBits Source # 
Instance details

Defined in Vulkan.Core10.Enums.StencilFaceFlagBits

Eq StencilFaceFlagBits Source # 
Instance details

Defined in Vulkan.Core10.Enums.StencilFaceFlagBits

Ord StencilFaceFlagBits Source # 
Instance details

Defined in Vulkan.Core10.Enums.StencilFaceFlagBits

Zero StencilFaceFlagBits Source # 
Instance details

Defined in Vulkan.Core10.Enums.StencilFaceFlagBits