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