Graphics.Vulkan.Core10.CommandBufferBuilding

Documentation

cmdBindPipeline :: forall io. MonadIO io => CommandBuffer -> PipelineBindPoint -> Pipeline -> io ()

vkCmdBindPipeline - Bind a pipeline object to a command buffer

Parameters

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

• pipelineBindPoint is a PipelineBindPoint value specifying whether to bind to the compute or graphics bind point. Binding one does not disturb the other.
• pipeline is the pipeline to be bound.

Description

Once bound, a pipeline binding affects subsequent graphics or compute commands in the command buffer until a different pipeline is bound to the bind point. The pipeline bound to PIPELINE_BIND_POINT_COMPUTE controls the behavior of cmdDispatch and cmdDispatchIndirect. The pipeline bound to PIPELINE_BIND_POINT_GRAPHICS controls the behavior of all drawing commands. The pipeline bound to PIPELINE_BIND_POINT_RAY_TRACING_KHR controls the behavior of cmdTraceRaysKHR. No other commands are affected by the pipeline state.

Valid Usage

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

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

Valid Usage (Implicit)

• commandBuffer must be a valid CommandBuffer handle

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

Host Synchronization

• Host access to commandBuffer must be externally synchronized

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

Command Properties

'

Command Buffer Levels	Render Pass Scope	Supported Queue Types	Pipeline Type
Primary Secondary	Both	Graphics Compute

See Also

CommandBuffer, Pipeline, PipelineBindPoint

cmdSetViewport :: forall io. MonadIO io => CommandBuffer -> ("firstViewport" ::: Word32) -> ("viewports" ::: Vector Viewport) -> io ()

vkCmdSetViewport - Set the viewport on a command buffer

Parameters

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

• firstViewport is the index of the first viewport whose parameters are updated by the command.
• viewportCount is the number of viewports whose parameters are updated by the command.
• pViewports is a pointer to an array of Viewport structures specifying viewport parameters.

Description

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

Valid Usage

• firstViewport must be less than PhysicalDeviceLimits::maxViewports

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

Valid Usage (Implicit)

• commandBuffer must be a valid CommandBuffer handle

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

Host Synchronization

• Host access to commandBuffer must be externally synchronized

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

Command Properties

'

Command Buffer Levels	Render Pass Scope	Supported Queue Types	Pipeline Type
Primary Secondary	Both	Graphics

See Also

CommandBuffer, Viewport

cmdSetScissor :: forall io. MonadIO io => CommandBuffer -> ("firstScissor" ::: Word32) -> ("scissors" ::: Vector Rect2D) -> io ()

vkCmdSetScissor - Set the dynamic scissor rectangles on a command buffer

Parameters

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

• firstScissor is the index of the first scissor whose state is updated by the command.
• scissorCount is the number of scissors whose rectangles are updated by the command.
• pScissors is a pointer to an array of Rect2D structures defining scissor rectangles.

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

Each scissor rectangle is described by a Rect2D structure, with the offset.x and offset.y values determining the upper left corner of the scissor rectangle, and the extent.width and extent.height values determining the size in pixels.

If a render pass transform is enabled, the (offset.x and offset.y) and (extent.width and extent.height) values are transformed as described in render pass transform before participating in the scissor test.

Valid Usage

• firstScissor must be less than PhysicalDeviceLimits::maxViewports

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

Valid Usage (Implicit)

• commandBuffer must be a valid CommandBuffer handle

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

Host Synchronization

• Host access to commandBuffer must be externally synchronized

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

Command Properties

'

Command Buffer Levels	Render Pass Scope	Supported Queue Types	Pipeline Type
Primary Secondary	Both	Graphics

See Also

CommandBuffer, Rect2D

cmdSetLineWidth :: forall io. MonadIO io => CommandBuffer -> ("lineWidth" ::: Float) -> io ()

vkCmdSetLineWidth - Set the dynamic line width state

Parameters

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

• lineWidth is the width of rasterized line segments.

Valid Usage

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

Valid Usage (Implicit)

• commandBuffer must be a valid CommandBuffer handle

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

Host Synchronization

• Host access to commandBuffer must be externally synchronized

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

Command Properties

'

Command Buffer Levels	Render Pass Scope	Supported Queue Types	Pipeline Type
Primary Secondary	Both	Graphics

See Also

CommandBuffer

cmdSetDepthBias :: forall io. MonadIO io => CommandBuffer -> ("depthBiasConstantFactor" ::: Float) -> ("depthBiasClamp" ::: Float) -> ("depthBiasSlopeFactor" ::: Float) -> io ()

vkCmdSetDepthBias - Set the depth bias dynamic state

Parameters

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

• depthBiasConstantFactor is a scalar factor controlling the constant depth value added to each fragment.
• depthBiasClamp is the maximum (or minimum) depth bias of a fragment.
• depthBiasSlopeFactor is a scalar factor applied to a fragment’s slope in depth bias calculations.

Description

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

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

The maximum depth slope m of a triangle is

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

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

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

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

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

• r = 2e-n

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

If no depth buffer is present, r is undefined.

The bias value o for a polygon is

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

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

See Also

CommandBuffer

cmdSetBlendConstants :: forall io. MonadIO io => CommandBuffer -> ("blendConstants" ::: (Float, Float, Float, Float)) -> io ()

vkCmdSetBlendConstants - Set the values of blend constants

Parameters

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

• blendConstants is a pointer to an array of four values specifying the R, G, B, and A components of the blend constant color used in blending, depending on the blend factor.

Valid Usage (Implicit)

• commandBuffer must be a valid CommandBuffer handle

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

Host Synchronization

• Host access to commandBuffer must be externally synchronized

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

Command Properties

'

Command Buffer Levels	Render Pass Scope	Supported Queue Types	Pipeline Type
Primary Secondary	Both	Graphics

See Also

CommandBuffer

cmdSetDepthBounds :: forall io. MonadIO io => CommandBuffer -> ("minDepthBounds" ::: Float) -> ("maxDepthBounds" ::: Float) -> io ()

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

Parameters

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

• minDepthBounds is the lower bound of the range of depth values used in the depth bounds test.
• maxDepthBounds is the upper bound of the range.

Valid Usage

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

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

Valid Usage (Implicit)

• commandBuffer must be a valid CommandBuffer handle

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

Host Synchronization

• Host access to commandBuffer must be externally synchronized

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

Command Properties

'

Command Buffer Levels	Render Pass Scope	Supported Queue Types	Pipeline Type
Primary Secondary	Both	Graphics

See Also

CommandBuffer

cmdSetStencilCompareMask :: forall io. MonadIO io => CommandBuffer -> ("faceMask" ::: StencilFaceFlags) -> ("compareMask" ::: Word32) -> io ()

vkCmdSetStencilCompareMask - Set the stencil compare mask dynamic state

Parameters

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

• faceMask is a bitmask of StencilFaceFlagBits specifying the set of stencil state for which to update the compare mask.
• compareMask is the new value to use as the stencil compare mask.

Valid Usage (Implicit)

• commandBuffer must be a valid CommandBuffer handle

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

Host Synchronization

• Host access to commandBuffer must be externally synchronized

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

Command Properties

'

Command Buffer Levels	Render Pass Scope	Supported Queue Types	Pipeline Type
Primary Secondary	Both	Graphics

See Also

CommandBuffer, StencilFaceFlags

cmdSetStencilWriteMask :: forall io. MonadIO io => CommandBuffer -> ("faceMask" ::: StencilFaceFlags) -> ("writeMask" ::: Word32) -> io ()

vkCmdSetStencilWriteMask - Set the stencil write mask dynamic state

Parameters

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

• 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 is the new value to use as the stencil write mask.

Valid Usage (Implicit)

• commandBuffer must be a valid CommandBuffer handle

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

Host Synchronization

• Host access to commandBuffer must be externally synchronized

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

Command Properties

'

Command Buffer Levels	Render Pass Scope	Supported Queue Types	Pipeline Type
Primary Secondary	Both	Graphics

See Also

CommandBuffer, StencilFaceFlags

cmdSetStencilReference :: forall io. MonadIO io => CommandBuffer -> ("faceMask" ::: StencilFaceFlags) -> ("reference" ::: Word32) -> io ()

vkCmdSetStencilReference - Set the stencil reference dynamic state

Parameters

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

• 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 is the new value to use as the stencil reference value.

Valid Usage (Implicit)

• commandBuffer must be a valid CommandBuffer handle

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

Host Synchronization

• Host access to commandBuffer must be externally synchronized

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

Command Properties

'

Command Buffer Levels	Render Pass Scope	Supported Queue Types	Pipeline Type
Primary Secondary	Both	Graphics

See Also

CommandBuffer, StencilFaceFlags

cmdBindDescriptorSets :: forall io. MonadIO io => CommandBuffer -> PipelineBindPoint -> PipelineLayout -> ("firstSet" ::: Word32) -> ("descriptorSets" ::: Vector DescriptorSet) -> ("dynamicOffsets" ::: Vector Word32) -> io ()

vkCmdBindDescriptorSets - Binds descriptor sets to a command buffer

Parameters

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

• pipelineBindPoint is a PipelineBindPoint indicating whether the descriptors will be used by graphics pipelines or compute pipelines. There is a separate set of bind points for each of graphics and compute, so binding one does not disturb the other.
• layout is a PipelineLayout object used to program the bindings.
• firstSet is the set number of the first descriptor set to be bound.
• descriptorSetCount is the number of elements in the pDescriptorSets array.
• pDescriptorSets is a pointer to an array of handles to DescriptorSet objects describing the descriptor sets to write to.
• dynamicOffsetCount is the number of dynamic offsets in the pDynamicOffsets array.
• pDynamicOffsets is a pointer to an array of uint32_t values specifying dynamic offsets.

Description

cmdBindDescriptorSets causes the sets numbered [firstSet.. firstSet+descriptorSetCount-1] to use the bindings stored in pDescriptorSets[0..descriptorSetCount-1] for subsequent rendering commands (either compute or graphics, according to the pipelineBindPoint). Any bindings that were previously applied via these sets are no longer valid.

Once bound, a descriptor set affects rendering of subsequent graphics or compute commands in the command buffer until a different set is bound to the same set number, or else until the set is disturbed as described in Pipeline Layout Compatibility.

A compatible descriptor set must be bound for all set numbers that any shaders in a pipeline access, at the time that a draw or dispatch command is recorded to execute using that pipeline. However, if none of the shaders in a pipeline statically use any bindings with a particular set number, then no descriptor set need be bound for that set number, even if the pipeline layout includes a non-trivial descriptor set layout for that set number.

If any of the sets being bound include dynamic uniform or storage buffers, then pDynamicOffsets includes one element for each array element in each dynamic descriptor type binding in each set. Values are taken from pDynamicOffsets in an order such that all entries for set N come before set N+1; within a set, entries are ordered by the binding numbers in the descriptor set layouts; and within a binding array, elements are in order. dynamicOffsetCount must equal the total number of dynamic descriptors in the sets being bound.

The effective offset used for dynamic uniform and storage buffer bindings is the sum of the relative offset taken from pDynamicOffsets, and the base address of the buffer plus base offset in the descriptor set. The range of the dynamic uniform and storage buffer bindings is the buffer range as specified in the descriptor set.

Each of the pDescriptorSets must be compatible with the pipeline layout specified by layout. The layout used to program the bindings must also be compatible with the pipeline used in subsequent graphics or compute commands, as defined in the Pipeline Layout Compatibility section.

The descriptor set contents bound by a call to cmdBindDescriptorSets may be consumed at the following times:

• For descriptor bindings created with the DESCRIPTOR_BINDING_UPDATE_AFTER_BIND_BIT bit set, the contents may be consumed when the command buffer is submitted to a queue, or during shader execution of the resulting draws and dispatches, or any time in between. Otherwise,
• during host execution of the command, or during shader execution of the resulting draws and dispatches, or any time in between.

Thus, the contents of a descriptor set binding must not be altered (overwritten by an update command, or freed) between the first point in time that it may be consumed, and when the command completes executing on the queue.

The contents of pDynamicOffsets are consumed immediately during execution of cmdBindDescriptorSets. Once all pending uses have completed, it is legal to update and reuse a descriptor set.

Valid Usage

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

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

Valid Usage (Implicit)

• commandBuffer must be a valid CommandBuffer handle

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

Host Synchronization

• Host access to commandBuffer must be externally synchronized

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

Command Properties

'

Command Buffer Levels	Render Pass Scope	Supported Queue Types	Pipeline Type
Primary Secondary	Both	Graphics Compute

See Also

CommandBuffer, DescriptorSet, PipelineBindPoint, PipelineLayout

cmdBindIndexBuffer :: forall io. MonadIO io => CommandBuffer -> Buffer -> ("offset" ::: DeviceSize) -> IndexType -> io ()

vkCmdBindIndexBuffer - Bind an index buffer to a command buffer

Parameters

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

• buffer is the buffer being bound.
• offset is the starting offset in bytes within buffer used in index buffer address calculations.
• indexType is a IndexType value specifying whether indices are treated as 16 bits or 32 bits.

Valid Usage

• offset must be less than the size of buffer

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

Valid Usage (Implicit)

• commandBuffer must be a valid CommandBuffer handle

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

Host Synchronization

• Host access to commandBuffer must be externally synchronized

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

Command Properties

'

Command Buffer Levels	Render Pass Scope	Supported Queue Types	Pipeline Type
Primary Secondary	Both	Graphics

See Also

Buffer, CommandBuffer, DeviceSize, IndexType

cmdBindVertexBuffers :: forall io. MonadIO io => CommandBuffer -> ("firstBinding" ::: Word32) -> ("buffers" ::: Vector Buffer) -> ("offsets" ::: Vector DeviceSize) -> io ()

vkCmdBindVertexBuffers - Bind vertex buffers to a command buffer

Parameters

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

• firstBinding is the index of the first vertex input binding whose state is updated by the command.
• bindingCount is the number of vertex input bindings whose state is updated by the command.
• pBuffers is a pointer to an array of buffer handles.
• pOffsets is a pointer to an array of buffer offsets.

Description

The values taken from elements i of pBuffers and pOffsets replace the current state for the vertex input binding firstBinding + i, for i in [0, bindingCount). The vertex input binding is updated to start at the offset indicated by pOffsets[i] from the start of the buffer pBuffers[i]. All vertex input attributes that use each of these bindings will use these updated addresses in their address calculations for subsequent draw commands. If the nullDescriptor feature is enabled, elements of pBuffers can be NULL_HANDLE, and can be used by the vertex shader. If a vertex input attribute is bound to a vertex input binding that is NULL_HANDLE, the values taken from memory are considered to be zero, and missing G, B, or A components are filled with (0,0,1).

Valid Usage

• firstBinding must be less than PhysicalDeviceLimits::maxVertexInputBindings

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

Valid Usage (Implicit)

• commandBuffer must be a valid CommandBuffer handle

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

Host Synchronization

• Host access to commandBuffer must be externally synchronized

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

Command Properties

'

Command Buffer Levels	Render Pass Scope	Supported Queue Types	Pipeline Type
Primary Secondary	Both	Graphics

See Also

Buffer, CommandBuffer, DeviceSize

cmdDraw :: forall io. MonadIO io => CommandBuffer -> ("vertexCount" ::: Word32) -> ("instanceCount" ::: Word32) -> ("firstVertex" ::: Word32) -> ("firstInstance" ::: Word32) -> io ()

vkCmdDraw - Draw primitives

Parameters

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

• vertexCount is the number of vertices to draw.
• instanceCount is the number of instances to draw.
• firstVertex is the index of the first vertex to draw.
• firstInstance is the instance ID of the first instance to draw.

Description

When the command is executed, primitives are assembled using the current primitive topology and vertexCount consecutive vertex indices with the first vertexIndex value equal to firstVertex. The primitives are drawn instanceCount times with instanceIndex starting with firstInstance and increasing sequentially for each instance. The assembled primitives execute the bound graphics pipeline.

Valid Usage

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

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

Valid Usage (Implicit)

• commandBuffer must be a valid CommandBuffer handle

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

Host Synchronization

• Host access to commandBuffer must be externally synchronized

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

Command Properties

'

Command Buffer Levels	Render Pass Scope	Supported Queue Types	Pipeline Type
Primary Secondary	Inside	Graphics	Graphics

See Also

CommandBuffer

cmdDrawIndexed :: forall io. MonadIO io => CommandBuffer -> ("indexCount" ::: Word32) -> ("instanceCount" ::: Word32) -> ("firstIndex" ::: Word32) -> ("vertexOffset" ::: Int32) -> ("firstInstance" ::: Word32) -> io ()

vkCmdDrawIndexed - Issue an indexed draw into a command buffer

Parameters

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

• indexCount is the number of vertices to draw.
• instanceCount is the number of instances to draw.
• firstIndex is the base index within the index buffer.
• vertexOffset is the value added to the vertex index before indexing into the vertex buffer.
• firstInstance is the instance ID of the first instance to draw.

Description

When the command is executed, primitives are assembled using the current primitive topology and indexCount vertices whose indices are retrieved from the index buffer. The index buffer is treated as an array of tightly packed unsigned integers of size defined by the cmdBindIndexBuffer::indexType parameter with which the buffer was bound.

The first vertex index is at an offset of firstIndex * indexSize + offset within the bound index buffer, where offset is the offset specified by cmdBindIndexBuffer and indexSize is the byte size of the type specified by indexType. Subsequent index values are retrieved from consecutive locations in the index buffer. Indices are first compared to the primitive restart value, then zero extended to 32 bits (if the indexType is INDEX_TYPE_UINT8_EXT or INDEX_TYPE_UINT16) and have vertexOffset added to them, before being supplied as the vertexIndex value.

The primitives are drawn instanceCount times with instanceIndex starting with firstInstance and increasing sequentially for each instance. The assembled primitives execute the bound graphics pipeline.

Valid Usage

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

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

Valid Usage (Implicit)

• commandBuffer must be a valid CommandBuffer handle

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

Host Synchronization

• Host access to commandBuffer must be externally synchronized

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

Command Properties

'

Command Buffer Levels	Render Pass Scope	Supported Queue Types	Pipeline Type
Primary Secondary	Inside	Graphics	Graphics

See Also

CommandBuffer

cmdDrawIndirect :: forall io. MonadIO io => CommandBuffer -> Buffer -> ("offset" ::: DeviceSize) -> ("drawCount" ::: Word32) -> ("stride" ::: Word32) -> io ()

vkCmdDrawIndirect - Issue an indirect draw into a command buffer

Parameters

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

• buffer is the buffer containing draw parameters.
• offset is the byte offset into buffer where parameters begin.
• drawCount is the number of draws to execute, and can be zero.
• stride is the byte stride between successive sets of draw 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

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

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

Valid Usage (Implicit)

• commandBuffer must be a valid CommandBuffer handle

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

Host Synchronization

• Host access to commandBuffer must be externally synchronized

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

Command Properties

'

Command Buffer Levels	Render Pass Scope	Supported Queue Types	Pipeline Type
Primary Secondary	Inside	Graphics	Graphics

See Also

Buffer, CommandBuffer, DeviceSize

cmdDrawIndexedIndirect :: forall io. MonadIO io => CommandBuffer -> Buffer -> ("offset" ::: DeviceSize) -> ("drawCount" ::: Word32) -> ("stride" ::: Word32) -> io ()

vkCmdDrawIndexedIndirect - Perform an indexed indirect draw

Parameters

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

• buffer is the buffer containing draw parameters.
• offset is the byte offset into buffer where parameters begin.
• drawCount is the number of draws to execute, and can be zero.
• stride is the byte stride between successive sets of draw parameters.

Description

cmdDrawIndexedIndirect behaves similarly to cmdDrawIndexed except that the parameters are read by the device from a buffer during execution. drawCount draws are executed by the command, with parameters taken from buffer starting at offset and increasing by stride bytes for each successive draw. The parameters of each draw are encoded in an array of DrawIndexedIndirectCommand structures. If drawCount is less than or equal to one, stride is ignored.

Valid Usage

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

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

Valid Usage (Implicit)

• commandBuffer must be a valid CommandBuffer handle

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

Host Synchronization

• Host access to commandBuffer must be externally synchronized

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

Command Properties

'

Command Buffer Levels	Render Pass Scope	Supported Queue Types	Pipeline Type
Primary Secondary	Inside	Graphics	Graphics

See Also

Buffer, CommandBuffer, DeviceSize

cmdDispatch :: forall io. MonadIO io => CommandBuffer -> ("groupCountX" ::: Word32) -> ("groupCountY" ::: Word32) -> ("groupCountZ" ::: Word32) -> io ()

vkCmdDispatch - Dispatch compute work items

Parameters

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

• groupCountX is the number of local workgroups to dispatch in the X dimension.
• groupCountY is the number of local workgroups to dispatch in the Y dimension.
• groupCountZ is the number of local workgroups to dispatch in the Z dimension.

Description

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

Valid Usage

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

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

Valid Usage (Implicit)

• commandBuffer must be a valid CommandBuffer handle

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

Host Synchronization

• Host access to commandBuffer must be externally synchronized

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

Command Properties

'

Command Buffer Levels	Render Pass Scope	Supported Queue Types	Pipeline Type
Primary Secondary	Outside	Compute	Compute

See Also

CommandBuffer

cmdDispatchIndirect :: forall io. MonadIO io => CommandBuffer -> Buffer -> ("offset" ::: DeviceSize) -> io ()

vkCmdDispatchIndirect - Dispatch compute work items using indirect parameters

Parameters

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

• buffer is the buffer containing dispatch parameters.
• offset is the byte offset into buffer where parameters begin.

Description

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

Valid Usage

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

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

Valid Usage (Implicit)

• commandBuffer must be a valid CommandBuffer handle

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

Host Synchronization

• Host access to commandBuffer must be externally synchronized

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

Command Properties

'

Command Buffer Levels	Render Pass Scope	Supported Queue Types	Pipeline Type
Primary Secondary	Outside	Compute	Compute

See Also

Buffer, CommandBuffer, DeviceSize

cmdCopyBuffer :: forall io. MonadIO io => CommandBuffer -> ("srcBuffer" ::: Buffer) -> ("dstBuffer" ::: Buffer) -> ("regions" ::: Vector BufferCopy) -> io ()

vkCmdCopyBuffer - Copy data between buffer regions

Parameters

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

• srcBuffer is the source buffer.
• dstBuffer is the destination buffer.
• regionCount is the number of regions to copy.
• pRegions is a pointer to an array of BufferCopy structures specifying the regions to copy.

Description

Each region in pRegions is copied from the source buffer to the same region of the destination buffer. srcBuffer and dstBuffer can be the same buffer or alias the same memory, but the resulting values are undefined if the copy regions overlap in memory.

Valid Usage

• 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
• If commandBuffer is an unprotected command buffer, then srcBuffer must not be a protected buffer
• If commandBuffer is an unprotected command buffer, then dstBuffer must not be a protected buffer
• If commandBuffer is a protected command buffer, then dstBuffer must not be an unprotected buffer

Valid Usage (Implicit)

• commandBuffer must be a valid CommandBuffer handle

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

Host Synchronization

• Host access to commandBuffer must be externally synchronized

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

Command Properties

'

Command Buffer Levels	Render Pass Scope	Supported Queue Types	Pipeline Type
Primary Secondary	Outside	Transfer Graphics Compute	Transfer

See Also

Buffer, BufferCopy, CommandBuffer

cmdCopyImage :: forall io. MonadIO io => CommandBuffer -> ("srcImage" ::: Image) -> ("srcImageLayout" ::: ImageLayout) -> ("dstImage" ::: Image) -> ("dstImageLayout" ::: ImageLayout) -> ("regions" ::: Vector ImageCopy) -> io ()

vkCmdCopyImage - Copy data between images

Parameters

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

• srcImage is the source image.
• srcImageLayout is the current layout of the source image subresource.
• dstImage is the destination image.
• dstImageLayout is the current layout of the destination image subresource.
• regionCount is the number of regions to copy.
• pRegions is a pointer to an array of ImageCopy structures specifying the regions to copy.

Description

Each region in pRegions is copied from the source image to the same region of the destination image. srcImage and dstImage can be the same image or alias the same memory.

The formats of srcImage and dstImage must be compatible. Formats are compatible if they share the same class, as shown in the Compatible Formats table. Depth/stencil formats must match exactly.

If the format of srcImage or dstImage is a multi-planar image format, regions of each plane to be copied must be specified separately using the srcSubresource and dstSubresource members of the ImageCopy structure. In this case, the aspectMask of the srcSubresource or dstSubresource that refers to the multi-planar image must be IMAGE_ASPECT_PLANE_0_BIT, IMAGE_ASPECT_PLANE_1_BIT, or IMAGE_ASPECT_PLANE_2_BIT. For the purposes of cmdCopyImage, each plane of a multi-planar image is treated as having the format listed in https://www.khronos.org/registry/vulkan/specs/1.2-extensions/html/vkspec.html#formats-compatible-planes for the plane identified by the aspectMask of the corresponding subresource. This applies both to Format and to coordinates used in the copy, which correspond to texels in the plane rather than how these texels map to coordinates in the image as a whole.

Note

For example, the IMAGE_ASPECT_PLANE_1_BIT plane of a FORMAT_G8_B8R8_2PLANE_420_UNORM image is compatible with an image of format FORMAT_R8G8_UNORM and (less usefully) with the IMAGE_ASPECT_PLANE_0_BIT plane of an image of format FORMAT_G10X6_B10X6_R10X6_3PLANE_420_UNORM_3PACK16, as each texel is 2 bytes in size.

cmdCopyImage allows copying between size-compatible compressed and uncompressed internal formats. Formats are size-compatible if the texel block size of the uncompressed format is equal to the texel block size of the compressed format. Such a copy does not perform on-the-fly compression or decompression. When copying from an uncompressed format to a compressed format, each texel of uncompressed data of the source image is copied as a raw value to the corresponding compressed texel block of the destination image. When copying from a compressed format to an uncompressed format, each compressed texel block of the source image is copied as a raw value to the corresponding texel of uncompressed data in the destination image. Thus, for example, it is legal to copy between a 128-bit uncompressed format and a compressed format which has a 128-bit sized compressed texel block representing 4×4 texels (using 8 bits per texel), or between a 64-bit uncompressed format and a compressed format which has a 64-bit sized compressed texel block representing 4×4 texels (using 4 bits per texel).

When copying between compressed and uncompressed formats the extent members represent the texel dimensions of the source image and not the destination. When copying from a compressed image to an uncompressed image the image texel dimensions written to the uncompressed image will be source extent divided by the compressed texel block dimensions. When copying from an uncompressed image to a compressed image the image texel dimensions written to the compressed image will be the source extent multiplied by the compressed texel block dimensions. In both cases the number of bytes read and the number of bytes written will be identical.

Copying to or from block-compressed images is typically done in multiples of the compressed texel block size. For this reason the extent must be a multiple of the compressed texel block dimension. There is one exception to this rule which is required to handle compressed images created with dimensions that are not a multiple of the compressed texel block dimensions: if the srcImage is compressed, then:

• If extent.width is not a multiple of the compressed texel block width, then (extent.width + srcOffset.x) must equal the image subresource width.
• If extent.height is not a multiple of the compressed texel block height, then (extent.height + srcOffset.y) must equal the image subresource height.
• If extent.depth is not a multiple of the compressed texel block depth, then (extent.depth + srcOffset.z) must equal the image subresource depth.

Similarly, if the dstImage is compressed, then:

• If extent.width is not a multiple of the compressed texel block width, then (extent.width + dstOffset.x) must equal the image subresource width.
• If extent.height is not a multiple of the compressed texel block height, then (extent.height + dstOffset.y) must equal the image subresource height.
• If extent.depth is not a multiple of the compressed texel block depth, then (extent.depth + dstOffset.z) must equal the image subresource depth.

This allows the last compressed texel block of the image in each non-multiple dimension to be included as a source or destination of the copy.

“_422” image formats that are not multi-planar are treated as having a 2×1 compressed texel block for the purposes of these rules.

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

Valid Usage

• The union of all source regions, and the union of all destination regions, specified by the elements of pRegions, must not overlap in memory

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

Valid Usage (Implicit)

• commandBuffer must be a valid CommandBuffer handle

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

Host Synchronization

• Host access to commandBuffer must be externally synchronized

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

Command Properties

'

Command Buffer Levels	Render Pass Scope	Supported Queue Types	Pipeline Type
Primary Secondary	Outside	Transfer Graphics Compute	Transfer

See Also

CommandBuffer, Image, ImageCopy, ImageLayout

cmdBlitImage :: forall io. MonadIO io => CommandBuffer -> ("srcImage" ::: Image) -> ("srcImageLayout" ::: ImageLayout) -> ("dstImage" ::: Image) -> ("dstImageLayout" ::: ImageLayout) -> ("regions" ::: Vector ImageBlit) -> Filter -> io ()

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

Parameters

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

• srcImage is the source image.
• srcImageLayout is the layout of the source image subresources for the blit.
• dstImage is the destination image.
• dstImageLayout is the layout of the destination image subresources for the blit.
• regionCount is the number of regions to blit.
• pRegions is a pointer to an array of ImageBlit structures specifying the regions to blit.
• filter is a Filter specifying the filter to apply if the blits require scaling.

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:

  • scale_u = (xsrc1 - xsrc0) / (xdst1 - xdst0)
  • scale_v = (ysrc1 - ysrc0) / (ydst1 - ydst0)
  • scale_w = (zsrc1 - zsrc0) / (zdst1 - zdst0)
  • uscaled = uoffset * scaleu
  • vscaled = voffset * scalev
  • wscaled = woffset * scalew

• Finally the source offset is added to the scaled coordinates, to determine the final unnormalized coordinates used to sample from srcImage:

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

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

Note

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

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

3D textures are blitted slice by slice. Slices in the source region bounded by srcOffsets[0].z and srcOffsets[1].z are copied to slices in the destination region bounded by dstOffsets[0].z and dstOffsets[1].z. For each destination slice, a source z coordinate is linearly interpolated between srcOffsets[0].z and srcOffsets[1].z. If the filter parameter is FILTER_LINEAR then the value sampled from the source image is taken by doing linear filtering using the interpolated z coordinate. If filter parameter is FILTER_NEAREST then the value sampled from the source image is taken from the single nearest slice, with an implementation-dependent arithmetic rounding mode.

The following filtering and conversion rules apply:

• Integer formats can only be converted to other integer formats with the same signedness.
• No format conversion is supported between depth/stencil images. The formats must match.
• Format conversions on unorm, snorm, unscaled and packed float formats of the copied aspect of the image are performed by first converting the pixels to float values.
• For sRGB source formats, nonlinear RGB values are converted to linear representation prior to filtering.
• After filtering, the float values are first clamped and then cast to the destination image format. In case of sRGB destination format, linear RGB values are converted to nonlinear representation before writing the pixel to the image.

Signed and unsigned integers are converted by first clamping to the representable range of the destination format, then casting the value.

Valid Usage

• The source region specified by each element of pRegions must be a region that is contained within srcImage

• The destination region specified by each element of pRegions must be a region that is contained within dstImage
• The union of all destination regions, specified by the elements of pRegions, must not overlap in memory with any texel that may be sampled during the blit operation
• The format features of srcImage must contain FORMAT_FEATURE_BLIT_SRC_BIT
• srcImage must not use a format listed in https://www.khronos.org/registry/vulkan/specs/1.2-extensions/html/vkspec.html#formats-requiring-sampler-ycbcr-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 listed in https://www.khronos.org/registry/vulkan/specs/1.2-extensions/html/vkspec.html#formats-requiring-sampler-ycbcr-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 have a ImageType of IMAGE_TYPE_2D
• If commandBuffer is an unprotected command buffer, then srcImage must not be a protected image
• If commandBuffer is an unprotected command buffer, then dstImage must not be a protected image
• If commandBuffer is a protected command buffer, then dstImage must not be an unprotected image
• The srcSubresource.mipLevel member of each element of pRegions must be less than the mipLevels specified in ImageCreateInfo when srcImage was created
• The dstSubresource.mipLevel member of each element of pRegions must be less than the mipLevels specified in ImageCreateInfo when dstImage was created
• The srcSubresource.baseArrayLayer + srcSubresource.layerCount of each element of pRegions must be less than or equal to the arrayLayers specified in ImageCreateInfo when srcImage was created
• The dstSubresource.baseArrayLayer + dstSubresource.layerCount of each element of pRegions must be less than or equal to the arrayLayers specified in ImageCreateInfo when dstImage was created
• dstImage and srcImage must not have been created with flags containing IMAGE_CREATE_SUBSAMPLED_BIT_EXT

Valid Usage (Implicit)

• commandBuffer must be a valid CommandBuffer handle

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

Host Synchronization

• Host access to commandBuffer must be externally synchronized

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

Command Properties

'

Command Buffer Levels	Render Pass Scope	Supported Queue Types	Pipeline Type
Primary Secondary	Outside	Graphics	Transfer

See Also

CommandBuffer, Filter, Image, ImageBlit, ImageLayout

cmdCopyBufferToImage :: forall io. MonadIO io => CommandBuffer -> ("srcBuffer" ::: Buffer) -> ("dstImage" ::: Image) -> ("dstImageLayout" ::: ImageLayout) -> ("regions" ::: Vector BufferImageCopy) -> io ()

vkCmdCopyBufferToImage - Copy data from a buffer into an image

Parameters

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

• srcBuffer is the source buffer.
• dstImage is the destination image.
• dstImageLayout is the layout of the destination image subresources for the copy.
• regionCount is the number of regions to copy.
• pRegions is a pointer to an array of BufferImageCopy structures specifying the regions to copy.

Description

Each region in pRegions is copied from the specified region of the source buffer to the specified region of the destination image.

If the format of dstImage is a multi-planar image format), regions of each plane to be a target of a copy must be specified separately using the pRegions member of the BufferImageCopy structure. In this case, the aspectMask of imageSubresource must be IMAGE_ASPECT_PLANE_0_BIT, IMAGE_ASPECT_PLANE_1_BIT, or IMAGE_ASPECT_PLANE_2_BIT. For the purposes of cmdCopyBufferToImage, each plane of a multi-planar image is treated as having the format listed in https://www.khronos.org/registry/vulkan/specs/1.2-extensions/html/vkspec.html#formats-compatible-planes for the plane identified by the aspectMask of the corresponding subresource. This applies both to Format and to coordinates used in the copy, which correspond to texels in the plane rather than how these texels map to coordinates in the image as a whole.

Valid Usage

• srcBuffer must be large enough to contain all buffer locations that are accessed according to Buffer and Image Addressing, for each element of pRegions

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

Valid Usage (Implicit)

• commandBuffer must be a valid CommandBuffer handle

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

Host Synchronization

• Host access to commandBuffer must be externally synchronized

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

Command Properties

'

Command Buffer Levels	Render Pass Scope	Supported Queue Types	Pipeline Type
Primary Secondary	Outside	Transfer Graphics Compute	Transfer

See Also

Buffer, BufferImageCopy, CommandBuffer, Image, ImageLayout

cmdCopyImageToBuffer :: forall io. MonadIO io => CommandBuffer -> ("srcImage" ::: Image) -> ("srcImageLayout" ::: ImageLayout) -> ("dstBuffer" ::: Buffer) -> ("regions" ::: Vector BufferImageCopy) -> io ()

vkCmdCopyImageToBuffer - Copy image data into a buffer

Parameters

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

• srcImage is the source image.
• srcImageLayout is the layout of the source image subresources for the copy.
• dstBuffer is the destination buffer.
• regionCount is the number of regions to copy.
• pRegions is a pointer to an array of BufferImageCopy structures specifying the regions to copy.

Description

Each region in pRegions is copied from the specified region of the source image to the specified region of the destination buffer.

If the Format of srcImage is a multi-planar image format, regions of each plane to be a source of a copy must be specified separately using the pRegions member of the BufferImageCopy structure. In this case, the aspectMask of imageSubresource must be IMAGE_ASPECT_PLANE_0_BIT, IMAGE_ASPECT_PLANE_1_BIT, or IMAGE_ASPECT_PLANE_2_BIT. For the purposes of cmdCopyBufferToImage, each plane of a multi-planar image is treated as having the format listed in https://www.khronos.org/registry/vulkan/specs/1.2-extensions/html/vkspec.html#formats-compatible-planes for the plane identified by the aspectMask of the corresponding subresource. This applies both to Format and to coordinates used in the copy, which correspond to texels in the plane rather than how these texels map to coordinates in the image as a whole.

Valid Usage

• The image region specified by each element of pRegions must be a region that is contained within srcImage if the srcImage’s Format is not a multi-planar format, and must be a region that is contained within the plane being copied if the srcImage’s Format is a multi-planar format

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

Valid Usage (Implicit)

• commandBuffer must be a valid CommandBuffer handle

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

Host Synchronization

• Host access to commandBuffer must be externally synchronized

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

Command Properties

'

Command Buffer Levels	Render Pass Scope	Supported Queue Types	Pipeline Type
Primary Secondary	Outside	Transfer Graphics Compute	Transfer

See Also

Buffer, BufferImageCopy, CommandBuffer, Image, ImageLayout

cmdUpdateBuffer :: forall io. MonadIO io => CommandBuffer -> ("dstBuffer" ::: Buffer) -> ("dstOffset" ::: DeviceSize) -> ("dataSize" ::: DeviceSize) -> ("data" ::: Ptr ()) -> io ()

vkCmdUpdateBuffer - Update a buffer’s contents from host memory

Parameters

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

• dstBuffer is a handle to the buffer to be updated.
• dstOffset is the byte offset into the buffer to start updating, and must be a multiple of 4.
• dataSize is the number of bytes to update, and must be a multiple of 4.
• pData is a pointer to the source data for the buffer update, and must be at least dataSize bytes in size.

Description

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

Note

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

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

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

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

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

Valid Usage

• dstOffset must be less than the size of dstBuffer

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

Valid Usage (Implicit)

• commandBuffer must be a valid CommandBuffer handle

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

Host Synchronization

• Host access to commandBuffer must be externally synchronized

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

Command Properties

'

Command Buffer Levels	Render Pass Scope	Supported Queue Types	Pipeline Type
Primary Secondary	Outside	Transfer Graphics Compute	Transfer

See Also

Buffer, CommandBuffer, DeviceSize

cmdFillBuffer :: forall io. MonadIO io => CommandBuffer -> ("dstBuffer" ::: Buffer) -> ("dstOffset" ::: DeviceSize) -> DeviceSize -> ("data" ::: Word32) -> io ()

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

Parameters

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

• dstBuffer is the buffer to be filled.
• dstOffset is the byte offset into the buffer at which to start filling, and must be a multiple of 4.
• 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 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.

Description

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

Valid Usage

• dstOffset must be less than the size of dstBuffer

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

Valid Usage (Implicit)

• commandBuffer must be a valid CommandBuffer handle

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

Host Synchronization

• Host access to commandBuffer must be externally synchronized

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

Command Properties

'

Command Buffer Levels	Render Pass Scope	Supported Queue Types	Pipeline Type
Primary Secondary	Outside	Transfer Graphics Compute	Transfer

See Also

Buffer, CommandBuffer, DeviceSize

cmdClearColorImage :: forall io. MonadIO io => CommandBuffer -> Image -> ImageLayout -> ClearColorValue -> ("ranges" ::: Vector ImageSubresourceRange) -> io ()

vkCmdClearColorImage - Clear regions of a color image

Parameters

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

• image is the image to be cleared.
• 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.
• pColor is a pointer to a ClearColorValue structure containing the values that the image subresource ranges will be cleared to (see https://www.khronos.org/registry/vulkan/specs/1.2-extensions/html/vkspec.html#clears-values below).
• rangeCount is the number of image subresource range structures in pRanges.
• 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.

Description

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

Valid Usage

• The format features of image must contain FORMAT_FEATURE_TRANSFER_DST_BIT

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

Valid Usage (Implicit)

• commandBuffer must be a valid CommandBuffer handle

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

Host Synchronization

• Host access to commandBuffer must be externally synchronized

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

Command Properties

'

Command Buffer Levels	Render Pass Scope	Supported Queue Types	Pipeline Type
Primary Secondary	Outside	Graphics Compute	Transfer

See Also

ClearColorValue, CommandBuffer, Image, ImageLayout, ImageSubresourceRange

cmdClearDepthStencilImage :: forall io. MonadIO io => CommandBuffer -> Image -> ImageLayout -> ClearDepthStencilValue -> ("ranges" ::: Vector ImageSubresourceRange) -> io ()

vkCmdClearDepthStencilImage - Fill regions of a combined depth/stencil image

Parameters

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

• image is the image to be cleared.
• 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.
• 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://www.khronos.org/registry/vulkan/specs/1.2-extensions/html/vkspec.html#clears-values below).
• rangeCount is the number of image subresource range structures in pRanges.
• 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.

Valid Usage

• The format features of image must contain FORMAT_FEATURE_TRANSFER_DST_BIT

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

Valid Usage (Implicit)

• commandBuffer must be a valid CommandBuffer handle

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

Host Synchronization

• Host access to commandBuffer must be externally synchronized

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

Command Properties

'

Command Buffer Levels	Render Pass Scope	Supported Queue Types	Pipeline Type
Primary Secondary	Outside	Graphics	Transfer

See Also

ClearDepthStencilValue, CommandBuffer, Image, ImageLayout, ImageSubresourceRange

cmdClearAttachments :: forall io. MonadIO io => CommandBuffer -> ("attachments" ::: Vector ClearAttachment) -> ("rects" ::: Vector ClearRect) -> io ()

vkCmdClearAttachments - Clear regions within bound framebuffer attachments

Parameters

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

• attachmentCount is the number of entries in the pAttachments array.
• pAttachments is a pointer to an array of ClearAttachment structures defining the attachments to clear and the clear values to use. If any attachment to be cleared in the current subpass is ATTACHMENT_UNUSED, then the clear has no effect on that attachment.
• rectCount is the number of entries in the pRects array.
• pRects is a pointer to an array of ClearRect structures defining regions within each selected attachment to clear.

Description

cmdClearAttachments can clear multiple regions of each attachment used in the current subpass of a render pass instance. This command must be called only inside a render pass instance, and implicitly selects the images to clear based on the current framebuffer attachments and the command parameters.

If the render pass has a fragment density map attachment, clears follow the operations of fragment density maps as if each clear region was a primitive which generates fragments. The clear color is applied to all pixels inside each fragment’s area regardless if the pixels lie outside of the clear region. Clears may have a different set of supported fragment areas than draws.

Unlike other clear commands, cmdClearAttachments executes as a drawing command, rather than a transfer command, with writes performed by it executing in rasterization order. Clears to color attachments are executed as color attachment writes, by the PIPELINE_STAGE_COLOR_ATTACHMENT_OUTPUT_BIT stage. Clears to depth/stencil attachments are executed as depth writes and writes by the PIPELINE_STAGE_EARLY_FRAGMENT_TESTS_BIT and PIPELINE_STAGE_LATE_FRAGMENT_TESTS_BIT stages.

Valid Usage

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

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

Valid Usage (Implicit)

• commandBuffer must be a valid CommandBuffer handle

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

Host Synchronization

• Host access to commandBuffer must be externally synchronized

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

Command Properties

'

Command Buffer Levels	Render Pass Scope	Supported Queue Types	Pipeline Type
Primary Secondary	Inside	Graphics	Graphics

See Also

ClearAttachment, ClearRect, CommandBuffer

cmdResolveImage :: forall io. MonadIO io => CommandBuffer -> ("srcImage" ::: Image) -> ("srcImageLayout" ::: ImageLayout) -> ("dstImage" ::: Image) -> ("dstImageLayout" ::: ImageLayout) -> ("regions" ::: Vector ImageResolve) -> io ()

vkCmdResolveImage - Resolve regions of an image

Parameters

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

• srcImage is the source image.
• srcImageLayout is the layout of the source image subresources for the resolve.
• dstImage is the destination image.
• dstImageLayout is the layout of the destination image subresources for the resolve.
• regionCount is the number of regions to resolve.
• pRegions is a pointer to an array of ImageResolve structures specifying the regions to resolve.

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.

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

• 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 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
• srcImage and dstImage must have been created with the same image format
• If commandBuffer is an unprotected command buffer, then srcImage must not be a protected image
• If commandBuffer is an unprotected command buffer, then dstImage must not be a protected image
• If commandBuffer is a protected command buffer, then dstImage must not be an unprotected image
• The srcSubresource.mipLevel member of each element of pRegions must be less than the mipLevels specified in ImageCreateInfo when srcImage was created
• The dstSubresource.mipLevel member of each element of pRegions must be less than the mipLevels specified in ImageCreateInfo when dstImage was created
• The srcSubresource.baseArrayLayer + srcSubresource.layerCount of each element of pRegions must be less than or equal to the arrayLayers specified in ImageCreateInfo when srcImage was created
• The dstSubresource.baseArrayLayer + dstSubresource.layerCount of each element of pRegions must be less than or equal to the arrayLayers specified in ImageCreateInfo when dstImage was created
• dstImage and srcImage must not have been created with flags containing IMAGE_CREATE_SUBSAMPLED_BIT_EXT

Valid Usage (Implicit)

• commandBuffer must be a valid CommandBuffer handle

• srcImage must be a valid Image handle
• srcImageLayout must be a valid ImageLayout value
• dstImage must be a valid Image handle
• dstImageLayout must be a valid ImageLayout value
• pRegions must be a valid pointer to an array of regionCount valid 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
• 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 Levels	Render Pass Scope	Supported Queue Types	Pipeline Type
Primary Secondary	Outside	Graphics	Transfer

See Also

CommandBuffer, Image, ImageLayout, ImageResolve

cmdSetEvent :: forall io. MonadIO io => CommandBuffer -> Event -> ("stageMask" ::: PipelineStageFlags) -> io ()

vkCmdSetEvent - Set an event object to signaled state

Parameters

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

• event is the event that will be signaled.
• stageMask specifies the source stage mask used to determine when the event is signaled.

Description

When cmdSetEvent is submitted to a queue, it defines an execution dependency on commands that were submitted before it, and defines an event signal operation which sets the event to the signaled state.

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

The second synchronization scope includes only the event signal operation.

If event is already in the signaled state when cmdSetEvent is executed on the device, then cmdSetEvent has no effect, no event signal operation occurs, and no execution dependency is generated.

Valid Usage

• stageMask must not include PIPELINE_STAGE_HOST_BIT

• If the geometry shaders feature is not enabled, stageMask must not contain PIPELINE_STAGE_GEOMETRY_SHADER_BIT
• If the tessellation shaders feature is not enabled, stageMask must not contain PIPELINE_STAGE_TESSELLATION_CONTROL_SHADER_BIT or PIPELINE_STAGE_TESSELLATION_EVALUATION_SHADER_BIT
• commandBuffer’s current device mask must include exactly one physical device
• If the mesh shaders feature is not enabled, stageMask must not contain PIPELINE_STAGE_MESH_SHADER_BIT_NV
• If the task shaders feature is not enabled, stageMask must not contain PIPELINE_STAGE_TASK_SHADER_BIT_NV

Valid Usage (Implicit)

• commandBuffer must be a valid CommandBuffer handle

• event must be a valid Event handle
• stageMask must be a valid combination of PipelineStageFlagBits values
• stageMask must not be 0
• 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
• 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 Levels	Render Pass Scope	Supported Queue Types	Pipeline Type
Primary Secondary	Outside	Graphics Compute

See Also

CommandBuffer, Event, PipelineStageFlags

cmdResetEvent :: forall io. MonadIO io => CommandBuffer -> Event -> ("stageMask" ::: PipelineStageFlags) -> io ()

vkCmdResetEvent - Reset an event object to non-signaled state

Parameters

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

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

Description

When cmdResetEvent is submitted to a queue, it defines an execution dependency on commands that were submitted before it, and defines an event unsignal operation which resets the event to the unsignaled state.

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

The second synchronization scope includes only the event unsignal operation.

If event is already in the unsignaled state when cmdResetEvent is executed on the device, then cmdResetEvent has no effect, no event unsignal operation occurs, and no execution dependency is generated.

Valid Usage

• stageMask must not include PIPELINE_STAGE_HOST_BIT

• If the geometry shaders feature is not enabled, stageMask must not contain PIPELINE_STAGE_GEOMETRY_SHADER_BIT
• If the tessellation shaders feature is not enabled, stageMask must not contain PIPELINE_STAGE_TESSELLATION_CONTROL_SHADER_BIT or PIPELINE_STAGE_TESSELLATION_EVALUATION_SHADER_BIT
• When this command executes, event must not be waited on by a cmdWaitEvents command that is currently executing
• commandBuffer’s current device mask must include exactly one physical device
• If the mesh shaders feature is not enabled, stageMask must not contain PIPELINE_STAGE_MESH_SHADER_BIT_NV
• If the task shaders feature is not enabled, stageMask must not contain PIPELINE_STAGE_TASK_SHADER_BIT_NV

Valid Usage (Implicit)

• commandBuffer must be a valid CommandBuffer handle

• event must be a valid Event handle
• stageMask must be a valid combination of PipelineStageFlagBits values
• stageMask must not be 0
• 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
• 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 Levels	Render Pass Scope	Supported Queue Types	Pipeline Type
Primary Secondary	Outside	Graphics Compute

See Also

CommandBuffer, Event, PipelineStageFlags

cmdWaitEvents :: forall a io. (PokeChain a, MonadIO io) => CommandBuffer -> ("events" ::: Vector Event) -> ("srcStageMask" ::: PipelineStageFlags) -> ("dstStageMask" ::: PipelineStageFlags) -> ("memoryBarriers" ::: Vector MemoryBarrier) -> ("bufferMemoryBarriers" ::: Vector BufferMemoryBarrier) -> ("imageMemoryBarriers" ::: Vector (ImageMemoryBarrier a)) -> io ()

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

Parameters

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

• eventCount is the length of the pEvents array.
• pEvents is a pointer to an array of event object handles to wait on.
• srcStageMask is a bitmask of PipelineStageFlagBits specifying the source stage mask.
• dstStageMask is a bitmask of PipelineStageFlagBits specifying the destination stage mask.
• memoryBarrierCount is the length of the pMemoryBarriers array.
• pMemoryBarriers is a pointer to an array of MemoryBarrier structures.
• bufferMemoryBarrierCount is the length of the pBufferMemoryBarriers array.
• pBufferMemoryBarriers is a pointer to an array of BufferMemoryBarrier structures.
• imageMemoryBarrierCount is the length of the pImageMemoryBarriers array.
• pImageMemoryBarriers is a pointer to an array of ImageMemoryBarrier structures.

Description

When cmdWaitEvents is submitted to a queue, it defines a memory dependency between prior event signal operations on the same queue or the host, and subsequent commands. cmdWaitEvents must not be used to wait on event signal operations occurring on other queues.

The first synchronization scope only includes event signal operations that operate on members of pEvents, and the operations that happened-before the event signal operations. Event signal operations performed by cmdSetEvent that occur earlier in submission order are included in the first synchronization scope, if the logically latest pipeline stage in their stageMask parameter is logically earlier than or equal to the logically latest pipeline stage in srcStageMask. Event signal operations performed by setEvent are only included in the first synchronization scope if PIPELINE_STAGE_HOST_BIT is included in srcStageMask.

The second synchronization scope includes all commands that occur later in submission order. The second synchronization scope is limited to operations on the pipeline stages determined by the destination stage mask specified by dstStageMask.

The first access scope is limited to access in the pipeline stages determined by the source stage mask specified by srcStageMask. Within that, the first access scope only includes the first access scopes defined by elements of the pMemoryBarriers, pBufferMemoryBarriers and pImageMemoryBarriers arrays, which each define a set of memory barriers. If no memory barriers are specified, then the first access scope includes no accesses.

The second access scope is limited to access in the pipeline stages determined by the destination stage mask specified by dstStageMask. Within that, the second access scope only includes the second access scopes defined by elements of the pMemoryBarriers, pBufferMemoryBarriers and pImageMemoryBarriers arrays, which each define a set of memory barriers. If no memory barriers are specified, then the second access scope includes no accesses.

Note

cmdWaitEvents is used with cmdSetEvent to define a memory dependency between two sets of action commands, roughly in the same way as pipeline barriers, but split into two commands such that work between the two may execute unhindered.

Unlike cmdPipelineBarrier, a queue family ownership transfer cannot be performed using cmdWaitEvents.

Note

Applications should be careful to avoid race conditions when using events. There is no direct ordering guarantee between a cmdResetEvent command and a cmdWaitEvents command submitted after it, so some other execution dependency must be included between these commands (e.g. a semaphore).

Valid Usage

• srcStageMask must be the bitwise OR of the stageMask parameter used in previous calls to cmdSetEvent with any of the members of pEvents and PIPELINE_STAGE_HOST_BIT if any of the members of pEvents was set using setEvent

• If the geometry shaders feature is not enabled, srcStageMask must not contain PIPELINE_STAGE_GEOMETRY_SHADER_BIT
• If the geometry shaders feature is not enabled, dstStageMask must not contain PIPELINE_STAGE_GEOMETRY_SHADER_BIT
• If the tessellation shaders feature is not enabled, srcStageMask must not contain PIPELINE_STAGE_TESSELLATION_CONTROL_SHADER_BIT or PIPELINE_STAGE_TESSELLATION_EVALUATION_SHADER_BIT
• If the tessellation shaders feature is not enabled, dstStageMask must not contain PIPELINE_STAGE_TESSELLATION_CONTROL_SHADER_BIT or PIPELINE_STAGE_TESSELLATION_EVALUATION_SHADER_BIT
• If pEvents includes one or more events that will be signaled by setEvent after commandBuffer has been submitted to a queue, then cmdWaitEvents must not be called inside a render pass instance
• Any pipeline stage included in srcStageMask or dstStageMask must be supported by the capabilities of the queue family specified by the queueFamilyIndex member of the CommandPoolCreateInfo structure that was used to create the CommandPool that commandBuffer was allocated from, as specified in the table of supported pipeline stages
• Each element of pMemoryBarriers, pBufferMemoryBarriers or pImageMemoryBarriers must not have any access flag included in its srcAccessMask member if that bit is not supported by any of the pipeline stages in srcStageMask, as specified in the table of supported access types
• Each element of pMemoryBarriers, pBufferMemoryBarriers or pImageMemoryBarriers must not have any access flag included in its dstAccessMask member if that bit is not supported by any of the pipeline stages in dstStageMask, as specified in the table of supported access types
• The srcQueueFamilyIndex and dstQueueFamilyIndex members of any element of pBufferMemoryBarriers or pImageMemoryBarriers must be equal
• commandBuffer’s current device mask must include exactly one physical device
• If the mesh shaders feature is not enabled, srcStageMask must not contain PIPELINE_STAGE_MESH_SHADER_BIT_NV
• If the task shaders feature is not enabled, srcStageMask must not contain PIPELINE_STAGE_TASK_SHADER_BIT_NV
• If the mesh shaders feature is not enabled, dstStageMask must not contain PIPELINE_STAGE_MESH_SHADER_BIT_NV
• If the task shaders feature is not enabled, dstStageMask must not contain PIPELINE_STAGE_TASK_SHADER_BIT_NV
• The srcAccessMask member of each element of pMemoryBarriers must only include access flags that are supported by one or more of the pipeline stages in srcStageMask, as specified in the table of supported access types
• The dstAccessMask member of each element of pMemoryBarriers must only include access flags that are supported by one or more of the pipeline stages in dstStageMask, as specified in the table of supported access types
• The srcAccessMask member of each element of pBufferMemoryBarriers must only include access flags that are supported by one or more of the pipeline stages in srcStageMask, as specified in the table of supported access types
• The dstAccessMask member of each element of pBufferMemoryBarriers must only include access flags that are supported by one or more of the pipeline stages in dstStageMask, as specified in the table of supported access types
• The srcAccessMask member of each element of pImageMemoryBarriers must only include access flags that are supported by one or more of the pipeline stages in srcStageMask, as specified in the table of supported access types
• The dstAccessMask member of any element of pImageMemoryBarriers must only include access flags that are supported by one or more of the pipeline stages in dstStageMask, as specified in the table of supported access types

Valid Usage (Implicit)

• commandBuffer must be a valid CommandBuffer handle

• pEvents must be a valid pointer to an array of eventCount valid Event handles
• srcStageMask must be a valid combination of PipelineStageFlagBits values
• srcStageMask must not be 0
• dstStageMask must be a valid combination of PipelineStageFlagBits values
• dstStageMask must not be 0
• 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, or compute 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 Levels	Render Pass Scope	Supported Queue Types	Pipeline Type
Primary Secondary	Both	Graphics Compute

See Also

BufferMemoryBarrier, CommandBuffer, Event, ImageMemoryBarrier, MemoryBarrier, PipelineStageFlags

cmdPipelineBarrier :: forall a io. (PokeChain a, MonadIO io) => CommandBuffer -> ("srcStageMask" ::: PipelineStageFlags) -> ("dstStageMask" ::: PipelineStageFlags) -> DependencyFlags -> ("memoryBarriers" ::: Vector MemoryBarrier) -> ("bufferMemoryBarriers" ::: Vector BufferMemoryBarrier) -> ("imageMemoryBarriers" ::: Vector (ImageMemoryBarrier a)) -> io ()

vkCmdPipelineBarrier - Insert a memory dependency

Parameters

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

• srcStageMask is a bitmask of PipelineStageFlagBits specifying the source stage mask.
• dstStageMask is a bitmask of PipelineStageFlagBits specifying the destination stage mask.
• dependencyFlags is a bitmask of DependencyFlagBits specifying how execution and memory dependencies are formed.
• memoryBarrierCount is the length of the pMemoryBarriers array.
• pMemoryBarriers is a pointer to an array of MemoryBarrier structures.
• bufferMemoryBarrierCount is the length of the pBufferMemoryBarriers array.
• pBufferMemoryBarriers is a pointer to an array of BufferMemoryBarrier structures.
• imageMemoryBarrierCount is the length of the pImageMemoryBarriers array.
• pImageMemoryBarriers is a pointer to an array of ImageMemoryBarrier structures.

Description

When cmdPipelineBarrier is submitted to a queue, it defines a memory dependency between commands that were submitted before it, and those submitted after it.

If cmdPipelineBarrier was recorded outside a render pass instance, the first synchronization scope includes all commands that occur earlier in submission order. If cmdPipelineBarrier was recorded inside a render pass instance, the first synchronization scope includes only commands that occur earlier in submission order within the same subpass. In either case, the first synchronization scope is limited to operations on the pipeline stages determined by the source stage mask specified by srcStageMask.

If cmdPipelineBarrier was recorded outside a render pass instance, the second synchronization scope includes all commands that occur later in submission order. If cmdPipelineBarrier was recorded inside a render pass instance, the second synchronization scope includes only commands that occur later in submission order within the same subpass. In either case, the second synchronization scope is limited to operations on the pipeline stages determined by the destination stage mask specified by dstStageMask.

The first access scope is limited to access in the pipeline stages determined by the source stage mask specified by srcStageMask. Within that, the first access scope only includes the first access scopes defined by elements of the pMemoryBarriers, pBufferMemoryBarriers and pImageMemoryBarriers arrays, which each define a set of memory barriers. If no memory barriers are specified, then the first access scope includes no accesses.

The second access scope is limited to access in the pipeline stages determined by the destination stage mask specified by dstStageMask. Within that, the second access scope only includes the second access scopes defined by elements of the pMemoryBarriers, pBufferMemoryBarriers and pImageMemoryBarriers arrays, which each define a set of memory barriers. If no memory barriers are specified, then the second access scope includes no accesses.

If dependencyFlags includes DEPENDENCY_BY_REGION_BIT, then any dependency between framebuffer-space pipeline stages is framebuffer-local - otherwise it is framebuffer-global.

Valid Usage

• If the geometry shaders feature is not enabled, srcStageMask must not contain PIPELINE_STAGE_GEOMETRY_SHADER_BIT

• If the geometry shaders feature is not enabled, dstStageMask must not contain PIPELINE_STAGE_GEOMETRY_SHADER_BIT
• If the tessellation shaders feature is not enabled, srcStageMask must not contain PIPELINE_STAGE_TESSELLATION_CONTROL_SHADER_BIT or PIPELINE_STAGE_TESSELLATION_EVALUATION_SHADER_BIT
• If the tessellation shaders feature is not enabled, dstStageMask must not contain PIPELINE_STAGE_TESSELLATION_CONTROL_SHADER_BIT or PIPELINE_STAGE_TESSELLATION_EVALUATION_SHADER_BIT
• If cmdPipelineBarrier is called within a render pass instance, the render pass must have been created with at least one SubpassDependency instance in RenderPassCreateInfo::pDependencies that expresses a dependency from the current subpass to itself, and for which srcStageMask contains a subset of the bit values in SubpassDependency::srcStageMask, dstStageMask contains a subset of the bit values in SubpassDependency::dstStageMask, dependencyFlags is equal to SubpassDependency::dependencyFlags, srcAccessMask member of each element of pMemoryBarriers and pImageMemoryBarriers contains a subset of the bit values in SubpassDependency::srcAccessMask, and dstAccessMask member of each element of pMemoryBarriers and pImageMemoryBarriers contains a subset of the bit values in SubpassDependency::dstAccessMask
• If cmdPipelineBarrier is called within a render pass instance, bufferMemoryBarrierCount must be 0
• If cmdPipelineBarrier is called within a render pass instance, the image member of any element of pImageMemoryBarriers must be equal to one of the elements of pAttachments that the current framebuffer was created with, that is also referred to by one of the elements of the pColorAttachments, pResolveAttachments or pDepthStencilAttachment members of the SubpassDescription instance or by the pDepthStencilResolveAttachment member of the SubpassDescriptionDepthStencilResolve structure that the current subpass was created with
• If cmdPipelineBarrier is called within a render pass instance, the oldLayout and newLayout members of any element of pImageMemoryBarriers must be equal to the layout member of an element of the pColorAttachments, pResolveAttachments or pDepthStencilAttachment members of the SubpassDescription instance or by the pDepthStencilResolveAttachment member of the SubpassDescriptionDepthStencilResolve structure that the current subpass was created with, that refers to the same image
• If cmdPipelineBarrier is called within a render pass instance, the oldLayout and newLayout members of an element of pImageMemoryBarriers must be equal
• If cmdPipelineBarrier is called within a render pass instance, the srcQueueFamilyIndex and dstQueueFamilyIndex members of any element of pImageMemoryBarriers must be QUEUE_FAMILY_IGNORED
• Any pipeline stage included in srcStageMask or dstStageMask must be supported by the capabilities of the queue family specified by the queueFamilyIndex member of the CommandPoolCreateInfo structure that was used to create the CommandPool that commandBuffer was allocated from, as specified in the table of supported pipeline stages
• If cmdPipelineBarrier is called outside of a render pass instance, dependencyFlags must not include DEPENDENCY_VIEW_LOCAL_BIT
• If the mesh shaders feature is not enabled, srcStageMask must not contain PIPELINE_STAGE_MESH_SHADER_BIT_NV
• If the task shaders feature is not enabled, srcStageMask must not contain PIPELINE_STAGE_TASK_SHADER_BIT_NV
• If the mesh shaders feature is not enabled, dstStageMask must not contain PIPELINE_STAGE_MESH_SHADER_BIT_NV
• If the task shaders feature is not enabled, dstStageMask must not contain PIPELINE_STAGE_TASK_SHADER_BIT_NV
• The srcAccessMask member of each element of pMemoryBarriers must only include access flags that are supported by one or more of the pipeline stages in srcStageMask, as specified in the table of supported access types
• The dstAccessMask member of each element of pMemoryBarriers must only include access flags that are supported by one or more of the pipeline stages in dstStageMask, as specified in the table of supported access types
• For any element of pBufferMemoryBarriers, if its srcQueueFamilyIndex and dstQueueFamilyIndex members are equal, or if its srcQueueFamilyIndex is the queue family index that was used to create the command pool that commandBuffer was allocated from, then its srcAccessMask member must only contain access flags that are supported by one or more of the pipeline stages in srcStageMask, as specified in the table of supported access types
• For any element of pBufferMemoryBarriers, if its srcQueueFamilyIndex and dstQueueFamilyIndex members are equal, or if its dstQueueFamilyIndex is the queue family index that was used to create the command pool that commandBuffer was allocated from, then its dstAccessMask member must only contain access flags that are supported by one or more of the pipeline stages in dstStageMask, as specified in the table of supported access types
• For any element of pImageMemoryBarriers, if its srcQueueFamilyIndex and dstQueueFamilyIndex members are equal, or if its srcQueueFamilyIndex is the queue family index that was used to create the command pool that commandBuffer was allocated from, then its srcAccessMask member must only contain access flags that are supported by one or more of the pipeline stages in srcStageMask, as specified in the table of supported access types
• For any element of pImageMemoryBarriers, if its srcQueueFamilyIndex and dstQueueFamilyIndex members are equal, or if its dstQueueFamilyIndex is the queue family index that was used to create the command pool that commandBuffer was allocated from, then its dstAccessMask member must only contain access flags that are supported by one or more of the pipeline stages in dstStageMask, as specified in the table of supported access types

Valid Usage (Implicit)

• commandBuffer must be a valid CommandBuffer handle

• srcStageMask must be a valid combination of PipelineStageFlagBits values
• srcStageMask must not be 0
• dstStageMask must be a valid combination of PipelineStageFlagBits values
• dstStageMask must not be 0
• 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, or compute 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 Levels	Render Pass Scope	Supported Queue Types	Pipeline Type
Primary Secondary	Both	Transfer Graphics Compute

See Also

BufferMemoryBarrier, CommandBuffer, DependencyFlags, ImageMemoryBarrier, MemoryBarrier, PipelineStageFlags

cmdBeginQuery :: forall io. MonadIO io => CommandBuffer -> QueryPool -> ("query" ::: Word32) -> QueryControlFlags -> io ()

vkCmdBeginQuery - Begin a query

Parameters

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

• queryPool is the query pool that will manage the results of the query.
• query is the query index within the query pool that will contain the results.
• flags is a bitmask of QueryControlFlagBits specifying constraints on the types of queries that can be performed.

Description

If the queryType of the pool is QUERY_TYPE_OCCLUSION and flags contains QUERY_CONTROL_PRECISE_BIT, an implementation must return a result that matches the actual number of samples passed. This is described in more detail in Occlusion Queries.

Calling cmdBeginQuery is equivalent to calling cmdBeginQueryIndexedEXT with the index parameter set to zero.

After beginning a query, that query is considered active within the command buffer it was called in until that same query is ended. Queries active in a primary command buffer when secondary command buffers are executed are considered active for those secondary command buffers.

Valid Usage

• queryPool must have been created with a queryType that differs from that of any queries that are active within commandBuffer

• All queries used by the command must be unavailable
• The queryType used to create queryPool must not be QUERY_TYPE_TIMESTAMP
• If the precise occlusion queries feature is not enabled, or the queryType used to create queryPool was not QUERY_TYPE_OCCLUSION, flags must not contain QUERY_CONTROL_PRECISE_BIT
• query must be less than the number of queries in queryPool
• If the queryType used to create queryPool was QUERY_TYPE_OCCLUSION, the CommandPool that commandBuffer was allocated from must support graphics operations
• If the queryType used to create queryPool was QUERY_TYPE_PIPELINE_STATISTICS and any of the pipelineStatistics indicate graphics operations, the CommandPool that commandBuffer was allocated from must support graphics operations
• If the queryType used to create queryPool was QUERY_TYPE_PIPELINE_STATISTICS and any of the pipelineStatistics indicate compute operations, the CommandPool that commandBuffer was allocated from must support compute operations
• commandBuffer must not be a protected command buffer
• If called within a render pass instance, the sum of query and the number of bits set in the current subpass’s view mask must be less than or equal to the number of queries in queryPool
• If the queryType used to create queryPool was QUERY_TYPE_TRANSFORM_FEEDBACK_STREAM_EXT the CommandPool that commandBuffer was allocated from must support graphics operations
• If the queryType used to create queryPool was QUERY_TYPE_TRANSFORM_FEEDBACK_STREAM_EXT then PhysicalDeviceTransformFeedbackPropertiesEXT::transformFeedbackQueries must be supported
• If queryPool was created with a queryType of QUERY_TYPE_PERFORMANCE_QUERY_KHR, the profiling lock must have been held before beginCommandBuffer was called on commandBuffer
• If queryPool was created with a queryType of QUERY_TYPE_PERFORMANCE_QUERY_KHR and one of the counters used to create queryPool was PERFORMANCE_COUNTER_SCOPE_COMMAND_BUFFER_KHR, the query begin must be the first recorded command in commandBuffer
• If queryPool was created with a queryType of QUERY_TYPE_PERFORMANCE_QUERY_KHR and one of the counters used to create queryPool was PERFORMANCE_COUNTER_SCOPE_RENDER_PASS_KHR, the begin command must not be recorded within a render pass instance
• If queryPool was created with a queryType of QUERY_TYPE_PERFORMANCE_QUERY_KHR and another query pool with a queryType QUERY_TYPE_PERFORMANCE_QUERY_KHR has been used within commandBuffer, its parent primary command buffer or secondary command buffer recorded within the same parent primary command buffer as commandBuffer, the performanceCounterMultipleQueryPools feature must be enabled
• If queryPool was created with a queryType of 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 a cmdResetQueryPool command affecting the same query

Valid Usage (Implicit)

• commandBuffer must be a valid CommandBuffer handle

• 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, or compute 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 Levels	Render Pass Scope	Supported Queue Types	Pipeline Type
Primary Secondary	Both	Graphics Compute

See Also

CommandBuffer, QueryControlFlags, QueryPool

cmdWithQuery :: forall io r. MonadIO io => (io () -> io () -> r) -> CommandBuffer -> QueryPool -> Word32 -> QueryControlFlags -> r

A convenience wrapper to make a compatible pair of calls to cmdBeginQuery and cmdEndQuery

To ensure that cmdEndQuery is always called: pass bracket_ (or the allocate function from your favourite resource management library) as the first argument. To just extract the pair pass '(,)' as the first argument.

Note that there is no inner resource

cmdEndQuery :: forall io. MonadIO io => CommandBuffer -> QueryPool -> ("query" ::: Word32) -> io ()

vkCmdEndQuery - Ends a query

Parameters

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

• queryPool is the query pool that is managing the results of the query.
• query is the query index within the query pool where the result is stored.

Description

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

As queries operate asynchronously, ending a query does not immediately set the query’s status to available. A query is considered finished when the final results of the query are ready to be retrieved by getQueryPoolResults and cmdCopyQueryPoolResults, and this is when the query’s status is set to available.

Once a query is ended the query must finish in finite time, unless the state of the query is changed using other commands, e.g. by issuing a reset of the query.

Valid Usage

• All queries used by the command must be active

• query must be less than the number of queries 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

Valid Usage (Implicit)

• commandBuffer must be a valid CommandBuffer handle

• queryPool must be a valid QueryPool handle
• commandBuffer must be in the recording state
• The CommandPool that commandBuffer was allocated from must support graphics, or compute operations
• Both of commandBuffer, and 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 Levels	Render Pass Scope	Supported Queue Types	Pipeline Type
Primary Secondary	Both	Graphics Compute

See Also

CommandBuffer, QueryPool

cmdResetQueryPool :: forall io. MonadIO io => CommandBuffer -> QueryPool -> ("firstQuery" ::: Word32) -> ("queryCount" ::: Word32) -> io ()

vkCmdResetQueryPool - Reset queries in a query pool

Parameters

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

• queryPool is the handle of the query pool managing the queries being reset.
• firstQuery is the initial query index to reset.
• queryCount is the number of queries to reset.

Description

When executed on a queue, this command sets the status of query indices [firstQuery, firstQuery + queryCount - 1] to unavailable.

If the queryType used to create queryPool was QUERY_TYPE_PERFORMANCE_QUERY_KHR, this command sets the status of query indices [firstQuery, firstQuery + queryCount - 1] to unavailable for each pass of queryPool, as indicated by a call to getPhysicalDeviceQueueFamilyPerformanceQueryPassesKHR.

Note

Because cmdResetQueryPool resets all the passes of the indicated queries, applications must not record a cmdResetQueryPool command for a queryPool created with QUERY_TYPE_PERFORMANCE_QUERY_KHR in a command buffer that needs to be submitted multiple times as indicated by a call to getPhysicalDeviceQueueFamilyPerformanceQueryPassesKHR. Otherwise applications will never be able to complete the recorded queries.

Valid Usage

• firstQuery must be less than the number of queries 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)

• commandBuffer must be a valid CommandBuffer handle

• queryPool must be a valid QueryPool 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 render pass instance
• 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 Levels	Render Pass Scope	Supported Queue Types	Pipeline Type
Primary Secondary	Outside	Graphics Compute

See Also

CommandBuffer, QueryPool

cmdWriteTimestamp :: forall io. MonadIO io => CommandBuffer -> PipelineStageFlagBits -> QueryPool -> ("query" ::: Word32) -> io ()

vkCmdWriteTimestamp - Write a device timestamp into a query object

Parameters

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

• pipelineStage is one of the PipelineStageFlagBits, specifying a stage of the pipeline.
• queryPool is the query pool that will manage the timestamp.
• query is the query within the query pool that will contain the timestamp.

Description

cmdWriteTimestamp latches the value of the timer when all previous commands have completed executing as far as the specified pipeline stage, and writes the timestamp value to memory. When the timestamp value is written, the availability status of the query is set to available.

Note

If an implementation is unable to detect completion and latch the timer at any specific stage of the pipeline, it may instead do so at any logically later stage.

cmdCopyQueryPoolResults can then be called to copy the timestamp value from the query pool into buffer memory, with ordering and synchronization behavior equivalent to how other queries operate. Timestamp values can also be retrieved from the query pool using getQueryPoolResults. As with other queries, the query must be reset using cmdResetQueryPool or resetQueryPool before requesting the timestamp value be written to it.

While cmdWriteTimestamp can be called inside or outside of a render pass instance, cmdCopyQueryPoolResults must only be called outside of a render pass instance.

Timestamps may only be meaningfully compared if they are written by commands submitted to the same queue.

Note

An example of such a comparison is determining the execution time of a sequence of commands.

If cmdWriteTimestamp is called while executing a render pass instance that has multiview enabled, the timestamp uses N consecutive query indices in the query pool (starting at query) where N is the number of bits set in the view mask of the subpass the command is executed in. The resulting query values are determined by an implementation-dependent choice of one of the following behaviors:

• The first query is a timestamp value and (if more than one bit is set in the view mask) zero is written to the remaining queries. If two timestamps are written in the same subpass, the sum of the execution time of all views between those commands is the difference between the first query written by each command.
• All N queries are timestamp values. If two timestamps are written in the same subpass, the sum of the execution time of all views between those commands is the sum of the difference between corresponding queries written by each command. The difference between corresponding queries may be the execution time of a single view.

In either case, the application can sum the differences between all N queries to determine the total execution time.

Valid Usage

• queryPool must have been created with a queryType of QUERY_TYPE_TIMESTAMP

• The query identified by queryPool and query must be unavailable
• The command pool’s queue family must support a non-zero timestampValidBits
• All queries used by the command must be unavailable
• If cmdWriteTimestamp is called within a render pass instance, the sum 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

Valid Usage (Implicit)

• commandBuffer must be a valid CommandBuffer handle

• 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, or compute 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 Levels	Render Pass Scope	Supported Queue Types	Pipeline Type
Primary Secondary	Both	Transfer Graphics Compute	Transfer

See Also

CommandBuffer, PipelineStageFlagBits, QueryPool

cmdCopyQueryPoolResults :: forall io. MonadIO io => CommandBuffer -> QueryPool -> ("firstQuery" ::: Word32) -> ("queryCount" ::: Word32) -> ("dstBuffer" ::: Buffer) -> ("dstOffset" ::: DeviceSize) -> ("stride" ::: DeviceSize) -> QueryResultFlags -> io ()

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

Parameters

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

• queryPool is the query pool managing the queries containing the desired results.
• firstQuery is the initial query index.
• queryCount is the number of queries. firstQuery and queryCount together define a range of queries.
• dstBuffer is a Buffer object that will receive the results of the copy command.
• dstOffset is an offset into dstBuffer.
• 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.
• flags is a bitmask of QueryResultFlagBits specifying how and when results are returned.

Description

cmdCopyQueryPoolResults is guaranteed to see the effect of previous uses of cmdResetQueryPool in the same queue, without any additional synchronization. Thus, the results will always reflect the most recent use of the query.

flags has the same possible values described above for the flags parameter of getQueryPoolResults, but the different style of execution causes some subtle behavioral differences. Because cmdCopyQueryPoolResults executes in order with respect to other query commands, there is less ambiguity about which use of a query is being requested.

Results for all requested occlusion queries, pipeline statistics queries, transform feedback queries, and timestamp queries are written as 64-bit unsigned integer values if QUERY_RESULT_64_BIT is set or 32-bit unsigned integer values otherwise. Performance queries store results in a tightly packed array whose type is determined by the unit member of the corresponding PerformanceCounterKHR.

If neither of QUERY_RESULT_WAIT_BIT and QUERY_RESULT_WITH_AVAILABILITY_BIT are set, results are only written out for queries in the available state.

If QUERY_RESULT_WAIT_BIT is set, the implementation will wait for each query’s status to be in the available state before retrieving the numerical results for that query. This is guaranteed to reflect the most recent use of the query on the same queue, assuming that the query is not being simultaneously used by other queues. If the query does not become available in a finite amount of time (e.g. due to not issuing a query since the last reset), a ERROR_DEVICE_LOST error may occur.

Similarly, if QUERY_RESULT_WITH_AVAILABILITY_BIT is set and QUERY_RESULT_WAIT_BIT is not set, the availability is guaranteed to reflect the most recent use of the query on the same queue, assuming that the query is not being simultaneously used by other queues. As with getQueryPoolResults, implementations must guarantee that if they return a non-zero availability value, then the numerical results are valid.

If QUERY_RESULT_PARTIAL_BIT is set, QUERY_RESULT_WAIT_BIT is not set, and the query’s status is unavailable, an intermediate result value between zero and the final result value is written for that query.

QUERY_RESULT_PARTIAL_BIT must not be used if the pool’s queryType is QUERY_TYPE_TIMESTAMP.

cmdCopyQueryPoolResults is considered to be a transfer operation, and its writes to buffer memory must be synchronized using PIPELINE_STAGE_TRANSFER_BIT and ACCESS_TRANSFER_WRITE_BIT before using the results.

Valid Usage

• dstOffset must be less than the size of dstBuffer

• 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
• If QUERY_RESULT_64_BIT is not set in flags then dstOffset and stride must be multiples of 4
• If QUERY_RESULT_64_BIT is set in flags then dstOffset and stride must be multiples of 8
• dstBuffer must have enough storage, from dstOffset, to contain the result of each query, as described here
• dstBuffer must have been created with BUFFER_USAGE_TRANSFER_DST_BIT usage flag
• If dstBuffer is non-sparse then it must be bound completely and contiguously to a single DeviceMemory object
• If the queryType used to create queryPool was QUERY_TYPE_TIMESTAMP, flags must not contain QUERY_RESULT_PARTIAL_BIT
• If the queryType used to create queryPool was QUERY_TYPE_PERFORMANCE_QUERY_KHR, PhysicalDevicePerformanceQueryPropertiesKHR::allowCommandBufferQueryCopies must be TRUE
• If the queryType used to create queryPool was QUERY_TYPE_PERFORMANCE_QUERY_KHR, flags must not contain QUERY_RESULT_WITH_AVAILABILITY_BIT, QUERY_RESULT_PARTIAL_BIT or QUERY_RESULT_64_BIT
• If the queryType used to create queryPool was QUERY_TYPE_PERFORMANCE_QUERY_KHR, the queryPool must have been submitted once for each pass as retrieved via a call to getPhysicalDeviceQueueFamilyPerformanceQueryPassesKHR
• cmdCopyQueryPoolResults must not be called if the queryType used to create queryPool was QUERY_TYPE_PERFORMANCE_QUERY_INTEL

Valid Usage (Implicit)

• commandBuffer must be a valid CommandBuffer handle

• 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
• 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 Levels	Render Pass Scope	Supported Queue Types	Pipeline Type
Primary Secondary	Outside	Graphics Compute	Transfer

See Also

Buffer, CommandBuffer, DeviceSize, QueryPool, QueryResultFlags

cmdPushConstants :: forall io. MonadIO io => CommandBuffer -> PipelineLayout -> ShaderStageFlags -> ("offset" ::: Word32) -> ("size" ::: Word32) -> ("values" ::: Ptr ()) -> io ()

vkCmdPushConstants - Update the values of push constants

Parameters

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

• layout is the pipeline layout used to program the push constant updates.
• stageFlags is a bitmask of ShaderStageFlagBits specifying the shader stages that will use the push constants in the updated range.
• offset is the start offset of the push constant range to update, in units of bytes.
• size is the size of the push constant range to update, in units of bytes.
• pValues is a pointer to an array of size bytes containing the new push constant values.

Description

Note

As stageFlags needs to include all flags the relevant push constant ranges were created with, any flags that are not supported by the queue family that the CommandPool used to allocate commandBuffer was created on are ignored.

Valid Usage

• For each byte in the range specified by offset 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)

• commandBuffer must be a valid CommandBuffer handle

• 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
• 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 Levels	Render Pass Scope	Supported Queue Types	Pipeline Type
Primary Secondary	Both	Graphics Compute

See Also

CommandBuffer, PipelineLayout, ShaderStageFlags

cmdBeginRenderPass :: forall a io. (PokeChain a, MonadIO io) => CommandBuffer -> RenderPassBeginInfo a -> SubpassContents -> io ()

vkCmdBeginRenderPass - Begin a new render pass

Parameters

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

• pRenderPassBegin is a pointer to a RenderPassBeginInfo structure specifying the render pass to begin an instance of, and the framebuffer the instance uses.
• contents is a SubpassContents value specifying how the commands in the first subpass will be provided.

Description

After beginning a render pass instance, the command buffer is ready to record the commands for the first subpass of that render pass.

Valid Usage

• If any of the initialLayout or finalLayout member of the AttachmentDescription structures or the layout member of the AttachmentReference structures specified when creating the render pass specified in the renderPass member of pRenderPassBegin is IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL then the corresponding attachment image view of the framebuffer specified in the framebuffer member of pRenderPassBegin must have been created with a usage value including IMAGE_USAGE_COLOR_ATTACHMENT_BIT

• If any of the initialLayout or finalLayout member of the AttachmentDescription structures or the layout member of the AttachmentReference structures specified when creating the render pass specified in the renderPass member of pRenderPassBegin is IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL, IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL, IMAGE_LAYOUT_DEPTH_STENCIL_ATTACHMENT_OPTIMAL, or IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL then the corresponding attachment image view of the framebuffer specified in the framebuffer member of pRenderPassBegin must have been created with a usage value including IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT
• If any of the initialLayout or finalLayout member of the AttachmentDescription structures or the layout member of the AttachmentReference structures specified when creating the render pass specified in the renderPass member of pRenderPassBegin is IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL, or IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL, IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL, or IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL then the corresponding attachment image view of the framebuffer specified in the framebuffer member of pRenderPassBegin must have been created with a usage value including IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT
• If any of the stencilInitialLayout or stencilFinalLayout member of the AttachmentDescriptionStencilLayout structures or the stencilLayout member of the AttachmentReferenceStencilLayout structures specified when creating the render pass specified in the renderPass member of pRenderPassBegin is IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL, or IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL then the corresponding attachment image view of the framebuffer specified in the framebuffer member of pRenderPassBegin must have been created with a usage value including IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT
• If any of the initialLayout or finalLayout member of the AttachmentDescription structures or the layout member of the AttachmentReference structures specified when creating the render pass specified in the renderPass member of pRenderPassBegin is IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL then the corresponding attachment image view of the framebuffer specified in the framebuffer member of pRenderPassBegin must have been created with a usage value including IMAGE_USAGE_SAMPLED_BIT or IMAGE_USAGE_INPUT_ATTACHMENT_BIT
• If any of the initialLayout or finalLayout member of the AttachmentDescription structures or the layout member of the AttachmentReference structures specified when creating the render pass specified in the renderPass member of pRenderPassBegin is IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL then the corresponding attachment image view of the framebuffer specified in the framebuffer member of pRenderPassBegin must have been created with a usage value including IMAGE_USAGE_TRANSFER_SRC_BIT
• If any of the initialLayout or finalLayout member of the AttachmentDescription structures or the layout member of the AttachmentReference structures specified when creating the render pass specified in the renderPass member of pRenderPassBegin is IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL then the corresponding attachment image view of the framebuffer specified in the framebuffer member of pRenderPassBegin must have been created with a usage value including IMAGE_USAGE_TRANSFER_DST_BIT
• If any of the initialLayout members of the AttachmentDescription structures specified when creating the render pass specified in the renderPass member of pRenderPassBegin is not IMAGE_LAYOUT_UNDEFINED, then each such initialLayout must be equal to the current layout of the corresponding attachment image subresource of the framebuffer specified in the framebuffer member of pRenderPassBegin
• The srcStageMask and dstStageMask members of any element of the pDependencies member of RenderPassCreateInfo used to create renderPass must be supported by the capabilities of the queue family identified by the queueFamilyIndex member of the CommandPoolCreateInfo used to create the command pool which commandBuffer was allocated from
• For any attachment in framebuffer that is used by renderPass and is bound to memory locations that are also bound to another attachment used by renderPass, and if at least one of those uses causes either attachment to be written to, both attachments must have had the ATTACHMENT_DESCRIPTION_MAY_ALIAS_BIT set

Valid Usage (Implicit)

• commandBuffer must be a valid CommandBuffer handle

• 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
• 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 Levels	Render Pass Scope	Supported Queue Types	Pipeline Type
Primary	Outside	Graphics	Graphics

See Also

CommandBuffer, RenderPassBeginInfo, SubpassContents

cmdWithRenderPass :: forall a io r. (PokeChain a, MonadIO io) => (io () -> io () -> r) -> CommandBuffer -> RenderPassBeginInfo a -> SubpassContents -> r

A convenience wrapper to make a compatible pair of calls to cmdBeginRenderPass and cmdEndRenderPass

To ensure that cmdEndRenderPass is always called: pass bracket_ (or the allocate function from your favourite resource management library) as the first argument. To just extract the pair pass '(,)' as the first argument.

Note that there is no inner resource

cmdNextSubpass :: forall io. MonadIO io => CommandBuffer -> SubpassContents -> io ()

vkCmdNextSubpass - Transition to the next subpass of a render pass

Parameters

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

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

Description

The subpass index for a render pass begins at zero when cmdBeginRenderPass is recorded, and increments each time cmdNextSubpass is recorded.

Moving to the next subpass automatically performs any multisample resolve operations in the subpass being ended. End-of-subpass multisample resolves are treated as color attachment writes for the purposes of synchronization. This applies to resolve operations for both color and depth/stencil attachments. That is, they are considered to execute in the PIPELINE_STAGE_COLOR_ATTACHMENT_OUTPUT_BIT pipeline stage and their writes are synchronized with ACCESS_COLOR_ATTACHMENT_WRITE_BIT. Synchronization between rendering within a subpass and any resolve operations at the end of the subpass occurs automatically, without need for explicit dependencies or pipeline barriers. However, if the resolve attachment is also used in a different subpass, an explicit dependency is needed.

After transitioning to the next subpass, the application can record the commands for that subpass.

Valid Usage

• The current subpass index must be less than the number of subpasses in the render pass minus one

• This command must not be recorded when transform feedback is active

Valid Usage (Implicit)

• commandBuffer must be a valid CommandBuffer handle

• 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
• 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 Levels	Render Pass Scope	Supported Queue Types	Pipeline Type
Primary	Inside	Graphics	Graphics

See Also

CommandBuffer, SubpassContents

cmdEndRenderPass :: forall io. MonadIO io => CommandBuffer -> io ()

vkCmdEndRenderPass - End the current render pass

Parameters

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

Description

Ending a render pass instance performs any multisample resolve operations on the final subpass.

Valid Usage

• The current subpass index must be equal to the number of subpasses in the render pass minus one

• This command must not be recorded when transform feedback is active

Valid Usage (Implicit)

• commandBuffer must be a valid CommandBuffer handle

• commandBuffer must be in the recording state
• The CommandPool that commandBuffer was allocated from must support graphics operations
• This command must only be called inside of a render pass instance
• 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 Levels	Render Pass Scope	Supported Queue Types	Pipeline Type
Primary	Inside	Graphics	Graphics

See Also

CommandBuffer

cmdExecuteCommands :: forall io. MonadIO io => CommandBuffer -> ("commandBuffers" ::: Vector CommandBuffer) -> io ()

vkCmdExecuteCommands - Execute a secondary command buffer from a primary command buffer

Parameters

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

• commandBufferCount is the length of the pCommandBuffers array.
• 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.

Description

If any element of pCommandBuffers was not recorded with the COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT flag, and it was recorded into any other primary command buffer which is currently in the executable or recording state, that primary command buffer becomes invalid.

Valid Usage

• Each element of pCommandBuffers must have been allocated with a level of COMMAND_BUFFER_LEVEL_SECONDARY

• Each element of pCommandBuffers must be in the pending or executable state
• If any element of pCommandBuffers was not recorded with the COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT flag, it must not be in the pending state
• If any element of pCommandBuffers was not recorded with the COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT flag, it must not have already been recorded to commandBuffer
• If any element of pCommandBuffers was not recorded with the COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT flag, it must not appear more than once in pCommandBuffers
• Each element of pCommandBuffers must have been allocated from a CommandPool that was created for the same queue family as the CommandPool from which commandBuffer was allocated
• If cmdExecuteCommands is being called within a render pass instance, that render pass instance must have been begun with the contents parameter of cmdBeginRenderPass set to SUBPASS_CONTENTS_SECONDARY_COMMAND_BUFFERS
• If cmdExecuteCommands is being called within a render pass instance, each element of pCommandBuffers must have been recorded with the COMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT
• If cmdExecuteCommands is being called within a render pass instance, each element of pCommandBuffers must have been recorded with CommandBufferInheritanceInfo::subpass set to the index of the subpass which the given command buffer will be executed in
• If cmdExecuteCommands is being called within a render pass instance, the render passes specified in the pBeginInfo->pInheritanceInfo->renderPass members of the beginCommandBuffer commands used to begin recording each element of pCommandBuffers must be compatible with the current render pass
• If cmdExecuteCommands is being called within a render pass instance, and any element of pCommandBuffers was recorded with CommandBufferInheritanceInfo::framebuffer not equal to NULL_HANDLE, that Framebuffer must match the Framebuffer used in the current render pass instance
• If cmdExecuteCommands is being called within a render pass instance that included RenderPassTransformBeginInfoQCOM in the pNext chain of RenderPassBeginInfo, then each element of pCommandBuffers must have been recorded with CommandBufferInheritanceRenderPassTransformInfoQCOM in the pNext chain of CommandBufferBeginInfo
• If cmdExecuteCommands is being called within a render pass instance that included RenderPassTransformBeginInfoQCOM in the pNext chain of RenderPassBeginInfo, then each element of pCommandBuffers must have been recorded with CommandBufferInheritanceRenderPassTransformInfoQCOM::transform identical to RenderPassTransformBeginInfoQCOM::transform
• If cmdExecuteCommands is being called within a render pass instance that included RenderPassTransformBeginInfoQCOM in the pNext chain of RenderPassBeginInfo, then each element of pCommandBuffers must have been recorded with CommandBufferInheritanceRenderPassTransformInfoQCOM::renderArea identical to RenderPassBeginInfo::renderArea
• If cmdExecuteCommands is not being called within a render pass instance, each element of pCommandBuffers must not have been recorded with the COMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT
• If the inherited queries feature is not enabled, commandBuffer must not have any queries active
• If commandBuffer has a QUERY_TYPE_OCCLUSION query active, then each element of pCommandBuffers must have been recorded with CommandBufferInheritanceInfo::occlusionQueryEnable set to TRUE
• If commandBuffer has a QUERY_TYPE_OCCLUSION query active, then each element of pCommandBuffers must have been recorded with CommandBufferInheritanceInfo::queryFlags having all bits set that are set for the query
• If commandBuffer has a QUERY_TYPE_PIPELINE_STATISTICS query active, then each element of pCommandBuffers must have been recorded with CommandBufferInheritanceInfo::pipelineStatistics having all bits set that are set in the QueryPool the query uses
• Each element of pCommandBuffers must not begin any query types that are active in commandBuffer
• If commandBuffer is a protected command buffer, then each element of pCommandBuffers must be a protected command buffer
• If commandBuffer is an unprotected command buffer, then each element of pCommandBuffers must be an unprotected command buffer
• This command must not be recorded when transform feedback is active

Valid Usage (Implicit)

• commandBuffer must be a valid CommandBuffer handle

• 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
• commandBuffer must be a primary CommandBuffer
• 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 Levels	Render Pass Scope	Supported Queue Types	Pipeline Type
Primary	Both	Transfer Graphics Compute

See Also

CommandBuffer

data Viewport

VkViewport - Structure specifying a viewport

Description

The framebuffer depth coordinate zf may be represented using either a fixed-point or floating-point representation. However, a floating-point representation must be used if the depth/stencil attachment has a floating-point depth component. If an m-bit fixed-point representation is used, we assume that it represents each value \(\frac{k}{2^m - 1}\), where k ∈ { 0, 1, …​, 2m-1 }, as k (e.g. 1.0 is represented in binary as a string of all ones).

The viewport parameters shown in the above equations are found from these values as

• ox = x + width / 2
• oy = y + height / 2
• oz = minDepth
• px = width
• py = height
• pz = maxDepth - minDepth.

If a render pass transform is enabled, the values (px,py) and (ox, oy) defining the viewport are transformed as described in render pass transform before participating in the viewport transform.

The application can specify a negative term for height, which has the effect of negating the y coordinate in clip space before performing the transform. When using a negative height, the application should also adjust the y value to point to the lower left corner of the viewport instead of the upper left corner. Using the negative height allows the application to avoid having to negate the y component of the Position output from the last vertex processing stage in shaders that also target other graphics APIs.

The width and height of the implementation-dependent maximum viewport dimensions must be greater than or equal to the width and height of the largest image which can be created and attached to a framebuffer.

The floating-point viewport bounds are represented with an implementation-dependent precision.

Valid Usage

• width must be greater than 0.0

• width must be less than or equal to PhysicalDeviceLimits::maxViewportDimensions[0]
• The absolute value of height must be less than or equal to PhysicalDeviceLimits::maxViewportDimensions[1]
• x must be greater than or equal to viewportBoundsRange[0]
• (x + width) must be less than or equal to viewportBoundsRange[1]
• y must be greater than or equal to viewportBoundsRange[0]
• y must be less than or equal to viewportBoundsRange[1]
• (y + height) must be greater than or equal to viewportBoundsRange[0]
• (y + height) must be less than or equal to viewportBoundsRange[1]
• Unless VK_EXT_depth_range_unrestricted extension is enabled minDepth must be between 0.0 and 1.0, inclusive
• Unless VK_EXT_depth_range_unrestricted extension is enabled maxDepth must be between 0.0 and 1.0, inclusive

See Also

PipelineViewportStateCreateInfo, cmdSetViewport

Constructors

Viewport

Fields

• x :: Float

  x and y are the viewport’s upper left corner (x,y).

• y :: Float
• width :: Float

  width and height are the viewport’s width and height, respectively.

• height :: Float
• minDepth :: Float

  minDepth and maxDepth are the depth range for the viewport. It is valid for minDepth to be greater than or equal to maxDepth.

• maxDepth :: Float

Instances

Show Viewport

Defined in Graphics.Vulkan.Core10.CommandBufferBuilding

Methods

showsPrec :: Int -> Viewport -> ShowS

show :: Viewport -> String

showList :: [Viewport] -> ShowS

Storable Viewport

Defined in Graphics.Vulkan.Core10.CommandBufferBuilding

Methods

sizeOf :: Viewport -> Int

alignment :: Viewport -> Int

peekElemOff :: Ptr Viewport -> Int -> IO Viewport

pokeElemOff :: Ptr Viewport -> Int -> Viewport -> IO ()

peekByteOff :: Ptr b -> Int -> IO Viewport

pokeByteOff :: Ptr b -> Int -> Viewport -> IO ()

peek :: Ptr Viewport -> IO Viewport

poke :: Ptr Viewport -> Viewport -> IO ()

FromCStruct Viewport

Defined in Graphics.Vulkan.Core10.CommandBufferBuilding

Methods

peekCStruct :: Ptr Viewport -> IO Viewport

ToCStruct Viewport

Defined in Graphics.Vulkan.Core10.CommandBufferBuilding

Methods

withCStruct :: Viewport -> (Ptr Viewport -> IO b) -> IO b

pokeCStruct :: Ptr Viewport -> Viewport -> IO b -> IO b

withZeroCStruct :: (Ptr Viewport -> IO b) -> IO b

pokeZeroCStruct :: Ptr Viewport -> IO b -> IO b

cStructSize :: Int

cStructAlignment :: Int

Zero Viewport

Defined in Graphics.Vulkan.Core10.CommandBufferBuilding

Methods

zero :: Viewport

data Rect2D

VkRect2D - Structure specifying a two-dimensional subregion

See Also

BindImageMemoryDeviceGroupInfo, ClearRect, CommandBufferInheritanceRenderPassTransformInfoQCOM, DeviceGroupRenderPassBeginInfo, DisplayPresentInfoKHR, Extent2D, Offset2D, PipelineDiscardRectangleStateCreateInfoEXT, PipelineViewportExclusiveScissorStateCreateInfoNV, PipelineViewportStateCreateInfo, RenderPassBeginInfo, cmdSetDiscardRectangleEXT, cmdSetExclusiveScissorNV, cmdSetScissor, getPhysicalDevicePresentRectanglesKHR

Constructors

Rect2D

Fields

• offset :: Offset2D

  offset is a Offset2D specifying the rectangle offset.

• extent :: Extent2D

  extent is a Extent2D specifying the rectangle extent.

Instances

Show Rect2D

Defined in Graphics.Vulkan.Core10.CommandBufferBuilding

Methods

showsPrec :: Int -> Rect2D -> ShowS

show :: Rect2D -> String

showList :: [Rect2D] -> ShowS

FromCStruct Rect2D

Defined in Graphics.Vulkan.Core10.CommandBufferBuilding

Methods

peekCStruct :: Ptr Rect2D -> IO Rect2D

ToCStruct Rect2D

Defined in Graphics.Vulkan.Core10.CommandBufferBuilding

Methods

withCStruct :: Rect2D -> (Ptr Rect2D -> IO b) -> IO b

pokeCStruct :: Ptr Rect2D -> Rect2D -> IO b -> IO b

withZeroCStruct :: (Ptr Rect2D -> IO b) -> IO b

pokeZeroCStruct :: Ptr Rect2D -> IO b -> IO b

cStructSize :: Int

cStructAlignment :: Int

Zero Rect2D

Defined in Graphics.Vulkan.Core10.CommandBufferBuilding

Methods

zero :: Rect2D

data ClearRect

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

Rect2D, cmdClearAttachments

Constructors

ClearRect

Fields

• rect :: Rect2D

  rect is the two-dimensional region to be cleared.

• baseArrayLayer :: Word32

  baseArrayLayer is the first layer to be cleared.

• layerCount :: Word32

  layerCount is the number of layers to clear.

Instances

Show ClearRect

Defined in Graphics.Vulkan.Core10.CommandBufferBuilding

Methods

showsPrec :: Int -> ClearRect -> ShowS

show :: ClearRect -> String

showList :: [ClearRect] -> ShowS

FromCStruct ClearRect

Defined in Graphics.Vulkan.Core10.CommandBufferBuilding

Methods

peekCStruct :: Ptr ClearRect -> IO ClearRect

ToCStruct ClearRect

Defined in Graphics.Vulkan.Core10.CommandBufferBuilding

Methods

withCStruct :: ClearRect -> (Ptr ClearRect -> IO b) -> IO b

pokeCStruct :: Ptr ClearRect -> ClearRect -> IO b -> IO b

withZeroCStruct :: (Ptr ClearRect -> IO b) -> IO b

pokeZeroCStruct :: Ptr ClearRect -> IO b -> IO b

cStructSize :: Int

cStructAlignment :: Int

Zero ClearRect

Defined in Graphics.Vulkan.Core10.CommandBufferBuilding

Methods

zero :: ClearRect

data BufferCopy

VkBufferCopy - Structure specifying a buffer copy operation

Valid Usage

• The size must be greater than 0

See Also

DeviceSize, cmdCopyBuffer

Constructors

BufferCopy

Fields

• srcOffset :: DeviceSize

  srcOffset is the starting offset in bytes from the start of srcBuffer.

• dstOffset :: DeviceSize

  dstOffset is the starting offset in bytes from the start of dstBuffer.

• size :: DeviceSize

  size is the number of bytes to copy.

Instances

Show BufferCopy

Defined in Graphics.Vulkan.Core10.CommandBufferBuilding

Methods

showsPrec :: Int -> BufferCopy -> ShowS

show :: BufferCopy -> String

showList :: [BufferCopy] -> ShowS

Storable BufferCopy

Defined in Graphics.Vulkan.Core10.CommandBufferBuilding

Methods

sizeOf :: BufferCopy -> Int

alignment :: BufferCopy -> Int

peekElemOff :: Ptr BufferCopy -> Int -> IO BufferCopy

pokeElemOff :: Ptr BufferCopy -> Int -> BufferCopy -> IO ()

peekByteOff :: Ptr b -> Int -> IO BufferCopy

pokeByteOff :: Ptr b -> Int -> BufferCopy -> IO ()

peek :: Ptr BufferCopy -> IO BufferCopy

poke :: Ptr BufferCopy -> BufferCopy -> IO ()

FromCStruct BufferCopy

Defined in Graphics.Vulkan.Core10.CommandBufferBuilding

Methods

peekCStruct :: Ptr BufferCopy -> IO BufferCopy

ToCStruct BufferCopy

Defined in Graphics.Vulkan.Core10.CommandBufferBuilding

Methods

withCStruct :: BufferCopy -> (Ptr BufferCopy -> IO b) -> IO b

pokeCStruct :: Ptr BufferCopy -> BufferCopy -> IO b -> IO b

withZeroCStruct :: (Ptr BufferCopy -> IO b) -> IO b

pokeZeroCStruct :: Ptr BufferCopy -> IO b -> IO b

cStructSize :: Int

cStructAlignment :: Int

Zero BufferCopy

Defined in Graphics.Vulkan.Core10.CommandBufferBuilding

Methods

zero :: BufferCopy

data ImageCopy

VkImageCopy - Structure specifying an image copy operation

Description

For IMAGE_TYPE_3D images, copies are performed slice by slice starting with the z member of the srcOffset or dstOffset, and copying depth slices. For images with multiple layers, copies are performed layer by layer starting with the baseArrayLayer member of the srcSubresource or dstSubresource and copying layerCount layers. Image data can be copied between images with different image types. If one image is IMAGE_TYPE_3D and the other image is IMAGE_TYPE_2D with multiple layers, then each slice is copied to or from a different layer.

Copies involving a multi-planar image format specify the region to be copied in terms of the plane to be copied, not the coordinates of the multi-planar image. This means that copies accessing the R/B planes of “_422” format images must fit the copied region within half the width of the parent image, and that copies accessing the R/B planes of “_420” format images must fit the copied region within half the width and height of the parent image.

Valid Usage

• If neither the calling command’s srcImage nor the calling command’s dstImage has a multi-planar image format then the aspectMask member of srcSubresource and dstSubresource must match

• If the calling command’s srcImage has a Format with two planes then the srcSubresource aspectMask must be IMAGE_ASPECT_PLANE_0_BIT or IMAGE_ASPECT_PLANE_1_BIT
• If the calling command’s srcImage has a Format with three planes then the srcSubresource aspectMask must be IMAGE_ASPECT_PLANE_0_BIT, IMAGE_ASPECT_PLANE_1_BIT, or IMAGE_ASPECT_PLANE_2_BIT
• If the calling command’s dstImage has a Format with two planes then the dstSubresource aspectMask must be IMAGE_ASPECT_PLANE_0_BIT or IMAGE_ASPECT_PLANE_1_BIT
• If the calling command’s dstImage has a Format with three planes then the dstSubresource aspectMask must be IMAGE_ASPECT_PLANE_0_BIT, IMAGE_ASPECT_PLANE_1_BIT, or IMAGE_ASPECT_PLANE_2_BIT
• If the calling command’s srcImage has a multi-planar image format and the dstImage does not have a multi-planar image format, the dstSubresource aspectMask must be IMAGE_ASPECT_COLOR_BIT
• If the calling command’s dstImage has a multi-planar image format and the srcImage does not have a multi-planar image format, the srcSubresource aspectMask must be IMAGE_ASPECT_COLOR_BIT
• The number of slices of the extent (for 3D) or layers of the srcSubresource (for non-3D) must match the number of slices of the extent (for 3D) or layers of the dstSubresource (for non-3D)
• If either of the calling command’s srcImage or dstImage parameters are of ImageType IMAGE_TYPE_3D, the baseArrayLayer and layerCount members of the corresponding subresource must be 0 and 1, respectively
• The aspectMask member of srcSubresource must specify aspects present in the calling command’s srcImage
• The aspectMask member of dstSubresource must specify aspects present in the calling command’s dstImage
• srcOffset.x and (extent.width + srcOffset.x) must both be greater than or equal to 0 and less than or equal to the source image subresource width
• srcOffset.y and (extent.height + srcOffset.y) must both be greater than or equal to 0 and less than or equal to the source image subresource height
• If the calling command’s srcImage is of type IMAGE_TYPE_1D, then srcOffset.y must be 0 and extent.height must be 1
• srcOffset.z and (extent.depth + srcOffset.z) must both be greater than or equal to 0 and less than or equal to the source image subresource depth
• If the calling command’s srcImage is of type IMAGE_TYPE_1D, then srcOffset.z must be 0 and extent.depth must be 1
• If the calling command’s dstImage is of type IMAGE_TYPE_1D, then dstOffset.z must be 0 and extent.depth must be 1
• If the calling command’s srcImage is of type IMAGE_TYPE_2D, then srcOffset.z must be 0
• If the calling command’s dstImage is of type IMAGE_TYPE_2D, then dstOffset.z must be 0
• If both srcImage and dstImage are of type IMAGE_TYPE_2D then extent.depth must be 1
• If the calling command’s srcImage is of type IMAGE_TYPE_2D, and the dstImage is of type IMAGE_TYPE_3D, then extent.depth must equal to the layerCount member of srcSubresource
• If the calling command’s dstImage is of type IMAGE_TYPE_2D, and the srcImage is of type IMAGE_TYPE_3D, then extent.depth must equal to the layerCount member of dstSubresource
• dstOffset.x and (extent.width + dstOffset.x) must both be greater than or equal to 0 and less than or equal to the destination image subresource width
• dstOffset.y and (extent.height + dstOffset.y) must both be greater than or equal to 0 and less than or equal to the destination image subresource height
• If the calling command’s dstImage is of type IMAGE_TYPE_1D, then dstOffset.y must be 0 and extent.height must be 1
• dstOffset.z and (extent.depth + dstOffset.z) must both be greater than or equal to 0 and less than or equal to the destination image subresource depth
• If the calling command’s srcImage is a compressed image, or a single-plane, “_422” image format, all members of srcOffset must be a multiple of the corresponding dimensions of the compressed texel block
• If the calling command’s srcImage is a compressed image, or a single-plane, “_422” image format, extent.width must be a multiple of the compressed texel block width or (extent.width + srcOffset.x) must equal the source image subresource width
• If the calling command’s srcImage is a compressed image, or a single-plane, “_422” image format, extent.height must be a multiple of the compressed texel block height or (extent.height + srcOffset.y) must equal the source image subresource height
• If the calling command’s srcImage is a compressed image, or a single-plane, “_422” image format, extent.depth must be a multiple of the compressed texel block depth or (extent.depth + srcOffset.z) must equal the source image subresource depth
• If the calling command’s dstImage is a compressed format image, or a single-plane, “_422” image format, all members of dstOffset must be a multiple of the corresponding dimensions of the compressed texel block
• If the calling command’s dstImage is a compressed format image, or a single-plane, “_422” image format, extent.width must be a multiple of the compressed texel block width or (extent.width + dstOffset.x) must equal the destination image subresource width
• If the calling command’s dstImage is a compressed format image, or a single-plane, “_422” image format, extent.height must be a multiple of the compressed texel block height or (extent.height + dstOffset.y) must equal the destination image subresource height
• If the calling command’s dstImage is a compressed format image, or a single-plane, “_422” image format, extent.depth must be a multiple of the compressed texel block depth or (extent.depth + dstOffset.z) must equal the destination image subresource depth

Valid Usage (Implicit)

• srcSubresource must be a valid ImageSubresourceLayers structure

• dstSubresource must be a valid ImageSubresourceLayers structure

See Also

Extent3D, ImageSubresourceLayers, Offset3D, cmdCopyImage

Constructors

ImageCopy

Fields

• srcSubresource :: ImageSubresourceLayers

  srcSubresource and dstSubresource are ImageSubresourceLayers structures specifying the image subresources of the images used for the source and destination image data, respectively.

• srcOffset :: Offset3D

  srcOffset and dstOffset select the initial x, y, and z offsets in texels of the sub-regions of the source and destination image data.

• dstSubresource :: ImageSubresourceLayers
• dstOffset :: Offset3D
• extent :: Extent3D

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

Instances

Show ImageCopy

Defined in Graphics.Vulkan.Core10.CommandBufferBuilding

Methods

showsPrec :: Int -> ImageCopy -> ShowS

show :: ImageCopy -> String

showList :: [ImageCopy] -> ShowS

FromCStruct ImageCopy

Defined in Graphics.Vulkan.Core10.CommandBufferBuilding

Methods

peekCStruct :: Ptr ImageCopy -> IO ImageCopy

ToCStruct ImageCopy

Defined in Graphics.Vulkan.Core10.CommandBufferBuilding

Methods

withCStruct :: ImageCopy -> (Ptr ImageCopy -> IO b) -> IO b

pokeCStruct :: Ptr ImageCopy -> ImageCopy -> IO b -> IO b

withZeroCStruct :: (Ptr ImageCopy -> IO b) -> IO b

pokeZeroCStruct :: Ptr ImageCopy -> IO b -> IO b

cStructSize :: Int

cStructAlignment :: Int

Zero ImageCopy

Defined in Graphics.Vulkan.Core10.CommandBufferBuilding

Methods

zero :: ImageCopy

data ImageBlit

VkImageBlit - Structure specifying an image blit operation

Description

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

Valid Usage

• The aspectMask member of srcSubresource and dstSubresource must match

• The layerCount member of srcSubresource and dstSubresource must match
• If either of the calling command’s srcImage or dstImage parameters are of ImageType IMAGE_TYPE_3D, the baseArrayLayer and layerCount members of both srcSubresource and dstSubresource must be 0 and 1, respectively
• The aspectMask member of srcSubresource must specify aspects present in the calling command’s srcImage
• The aspectMask member of dstSubresource must specify aspects present in the calling command’s dstImage
• srcOffset[0].x and srcOffset[1].x must both be greater than or equal to 0 and less than or equal to the source image subresource width
• srcOffset[0].y and srcOffset[1].y must both be greater than or equal to 0 and less than or equal to the source image subresource height
• If the calling command’s srcImage is of type IMAGE_TYPE_1D, then srcOffset[0].y must be 0 and srcOffset[1].y must be 1
• srcOffset[0].z and srcOffset[1].z must both be greater than or equal to 0 and less than or equal to the source image subresource depth
• If the calling command’s srcImage is of type IMAGE_TYPE_1D or IMAGE_TYPE_2D, then srcOffset[0].z must be 0 and srcOffset[1].z must be 1
• dstOffset[0].x and dstOffset[1].x must both be greater than or equal to 0 and less than or equal to the destination image subresource width
• dstOffset[0].y and dstOffset[1].y must both be greater than or equal to 0 and less than or equal to the destination image subresource height
• If the calling command’s dstImage is of type IMAGE_TYPE_1D, then dstOffset[0].y must be 0 and dstOffset[1].y must be 1
• dstOffset[0].z and dstOffset[1].z must both be greater than or equal to 0 and less than or equal to the destination image subresource depth
• If the calling command’s dstImage is of type IMAGE_TYPE_1D or IMAGE_TYPE_2D, then dstOffset[0].z must be 0 and dstOffset[1].z must be 1

Valid Usage (Implicit)

• srcSubresource must be a valid ImageSubresourceLayers structure

• dstSubresource must be a valid ImageSubresourceLayers structure

See Also

ImageSubresourceLayers, Offset3D, cmdBlitImage

Constructors

ImageBlit

Fields

• srcSubresource :: ImageSubresourceLayers

  srcSubresource is the subresource to blit from.

• srcOffsets :: (Offset3D, Offset3D)

  srcOffsets is a pointer to an array of two Offset3D structures specifying the bounds of the source region within srcSubresource.

• dstSubresource :: ImageSubresourceLayers

  dstSubresource is the subresource to blit into.

• dstOffsets :: (Offset3D, Offset3D)

  dstOffsets is a pointer to an array of two Offset3D structures specifying the bounds of the destination region within dstSubresource.

Instances

Show ImageBlit

Defined in Graphics.Vulkan.Core10.CommandBufferBuilding

Methods

showsPrec :: Int -> ImageBlit -> ShowS

show :: ImageBlit -> String

showList :: [ImageBlit] -> ShowS

FromCStruct ImageBlit

Defined in Graphics.Vulkan.Core10.CommandBufferBuilding

Methods

peekCStruct :: Ptr ImageBlit -> IO ImageBlit

ToCStruct ImageBlit

Defined in Graphics.Vulkan.Core10.CommandBufferBuilding

Methods

withCStruct :: ImageBlit -> (Ptr ImageBlit -> IO b) -> IO b

pokeCStruct :: Ptr ImageBlit -> ImageBlit -> IO b -> IO b

withZeroCStruct :: (Ptr ImageBlit -> IO b) -> IO b

pokeZeroCStruct :: Ptr ImageBlit -> IO b -> IO b

cStructSize :: Int

cStructAlignment :: Int

Zero ImageBlit

Defined in Graphics.Vulkan.Core10.CommandBufferBuilding

Methods

zero :: ImageBlit

data BufferImageCopy

VkBufferImageCopy - Structure specifying a buffer image copy operation

Description

When copying to or from a depth or stencil aspect, the data in buffer memory uses a layout that is a (mostly) tightly packed representation of the depth or stencil data. Specifically:

• data copied to or from the stencil aspect of any depth/stencil format is tightly packed with one FORMAT_S8_UINT value per texel.
• data copied to or from the depth aspect of a FORMAT_D16_UNORM or FORMAT_D16_UNORM_S8_UINT format is tightly packed with one FORMAT_D16_UNORM value per texel.
• data copied to or from the depth aspect of a FORMAT_D32_SFLOAT or FORMAT_D32_SFLOAT_S8_UINT format is tightly packed with one FORMAT_D32_SFLOAT value per texel.
• data copied to or from the depth aspect of a FORMAT_X8_D24_UNORM_PACK32 or FORMAT_D24_UNORM_S8_UINT format is packed with one 32-bit word per texel with the D24 value in the LSBs of the word, and undefined values in the eight MSBs.

Note

To copy both the depth and stencil aspects of a depth/stencil format, two entries in pRegions can be used, where one specifies the depth aspect in imageSubresource, and the other specifies the stencil aspect.

Because depth or stencil aspect buffer to image copies may require format conversions on some implementations, they are not supported on queues that do not support graphics.

When copying to a depth aspect, and the VK_EXT_depth_range_unrestricted extension is not enabled, the data in buffer memory must be in the range [0,1], or the resulting values are undefined.

Copies are done layer by layer starting with image layer baseArrayLayer member of imageSubresource. layerCount layers are copied from the source image or to the destination image.

Valid Usage

• If the calling command’s Image parameter’s format is not a depth/stencil format or a multi-planar format, then bufferOffset must be a multiple of the format’s texel block size

• If the calling command’s Image parameter’s format is a multi-planar format, then 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 https://www.khronos.org/registry/vulkan/specs/1.2-extensions/html/vkspec.html#formats-compatible-planes
• bufferOffset must be a multiple of 4
• 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
• imageOffset.x and (imageExtent.width + imageOffset.x) must both be greater than or equal to 0 and less than or equal to the image subresource width where this refers to the width of the plane of the image involved in the copy in the case of a multi-planar format
• imageOffset.y and (imageExtent.height + imageOffset.y) must both be greater than or equal to 0 and less than or equal to the image subresource height where this refers to the height of the plane of the image involved in the copy in the case of a multi-planar format
• If the calling command’s srcImage (cmdCopyImageToBuffer) or dstImage (cmdCopyBufferToImage) is of type IMAGE_TYPE_1D, then imageOffset.y must be 0 and imageExtent.height must be 1
• imageOffset.z and (imageExtent.depth + imageOffset.z) must both be greater than or equal to 0 and less than or equal to the image subresource depth
• If the calling command’s srcImage (cmdCopyImageToBuffer) or dstImage (cmdCopyBufferToImage) is of type IMAGE_TYPE_1D or IMAGE_TYPE_2D, then imageOffset.z must be 0 and imageExtent.depth must be 1
• If the calling command’s Image parameter is a compressed image, or a single-plane, “_422” image format, bufferRowLength must be a multiple of the compressed texel block width
• If the calling command’s Image parameter is a compressed image, or a single-plane, “_422” image format, bufferImageHeight must be a multiple of the compressed texel block height
• If the calling command’s Image parameter is a compressed image, or a single-plane, “_422” image format, all members of imageOffset must be a multiple of the corresponding dimensions of the compressed texel block
• If the calling command’s Image parameter is a compressed image, or a single-plane, “_422” image format, bufferOffset must be a multiple of the compressed texel block size in bytes
• If the calling command’s Image parameter is a compressed image, or a single-plane, “_422” image format, imageExtent.width must be a multiple of the compressed texel block width or (imageExtent.width + imageOffset.x) must equal the image subresource width
• If the calling command’s Image parameter is a compressed image, or a single-plane, “_422” image format, imageExtent.height must be a multiple of the compressed texel block height or (imageExtent.height + imageOffset.y) must equal the image subresource height
• If the calling command’s Image parameter is a compressed image, or a single-plane, “_422” image format, imageExtent.depth must be a multiple of the compressed texel block depth or (imageExtent.depth + imageOffset.z) must equal the image subresource depth
• The aspectMask member of imageSubresource must specify aspects present in the calling command’s Image parameter
• If the calling command’s Image parameter’s format is a multi-planar format, then the aspectMask member of imageSubresource must be IMAGE_ASPECT_PLANE_0_BIT, IMAGE_ASPECT_PLANE_1_BIT, or IMAGE_ASPECT_PLANE_2_BIT (with IMAGE_ASPECT_PLANE_2_BIT valid only for image formats with three planes)
• The aspectMask member of imageSubresource must only have a single bit set
• If the calling command’s Image parameter is of ImageType IMAGE_TYPE_3D, the baseArrayLayer and layerCount members of imageSubresource must be 0 and 1, respectively

Valid Usage (Implicit)

• imageSubresource must be a valid ImageSubresourceLayers structure

See Also

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

Show BufferImageCopy

Defined in Graphics.Vulkan.Core10.CommandBufferBuilding

Methods

showsPrec :: Int -> BufferImageCopy -> ShowS

show :: BufferImageCopy -> String

showList :: [BufferImageCopy] -> ShowS

FromCStruct BufferImageCopy

Defined in Graphics.Vulkan.Core10.CommandBufferBuilding

Methods

peekCStruct :: Ptr BufferImageCopy -> IO BufferImageCopy

ToCStruct BufferImageCopy

Defined in Graphics.Vulkan.Core10.CommandBufferBuilding

Methods

withCStruct :: BufferImageCopy -> (Ptr BufferImageCopy -> IO b) -> IO b

pokeCStruct :: Ptr BufferImageCopy -> BufferImageCopy -> IO b -> IO b

withZeroCStruct :: (Ptr BufferImageCopy -> IO b) -> IO b

pokeZeroCStruct :: Ptr BufferImageCopy -> IO b -> IO b

cStructSize :: Int

cStructAlignment :: Int

Zero BufferImageCopy

Defined in Graphics.Vulkan.Core10.CommandBufferBuilding

Methods

zero :: BufferImageCopy

data ImageResolve

VkImageResolve - Structure specifying an image resolve operation

Valid Usage

• The aspectMask member of srcSubresource and dstSubresource must only contain IMAGE_ASPECT_COLOR_BIT

• The layerCount member of srcSubresource and dstSubresource must match
• If either of the calling command’s srcImage or dstImage parameters are of ImageType IMAGE_TYPE_3D, the baseArrayLayer and layerCount members of both srcSubresource and dstSubresource must be 0 and 1, respectively
• srcOffset.x and (extent.width + srcOffset.x) must both be greater than or equal to 0 and less than or equal to the source image subresource width
• srcOffset.y and (extent.height + srcOffset.y) must both be greater than or equal to 0 and less than or equal to the source image subresource height
• If the calling command’s srcImage is of type IMAGE_TYPE_1D, then srcOffset.y must be 0 and extent.height must be 1
• srcOffset.z and (extent.depth + srcOffset.z) must both be greater than or equal to 0 and less than or equal to the source image subresource depth
• If the calling command’s srcImage is of type IMAGE_TYPE_1D or IMAGE_TYPE_2D, then srcOffset.z must be 0 and extent.depth must be 1
• dstOffset.x and (extent.width + dstOffset.x) must both be greater than or equal to 0 and less than or equal to the destination image subresource width
• dstOffset.y and (extent.height + dstOffset.y) must both be greater than or equal to 0 and less than or equal to the destination image subresource height
• If the calling command’s dstImage is of type IMAGE_TYPE_1D, then dstOffset.y must be 0 and extent.height must be 1
• dstOffset.z and (extent.depth + dstOffset.z) must both be greater than or equal to 0 and less than or equal to the destination image subresource depth
• If the calling command’s dstImage is of type IMAGE_TYPE_1D or IMAGE_TYPE_2D, then dstOffset.z must be 0 and extent.depth must be 1

Valid Usage (Implicit)

• srcSubresource must be a valid ImageSubresourceLayers structure

• dstSubresource must be a valid ImageSubresourceLayers structure

See Also

Extent3D, ImageSubresourceLayers, Offset3D, cmdResolveImage

Constructors

ImageResolve

Fields

• srcSubresource :: ImageSubresourceLayers

  srcSubresource and dstSubresource are ImageSubresourceLayers structures specifying the image subresources of the images used for the source and destination image data, respectively. Resolve of depth/stencil images is not supported.

• srcOffset :: Offset3D

  srcOffset and dstOffset select the initial x, y, and z offsets in texels of the sub-regions of the source and destination image data.

• dstSubresource :: ImageSubresourceLayers
• dstOffset :: Offset3D
• extent :: Extent3D

  extent is the size in texels of the source image to resolve in width, height and depth.

Instances

Show ImageResolve

Defined in Graphics.Vulkan.Core10.CommandBufferBuilding

Methods

showsPrec :: Int -> ImageResolve -> ShowS

show :: ImageResolve -> String

showList :: [ImageResolve] -> ShowS

FromCStruct ImageResolve

Defined in Graphics.Vulkan.Core10.CommandBufferBuilding

Methods

peekCStruct :: Ptr ImageResolve -> IO ImageResolve

ToCStruct ImageResolve

Defined in Graphics.Vulkan.Core10.CommandBufferBuilding

Methods

withCStruct :: ImageResolve -> (Ptr ImageResolve -> IO b) -> IO b

pokeCStruct :: Ptr ImageResolve -> ImageResolve -> IO b -> IO b

withZeroCStruct :: (Ptr ImageResolve -> IO b) -> IO b

pokeZeroCStruct :: Ptr ImageResolve -> IO b -> IO b

cStructSize :: Int

cStructAlignment :: Int

Zero ImageResolve

Defined in Graphics.Vulkan.Core10.CommandBufferBuilding

Methods

zero :: ImageResolve

data RenderPassBeginInfo (es :: [Type])

VkRenderPassBeginInfo - Structure specifying render pass begin info

Description

renderArea is the render area that is affected by the render pass instance. The effects of attachment load, store and multisample resolve operations are restricted to the pixels whose x and y coordinates fall within the render area on all attachments. The render area extends to all layers of framebuffer. The application must ensure (using scissor if necessary) that all rendering is contained within the render area. The render area, after any transform specified by RenderPassTransformBeginInfoQCOM::transform is applied, must be contained within the framebuffer dimensions.

If render pass transform is enabled, then renderArea must equal the framebuffer pre-transformed dimensions. After renderArea has been transformed by RenderPassTransformBeginInfoQCOM::transform, the resulting render area must be equal to the framebuffer dimensions.

When multiview is enabled, the resolve operation at the end of a subpass applies to all views in the view mask.

Note

There may be a performance cost for using a render area smaller than the framebuffer, unless it matches the render area granularity for the render pass.

Valid Usage

• clearValueCount must be greater than the largest attachment index in renderPass that specifies a loadOp (or stencilLoadOp, if the attachment has a depth/stencil format) of ATTACHMENT_LOAD_OP_CLEAR

• renderPass must be compatible with the renderPass member of the FramebufferCreateInfo structure specified when creating framebuffer
• If the pNext chain does not contain DeviceGroupRenderPassBeginInfo or its deviceRenderAreaCount member is equal to 0, renderArea.offset.x must be greater than or equal to 0
• If the pNext chain does not contain DeviceGroupRenderPassBeginInfo or its deviceRenderAreaCount member is equal to 0, renderArea.offset.y must be greater than or equal to 0
• If the pNext chain does not contain DeviceGroupRenderPassBeginInfo or its deviceRenderAreaCount member is equal to 0, renderArea.offset.x + renderArea.offset.width must be less than or equal to FramebufferCreateInfo::width the framebuffer was created with
• If the pNext chain does not contain DeviceGroupRenderPassBeginInfo or its deviceRenderAreaCount member is equal to 0, renderArea.offset.y + renderArea.offset.height must be less than or equal to FramebufferCreateInfo::height the framebuffer was created with
• If the pNext chain contains DeviceGroupRenderPassBeginInfo, the offset.x member of each element of pDeviceRenderAreas must be greater than or equal to 0
• If the pNext chain contains DeviceGroupRenderPassBeginInfo, the offset.y member of each element of pDeviceRenderAreas must be greater than or equal to 0
• If the pNext chain contains DeviceGroupRenderPassBeginInfo, offset.x + offset.width of each element of pDeviceRenderAreas must be less than or equal to FramebufferCreateInfo::width the framebuffer was created with
• If the pNext chain contains DeviceGroupRenderPassBeginInfo, offset.y + offset.height of each element of pDeviceRenderAreas must be less than or equal to FramebufferCreateInfo::height the framebuffer was created with
• If framebuffer was created with a FramebufferCreateInfo::flags value that did not include FRAMEBUFFER_CREATE_IMAGELESS_BIT, and the pNext chain includes a RenderPassAttachmentBeginInfo structure, its attachmentCount must be zero
• If framebuffer was created with a FramebufferCreateInfo::flags value that included FRAMEBUFFER_CREATE_IMAGELESS_BIT, the attachmentCount of a RenderPassAttachmentBeginInfo structure included in the pNext chain must be equal to the value of FramebufferAttachmentsCreateInfo::attachmentImageInfoCount used to create framebuffer
• If framebuffer was created with a FramebufferCreateInfo::flags value that included FRAMEBUFFER_CREATE_IMAGELESS_BIT_KHR, each element of the pAttachments member of a RenderPassAttachmentBeginInfo structure included in the pNext chain must have been created on the same Device as framebuffer and renderPass
• If framebuffer was created with a FramebufferCreateInfo::flags value that included FRAMEBUFFER_CREATE_IMAGELESS_BIT, each element of the pAttachments member of a RenderPassAttachmentBeginInfo structure included in the pNext chain must be a ImageView of an image created with a value of ImageCreateInfo::flags equal to the flags member of the corresponding element of FramebufferAttachmentsCreateInfoKHR::pAttachments used to create framebuffer
• If framebuffer was created with a FramebufferCreateInfo::flags value that included FRAMEBUFFER_CREATE_IMAGELESS_BIT, each element of the pAttachments member of a RenderPassAttachmentBeginInfo structure included in the pNext chain must be a ImageView of an image created with a value of ImageCreateInfo::usage equal to the usage member of the corresponding element of FramebufferAttachmentsCreateInfo::pAttachments used to create framebuffer
• If framebuffer was created with a FramebufferCreateInfo::flags value that included FRAMEBUFFER_CREATE_IMAGELESS_BIT, each element of the pAttachments member of a RenderPassAttachmentBeginInfo structure included in the pNext chain must be a ImageView with a width equal to the width member of the corresponding element of FramebufferAttachmentsCreateInfo::pAttachments used to create framebuffer
• If framebuffer was created with a FramebufferCreateInfo::flags value that included FRAMEBUFFER_CREATE_IMAGELESS_BIT, each element of the pAttachments member of a RenderPassAttachmentBeginInfo structure included in the pNext chain must be a ImageView with a height equal to the height member of the corresponding element of FramebufferAttachmentsCreateInfo::pAttachments used to create framebuffer
• If framebuffer was created with a FramebufferCreateInfo::flags value that included FRAMEBUFFER_CREATE_IMAGELESS_BIT, each element of the pAttachments member of a RenderPassAttachmentBeginInfo structure included in the pNext chain must be a ImageView of an image created with a value of ImageViewCreateInfo::subresourceRange.layerCount equal to the layerCount member of the corresponding element of FramebufferAttachmentsCreateInfo::pAttachments used to create framebuffer
• If framebuffer was created with a FramebufferCreateInfo::flags value that included FRAMEBUFFER_CREATE_IMAGELESS_BIT, each element of the pAttachments member of a RenderPassAttachmentBeginInfo structure included in the pNext chain must be a ImageView of an image created with a value of ImageFormatListCreateInfo::viewFormatCount equal to the viewFormatCount member of the corresponding element of FramebufferAttachmentsCreateInfo::pAttachments used to create framebuffer
• If framebuffer was created with a FramebufferCreateInfo::flags value that included FRAMEBUFFER_CREATE_IMAGELESS_BIT, each element of the pAttachments member of a RenderPassAttachmentBeginInfo structure included in the pNext chain must be a ImageView of an image created with a set of elements in ImageFormatListCreateInfo::pViewFormats equal to the set of elements in the pViewFormats member of the corresponding element of FramebufferAttachmentsCreateInfo::pAttachments used to create framebuffer
• If framebuffer was created with a FramebufferCreateInfo::flags value that included FRAMEBUFFER_CREATE_IMAGELESS_BIT, each element of the pAttachments member of a RenderPassAttachmentBeginInfo structure included in the pNext chain must be a ImageView of an image created with a value of ImageViewCreateInfo::format equal to the corresponding value of AttachmentDescription::format in renderPass
• If framebuffer was created with a FramebufferCreateInfo::flags value that included FRAMEBUFFER_CREATE_IMAGELESS_BIT, each element of the pAttachments member of a RenderPassAttachmentBeginInfo structure included in the pNext chain must be a ImageView of an image created with a value of ImageCreateInfo::samples equal to the corresponding value of AttachmentDescription::samples in renderPass
• If the pNext chain includes RenderPassTransformBeginInfoQCOM, renderArea::offset must equal (0,0)
• If the pNext chain includes RenderPassTransformBeginInfoQCOM, renderArea::extent transformed by RenderPassTransformBeginInfoQCOM::transform must equal the framebuffer dimensions

Valid Usage (Implicit)

• sType must be STRUCTURE_TYPE_RENDER_PASS_BEGIN_INFO

• Each pNext member of any structure (including this one) in the pNext chain must be either NULL or a pointer to a valid instance of DeviceGroupRenderPassBeginInfo, RenderPassAttachmentBeginInfo, RenderPassSampleLocationsBeginInfoEXT, or RenderPassTransformBeginInfoQCOM
• The sType value of each struct in the pNext chain must be unique
• renderPass must be a valid RenderPass handle
• framebuffer must be a valid Framebuffer handle
• If clearValueCount is not 0, pClearValues must be a valid pointer to an array of clearValueCount ClearValue unions
• Both of framebuffer, and renderPass must have been created, allocated, or retrieved from the same Device

See Also

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

Constructors

RenderPassBeginInfo

Fields

• next :: Chain es

  pNext is NULL or a pointer to an extension-specific 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 that contains 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.

Instances

Extensible RenderPassBeginInfo

Defined in Graphics.Vulkan.Core10.CommandBufferBuilding

Methods

extensibleType :: StructureType

getNext :: RenderPassBeginInfo es -> Chain es

setNext :: RenderPassBeginInfo ds -> Chain es -> RenderPassBeginInfo es

extends :: Typeable e => proxy e -> (Extends RenderPassBeginInfo e -> b) -> Maybe b

Show (Chain es) => Show (RenderPassBeginInfo es)

Defined in Graphics.Vulkan.Core10.CommandBufferBuilding

Methods

showsPrec :: Int -> RenderPassBeginInfo es -> ShowS

show :: RenderPassBeginInfo es -> String

showList :: [RenderPassBeginInfo es] -> ShowS

PokeChain es => ToCStruct (RenderPassBeginInfo es)

Defined in Graphics.Vulkan.Core10.CommandBufferBuilding

Methods

withCStruct :: RenderPassBeginInfo es -> (Ptr (RenderPassBeginInfo es) -> IO b) -> IO b

pokeCStruct :: Ptr (RenderPassBeginInfo es) -> RenderPassBeginInfo es -> IO b -> IO b

withZeroCStruct :: (Ptr (RenderPassBeginInfo es) -> IO b) -> IO b

pokeZeroCStruct :: Ptr (RenderPassBeginInfo es) -> IO b -> IO b

cStructSize :: Int

cStructAlignment :: Int

es ~ ([] :: [Type]) => Zero (RenderPassBeginInfo es)

Defined in Graphics.Vulkan.Core10.CommandBufferBuilding

Methods

zero :: RenderPassBeginInfo es

data ClearAttachment

VkClearAttachment - Structure specifying a clear attachment

Description

No memory barriers are needed between cmdClearAttachments and preceding or subsequent draw or attachment clear commands in the same subpass.

The cmdClearAttachments command is not affected by the bound pipeline state.

Attachments can also be cleared at the beginning of a render pass instance by setting loadOp (or stencilLoadOp) of AttachmentDescription to ATTACHMENT_LOAD_OP_CLEAR, as described for createRenderPass.

Valid Usage

• If aspectMask includes IMAGE_ASPECT_COLOR_BIT, it must not include IMAGE_ASPECT_DEPTH_BIT or IMAGE_ASPECT_STENCIL_BIT

• aspectMask must not include IMAGE_ASPECT_METADATA_BIT
• aspectMask must not include VK_IMAGE_ASPECT_MEMORY_PLANE_i_BIT_EXT for any index i
• clearValue must be a valid ClearValue union

Valid Usage (Implicit)

• aspectMask must be a valid combination of ImageAspectFlagBits values

• aspectMask must not be 0

See Also

ClearValue, ImageAspectFlags, cmdClearAttachments

Constructors

ClearAttachment

Fields

• aspectMask :: ImageAspectFlags

  aspectMask is a mask selecting the color, depth and/or stencil aspects of the attachment to be cleared.

• colorAttachment :: Word32

  colorAttachment is only meaningful if IMAGE_ASPECT_COLOR_BIT is set in aspectMask, in which case it is an index to the pColorAttachments array in the SubpassDescription structure of the current subpass which selects the color attachment to clear.

• clearValue :: ClearValue

  clearValue is the color or depth/stencil value to clear the attachment to, as described in Clear Values below.

Instances

Show ClearAttachment

Defined in Graphics.Vulkan.Core10.CommandBufferBuilding

Methods

showsPrec :: Int -> ClearAttachment -> ShowS

show :: ClearAttachment -> String

showList :: [ClearAttachment] -> ShowS

ToCStruct ClearAttachment

Defined in Graphics.Vulkan.Core10.CommandBufferBuilding

Methods

withCStruct :: ClearAttachment -> (Ptr ClearAttachment -> IO b) -> IO b

pokeCStruct :: Ptr ClearAttachment -> ClearAttachment -> IO b -> IO b

withZeroCStruct :: (Ptr ClearAttachment -> IO b) -> IO b

pokeZeroCStruct :: Ptr ClearAttachment -> IO b -> IO b

cStructSize :: Int

cStructAlignment :: Int

Zero ClearAttachment

Defined in Graphics.Vulkan.Core10.CommandBufferBuilding

Methods

zero :: ClearAttachment