1// Copyright 2015-2022 The Khronos Group Inc. 2// 3// SPDX-License-Identifier: CC-BY-4.0 4 5[[primsrast]] 6= Rasterization 7 8Rasterization is the process by which a primitive is converted to a 9two-dimensional image. 10Each discrete location of this image contains associated data such as depth, 11color, or other attributes. 12 13Rasterizing a primitive begins by determining which squares of an integer 14grid in framebuffer coordinates are occupied by the primitive, and assigning 15one or more depth values to each such square. 16This process is described below for points, lines, and polygons. 17 18A grid square, including its [eq]#(x,y)# framebuffer coordinates, [eq]#z# 19(depth), and associated data added by fragment shaders, is called a 20fragment. 21A fragment is located by its upper left corner, which lies on integer grid 22coordinates. 23 24Rasterization operations also refer to a fragment's sample locations, which 25are offset by fractional values from its upper left corner. 26The rasterization rules for points, lines, and triangles involve testing 27whether each sample location is inside the primitive. 28Fragments need not actually be square, and rasterization rules are not 29affected by the aspect ratio of fragments. 30Display of non-square grids, however, will cause rasterized points and line 31segments to appear fatter in one direction than the other. 32 33We assume that fragments are square, since it simplifies antialiasing and 34texturing. 35After rasterization, fragments are processed by <<fragops, fragment 36operations>>. 37 38Several factors affect rasterization, including the members of 39slink:VkPipelineRasterizationStateCreateInfo and 40slink:VkPipelineMultisampleStateCreateInfo. 41 42[open,refpage='VkPipelineRasterizationStateCreateInfo',desc='Structure specifying parameters of a newly created pipeline rasterization state',type='structs'] 43-- 44The sname:VkPipelineRasterizationStateCreateInfo structure is defined as: 45 46include::{generated}/api/structs/VkPipelineRasterizationStateCreateInfo.adoc[] 47 48 * pname:sType is the type of this structure. 49 * pname:pNext is `NULL` or a pointer to a structure extending this 50 structure. 51 * pname:flags is reserved for future use. 52 * pname:depthClampEnable controls whether to clamp the fragment's depth 53 values as described in <<fragops-depth,Depth Test>>. 54ifdef::VK_EXT_depth_clip_enable[] 55 If the pipeline is not created with 56 slink:VkPipelineRasterizationDepthClipStateCreateInfoEXT present then 57 enabling depth clamp will also disable clipping primitives to the z 58 planes of the frustrum as described in <<vertexpostproc-clipping, 59 Primitive Clipping>>. 60 Otherwise depth clipping is controlled by the state set in 61 slink:VkPipelineRasterizationDepthClipStateCreateInfoEXT. 62endif::VK_EXT_depth_clip_enable[] 63ifndef::VK_EXT_depth_clip_enable[] 64 Enabling depth clamp will also disable clipping primitives to the z 65 planes of the frustrum as described in <<vertexpostproc-clipping, 66 Primitive Clipping>>. 67endif::VK_EXT_depth_clip_enable[] 68 * pname:rasterizerDiscardEnable controls whether primitives are discarded 69 immediately before the rasterization stage. 70 * pname:polygonMode is the triangle rendering mode. 71 See elink:VkPolygonMode. 72 * pname:cullMode is the triangle facing direction used for primitive 73 culling. 74 See elink:VkCullModeFlagBits. 75 * pname:frontFace is a elink:VkFrontFace value specifying the front-facing 76 triangle orientation to be used for culling. 77 * pname:depthBiasEnable controls whether to bias fragment depth values. 78 * pname:depthBiasConstantFactor is a scalar factor controlling the 79 constant depth value added to each fragment. 80 * pname:depthBiasClamp is the maximum (or minimum) depth bias of a 81 fragment. 82 * pname:depthBiasSlopeFactor is a scalar factor applied to a fragment's 83 slope in depth bias calculations. 84 * pname:lineWidth is the width of rasterized line segments. 85 86ifdef::VK_AMD_rasterization_order[] 87The application can: also add a 88sname:VkPipelineRasterizationStateRasterizationOrderAMD structure to the 89pname:pNext chain of a slink:VkPipelineRasterizationStateCreateInfo 90structure. 91This structure enables selecting the rasterization order to use when 92rendering with the corresponding graphics pipeline as described in 93<<primsrast-order, Rasterization Order>>. 94endif::VK_AMD_rasterization_order[] 95 96.Valid Usage 97**** 98 * [[VUID-VkPipelineRasterizationStateCreateInfo-depthClampEnable-00782]] 99 If the <<features-depthClamp, pname:depthClamp>> feature is not enabled, 100 pname:depthClampEnable must: be ename:VK_FALSE 101ifndef::VK_NV_fill_rectangle[] 102 * [[VUID-VkPipelineRasterizationStateCreateInfo-polygonMode-01413]] 103 If the <<features-fillModeNonSolid, pname:fillModeNonSolid>> feature is 104 not enabled, pname:polygonMode must: be ename:VK_POLYGON_MODE_FILL 105endif::VK_NV_fill_rectangle[] 106ifdef::VK_NV_fill_rectangle[] 107 * [[VUID-VkPipelineRasterizationStateCreateInfo-polygonMode-01507]] 108 If the <<features-fillModeNonSolid, pname:fillModeNonSolid>> feature is 109 not enabled, pname:polygonMode must: be ename:VK_POLYGON_MODE_FILL or 110 ename:VK_POLYGON_MODE_FILL_RECTANGLE_NV 111 * [[VUID-VkPipelineRasterizationStateCreateInfo-polygonMode-01414]] 112 If the `apiext:VK_NV_fill_rectangle` extension is not enabled, 113 pname:polygonMode must: not be ename:VK_POLYGON_MODE_FILL_RECTANGLE_NV 114endif::VK_NV_fill_rectangle[] 115ifdef::VK_KHR_portability_subset[] 116 * [[VUID-VkPipelineRasterizationStateCreateInfo-pointPolygons-04458]] 117 If the `apiext:VK_KHR_portability_subset` extension is enabled, and 118 slink:VkPhysicalDevicePortabilitySubsetFeaturesKHR::pname:pointPolygons 119 is ename:VK_FALSE, and pname:rasterizerDiscardEnable is ename:VK_FALSE, 120 pname:polygonMode must: not be ename:VK_POLYGON_MODE_POINT 121endif::VK_KHR_portability_subset[] 122**** 123 124include::{generated}/validity/structs/VkPipelineRasterizationStateCreateInfo.adoc[] 125-- 126 127[open,refpage='VkPipelineRasterizationStateCreateFlags',desc='Reserved for future use',type='flags'] 128-- 129include::{generated}/api/flags/VkPipelineRasterizationStateCreateFlags.adoc[] 130 131tname:VkPipelineRasterizationStateCreateFlags is a bitmask type for setting 132a mask, but is currently reserved for future use. 133-- 134 135ifdef::VK_EXT_depth_clip_enable[] 136[open,refpage='VkPipelineRasterizationDepthClipStateCreateInfoEXT',desc='Structure specifying depth clipping state',type='structs'] 137-- 138If the pname:pNext chain of slink:VkPipelineRasterizationStateCreateInfo 139includes a sname:VkPipelineRasterizationDepthClipStateCreateInfoEXT 140structure, then that structure controls whether depth clipping is enabled or 141disabled. 142 143The sname:VkPipelineRasterizationDepthClipStateCreateInfoEXT structure is 144defined as: 145 146include::{generated}/api/structs/VkPipelineRasterizationDepthClipStateCreateInfoEXT.adoc[] 147 148 * pname:sType is the type of this structure. 149 * pname:pNext is `NULL` or a pointer to a structure extending this 150 structure. 151 * pname:flags is reserved for future use. 152 * pname:depthClipEnable controls whether depth clipping is enabled as 153 described in <<vertexpostproc-clipping, Primitive Clipping>>. 154 155include::{generated}/validity/structs/VkPipelineRasterizationDepthClipStateCreateInfoEXT.adoc[] 156-- 157 158[open,refpage='VkPipelineRasterizationDepthClipStateCreateFlagsEXT',desc='Reserved for future use',type='flags'] 159-- 160include::{generated}/api/flags/VkPipelineRasterizationDepthClipStateCreateFlagsEXT.adoc[] 161 162tname:VkPipelineRasterizationDepthClipStateCreateFlagsEXT is a bitmask type 163for setting a mask, but is currently reserved for future use. 164-- 165endif::VK_EXT_depth_clip_enable[] 166 167[open,refpage='VkPipelineMultisampleStateCreateInfo',desc='Structure specifying parameters of a newly created pipeline multisample state',type='structs'] 168-- 169The sname:VkPipelineMultisampleStateCreateInfo structure is defined as: 170 171include::{generated}/api/structs/VkPipelineMultisampleStateCreateInfo.adoc[] 172 173 * pname:sType is the type of this structure. 174 * pname:pNext is `NULL` or a pointer to a structure extending this 175 structure. 176 * pname:flags is reserved for future use. 177 * pname:rasterizationSamples is a elink:VkSampleCountFlagBits value 178 specifying the number of samples used in rasterization. 179ifdef::VK_EXT_extended_dynamic_state3[] 180 This value is ignored for the purposes of setting the number of samples 181 used in rasterization if the pipeline is created with the 182 ename:VK_DYNAMIC_STATE_RASTERIZATION_SAMPLES_EXT dynamic state set, but 183 if ename:VK_DYNAMIC_STATE_SAMPLE_MASK_EXT dynamic state is not set, it 184 is still used to define the size of the pname:pSampleMask array as 185 described below. 186endif::VK_EXT_extended_dynamic_state3[] 187 * pname:sampleShadingEnable can: be used to enable 188 <<primsrast-sampleshading,Sample Shading>>. 189 * pname:minSampleShading specifies a minimum fraction of sample shading if 190 pname:sampleShadingEnable is set to ename:VK_TRUE. 191 * pname:pSampleMask is a pointer to an array of basetype:VkSampleMask 192 values used in the <<fragops-samplemask,sample mask test>>. 193 * pname:alphaToCoverageEnable controls whether a temporary coverage value 194 is generated based on the alpha component of the fragment's first color 195 output as specified in the <<fragops-covg,Multisample Coverage>> 196 section. 197 * pname:alphaToOneEnable controls whether the alpha component of the 198 fragment's first color output is replaced with one as described in 199 <<fragops-covg,Multisample Coverage>>. 200 201Each bit in the sample mask is associated with a unique 202<<primsrast-multisampling-coverage-mask, sample index>> as defined for the 203<<primsrast-multisampling-coverage-mask, coverage mask>>. 204Each bit [eq]#b# for mask word [eq]#w# in the sample mask corresponds to 205sample index [eq]#i#, where [eq]#i = 32 {times} w {plus} b#. 206pname:pSampleMask has a length equal to [eq]#{lceil} 207pname:rasterizationSamples / 32 {rceil}# words. 208 209If pname:pSampleMask is `NULL`, it is treated as if the mask has all bits 210set to `1`. 211 212.Valid Usage 213**** 214 * [[VUID-VkPipelineMultisampleStateCreateInfo-sampleShadingEnable-00784]] 215 If the <<features-sampleRateShading, pname:sampleRateShading>> feature 216 is not enabled, pname:sampleShadingEnable must: be ename:VK_FALSE 217 * [[VUID-VkPipelineMultisampleStateCreateInfo-alphaToOneEnable-00785]] 218 If the <<features-alphaToOne, pname:alphaToOne>> feature is not enabled, 219 pname:alphaToOneEnable must: be ename:VK_FALSE 220 * [[VUID-VkPipelineMultisampleStateCreateInfo-minSampleShading-00786]] 221 pname:minSampleShading must: be in the range [eq]#[0,1]# 222ifdef::VK_NV_framebuffer_mixed_samples[] 223 * [[VUID-VkPipelineMultisampleStateCreateInfo-rasterizationSamples-01415]] 224 If the `apiext:VK_NV_framebuffer_mixed_samples` extension is enabled, 225 and if the subpass has any color attachments and 226 pname:rasterizationSamples is greater than the number of color samples, 227 then pname:sampleShadingEnable must: be ename:VK_FALSE 228endif::VK_NV_framebuffer_mixed_samples[] 229**** 230 231include::{generated}/validity/structs/VkPipelineMultisampleStateCreateInfo.adoc[] 232-- 233 234[open,refpage='VkPipelineMultisampleStateCreateFlags',desc='Reserved for future use',type='flags'] 235-- 236include::{generated}/api/flags/VkPipelineMultisampleStateCreateFlags.adoc[] 237 238tname:VkPipelineMultisampleStateCreateFlags is a bitmask type for setting a 239mask, but is currently reserved for future use. 240-- 241 242[open,refpage='VkSampleMask',desc='Mask of sample coverage information',type='basetypes',xrefs='VkPipelineMultisampleStateCreateInfo'] 243-- 244The elements of the sample mask array are of type basetype:VkSampleMask, 245each representing 32 bits of coverage information: 246 247include::{generated}/api/basetypes/VkSampleMask.adoc[] 248-- 249 250Rasterization only generates fragments which cover one or more pixels inside 251the framebuffer. 252Pixels outside the framebuffer are never considered covered in the fragment. 253Fragments which would be produced by application of any of the primitive 254rasterization rules described below but which lie outside the framebuffer 255are not produced, nor are they processed by any later stage of the pipeline, 256including any of the <<fragops, fragment operations>>. 257 258Surviving fragments are processed by fragment shaders. 259Fragment shaders determine associated data for fragments, and can: also 260modify or replace their assigned depth values. 261 262 263[[primsrast-discard]] 264== Discarding Primitives Before Rasterization 265 266Primitives are discarded before rasterization if the 267pname:rasterizerDiscardEnable member of 268slink:VkPipelineRasterizationStateCreateInfo is enabled. 269When enabled, primitives are discarded after they are processed by the last 270active shader stage in the pipeline before rasterization. 271 272ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state2[] 273[open,refpage='vkCmdSetRasterizerDiscardEnable',desc='Control whether primitives are discarded before the rasterization stage dynamically for a command buffer',type='protos',alias='vkCmdSetRasterizerDiscardEnableEXT'] 274-- 275To <<pipelines-dynamic-state, dynamically enable>> whether primitives are 276discarded before the rasterization stage, call: 277 278ifdef::VK_VERSION_1_3[] 279include::{generated}/api/protos/vkCmdSetRasterizerDiscardEnable.adoc[] 280endif::VK_VERSION_1_3[] 281 282ifdef::VK_VERSION_1_3+VK_EXT_extended_dynamic_state2[or the equivalent command] 283 284ifdef::VK_EXT_extended_dynamic_state2[] 285include::{generated}/api/protos/vkCmdSetRasterizerDiscardEnableEXT.adoc[] 286endif::VK_EXT_extended_dynamic_state2[] 287 288 * pname:commandBuffer is the command buffer into which the command will be 289 recorded. 290 * pname:rasterizerDiscardEnable controls whether primitives are discarded 291 immediately before the rasterization stage. 292 293This command sets the discard enable for subsequent drawing commands when 294the graphics pipeline is created with 295ename:VK_DYNAMIC_STATE_RASTERIZER_DISCARD_ENABLE set in 296slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. 297Otherwise, this state is specified by the 298slink:VkPipelineRasterizationStateCreateInfo::pname:rasterizerDiscardEnable 299value used to create the currently active pipeline. 300 301ifndef::VK_VERSION_1_3[] 302.Valid Usage 303**** 304 * [[VUID-vkCmdSetRasterizerDiscardEnable-None-04871]] 305 The <<features-extendedDynamicState2, pname:extendedDynamicState2>> 306 feature must: be enabled 307**** 308endif::VK_VERSION_1_3[] 309 310include::{generated}/validity/protos/vkCmdSetRasterizerDiscardEnable.adoc[] 311-- 312endif::VK_VERSION_1_3,VK_EXT_extended_dynamic_state2[] 313 314 315ifdef::VK_EXT_transform_feedback[] 316[[primsrast-stream]] 317== Controlling the Vertex Stream Used for Rasterization 318 319By default vertex data output from the last 320<<pipelines-graphics-subsets-pre-rasterization,pre-rasterization shader 321stage>> are directed to vertex stream zero. 322Geometry shaders can: emit primitives to multiple independent vertex 323streams. 324Each vertex emitted by the geometry shader is directed at one of the vertex 325streams. 326As vertices are received on each vertex stream, they are arranged into 327primitives of the type specified by the geometry shader output primitive 328type. 329The shading language instructions code:OpEndPrimitive and 330code:OpEndStreamPrimitive can: be used to end the primitive being assembled 331on a given vertex stream and start a new empty primitive of the same type. 332An implementation supports up to 333sname:VkPhysicalDeviceTransformFeedbackPropertiesEXT::pname:maxTransformFeedbackStreams 334streams, which is at least 1. 335The individual streams are numbered 0 through 336pname:maxTransformFeedbackStreams minus 1. 337There is no requirement on the order of the streams to which vertices are 338emitted, and the number of vertices emitted to each vertex stream can: be 339completely independent, subject only to the 340sname:VkPhysicalDeviceTransformFeedbackPropertiesEXT::pname:maxTransformFeedbackStreamDataSize 341and 342sname:VkPhysicalDeviceTransformFeedbackPropertiesEXT::pname:maxTransformFeedbackBufferDataSize 343limits. 344The primitives output from all vertex streams are passed to the transform 345feedback stage to be captured to transform feedback buffers in the manner 346specified by the last 347<<pipelines-graphics-subsets-pre-rasterization,pre-rasterization shader 348stage>> shader's code:XfbBuffer, code:XfbStride, and code:Offsets 349decorations on the output interface variables in the graphics pipeline. 350To use a vertex stream other than zero, or to use multiple streams, the 351code:GeometryStreams capability must: be specified. 352 353By default, the primitives output from vertex stream zero are rasterized. 354If the implementation supports the 355slink:VkPhysicalDeviceTransformFeedbackPropertiesEXT::pname:transformFeedbackRasterizationStreamSelect 356property it is possible to rasterize a vertex stream other than zero. 357 358By default, geometry shaders that emit vertices to multiple vertex streams 359are limited to using only the code:OutputPoints output primitive type. 360If the implementation supports the 361slink:VkPhysicalDeviceTransformFeedbackPropertiesEXT::pname:transformFeedbackStreamsLinesTriangles 362property it is possible to emit code:OutputLineStrip or 363code:OutputTriangleStrip in addition to code:OutputPoints. 364 365[open,refpage='VkPipelineRasterizationStateStreamCreateInfoEXT',desc='Structure defining the geometry stream used for rasterization',type='structs'] 366-- 367The vertex stream used for rasterization is specified by adding a 368sname:VkPipelineRasterizationStateStreamCreateInfoEXT structure to the 369pname:pNext chain of a slink:VkPipelineRasterizationStateCreateInfo 370structure. 371 372The sname:VkPipelineRasterizationStateStreamCreateInfoEXT structure is 373defined as: 374 375include::{generated}/api/structs/VkPipelineRasterizationStateStreamCreateInfoEXT.adoc[] 376 377 * pname:sType is the type of this structure. 378 * pname:pNext is `NULL` or a pointer to a structure extending this 379 structure. 380 * pname:flags is reserved for future use. 381 * pname:rasterizationStream is the vertex stream selected for 382 rasterization. 383 384If this structure is not present, pname:rasterizationStream is assumed to be 385zero. 386 387.Valid Usage 388**** 389 * [[VUID-VkPipelineRasterizationStateStreamCreateInfoEXT-geometryStreams-02324]] 390 sname:VkPhysicalDeviceTransformFeedbackFeaturesEXT::pname:geometryStreams 391 must: be enabled 392 * [[VUID-VkPipelineRasterizationStateStreamCreateInfoEXT-rasterizationStream-02325]] 393 pname:rasterizationStream must: be less than 394 slink:VkPhysicalDeviceTransformFeedbackPropertiesEXT::pname:maxTransformFeedbackStreams 395 * [[VUID-VkPipelineRasterizationStateStreamCreateInfoEXT-rasterizationStream-02326]] 396 pname:rasterizationStream must: be zero if 397 sname:VkPhysicalDeviceTransformFeedbackPropertiesEXT::pname:transformFeedbackRasterizationStreamSelect 398 is ename:VK_FALSE 399**** 400 401include::{generated}/validity/structs/VkPipelineRasterizationStateStreamCreateInfoEXT.adoc[] 402-- 403 404[open,refpage='VkPipelineRasterizationStateStreamCreateFlagsEXT',desc='Reserved for future use',type='flags'] 405-- 406include::{generated}/api/flags/VkPipelineRasterizationStateStreamCreateFlagsEXT.adoc[] 407 408tname:VkPipelineRasterizationStateStreamCreateFlagsEXT is a bitmask type for 409setting a mask, but is currently reserved for future use. 410-- 411 412ifdef::VK_EXT_extended_dynamic_state3[] 413[open,refpage='vkCmdSetRasterizationStreamEXT',desc='Specify the rasterization stream dynamically for a command buffer',type='protos'] 414-- 415To <<pipelines-dynamic-state, dynamically set>> the 416pname:rasterizationStream state, call: 417 418include::{generated}/api/protos/vkCmdSetRasterizationStreamEXT.adoc[] 419 420 * pname:commandBuffer is the command buffer into which the command will be 421 recorded. 422 * pname:rasterizationStream specifies the pname:rasterizationStream state. 423 424This command sets the pname:rasterizationStream state for subsequent drawing 425commands when the graphics pipeline is created with 426ename:VK_DYNAMIC_STATE_RASTERIZATION_STREAM_EXT set in 427slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. 428Otherwise, this state is specified by the 429slink:VkPipelineRasterizationStateStreamCreateInfoEXT::pname:rasterizationStream 430value used to create the currently active pipeline. 431 432.Valid Usage 433**** 434 * [[VUID-vkCmdSetRasterizationStreamEXT-extendedDynamicState3RasterizationStream-07410]] 435 The <<features-extendedDynamicState3RasterizationStream, 436 pname:extendedDynamicState3RasterizationStream>> feature must: be 437 enabled 438 * [[VUID-vkCmdSetRasterizationStreamEXT-transformFeedback-07411]] 439 The <<features-transformFeedback, pname:transformFeedback>> feature 440 must: be enabled 441 * [[VUID-vkCmdSetRasterizationStreamEXT-rasterizationStream-07412]] 442 pname:rasterizationStream must: be less than 443 slink:VkPhysicalDeviceTransformFeedbackPropertiesEXT::pname:maxTransformFeedbackStreams 444 * [[VUID-vkCmdSetRasterizationStreamEXT-rasterizationStream-07413]] 445 pname:rasterizationStream must: be zero if 446 sname:VkPhysicalDeviceTransformFeedbackPropertiesEXT::pname:transformFeedbackRasterizationStreamSelect 447 is ename:VK_FALSE 448**** 449 450include::{generated}/validity/protos/vkCmdSetRasterizationStreamEXT.adoc[] 451-- 452endif::VK_EXT_extended_dynamic_state3[] 453endif::VK_EXT_transform_feedback[] 454 455 456[[primsrast-order]] 457== Rasterization Order 458 459Within a subpass of a <<renderpass,render pass instance>>, for a given 460(x,y,layer,sample) sample location, the following operations are guaranteed 461to execute in _rasterization order_, for each separate primitive that 462includes that sample location: 463 464 . <<fragops, Fragment operations>>, in the order defined 465 . <<framebuffer-blending, Blending>>, <<framebuffer-logicop, logic 466 operations>>, and color writes 467 468Execution of these operations for each primitive in a subpass occurs in 469ifndef::VK_AMD_rasterization_order[] 470<<drawing-primitive-order, primitive order>>. 471endif::VK_AMD_rasterization_order[] 472ifdef::VK_AMD_rasterization_order[] 473an order determined by the application. 474 475[open,refpage='VkPipelineRasterizationStateRasterizationOrderAMD',desc='Structure defining rasterization order for a graphics pipeline',type='structs'] 476-- 477The rasterization order to use for a graphics pipeline is specified by 478adding a sname:VkPipelineRasterizationStateRasterizationOrderAMD structure 479to the pname:pNext chain of a slink:VkPipelineRasterizationStateCreateInfo 480structure. 481 482The sname:VkPipelineRasterizationStateRasterizationOrderAMD structure is 483defined as: 484 485include::{generated}/api/structs/VkPipelineRasterizationStateRasterizationOrderAMD.adoc[] 486 487 * pname:sType is the type of this structure. 488 * pname:pNext is `NULL` or a pointer to a structure extending this 489 structure. 490 * pname:rasterizationOrder is a elink:VkRasterizationOrderAMD value 491 specifying the primitive rasterization order to use. 492 493include::{generated}/validity/structs/VkPipelineRasterizationStateRasterizationOrderAMD.adoc[] 494 495If the `apiext:VK_AMD_rasterization_order` device extension is not enabled 496or the application does not request a particular rasterization order through 497specifying a sname:VkPipelineRasterizationStateRasterizationOrderAMD 498structure then the rasterization order used by the graphics pipeline 499defaults to ename:VK_RASTERIZATION_ORDER_STRICT_AMD. 500-- 501 502[open,refpage='VkRasterizationOrderAMD',desc='Specify rasterization order for a graphics pipeline',type='enums'] 503-- 504Possible values of 505slink:VkPipelineRasterizationStateRasterizationOrderAMD::pname:rasterizationOrder, 506specifying the primitive rasterization order, are: 507 508include::{generated}/api/enums/VkRasterizationOrderAMD.adoc[] 509 510 * ename:VK_RASTERIZATION_ORDER_STRICT_AMD specifies that operations for 511 each primitive in a subpass must: occur in <<drawing-primitive-order, 512 primitive order>>. 513 * ename:VK_RASTERIZATION_ORDER_RELAXED_AMD specifies that operations for 514 each primitive in a subpass may: not occur in <<drawing-primitive-order, 515 primitive order>>. 516-- 517endif::VK_AMD_rasterization_order[] 518 519 520[[primsrast-multisampling]] 521== Multisampling 522 523Multisampling is a mechanism to antialias all Vulkan primitives: points, 524lines, and polygons. 525The technique is to sample all primitives multiple times at each pixel. 526Each sample in each framebuffer attachment has storage for a color, depth, 527and/or stencil value, such that per-fragment operations apply to each sample 528independently. 529The color sample values can: be later _resolved_ to a single color (see 530<<copies-resolve,Resolving Multisample Images>> and the <<renderpass,Render 531Pass>> chapter for more details on how to resolve multisample images to 532non-multisample images). 533 534Vulkan defines rasterization rules for single-sample modes in a way that is 535equivalent to a multisample mode with a single sample in the center of each 536fragment. 537 538Each fragment includes a <<primsrast-multisampling-coverage-mask, coverage 539mask>> with a single bit for each sample in the fragment, and a number of 540depth values and associated data for each sample. 541 542It is understood that each pixel has pname:rasterizationSamples locations 543associated with it. 544These locations are exact positions, rather than regions or areas, and each 545is referred to as a sample point. 546The sample points associated with a pixel must: be located inside or on the 547boundary of the unit square that is considered to bound the pixel. 548Furthermore, the relative locations of sample points may: be identical for 549each pixel in the framebuffer, or they may: differ. 550 551ifdef::VK_EXT_fragment_density_map[] 552If the render pass has a fragment density map attachment, each fragment only 553has pname:rasterizationSamples locations associated with it regardless of 554how many pixels are covered in the fragment area. 555Fragment sample locations are defined as if the fragment had an area of 556[eq]#(1,1)# and its sample points must: be located within these bounds. 557Their actual location in the framebuffer is calculated by scaling the sample 558location by the fragment area. 559Attachments with storage for multiple samples per pixel are located at the 560pixel sample locations. 561Otherwise, the fragment's sample locations are generally used for evaluation 562of associated data and fragment operations. 563endif::VK_EXT_fragment_density_map[] 564 565If the current pipeline includes a fragment shader with one or more 566variables in its interface decorated with code:Sample and code:Input, the 567data associated with those variables will be assigned independently for each 568sample. 569The values for each sample must: be evaluated at the location of the sample. 570The data associated with any other variables not decorated with code:Sample 571and code:Input need not be evaluated independently for each sample. 572 573[[primsrast-multisampling-coverage-mask]] 574A _coverage mask_ is generated for each fragment, based on which samples 575within that fragment are determined to be within the area of the primitive 576that generated the fragment. 577 578Single pixel fragments 579ifdef::VK_EXT_fragment_density_map[] 580and multi-pixel fragments defined by a 581<<renderpass-fragmentdensitymapattachment, fragment density map>> 582endif::VK_EXT_fragment_density_map[] 583have one set of samples. 584ifdef::VK_NV_shading_rate_image[] 585Multi-pixel fragments defined by a <<primsrast-shading-rate-image, shading 586rate image>> have one set of samples per pixel. 587endif::VK_NV_shading_rate_image[] 588ifdef::VK_KHR_fragment_shading_rate[] 589Multi-pixel fragments defined by setting the 590<<primsrast-fragment-shading-rate, fragment shading rate>> have one set of 591samples per pixel. 592endif::VK_KHR_fragment_shading_rate[] 593Each set of samples has a number of samples determined by 594slink:VkPipelineMultisampleStateCreateInfo::pname:rasterizationSamples. 595Each sample in a set is assigned a unique _sample index_ [eq]#i# in the 596range [eq]#[0, pname:rasterizationSamples)#. 597 598ifdef::VK_EXT_extended_dynamic_state3[] 599[open,refpage='vkCmdSetRasterizationSamplesEXT',desc='Specify the rasterization samples dynamically for a command buffer',type='protos'] 600-- 601To <<pipelines-dynamic-state, dynamically set>> the 602pname:rasterizationSamples, call: 603 604include::{generated}/api/protos/vkCmdSetRasterizationSamplesEXT.adoc[] 605 606 * pname:commandBuffer is the command buffer into which the command will be 607 recorded. 608 * pname:rasterizationSamples specifies pname:rasterizationSamples. 609 610This command sets the pname:rasterizationSamples for subsequent drawing 611commands when the graphics pipeline is created with 612ename:VK_DYNAMIC_STATE_RASTERIZATION_SAMPLES_EXT set in 613slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. 614Otherwise, this state is specified by the 615slink:VkPipelineMultisampleStateCreateInfo::pname:rasterizationSamples value 616used to create the currently active pipeline. 617 618.Valid Usage 619**** 620 * [[VUID-vkCmdSetRasterizationSamplesEXT-extendedDynamicState3RasterizationSamples-07414]] 621 The <<features-extendedDynamicState3RasterizationSamples, 622 pname:extendedDynamicState3RasterizationSamples>> feature must: be 623 enabled 624**** 625 626include::{generated}/validity/protos/vkCmdSetRasterizationSamplesEXT.adoc[] 627-- 628endif::VK_EXT_extended_dynamic_state3[] 629 630Each sample in a fragment is also assigned a unique _coverage index_ [eq]#j# 631in the range [eq]#[0, n {times} pname:rasterizationSamples)#, where [eq]#n# 632is the number of sets in the fragment. 633If the fragment contains a single set of samples, the _coverage index_ is 634always equal to the _sample index_. 635ifdef::VK_NV_shading_rate_image[] 636If a <<primsrast-shading-rate-image,shading rate image>> is used and a 637fragment covers multiple pixels, the coverage index is determined as defined 638by slink:VkPipelineViewportCoarseSampleOrderStateCreateInfoNV or 639flink:vkCmdSetCoarseSampleOrderNV. 640endif::VK_NV_shading_rate_image[] 641 642ifdef::VK_KHR_fragment_shading_rate[] 643[[primsrast-multisampling-coverage-mask-vrfs]] 644If the <<primsrast-fragment-shading-rate, fragment shading rate>> is set, 645the coverage index [eq]#j# is determined as a function of the _pixel index_ 646[eq]#p#, the _sample index_ [eq]#i#, and the number of rasterization samples 647[eq]#r# as: 648 649 {empty}:: [eq]#j = i + r {times} ((f~w~ {times} f~h~) - 1 - p)# 650 651where the pixel index [eq]#p# is determined as a function of the pixel's 652framebuffer location [eq]#(x,y)# and the fragment size [eq]#(f~w~,f~h~)#: 653 654 {empty}:: [eq]#p~x~ = x % f~w~# 655 {empty}:: [eq]#p~y~ = y % f~h~# 656 {empty}:: [eq]#p = p~x~ + (p~y~ {times} f~w~)# 657 658The table below illustrates the pixel index for multi-pixel fragments: 659 660.Pixel indices - 1 wide 661[align="center"] 662|==== 663| 1x1 | 1x2 | 1x4 664 665.>| image:{images}/pixel_index_1x1.svg[pdfwidth=90pt,opts="{imageopts}"] 666.>| image:{images}/pixel_index_1x2.svg[pdfwidth=90pt,align="center",opts="{imageopts}"] 667.>| image:{images}/pixel_index_1x4.svg[pdfwidth=90pt,align="center",opts="{imageopts}"] 668|==== 669 670.Pixel indices - 2 wide 671[align="center"] 672|==== 673| 2x1 | 2x2 | 2x4 674 675.>| image:{images}/pixel_index_2x1.svg[pdfwidth=90pt,align="center",opts="{imageopts}"] 676.>| image:{images}/pixel_index_2x2.svg[pdfwidth=90pt,align="center",opts="{imageopts}"] 677.>| image:{images}/pixel_index_2x4.svg[pdfwidth=90pt,align="center",opts="{imageopts}"] 678|==== 679 680.Pixel indices - 4 wide 681[align="center"] 682|==== 683| 4x1 | 4x2 | 4x4 684 685.>| image:{images}/pixel_index_4x1.svg[pdfwidth=90pt,align="center",opts="{imageopts}"] 686.>| image:{images}/pixel_index_4x2.svg[pdfwidth=90pt,align="center",opts="{imageopts}"] 687.>| image:{images}/pixel_index_4x4.svg[pdfwidth=90pt,align="center",opts="{imageopts}"] 688|==== 689endif::VK_KHR_fragment_shading_rate[] 690 691The coverage mask includes [eq]#B# bits packed into [eq]#W# words, defined 692as: 693 694 {empty}:: [eq]#B = n {times} pname:rasterizationSamples# 695 {empty}:: [eq]#W = {lceil}B/32{rceil}# 696 697Bit [eq]#b# in coverage mask word [eq]#w# is `1` if the sample with coverage 698index [eq]#j = 32{times}w + b# is covered, and `0` otherwise. 699 700If the pname:standardSampleLocations member of slink:VkPhysicalDeviceLimits 701is ename:VK_TRUE, then the sample counts ename:VK_SAMPLE_COUNT_1_BIT, 702ename:VK_SAMPLE_COUNT_2_BIT, ename:VK_SAMPLE_COUNT_4_BIT, 703ename:VK_SAMPLE_COUNT_8_BIT, and ename:VK_SAMPLE_COUNT_16_BIT have sample 704locations as listed in the following table, with the [eq]##i##th entry in 705the table corresponding to sample index [eq]#i#. 706ename:VK_SAMPLE_COUNT_32_BIT and ename:VK_SAMPLE_COUNT_64_BIT do not have 707standard sample locations. 708Locations are defined relative to an origin in the upper left corner of the 709fragment. 710 711<<< 712 713.Standard sample locations 714[options="header",align="center"] 715|==== 716| Sample count 2+| Sample Locations 717|ename:VK_SAMPLE_COUNT_1_BIT 718 | [eq]#(0.5,0.5)# 719 | image:{images}/sample_count_1.svg[pdfwidth=90pt,align="center",opts="{imageopts}"] 720|ename:VK_SAMPLE_COUNT_2_BIT 721 | [eq]#(0.75,0.75)# + 722 [eq]#(0.25,0.25)# 723 | image:{images}/sample_count_2.svg[pdfwidth=90pt,align="center",opts="{imageopts}"] 724|ename:VK_SAMPLE_COUNT_4_BIT 725 | [eq]#(0.375, 0.125)# + 726 [eq]#(0.875, 0.375)# + 727 [eq]#(0.125, 0.625)# + 728 [eq]#(0.625, 0.875)# 729 | image:{images}/sample_count_4.svg[pdfwidth=90pt,align="center",opts="{imageopts}"] 730|ename:VK_SAMPLE_COUNT_8_BIT 731 | [eq]#(0.5625, 0.3125)# + 732 [eq]#(0.4375, 0.6875)# + 733 [eq]#(0.8125, 0.5625)# + 734 [eq]#(0.3125, 0.1875)# + 735 [eq]#(0.1875, 0.8125)# + 736 [eq]#(0.0625, 0.4375)# + 737 [eq]#(0.6875, 0.9375)# + 738 [eq]#(0.9375, 0.0625)# 739 | image:{images}/sample_count_8.svg[pdfwidth=90pt,align="center",opts="{imageopts}"] 740|ename:VK_SAMPLE_COUNT_16_BIT 741 | [eq]#(0.5625, 0.5625)# + 742 [eq]#(0.4375, 0.3125)# + 743 [eq]#(0.3125, 0.625)# + 744 [eq]#(0.75, 0.4375)# + 745 [eq]#(0.1875, 0.375)# + 746 [eq]#(0.625, 0.8125)# + 747 [eq]#(0.8125, 0.6875)# + 748 [eq]#(0.6875, 0.1875)# + 749 [eq]#(0.375, 0.875)# + 750 [eq]#(0.5, 0.0625)# + 751 [eq]#(0.25, 0.125)# + 752 [eq]#(0.125, 0.75)# + 753 [eq]#(0.0, 0.5)# + 754 [eq]#(0.9375, 0.25)# + 755 [eq]#(0.875, 0.9375)# + 756 [eq]#(0.0625, 0.0)# 757 | image:{images}/sample_count_16.svg[pdfwidth=90pt,align="center",opts="{imageopts}"] 758|==== 759 760ifdef::VK_AMD_shader_fragment_mask[] 761Color images created with multiple samples per pixel use a compression 762technique where there are two arrays of data associated with each pixel. 763The first array contains one element per sample where each element stores an 764index to the second array defining the _fragment mask_ of the pixel. 765The second array contains one element per _color fragment_ and each element 766stores a unique color value in the format of the image. 767With this compression technique it is not always necessary to actually use 768unique storage locations for each color sample: when multiple samples share 769the same color value the fragment mask may: have two samples referring to 770the same color fragment. 771The number of color fragments is determined by the pname:samples member of 772the slink:VkImageCreateInfo structure used to create the image. 773The `apiext:VK_AMD_shader_fragment_mask` device extension provides shader 774instructions enabling the application to get direct access to the fragment 775mask and the individual color fragment values. 776 777[[vk-amd-shader-fragment-mask-diagram]] 778image::{images}/fragment_mask.svg[align="center",title="Fragment Mask",align="center",opts="{imageopts}"] 779 780endif::VK_AMD_shader_fragment_mask[] 781 782 783ifdef::VK_EXT_sample_locations[] 784[[primsrast-samplelocations]] 785== Custom Sample Locations 786 787[open,refpage='VkPipelineSampleLocationsStateCreateInfoEXT',desc='Structure specifying sample locations for a pipeline',type='structs'] 788-- 789Applications can: also control the sample locations used for rasterization. 790 791If the pname:pNext chain of the slink:VkPipelineMultisampleStateCreateInfo 792structure specified at pipeline creation time includes a 793sname:VkPipelineSampleLocationsStateCreateInfoEXT structure, then that 794structure controls the sample locations used when rasterizing primitives 795with the pipeline. 796 797The sname:VkPipelineSampleLocationsStateCreateInfoEXT structure is defined 798as: 799 800include::{generated}/api/structs/VkPipelineSampleLocationsStateCreateInfoEXT.adoc[] 801 802 * pname:sType is the type of this structure. 803 * pname:pNext is `NULL` or a pointer to a structure extending this 804 structure. 805 * pname:sampleLocationsEnable controls whether custom sample locations are 806 used. 807 If pname:sampleLocationsEnable is ename:VK_FALSE, the default sample 808 locations are used and the values specified in pname:sampleLocationsInfo 809 are ignored. 810 * pname:sampleLocationsInfo is the sample locations to use during 811 rasterization if pname:sampleLocationsEnable is ename:VK_TRUE and the 812 graphics pipeline is not created with 813 ename:VK_DYNAMIC_STATE_SAMPLE_LOCATIONS_EXT. 814 815include::{generated}/validity/structs/VkPipelineSampleLocationsStateCreateInfoEXT.adoc[] 816-- 817 818[open,refpage='VkSampleLocationsInfoEXT',desc='Structure specifying a set of sample locations',type='structs'] 819-- 820The sname:VkSampleLocationsInfoEXT structure is defined as: 821 822include::{generated}/api/structs/VkSampleLocationsInfoEXT.adoc[] 823 824 * pname:sType is the type of this structure. 825 * pname:pNext is `NULL` or a pointer to a structure extending this 826 structure. 827 * pname:sampleLocationsPerPixel is a elink:VkSampleCountFlagBits value 828 specifying the number of sample locations per pixel. 829 * pname:sampleLocationGridSize is the size of the sample location grid to 830 select custom sample locations for. 831 * pname:sampleLocationsCount is the number of sample locations in 832 pname:pSampleLocations. 833 * pname:pSampleLocations is a pointer to an array of 834 pname:sampleLocationsCount slink:VkSampleLocationEXT structures. 835 836This structure can: be used either to specify the sample locations to be 837used for rendering or to specify the set of sample locations an image 838subresource has been last rendered with for the purposes of layout 839transitions of depth/stencil images created with 840ename:VK_IMAGE_CREATE_SAMPLE_LOCATIONS_COMPATIBLE_DEPTH_BIT_EXT. 841 842The sample locations in pname:pSampleLocations specify 843pname:sampleLocationsPerPixel number of sample locations for each pixel in 844the grid of the size specified in pname:sampleLocationGridSize. 845The sample location for sample [eq]#i# at the pixel grid location 846[eq]#(x,y)# is taken from [eq]#pname:pSampleLocations[(x {plus} y {times} 847pname:sampleLocationGridSize.width) {times} pname:sampleLocationsPerPixel 848{plus} i]#. 849 850ifdef::VK_EXT_fragment_density_map[] 851If the render pass has a fragment density map, the implementation will 852choose the sample locations for the fragment and the contents of 853pname:pSampleLocations may: be ignored. 854endif::VK_EXT_fragment_density_map[] 855 856.Valid Usage 857**** 858 * [[VUID-VkSampleLocationsInfoEXT-sampleLocationsPerPixel-01526]] 859 pname:sampleLocationsPerPixel must: be a bit value that is set in 860 slink:VkPhysicalDeviceSampleLocationsPropertiesEXT::pname:sampleLocationSampleCounts 861 * [[VUID-VkSampleLocationsInfoEXT-sampleLocationsCount-01527]] 862 pname:sampleLocationsCount must: equal 863 [eq]#pname:sampleLocationsPerPixel {times} 864 pname:sampleLocationGridSize.width {times} 865 pname:sampleLocationGridSize.height# 866**** 867 868include::{generated}/validity/structs/VkSampleLocationsInfoEXT.adoc[] 869-- 870 871[open,refpage='VkSampleLocationEXT',desc='Structure specifying the coordinates of a sample location',type='structs'] 872-- 873The sname:VkSampleLocationEXT structure is defined as: 874 875include::{generated}/api/structs/VkSampleLocationEXT.adoc[] 876 877 * pname:x is the horizontal coordinate of the sample's location. 878 * pname:y is the vertical coordinate of the sample's location. 879 880The domain space of the sample location coordinates has an upper-left origin 881within the pixel in framebuffer space. 882 883The values specified in a sname:VkSampleLocationEXT structure are always 884clamped to the implementation-dependent sample location coordinate range 885[eq]#[pname:sampleLocationCoordinateRange[0],pname:sampleLocationCoordinateRange[1]]# 886that can: be queried using 887slink:VkPhysicalDeviceSampleLocationsPropertiesEXT. 888 889include::{generated}/validity/structs/VkSampleLocationEXT.adoc[] 890-- 891 892ifdef::VK_EXT_extended_dynamic_state3[] 893 894[open,refpage='vkCmdSetSampleLocationsEnableEXT',desc='Specify the samples locations enable state dynamically for a command buffer',type='protos'] 895-- 896To <<pipelines-dynamic-state, dynamically set>> the 897pname:sampleLocationsEnable state, call: 898 899include::{generated}/api/protos/vkCmdSetSampleLocationsEnableEXT.adoc[] 900 901 * pname:commandBuffer is the command buffer into which the command will be 902 recorded. 903 * pname:sampleLocationsEnable specifies the pname:sampleLocationsEnable 904 state. 905 906This command sets the pname:sampleLocationsEnable state for subsequent 907drawing commands when the graphics pipeline is created with 908ename:VK_DYNAMIC_STATE_SAMPLE_LOCATIONS_ENABLE_EXT set in 909slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. 910Otherwise, this state is specified by the 911slink:VkPipelineSampleLocationsStateCreateInfoEXT::pname:sampleLocationsEnable 912value used to create the currently active pipeline. 913 914.Valid Usage 915**** 916 * [[VUID-vkCmdSetSampleLocationsEnableEXT-extendedDynamicState3SampleLocationsEnable-07415]] 917 The <<features-extendedDynamicState3SampleLocationsEnable, 918 pname:extendedDynamicState3SampleLocationsEnable>> feature must: be 919 enabled 920**** 921 922include::{generated}/validity/protos/vkCmdSetSampleLocationsEnableEXT.adoc[] 923-- 924 925endif::VK_EXT_extended_dynamic_state3[] 926 927[open,refpage='vkCmdSetSampleLocationsEXT',desc='Set sample locations dynamically for a command buffer',type='protos'] 928-- 929To <<pipelines-dynamic-state, dynamically set>> the sample locations used 930for rasterization, call: 931 932include::{generated}/api/protos/vkCmdSetSampleLocationsEXT.adoc[] 933 934 * pname:commandBuffer is the command buffer into which the command will be 935 recorded. 936 * pname:pSampleLocationsInfo is the sample locations state to set. 937 938This command sets the custom sample locations for subsequent drawing 939commands when the graphics pipeline is created with 940ename:VK_DYNAMIC_STATE_SAMPLE_LOCATIONS_EXT set in 941slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates, and when the 942slink:VkPipelineSampleLocationsStateCreateInfoEXT::pname:sampleLocationsEnable 943property of the bound graphics pipeline is ename:VK_TRUE. 944Otherwise, this state is specified by the 945slink:VkPipelineSampleLocationsStateCreateInfoEXT::pname:sampleLocationsInfo 946values used to create the currently active pipeline. 947 948.Valid Usage 949**** 950ifndef::VK_EXT_extended_dynamic_state3[] 951 * [[VUID-vkCmdSetSampleLocationsEXT-sampleLocationsPerPixel-01529]] 952 The pname:sampleLocationsPerPixel member of pname:pSampleLocationsInfo 953 must: equal the pname:rasterizationSamples member of the 954 slink:VkPipelineMultisampleStateCreateInfo structure the bound graphics 955 pipeline has been created with 956endif::VK_EXT_extended_dynamic_state3[] 957 * [[VUID-vkCmdSetSampleLocationsEXT-variableSampleLocations-01530]] 958 If 959 slink:VkPhysicalDeviceSampleLocationsPropertiesEXT::pname:variableSampleLocations 960 is ename:VK_FALSE then the current render pass must: have been begun by 961 specifying a slink:VkRenderPassSampleLocationsBeginInfoEXT structure 962 whose pname:pPostSubpassSampleLocations member contains an element with 963 a pname:subpassIndex matching the current subpass index and the 964 pname:sampleLocationsInfo member of that element must: match the sample 965 locations state pointed to by pname:pSampleLocationsInfo 966**** 967 968include::{generated}/validity/protos/vkCmdSetSampleLocationsEXT.adoc[] 969-- 970endif::VK_EXT_sample_locations[] 971 972 973ifdef::VK_KHR_fragment_shading_rate[] 974[[primsrast-fragment-shading-rate]] 975== Fragment Shading Rates 976 977The features advertised by 978slink:VkPhysicalDeviceFragmentShadingRateFeaturesKHR allow an application to 979control the <<glossary-shading-rate, shading rate>> of a given fragment 980shader invocation. 981 982The fragment shading rate strongly interacts with <<primsrast-multisampling, 983Multisampling>>, and the set of available rates for an implementation may: 984be restricted by sample rate. 985 986[open,refpage='vkGetPhysicalDeviceFragmentShadingRatesKHR',desc='Get available shading rates for a physical device',type='protos'] 987-- 988To query available shading rates, call: 989 990include::{generated}/api/protos/vkGetPhysicalDeviceFragmentShadingRatesKHR.adoc[] 991 992 * pname:physicalDevice is the handle to the physical device whose 993 properties will be queried. 994 * pname:pFragmentShadingRateCount is a pointer to an integer related to 995 the number of fragment shading rates available or queried, as described 996 below. 997 * pname:pFragmentShadingRates is either `NULL` or a pointer to an array of 998 slink:VkPhysicalDeviceFragmentShadingRateKHR structures. 999 1000If pname:pFragmentShadingRates is `NULL`, then the number of fragment 1001shading rates available is returned in pname:pFragmentShadingRateCount. 1002Otherwise, pname:pFragmentShadingRateCount must: point to a variable set by 1003the user to the number of elements in the pname:pFragmentShadingRates array, 1004and on return the variable is overwritten with the number of structures 1005actually written to pname:pFragmentShadingRates. 1006If pname:pFragmentShadingRateCount is less than the number of fragment 1007shading rates available, at most pname:pFragmentShadingRateCount structures 1008will be written, and ename:VK_INCOMPLETE will be returned instead of 1009ename:VK_SUCCESS, to indicate that not all the available fragment shading 1010rates were returned. 1011 1012The returned array of fragment shading rates must: be ordered from largest 1013pname:fragmentSize.width value to smallest, and each set of fragment shading 1014rates with the same pname:fragmentSize.width value must: be ordered from 1015largest pname:fragmentSize.height to smallest. 1016Any two entries in the array must: not have the same pname:fragmentSize 1017values. 1018 1019For any entry in the array, the following rules also apply: 1020 1021 * The value of pname:fragmentSize.width must: be less than or equal to 1022 <<limits-maxFragmentSize, pname:maxFragmentSize.width>>. 1023 * The value of pname:fragmentSize.width must: be greater than or equal to 1024 `1`. 1025 * The value of pname:fragmentSize.width must: be a power-of-two. 1026 * The value of pname:fragmentSize.height must: be less than or equal to 1027 <<limits-maxFragmentSize, pname:maxFragmentSize.height>>. 1028 * The value of pname:fragmentSize.height must: be greater than or equal to 1029 `1`. 1030 * The value of pname:fragmentSize.height must: be a power-of-two. 1031 * The highest sample count in pname:sampleCounts must: be less than or 1032 equal to <<limits-maxFragmentShadingRateRasterizationSamples, 1033 pname:maxFragmentShadingRateRasterizationSamples>>. 1034 * The product of pname:fragmentSize.width, pname:fragmentSize.height, and 1035 the highest sample count in pname:sampleCounts must: be less than or 1036 equal to <<limits-maxFragmentShadingRateCoverageSamples, 1037 pname:maxFragmentShadingRateCoverageSamples>>. 1038 1039Implementations must: support at least the following shading rates: 1040 1041[options="autowidth"] 1042|=== 1043| pname:sampleCounts | pname:fragmentSize 1044 1045| ename:VK_SAMPLE_COUNT_1_BIT \| ename:VK_SAMPLE_COUNT_4_BIT | {2,2} 1046| ename:VK_SAMPLE_COUNT_1_BIT \| ename:VK_SAMPLE_COUNT_4_BIT | {2,1} 1047| ~0 | {1,1} 1048|=== 1049 1050If <<limits-framebufferColorSampleCounts, 1051pname:framebufferColorSampleCounts>>, includes ename:VK_SAMPLE_COUNT_2_BIT, 1052the required rates must: also include ename:VK_SAMPLE_COUNT_2_BIT. 1053 1054[NOTE] 1055.Note 1056==== 1057Including the {1,1} fragment size is done for completeness; it has no actual 1058effect on the support of rendering without setting the fragment size. 1059All sample counts 1060ifdef::VK_QCOM_render_pass_transform[] 1061and render pass transforms 1062endif::VK_QCOM_render_pass_transform[] 1063are supported for this rate. 1064==== 1065 1066ifdef::VK_QCOM_render_pass_transform[] 1067The returned set of fragment shading rates must: be returned in the native 1068(rotated) coordinate system. 1069For rasterization using render pass pname:transform not equal to 1070ename:VK_SURFACE_TRANSFORM_IDENTITY_BIT_KHR, the application must: transform 1071the returned fragment shading rates into the current (unrotated) coordinate 1072system to get the supported rates for that transform. 1073 1074[NOTE] 1075.Note 1076==== 1077For example, consider an implementation returning support for 4x2, but not 10782x4 in the set of supported fragment shading rates. 1079This means that for transforms ename:VK_SURFACE_TRANSFORM_ROTATE_90_BIT_KHR 1080and ename:VK_SURFACE_TRANSFORM_ROTATE_270_BIT_KHR, 2x4 is a supported rate, 1081but 4x2 is an unsupported rate. 1082==== 1083endif::VK_QCOM_render_pass_transform[] 1084 1085include::{generated}/validity/protos/vkGetPhysicalDeviceFragmentShadingRatesKHR.adoc[] 1086-- 1087 1088[open,refpage='VkPhysicalDeviceFragmentShadingRateKHR',desc='Structure returning information about sample count specific additional multisampling capabilities',type='structs'] 1089-- 1090The sname:VkPhysicalDeviceFragmentShadingRateKHR structure is defined as 1091 1092include::{generated}/api/structs/VkPhysicalDeviceFragmentShadingRateKHR.adoc[] 1093 1094 * pname:sType is the type of this structure. 1095 * pname:pNext is `NULL` or a pointer to a structure extending this 1096 structure. 1097 * pname:sampleCounts is a bitmask of sample counts for which the shading 1098 rate described by pname:fragmentSize is supported. 1099 * pname:fragmentSize is a slink:VkExtent2D describing the width and height 1100 of a supported shading rate. 1101 1102include::{generated}/validity/structs/VkPhysicalDeviceFragmentShadingRateKHR.adoc[] 1103-- 1104 1105Fragment shading rates can: be set at three points, with the three rates 1106combined to determine the final shading rate. 1107 1108 1109[[primsrast-fragment-shading-rate-pipeline]] 1110=== Pipeline Fragment Shading Rate 1111 1112The _pipeline fragment shading rate_ can: be set on a per-draw basis by 1113either setting the rate in a graphics pipeline, or dynamically via 1114flink:vkCmdSetFragmentShadingRateKHR. 1115 1116[open,refpage='VkPipelineFragmentShadingRateStateCreateInfoKHR',desc='Structure specifying parameters controlling the fragment shading rate',type='structs'] 1117-- 1118The sname:VkPipelineFragmentShadingRateStateCreateInfoKHR structure is 1119defined as: 1120 1121include::{generated}/api/structs/VkPipelineFragmentShadingRateStateCreateInfoKHR.adoc[] 1122 1123 * pname:sType is the type of this structure. 1124 * pname:pNext is `NULL` or a pointer to a structure extending this 1125 structure. 1126 * pname:fragmentSize specifies a slink:VkExtent2D structure containing the 1127 fragment size used to define the pipeline fragment shading rate for 1128 drawing commands using this pipeline. 1129 * pname:combinerOps specifies a elink:VkFragmentShadingRateCombinerOpKHR 1130 value determining how the 1131 <<primsrast-fragment-shading-rate-pipeline,pipeline>>, 1132 <<primsrast-fragment-shading-rate-primitive,primitive>>, and 1133 <<primsrast-fragment-shading-rate-attachment,attachment shading rates>> 1134 are <<primsrast-fragment-shading-rate-combining,combined>> for fragments 1135 generated by drawing commands using the created pipeline. 1136 1137If the pname:pNext chain of slink:VkGraphicsPipelineCreateInfo includes a 1138sname:VkPipelineFragmentShadingRateStateCreateInfoKHR structure, then that 1139structure includes parameters controlling the pipeline fragment shading 1140rate. 1141 1142If this structure is not present, pname:fragmentSize is considered to be 1143equal to [eq]#(1,1)#, and both elements of pname:combinerOps are considered 1144to be equal to ename:VK_FRAGMENT_SHADING_RATE_COMBINER_OP_KEEP_KHR. 1145 1146include::{generated}/validity/structs/VkPipelineFragmentShadingRateStateCreateInfoKHR.adoc[] 1147-- 1148 1149[open,refpage='vkCmdSetFragmentShadingRateKHR',desc='Set pipeline fragment shading rate and combiner operation dynamically for a command buffer',type='protos'] 1150-- 1151To <<pipelines-dynamic-state, dynamically set>> the pipeline fragment 1152shading rate and combiner operation, call: 1153 1154include::{generated}/api/protos/vkCmdSetFragmentShadingRateKHR.adoc[] 1155 1156 * pname:commandBuffer is the command buffer into which the command will be 1157 recorded. 1158 * pname:pFragmentSize specifies the pipeline fragment shading rate for 1159 subsequent drawing commands. 1160 * pname:combinerOps specifies a elink:VkFragmentShadingRateCombinerOpKHR 1161 determining how the 1162 <<primsrast-fragment-shading-rate-pipeline,pipeline>>, 1163 <<primsrast-fragment-shading-rate-primitive,primitive>>, and 1164 <<primsrast-fragment-shading-rate-attachment,attachment shading rates>> 1165 are <<primsrast-fragment-shading-rate-combining,combined>> for fragments 1166 generated by subsequent drawing commands. 1167 1168This command sets the pipeline fragment shading rate and combiner operation 1169for subsequent drawing commands when the graphics pipeline is created with 1170ename:VK_DYNAMIC_STATE_FRAGMENT_SHADING_RATE_KHR set in 1171slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. 1172Otherwise, this state is specified by the 1173slink:VkPipelineFragmentShadingRateStateCreateInfoKHR values used to create 1174the currently active pipeline. 1175 1176.Valid Usage 1177**** 1178 * [[VUID-vkCmdSetFragmentShadingRateKHR-pipelineFragmentShadingRate-04507]] 1179 If <<features-pipelineFragmentShadingRate, 1180 pname:pipelineFragmentShadingRate>> is not enabled, 1181 pname:pFragmentSize->width must: be `1` 1182 * [[VUID-vkCmdSetFragmentShadingRateKHR-pipelineFragmentShadingRate-04508]] 1183 If <<features-pipelineFragmentShadingRate, 1184 pname:pipelineFragmentShadingRate>> is not enabled, 1185 pname:pFragmentSize->height must: be `1` 1186 * [[VUID-vkCmdSetFragmentShadingRateKHR-pipelineFragmentShadingRate-04509]] 1187 One of <<features-pipelineFragmentShadingRate, 1188 pname:pipelineFragmentShadingRate>>, 1189 <<features-primitiveFragmentShadingRate, 1190 pname:primitiveFragmentShadingRate>>, or 1191 <<features-attachmentFragmentShadingRate, 1192 pname:attachmentFragmentShadingRate>> must: be enabled 1193 * [[VUID-vkCmdSetFragmentShadingRateKHR-primitiveFragmentShadingRate-04510]] 1194 If the <<features-primitiveFragmentShadingRate, 1195 pname:primitiveFragmentShadingRate>> feature is not enabled, 1196 pname:combinerOps[0] must: be 1197 ename:VK_FRAGMENT_SHADING_RATE_COMBINER_OP_KEEP_KHR 1198 * [[VUID-vkCmdSetFragmentShadingRateKHR-attachmentFragmentShadingRate-04511]] 1199 If the <<features-attachmentFragmentShadingRate, 1200 pname:attachmentFragmentShadingRate>> feature is not enabled, 1201 pname:combinerOps[1] must: be 1202 ename:VK_FRAGMENT_SHADING_RATE_COMBINER_OP_KEEP_KHR 1203 * [[VUID-vkCmdSetFragmentShadingRateKHR-fragmentSizeNonTrivialCombinerOps-04512]] 1204 If the <<limits-fragmentShadingRateNonTrivialCombinerOps, 1205 pname:fragmentSizeNonTrivialCombinerOps>> limit is not supported, 1206 elements of pname:combinerOps must: be either 1207 ename:VK_FRAGMENT_SHADING_RATE_COMBINER_OP_KEEP_KHR or 1208 ename:VK_FRAGMENT_SHADING_RATE_COMBINER_OP_REPLACE_KHR 1209 * [[VUID-vkCmdSetFragmentShadingRateKHR-pFragmentSize-04513]] 1210 pname:pFragmentSize->width must: be greater than or equal to `1` 1211 * [[VUID-vkCmdSetFragmentShadingRateKHR-pFragmentSize-04514]] 1212 pname:pFragmentSize->height must: be greater than or equal to `1` 1213 * [[VUID-vkCmdSetFragmentShadingRateKHR-pFragmentSize-04515]] 1214 pname:pFragmentSize->width must: be a power-of-two value 1215 * [[VUID-vkCmdSetFragmentShadingRateKHR-pFragmentSize-04516]] 1216 pname:pFragmentSize->height must: be a power-of-two value 1217 * [[VUID-vkCmdSetFragmentShadingRateKHR-pFragmentSize-04517]] 1218 pname:pFragmentSize->width must: be less than or equal to `4` 1219 * [[VUID-vkCmdSetFragmentShadingRateKHR-pFragmentSize-04518]] 1220 pname:pFragmentSize->height must: be less than or equal to `4` 1221**** 1222 1223include::{generated}/validity/protos/vkCmdSetFragmentShadingRateKHR.adoc[] 1224-- 1225 1226 1227[[primsrast-fragment-shading-rate-primitive]] 1228=== Primitive Fragment Shading Rate 1229 1230The _primitive fragment shading rate_ can: be set via the 1231<<interfaces-builtin-variables-primitiveshadingrate, 1232code:PrimitiveShadingRateKHR>> built-in in the last active 1233<<pipelines-graphics-subsets-pre-rasterization,pre-rasterization shader 1234stage>>. 1235ifdef::VK_EXT_mesh_shader[] 1236If the last <<pipelines-graphics-subsets-pre-rasterization,pre-rasterization 1237shader stage>> is using the code:MeshEXT {ExecutionModel}, the rate 1238associated with a given primitive is sourced from the value written to the 1239per-primitive code:PrimitiveShadingRateKHR. 1240Otherwise the 1241endif::VK_EXT_mesh_shader[] 1242ifndef::VK_EXT_mesh_shader[The] 1243rate associated with a given primitive is sourced from the value written to 1244code:PrimitiveShadingRateKHR by that primitive's 1245<<vertexpostproc-flatshading,provoking vertex>>. 1246 1247 1248[[primsrast-fragment-shading-rate-attachment]] 1249=== Attachment Fragment Shading Rate 1250 1251The _attachment shading rate_ can: be set by including 1252slink:VkFragmentShadingRateAttachmentInfoKHR in a subpass to define a 1253_fragment shading rate attachment_. 1254Each pixel in the framebuffer is assigned an attachment fragment shading 1255rate by the corresponding texel in the fragment shading rate attachment, 1256according to: 1257 1258 {empty}:: [eq]#x' = floor(x / region~x~)# 1259 {empty}:: [eq]#y' = floor(y / region~y~)# 1260 1261where [eq]#x'# and [eq]#y'# are the coordinates of a texel in the fragment 1262shading rate attachment, [eq]#x# and [eq]#y# are the coordinates of the 1263pixel in the framebuffer, and [eq]#region~x~# and [eq]#region~y~# are the 1264size of the region each texel corresponds to, as defined by the 1265pname:shadingRateAttachmentTexelSize member of 1266slink:VkFragmentShadingRateAttachmentInfoKHR. 1267 1268If <<VkRenderPassMultiviewCreateInfo, multiview is enabled>> and the shading 1269rate attachment has multiple layers, the shading rate attachment texel is 1270selected from the layer determined by the 1271<<interfaces-builtin-variables-viewindex,code:ViewIndex>> built-in. 1272If <<VkRenderPassMultiviewCreateInfo, multiview is disabled>>, and both the 1273shading rate attachment and the framebuffer have multiple layers, the 1274shading rate attachment texel is selected from the layer determined by the 1275<<interfaces-builtin-variables-layer,code:Layer>> built-in. 1276Otherwise, the texel is unconditionally selected from the first layer of the 1277attachment. 1278 1279The fragment size is encoded into the first component of the identified 1280texel as follows: 1281 1282 {empty}:: [eq]#size~w~ = 2^((texel / 4) & 3)^# 1283 {empty}:: [eq]#size~h~ = 2^(texel & 3)^# 1284 1285where [eq]#texel# is the value in the first component of the identified 1286texel, and [eq]#size~w~# and [eq]#size~h~# are the width and height of the 1287fragment size, decoded from the texel. 1288 1289If no fragment shading rate attachment is specified, this size is calculated 1290as [eq]#size~w~ = size~h~ = 1#. 1291Applications must: not specify a width or height greater than 4 by this 1292method. 1293 1294The _Fragment Shading Rate_ enumeration in SPIR-V adheres to the above 1295encoding. 1296 1297 1298[[primsrast-fragment-shading-rate-combining]] 1299=== Combining the Fragment Shading Rates 1300 1301The final rate ([eq]#C~xy~'#) used for fragment shading must: be one of the 1302rates returned by flink:vkGetPhysicalDeviceFragmentShadingRatesKHR for the 1303sample count 1304ifdef::VK_QCOM_render_pass_transform[] 1305and render pass transform 1306endif::VK_QCOM_render_pass_transform[] 1307used by rasterization. 1308 1309If any of the following conditions are met, [eq]#C~xy~'# must: be set to 1310[eq]#{1,1}#: 1311 1312 * If <<primsrast-sampleshading,Sample Shading>> is enabled. 1313 * The <<limits-fragmentShadingRateWithSampleMask, 1314 pname:fragmentShadingRateWithSampleMask>> limit is not supported, and 1315 slink:VkPipelineMultisampleStateCreateInfo::pname:pSampleMask contains a 1316 zero value in any bit used by fragment operations. 1317 * The <<limits-fragmentShadingRateWithShaderSampleMask, 1318 pname:fragmentShadingRateWithShaderSampleMask>> is not supported, and 1319 the fragment shader has code:SampleMask in the input or output 1320 interface. 1321 * The <<limits-fragmentShadingRateWithShaderDepthStencilWrites, 1322 pname:fragmentShadingRateWithShaderDepthStencilWrites>> limit is not 1323 supported, and the fragment shader declares the code:FragDepth 1324ifdef::VK_EXT_shader_stencil_export[] 1325 or code:FragStencilRefEXT 1326endif::VK_EXT_shader_stencil_export[] 1327 built-in. 1328ifdef::VK_EXT_conservative_rasterization[] 1329 * The <<limits-fragmentShadingRateWithConservativeRasterization, 1330 pname:fragmentShadingRateWithConservativeRasterization>> limit is not 1331 supported, and 1332 slink:VkPipelineRasterizationConservativeStateCreateInfoEXT::pname:conservativeRasterizationMode 1333 is not ename:VK_CONSERVATIVE_RASTERIZATION_MODE_DISABLED_EXT. 1334endif::VK_EXT_conservative_rasterization[] 1335ifdef::VK_EXT_fragment_shader_interlock[] 1336 * The <<limits-fragmentShadingRateWithFragmentShaderInterlock, 1337 pname:fragmentShadingRateWithFragmentShaderInterlock>> limit is not 1338 supported, and the fragment shader declares any of the 1339 <<fragops-shader-interlock, fragment shader interlock>> execution modes. 1340endif::VK_EXT_fragment_shader_interlock[] 1341ifdef::VK_EXT_sample_locations[] 1342 * The <<limits-fragmentShadingRateWithCustomSampleLocations, 1343 pname:fragmentShadingRateWithCustomSampleLocations>> limit is not 1344 supported, and 1345 slink:VkPipelineSampleLocationsStateCreateInfoEXT::pname:sampleLocationsEnable 1346 is ename:VK_TRUE. 1347endif::VK_EXT_sample_locations[] 1348 1349Otherwise, each of the specified shading rates are combined and then used to 1350derive the value of [eq]#C~xy~'#. 1351As there are three ways to specify shading rates, two combiner operations 1352are specified - between the 1353<<primsrast-fragment-shading-rate-pipeline,pipeline>> and 1354<<primsrast-fragment-shading-rate-primitive,primitive>> shading rates, and 1355between the result of that and the 1356<<primsrast-fragment-shading-rate-attachment,attachment shading rate>>. 1357 1358[open,refpage='VkFragmentShadingRateCombinerOpKHR',desc='Control how fragment shading rates are combined',type='enums'] 1359-- 1360The equation used for each combiner operation is defined by 1361ename:VkFragmentShadingRateCombinerOpKHR: 1362 1363include::{generated}/api/enums/VkFragmentShadingRateCombinerOpKHR.adoc[] 1364 1365 * ename:VK_FRAGMENT_SHADING_RATE_COMBINER_OP_KEEP_KHR specifies a combiner 1366 operation of [eq]#combine(A~xy~,B~xy~) = A~xy~#. 1367 * ename:VK_FRAGMENT_SHADING_RATE_COMBINER_OP_REPLACE_KHR specifies a 1368 combiner operation of [eq]#combine(A~xy~,B~xy~) = B~xy~#. 1369 * ename:VK_FRAGMENT_SHADING_RATE_COMBINER_OP_MIN_KHR specifies a combiner 1370 operation of [eq]#combine(A~xy~,B~xy~) = min(A~xy~,B~xy~)#. 1371 * ename:VK_FRAGMENT_SHADING_RATE_COMBINER_OP_MAX_KHR specifies a combiner 1372 operation of [eq]#combine(A~xy~,B~xy~) = max(A~xy~,B~xy~)#. 1373 * ename:VK_FRAGMENT_SHADING_RATE_COMBINER_OP_MUL_KHR specifies a combiner 1374 operation of [eq]#combine(A~xy~,B~xy~) = A~xy~*B~xy~#. 1375 1376where [eq]#combine(A~xy~,B~xy~)# is the combine operation, and [eq]#A~xy~# 1377and [eq]#B~xy~# are the inputs to the operation. 1378 1379If <<limits-fragmentShadingRateStrictMultiplyCombiner, 1380pname:fragmentShadingRateStrictMultiplyCombiner>> is ename:VK_FALSE, using 1381ename:VK_FRAGMENT_SHADING_RATE_COMBINER_OP_MUL_KHR with values of 1 for both 1382A and B in the same dimension results in the value 2 being produced for that 1383dimension. 1384See the definition of <<limits-fragmentShadingRateStrictMultiplyCombiner, 1385pname:fragmentShadingRateStrictMultiplyCombiner>> for more information. 1386 1387These operations are performed in a component-wise fashion. 1388-- 1389 1390This is used to generate a combined fragment area using the equation: 1391 1392 {empty}:: [eq]#C~xy~ = combine(A~xy~,B~xy~)# 1393 1394where [eq]#C~xy~# is the combined fragment area result, and [eq]#A~xy~# and 1395[eq]#B~xy~# are the fragment areas of the fragment shading rates being 1396combined. 1397 1398Two combine operations are performed, first with [eq]#A~xy~# equal to the 1399<<primsrast-fragment-shading-rate-pipeline,pipeline fragment shading rate>> 1400and [eq]#B~xy~# equal to the <<primsrast-fragment-shading-rate-primitive, 1401primitive fragment shading rate>>, with the [eq]#combine()# operation 1402selected by combinerOps[0]. 1403A second combination is then performed, with [eq]#A~xy~# equal to the result 1404of the first combination and [eq]#B~xy~# equal to the 1405<<primsrast-fragment-shading-rate-attachment, attachment fragment shading 1406rate>>, with the [eq]#combine()# operation selected by combinerOps[1]. 1407The result of the second combination is used as the final fragment shading 1408rate, reported via the <<interfaces-builtin-variables-primitiveshadingrate, 1409code:ShadingRateKHR built-in>>. 1410 1411Implementations may: clamp the [eq]#C~xy~# result of each combiner operation 1412separately, or only after the second combiner operation. 1413 1414If the final combined rate is one of the rates returned by 1415flink:vkGetPhysicalDeviceFragmentShadingRatesKHR for the sample count 1416ifdef::VK_QCOM_render_pass_transform[] 1417and render pass transform 1418endif::VK_QCOM_render_pass_transform[] 1419used by rasterization, [eq]#C~xy~' = C~xy~#. 1420Otherwise, [eq]#C~xy~'# is selected from the rates returned by 1421flink:vkGetPhysicalDeviceFragmentShadingRatesKHR for the sample count 1422ifdef::VK_QCOM_render_pass_transform[] 1423and render pass transform 1424endif::VK_QCOM_render_pass_transform[] 1425used by rasterization. 1426From this list of supported rates, the following steps are applied in order, 1427to select a single value: 1428 1429 . Keep only rates where [eq]#C~x~' {leq} C~x~# and [eq]#C~y~' {leq} C~y~#. 1430 ** Implementations may: also keep rates where [eq]#C~x~' {leq} C~y~# and 1431 [eq]#C~y~' {leq} C~x~#. 1432 . Keep only rates with the highest area ([eq]#C~x~' {times} C~y~'#). 1433 . Keep only rates with the lowest aspect ratio ([eq]#C~x~' {plus} C~y~'#). 1434 . In cases where a wide (e.g. 4x1) and tall (e.g. 1x4) rate remain, the 1435 implementation may: choose either rate. 1436 However, it must: choose this rate consistently for the same shading 1437 rates, 1438ifdef::VK_QCOM_render_pass_transform[] 1439 render pass transform, 1440endif::VK_QCOM_render_pass_transform[] 1441 and combiner operations for the lifetime of the slink:VkDevice. 1442endif::VK_KHR_fragment_shading_rate[] 1443 1444 1445ifdef::VK_NV_fragment_shading_rate_enums[] 1446=== Extended Fragment Shading Rates 1447 1448The features advertised by 1449slink:VkPhysicalDeviceFragmentShadingRateEnumsFeaturesNV provide support for 1450additional fragment shading rates beyond those specifying one fragment 1451shader invocation covering all pixels in a fragment whose size is indicated 1452by the fragment shading rate. 1453 1454[open,refpage='VkFragmentShadingRateNV',desc='Enumeration with fragment shading rates',type='enums'] 1455-- 1456If the pname:fragmentShadingRateEnums feature is enabled, fragment shading 1457rates may be specified using the elink:VkFragmentShadingRateNV enumerated 1458type defined as: 1459 1460include::{generated}/api/enums/VkFragmentShadingRateNV.adoc[] 1461 1462 * ename:VK_FRAGMENT_SHADING_RATE_1_INVOCATION_PER_PIXEL_NV specifies a 1463 fragment size of 1x1 pixels. 1464 * ename:VK_FRAGMENT_SHADING_RATE_1_INVOCATION_PER_1X2_PIXELS_NV specifies 1465 a fragment size of 1x2 pixels. 1466 * ename:VK_FRAGMENT_SHADING_RATE_1_INVOCATION_PER_2X1_PIXELS_NV specifies 1467 a fragment size of 2x1 pixels. 1468 * ename:VK_FRAGMENT_SHADING_RATE_1_INVOCATION_PER_2X2_PIXELS_NV specifies 1469 a fragment size of 2x2 pixels. 1470 * ename:VK_FRAGMENT_SHADING_RATE_1_INVOCATION_PER_2X4_PIXELS_NV specifies 1471 a fragment size of 2x4 pixels. 1472 * ename:VK_FRAGMENT_SHADING_RATE_1_INVOCATION_PER_4X2_PIXELS_NV specifies 1473 a fragment size of 4x2 pixels. 1474 * ename:VK_FRAGMENT_SHADING_RATE_1_INVOCATION_PER_4X4_PIXELS_NV specifies 1475 a fragment size of 4x4 pixels. 1476 * ename:VK_FRAGMENT_SHADING_RATE_2_INVOCATIONS_PER_PIXEL_NV specifies a 1477 fragment size of 1x1 pixels, with two fragment shader invocations per 1478 fragment. 1479 * ename:VK_FRAGMENT_SHADING_RATE_4_INVOCATIONS_PER_PIXEL_NV specifies a 1480 fragment size of 1x1 pixels, with four fragment shader invocations per 1481 fragment. 1482 * ename:VK_FRAGMENT_SHADING_RATE_8_INVOCATIONS_PER_PIXEL_NV specifies a 1483 fragment size of 1x1 pixels, with eight fragment shader invocations per 1484 fragment. 1485 * ename:VK_FRAGMENT_SHADING_RATE_16_INVOCATIONS_PER_PIXEL_NV specifies a 1486 fragment size of 1x1 pixels, with sixteen fragment shader invocations 1487 per fragment. 1488 * ename:VK_FRAGMENT_SHADING_RATE_NO_INVOCATIONS_NV specifies that any 1489 portions of a primitive that use that shading rate should be discarded 1490 without invoking any fragment shader. 1491 1492To use the shading rates 1493ename:VK_FRAGMENT_SHADING_RATE_2_INVOCATIONS_PER_PIXEL_NV, 1494ename:VK_FRAGMENT_SHADING_RATE_4_INVOCATIONS_PER_PIXEL_NV, 1495ename:VK_FRAGMENT_SHADING_RATE_8_INVOCATIONS_PER_PIXEL_NV, and 1496ename:VK_FRAGMENT_SHADING_RATE_16_INVOCATIONS_PER_PIXEL_NV as a pipeline, 1497primitive, or attachment shading rate, the 1498pname:supersampleFragmentShadingRates feature must: be enabled. 1499To use the shading rate ename:VK_FRAGMENT_SHADING_RATE_NO_INVOCATIONS_NV as 1500a pipeline, primitive, or attachment shading rate, the 1501pname:noInvocationFragmentShadingRates feature must: be enabled. 1502-- 1503 1504When using fragment shading rate enums, the pipeline fragment shading rate 1505can: be set on a per-draw basis by either setting the rate in a graphics 1506pipeline, or dynamically via flink:vkCmdSetFragmentShadingRateEnumNV. 1507 1508[open,refpage='VkPipelineFragmentShadingRateEnumStateCreateInfoNV',desc='Structure specifying parameters controlling the fragment shading rate using rate enums',type='structs'] 1509-- 1510The sname:VkPipelineFragmentShadingRateEnumStateCreateInfoNV structure is 1511defined as: 1512 1513include::{generated}/api/structs/VkPipelineFragmentShadingRateEnumStateCreateInfoNV.adoc[] 1514 1515 * pname:sType is the type of this structure. 1516 * pname:pNext is `NULL` or a pointer to a structure extending this 1517 structure. 1518 * pname:shadingRateType specifies a elink:VkFragmentShadingRateTypeNV 1519 value indicating whether fragment shading rates are specified using 1520 fragment sizes or elink:VkFragmentShadingRateNV enums. 1521 * pname:shadingRate specifies a elink:VkFragmentShadingRateNV value 1522 indicating the pipeline fragment shading rate. 1523 * pname:combinerOps specifies elink:VkFragmentShadingRateCombinerOpKHR 1524 values determining how the 1525 <<primsrast-fragment-shading-rate-pipeline,pipeline>>, 1526 <<primsrast-fragment-shading-rate-primitive,primitive>>, and 1527 <<primsrast-fragment-shading-rate-attachment,attachment shading rates>> 1528 are <<primsrast-fragment-shading-rate-combining,combined>> for fragments 1529 generated by drawing commands using the created pipeline. 1530 1531If the pname:pNext chain of slink:VkGraphicsPipelineCreateInfo includes a 1532sname:VkPipelineFragmentShadingRateEnumStateCreateInfoNV structure, then 1533that structure includes parameters controlling the pipeline fragment shading 1534rate. 1535 1536If this structure is not present, pname:shadingRateType is considered to be 1537equal to ename:VK_FRAGMENT_SHADING_RATE_TYPE_FRAGMENT_SIZE_NV, 1538pname:shadingRate is considered to be equal to 1539ename:VK_FRAGMENT_SHADING_RATE_1_INVOCATION_PER_PIXEL_NV, and both elements 1540of pname:combinerOps are considered to be equal to 1541ename:VK_FRAGMENT_SHADING_RATE_COMBINER_OP_KEEP_KHR. 1542 1543include::{generated}/validity/structs/VkPipelineFragmentShadingRateEnumStateCreateInfoNV.adoc[] 1544-- 1545 1546[open,refpage='VkFragmentShadingRateTypeNV',desc='Enumeration with fragment shading rate types',type='enums'] 1547-- 1548The elink:VkFragmentShadingRateTypeNV enumerated type specifies whether a 1549graphics pipeline gets its pipeline fragment shading rates and combiners 1550from the slink:VkPipelineFragmentShadingRateEnumStateCreateInfoNV structure 1551or the slink:VkPipelineFragmentShadingRateStateCreateInfoKHR structure. 1552 1553include::{generated}/api/enums/VkFragmentShadingRateTypeNV.adoc[] 1554 1555 * ename:VK_FRAGMENT_SHADING_RATE_TYPE_FRAGMENT_SIZE_NV specifies that a 1556 graphics pipeline should obtain its pipeline fragment shading rate and 1557 shading rate combiner state from the 1558 slink:VkPipelineFragmentShadingRateStateCreateInfoKHR structure and that 1559 any state specified by the 1560 slink:VkPipelineFragmentShadingRateEnumStateCreateInfoNV structure 1561 should be ignored. 1562 * ename:VK_FRAGMENT_SHADING_RATE_TYPE_ENUMS_NV specifies that a graphics 1563 pipeline should obtain its pipeline fragment shading rate and shading 1564 rate combiner state from the 1565 slink:VkPipelineFragmentShadingRateEnumStateCreateInfoNV structure and 1566 that any state specified by the 1567 slink:VkPipelineFragmentShadingRateStateCreateInfoKHR structure should 1568 be ignored. 1569-- 1570 1571[open,refpage='vkCmdSetFragmentShadingRateEnumNV',desc='Set pipeline fragment shading rate dynamically for a command buffer using enums',type='protos'] 1572-- 1573To <<pipelines-dynamic-state, dynamically set>> the pipeline fragment 1574shading rate and combiner operation, call: 1575 1576include::{generated}/api/protos/vkCmdSetFragmentShadingRateEnumNV.adoc[] 1577 1578 * pname:commandBuffer is the command buffer into which the command will be 1579 recorded. 1580 * pname:shadingRate specifies a elink:VkFragmentShadingRateNV enum 1581 indicating the pipeline fragment shading rate for subsequent drawing 1582 commands. 1583 * pname:combinerOps specifies a elink:VkFragmentShadingRateCombinerOpKHR 1584 determining how the 1585 <<primsrast-fragment-shading-rate-pipeline,pipeline>>, 1586 <<primsrast-fragment-shading-rate-primitive,primitive>>, and 1587 <<primsrast-fragment-shading-rate-attachment,attachment shading rates>> 1588 are <<primsrast-fragment-shading-rate-combining,combined>> for fragments 1589 generated by subsequent drawing commands. 1590 1591This command sets the pipeline fragment shading rate and combiner operation 1592for subsequent drawing commands when the graphics pipeline is created with 1593ename:VK_DYNAMIC_STATE_FRAGMENT_SHADING_RATE_KHR set in 1594slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. 1595Otherwise, this state is specified by the 1596slink:VkPipelineFragmentShadingRateEnumStateCreateInfoNV values used to 1597create the currently active pipeline. 1598 1599[NOTE] 1600.Note 1601==== 1602This command allows specifying additional shading rates beyond those 1603supported by flink:vkCmdSetFragmentShadingRateKHR. 1604For more information, refer to the 1605`apiext:VK_NV_fragment_shading_rate_enums` appendix. 1606==== 1607 1608.Valid Usage 1609**** 1610 * [[VUID-vkCmdSetFragmentShadingRateEnumNV-pipelineFragmentShadingRate-04576]] 1611 If <<features-pipelineFragmentShadingRate, 1612 pname:pipelineFragmentShadingRate>> is not enabled, pname:shadingRate 1613 must: be ename:VK_FRAGMENT_SHADING_RATE_1_INVOCATION_PER_PIXEL_NV 1614 * [[VUID-vkCmdSetFragmentShadingRateEnumNV-supersampleFragmentShadingRates-04577]] 1615 If <<features-supersampleFragmentShadingRates, 1616 pname:supersampleFragmentShadingRates>> is not enabled, 1617 pname:shadingRate must: not be 1618 ename:VK_FRAGMENT_SHADING_RATE_2_INVOCATIONS_PER_PIXEL_NV, 1619 ename:VK_FRAGMENT_SHADING_RATE_4_INVOCATIONS_PER_PIXEL_NV, 1620 ename:VK_FRAGMENT_SHADING_RATE_8_INVOCATIONS_PER_PIXEL_NV, or 1621 ename:VK_FRAGMENT_SHADING_RATE_16_INVOCATIONS_PER_PIXEL_NV 1622 * [[VUID-vkCmdSetFragmentShadingRateEnumNV-noInvocationFragmentShadingRates-04578]] 1623 If <<features-noInvocationFragmentShadingRates, 1624 pname:noInvocationFragmentShadingRates>> is not enabled, 1625 pname:shadingRate must: not be 1626 ename:VK_FRAGMENT_SHADING_RATE_NO_INVOCATIONS_NV 1627 * [[VUID-vkCmdSetFragmentShadingRateEnumNV-fragmentShadingRateEnums-04579]] 1628 The <<features-fragmentShadingRateEnums, 1629 pname:fragmentShadingRateEnums>> feature must: be enabled 1630 * [[VUID-vkCmdSetFragmentShadingRateEnumNV-pipelineFragmentShadingRate-04580]] 1631 One of the <<features-pipelineFragmentShadingRate, 1632 pname:pipelineFragmentShadingRate>>, 1633 <<features-primitiveFragmentShadingRate, 1634 pname:primitiveFragmentShadingRate>>, or 1635 <<features-attachmentFragmentShadingRate, 1636 pname:attachmentFragmentShadingRate>> features must: be enabled 1637 * [[VUID-vkCmdSetFragmentShadingRateEnumNV-primitiveFragmentShadingRate-04581]] 1638 If the <<features-primitiveFragmentShadingRate, 1639 pname:primitiveFragmentShadingRate>> feature is not enabled, 1640 pname:combinerOps[0] must: be 1641 ename:VK_FRAGMENT_SHADING_RATE_COMBINER_OP_KEEP_KHR 1642 * [[VUID-vkCmdSetFragmentShadingRateEnumNV-attachmentFragmentShadingRate-04582]] 1643 If the <<features-attachmentFragmentShadingRate, 1644 pname:attachmentFragmentShadingRate>> feature is not enabled, 1645 pname:combinerOps[1] must: be 1646 ename:VK_FRAGMENT_SHADING_RATE_COMBINER_OP_KEEP_KHR 1647 * [[VUID-vkCmdSetFragmentShadingRateEnumNV-fragmentSizeNonTrivialCombinerOps-04583]] 1648 If the <<limits-fragmentShadingRateNonTrivialCombinerOps, 1649 pname:fragmentSizeNonTrivialCombinerOps>> limit is not supported, 1650 elements of pname:combinerOps must: be either 1651 ename:VK_FRAGMENT_SHADING_RATE_COMBINER_OP_KEEP_KHR or 1652 ename:VK_FRAGMENT_SHADING_RATE_COMBINER_OP_REPLACE_KHR 1653**** 1654 1655include::{generated}/validity/protos/vkCmdSetFragmentShadingRateEnumNV.adoc[] 1656-- 1657 1658When the <<features-supersampleFragmentShadingRates, 1659pname:supersampleFragmentShadingRates>> or 1660<<features-noInvocationFragmentShadingRates, 1661pname:noInvocationFragmentShadingRates>> features are enabled, the behavior 1662of the <<primsrast-fragment-shading-rate-combining,shading rate combiner 1663operations>> is extended to support the shading rates enabled by those 1664features. 1665Primitive and attachment shading rate values are interpreted as 1666elink:VkFragmentShadingRateNV values and the behavior of the combiners is 1667modified as follows: 1668 1669 * For ename:VK_FRAGMENT_SHADING_RATE_COMBINER_OP_MIN_KHR, 1670 ename:VK_FRAGMENT_SHADING_RATE_COMBINER_OP_MAX_KHR, and 1671 ename:VK_FRAGMENT_SHADING_RATE_COMBINER_OP_MUL_KHR, if either 1672 [eq]#A~xy~# or [eq]#B~xy~# is 1673 ename:VK_FRAGMENT_SHADING_RATE_NO_INVOCATIONS_NV, 1674 [eq]#combine(A~xy~,B~xy~)# produces a shading rate of 1675 ename:VK_FRAGMENT_SHADING_RATE_NO_INVOCATIONS_NV, regardless of the 1676 other input shading rate. 1677 * For ename:VK_FRAGMENT_SHADING_RATE_COMBINER_OP_MIN_KHR, 1678 [eq]#combine(A~xy~,B~xy~)# produces a shading rate whose fragment size 1679 is the smaller of the fragment sizes of [eq]#A~xy~# and [eq]#B~xy~# and 1680 whose invocation count is the larger of the invocation counts of 1681 [eq]#A~xy~# and [eq]#B~xy~#. 1682 * For ename:VK_FRAGMENT_SHADING_RATE_COMBINER_OP_MAX_KHR, 1683 [eq]#combine(A~xy~,B~xy~)# produces a shading rate whose fragment size 1684 is the larger of the fragment sizes of [eq]#A~xy~# and [eq]#B~xy~# and 1685 whose invocation count is the smaller of the invocation counts of 1686 [eq]#A~xy~# and [eq]#B~xy~#. 1687 * For ename:VK_FRAGMENT_SHADING_RATE_COMBINER_OP_MUL_KHR, 1688 [eq]#combine(A~xy~,B~xy~)# produces a shading rate whose fragment size 1689 and invocation count is the product of the fragment sizes and invocation 1690 counts, respectively, of [eq]#A~xy~# and [eq]#B~xy~#. 1691 If the resulting shading rate has both multiple pixels and multiple 1692 invocations per fragment, an implementation may: adjust the shading rate 1693 by reducing both the pixel and invocation counts. 1694 1695If the final shading rate from the combiners is 1696ename:VK_FRAGMENT_SHADING_RATE_NO_INVOCATIONS_NV, no fragments will be 1697generated for any portion of a primitive using that shading rate. 1698 1699If the final shading rate from the combiners specifies multiple fragment 1700shader invocations per fragment, the fragment will be processed with 1701multiple unique samples as in <<primsrast-sampleshading, sample shading>>, 1702where the total number the total number of invocations is taken from the 1703shading rate and then clamped to pname:rasterizationSamples and 1704<<limits-maxFragmentShadingRateInvocationCount, 1705pname:maxFragmentShadingRateInvocationCount>>. 1706 1707endif::VK_NV_fragment_shading_rate_enums[] 1708 1709 1710ifdef::VK_NV_shading_rate_image[] 1711[[primsrast-shading-rate-image]] 1712== Shading Rate Image 1713 1714The <<features-shadingRateImage, pname:shadingRateImage>> feature allows 1715pipelines to use a <<glossary-shading-rate-image,shading rate image>> to 1716control the <<glossary-fragment-area, fragment area>> and the minimum number 1717of fragment shader invocations launched for each fragment. 1718When the shading rate image is enabled, the rasterizer determines a base 1719<<glossary-shading-rate,shading rate>> for each region of the framebuffer 1720covered by a primitive by fetching a value from the shading rate image and 1721translating it to a shading rate using a per-viewport shading rate palette. 1722This base shading rate is then adjusted to derive a final shading rate. 1723The final shading rate specifies the fragment area and fragment shader 1724invocation count to use for fragments generated in the region. 1725 1726[open,refpage='VkPipelineViewportShadingRateImageStateCreateInfoNV',desc='Structure specifying parameters controlling shading rate image usage',type='structs'] 1727-- 1728If the pname:pNext chain of slink:VkPipelineViewportStateCreateInfo includes 1729a sname:VkPipelineViewportShadingRateImageStateCreateInfoNV structure, then 1730that structure includes parameters controlling the shading rate. 1731 1732The sname:VkPipelineViewportShadingRateImageStateCreateInfoNV structure is 1733defined as: 1734 1735include::{generated}/api/structs/VkPipelineViewportShadingRateImageStateCreateInfoNV.adoc[] 1736 1737 * pname:sType is the type of this structure. 1738 * pname:pNext is `NULL` or a pointer to a structure extending this 1739 structure. 1740 * pname:shadingRateImageEnable specifies whether shading rate image and 1741 palettes are used during rasterization. 1742 * pname:viewportCount specifies the number of per-viewport palettes used 1743 to translate values stored in shading rate images. 1744 * pname:pShadingRatePalettes is a pointer to an array of 1745 slink:VkShadingRatePaletteNV structures defining the palette for each 1746 viewport. 1747 If the shading rate palette state is dynamic, this member is ignored. 1748 1749If this structure is not present, pname:shadingRateImageEnable is considered 1750to be ename:VK_FALSE, and the shading rate image and palettes are not used. 1751 1752.Valid Usage 1753**** 1754 * [[VUID-VkPipelineViewportShadingRateImageStateCreateInfoNV-viewportCount-02054]] 1755 If the <<features-multiViewport, pname:multiViewport>> feature is not 1756 enabled, pname:viewportCount must: be `0` or `1` 1757 * [[VUID-VkPipelineViewportShadingRateImageStateCreateInfoNV-viewportCount-02055]] 1758 pname:viewportCount must: be less than or equal to 1759 sname:VkPhysicalDeviceLimits::pname:maxViewports 1760 * [[VUID-VkPipelineViewportShadingRateImageStateCreateInfoNV-shadingRateImageEnable-02056]] 1761 If pname:shadingRateImageEnable is ename:VK_TRUE, pname:viewportCount 1762 must: be greater or equal to the pname:viewportCount member of 1763 slink:VkPipelineViewportStateCreateInfo 1764**** 1765include::{generated}/validity/structs/VkPipelineViewportShadingRateImageStateCreateInfoNV.adoc[] 1766-- 1767 1768[open,refpage='vkCmdBindShadingRateImageNV',desc='Bind a shading rate image on a command buffer',type='protos'] 1769-- 1770When shading rate image usage is enabled in the bound pipeline, the pipeline 1771uses a shading rate image specified by the command: 1772 1773include::{generated}/api/protos/vkCmdBindShadingRateImageNV.adoc[] 1774 1775 * pname:commandBuffer is the command buffer into which the command will be 1776 recorded. 1777 * pname:imageView is an image view handle specifying the shading rate 1778 image. 1779 pname:imageView may: be set to dlink:VK_NULL_HANDLE, which is equivalent 1780 to specifying a view of an image filled with zero values. 1781 * pname:imageLayout is the layout that the image subresources accessible 1782 from pname:imageView will be in when the shading rate image is accessed. 1783 1784.Valid Usage 1785**** 1786 * [[VUID-vkCmdBindShadingRateImageNV-None-02058]] 1787 The <<features-shadingRateImage, pname:shadingRateImage>> feature must: 1788 be enabled 1789 * [[VUID-vkCmdBindShadingRateImageNV-imageView-02059]] 1790 If pname:imageView is not dlink:VK_NULL_HANDLE, it must: be a valid 1791 slink:VkImageView handle of type ename:VK_IMAGE_VIEW_TYPE_2D or 1792 ename:VK_IMAGE_VIEW_TYPE_2D_ARRAY 1793 * [[VUID-vkCmdBindShadingRateImageNV-imageView-02060]] 1794 If pname:imageView is not dlink:VK_NULL_HANDLE, it must: have a format 1795 of ename:VK_FORMAT_R8_UINT 1796 * [[VUID-vkCmdBindShadingRateImageNV-imageView-02061]] 1797 If pname:imageView is not dlink:VK_NULL_HANDLE, it must: have been 1798 created with a pname:usage value including 1799 ename:VK_IMAGE_USAGE_SHADING_RATE_IMAGE_BIT_NV 1800 * [[VUID-vkCmdBindShadingRateImageNV-imageView-02062]] 1801 If pname:imageView is not dlink:VK_NULL_HANDLE, pname:imageLayout must: 1802 match the actual elink:VkImageLayout of each subresource accessible from 1803 pname:imageView at the time the subresource is accessed 1804 * [[VUID-vkCmdBindShadingRateImageNV-imageLayout-02063]] 1805 If pname:imageView is not dlink:VK_NULL_HANDLE, pname:imageLayout must: 1806 be ename:VK_IMAGE_LAYOUT_SHADING_RATE_OPTIMAL_NV or 1807 ename:VK_IMAGE_LAYOUT_GENERAL 1808**** 1809 1810include::{generated}/validity/protos/vkCmdBindShadingRateImageNV.adoc[] 1811-- 1812 1813When the shading rate image is enabled in the current pipeline, rasterizing 1814a primitive covering the pixel with coordinates (_x_,_y_) will fetch a 1815shading rate index value from the shading rate image bound by 1816fname:vkCmdBindShadingRateImageNV. 1817If the shading rate image view has a type of ename:VK_IMAGE_VIEW_TYPE_2D, 1818the lookup will use texel coordinates (_u_,_v_) where latexmath:[u = 1819\left\lfloor \frac{x}{twidth} \right\rfloor], latexmath:[v = \left\lfloor 1820\frac{y}{theight} \right\rfloor], and latexmath:[twidth] and 1821latexmath:[theight] are the width and height of the implementation-dependent 1822<<limits-shadingRateTexelSize, shading rate texel size>>. 1823If the shading rate image view has a type of 1824ename:VK_IMAGE_VIEW_TYPE_2D_ARRAY, the lookup will use texel coordinates 1825(_u_,_v_) to extract a texel from the layer _l_, where _l_ is the layer of 1826the framebuffer being rendered to. 1827If _l_ is greater than or equal to the number of layers in the image view, 1828layer zero will be used. 1829 1830If the bound shading rate image view is not dlink:VK_NULL_HANDLE and 1831contains a texel with coordinates (_u_,_v_) in layer _l_ (if applicable), 1832the single unsigned integer component for that texel will be used as the 1833shading rate index. 1834If the (_u_,_v_) coordinate is outside the extents of the subresource used 1835by the shading rate image view, or if the image view is 1836dlink:VK_NULL_HANDLE, the shading rate index is zero. 1837If the shading rate image view has multiple mipmap levels, the base level 1838identified by sname:VkImageSubresourceRange::pname:baseMipLevel will be 1839used. 1840 1841A shading rate index is mapped to a base shading rate using a lookup table 1842called the shading rate image palette. 1843There is a separate palette for each viewport. 1844The number of entries in each palette is given by the 1845implementation-dependent <<limits-shadingRatePaletteSize, shading rate image 1846palette size>>. 1847 1848ifdef::VK_EXT_extended_dynamic_state3[] 1849[open,refpage='vkCmdSetShadingRateImageEnableNV',desc='Specify the shading rate image enable state dynamically for a command buffer',type='protos'] 1850-- 1851To <<pipelines-dynamic-state, dynamically set>> the 1852pname:shadingRateImageEnable state, call: 1853 1854include::{generated}/api/protos/vkCmdSetShadingRateImageEnableNV.adoc[] 1855 1856 * pname:commandBuffer is the command buffer into which the command will be 1857 recorded. 1858 * pname:shadingRateImageEnable specifies the pname:shadingRateImageEnable 1859 state. 1860 1861This command sets the pname:shadingRateImageEnable state for subsequent 1862drawing commands when the graphics pipeline is created with 1863ename:VK_DYNAMIC_STATE_SHADING_RATE_IMAGE_ENABLE_NV set in 1864slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. 1865Otherwise, this state is specified by the 1866slink:VkPipelineViewportShadingRateImageStateCreateInfoNV::pname:shadingRateImageEnable 1867value used to create the currently active pipeline. 1868 1869.Valid Usage 1870**** 1871 * [[VUID-vkCmdSetShadingRateImageEnableNV-extendedDynamicState3ShadingRateImageEnable-07416]] 1872 The <<features-extendedDynamicState3ShadingRateImageEnable, 1873 pname:extendedDynamicState3ShadingRateImageEnable>> feature must: be 1874 enabled 1875**** 1876 1877include::{generated}/validity/protos/vkCmdSetShadingRateImageEnableNV.adoc[] 1878-- 1879endif::VK_EXT_extended_dynamic_state3[] 1880 1881[open,refpage='vkCmdSetViewportShadingRatePaletteNV',desc='Set shading rate image palettes dynamically for a command buffer',type='protos'] 1882-- 1883To <<pipelines-dynamic-state, dynamically set>> the per-viewport shading 1884rate image palettes, call: 1885 1886include::{generated}/api/protos/vkCmdSetViewportShadingRatePaletteNV.adoc[] 1887 1888 * pname:commandBuffer is the command buffer into which the command will be 1889 recorded. 1890 * pname:firstViewport is the index of the first viewport whose shading 1891 rate palette is updated by the command. 1892 * pname:viewportCount is the number of viewports whose shading rate 1893 palettes are updated by the command. 1894 * pname:pShadingRatePalettes is a pointer to an array of 1895 slink:VkShadingRatePaletteNV structures defining the palette for each 1896 viewport. 1897 1898This command sets the per-viewport shading rate image palettes for 1899subsequent drawing commands when the graphics pipeline is created with 1900ename:VK_DYNAMIC_STATE_VIEWPORT_SHADING_RATE_PALETTE_NV set in 1901slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. 1902Otherwise, this state is specified by the 1903slink:VkPipelineViewportShadingRateImageStateCreateInfoNV::pname:pShadingRatePalettes 1904values used to create the currently active pipeline. 1905 1906.Valid Usage 1907**** 1908 * [[VUID-vkCmdSetViewportShadingRatePaletteNV-None-02064]] 1909 The <<features-shadingRateImage, pname:shadingRateImage>> feature must: 1910 be enabled 1911 * [[VUID-vkCmdSetViewportShadingRatePaletteNV-firstViewport-02067]] 1912 The sum of pname:firstViewport and pname:viewportCount must: be between 1913 `1` and sname:VkPhysicalDeviceLimits::pname:maxViewports, inclusive 1914 * [[VUID-vkCmdSetViewportShadingRatePaletteNV-firstViewport-02068]] 1915 If the <<features-multiViewport, pname:multiViewport>> feature is not 1916 enabled, pname:firstViewport must: be `0` 1917 * [[VUID-vkCmdSetViewportShadingRatePaletteNV-viewportCount-02069]] 1918 If the <<features-multiViewport, pname:multiViewport>> feature is not 1919 enabled, pname:viewportCount must: be `1` 1920**** 1921 1922include::{generated}/validity/protos/vkCmdSetViewportShadingRatePaletteNV.adoc[] 1923-- 1924 1925[open,refpage='VkShadingRatePaletteNV',desc='Structure specifying a single shading rate palette',type='structs'] 1926-- 1927The sname:VkShadingRatePaletteNV structure specifies to contents of a single 1928shading rate image palette and is defined as: 1929 1930include::{generated}/api/structs/VkShadingRatePaletteNV.adoc[] 1931 1932 * pname:shadingRatePaletteEntryCount specifies the number of entries in 1933 the shading rate image palette. 1934 * pname:pShadingRatePaletteEntries is a pointer to an array of 1935 elink:VkShadingRatePaletteEntryNV enums defining the shading rate for 1936 each palette entry. 1937 1938.Valid Usage 1939**** 1940 * [[VUID-VkShadingRatePaletteNV-shadingRatePaletteEntryCount-02071]] 1941 pname:shadingRatePaletteEntryCount must: be between `1` and 1942 sname:VkPhysicalDeviceShadingRateImagePropertiesNV::pname:shadingRatePaletteSize, 1943 inclusive 1944 1945**** 1946include::{generated}/validity/structs/VkShadingRatePaletteNV.adoc[] 1947-- 1948 1949To determine the base shading rate image, a shading rate index _i_ is mapped 1950to array element _i_ in the array pname:pShadingRatePaletteEntries for the 1951palette corresponding to the viewport used for the fragment. 1952If _i_ is greater than or equal to the palette size 1953pname:shadingRatePaletteEntryCount, the base shading rate is undefined:. 1954 1955[open,refpage='VkShadingRatePaletteEntryNV',desc='Shading rate image palette entry types',type='enums'] 1956-- 1957The supported shading rate image palette entries are defined by 1958elink:VkShadingRatePaletteEntryNV: 1959 1960include::{generated}/api/enums/VkShadingRatePaletteEntryNV.adoc[] 1961 1962The following table indicates the width and height (in pixels) of each 1963fragment generated using the indicated shading rate, as well as the maximum 1964number of fragment shader invocations launched for each fragment. 1965When processing regions of a primitive that have a shading rate of 1966ename:VK_SHADING_RATE_PALETTE_ENTRY_NO_INVOCATIONS_NV, no fragments will be 1967generated in that region. 1968 1969[options="header"] 1970|==== 1971| Shading Rate | Width | Height | Invocations 1972| ename:VK_SHADING_RATE_PALETTE_ENTRY_NO_INVOCATIONS_NV | 0 | 0 | 0 1973| ename:VK_SHADING_RATE_PALETTE_ENTRY_16_INVOCATIONS_PER_PIXEL_NV | 1 | 1 | 16 1974| ename:VK_SHADING_RATE_PALETTE_ENTRY_8_INVOCATIONS_PER_PIXEL_NV | 1 | 1 | 8 1975| ename:VK_SHADING_RATE_PALETTE_ENTRY_4_INVOCATIONS_PER_PIXEL_NV | 1 | 1 | 4 1976| ename:VK_SHADING_RATE_PALETTE_ENTRY_2_INVOCATIONS_PER_PIXEL_NV | 1 | 1 | 2 1977| ename:VK_SHADING_RATE_PALETTE_ENTRY_1_INVOCATION_PER_PIXEL_NV | 1 | 1 | 1 1978| ename:VK_SHADING_RATE_PALETTE_ENTRY_1_INVOCATION_PER_2X1_PIXELS_NV | 2 | 1 | 1 1979| ename:VK_SHADING_RATE_PALETTE_ENTRY_1_INVOCATION_PER_1X2_PIXELS_NV | 1 | 2 | 1 1980| ename:VK_SHADING_RATE_PALETTE_ENTRY_1_INVOCATION_PER_2X2_PIXELS_NV | 2 | 2 | 1 1981| ename:VK_SHADING_RATE_PALETTE_ENTRY_1_INVOCATION_PER_4X2_PIXELS_NV | 4 | 2 | 1 1982| ename:VK_SHADING_RATE_PALETTE_ENTRY_1_INVOCATION_PER_2X4_PIXELS_NV | 2 | 4 | 1 1983| ename:VK_SHADING_RATE_PALETTE_ENTRY_1_INVOCATION_PER_4X4_PIXELS_NV | 4 | 4 | 1 1984|==== 1985-- 1986 1987When the shading rate image is disabled, a shading rate of 1988ename:VK_SHADING_RATE_PALETTE_ENTRY_1_INVOCATION_PER_PIXEL_NV will be used 1989as the base shading rate. 1990 1991Once a base shading rate has been established, it is adjusted to produce a 1992final shading rate. 1993First, if the base shading rate uses multiple pixels for each fragment, the 1994implementation may: reduce the fragment area to ensure that the total number 1995of coverage samples for all pixels in a fragment does not exceed 1996<<limits-shadingRateMaxCoarseSamples, an implementation-dependent maximum>>. 1997 1998If <<primsrast-sampleshading, sample shading>> is active in the current 1999pipeline and would result in processing _n_ (_n_ > 1) unique samples per 2000fragment when the shading rate image is disabled, the shading rate is 2001adjusted in an implementation-dependent manner to increase the number of 2002fragment shader invocations spawned by the primitive. 2003If the shading rate indicates _fs_ pixels per fragment and _fs_ is greater 2004than _n_, the fragment area is adjusted so each fragment has approximately 2005latexmath:[fs \over n] pixels. 2006Otherwise, if the shading rate indicates _ipf_ invocations per fragment, the 2007fragment area will be adjusted to a single pixel with approximately 2008latexmath:[ipf \times n \over fs] invocations per fragment. 2009 2010If sample shading occurs due to the use of a fragment shader input variable 2011decorated with code:SampleId or code:SamplePosition, the shading rate is 2012ignored. 2013Each fragment will have a single pixel and will spawn up to 2014pname:rasterizationSamples fragment shader invocations, as when using 2015<<primsrast-sampleshading, sample shading>> without a shading rate image. 2016 2017Finally, if the shading rate specifies multiple fragment shader invocations 2018per fragment, the total number of invocations in the shading rate is clamped 2019to be no larger than pname:rasterizationSamples. 2020 2021When the final shading rate for a primitive covering pixel (_x_,_y_) has a 2022fragment area of latexmath:[fw \times fh], the fragment for that pixel will 2023cover all pixels with coordinates (_x_',_y_') that satisfy the equations: 2024 2025[latexmath] 2026+++++++++++++++++++ 2027\begin{aligned} 2028\left\lfloor \frac{x}{fw} \right\rfloor = \left\lfloor \frac{x'}{fw} \right\rfloor 2029\end{aligned} 2030+++++++++++++++++++ 2031[latexmath] 2032+++++++++++++++++++ 2033\begin{aligned} 2034\left\lfloor \frac{y}{fh} \right\rfloor = \left\lfloor \frac{y'}{fh} \right\rfloor 2035\end{aligned} 2036+++++++++++++++++++ 2037 2038This combined fragment is considered to have multiple coverage samples; the 2039total number of samples in this fragment is given by latexmath:[samples = fw 2040\times fh \times rs] where _rs_ indicates the value of 2041sname:VkPipelineMultisampleStateCreateInfo::pname:rasterizationSamples 2042specified at pipeline creation time. 2043The set of coverage samples in the fragment is the union of the per-pixel 2044coverage samples in each of the fragment's pixels The location and order of 2045coverage samples within each pixel in the combined fragment are assigned as 2046described in 2047ifndef::VK_EXT_sample_locations[] 2048<<primsrast-multisampling, Multisampling>>. 2049endif::VK_EXT_sample_locations[] 2050ifdef::VK_EXT_sample_locations[] 2051<<primsrast-multisampling, Multisampling>> and <<primsrast-samplelocations, 2052Custom Sample Locations>>. 2053endif::VK_EXT_sample_locations[] 2054Each coverage sample in the set of pixels belonging to the combined fragment 2055is assigned a unique <<primsrast-multisampling-coverage-mask, coverage 2056index>> in the range [0,_samples_-1]. 2057If the <<features-shadingRateCoarseSampleOrder, 2058pname:shadingRateCoarseSampleOrder>> feature is supported, the order of 2059coverage samples can: be specified for each combination of fragment area and 2060coverage sample count. 2061If this feature is not supported, the sample order is 2062implementation-dependent. 2063 2064[open,refpage='VkPipelineViewportCoarseSampleOrderStateCreateInfoNV',desc='Structure specifying parameters controlling sample order in coarse fragments',type='structs'] 2065-- 2066If the pname:pNext chain of slink:VkPipelineViewportStateCreateInfo includes 2067a sname:VkPipelineViewportCoarseSampleOrderStateCreateInfoNV structure, then 2068that structure includes parameters controlling the order of coverage samples 2069in fragments larger than one pixel. 2070 2071The sname:VkPipelineViewportCoarseSampleOrderStateCreateInfoNV structure is 2072defined as: 2073 2074include::{generated}/api/structs/VkPipelineViewportCoarseSampleOrderStateCreateInfoNV.adoc[] 2075 2076 * pname:sType is the type of this structure. 2077 * pname:pNext is `NULL` or a pointer to a structure extending this 2078 structure. 2079 * pname:sampleOrderType specifies the mechanism used to order coverage 2080 samples in fragments larger than one pixel. 2081 * pname:customSampleOrderCount specifies the number of custom sample 2082 orderings to use when ordering coverage samples. 2083 * pname:pCustomSampleOrders is a pointer to an array of 2084 pname:customSampleOrderCount slink:VkCoarseSampleOrderCustomNV 2085 structures, each structure specifying the coverage sample order for a 2086 single combination of fragment area and coverage sample count. 2087 2088If this structure is not present, pname:sampleOrderType is considered to be 2089ename:VK_COARSE_SAMPLE_ORDER_TYPE_DEFAULT_NV. 2090 2091If pname:sampleOrderType is ename:VK_COARSE_SAMPLE_ORDER_TYPE_CUSTOM_NV, the 2092coverage sample order used for any combination of fragment area and coverage 2093sample count not enumerated in pname:pCustomSampleOrders will be identical 2094to that used for ename:VK_COARSE_SAMPLE_ORDER_TYPE_DEFAULT_NV. 2095 2096If the pipeline was created with 2097ename:VK_DYNAMIC_STATE_VIEWPORT_COARSE_SAMPLE_ORDER_NV, the contents of this 2098structure (if present) are ignored, and the coverage sample order is instead 2099specified by flink:vkCmdSetCoarseSampleOrderNV. 2100 2101.Valid Usage 2102**** 2103 * [[VUID-VkPipelineViewportCoarseSampleOrderStateCreateInfoNV-sampleOrderType-02072]] 2104 If pname:sampleOrderType is not 2105 ename:VK_COARSE_SAMPLE_ORDER_TYPE_CUSTOM_NV, 2106 pname:customSamplerOrderCount must: be `0` 2107 * [[VUID-VkPipelineViewportCoarseSampleOrderStateCreateInfoNV-pCustomSampleOrders-02234]] 2108 The array pname:pCustomSampleOrders must: not contain two structures 2109 with matching values for both the pname:shadingRate and 2110 pname:sampleCount members 2111**** 2112include::{generated}/validity/structs/VkPipelineViewportCoarseSampleOrderStateCreateInfoNV.adoc[] 2113-- 2114 2115[open,refpage='VkCoarseSampleOrderTypeNV',desc='Shading rate image sample ordering types',type='enums'] 2116-- 2117The type elink:VkCoarseSampleOrderTypeNV specifies the technique used to 2118order coverage samples in fragments larger than one pixel, and is defined 2119as: 2120 2121include::{generated}/api/enums/VkCoarseSampleOrderTypeNV.adoc[] 2122 2123 * ename:VK_COARSE_SAMPLE_ORDER_TYPE_DEFAULT_NV specifies that coverage 2124 samples will be ordered in an implementation-dependent manner. 2125 * ename:VK_COARSE_SAMPLE_ORDER_TYPE_CUSTOM_NV specifies that coverage 2126 samples will be ordered according to the array of custom orderings 2127 provided in either the pname:pCustomSampleOrders member of 2128 sname:VkPipelineViewportCoarseSampleOrderStateCreateInfoNV or the 2129 pname:pCustomSampleOrders member of flink:vkCmdSetCoarseSampleOrderNV. 2130 * ename:VK_COARSE_SAMPLE_ORDER_TYPE_PIXEL_MAJOR_NV specifies that coverage 2131 samples will be ordered sequentially, sorted first by pixel coordinate 2132 (in row-major order) and then by 2133 <<primsrast-multisampling-coverage-mask, sample index>>. 2134 * ename:VK_COARSE_SAMPLE_ORDER_TYPE_SAMPLE_MAJOR_NV specifies that 2135 coverage samples will be ordered sequentially, sorted first by 2136 <<primsrast-multisampling-coverage-mask, sample index>> and then by 2137 pixel coordinate (in row-major order). 2138-- 2139 2140When using a coarse sample order of 2141ename:VK_COARSE_SAMPLE_ORDER_TYPE_PIXEL_MAJOR_NV for a fragment with an 2142upper-left corner of latexmath:[(fx,fy)] with a width of latexmath:[fw 2143\times fh] and latexmath:[fsc] samples per pixel, 2144<<primsrast-multisampling-coverage-mask, coverage index>> latexmath:[cs] of 2145the fragment will be assigned to <<primsrast-multisampling-coverage-mask, 2146sample index>> latexmath:[fs] of pixel latexmath:[(px,py)] as follows: 2147 2148[latexmath] 2149+++++++++++++++++++ 2150\begin{aligned} 2151px = & fx + (\left\lfloor {cs \over fsc} \right\rfloor \text{ \% } fw) \\ 2152py = & fy + \left\lfloor {cs \over {fsc \times fw}} \right\rfloor \\ 2153fs = & cs \text{ \% } fsc 2154\end{aligned} 2155+++++++++++++++++++ 2156 2157When using a coarse sample order of 2158ename:VK_COARSE_SAMPLE_ORDER_TYPE_SAMPLE_MAJOR_NV, 2159<<primsrast-multisampling-coverage-mask, coverage index>> latexmath:[cs] 2160will be assigned as follows: 2161 2162[latexmath] 2163+++++++++++++++++++ 2164\begin{aligned} 2165px = & fx + cs \text{ \% } fw \\ 2166py = & (fy + \left\lfloor {cs \over fw} \right\rfloor \text{ \% } fh) \\ 2167fs = & \left\lfloor {cs \over {fw \times fh}} \right\rfloor 2168\end{aligned} 2169+++++++++++++++++++ 2170 2171[open,refpage='VkCoarseSampleOrderCustomNV',desc='Structure specifying parameters controlling shading rate image usage',type='structs'] 2172-- 2173The sname:VkCoarseSampleOrderCustomNV structure is defined as: 2174 2175include::{generated}/api/structs/VkCoarseSampleOrderCustomNV.adoc[] 2176 2177 * pname:shadingRate is a shading rate palette entry that identifies the 2178 fragment width and height for the combination of fragment area and 2179 per-pixel coverage sample count to control. 2180 * pname:sampleCount identifies the per-pixel coverage sample count for the 2181 combination of fragment area and coverage sample count to control. 2182 * pname:sampleLocationCount specifies the number of sample locations in 2183 the custom ordering. 2184 * pname:pSampleLocations is a pointer to an array of 2185 slink:VkCoarseSampleLocationNV structures specifying the location of 2186 each sample in the custom ordering. 2187 2188The sname:VkCoarseSampleOrderCustomNV structure is used with a coverage 2189sample ordering type of ename:VK_COARSE_SAMPLE_ORDER_TYPE_CUSTOM_NV to 2190specify the order of coverage samples for one combination of fragment width, 2191fragment height, and coverage sample count. 2192 2193When using a custom sample ordering, element _j_ in pname:pSampleLocations 2194specifies a specific pixel location and 2195<<primsrast-multisampling-coverage-mask, sample index>> that corresponds to 2196<<primsrast-multisampling-coverage-mask, coverage index>> _j_ in the 2197multi-pixel fragment. 2198 2199.Valid Usage 2200**** 2201 * [[VUID-VkCoarseSampleOrderCustomNV-shadingRate-02073]] 2202 pname:shadingRate must: be a shading rate that generates fragments with 2203 more than one pixel 2204 * [[VUID-VkCoarseSampleOrderCustomNV-sampleCount-02074]] 2205 pname:sampleCount must: correspond to a sample count enumerated in 2206 tlink:VkSampleCountFlags whose corresponding bit is set in 2207 slink:VkPhysicalDeviceLimits::pname:framebufferNoAttachmentsSampleCounts 2208 * [[VUID-VkCoarseSampleOrderCustomNV-sampleLocationCount-02075]] 2209 pname:sampleLocationCount must: be equal to the product of 2210 pname:sampleCount, the fragment width for pname:shadingRate, and the 2211 fragment height for pname:shadingRate 2212 * [[VUID-VkCoarseSampleOrderCustomNV-sampleLocationCount-02076]] 2213 pname:sampleLocationCount must: be less than or equal to the value of 2214 sname:VkPhysicalDeviceShadingRateImagePropertiesNV::pname:shadingRateMaxCoarseSamples 2215 * [[VUID-VkCoarseSampleOrderCustomNV-pSampleLocations-02077]] 2216 The array pname:pSampleLocations must: contain exactly one entry for 2217 every combination of valid values for pname:pixelX, pname:pixelY, and 2218 pname:sample in the structure slink:VkCoarseSampleOrderCustomNV 2219**** 2220include::{generated}/validity/structs/VkCoarseSampleOrderCustomNV.adoc[] 2221-- 2222 2223[open,refpage='VkCoarseSampleLocationNV',desc='Structure specifying parameters controlling shading rate image usage',type='structs'] 2224-- 2225The sname:VkCoarseSampleLocationNV structure identifies a specific pixel and 2226<<primsrast-multisampling-coverage-mask, sample index>> for one of the 2227coverage samples in a fragment that is larger than one pixel. 2228This structure is defined as: 2229 2230include::{generated}/api/structs/VkCoarseSampleLocationNV.adoc[] 2231 2232 * pname:pixelX is added to the x coordinate of the upper-leftmost pixel of 2233 each fragment to identify the pixel containing the coverage sample. 2234 * pname:pixelY is added to the y coordinate of the upper-leftmost pixel of 2235 each fragment to identify the pixel containing the coverage sample. 2236 * pname:sample is the number of the coverage sample in the pixel 2237 identified by pname:pixelX and pname:pixelY. 2238 2239.Valid Usage 2240**** 2241 * [[VUID-VkCoarseSampleLocationNV-pixelX-02078]] 2242 pname:pixelX must: be less than the width (in pixels) of the fragment 2243 * [[VUID-VkCoarseSampleLocationNV-pixelY-02079]] 2244 pname:pixelY must: be less than the height (in pixels) of the fragment 2245 * [[VUID-VkCoarseSampleLocationNV-sample-02080]] 2246 pname:sample must: be less than the number of coverage samples in each 2247 pixel belonging to the fragment 2248**** 2249 2250include::{generated}/validity/structs/VkCoarseSampleLocationNV.adoc[] 2251-- 2252 2253[open,refpage='vkCmdSetCoarseSampleOrderNV',desc='Set order of coverage samples for coarse fragments dynamically for a command buffer',type='protos'] 2254-- 2255To <<pipelines-dynamic-state, dynamically set>> the order of coverage 2256samples in fragments larger than one pixel, call: 2257 2258include::{generated}/api/protos/vkCmdSetCoarseSampleOrderNV.adoc[] 2259 2260 * pname:commandBuffer is the command buffer into which the command will be 2261 recorded. 2262 * pname:sampleOrderType specifies the mechanism used to order coverage 2263 samples in fragments larger than one pixel. 2264 * pname:customSampleOrderCount specifies the number of custom sample 2265 orderings to use when ordering coverage samples. 2266 * pname:pCustomSampleOrders is a pointer to an array of 2267 slink:VkCoarseSampleOrderCustomNV structures, each structure specifying 2268 the coverage sample order for a single combination of fragment area and 2269 coverage sample count. 2270 2271If pname:sampleOrderType is ename:VK_COARSE_SAMPLE_ORDER_TYPE_CUSTOM_NV, the 2272coverage sample order used for any combination of fragment area and coverage 2273sample count not enumerated in pname:pCustomSampleOrders will be identical 2274to that used for ename:VK_COARSE_SAMPLE_ORDER_TYPE_DEFAULT_NV. 2275 2276This command sets the order of coverage samples for subsequent drawing 2277commands when the graphics pipeline is created with 2278ename:VK_DYNAMIC_STATE_VIEWPORT_COARSE_SAMPLE_ORDER_NV set in 2279slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. 2280Otherwise, this state is specified by the 2281slink:VkPipelineViewportCoarseSampleOrderStateCreateInfoNV values used to 2282create the currently active pipeline. 2283 2284.Valid Usage 2285**** 2286 * [[VUID-vkCmdSetCoarseSampleOrderNV-sampleOrderType-02081]] 2287 If pname:sampleOrderType is not 2288 ename:VK_COARSE_SAMPLE_ORDER_TYPE_CUSTOM_NV, 2289 pname:customSamplerOrderCount must: be `0` 2290 * [[VUID-vkCmdSetCoarseSampleOrderNV-pCustomSampleOrders-02235]] 2291 The array pname:pCustomSampleOrders must: not contain two structures 2292 with matching values for both the pname:shadingRate and 2293 pname:sampleCount members 2294**** 2295 2296include::{generated}/validity/protos/vkCmdSetCoarseSampleOrderNV.adoc[] 2297-- 2298 2299If the final shading rate for a primitive covering pixel (_x_,_y_) results 2300in _n_ invocations per pixel (_n_ > 1), _n_ separate fragment shader 2301invocations will be generated for the fragment. 2302Each coverage sample in the fragment will be assigned to one of the _n_ 2303fragment shader invocations in an implementation-dependent manner. 2304The outputs from the <<interfaces-fragmentoutput, fragment output 2305interface>> of each shader invocation will be broadcast to all of the 2306framebuffer samples associated with the invocation. 2307If none of the coverage samples associated with a fragment shader invocation 2308is covered by a primitive, the implementation may: discard the fragment 2309shader invocation for those samples. 2310 2311If the final shading rate for a primitive covering pixel (_x_,_y_) results 2312in a fragment containing multiple pixels, a single set of fragment shader 2313invocations will be generated for all pixels in the combined fragment. 2314Outputs from the <<interfaces-fragmentoutput, fragment output interface>> 2315will be broadcast to all covered framebuffer samples belonging to the 2316fragment. 2317If the fragment shader executes code discarding the fragment, none of the 2318samples of the fragment will be updated. 2319 2320endif::VK_NV_shading_rate_image[] 2321 2322 2323[[primsrast-sampleshading]] 2324== Sample Shading 2325 2326Sample shading can: be used to specify a minimum number of unique samples to 2327process for each fragment. 2328If sample shading is enabled, an implementation must: invoke the fragment 2329shader at least [eq]#max({lceil} 2330slink:VkPipelineMultisampleStateCreateInfo::pname:minSampleShading {times} 2331slink:VkPipelineMultisampleStateCreateInfo::pname:rasterizationSamples 2332{rceil}, 1)# times per fragment. 2333If a fragment shader entry point's interface includes an input variable 2334decorated with a code:BuiltIn of code:SampleId or code:SamplePosition, a 2335value of `1.0` is used instead of pname:minSampleShading. 2336ifdef::VK_AMD_mixed_attachment_samples[] 2337If the `apiext:VK_AMD_mixed_attachment_samples` extension is enabled and the 2338subpass uses color attachments, the pname:samples value used to create each 2339color attachment is used instead of pname:rasterizationSamples. 2340endif::VK_AMD_mixed_attachment_samples[] 2341 2342Sample shading is enabled if at least one of the following conditions is 2343true: 2344 2345 * slink:VkPipelineMultisampleStateCreateInfo::pname:sampleShadingEnable is 2346 set to ename:VK_TRUE, or 2347 * the fragment shader's entry point interface includes input variables 2348 decorated with a code:BuiltIn of code:SampleId or code:SamplePosition 2349 built-ins. 2350 2351If there are fewer invocations than <<fragops,covered samples>>, 2352implementations may: include those samples in fragment shader invocations in 2353any manner as long as covered samples are all shaded at least once. 2354 2355 2356ifdef::VK_NV_fragment_shader_barycentric,VK_KHR_fragment_shader_barycentric[] 2357[[primsrast-barycentric]] 2358== Barycentric Interpolation 2359 2360When the pname:fragmentShaderBarycentric feature is enabled, the 2361code:PerVertexKHR <<shaders-interpolation-decorations, interpolation 2362decoration>> can: be used with fragment shader inputs to indicate that the 2363decorated inputs do not have associated data in the fragment. 2364Such inputs can: only be accessed in a fragment shader using an array index 2365whose value (0, 1, or 2) identifies one of the vertices of the primitive 2366that produced the fragment. 2367Reads of per-vertex values for missing vertices, such as the third vertex of 2368a line primitive, will return values from the valid vertex with the highest 2369index. 2370This means that the per-vertex values of indices 1 and 2 for point 2371primitives will be equal to those of index 0, and the per-vertex values of 2372index 2 for line primitives will be equal to those of index 1. 2373 2374ifndef::VK_NV_mesh_shader,VK_EXT_mesh_shader[] 2375When <<tessellation, tessellation>> and <<geometry, geometry shading>> 2376endif::VK_NV_mesh_shader,VK_EXT_mesh_shader[] 2377ifdef::VK_NV_mesh_shader,VK_EXT_mesh_shader[] 2378When <<tessellation, tessellation>>, <<geometry, geometry shading>>, and 2379<<mesh,mesh shading>> 2380endif::VK_NV_mesh_shader,VK_EXT_mesh_shader[] 2381are not active, fragment shader inputs decorated with code:PerVertexKHR will 2382take values from one of the vertices of the primitive that produced the 2383fragment, identified by the extra index provided in SPIR-V code accessing 2384the input. 2385If the _n_ vertices passed to a draw call are numbered 0 through _n_-1, and 2386the point, line, and triangle primitives produced by the draw call are 2387numbered with consecutive integers beginning with zero, the following table 2388indicates the original vertex numbers used 2389ifdef::VK_EXT_provoking_vertex[] 2390when the <<vertexpostproc-flatshading,provoking vertex mode>> is 2391ename:VK_PROVOKING_VERTEX_MODE_FIRST_VERTEX_EXT 2392endif::VK_EXT_provoking_vertex[] 2393for index values of 0, 1, and 2. 2394If an input decorated with code:PerVertexKHR is accessed with any other 2395vertex index value, or is accessed while rasterizing a polygon when the 2396slink:VkPipelineRasterizationStateCreateInfo::pname:polygonMode property of 2397the currently active pipeline is not ename:VK_POLYGON_MODE_FILL, an 2398undefined: value is returned. 2399 2400[[primsrast-barycentric-order-table]] 2401[options="header"] 2402|==== 2403| Primitive Topology | Vertex 0 | Vertex 1 | Vertex 2 2404| ename:VK_PRIMITIVE_TOPOLOGY_POINT_LIST | i | i | i 2405| ename:VK_PRIMITIVE_TOPOLOGY_LINE_LIST | 2i | 2i+1 | 2i+1 2406| ename:VK_PRIMITIVE_TOPOLOGY_LINE_STRIP | i | i+1 | i+1 2407| ename:VK_PRIMITIVE_TOPOLOGY_TRIANGLE_LIST | 3i | 3i+1 | 3i+2 2408| ename:VK_PRIMITIVE_TOPOLOGY_TRIANGLE_STRIP (even) | i | i+1 | i+2 2409| ename:VK_PRIMITIVE_TOPOLOGY_TRIANGLE_STRIP (odd) | i | i+2 | i+1 2410| ename:VK_PRIMITIVE_TOPOLOGY_TRIANGLE_FAN | i+1 | i+2 | 0 2411| ename:VK_PRIMITIVE_TOPOLOGY_LINE_LIST_WITH_ADJACENCY | 4i+1 | 4i+2 | 4i+2 2412| ename:VK_PRIMITIVE_TOPOLOGY_LINE_STRIP_WITH_ADJACENCY | i+1 | i+2 | i+2 2413| ename:VK_PRIMITIVE_TOPOLOGY_TRIANGLE_LIST_WITH_ADJACENCY | 6i | 6i+2 | 6i+4 2414| ename:VK_PRIMITIVE_TOPOLOGY_TRIANGLE_STRIP_WITH_ADJACENCY (even) | 2i | 2i+2 | 2i+4 2415| ename:VK_PRIMITIVE_TOPOLOGY_TRIANGLE_STRIP_WITH_ADJACENCY (odd) | 2i | 2i+4 | 2i+2 2416|==== 2417 2418ifdef::VK_EXT_provoking_vertex[] 2419When the provoking vertex mode is 2420ename:VK_PROVOKING_VERTEX_MODE_LAST_VERTEX_EXT, the original vertex numbers 2421used are the same as above except as indicated in the table below. 2422 2423[[primsrast-barycentric-order-table-last-vertex]] 2424[options="header"] 2425|==== 2426| Primitive Topology | Vertex 0 | Vertex 1 | Vertex 2 2427ifdef::VK_KHR_fragment_shader_barycentric[] 2428| ename:VK_PRIMITIVE_TOPOLOGY_TRIANGLE_STRIP (odd, and 2429pname:triStripVertexOrderIndependentOfProvokingVertex of 2430slink:VkPhysicalDeviceFragmentShaderBarycentricPropertiesKHR is ename:VK_FALSE) | i+1 | i | i+2 2431endif::VK_KHR_fragment_shader_barycentric[] 2432ifndef::VK_KHR_fragment_shader_barycentric[] 2433| ename:VK_PRIMITIVE_TOPOLOGY_TRIANGLE_STRIP (odd) | i+1 | i | i+2 2434endif::VK_KHR_fragment_shader_barycentric[] 2435| ename:VK_PRIMITIVE_TOPOLOGY_TRIANGLE_FAN | 0 | i+1 | i+2 2436| ename:VK_PRIMITIVE_TOPOLOGY_TRIANGLE_STRIP_WITH_ADJACENCY (odd) | 2i+2 | 2i | 2i+4 2437|==== 2438endif::VK_EXT_provoking_vertex[] 2439 2440When geometry 2441ifdef::VK_NV_mesh_shader,VK_EXT_mesh_shader[or mesh] 2442shading is active, primitives processed by fragment shaders are assembled 2443from the vertices emitted by the geometry 2444ifdef::VK_NV_mesh_shader,VK_EXT_mesh_shader[or mesh] 2445shader. 2446In this case, the vertices used for fragment shader inputs decorated with 2447code:PerVertexKHR are derived by treating the primitives produced by the 2448shader as though they were specified by a draw call and consulting 2449<<primsrast-barycentric-order-table, the table above>>. 2450 2451When using tessellation without geometry shading, the tessellator produces 2452primitives in an implementation-dependent manner. 2453While there is no defined vertex ordering for inputs decorated with 2454code:PerVertexKHR, the vertex ordering used in this case will be consistent 2455with the ordering used to derive the values of inputs decorated with 2456code:BaryCoordKHR or code:BaryCoordNoPerspKHR. 2457 2458Fragment shader inputs decorated with code:BaryCoordKHR or 2459code:BaryCoordNoPerspKHR hold three-component vectors with barycentric 2460weights that indicate the location of the fragment relative to the 2461screen-space locations of vertices of its primitive. 2462For point primitives, such variables are always assigned the value 2463[eq]#(1,0,0)#. 2464For <<primsrast-lines-basic, line>> primitives, the built-ins are obtained 2465by interpolating an attribute whose values for the vertices numbered 0 and 1 2466are [eq]#(1,0,0)# and [eq]#(0,1,0)#, respectively. 2467For <<primsrast-polygons-basic, polygon>> primitives, the built-ins are 2468obtained by interpolating an attribute whose values for the vertices 2469numbered 0, 1, and 2 are [eq]#(1,0,0)#, [eq]#(0,1,0)#, and [eq]#(0,0,1)#, 2470respectively. 2471For code:BaryCoordKHR, the values are obtained using perspective 2472interpolation. 2473For code:BaryCoordNoPerspKHR, the values are obtained using linear 2474interpolation. 2475The values of code:BaryCoordKHR and code:BaryCoordNoPerspKHR are undefined: 2476while rasterizing a polygon when the 2477slink:VkPipelineRasterizationStateCreateInfo::pname:polygonMode property of 2478the currently active pipeline is not ename:VK_POLYGON_MODE_FILL. 2479 2480endif::VK_NV_fragment_shader_barycentric,VK_KHR_fragment_shader_barycentric[] 2481 2482 2483[[primsrast-points]] 2484== Points 2485 2486A point is drawn by generating a set of fragments in the shape of a square 2487centered around the vertex of the point. 2488Each vertex has an associated point size controlling the width/height of 2489that square. 2490The point size is taken from the (potentially clipped) shader built-in 2491code:PointSize written by: 2492 2493 * the geometry shader, if active; 2494 * the tessellation evaluation shader, if active and no geometry shader is 2495 active; 2496 * the vertex shader, otherwise 2497 2498and clamped to the implementation-dependent point size range 2499[eq]#[pname:pointSizeRange[0],pname:pointSizeRange[1]]#. 2500The value written to code:PointSize must: be greater than zero. 2501 2502Not all point sizes need be supported, but the size 1.0 must: be supported. 2503The range of supported sizes and the size of evenly-spaced gradations within 2504that range are implementation-dependent. 2505The range and gradations are obtained from the pname:pointSizeRange and 2506pname:pointSizeGranularity members of slink:VkPhysicalDeviceLimits. 2507If, for instance, the size range is from 0.1 to 2.0 and the gradation size 2508is 0.1, then the sizes 0.1, 0.2, ..., 1.9, 2.0 are supported. 2509Additional point sizes may: also be supported. 2510There is no requirement that these sizes be equally spaced. 2511If an unsupported size is requested, the nearest supported size is used 2512instead. 2513 2514ifdef::VK_EXT_fragment_density_map[] 2515Further, if the render pass has a fragment density map attachment, point 2516size may: be rounded by the implementation to a multiple of the fragment's 2517width or height. 2518endif::VK_EXT_fragment_density_map[] 2519 2520 2521[[primsrast-points-basic]] 2522=== Basic Point Rasterization 2523 2524Point rasterization produces a fragment for each fragment area group of 2525framebuffer pixels with one or more sample points that intersect a region 2526centered at the point's [eq]#(x~f~,y~f~)#. 2527This region is a square with side equal to the current point size. 2528Coverage bits that correspond to sample points that intersect the region are 25291, other coverage bits are 0. 2530All fragments produced in rasterizing a point are assigned the same 2531associated data, which are those of the vertex corresponding to the point. 2532However, the fragment shader built-in code:PointCoord contains point sprite 2533texture coordinates. 2534The [eq]#s# and [eq]#t# point sprite texture coordinates vary from zero to 2535one across the point horizontally left-to-right and vertically 2536top-to-bottom, respectively. 2537The following formulas are used to evaluate [eq]#s# and [eq]#t#: 2538 2539[latexmath] 2540++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2541s = {1 \over 2} + { \left( x_p - x_f \right) \over \text{size} } 2542++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2543 2544[latexmath] 2545++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2546t = {1 \over 2} + { \left( y_p - y_f \right) \over \text{size} } 2547++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2548 2549where size is the point's size; [eq]#(x~p~,y~p~)# is the location at which 2550the point sprite coordinates are evaluated - this may: be the framebuffer 2551coordinates of the fragment center, or the location of a sample; and 2552[eq]#(x~f~,y~f~)# is the exact, unrounded framebuffer coordinate of the 2553vertex for the point. 2554 2555 2556[[primsrast-lines]] 2557== Line Segments 2558 2559ifdef::VK_EXT_line_rasterization[] 2560[open,refpage='VkPipelineRasterizationLineStateCreateInfoEXT',desc='Structure specifying parameters of a newly created pipeline line rasterization state',type='structs'] 2561-- 2562Line segment rasterization options are controlled by the 2563slink:VkPipelineRasterizationLineStateCreateInfoEXT structure. 2564 2565The sname:VkPipelineRasterizationLineStateCreateInfoEXT structure is defined 2566as: 2567 2568include::{generated}/api/structs/VkPipelineRasterizationLineStateCreateInfoEXT.adoc[] 2569 2570 * pname:sType is the type of this structure. 2571 * pname:pNext is `NULL` or a pointer to a structure extending this 2572 structure. 2573 * pname:lineRasterizationMode is a elink:VkLineRasterizationModeEXT value 2574 selecting the style of line rasterization. 2575 * pname:stippledLineEnable enables <<primsrast-lines-stipple, stippled 2576 line rasterization>>. 2577 * pname:lineStippleFactor is the repeat factor used in stippled line 2578 rasterization. 2579 * pname:lineStipplePattern is the bit pattern used in stippled line 2580 rasterization. 2581 2582If pname:stippledLineEnable is ename:VK_FALSE, the values of 2583pname:lineStippleFactor and pname:lineStipplePattern are ignored. 2584 2585.Valid Usage 2586**** 2587 * [[VUID-VkPipelineRasterizationLineStateCreateInfoEXT-lineRasterizationMode-02768]] 2588 If pname:lineRasterizationMode is 2589 ename:VK_LINE_RASTERIZATION_MODE_RECTANGULAR_EXT, then the 2590 <<features-rectangularLines, pname:rectangularLines>> feature must: be 2591 enabled 2592 * [[VUID-VkPipelineRasterizationLineStateCreateInfoEXT-lineRasterizationMode-02769]] 2593 If pname:lineRasterizationMode is 2594 ename:VK_LINE_RASTERIZATION_MODE_BRESENHAM_EXT, then the 2595 <<features-bresenhamLines, pname:bresenhamLines>> feature must: be 2596 enabled 2597 * [[VUID-VkPipelineRasterizationLineStateCreateInfoEXT-lineRasterizationMode-02770]] 2598 If pname:lineRasterizationMode is 2599 ename:VK_LINE_RASTERIZATION_MODE_RECTANGULAR_SMOOTH_EXT, then the 2600 <<features-smoothLines, pname:smoothLines>> feature must: be enabled 2601 * [[VUID-VkPipelineRasterizationLineStateCreateInfoEXT-stippledLineEnable-02771]] 2602 If pname:stippledLineEnable is ename:VK_TRUE and 2603 pname:lineRasterizationMode is 2604 ename:VK_LINE_RASTERIZATION_MODE_RECTANGULAR_EXT, then the 2605 <<features-stippledRectangularLines, pname:stippledRectangularLines>> 2606 feature must: be enabled 2607 * [[VUID-VkPipelineRasterizationLineStateCreateInfoEXT-stippledLineEnable-02772]] 2608 If pname:stippledLineEnable is ename:VK_TRUE and 2609 pname:lineRasterizationMode is 2610 ename:VK_LINE_RASTERIZATION_MODE_BRESENHAM_EXT, then the 2611 <<features-stippledBresenhamLines, pname:stippledBresenhamLines>> 2612 feature must: be enabled 2613 * [[VUID-VkPipelineRasterizationLineStateCreateInfoEXT-stippledLineEnable-02773]] 2614 If pname:stippledLineEnable is ename:VK_TRUE and 2615 pname:lineRasterizationMode is 2616 ename:VK_LINE_RASTERIZATION_MODE_RECTANGULAR_SMOOTH_EXT, then the 2617 <<features-stippledSmoothLines, pname:stippledSmoothLines>> feature 2618 must: be enabled 2619 * [[VUID-VkPipelineRasterizationLineStateCreateInfoEXT-stippledLineEnable-02774]] 2620 If pname:stippledLineEnable is ename:VK_TRUE and 2621 pname:lineRasterizationMode is 2622 ename:VK_LINE_RASTERIZATION_MODE_DEFAULT_EXT, then the 2623 <<features-stippledRectangularLines, pname:stippledRectangularLines>> 2624 feature must: be enabled and 2625 slink:VkPhysicalDeviceLimits::pname:strictLines must: be ename:VK_TRUE 2626**** 2627 2628include::{generated}/validity/structs/VkPipelineRasterizationLineStateCreateInfoEXT.adoc[] 2629-- 2630 2631[open,refpage='VkLineRasterizationModeEXT',desc='Line rasterization modes',type='enums'] 2632-- 2633Possible values of 2634slink:VkPipelineRasterizationLineStateCreateInfoEXT::pname:lineRasterizationMode 2635are: 2636 2637include::{generated}/api/enums/VkLineRasterizationModeEXT.adoc[] 2638 2639 * ename:VK_LINE_RASTERIZATION_MODE_DEFAULT_EXT is equivalent to 2640 ename:VK_LINE_RASTERIZATION_MODE_RECTANGULAR_EXT if 2641 slink:VkPhysicalDeviceLimits::pname:strictLines is ename:VK_TRUE, 2642 otherwise lines are drawn as non-pname:strictLines parallelograms. 2643 Both of these modes are defined in <<primsrast-lines-basic,Basic Line 2644 Segment Rasterization>>. 2645 * ename:VK_LINE_RASTERIZATION_MODE_RECTANGULAR_EXT specifies lines drawn 2646 as if they were rectangles extruded from the line 2647 * ename:VK_LINE_RASTERIZATION_MODE_BRESENHAM_EXT specifies lines drawn by 2648 determining which pixel diamonds the line intersects and exits, as 2649 defined in <<primsrast-lines-bresenham,Bresenham Line Segment 2650 Rasterization>>. 2651 * ename:VK_LINE_RASTERIZATION_MODE_RECTANGULAR_SMOOTH_EXT specifies lines 2652 drawn if they were rectangles extruded from the line, with alpha 2653 falloff, as defined in <<primsrast-lines-smooth,Smooth Lines>>. 2654-- 2655 2656ifdef::VK_EXT_extended_dynamic_state3[] 2657 2658[open,refpage='vkCmdSetLineRasterizationModeEXT',desc='Specify the line rasterization mode dynamically for a command buffer',type='protos'] 2659-- 2660To <<pipelines-dynamic-state, dynamically set>> the 2661pname:lineRasterizationMode state, call: 2662 2663include::{generated}/api/protos/vkCmdSetLineRasterizationModeEXT.adoc[] 2664 2665 * pname:commandBuffer is the command buffer into which the command will be 2666 recorded. 2667 * pname:lineRasterizationMode specifies the pname:lineRasterizationMode 2668 state. 2669 2670This command sets the pname:lineRasterizationMode state for subsequent 2671drawing commands when the graphics pipeline is created with 2672ename:VK_DYNAMIC_STATE_LINE_RASTERIZATION_MODE_EXT set in 2673slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. 2674Otherwise, this state is specified by the 2675slink:VkPipelineRasterizationLineStateCreateInfoEXT::pname:lineRasterizationMode 2676value used to create the currently active pipeline. 2677 2678.Valid Usage 2679**** 2680 * [[VUID-vkCmdSetLineRasterizationModeEXT-extendedDynamicState3LineRasterizationMode-07417]] 2681 The <<features-extendedDynamicState3LineRasterizationMode, 2682 pname:extendedDynamicState3LineRasterizationMode>> feature must: be 2683 enabled 2684 * [[VUID-vkCmdSetLineRasterizationModeEXT-lineRasterizationMode-07418]] 2685 If pname:lineRasterizationMode is 2686 ename:VK_LINE_RASTERIZATION_MODE_RECTANGULAR_EXT, then the 2687 <<features-rectangularLines, pname:rectangularLines>> feature must: be 2688 enabled 2689 * [[VUID-vkCmdSetLineRasterizationModeEXT-lineRasterizationMode-07419]] 2690 If pname:lineRasterizationMode is 2691 ename:VK_LINE_RASTERIZATION_MODE_BRESENHAM_EXT, then the 2692 <<features-bresenhamLines, pname:bresenhamLines>> feature must: be 2693 enabled 2694 * [[VUID-vkCmdSetLineRasterizationModeEXT-lineRasterizationMode-07420]] 2695 If pname:lineRasterizationMode is 2696 ename:VK_LINE_RASTERIZATION_MODE_RECTANGULAR_SMOOTH_EXT, then the 2697 <<features-smoothLines, pname:smoothLines>> feature must: be enabled 2698**** 2699 2700include::{generated}/validity/protos/vkCmdSetLineRasterizationModeEXT.adoc[] 2701-- 2702 2703[open,refpage='vkCmdSetLineStippleEnableEXT',desc='Specify the line stipple enable dynamically for a command buffer',type='protos'] 2704-- 2705To <<pipelines-dynamic-state, dynamically set>> the pname:stippledLineEnable 2706state, call: 2707 2708include::{generated}/api/protos/vkCmdSetLineStippleEnableEXT.adoc[] 2709 2710 * pname:commandBuffer is the command buffer into which the command will be 2711 recorded. 2712 * pname:stippledLineEnable specifies the pname:stippledLineEnable state. 2713 2714This command sets the pname:stippledLineEnable state for subsequent drawing 2715commands when the graphics pipeline is created with 2716ename:VK_DYNAMIC_STATE_LINE_STIPPLE_ENABLE_EXT set in 2717slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. 2718Otherwise, this state is specified by the 2719slink:VkPipelineRasterizationLineStateCreateInfoEXT::pname:stippledLineEnable 2720value used to create the currently active pipeline. 2721 2722.Valid Usage 2723**** 2724 * [[VUID-vkCmdSetLineStippleEnableEXT-extendedDynamicState3LineStippleEnable-07421]] 2725 The <<features-extendedDynamicState3LineStippleEnable, 2726 pname:extendedDynamicState3LineStippleEnable>> feature must: be enabled 2727**** 2728 2729include::{generated}/validity/protos/vkCmdSetLineStippleEnableEXT.adoc[] 2730-- 2731 2732endif::VK_EXT_extended_dynamic_state3[] 2733 2734endif::VK_EXT_line_rasterization[] 2735 2736[open,refpage='vkCmdSetLineWidth',desc='Set line width dynamically for a command buffer',type='protos'] 2737-- 2738To <<pipelines-dynamic-state, dynamically set>> the line width, call: 2739 2740include::{generated}/api/protos/vkCmdSetLineWidth.adoc[] 2741 2742 * pname:commandBuffer is the command buffer into which the command will be 2743 recorded. 2744 * pname:lineWidth is the width of rasterized line segments. 2745 2746This command sets the line width for subsequent drawing commands when the 2747graphics pipeline is created with ename:VK_DYNAMIC_STATE_LINE_WIDTH set in 2748slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. 2749Otherwise, this state is specified by the 2750slink:VkPipelineRasterizationStateCreateInfo::pname:lineWidth value used to 2751create the currently active pipeline. 2752 2753.Valid Usage 2754**** 2755 * [[VUID-vkCmdSetLineWidth-lineWidth-00788]] 2756 If the <<features-wideLines, pname:wideLines>> feature is not enabled, 2757 pname:lineWidth must: be `1.0` 2758**** 2759 2760include::{generated}/validity/protos/vkCmdSetLineWidth.adoc[] 2761-- 2762 2763Not all line widths need be supported for line segment rasterization, but 2764width 1.0 antialiased segments must: be provided. 2765The range and gradations are obtained from the pname:lineWidthRange and 2766pname:lineWidthGranularity members of slink:VkPhysicalDeviceLimits. 2767If, for instance, the size range is from 0.1 to 2.0 and the gradation size 2768is 0.1, then the sizes 0.1, 0.2, ..., 1.9, 2.0 are supported. 2769Additional line widths may: also be supported. 2770There is no requirement that these widths be equally spaced. 2771If an unsupported width is requested, the nearest supported width is used 2772instead. 2773 2774ifdef::VK_EXT_fragment_density_map[] 2775Further, if the render pass has a fragment density map attachment, line 2776width may: be rounded by the implementation to a multiple of the fragment's 2777width or height. 2778endif::VK_EXT_fragment_density_map[] 2779 2780 2781[[primsrast-lines-basic]] 2782=== Basic Line Segment Rasterization 2783 2784ifdef::VK_EXT_line_rasterization[] 2785If the pname:lineRasterizationMode member of 2786slink:VkPipelineRasterizationLineStateCreateInfoEXT is 2787ename:VK_LINE_RASTERIZATION_MODE_RECTANGULAR_EXT, rasterized 2788endif::VK_EXT_line_rasterization[] 2789ifndef::VK_EXT_line_rasterization[] 2790Rasterized 2791endif::VK_EXT_line_rasterization[] 2792line segments produce fragments which intersect a rectangle centered on the 2793line segment. 2794Two of the edges are parallel to the specified line segment; each is at a 2795distance of one-half the current width from that segment in directions 2796perpendicular to the direction of the line. 2797The other two edges pass through the line endpoints and are perpendicular to 2798the direction of the specified line segment. 2799Coverage bits that correspond to sample points that intersect the rectangle 2800are 1, other coverage bits are 0. 2801 2802Next we specify how the data associated with each rasterized fragment are 2803obtained. 2804Let [eq]#**p**~r~ = (x~d~, y~d~)# be the framebuffer coordinates at which 2805associated data are evaluated. 2806This may: be the center of a fragment or the location of a sample within the 2807fragment. 2808When pname:rasterizationSamples is ename:VK_SAMPLE_COUNT_1_BIT, the fragment 2809center must: be used. 2810Let [eq]#**p**~a~ = (x~a~, y~a~)# and [eq]#**p**~b~ = (x~b~,y~b~)# be 2811initial and final endpoints of the line segment, respectively. 2812Set 2813 2814// Equation {linet:eq} 2815[latexmath] 2816++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2817t = {{( \mathbf{p}_r - \mathbf{p}_a ) \cdot ( \mathbf{p}_b - \mathbf{p}_a )} 2818 \over {\| \mathbf{p}_b - \mathbf{p}_a \|^2 }} 2819++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2820 2821(Note that [eq]#t = 0# at [eq]#**p**~a~# and [eq]#t = 1# at [eq]#**p**~b~#. 2822Also note that this calculation projects the vector from [eq]#**p**~a~# to 2823[eq]#**p**~r~# onto the line, and thus computes the normalized distance of 2824the fragment along the line.) 2825 2826If <<limits-strictLines, pname:strictLines>> is ename:VK_TRUE, line segments 2827are rasterized using perspective or linear interpolation. 2828 2829[[line_perspective_interpolation]] 2830_Perspective interpolation_ for a line segment interpolates two values in a 2831manner that is correct when taking the perspective of the viewport into 2832consideration, by way of the line segment's clip coordinates. 2833An interpolated value [eq]#f# can be determined by 2834 2835[latexmath] 2836++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2837f = {{ (1-t) {f_a / w_a} + t { f_b / w_b} } \over 2838 {(1-t) / w_a + t / w_b }} 2839++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2840 2841where [eq]#f~a~# and [eq]#f~b~# are the data associated with the starting 2842and ending endpoints of the segment, respectively; [eq]#w~a~# and [eq]#w~b~# 2843are the clip [eq]#w# coordinates of the starting and ending endpoints of the 2844segment, respectively. 2845 2846[[line_linear_interpolation]] 2847_Linear interpolation_ for a line segment directly interpolates two values, 2848and an interpolated value [eq]#f# can be determined by 2849 2850 {empty}:: [eq]#f = (1 - t) f~a~ {plus} t f~b~# 2851 2852where [eq]#f~a~# and [eq]#f~b~# are the data associated with the starting 2853and ending endpoints of the segment, respectively. 2854 2855The clip coordinate [eq]#w# for a sample is determined using perspective 2856interpolation. 2857The depth value [eq]#z# for a sample is determined using linear 2858interpolation. 2859Interpolation of fragment shader input values are determined by 2860<<shaders-interpolation-decorations,Interpolation decorations>>. 2861 2862The above description documents the preferred method of line rasterization, 2863and must: be used when 2864ifdef::VK_EXT_line_rasterization[] 2865pname:lineRasterizationMode is 2866ename:VK_LINE_RASTERIZATION_MODE_RECTANGULAR_EXT. 2867endif::VK_EXT_line_rasterization[] 2868ifndef::VK_EXT_line_rasterization[] 2869the implementation advertises the pname:strictLines limit in 2870slink:VkPhysicalDeviceLimits as ename:VK_TRUE. 2871endif::VK_EXT_line_rasterization[] 2872 2873When pname:strictLines is ename:VK_FALSE, 2874ifdef::VK_EXT_line_rasterization[] 2875and when the pname:lineRasterizationMode is 2876ename:VK_LINE_RASTERIZATION_MODE_DEFAULT_EXT, 2877endif::VK_EXT_line_rasterization[] 2878the edges of the lines are generated as a parallelogram surrounding the 2879original line. 2880The major axis is chosen by noting the axis in which there is the greatest 2881distance between the line start and end points. 2882If the difference is equal in both directions then the X axis is chosen as 2883the major axis. 2884Edges 2 and 3 are aligned to the minor axis and are centered on the 2885endpoints of the line as in <<fig-non-strict-lines>>, and each is 2886pname:lineWidth long. 2887Edges 0 and 1 are parallel to the line and connect the endpoints of edges 2 2888and 3. 2889Coverage bits that correspond to sample points that intersect the 2890parallelogram are 1, other coverage bits are 0. 2891 2892Samples that fall exactly on the edge of the parallelogram follow the 2893polygon rasterization rules. 2894 2895Interpolation occurs as if the parallelogram was decomposed into two 2896triangles where each pair of vertices at each end of the line has identical 2897attributes. 2898 2899[[fig-non-strict-lines]] 2900image::{images}/non_strict_lines.svg[align="center",title="Non strict lines",opts="{imageopts}"] 2901 2902Only when pname:strictLines is ename:VK_FALSE implementations may: deviate 2903from the non-strict line algorithm described above in the following ways: 2904 2905 * Implementations may: instead interpolate each fragment according to the 2906 formula in <<primsrast-lines-basic, Basic Line Segment Rasterization>> 2907 using the original line segment endpoints. 2908 2909 * Rasterization of non-antialiased non-strict line segments may: be 2910 performed using the rules defined in 2911 <<primsrast-lines-bresenham,Bresenham Line Segment Rasterization>>. 2912 2913 2914[[primsrast-lines-bresenham]] 2915=== Bresenham Line Segment Rasterization 2916 2917ifdef::VK_EXT_line_rasterization[] 2918If pname:lineRasterizationMode is 2919ename:VK_LINE_RASTERIZATION_MODE_BRESENHAM_EXT, then the following rules 2920replace the line rasterization rules defined in <<primsrast-lines-basic, 2921Basic Line Segment Rasterization>>. 2922endif::VK_EXT_line_rasterization[] 2923 2924Non-strict lines may: also follow these rasterization rules for 2925non-antialiased lines. 2926 2927Line segment rasterization begins by characterizing the segment as either 2928_x-major_ or _y-major_. 2929x-major line segments have slope in the closed interval [eq]#[-1,1]#; all 2930other line segments are y-major (slope is determined by the segment's 2931endpoints). 2932We specify rasterization only for x-major segments except in cases where the 2933modifications for y-major segments are not self-evident. 2934 2935Ideally, Vulkan uses a _diamond-exit_ rule to determine those fragments that 2936are produced by rasterizing a line segment. 2937For each fragment [eq]#f# with center at framebuffer coordinates [eq]#x~f~# 2938and [eq]#y~f~#, define a diamond-shaped region that is the intersection of 2939four half planes: 2940 2941[latexmath] 2942+++++++++++++++++++ 2943 R_f = \{ (x,y) \mid | x - x_f | + | y - y_f | < \frac{1}{2} \} 2944+++++++++++++++++++ 2945 2946Essentially, a line segment starting at [eq]#p~a~# and ending at [eq]#p~b~# 2947produces those fragments [eq]#f# for which the segment intersects 2948[eq]#R~f~#, except if [eq]#p~b~# is contained in [eq]#R~f~#. 2949 2950image::{images}/bresenham.svg[title="Visualization of Bresenham's algorithm",align="center",opts="{imageopts}"] 2951 2952To avoid difficulties when an endpoint lies on a boundary of [eq]#R~f~# we 2953(in principle) perturb the supplied endpoints by a tiny amount. 2954Let [eq]#p~a~# and [eq]#p~b~# have framebuffer coordinates [eq]#(x~a~, 2955y~a~)# and [eq]#(x~b~, y~b~)#, respectively. 2956Obtain the perturbed endpoints [eq]#p~a~'# given by [eq]#(x~a~, y~a~) - 2957({epsilon}, {epsilon}^2^)# and [eq]#p~b~'# given by [eq]#(x~b~, y~b~) - 2958({epsilon}, {epsilon}^2^)#. 2959Rasterizing the line segment starting at [eq]#p~a~# and ending at [eq]#p~b~# 2960produces those fragments [eq]#f# for which the segment starting at 2961[eq]#p~a~'# and ending on [eq]#p~b~'# intersects [eq]#R~f~#, except if 2962[eq]#p~b~'# is contained in [eq]#R~f~#. 2963[eq]#{epsilon}# is chosen to be so small that rasterizing the line segment 2964produces the same fragments when [eq]#{delta}# is substituted for 2965[eq]#{epsilon}# for any [eq]#0 < {delta} {leq} {epsilon}#. 2966 2967When [eq]#p~a~# and [eq]#p~b~# lie on fragment centers, this 2968characterization of fragments reduces to Bresenham's algorithm with one 2969modification: lines produced in this description are "`half-open`", meaning 2970that the final fragment (corresponding to [eq]#p~b~#) is not drawn. 2971This means that when rasterizing a series of connected line segments, shared 2972endpoints will be produced only once rather than twice (as would occur with 2973Bresenham's algorithm). 2974 2975Implementations may: use other line segment rasterization algorithms, 2976subject to the following rules: 2977 2978 * The coordinates of a fragment produced by the algorithm must: not 2979 deviate by more than one unit in either x or y framebuffer coordinates 2980 from a corresponding fragment produced by the diamond-exit rule. 2981 * The total number of fragments produced by the algorithm must: not differ 2982 from that produced by the diamond-exit rule by no more than one. 2983 * For an x-major line, two fragments that lie in the same 2984 framebuffer-coordinate column must: not be produced (for a y-major line, 2985 two fragments that lie in the same framebuffer-coordinate row must: not 2986 be produced). 2987 * If two line segments share a common endpoint, and both segments are 2988 either x-major (both left-to-right or both right-to-left) or y-major 2989 (both bottom-to-top or both top-to-bottom), then rasterizing both 2990 segments must: not produce duplicate fragments. 2991 Fragments also must: not be omitted so as to interrupt continuity of the 2992 connected segments. 2993 2994The actual width [eq]#w# of Bresenham lines is determined by rounding the 2995line width to the nearest integer, clamping it to the 2996implementation-dependent pname:lineWidthRange (with both values rounded to 2997the nearest integer), then clamping it to be no less than 1. 2998 2999Bresenham line segments of width other than one are rasterized by offsetting 3000them in the minor direction (for an x-major line, the minor direction is y, 3001and for a y-major line, the minor direction is x) and producing a row or 3002column of fragments in the minor direction. 3003If the line segment has endpoints given by [eq]#(x~0~, y~0~)# and 3004[eq]#(x~1~, y~1~)# in framebuffer coordinates, the segment with endpoints 3005latexmath:[(x_0, y_0 - \frac{w-1}{2})] and latexmath:[(x_1, y_1 - 3006\frac{w-1}{2})] is rasterized, but instead of a single fragment, a column of 3007fragments of height w (a row of fragments of length w for a y-major segment) 3008is produced at each x (y for y-major) location. 3009The lowest fragment of this column is the fragment that would be produced by 3010rasterizing the segment of width 1 with the modified coordinates. 3011 3012The preferred method of attribute interpolation for a wide line is to 3013generate the same attribute values for all fragments in the row or column 3014described above, as if the adjusted line was used for interpolation and 3015those values replicated to the other fragments, except for code:FragCoord 3016which is interpolated as usual. 3017Implementations may: instead interpolate each fragment according to the 3018formula in <<primsrast-lines-basic,Basic Line Segment Rasterization>>, using 3019the original line segment endpoints. 3020 3021When Bresenham lines are being rasterized, sample locations may: all be 3022treated as being at the pixel center (this may: affect attribute and depth 3023interpolation). 3024 3025[NOTE] 3026.Note 3027==== 3028The sample locations described above are *not* used for determining 3029coverage, they are only used for things like attribute interpolation. 3030The rasterization rules that determine coverage are defined in terms of 3031whether the line intersects *pixels*, as opposed to the point sampling rules 3032used for other primitive types. 3033So these rules are independent of the sample locations. 3034One consequence of this is that Bresenham lines cover the same pixels 3035regardless of the number of rasterization samples, and cover all samples in 3036those pixels (unless masked out or killed). 3037==== 3038 3039 3040ifdef::VK_EXT_line_rasterization[] 3041[[primsrast-lines-stipple]] 3042=== Line Stipple 3043 3044If the pname:stippledLineEnable member of 3045slink:VkPipelineRasterizationLineStateCreateInfoEXT is ename:VK_TRUE, then 3046lines are rasterized with a _line stipple_ determined by 3047pname:lineStippleFactor and pname:lineStipplePattern. 3048pname:lineStipplePattern is an unsigned 16-bit integer that determines which 3049fragments are to be drawn or discarded when the line is rasterized. 3050pname:lineStippleFactor is a count that is used to modify the effective line 3051stipple by causing each bit in pname:lineStipplePattern to be used 3052pname:lineStippleFactor times. 3053 3054Line stippling discards certain fragments that are produced by 3055rasterization. 3056The masking is achieved using three parameters: the 16-bit line stipple 3057pattern _p_, the line stipple factor _r_, and an integer stipple counter 3058_s_. 3059Let 3060 3061[latexmath] 3062+++++++++++++++++++ 3063b = \left\lfloor \frac{s}{r} \right\rfloor \bmod 16 3064+++++++++++++++++++ 3065 3066Then a fragment is produced if the _b_'th bit of _p_ is 1, and discarded 3067otherwise. 3068The bits of _p_ are numbered with 0 being the least significant and 15 being 3069the most significant. 3070 3071The initial value of _s_ is zero. 3072For ename:VK_LINE_RASTERIZATION_MODE_BRESENHAM_EXT lines, _s_ is incremented 3073after production of each fragment of a line segment (fragments are produced 3074in order, beginning at the starting point and working towards the ending 3075point). 3076For ename:VK_LINE_RASTERIZATION_MODE_RECTANGULAR_EXT and 3077ename:VK_LINE_RASTERIZATION_MODE_RECTANGULAR_SMOOTH_EXT lines, the 3078rectangular region is subdivided into adjacent unit-length rectangles, and s 3079is incremented once for each rectangle. 3080Rectangles with a value of _s_ such that the _b_'th bit of _p_ is zero are 3081discarded. 3082If the last rectangle in a line segment is shorter than unit-length, then 3083the remainder may: carry over to the next line segment in the line strip 3084using the same value of _s_ (this is the preferred behavior, for the stipple 3085pattern to appear more consistent through the strip). 3086 3087_s_ is reset to 0 at the start of each strip (for line strips), and before 3088every line segment in a group of independent segments. 3089 3090If the line segment has been clipped, then the value of _s_ at the beginning 3091of the line segment is implementation-dependent. 3092 3093[open,refpage='vkCmdSetLineStippleEXT',desc='Set line stipple dynamically for a command buffer',type='protos'] 3094-- 3095To <<pipelines-dynamic-state, dynamically set>> the line stipple state, 3096call: 3097 3098include::{generated}/api/protos/vkCmdSetLineStippleEXT.adoc[] 3099 3100 * pname:commandBuffer is the command buffer into which the command will be 3101 recorded. 3102 * pname:lineStippleFactor is the repeat factor used in stippled line 3103 rasterization. 3104 * pname:lineStipplePattern is the bit pattern used in stippled line 3105 rasterization. 3106 3107This command sets the line stipple state for subsequent drawing commands 3108when the graphics pipeline is created with 3109ename:VK_DYNAMIC_STATE_LINE_STIPPLE_EXT set in 3110slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. 3111Otherwise, this state is specified by the 3112slink:VkPipelineRasterizationLineStateCreateInfoEXT::pname:lineStippleFactor 3113and 3114slink:VkPipelineRasterizationLineStateCreateInfoEXT::pname:lineStipplePattern 3115values used to create the currently active pipeline. 3116 3117.Valid Usage 3118**** 3119 * [[VUID-vkCmdSetLineStippleEXT-lineStippleFactor-02776]] 3120 pname:lineStippleFactor must: be in the range [eq]#[1,256]# 3121**** 3122 3123include::{generated}/validity/protos/vkCmdSetLineStippleEXT.adoc[] 3124-- 3125 3126 3127[[primsrast-lines-smooth]] 3128=== Smooth Lines 3129 3130If the pname:lineRasterizationMode member of 3131slink:VkPipelineRasterizationLineStateCreateInfoEXT is 3132ename:VK_LINE_RASTERIZATION_MODE_RECTANGULAR_SMOOTH_EXT, then lines are 3133considered to be rectangles using the same geometry as for 3134ename:VK_LINE_RASTERIZATION_MODE_RECTANGULAR_EXT lines. 3135The rules for determining which pixels are covered are 3136implementation-dependent, and may: include nearby pixels where no sample 3137locations are covered or where the rectangle does not intersect the pixel at 3138all. 3139For each pixel that is considered covered, the fragment computes a coverage 3140value that approximates the area of the intersection of the rectangle with 3141the pixel square, and this coverage value is multiplied into the color 3142location 0's alpha value after fragment shading, as described in 3143<<fragops-covg,Multisample Coverage>>. 3144 3145[NOTE] 3146.Note 3147==== 3148The details of the rasterization rules and area calculation are left 3149intentionally vague, to allow implementations to generate coverage and 3150values that are aesthetically pleasing. 3151==== 3152endif::VK_EXT_line_rasterization[] 3153 3154 3155[[primsrast-polygons]] 3156== Polygons 3157 3158A polygon results from the decomposition of a triangle strip, triangle fan 3159or a series of independent triangles. 3160Like points and line segments, polygon rasterization is controlled by 3161several variables in the slink:VkPipelineRasterizationStateCreateInfo 3162structure. 3163 3164 3165[[primsrast-polygons-basic]] 3166=== Basic Polygon Rasterization 3167 3168[open,refpage='VkFrontFace',desc='Interpret polygon front-facing orientation',type='enums'] 3169-- 3170The first step of polygon rasterization is to determine whether the triangle 3171is _back-facing_ or _front-facing_. 3172This determination is made based on the sign of the (clipped or unclipped) 3173polygon's area computed in framebuffer coordinates. 3174One way to compute this area is: 3175 3176[latexmath] 3177++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 3178a = -{1 \over 2}\sum_{i=0}^{n-1} 3179 x_f^i y_f^{i \oplus 1} - 3180 x_f^{i \oplus 1} y_f^i 3181++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 3182 3183where latexmath:[x_f^i] and latexmath:[y_f^i] are the [eq]#x# and [eq]#y# 3184framebuffer coordinates of the [eq]##i##th vertex of the [eq]#n#-vertex 3185polygon (vertices are numbered starting at zero for the purposes of this 3186computation) and [eq]#i {oplus} 1# is [eq]#(i {plus} 1) mod n#. 3187 3188The interpretation of the sign of [eq]#a# is determined by the 3189slink:VkPipelineRasterizationStateCreateInfo::pname:frontFace property of 3190the currently active pipeline. 3191Possible values are: 3192 3193include::{generated}/api/enums/VkFrontFace.adoc[] 3194 3195 * ename:VK_FRONT_FACE_COUNTER_CLOCKWISE specifies that a triangle with 3196 positive area is considered front-facing. 3197 * ename:VK_FRONT_FACE_CLOCKWISE specifies that a triangle with negative 3198 area is considered front-facing. 3199 3200Any triangle which is not front-facing is back-facing, including zero-area 3201triangles. 3202-- 3203 3204ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[] 3205[open,refpage='vkCmdSetFrontFace',desc='Set front face orientation dynamically for a command buffer',type='protos',alias='vkCmdSetFrontFaceEXT'] 3206-- 3207To <<pipelines-dynamic-state, dynamically set>> the front face orientation, 3208call: 3209 3210ifdef::VK_VERSION_1_3[] 3211include::{generated}/api/protos/vkCmdSetFrontFace.adoc[] 3212endif::VK_VERSION_1_3[] 3213 3214ifdef::VK_VERSION_1_3+VK_EXT_extended_dynamic_state[or the equivalent command] 3215 3216ifdef::VK_EXT_extended_dynamic_state[] 3217include::{generated}/api/protos/vkCmdSetFrontFaceEXT.adoc[] 3218endif::VK_EXT_extended_dynamic_state[] 3219 3220 * pname:commandBuffer is the command buffer into which the command will be 3221 recorded. 3222 * pname:frontFace is a elink:VkFrontFace value specifying the front-facing 3223 triangle orientation to be used for culling. 3224 3225This command sets the front face orientation for subsequent drawing commands 3226when the graphics pipeline is created with ename:VK_DYNAMIC_STATE_FRONT_FACE 3227set in slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. 3228Otherwise, this state is specified by the 3229slink:VkPipelineRasterizationStateCreateInfo::pname:frontFace value used to 3230create the currently active pipeline. 3231 3232ifndef::VK_VERSION_1_3[] 3233.Valid Usage 3234**** 3235 * [[VUID-vkCmdSetFrontFace-None-03383]] 3236 The <<features-extendedDynamicState, pname:extendedDynamicState>> 3237 feature must: be enabled 3238**** 3239endif::VK_VERSION_1_3[] 3240 3241include::{generated}/validity/protos/vkCmdSetFrontFace.adoc[] 3242-- 3243endif::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[] 3244 3245 3246[open,refpage='VkCullModeFlagBits',desc='Bitmask controlling triangle culling',type='enums'] 3247-- 3248Once the orientation of triangles is determined, they are culled according 3249to the slink:VkPipelineRasterizationStateCreateInfo::pname:cullMode property 3250of the currently active pipeline. 3251Possible values are: 3252 3253include::{generated}/api/enums/VkCullModeFlagBits.adoc[] 3254 3255 * ename:VK_CULL_MODE_NONE specifies that no triangles are discarded 3256 * ename:VK_CULL_MODE_FRONT_BIT specifies that front-facing triangles are 3257 discarded 3258 * ename:VK_CULL_MODE_BACK_BIT specifies that back-facing triangles are 3259 discarded 3260 * ename:VK_CULL_MODE_FRONT_AND_BACK specifies that all triangles are 3261 discarded. 3262 3263Following culling, fragments are produced for any triangles which have not 3264been discarded. 3265-- 3266 3267[open,refpage='VkCullModeFlags',desc='Bitmask of VkCullModeFlagBits',type='flags'] 3268-- 3269include::{generated}/api/flags/VkCullModeFlags.adoc[] 3270 3271tname:VkCullModeFlags is a bitmask type for setting a mask of zero or more 3272elink:VkCullModeFlagBits. 3273-- 3274 3275ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[] 3276[open,refpage='vkCmdSetCullMode',desc='Set cull mode dynamically for a command buffer',type='protos',alias='vkCmdSetCullModeEXT'] 3277-- 3278To <<pipelines-dynamic-state, dynamically set>> the cull mode, call: 3279 3280ifdef::VK_VERSION_1_3[] 3281include::{generated}/api/protos/vkCmdSetCullMode.adoc[] 3282endif::VK_VERSION_1_3[] 3283 3284ifdef::VK_VERSION_1_3+VK_EXT_extended_dynamic_state[or the equivalent command] 3285 3286ifdef::VK_EXT_extended_dynamic_state[] 3287include::{generated}/api/protos/vkCmdSetCullModeEXT.adoc[] 3288endif::VK_EXT_extended_dynamic_state[] 3289 3290 * pname:commandBuffer is the command buffer into which the command will be 3291 recorded. 3292 * pname:cullMode specifies the cull mode property to use for drawing. 3293 3294This command sets the cull mode for subsequent drawing commands when the 3295graphics pipeline is created with ename:VK_DYNAMIC_STATE_CULL_MODE set in 3296slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. 3297Otherwise, this state is specified by the 3298slink:VkPipelineRasterizationStateCreateInfo::pname:cullMode value used to 3299create the currently active pipeline. 3300 3301ifndef::VK_VERSION_1_3[] 3302.Valid Usage 3303**** 3304 * [[VUID-vkCmdSetCullMode-None-03384]] 3305 The <<features-extendedDynamicState, pname:extendedDynamicState>> 3306 feature must: be enabled 3307**** 3308endif::VK_VERSION_1_3[] 3309 3310include::{generated}/validity/protos/vkCmdSetCullMode.adoc[] 3311-- 3312endif::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[] 3313 3314The rule for determining which fragments are produced by polygon 3315rasterization is called _point sampling_. 3316The two-dimensional projection obtained by taking the x and y framebuffer 3317coordinates of the polygon's vertices is formed. 3318Fragments are produced for any fragment area groups of pixels for which any 3319sample points lie inside of this polygon. 3320Coverage bits that correspond to sample points that satisfy the point 3321sampling criteria are 1, other coverage bits are 0. 3322Special treatment is given to a sample whose sample location lies on a 3323polygon edge. 3324In such a case, if two polygons lie on either side of a common edge (with 3325identical endpoints) on which a sample point lies, then exactly one of the 3326polygons must: result in a covered sample for that fragment during 3327rasterization. 3328As for the data associated with each fragment produced by rasterizing a 3329polygon, we begin by specifying how these values are produced for fragments 3330in a triangle. 3331 3332[[primsrast-polygon-barycentrics]] 3333_Barycentric coordinates_ are a set of three numbers, [eq]#a#, [eq]#b#, and 3334[eq]#c#, each in the range [eq]#[0,1]#, with [eq]#a {plus} b {plus} c = 1#. 3335These coordinates uniquely specify any point [eq]#p# within the triangle or 3336on the triangle's boundary as 3337 3338 {empty}:: [eq]#p = a p~a~ {plus} b p~b~ {plus} c p~c~# 3339 3340where [eq]#p~a~#, [eq]#p~b~#, and [eq]#p~c~# are the vertices of the 3341triangle. 3342[eq]#a#, [eq]#b#, and [eq]#c# are determined by: 3343 3344[latexmath] 3345++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 3346a = {{\mathrm{A}(p p_b p_c)} \over {\mathrm{A}(p_a p_b p_c)}}, \quad 3347b = {{\mathrm{A}(p p_a p_c)} \over {\mathrm{A}(p_a p_b p_c)}}, \quad 3348c = {{\mathrm{A}(p p_a p_b)} \over {\mathrm{A}(p_a p_b p_c)}}, 3349++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 3350 3351where [eq]#A(lmn)# denotes the area in framebuffer coordinates of the 3352triangle with vertices [eq]#l#, [eq]#m#, and [eq]#n#. 3353 3354Denote an associated datum at [eq]#p~a~#, [eq]#p~b~#, or [eq]#p~c~# as 3355[eq]#f~a~#, [eq]#f~b~#, or [eq]#f~c~#, respectively. 3356 3357[[triangle_perspective_interpolation]] 3358_Perspective interpolation_ for a triangle interpolates three values in a 3359manner that is correct when taking the perspective of the viewport into 3360consideration, by way of the triangle's clip coordinates. 3361An interpolated value [eq]#f# can be determined by 3362 3363[latexmath] 3364++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 3365f = {{ a {f_a / w_a} + b {f_b / w_b} + c {f_c / w_c} } \over 3366 { {a / w_a} + {b / w_b} + {c / w_c} }} 3367++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 3368 3369where [eq]#w~a~#, [eq]#w~b~#, and [eq]#w~c~# are the clip [eq]#w# 3370coordinates of [eq]#p~a~#, [eq]#p~b~#, and [eq]#p~c~#, respectively. 3371[eq]#a#, [eq]#b#, and [eq]#c# are the barycentric coordinates of the 3372location at which the data are produced. 3373 3374[[triangle_linear_interpolation]] 3375_Linear interpolation_ for a triangle directly interpolates three values, 3376and an interpolated value [eq]#f# can be determined by 3377 3378 {empty}:: [eq]#f = a f~a~ {plus} b f~b~ {plus} c f~c~# 3379 3380where [eq]#f~a~#, [eq]#f~b~#, and [eq]#f~c~# are the data associated with 3381[eq]#p~a~#, [eq]#p~b~#, and [eq]#p~c~#, respectively. 3382 3383The clip coordinate [eq]#w# for a sample is determined using perspective 3384interpolation. 3385The depth value [eq]#z# for a sample is determined using linear 3386interpolation. 3387Interpolation of fragment shader input values are determined by 3388<<shaders-interpolation-decorations,Interpolation decorations>>. 3389 3390For a polygon with more than three edges, such as are produced by clipping a 3391triangle, a convex combination of the values of the datum at the polygon's 3392vertices must: be used to obtain the value assigned to each fragment 3393produced by the rasterization algorithm. 3394That is, it must: be the case that at every fragment 3395 3396[latexmath] 3397++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 3398f = \sum_{i=1}^{n} a_i f_i 3399++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 3400 3401where [eq]#n# is the number of vertices in the polygon and [eq]#f~i~# is the 3402value of [eq]#f# at vertex [eq]#i#. 3403For each [eq]#i#, [eq]#0 {leq} a~i~ {leq} 1# and 3404latexmath:[\sum_{i=1}^{n}a_i = 1]. 3405The values of [eq]#a~i~# may: differ from fragment to fragment, but at 3406vertex [eq]#i#, [eq]#a~i~ = 1# and [eq]#a~j~ = 0# for [eq]#j {neq} i#. 3407 3408[NOTE] 3409.Note 3410==== 3411One algorithm that achieves the required behavior is to triangulate a 3412polygon (without adding any vertices) and then treat each triangle 3413individually as already discussed. 3414A scan-line rasterizer that linearly interpolates data along each edge and 3415then linearly interpolates data across each horizontal span from edge to 3416edge also satisfies the restrictions (in this case the numerator and 3417denominator of <<triangle_perspective_interpolation, perspective 3418interpolation>> are iterated independently, and a division is performed for 3419each fragment). 3420==== 3421 3422 3423[[primsrast-polygonmode]] 3424=== Polygon Mode 3425 3426[open,refpage='VkPolygonMode',desc='Control polygon rasterization mode',type='enums'] 3427-- 3428Possible values of the 3429slink:VkPipelineRasterizationStateCreateInfo::pname:polygonMode property of 3430the currently active pipeline, specifying the method of rasterization for 3431polygons, are: 3432 3433include::{generated}/api/enums/VkPolygonMode.adoc[] 3434 3435 * ename:VK_POLYGON_MODE_POINT specifies that polygon vertices are drawn as 3436 points. 3437 * ename:VK_POLYGON_MODE_LINE specifies that polygon edges are drawn as 3438 line segments. 3439 * ename:VK_POLYGON_MODE_FILL specifies that polygons are rendered using 3440 the polygon rasterization rules in this section. 3441ifdef::VK_NV_fill_rectangle[] 3442 * ename:VK_POLYGON_MODE_FILL_RECTANGLE_NV specifies that polygons are 3443 rendered using polygon rasterization rules, modified to consider a 3444 sample within the primitive if the sample location is inside the 3445 axis-aligned bounding box of the triangle after projection. 3446 Note that the barycentric weights used in attribute interpolation can: 3447 extend outside the range [eq]#[0,1]# when these primitives are shaded. 3448 Special treatment is given to a sample position on the boundary edge of 3449 the bounding box. 3450 In such a case, if two rectangles lie on either side of a common edge 3451 (with identical endpoints) on which a sample position lies, then exactly 3452 one of the triangles must: produce a fragment that covers that sample 3453 during rasterization. 3454+ 3455Polygons rendered in ename:VK_POLYGON_MODE_FILL_RECTANGLE_NV mode may: be 3456clipped by the frustum or by user clip planes. 3457If clipping is applied, the triangle is culled rather than clipped. 3458+ 3459Area calculation and facingness are determined for 3460ename:VK_POLYGON_MODE_FILL_RECTANGLE_NV mode using the triangle's vertices. 3461endif::VK_NV_fill_rectangle[] 3462 3463These modes affect only the final rasterization of polygons: in particular, 3464a polygon's vertices are shaded and the polygon is clipped and possibly 3465culled before these modes are applied. 3466-- 3467 3468ifdef::VK_EXT_extended_dynamic_state3[] 3469 3470[open,refpage='vkCmdSetPolygonModeEXT',desc='Specify polygon mode dynamically for a command buffer',type='protos'] 3471-- 3472To <<pipelines-dynamic-state, dynamically set>> the polygon mode, call: 3473 3474include::{generated}/api/protos/vkCmdSetPolygonModeEXT.adoc[] 3475 3476 * pname:commandBuffer is the command buffer into which the command will be 3477 recorded. 3478 * pname:polygonMode specifies polygon mode. 3479 3480This command sets the polygon mode for subsequent drawing commands when the 3481graphics pipeline is created with ename:VK_DYNAMIC_STATE_POLYGON_MODE_EXT 3482set in slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. 3483Otherwise, this state is specified by the 3484slink:VkPipelineRasterizationStateCreateInfo::pname:polygonMode value used 3485to create the currently active pipeline. 3486 3487.Valid Usage 3488**** 3489 * [[VUID-vkCmdSetPolygonModeEXT-extendedDynamicState3PolygonMode-07422]] 3490 The <<features-extendedDynamicState3PolygonMode, 3491 pname:extendedDynamicState3PolygonMode>> feature must: be enabled 3492ifndef::VK_NV_fill_rectangle[] 3493 * [[VUID-vkCmdSetPolygonModeEXT-fillModeNonSolid-07423]] 3494 If the <<features-fillModeNonSolid, pname:fillModeNonSolid>> feature is 3495 not enabled, pname:polygonMode must: be ename:VK_POLYGON_MODE_FILL 3496endif::VK_NV_fill_rectangle[] 3497ifdef::VK_NV_fill_rectangle[] 3498 * [[VUID-vkCmdSetPolygonModeEXT-fillModeNonSolid-07424]] 3499 If the <<features-fillModeNonSolid, pname:fillModeNonSolid>> feature is 3500 not enabled, pname:polygonMode must: be ename:VK_POLYGON_MODE_FILL or 3501 ename:VK_POLYGON_MODE_FILL_RECTANGLE_NV 3502 * [[VUID-vkCmdSetPolygonModeEXT-polygonMode-07425]] 3503 If the `apiext:VK_NV_fill_rectangle` extension is not enabled, 3504 pname:polygonMode must: not be ename:VK_POLYGON_MODE_FILL_RECTANGLE_NV 3505endif::VK_NV_fill_rectangle[] 3506**** 3507 3508include::{generated}/validity/protos/vkCmdSetPolygonModeEXT.adoc[] 3509-- 3510 3511endif::VK_EXT_extended_dynamic_state3[] 3512 3513 3514[[primsrast-depthbias]] 3515=== Depth Bias 3516 3517The depth values of all fragments generated by the rasterization of a 3518polygon can: be biased (offset) by a single depth bias value latexmath:[o] 3519that is computed for that polygon. 3520 3521 3522[[primsrast-depthbias-enable]] 3523==== Depth Bias Enable 3524 3525The depth bias computation is enabled by the 3526ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state2[] 3527pname:depthBiasEnable set with flink:vkCmdSetDepthBiasEnable 3528ifdef::VK_EXT_extended_dynamic_state2[] 3529and fname:vkCmdSetDepthBiasEnableEXT, 3530endif::VK_EXT_extended_dynamic_state2[] 3531or the corresponding 3532endif::VK_VERSION_1_3,VK_EXT_extended_dynamic_state2[] 3533slink:VkPipelineRasterizationStateCreateInfo::pname:depthBiasEnable value 3534used to create the currently active pipeline. 3535If the depth bias enable is ename:VK_FALSE, no bias is applied and the 3536fragment's depth values are unchanged. 3537 3538ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state2[] 3539[open,refpage='vkCmdSetDepthBiasEnable',desc='Control whether to bias fragment depth values dynamically for a command buffer',type='protos',alias='vkCmdSetDepthBiasEnableEXT'] 3540-- 3541To <<pipelines-dynamic-state, dynamically enable>> whether to bias fragment 3542depth values, call: 3543 3544ifdef::VK_VERSION_1_3[] 3545include::{generated}/api/protos/vkCmdSetDepthBiasEnable.adoc[] 3546endif::VK_VERSION_1_3[] 3547 3548ifdef::VK_VERSION_1_3+VK_EXT_extended_dynamic_state2[or the equivalent command] 3549 3550ifdef::VK_EXT_extended_dynamic_state2[] 3551include::{generated}/api/protos/vkCmdSetDepthBiasEnableEXT.adoc[] 3552endif::VK_EXT_extended_dynamic_state2[] 3553 3554 * pname:commandBuffer is the command buffer into which the command will be 3555 recorded. 3556 * pname:depthBiasEnable controls whether to bias fragment depth values. 3557 3558This command sets the depth bias enable for subsequent drawing commands when 3559the graphics pipeline is created with 3560ename:VK_DYNAMIC_STATE_DEPTH_BIAS_ENABLE set in 3561slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. 3562Otherwise, this state is specified by the 3563slink:VkPipelineRasterizationStateCreateInfo::pname:depthBiasEnable value 3564used to create the currently active pipeline. 3565 3566ifndef::VK_VERSION_1_3[] 3567.Valid Usage 3568**** 3569 * [[VUID-vkCmdSetDepthBiasEnable-None-04872]] 3570 The <<features-extendedDynamicState2, pname:extendedDynamicState2>> 3571 feature must: be enabled 3572**** 3573endif::VK_VERSION_1_3[] 3574 3575include::{generated}/validity/protos/vkCmdSetDepthBiasEnable.adoc[] 3576-- 3577endif::VK_VERSION_1_3,VK_EXT_extended_dynamic_state2[] 3578 3579 3580[[primsrast-depthbias-computation]] 3581==== Depth Bias Computation 3582 3583The depth bias depends on three parameters: 3584 3585 * pname:depthBiasSlopeFactor scales the maximum depth slope [eq]#m# of the 3586 polygon 3587 * pname:depthBiasConstantFactor scales the minimum resolvable difference 3588 [eq]#r# of the depth attachment 3589 * the scaled terms are summed to produce a value which is then clamped to 3590 a minimum or maximum value specified by pname:depthBiasClamp 3591 3592pname:depthBiasSlopeFactor, pname:depthBiasConstantFactor, and 3593pname:depthBiasClamp can: each be positive, negative, or zero. 3594These parameters are set as described for flink:vkCmdSetDepthBias below. 3595 3596The maximum depth slope [eq]#m# of a triangle is 3597 3598[latexmath] 3599++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 3600m = \sqrt{ \left({{\partial z_f} \over {\partial x_f}}\right)^2 3601 + \left({{\partial z_f} \over {\partial y_f}}\right)^2} 3602++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 3603 3604where [eq]#(x~f~, y~f~, z~f~)# is a point on the triangle. 3605[eq]#m# may: be approximated as 3606 3607[latexmath] 3608++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 3609m = \max\left( \left| { {\partial z_f} \over {\partial x_f} } \right|, 3610 \left| { {\partial z_f} \over {\partial y_f} } \right| 3611 \right). 3612++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 3613 3614The minimum resolvable difference [eq]#r# is a parameter that depends on the 3615depth attachment representation. 3616It is the smallest difference in framebuffer coordinate [eq]#z# values that 3617is guaranteed to remain distinct throughout polygon rasterization and in the 3618depth attachment. 3619All pairs of fragments generated by the rasterization of two polygons with 3620otherwise identical vertices, but [eq]#pname:z~f~# values that differ by 3621[eq]#r#, will have distinct depth values. 3622 3623For fixed-point depth attachment representations, [eq]#r# is constant 3624throughout the range of the entire depth attachment. 3625Its value is implementation-dependent but must: be at most 3626 3627 {empty}:: [eq]#r = 2 {times} 2^-n^# 3628 3629for an n-bit buffer. 3630For floating-point depth attachment, there is no single minimum resolvable 3631difference. 3632In this case, the minimum resolvable difference for a given polygon is 3633dependent on the maximum exponent, [eq]#e#, in the range of [eq]#z# values 3634spanned by the primitive. 3635If [eq]#n# is the number of bits in the floating-point mantissa, the minimum 3636resolvable difference, [eq]#r#, for the given primitive is defined as 3637 3638 {empty}:: [eq]#r = 2^e-n^# 3639 3640ifdef::VK_NV_fill_rectangle[] 3641If a triangle is rasterized using the 3642ename:VK_POLYGON_MODE_FILL_RECTANGLE_NV polygon mode, then this minimum 3643resolvable difference may: not be resolvable for samples outside of the 3644triangle, where the depth is extrapolated. 3645endif::VK_NV_fill_rectangle[] 3646 3647If no depth attachment is present, [eq]#r# is undefined:. 3648 3649The bias value [eq]#o# for a polygon is 3650 3651[latexmath] 3652++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 3653\begin{aligned} 3654o &= \mathrm{dbclamp}( m \times \mathtt{depthBiasSlopeFactor} + r \times \mathtt{depthBiasConstantFactor} ) \\ 3655\text{where} &\quad \mathrm{dbclamp}(x) = 3656\begin{cases} 3657 x & \mathtt{depthBiasClamp} = 0 \ \text{or}\ \texttt{NaN} \\ 3658 \min(x, \mathtt{depthBiasClamp}) & \mathtt{depthBiasClamp} > 0 \\ 3659 \max(x, \mathtt{depthBiasClamp}) & \mathtt{depthBiasClamp} < 0 \\ 3660\end{cases} 3661\end{aligned} 3662++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 3663 3664[eq]#m# is computed as described above. 3665If the depth attachment uses a fixed-point representation, [eq]#m# is a 3666function of depth values in the range [eq]#[0,1]#, and [eq]#o# is applied to 3667depth values in the same range. 3668 3669Depth bias is applied to triangle topology primitives received by the 3670rasterizer regardless of <<primsrast-polygonmode, polygon mode>>. 3671Depth bias may: also be applied to line and point topology primitives 3672received by the rasterizer. 3673 3674[open,refpage='vkCmdSetDepthBias',desc='Set depth bias factors and clamp dynamically for a command buffer',type='protos'] 3675-- 3676To <<pipelines-dynamic-state, dynamically set>> the depth bias parameters, 3677call: 3678 3679include::{generated}/api/protos/vkCmdSetDepthBias.adoc[] 3680 3681 * pname:commandBuffer is the command buffer into which the command will be 3682 recorded. 3683 * pname:depthBiasConstantFactor is a scalar factor controlling the 3684 constant depth value added to each fragment. 3685 * pname:depthBiasClamp is the maximum (or minimum) depth bias of a 3686 fragment. 3687 * pname:depthBiasSlopeFactor is a scalar factor applied to a fragment's 3688 slope in depth bias calculations. 3689 3690This command sets the depth bias parameters for subsequent drawing commands 3691when the graphics pipeline is created with ename:VK_DYNAMIC_STATE_DEPTH_BIAS 3692set in slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. 3693Otherwise, this state is specified by the corresponding 3694slink:VkPipelineRasterizationStateCreateInfo::pname:depthBiasConstantFactor, 3695pname:depthBiasClamp, and pname:depthBiasSlopeFactor values used to create 3696the currently active pipeline. 3697 3698.Valid Usage 3699**** 3700 * [[VUID-vkCmdSetDepthBias-depthBiasClamp-00790]] 3701 If the <<features-depthBiasClamp, pname:depthBiasClamp>> feature is not 3702 enabled, pname:depthBiasClamp must: be `0.0` 3703**** 3704 3705include::{generated}/validity/protos/vkCmdSetDepthBias.adoc[] 3706-- 3707 3708 3709ifdef::VK_EXT_conservative_rasterization[] 3710[[primsrast-conservativeraster]] 3711=== Conservative Rasterization 3712 3713[open,refpage='VkPipelineRasterizationConservativeStateCreateInfoEXT',desc='Structure specifying conservative raster state',type='structs'] 3714-- 3715If the pname:pNext chain of slink:VkPipelineRasterizationStateCreateInfo 3716includes a sname:VkPipelineRasterizationConservativeStateCreateInfoEXT 3717structure, then that structure includes parameters controlling conservative 3718rasterization. 3719 3720sname:VkPipelineRasterizationConservativeStateCreateInfoEXT is defined as: 3721 3722include::{generated}/api/structs/VkPipelineRasterizationConservativeStateCreateInfoEXT.adoc[] 3723 3724 * pname:sType is the type of this structure. 3725 * pname:pNext is `NULL` or a pointer to a structure extending this 3726 structure. 3727 * pname:flags is reserved for future use. 3728 * pname:conservativeRasterizationMode is the conservative rasterization 3729 mode to use. 3730 * pname:extraPrimitiveOverestimationSize is the extra size in pixels to 3731 increase the generating primitive during conservative rasterization at 3732 each of its edges in `X` and `Y` equally in screen space beyond the base 3733 overestimation specified in 3734 sname:VkPhysicalDeviceConservativeRasterizationPropertiesEXT::pname:primitiveOverestimationSize. 3735 If pname:conservativeRasterizationMode is not 3736 ename:VK_CONSERVATIVE_RASTERIZATION_MODE_OVERESTIMATE_EXT, this value is 3737 ignored. 3738 3739If this structure is not included in the pname:pNext chain, 3740pname:conservativeRasterizationMode is considered to be 3741ename:VK_CONSERVATIVE_RASTERIZATION_MODE_DISABLED_EXT, and and conservative 3742rasterization is disabled. 3743 3744Polygon rasterization can: be made conservative by setting 3745pname:conservativeRasterizationMode to 3746ename:VK_CONSERVATIVE_RASTERIZATION_MODE_OVERESTIMATE_EXT or 3747ename:VK_CONSERVATIVE_RASTERIZATION_MODE_UNDERESTIMATE_EXT in 3748sname:VkPipelineRasterizationConservativeStateCreateInfoEXT. 3749 3750[NOTE] 3751.Note 3752==== 3753If <<limits-conservativePointAndLineRasterization, 3754pname:conservativePointAndLineRasterization>> is supported, conservative 3755rasterization can be applied to line and point primitives, otherwise it must 3756be disabled. 3757==== 3758 3759.Valid Usage 3760**** 3761 * [[VUID-VkPipelineRasterizationConservativeStateCreateInfoEXT-extraPrimitiveOverestimationSize-01769]] 3762 pname:extraPrimitiveOverestimationSize must: be in the range of `0.0` to 3763 sname:VkPhysicalDeviceConservativeRasterizationPropertiesEXT::pname:maxExtraPrimitiveOverestimationSize 3764 inclusive 3765**** 3766 3767include::{generated}/validity/structs/VkPipelineRasterizationConservativeStateCreateInfoEXT.adoc[] 3768-- 3769 3770[open,refpage='VkPipelineRasterizationConservativeStateCreateFlagsEXT',desc='Reserved for future use',type='flags'] 3771-- 3772include::{generated}/api/flags/VkPipelineRasterizationConservativeStateCreateFlagsEXT.adoc[] 3773 3774tname:VkPipelineRasterizationConservativeStateCreateFlagsEXT is a bitmask 3775type for setting a mask, but is currently reserved for future use. 3776-- 3777 3778[open,refpage='VkConservativeRasterizationModeEXT',desc='Specify the conservative rasterization mode',type='enums'] 3779-- 3780Possible values of 3781slink:VkPipelineRasterizationConservativeStateCreateInfoEXT::pname:conservativeRasterizationMode, 3782specifying the conservative rasterization mode are: 3783 3784include::{generated}/api/enums/VkConservativeRasterizationModeEXT.adoc[] 3785 3786 * ename:VK_CONSERVATIVE_RASTERIZATION_MODE_DISABLED_EXT specifies that 3787 conservative rasterization is disabled and rasterization proceeds as 3788 normal. 3789 * ename:VK_CONSERVATIVE_RASTERIZATION_MODE_OVERESTIMATE_EXT specifies that 3790 conservative rasterization is enabled in overestimation mode. 3791 * ename:VK_CONSERVATIVE_RASTERIZATION_MODE_UNDERESTIMATE_EXT specifies 3792 that conservative rasterization is enabled in underestimation mode. 3793-- 3794 3795ifdef::VK_EXT_extended_dynamic_state3[] 3796 3797[open,refpage='vkCmdSetConservativeRasterizationModeEXT',desc='Specify the conservative rasterization mode dynamically for a command buffer',type='protos'] 3798-- 3799To <<pipelines-dynamic-state, dynamically set>> the 3800pname:conservativeRasterizationMode, call: 3801 3802include::{generated}/api/protos/vkCmdSetConservativeRasterizationModeEXT.adoc[] 3803 3804 * pname:commandBuffer is the command buffer into which the command will be 3805 recorded. 3806 * pname:conservativeRasterizationMode specifies the 3807 pname:conservativeRasterizationMode state. 3808 3809This command sets the pname:conservativeRasterizationMode state for 3810subsequent drawing commands when the graphics pipeline is created with 3811ename:VK_DYNAMIC_STATE_CONSERVATIVE_RASTERIZATION_MODE_EXT set in 3812slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. 3813Otherwise, this state is specified by the 3814slink:VkPipelineRasterizationConservativeStateCreateInfoEXT::pname:conservativeRasterizationMode 3815value used to create the currently active pipeline. 3816 3817.Valid Usage 3818**** 3819 * [[VUID-vkCmdSetConservativeRasterizationModeEXT-extendedDynamicState3ConservativeRasterizationMode-07426]] 3820 The <<features-extendedDynamicState3ConservativeRasterizationMode, 3821 pname:extendedDynamicState3ConservativeRasterizationMode>> feature must: 3822 be enabled 3823**** 3824 3825include::{generated}/validity/protos/vkCmdSetConservativeRasterizationModeEXT.adoc[] 3826-- 3827 3828[open,refpage='vkCmdSetExtraPrimitiveOverestimationSizeEXT',desc='Specify the conservative rasterization extra primitive overestimation size dynamically for a command buffer',type='protos'] 3829-- 3830To <<pipelines-dynamic-state, dynamically set>> the 3831pname:extraPrimitiveOverestimationSize, call: 3832 3833include::{generated}/api/protos/vkCmdSetExtraPrimitiveOverestimationSizeEXT.adoc[] 3834 3835 * pname:commandBuffer is the command buffer into which the command will be 3836 recorded. 3837 * pname:extraPrimitiveOverestimationSize specifies the 3838 pname:extraPrimitiveOverestimationSize. 3839 3840This command sets the pname:extraPrimitiveOverestimationSize for subsequent 3841drawing commands when the graphics pipeline is created with 3842ename:VK_DYNAMIC_STATE_EXTRA_PRIMITIVE_OVERESTIMATION_SIZE_EXT set in 3843slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. 3844Otherwise, this state is specified by the 3845slink:VkPipelineRasterizationConservativeStateCreateInfoEXT::pname:extraPrimitiveOverestimationSize 3846value used to create the currently active pipeline. 3847 3848.Valid Usage 3849**** 3850 * [[VUID-vkCmdSetExtraPrimitiveOverestimationSizeEXT-extendedDynamicState3ExtraPrimitiveOverestimationSize-07427]] 3851 The <<features-extendedDynamicState3ExtraPrimitiveOverestimationSize, 3852 pname:extendedDynamicState3ExtraPrimitiveOverestimationSize>> feature 3853 must: be enabled 3854 * [[VUID-vkCmdSetExtraPrimitiveOverestimationSizeEXT-extraPrimitiveOverestimationSize-07428]] 3855 pname:extraPrimitiveOverestimationSize must: be in the range of `0.0` to 3856 sname:VkPhysicalDeviceConservativeRasterizationPropertiesEXT::pname:maxExtraPrimitiveOverestimationSize 3857 inclusive 3858**** 3859 3860include::{generated}/validity/protos/vkCmdSetExtraPrimitiveOverestimationSizeEXT.adoc[] 3861-- 3862 3863endif::VK_EXT_extended_dynamic_state3[] 3864 3865When overestimate conservative rasterization is enabled, rather than 3866evaluating coverage at individual sample locations, a determination is made 3867whether any portion of the pixel (including its edges and corners) is 3868covered by the primitive. 3869If any portion of the pixel is covered, then all bits of the 3870<<primsrast-multisampling-coverage-mask, coverage mask>> for the fragment 3871corresponding to that pixel are enabled. 3872ifdef::VK_EXT_fragment_density_map[] 3873If the render pass has a fragment density map attachment and any bit of the 3874<<primsrast-multisampling-coverage-mask, coverage mask>> for the fragment is 3875enabled, then all bits of the <<primsrast-multisampling-coverage-mask, 3876coverage mask>> for the fragment are enabled. 3877endif::VK_EXT_fragment_density_map[] 3878 3879For the purposes of evaluating which pixels are covered by the primitive, 3880implementations can: increase the size of the primitive by up to 3881sname:VkPhysicalDeviceConservativeRasterizationPropertiesEXT::pname:primitiveOverestimationSize 3882pixels at each of the primitive edges. 3883This may: increase the number of fragments generated by this primitive and 3884represents an overestimation of the pixel coverage. 3885 3886This overestimation size can be increased further by setting the 3887pname:extraPrimitiveOverestimationSize value above `0.0` in steps of 3888sname:VkPhysicalDeviceConservativeRasterizationPropertiesEXT::pname:extraPrimitiveOverestimationSizeGranularity 3889up to and including 3890sname:VkPhysicalDeviceConservativeRasterizationPropertiesEXT::pname:extraPrimitiveOverestimationSize. 3891This may: further increase the number of fragments generated by this 3892primitive. 3893 3894The actual precision of the overestimation size used for conservative 3895rasterization may: vary between implementations and produce results that 3896only approximate the pname:primitiveOverestimationSize and 3897pname:extraPrimitiveOverestimationSizeGranularity properties. 3898ifdef::VK_EXT_fragment_density_map[] 3899Implementations may: especially vary these approximations when the render 3900pass has a fragment density map and the fragment area covers multiple 3901pixels. 3902endif::VK_EXT_fragment_density_map[] 3903 3904For triangles if ename:VK_CONSERVATIVE_RASTERIZATION_MODE_OVERESTIMATE_EXT 3905is enabled, fragments will be generated if the primitive area covers any 3906portion of any pixel inside the fragment area, including their edges or 3907corners. 3908The tie-breaking rule described in <<primsrast-polygons-basic, Basic Polygon 3909Rasterization>> does not apply during conservative rasterization and 3910coverage is set for all fragments generated from shared edges of polygons. 3911Degenerate triangles that evaluate to zero area after rasterization, even 3912for pixels containing a vertex or edge of the zero-area polygon, will be 3913culled if 3914sname:VkPhysicalDeviceConservativeRasterizationPropertiesEXT::pname:degenerateTrianglesRasterized 3915is ename:VK_FALSE or will generate fragments if 3916pname:degenerateTrianglesRasterized is ename:VK_TRUE. 3917The fragment input values for these degenerate triangles take their 3918attribute and depth values from the provoking vertex. 3919Degenerate triangles are considered backfacing and the application can: 3920enable backface culling if desired. 3921Triangles that are zero area before rasterization may: be culled regardless. 3922 3923For lines if ename:VK_CONSERVATIVE_RASTERIZATION_MODE_OVERESTIMATE_EXT is 3924enabled, and the implementation sets 3925sname:VkPhysicalDeviceConservativeRasterizationPropertiesEXT::pname:conservativePointAndLineRasterization 3926to ename:VK_TRUE, fragments will be generated if the line covers any portion 3927of any pixel inside the fragment area, including their edges or corners. 3928Degenerate lines that evaluate to zero length after rasterization will be 3929culled if 3930sname:VkPhysicalDeviceConservativeRasterizationPropertiesEXT::pname:degenerateLinesRasterized 3931is ename:VK_FALSE or will generate fragments if 3932pname:degenerateLinesRasterized is ename:VK_TRUE. 3933The fragments input values for these degenerate lines take their attribute 3934and depth values from the provoking vertex. 3935Lines that are zero length before rasterization may: be culled regardless. 3936 3937For points if ename:VK_CONSERVATIVE_RASTERIZATION_MODE_OVERESTIMATE_EXT is 3938enabled, and the implementation sets 3939sname:VkPhysicalDeviceConservativeRasterizationPropertiesEXT::pname:conservativePointAndLineRasterization 3940to ename:VK_TRUE, fragments will be generated if the point square covers any 3941portion of any pixel inside the fragment area, including their edges or 3942corners. 3943 3944When underestimate conservative rasterization is enabled, rather than 3945evaluating coverage at individual sample locations, a determination is made 3946whether all of the pixel (including its edges and corners) is covered by the 3947primitive. 3948If the entire pixel is covered, then a fragment is generated with all bits 3949of its <<primsrast-multisampling-coverage-mask, coverage mask>> 3950corresponding to the pixel enabled, otherwise the pixel is not considered 3951covered even if some portion of the pixel is covered. 3952The fragment is discarded if no pixels inside the fragment area are 3953considered covered. 3954ifdef::VK_EXT_fragment_density_map[] 3955If the render pass has a fragment density map attachment and any pixel 3956inside the fragment area is not considered covered, then the fragment is 3957discarded even if some pixels are considered covered. 3958endif::VK_EXT_fragment_density_map[] 3959 3960For triangles, if ename:VK_CONSERVATIVE_RASTERIZATION_MODE_UNDERESTIMATE_EXT 3961is enabled, fragments will only be generated if any pixel inside the 3962fragment area is fully covered by the generating primitive, including its 3963edges and corners. 3964 3965For lines, if ename:VK_CONSERVATIVE_RASTERIZATION_MODE_UNDERESTIMATE_EXT is 3966enabled, fragments will be generated if any pixel inside the fragment area, 3967including its edges and corners, are entirely covered by the line. 3968 3969For points, if ename:VK_CONSERVATIVE_RASTERIZATION_MODE_UNDERESTIMATE_EXT is 3970enabled, fragments will only be generated if the point square covers the 3971entirety of any pixel square inside the fragment area, including its edges 3972or corners. 3973 3974ifdef::VK_EXT_fragment_density_map[] 3975If the render pass has a fragment density map and 3976ename:VK_CONSERVATIVE_RASTERIZATION_MODE_UNDERESTIMATE_EXT is enabled, 3977fragments will only be generated if the entirety of all pixels inside the 3978fragment area are covered by the generating primitive, line, or point. 3979endif::VK_EXT_fragment_density_map[] 3980 3981For both overestimate and underestimate conservative rasterization modes a 3982fragment has all of its pixel squares fully covered by the generating 3983primitive must: set code:FullyCoveredEXT to ename:VK_TRUE if the 3984implementation enables the 3985sname:VkPhysicalDeviceConservativeRasterizationPropertiesEXT::pname:fullyCoveredFragmentShaderInputVariable 3986feature. 3987 3988ifdef::VK_NV_shading_rate_image,VK_KHR_fragment_shading_rate[] 3989When 3990ifdef::VK_NV_shading_rate_image[] 3991the use of a <<primsrast-shading-rate-image, shading rate image>> 3992endif::VK_NV_shading_rate_image[] 3993ifdef::VK_NV_shading_rate_image+VK_KHR_fragment_shading_rate[or] 3994ifdef::VK_KHR_fragment_shading_rate[] 3995setting the <<primsrast-fragment-shading-rate, fragment shading rate>> 3996endif::VK_KHR_fragment_shading_rate[] 3997results in fragments covering multiple pixels, coverage for conservative 3998rasterization is still evaluated on a per-pixel basis and may result in 3999fragments with partial coverage. 4000For fragment shader inputs decorated with code:FullyCoveredEXT, a fragment 4001is considered fully covered if and only if all pixels in the fragment are 4002fully covered by the generating primitive. 4003endif::VK_NV_shading_rate_image,VK_KHR_fragment_shading_rate[] 4004 4005endif::VK_EXT_conservative_rasterization[] 4006
