vulkan-3.6.11.1: Bindings to the Vulkan graphics API.

Synopsis

# Documentation

Arguments

 :: forall io. MonadIO io => CommandBuffer commandBuffer is the command buffer into which the command will be recorded. -> ("fragmentSize" ::: Extent2D) pFragmentSize specifies the pipeline fragment shading rate for subsequent draw commands. -> ("combinerOps" ::: (FragmentShadingRateCombinerOpKHR, FragmentShadingRateCombinerOpKHR)) combinerOps specifies a FragmentShadingRateCombinerOpKHR determining how the pipeline, primitive, and attachment shading rates are combined for fragments generated by subsequent drawing commands. -> io ()

## Valid Usage

• If pipelineFragmentShadingRate is not enabled, pFragmentSize->height must be 1
• If the primitiveFragmentShadingRate feature is not enabled, combinerOps[0] must be FRAGMENT_SHADING_RATE_COMBINER_OP_KEEP_KHR
• If the attachmentFragmentShadingRate feature is not enabled, combinerOps[1] must be FRAGMENT_SHADING_RATE_COMBINER_OP_KEEP_KHR
• If the fragmentSizeNonTrivialCombinerOps limit is not supported, elements of combinerOps must be either FRAGMENT_SHADING_RATE_COMBINER_OP_KEEP_KHR or FRAGMENT_SHADING_RATE_COMBINER_OP_REPLACE_KHR
• pFragmentSize->width must be greater than or equal to 1
• pFragmentSize->height must be greater than or equal to 1
• pFragmentSize->width must be a power-of-two value
• pFragmentSize->height must be a power-of-two value
• pFragmentSize->width must be less than or equal to 4
• pFragmentSize->height must be less than or equal to 4

## Valid Usage (Implicit)

• commandBuffer must be a valid CommandBuffer handle
• pFragmentSize must be a valid pointer to a valid Extent2D structure
• Any given element of combinerOps must be a valid FragmentShadingRateCombinerOpKHR value
• 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

CommandBuffer, Extent2D, FragmentShadingRateCombinerOpKHR

Arguments

 :: forall io. MonadIO io => PhysicalDevice physicalDevice is the handle to the physical device whose properties will be queried. -> io (Result, "fragmentShadingRates" ::: Vector PhysicalDeviceFragmentShadingRateKHR)

# Description

If pFragmentShadingRates is NULL, then the number of fragment shading rates available is returned in pFragmentShadingRateCount. Otherwise, pFragmentShadingRateCount must point to a variable set by the user to the number of elements in the pFragmentShadingRates array, and on return the variable is overwritten with the number of structures actually written to pFragmentShadingRates. If pFragmentShadingRateCount is less than the number of fragment shading rates available, at most pFragmentShadingRateCount structures will be written, and INCOMPLETE will be returned instead of SUCCESS, to indicate that not all the available fragment shading rates were returned.

The returned array of fragment shading rates must be ordered from largest fragmentSize.width value to smallest, and each set of fragment shading rates with the same fragmentSize.width value must be ordered from largest fragmentSize.height to smallest. Any two entries in the array must not have the same fragmentSize values.

For any entry in the array, the following rules also apply:

• The value of fragmentSize.width must be less than or equal to maxFragmentSize.width.
• The value of fragmentSize.width must be greater than or equal to 1.
• The value of fragmentSize.width must be a power-of-two.
• The value of fragmentSize.height must be less than or equal to maxFragmentSize.height.
• The value of fragmentSize.height must be greater than or equal to 1.
• The value of fragmentSize.height must be a power-of-two.
• The highest sample count in sampleCounts must be less than or equal to maxFragmentShadingRateRasterizationSamples.
• The product of fragmentSize.width, fragmentSize.height, and the highest sample count in sampleCounts must be less than or equal to maxFragmentShadingRateCoverageSamples.

Implementations must support at least the following shading rates:

sampleCounts fragmentSize
SAMPLE_COUNT_1_BIT | SAMPLE_COUNT_4_BIT {2,2}
SAMPLE_COUNT_1_BIT | SAMPLE_COUNT_4_BIT {2,1}
~0 {1,1}

If framebufferColorSampleCounts, includes SAMPLE_COUNT_2_BIT, the required rates must also include SAMPLE_COUNT_2_BIT.

Note

Including the {1,1} fragment size is done for completeness; it has no actual effect on the support of rendering without setting the fragment size. All sample counts are supported for this rate.

## Valid Usage (Implicit)

• physicalDevice must be a valid PhysicalDevice handle
• pFragmentShadingRateCount must be a valid pointer to a uint32_t value
• If the value referenced by pFragmentShadingRateCount is not 0, and pFragmentShadingRates is not NULL, pFragmentShadingRates must be a valid pointer to an array of pFragmentShadingRateCount PhysicalDeviceFragmentShadingRateKHR structures

## Return Codes

Success
• SUCCESS
• INCOMPLETE
Failure
• ERROR_OUT_OF_HOST_MEMORY

PhysicalDevice, PhysicalDeviceFragmentShadingRateKHR

VkFragmentShadingRateAttachmentInfoKHR - Structure specifying a fragment shading rate attachment for a subpass

# Description

If no shading rate attachment is specified, or if this structure isn’t specified, the implementation behaves as if a valid shading rate attachment was specified with all texels specifying a single pixel per fragment.

## Valid Usage

• If pFragmentShadingRateAttachment is not NULL and its attachment member is not ATTACHMENT_UNUSED then it must have a format whose features contain FORMAT_FEATURE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR
• If pFragmentShadingRateAttachment is not NULL and its attachment member is not ATTACHMENT_UNUSED, its layout member must be equal to IMAGE_LAYOUT_GENERAL or IMAGE_LAYOUT_FRAGMENT_SHADING_RATE_ATTACHMENT_OPTIMAL_KHR
• If pFragmentShadingRateAttachment is not NULL and its attachment member is not ATTACHMENT_UNUSED, shadingRateAttachmentTexelSize.width must be a power of two value
• If pFragmentShadingRateAttachment is not NULL and its attachment member is not ATTACHMENT_UNUSED, shadingRateAttachmentTexelSize.width must be less than or equal to maxFragmentShadingRateAttachmentTexelSize.width
• If pFragmentShadingRateAttachment is not NULL and its attachment member is not ATTACHMENT_UNUSED, shadingRateAttachmentTexelSize.width must be greater than or equal to minFragmentShadingRateAttachmentTexelSize.width
• If pFragmentShadingRateAttachment is not NULL and its attachment member is not ATTACHMENT_UNUSED, shadingRateAttachmentTexelSize.height must be a power of two value
• If pFragmentShadingRateAttachment is not NULL and its attachment member is not ATTACHMENT_UNUSED, shadingRateAttachmentTexelSize.height must be less than or equal to maxFragmentShadingRateAttachmentTexelSize.height
• If pFragmentShadingRateAttachment is not NULL and its attachment member is not ATTACHMENT_UNUSED, shadingRateAttachmentTexelSize.height must be greater than or equal to minFragmentShadingRateAttachmentTexelSize.height
• If pFragmentShadingRateAttachment is not NULL and its attachment member is not ATTACHMENT_UNUSED, the quotient of shadingRateAttachmentTexelSize.width and shadingRateAttachmentTexelSize.height must be less than or equal to maxFragmentShadingRateAttachmentTexelSizeAspectRatio
• If pFragmentShadingRateAttachment is not NULL and its attachment member is not ATTACHMENT_UNUSED, the quotient of shadingRateAttachmentTexelSize.height and shadingRateAttachmentTexelSize.width must be less than or equal to maxFragmentShadingRateAttachmentTexelSizeAspectRatio

## Valid Usage (Implicit)

• sType must be STRUCTURE_TYPE_FRAGMENT_SHADING_RATE_ATTACHMENT_INFO_KHR
• pFragmentShadingRateAttachment must be a valid pointer to a valid AttachmentReference2 structure

AttachmentReference2, Extent2D, StructureType

Constructors

 FragmentShadingRateAttachmentInfoKHR FieldsfragmentShadingRateAttachment :: SomeStruct AttachmentReference2pFragmentShadingRateAttachment is an optional AttachmentReference2KHR structure defining the fragment shading rate attachment for this subpass.shadingRateAttachmentTexelSize :: Extent2DshadingRateAttachmentTexelSize specifies the size of the portion of the framebuffer corresponding to each texel in pFragmentShadingRateAttachment.

#### Instances

Instances details
 Source # Instance details Methods Source # Instance details Source # Instance details Methods Source # Instance details Methods

# Description

If the pNext chain of GraphicsPipelineCreateInfo includes a PipelineFragmentShadingRateStateCreateInfoKHR structure, then that structure includes parameters that control the pipeline fragment shading rate.

If this structure is not present, fragmentSize is considered to be equal to (1,1), and both elements of combinerOps are considered to be equal to FRAGMENT_SHADING_RATE_COMBINER_OP_KEEP_KHR.

## Valid Usage (Implicit)

• sType must be STRUCTURE_TYPE_PIPELINE_FRAGMENT_SHADING_RATE_STATE_CREATE_INFO_KHR
• Any given element of combinerOps must be a valid FragmentShadingRateCombinerOpKHR value

Extent2D, FragmentShadingRateCombinerOpKHR, StructureType

Constructors

 PipelineFragmentShadingRateStateCreateInfoKHR FieldsfragmentSize :: Extent2DfragmentSize specifies a Extent2D structure containing the fragment size used to define the pipeline fragment shading rate for draw commands using this pipeline.combinerOps :: (FragmentShadingRateCombinerOpKHR, FragmentShadingRateCombinerOpKHR)combinerOps specifies a FragmentShadingRateCombinerOpKHR value determining how the pipeline, primitive, and attachment shading rates are combined for fragments generated by drawing commands using the created pipeline.

#### Instances

Instances details
 Source # Instance details Source # Instance details Source # Instance details Methods Source # Instance details

# Members

The members of the PhysicalDeviceFragmentShadingRateFeaturesKHR structure describe the following features:

# Description

If the PhysicalDeviceFragmentShadingRateFeaturesKHR structure is included in the pNext chain of PhysicalDeviceFeatures2, it is filled with values indicating whether each feature is supported. PhysicalDeviceFragmentShadingRateFeaturesKHR can also be used in the pNext chain of DeviceCreateInfo to enable these features.

## Valid Usage (Implicit)

Bool32, StructureType

Constructors

 PhysicalDeviceFragmentShadingRateFeaturesKHR FieldspipelineFragmentShadingRate :: BoolpipelineFragmentShadingRate indicates that the implementation supports the pipeline fragment shading rate.primitiveFragmentShadingRate :: BoolprimitiveFragmentShadingRate indicates that the implementation supports the primitive fragment shading rate.attachmentFragmentShadingRate :: BoolattachmentFragmentShadingRate indicates that the implementation supports the attachment fragment shading rate.

#### Instances

Instances details
 Source # Instance details Source # Instance details Source # Instance details Source # Instance details Source # Instance details Methods Source # Instance details

VkPhysicalDeviceFragmentShadingRatePropertiesKHR - Structure describing variable fragment shading rate limits that can be supported by an implementation

# Members

The members of the PhysicalDeviceFragmentShadingRatePropertiesKHR structure describe the following implementation-dependent properties related to fragment shading rates:

# Description

Note

Multiplication of the combiner rates using the fragment width/height in linear space is equivalent to an addition of those values in log2 space. Some implementations inadvertently implemented an addition in linear space due to unclear requirements originating outside of this specification. This resulted in fragmentShadingRateStrictMultiplyCombiner being added. Fortunately, this only affects situations where a rate of 1 in either dimension is combined with another rate of 1. All other combinations result in the exact same result as if multiplication was performed in linear space due to the clamping logic, and the fact that both the sum and product of 2 and 2 are equal. In many cases, this limit will not affect the correct operation of applications.

If the PhysicalDeviceFragmentShadingRatePropertiesKHR structure is included in the pNext chain of PhysicalDeviceProperties2, it is filled with the implementation-dependent limits.

## Valid Usage (Implicit)

Bool32, Extent2D, SampleCountFlagBits, StructureType

Constructors

 PhysicalDeviceFragmentShadingRatePropertiesKHR FieldsminFragmentShadingRateAttachmentTexelSize :: Extent2DminFragmentShadingRateAttachmentTexelSize indicates minimum supported width and height of the portion of the framebuffer corresponding to each texel in a fragment shading rate attachment. Each value must be less than or equal to the values in maxFragmentShadingRateAttachmentTexelSize. Each value must be a power-of-two. It must be (0,0) if the attachmentFragmentShadingRate feature is not supported.maxFragmentShadingRateAttachmentTexelSize :: Extent2DmaxFragmentShadingRateAttachmentTexelSize indicates maximum supported width and height of the portion of the framebuffer corresponding to each texel in a fragment shading rate attachment. Each value must be greater than or equal to the values in minFragmentShadingRateAttachmentTexelSize. Each value must be a power-of-two. It must be (0,0) if the attachmentFragmentShadingRate feature is not supported.maxFragmentShadingRateAttachmentTexelSizeAspectRatio :: Word32maxFragmentShadingRateAttachmentTexelSizeAspectRatio indicates the maximum ratio between the width and height of the portion of the framebuffer corresponding to each texel in a fragment shading rate attachment. maxFragmentShadingRateAttachmentTexelSizeAspectRatio must be a power-of-two value, and must be less than or equal to max(maxFragmentShadingRateAttachmentTexelSize.width / minFragmentShadingRateAttachmentTexelSize.height, maxFragmentShadingRateAttachmentTexelSize.height / minFragmentShadingRateAttachmentTexelSize.width). It must be 0 if the attachmentFragmentShadingRate feature is not supported.primitiveFragmentShadingRateWithMultipleViewports :: BoolprimitiveFragmentShadingRateWithMultipleViewports specifies whether the primitive fragment shading rate can be used when multiple viewports are used. If this value is FALSE, only a single viewport must be used, and applications must not write to the ViewportMaskNV or ViewportIndex built-in when setting PrimitiveShadingRateKHR. It must be FALSE if the shaderOutputViewportIndex feature, the VK_EXT_shader_viewport_index_layer extension, or the geometryShader feature is not supported, or if the primitiveFragmentShadingRate feature is not supported.layeredShadingRateAttachments :: BoollayeredShadingRateAttachments specifies whether a shading rate attachment image view can be created with multiple layers. If this value is FALSE, when creating an image view with a usage that includes IMAGE_USAGE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR, layerCount must be 1. It must be FALSE if the multiview feature, the shaderOutputViewportIndex feature, the VK_EXT_shader_viewport_index_layer extension, or the geometryShader feature is not supported, or if the attachmentFragmentShadingRate feature is not supported.fragmentShadingRateNonTrivialCombinerOps :: BoolfragmentShadingRateNonTrivialCombinerOps specifies whether FragmentShadingRateCombinerOpKHR enums other than FRAGMENT_SHADING_RATE_COMBINER_OP_KEEP_KHR or FRAGMENT_SHADING_RATE_COMBINER_OP_REPLACE_KHR can be used. It must be FALSE unless either the primitiveFragmentShadingRate or attachmentFragmentShadingRate feature is supported.maxFragmentSize :: Extent2DmaxFragmentSize indicates the maximum supported width and height of a fragment. Its width and height members must both be power-of-two values. This limit is purely informational, and is not validated.maxFragmentSizeAspectRatio :: Word32maxFragmentSizeAspectRatio indicates the maximum ratio between the width and height of a fragment. maxFragmentSizeAspectRatio must be a power-of-two value, and must be less than or equal to the maximum of the width and height members of maxFragmentSize. This limit is purely informational, and is not validated.maxFragmentShadingRateCoverageSamples :: Word32maxFragmentShadingRateCoverageSamples specifies the maximum number of coverage samples supported in a single fragment. maxFragmentShadingRateCoverageSamples must be less than or equal to the product of the width and height members of maxFragmentSize, and the sample count reported by maxFragmentShadingRateRasterizationSamples. maxFragmentShadingRateCoverageSamples must be less than or equal to maxSampleMaskWords * 32 if fragmentShadingRateWithShaderSampleMask is supported. This limit is purely informational, and is not validated.maxFragmentShadingRateRasterizationSamples :: SampleCountFlagBitsmaxFragmentShadingRateRasterizationSamples specifies the maximum sample rate supported when a fragment covers multiple pixels. This limit is purely informational, and is not validated.fragmentShadingRateWithShaderDepthStencilWrites :: BoolfragmentShadingRateWithShaderDepthStencilWrites specifies whether the implementation supports writing FragDepth or FragStencilRefEXT from a fragment shader for multi-pixel fragments. If this value is FALSE, writing to those built-ins will clamp the fragment shading rate to (1,1).fragmentShadingRateWithSampleMask :: BoolfragmentShadingRateWithSampleMask specifies whether the the implementation supports setting valid bits of PipelineMultisampleStateCreateInfo::pSampleMask to 0 for multi-pixel fragments. If this value is FALSE, zeroing valid bits in the sample mask will clamp the fragment shading rate to (1,1).fragmentShadingRateWithShaderSampleMask :: BoolfragmentShadingRateWithShaderSampleMask specifies whether the implementation supports reading or writing SampleMask for multi-pixel fragments. If this value is FALSE, using that built-in will clamp the fragment shading rate to (1,1).fragmentShadingRateWithConservativeRasterization :: BoolfragmentShadingRateWithConservativeRasterization specifies whether conservative rasterization is supported for multi-pixel fragments. It must be FALSE if VK_EXT_conservative_rasterization is not supported. If this value is FALSE, using conservative rasterization will clamp the fragment shading rate to (1,1).fragmentShadingRateWithFragmentShaderInterlock :: BoolfragmentShadingRateWithFragmentShaderInterlock specifies whether fragment shader interlock is supported for multi-pixel fragments. It must be FALSE if VK_EXT_fragment_shader_interlock is not supported. If this value is FALSE, using fragment shader interlock will clamp the fragment shading rate to (1,1).fragmentShadingRateWithCustomSampleLocations :: BoolfragmentShadingRateWithCustomSampleLocations specifies whether custom sample locations are supported for multi-pixel fragments. It must be FALSE if VK_EXT_sample_locations is not supported. If this value is FALSE, using custom sample locations will clamp the fragment shading rate to (1,1).fragmentShadingRateStrictMultiplyCombiner :: BoolfragmentShadingRateStrictMultiplyCombiner specifies whether VK_FRAGMENT_SHADING_RATE_COMBINER_OP_MUL_KHR accurately performs a multiplication or not. Implementations where this value is FALSE will instead combine rates with an addition. If fragmentShadingRateNonTrivialCombinerOps is FALSE, implementations must report this as FALSE. If fragmentShadingRateNonTrivialCombinerOps is TRUE, implementations should report this as TRUE.

#### Instances

Instances details
 Source # Instance details Source # Instance details Source # Instance details Source # Instance details

## Valid Usage (Implicit)

Extent2D, SampleCountFlags, StructureType, getPhysicalDeviceFragmentShadingRatesKHR

Constructors

 PhysicalDeviceFragmentShadingRateKHR FieldssampleCounts :: SampleCountFlagssampleCounts is a bitmask of sample counts for which the shading rate described by fragmentSize is supported.fragmentSize :: Extent2DfragmentSize is a Extent2D describing the width and height of a supported shading rate.

#### Instances

Instances details
 Source # Instance details Methods Source # Instance details Source # Instance details Methods Source # Instance details Methods

# Description

where combine(Axy,Bxy) is the combine operation, and Axy and Bxy are the inputs to the operation.

If fragmentShadingRateStrictMultiplyCombiner is FALSE, using FRAGMENT_SHADING_RATE_COMBINER_OP_MUL_KHR with values of 1 for both A and B in the same dimension results in the value 2 being produced for that dimension. See the definition of fragmentShadingRateStrictMultiplyCombiner for more information.

These operations are performed in a component-wise fashion.

PipelineFragmentShadingRateStateCreateInfoKHR, cmdSetFragmentShadingRateKHR

Constructors

 pattern FRAGMENT_SHADING_RATE_COMBINER_OP_KEEP_KHR :: FragmentShadingRateCombinerOpKHR FRAGMENT_SHADING_RATE_COMBINER_OP_KEEP_KHR specifies a combiner operation of combine(Axy,Bxy) = Axy. pattern FRAGMENT_SHADING_RATE_COMBINER_OP_REPLACE_KHR :: FragmentShadingRateCombinerOpKHR FRAGMENT_SHADING_RATE_COMBINER_OP_REPLACE_KHR specifies a combiner operation of combine(Axy,Bxy) = Bxy. pattern FRAGMENT_SHADING_RATE_COMBINER_OP_MIN_KHR :: FragmentShadingRateCombinerOpKHR FRAGMENT_SHADING_RATE_COMBINER_OP_MIN_KHR specifies a combiner operation of combine(Axy,Bxy) = min(Axy,Bxy). pattern FRAGMENT_SHADING_RATE_COMBINER_OP_MAX_KHR :: FragmentShadingRateCombinerOpKHR FRAGMENT_SHADING_RATE_COMBINER_OP_MAX_KHR specifies a combiner operation of combine(Axy,Bxy) = max(Axy,Bxy). pattern FRAGMENT_SHADING_RATE_COMBINER_OP_MUL_KHR :: FragmentShadingRateCombinerOpKHR FRAGMENT_SHADING_RATE_COMBINER_OP_MUL_KHR combiner operation of combine(Axy,Bxy) = Axy*Bxy.