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