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

Vulkan.Extensions.VK_KHR_fragment_shading_rate

Description

Name

VK_KHR_fragment_shading_rate - device extension

VK_KHR_fragment_shading_rate

Name String
VK_KHR_fragment_shading_rate
Extension Type
Device extension
Registered Extension Number
227
Revision
2
Ratification Status
Ratified
Extension and Version Dependencies

VK_KHR_create_renderpass2      or

Version 1.2 and

VK_KHR_get_physical_device_properties2      or

Version 1.1

Contact
Extension Proposal
VK_KHR_fragment_shading_rate

Other Extension Metadata

Last Modified Date
2021-09-30
Interactions and External Dependencies
Contributors
  • Tobias Hector, AMD
  • Guennadi Riguer, AMD
  • Matthaeus Chajdas, AMD
  • Pat Brown, Nvidia
  • Matthew Netsch, Qualcomm
  • Slawomir Grajewski, Intel
  • Jan-Harald Fredriksen, Arm
  • Jeff Bolz, Nvidia
  • Arseny Kapoulkine, Roblox
  • Contributors to the VK_NV_shading_rate_image specification
  • Contributors to the VK_EXT_fragment_density_map specification

Description

This extension adds the ability to change the rate at which fragments are shaded. Rather than the usual single fragment invocation for each pixel covered by a primitive, multiple pixels can be shaded by a single fragment shader invocation.

Up to three methods are available to the application to change the fragment shading rate:

Additionally, these rates can all be specified and combined in order to adjust the overall detail in the image at each point.

This functionality can be used to focus shading efforts where higher levels of detail are needed in some parts of a scene compared to others. This can be particularly useful in high resolution rendering, or for XR contexts.

This extension also adds support for the SPV_KHR_fragment_shading_rate extension which enables setting the primitive fragment shading rate, and allows querying the final shading rate from a fragment shader.

New Commands

New Structures

New Enums

New Enum Constants

If VK_KHR_format_feature_flags2 is supported:

Version History

  • Revision 1, 2020-05-06 (Tobias Hector)

    • Initial revision
  • Revision 2, 2021-09-30 (Jon Leech)

    • Add interaction with VK_KHR_format_feature_flags2 to vk.xml

See Also

FragmentShadingRateAttachmentInfoKHR, FragmentShadingRateCombinerOpKHR, PhysicalDeviceFragmentShadingRateFeaturesKHR, PhysicalDeviceFragmentShadingRateKHR, PhysicalDeviceFragmentShadingRatePropertiesKHR, PipelineFragmentShadingRateStateCreateInfoKHR, cmdSetFragmentShadingRateKHR, getPhysicalDeviceFragmentShadingRatesKHR

Document Notes

For more information, see the Vulkan Specification

This page is a generated document. Fixes and changes should be made to the generator scripts, not directly.

Synopsis

Documentation

cmdSetFragmentShadingRateKHR Source #

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

vkCmdSetFragmentShadingRateKHR - Set pipeline fragment shading rate and combiner operation dynamically for a command buffer

Description

This command sets the pipeline fragment shading rate and combiner operation for subsequent drawing commands when drawing using shader objects, or when the graphics pipeline is created with DYNAMIC_STATE_FRAGMENT_SHADING_RATE_KHR set in PipelineDynamicStateCreateInfo::pDynamicStates. Otherwise, this state is specified by the PipelineFragmentShadingRateStateCreateInfoKHR values used to create the currently active pipeline.

Valid Usage

Valid Usage (Implicit)

  • pFragmentSize must be a valid pointer to a valid Extent2D structure
  • Each 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
  • This command must only be called outside of a video coding scope

Host Synchronization

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

Command Properties

'

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

See Also

VK_KHR_fragment_shading_rate, CommandBuffer, Extent2D, FragmentShadingRateCombinerOpKHR

getPhysicalDeviceFragmentShadingRatesKHR Source #

Arguments

:: forall io. MonadIO io 
=> PhysicalDevice

physicalDevice is the handle to the physical device whose properties will be queried.

-> io (Result, "fragmentShadingRates" ::: Vector PhysicalDeviceFragmentShadingRateKHR) 

vkGetPhysicalDeviceFragmentShadingRatesKHR - Get available shading rates for a physical device

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:

sampleCountsfragmentSize
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 and render pass transforms are supported for this rate.

The returned set of fragment shading rates must be returned in the native (rotated) coordinate system. For rasterization using render pass transform not equal to SURFACE_TRANSFORM_IDENTITY_BIT_KHR, the application must transform the returned fragment shading rates into the current (unrotated) coordinate system to get the supported rates for that transform.

Note

For example, consider an implementation returning support for 4x2, but not 2x4 in the set of supported fragment shading rates. This means that for transforms SURFACE_TRANSFORM_ROTATE_90_BIT_KHR and SURFACE_TRANSFORM_ROTATE_270_BIT_KHR, 2x4 is a supported rate, but 4x2 is an unsupported rate.

Valid Usage (Implicit)

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

See Also

VK_KHR_fragment_shading_rate, PhysicalDevice, PhysicalDeviceFragmentShadingRateKHR

data FragmentShadingRateAttachmentInfoKHR Source #

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

Description

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

Valid Usage

Valid Usage (Implicit)

  • If pFragmentShadingRateAttachment is not NULL, pFragmentShadingRateAttachment must be a valid pointer to a valid AttachmentReference2 structure

See Also

VK_KHR_fragment_shading_rate, AttachmentReference2, Extent2D, StructureType

Constructors

FragmentShadingRateAttachmentInfoKHR 

Fields

data PipelineFragmentShadingRateStateCreateInfoKHR Source #

VkPipelineFragmentShadingRateStateCreateInfoKHR - Structure specifying parameters controlling the fragment shading rate

Description

If the pNext chain of GraphicsPipelineCreateInfo includes a PipelineFragmentShadingRateStateCreateInfoKHR structure, then that structure includes parameters controlling 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)

See Also

VK_KHR_fragment_shading_rate, Extent2D, FragmentShadingRateCombinerOpKHR, StructureType

Constructors

PipelineFragmentShadingRateStateCreateInfoKHR 

Fields

Instances

Instances details
Storable PipelineFragmentShadingRateStateCreateInfoKHR Source # 
Instance details

Defined in Vulkan.Extensions.VK_KHR_fragment_shading_rate

Show PipelineFragmentShadingRateStateCreateInfoKHR Source # 
Instance details

Defined in Vulkan.Extensions.VK_KHR_fragment_shading_rate

FromCStruct PipelineFragmentShadingRateStateCreateInfoKHR Source # 
Instance details

Defined in Vulkan.Extensions.VK_KHR_fragment_shading_rate

ToCStruct PipelineFragmentShadingRateStateCreateInfoKHR Source # 
Instance details

Defined in Vulkan.Extensions.VK_KHR_fragment_shading_rate

Zero PipelineFragmentShadingRateStateCreateInfoKHR Source # 
Instance details

Defined in Vulkan.Extensions.VK_KHR_fragment_shading_rate

data PhysicalDeviceFragmentShadingRateFeaturesKHR Source #

VkPhysicalDeviceFragmentShadingRateFeaturesKHR - Structure indicating support for variable rate fragment shading

Members

This structure describes the following features:

Description

If the PhysicalDeviceFragmentShadingRateFeaturesKHR structure is included in the pNext chain of the PhysicalDeviceFeatures2 structure passed to getPhysicalDeviceFeatures2, it is filled in to indicate whether each corresponding feature is supported. PhysicalDeviceFragmentShadingRateFeaturesKHR can also be used in the pNext chain of DeviceCreateInfo to selectively enable these features.

Valid Usage (Implicit)

See Also

VK_KHR_fragment_shading_rate, Bool32, StructureType

Constructors

PhysicalDeviceFragmentShadingRateFeaturesKHR 

Fields

Instances

Instances details
Storable PhysicalDeviceFragmentShadingRateFeaturesKHR Source # 
Instance details

Defined in Vulkan.Extensions.VK_KHR_fragment_shading_rate

Show PhysicalDeviceFragmentShadingRateFeaturesKHR Source # 
Instance details

Defined in Vulkan.Extensions.VK_KHR_fragment_shading_rate

Eq PhysicalDeviceFragmentShadingRateFeaturesKHR Source # 
Instance details

Defined in Vulkan.Extensions.VK_KHR_fragment_shading_rate

FromCStruct PhysicalDeviceFragmentShadingRateFeaturesKHR Source # 
Instance details

Defined in Vulkan.Extensions.VK_KHR_fragment_shading_rate

ToCStruct PhysicalDeviceFragmentShadingRateFeaturesKHR Source # 
Instance details

Defined in Vulkan.Extensions.VK_KHR_fragment_shading_rate

Zero PhysicalDeviceFragmentShadingRateFeaturesKHR Source # 
Instance details

Defined in Vulkan.Extensions.VK_KHR_fragment_shading_rate

data PhysicalDeviceFragmentShadingRatePropertiesKHR Source #

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

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 the PhysicalDeviceProperties2 structure passed to getPhysicalDeviceProperties2, it is filled in with each corresponding implementation-dependent property.

These properties are related to fragment shading rates.

Valid Usage (Implicit)

See Also

VK_KHR_fragment_shading_rate, Bool32, Extent2D, SampleCountFlagBits, StructureType

Constructors

PhysicalDeviceFragmentShadingRatePropertiesKHR 

Fields

Instances

Instances details
Storable PhysicalDeviceFragmentShadingRatePropertiesKHR Source # 
Instance details

Defined in Vulkan.Extensions.VK_KHR_fragment_shading_rate

Show PhysicalDeviceFragmentShadingRatePropertiesKHR Source # 
Instance details

Defined in Vulkan.Extensions.VK_KHR_fragment_shading_rate

FromCStruct PhysicalDeviceFragmentShadingRatePropertiesKHR Source # 
Instance details

Defined in Vulkan.Extensions.VK_KHR_fragment_shading_rate

ToCStruct PhysicalDeviceFragmentShadingRatePropertiesKHR Source # 
Instance details

Defined in Vulkan.Extensions.VK_KHR_fragment_shading_rate

Zero PhysicalDeviceFragmentShadingRatePropertiesKHR Source # 
Instance details

Defined in Vulkan.Extensions.VK_KHR_fragment_shading_rate

data PhysicalDeviceFragmentShadingRateKHR Source #

VkPhysicalDeviceFragmentShadingRateKHR - Structure returning information about sample count specific additional multisampling capabilities

Valid Usage (Implicit)

See Also

VK_KHR_fragment_shading_rate, Extent2D, SampleCountFlags, StructureType, getPhysicalDeviceFragmentShadingRatesKHR

Constructors

PhysicalDeviceFragmentShadingRateKHR 

Fields

Instances

Instances details
Storable PhysicalDeviceFragmentShadingRateKHR Source # 
Instance details

Defined in Vulkan.Extensions.VK_KHR_fragment_shading_rate

Show PhysicalDeviceFragmentShadingRateKHR Source # 
Instance details

Defined in Vulkan.Extensions.VK_KHR_fragment_shading_rate

FromCStruct PhysicalDeviceFragmentShadingRateKHR Source # 
Instance details

Defined in Vulkan.Extensions.VK_KHR_fragment_shading_rate

ToCStruct PhysicalDeviceFragmentShadingRateKHR Source # 
Instance details

Defined in Vulkan.Extensions.VK_KHR_fragment_shading_rate

Zero PhysicalDeviceFragmentShadingRateKHR Source # 
Instance details

Defined in Vulkan.Extensions.VK_KHR_fragment_shading_rate

newtype FragmentShadingRateCombinerOpKHR Source #

VkFragmentShadingRateCombinerOpKHR - Control how fragment shading rates are combined

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.

See Also

VK_KHR_fragment_shading_rate, PipelineFragmentShadingRateEnumStateCreateInfoNV, PipelineFragmentShadingRateStateCreateInfoKHR, cmdSetFragmentShadingRateEnumNV, cmdSetFragmentShadingRateKHR

Bundled Patterns

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 specifies a combiner operation of combine(Axy,Bxy) = Axy*Bxy.

Instances

Instances details
Storable FragmentShadingRateCombinerOpKHR Source # 
Instance details

Defined in Vulkan.Extensions.VK_KHR_fragment_shading_rate

Read FragmentShadingRateCombinerOpKHR Source # 
Instance details

Defined in Vulkan.Extensions.VK_KHR_fragment_shading_rate

Show FragmentShadingRateCombinerOpKHR Source # 
Instance details

Defined in Vulkan.Extensions.VK_KHR_fragment_shading_rate

Eq FragmentShadingRateCombinerOpKHR Source # 
Instance details

Defined in Vulkan.Extensions.VK_KHR_fragment_shading_rate

Ord FragmentShadingRateCombinerOpKHR Source # 
Instance details

Defined in Vulkan.Extensions.VK_KHR_fragment_shading_rate

Zero FragmentShadingRateCombinerOpKHR Source # 
Instance details

Defined in Vulkan.Extensions.VK_KHR_fragment_shading_rate

type KHR_FRAGMENT_SHADING_RATE_EXTENSION_NAME = "VK_KHR_fragment_shading_rate" Source #