// Copyright 2021-2024 The Khronos Group Inc.
//
// SPDX-License-Identifier: CC-BY-4.0

= VK_EXT_extended_dynamic_state3
:toc: left
:refpage: https://www.khronos.org/registry/vulkan/specs/1.3-extensions/man/html/
:sectnums:

This document details the motivation behind another extended dynamic state extension, which follows VK_EXT_extended_dynamic_state and VK_EXT_extended_dynamic_state2.

== Problem Statement

Since the release of VK_EXT_extended_dynamic_state and VK_EXT_extended_dynamic_state2 in Vulkan 1.3, which made
more pipeline state dynamic, there is still some remaining pipeline state that cannot be changed dynamically.
Dynamic state helps applications reduce the number of pipelines they need to create and bind.
It was also noted that several extensions that add pipeline state lack dynamic state equivalents.

Reducing the amount of state required to build a pipeline can also help applications build pipelines ahead of time
and avoid hitching since that state might not be known until right before the draw command is recorded. By making it
dynamic there is less state that applications need to hash and cache for on-demand pipeline creation.

These additional dynamic states can also help pare down the pipeline state to help other extensions build on this
and potentially remove the need to create and bind linked monolithic pipeline objects at all.


== Solution Space

This proposal adds more dynamic state that hardware vendors can optionally implement, with enough in common
between most vendors to be useful for applications.
This extension also sets a baseline for a potential roadmap for future hardware to handle all dynamic state efficiently.

Some of the dynamic state added by this proposal may not have immediate benefits for applications
since the state could be constant throughout the application, but it is added anyway to
capture as much pipeline state as possible and lay a foundation for potentially doing away with linked
monolithic pipeline objects.

Adding more and more dynamic state by itself is not the solution to all pipeline problems, and this extension
does not attempt go beyond adding dynamic state to address those other problems.


== Proposal

IHVs should only implement support for the dynamic state below if it is efficient on their
platform. Feature bits are provided for all state so IHVs can implement any subset of
VK_EXT_extended_dynamic_state3.

=== New Dynamic State

This adds the following dynamic state:

VK_DYNAMIC_STATE_TESSELLATION_DOMAIN_ORIGIN_EXT::
  VkPipelineTessellationDomainOriginStateCreateInfo::domainOrigin
  * Assuming VkPhysicalDeviceFeatures::tessellationShader is enabled
  * Requires VK_KHR_maintenance2

VK_DYNAMIC_STATE_DEPTH_CLAMP_ENABLE_EXT::
  VkPipelineRasterizationStateCreateInfo::depthClampEnable
  * Assuming VkPhysicalDeviceFeatures::depthClamp is enabled

VK_DYNAMIC_STATE_POLYGON_MODE_EXT::
  VkPipelineRasterizationStateCreateInfo::polygonMode
  * Assuming VkPhysicalDeviceFeatures::fillModeNonSolid is enabled

VK_DYNAMIC_STATE_RASTERIZATION_SAMPLES_EXT::
  VkPipelineMultisampleStateCreateInfo::rasterizationSamples
  * There are restrictions on what values this can be set to
    based on the variableMultisampleRate feature, the render pass
    instance attachments, and the extensions
    VK_NV_framebuffer_mixed_samples and VK_AMD_mixed_attachment_samples.

VK_DYNAMIC_STATE_SAMPLE_MASK_EXT::
  VkPipelineMultisampleStateCreateInfo::pSampleMask

VK_DYNAMIC_STATE_ALPHA_TO_COVERAGE_ENABLE_EXT::
  VkPipelineMultisampleStateCreateInfo::alphaToCoverageEnable

VK_DYNAMIC_STATE_ALPHA_TO_ONE_ENABLE_EXT::
  VkPipelineMultisampleStateCreateInfo::alphaToOneEnable
  * Assuming VkPhysicalDeviceFeatures::alphaToOne is enabled

VK_DYNAMIC_STATE_LOGIC_OP_ENABLE_EXT::
  VkPipelineColorBlendStateCreateInfo::logicOpEnable
  * Assuming VkPhysicalDeviceFeatures::logicOp is enabled

VK_DYNAMIC_STATE_COLOR_BLEND_ENABLE_EXT::
  Per-attachment:
    - VkPipelineColorBlendAttachmentState::blendEnable

VK_DYNAMIC_STATE_COLOR_BLEND_EQUATION_EXT::
  Per-attachment:
    - VkPipelineColorBlendAttachmentState::srcColorBlendFactor
    - VkPipelineColorBlendAttachmentState::dstColorBlendFactor
    - VkPipelineColorBlendAttachmentState::colorBlendOp
    - VkPipelineColorBlendAttachmentState::srcAlphaBlendFactor
    - VkPipelineColorBlendAttachmentState::dstAlphaBlendFactor
    - VkPipelineColorBlendAttachmentState::alphaBlendOp

VK_DYNAMIC_STATE_COLOR_WRITE_MASK_EXT::
  Per-attachment:
    - VkPipelineColorBlendAttachmentState::colorWriteMask

VK_DYNAMIC_STATE_RASTERIZATION_STREAM_EXT::
  VkPipelineRasterizationStateStreamCreateInfoEXT::rasterizationStream
  * Assuming VkPhysicalDeviceTransformFeedbackFeaturesEXT::geometryStreams is enabled
  * Requires VK_EXT_transform_feedback

VK_DYNAMIC_STATE_CONSERVATIVE_RASTERIZATION_MODE_EXT::
  VkPipelineRasterizationConservativeStateCreateInfoEXT::conservativeRasterizationMode
  * Assuming VK_EXT_conservative_rasterization is enabled
  ** Also depends on VkPhysicalDeviceConservativeRasterizationPropertiesEXT::primitiveUnderestimation
  * Requires VK_EXT_conservative_rasterization

VK_DYNAMIC_STATE_EXTRA_PRIMITIVE_OVERESTIMATION_SIZE_EXT::
  VkPipelineRasterizationConservativeStateCreateInfoEXT::extraPrimitiveOverestimationSize
  * Assuming VK_EXT_conservative_rasterization is enabled
  * Requires VK_EXT_conservative_rasterization

VK_DYNAMIC_STATE_DEPTH_CLIP_ENABLE_EXT::
  VkPipelineRasterizationDepthClipStateCreateInfoEXT::depthClipEnable
  * Assuming VkPhysicalDeviceDepthClipEnableFeaturesEXT::depthClipEnable is enabled
  * Requires VK_EXT_depth_clip_enable

VK_DYNAMIC_STATE_SAMPLE_LOCATIONS_ENABLE_EXT::
  VkPipelineSampleLocationsStateCreateInfoEXT::sampleLocationsEnable
  * Assuming VK_EXT_sample_locations is enabled
  * Requires VK_EXT_sample_locations

VK_DYNAMIC_STATE_COLOR_BLEND_ADVANCED_EXT::
  Per-attachment:
    - VkPipelineColorBlendAttachmentState::colorBlendOp
    - VkPipelineColorBlendAdvancedStateCreateInfoEXT::srcPremultiplied
    - VkPipelineColorBlendAdvancedStateCreateInfoEXT::dstPremultiplied
    - VkPipelineColorBlendAdvancedStateCreateInfoEXT::blendOverlap
   * Requires VK_EXT_blend_operation_advanced

VK_DYNAMIC_STATE_PROVOKING_VERTEX_MODE_EXT::
  VkPipelineRasterizationProvokingVertexStateCreateInfoEXT::provokingVertexMode
  * Assuming VkPhysicalDeviceProvokingVertexFeaturesEXT::provokingVertexLast is enabled
  * Requires VK_EXT_provoking_vertex

VK_DYNAMIC_STATE_LINE_RASTERIZATION_MODE_EXT::
  VkPipelineRasterizationLineStateCreateInfoEXT::lineRasterizationMode
  * Assuming VK_EXT_line_rasterization is enabled
  * Requires VK_EXT_line_rasterization

VK_DYNAMIC_STATE_LINE_STIPPLE_ENABLE_EXT::
  VkPipelineRasterizationLineStateCreateInfoEXT::stippledLineEnable
  * Assuming VK_EXT_line_rasterization is enabled
  * Requires VK_EXT_line_rasterization

VK_DYNAMIC_STATE_DEPTH_CLIP_NEGATIVE_ONE_TO_ONE_EXT::
  VkPipelineViewportDepthClipControlCreateInfoEXT::negativeOneToOne
  * Assuming VkPhysicalDeviceDepthClipControlFeaturesEXT::depthClipControl is enabled
  * Requires VK_EXT_depth_clip_control

VK_DYNAMIC_STATE_VIEWPORT_W_SCALING_ENABLE_NV::
  VkPipelineViewportWScalingStateCreateInfoNV::viewportWScalingEnable
  * Assuming VK_NV_clip_space_w_scaling is enabled
  * Requires VK_NV_clip_space_w_scaling

VK_DYNAMIC_STATE_VIEWPORT_SWIZZLE_NV::
  VkPipelineViewportSwizzleStateCreateInfoNV::pViewportSwizzles
  * Assuming VK_NV_viewport_swizzle is enabled
  * Requires VK_NV_viewport_swizzle

VK_DYNAMIC_STATE_COVERAGE_TO_COLOR_ENABLE_NV::
  VkPipelineCoverageToColorStateCreateInfoNV::coverageToColorEnable
  * Assuming VK_NV_fragment_coverage_to_color is enabled
  * Requires VK_NV_fragment_coverage_to_color

VK_DYNAMIC_STATE_COVERAGE_TO_COLOR_LOCATION_NV::
  VkPipelineCoverageToColorStateCreateInfoNV::coverageToColorLocation
  * Assuming VK_NV_fragment_coverage_to_color is enabled
  * Requires VK_NV_fragment_coverage_to_color

VK_DYNAMIC_STATE_COVERAGE_MODULATION_MODE_NV::
  VkPipelineCoverageModulationStateCreateInfoNV::coverageModulationMode
  * Assuming VK_NV_framebuffer_mixed_samples is enabled
  * Requires VK_NV_framebuffer_mixed_samples

VK_DYNAMIC_STATE_COVERAGE_MODULATION_TABLE_ENABLE_NV::
  VkPipelineCoverageModulationStateCreateInfoNV::coverageModulationTableEnable
  * Assuming VK_NV_framebuffer_mixed_samples is enabled
  * Requires VK_NV_framebuffer_mixed_samples

VK_DYNAMIC_STATE_COVERAGE_MODULATION_TABLE_NV::
  VkPipelineCoverageModulationStateCreateInfoNV::pCoverageModulationTable
  * Assuming VK_NV_framebuffer_mixed_samples is enabled
  * Requires VK_NV_framebuffer_mixed_samples

VK_DYNAMIC_STATE_COVERAGE_REDUCTION_MODE_NV::
  VkPipelineCoverageReductionStateCreateInfoNV::coverageReductionMode
  * Assuming VkPhysicalDeviceCoverageReductionModeFeaturesNV::coverageReductionMode is enabled
  * Requires VK_NV_coverage_reduction_mode

VK_DYNAMIC_STATE_REPRESENTATIVE_FRAGMENT_TEST_ENABLE_NV::
  VkPipelineRepresentativeFragmentTestStateCreateInfoNV::representativeFragmentTestEnable
  * Assuming VkPhysicalDeviceRepresentativeFragmentTestFeaturesNV::representativeFragmentTest is enabled
  * Requires VK_NV_representative_fragment_test

VK_DYNAMIC_STATE_SHADING_RATE_IMAGE_ENABLE_NV::
  VkPipelineViewportShadingRateImageStateCreateInfoNV::shadingRateImageEnable
  * Assuming VkPhysicalDeviceShadingRateImageFeaturesNV::shadingRateImage is enabled
  * Requires VK_NV_shading_rate_image


=== New Properties

VkPhysicalDeviceExtendedDynamicState3PropertiesEXT::dynamicPrimitiveTopologyUnrestricted::
  Indicates that VkPipelineInputAssemblyStateCreateInfo::topology is ignored when
  VK_DYNAMIC_STATE_PRIMITIVE_TOPOLOGY_EXT is enabled, and the application can set any
  primitive topology in any primitive topology class with vkCmdSetPrimitiveTopology.
