1// Copyright (c) 2015-2018 Khronos Group. This work is licensed under a 2// Creative Commons Attribution 4.0 International License; see 3// http://creativecommons.org/licenses/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 point of this image contains associated data such as depth, color, or 11other 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 subpixel 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 the <<fragops-early,early 36per-fragment tests>>, if enabled. 37 38Several factors affect rasterization, including the members of 39sname:VkPipelineRasterizationStateCreateInfo and 40sname:VkPipelineMultisampleStateCreateInfo. 41 42[open,refpage='VkPipelineRasterizationStateCreateInfo',desc='Structure specifying parameters of a newly created pipeline rasterization state',type='structs'] 43-- 44 45The sname:VkPipelineRasterizationStateCreateInfo structure is defined as: 46 47include::../api/structs/VkPipelineRasterizationStateCreateInfo.txt[] 48 49 * pname:sType is the type of this structure. 50 * pname:pNext is `NULL` or a pointer to an extension-specific structure. 51 * pname:flags is reserved for future use. 52 * pname:depthClampEnable controls whether to clamp the fragment's depth 53 values instead of clipping primitives to the z planes of the frustum, as 54 described in <<vertexpostproc-clipping,Primitive Clipping>>. 55 * pname:rasterizerDiscardEnable controls whether primitives are discarded 56 immediately before the rasterization stage. 57 * pname:polygonMode is the triangle rendering mode. 58 See elink:VkPolygonMode. 59 * pname:cullMode is the triangle facing direction used for primitive 60 culling. 61 See elink:VkCullModeFlagBits. 62 * pname:frontFace is a elink:VkFrontFace value specifying the front-facing 63 triangle orientation to be used for culling. 64 * pname:depthBiasEnable controls whether to bias fragment depth values. 65 * pname:depthBiasConstantFactor is a scalar factor controlling the 66 constant depth value added to each fragment. 67 * pname:depthBiasClamp is the maximum (or minimum) depth bias of a 68 fragment. 69 * pname:depthBiasSlopeFactor is a scalar factor applied to a fragment's 70 slope in depth bias calculations. 71 * pname:lineWidth is the width of rasterized line segments. 72 73ifdef::VK_AMD_rasterization_order[] 74The application can: also add a 75sname:VkPipelineRasterizationStateRasterizationOrderAMD structure to the 76pname:pNext chain of a sname:VkPipelineRasterizationStateCreateInfo 77structure. 78This structure enables selecting the rasterization order to use when 79rendering with the corresponding graphics pipeline as described in 80<<primrast-order, Rasterization Order>>. 81endif::VK_AMD_rasterization_order[] 82 83.Valid Usage 84**** 85 * [[VUID-VkPipelineRasterizationStateCreateInfo-depthClampEnable-00782]] 86 If the <<features-features-depthClamp,depth clamping>> feature is not 87 enabled, pname:depthClampEnable must: be ename:VK_FALSE 88ifndef::VK_NV_fill_rectangle[] 89 * [[VUID-VkPipelineRasterizationStateCreateInfo-polygonMode-01413]] 90 If the <<features-features-fillModeNonSolid,non-solid fill modes>> 91 feature is not enabled, pname:polygonMode must: be 92 ename:VK_POLYGON_MODE_FILL 93endif::VK_NV_fill_rectangle[] 94ifdef::VK_NV_fill_rectangle[] 95 * [[VUID-VkPipelineRasterizationStateCreateInfo-polygonMode-01507]] 96 If the <<features-features-fillModeNonSolid,non-solid fill modes>> 97 feature is not enabled, pname:polygonMode must: be 98 ename:VK_POLYGON_MODE_FILL or ename:VK_POLYGON_MODE_FILL_RECTANGLE_NV 99 * [[VUID-VkPipelineRasterizationStateCreateInfo-polygonMode-01414]] 100 If the `<<VK_NV_fill_rectangle>>` extension is not enabled, 101 pname:polygonMode must: not be ename:VK_POLYGON_MODE_FILL_RECTANGLE_NV 102endif::VK_NV_fill_rectangle[] 103**** 104 105include::../validity/structs/VkPipelineRasterizationStateCreateInfo.txt[] 106-- 107 108[open,refpage='VkPipelineRasterizationStateCreateFlags',desc='Reserved for future use',type='enums'] 109-- 110include::../api/flags/VkPipelineRasterizationStateCreateFlags.txt[] 111 112sname:VkPipelineRasterizationStateCreateFlags is a bitmask type for setting 113a mask, but is currently reserved for future use. 114-- 115 116[open,refpage='VkPipelineMultisampleStateCreateInfo',desc='Structure specifying parameters of a newly created pipeline multisample state',type='structs'] 117-- 118 119The sname:VkPipelineMultisampleStateCreateInfo structure is defined as: 120 121include::../api/structs/VkPipelineMultisampleStateCreateInfo.txt[] 122 123 * pname:sType is the type of this structure. 124 * pname:pNext is `NULL` or a pointer to an extension-specific structure. 125 * pname:flags is reserved for future use. 126 * pname:rasterizationSamples is a elink:VkSampleCountFlagBits specifying 127 the number of samples per pixel used in rasterization. 128 * pname:sampleShadingEnable can: be used to enable 129 <<primsrast-sampleshading,Sample Shading>>. 130 * pname:minSampleShading specifies a minimum fraction of sample shading if 131 pname:sampleShadingEnable is set to ename:VK_TRUE. 132 * pname:pSampleMask is a bitmask of static coverage information that is 133 ANDed with the coverage information generated during rasterization, as 134 described in <<fragops-samplemask,Sample Mask>>. 135 * pname:alphaToCoverageEnable controls whether a temporary coverage value 136 is generated based on the alpha component of the fragment's first color 137 output as specified in the <<fragops-covg,Multisample Coverage>> 138 section. 139 * pname:alphaToOneEnable controls whether the alpha component of the 140 fragment's first color output is replaced with one as described in 141 <<fragops-covg,Multisample Coverage>>. 142 143.Valid Usage 144**** 145 * [[VUID-VkPipelineMultisampleStateCreateInfo-sampleShadingEnable-00784]] 146 If the <<features-features-sampleRateShading,sample rate shading>> 147 feature is not enabled, pname:sampleShadingEnable must: be 148 ename:VK_FALSE 149 * [[VUID-VkPipelineMultisampleStateCreateInfo-alphaToOneEnable-00785]] 150 If the <<features-features-alphaToOne,alpha to one>> feature is not 151 enabled, pname:alphaToOneEnable must: be ename:VK_FALSE 152 * [[VUID-VkPipelineMultisampleStateCreateInfo-minSampleShading-00786]] 153 pname:minSampleShading must: be in the range [eq]#[0,1]# 154ifdef::VK_NV_framebuffer_mixed_samples[] 155 * [[VUID-VkPipelineMultisampleStateCreateInfo-rasterizationSamples-01415]] 156 If the subpass has any color attachments and pname:rasterizationSamples 157 is greater than the number of color samples, then 158 pname:sampleShadingEnable must: be ename:VK_FALSE 159endif::VK_NV_framebuffer_mixed_samples[] 160 161**** 162 163include::../validity/structs/VkPipelineMultisampleStateCreateInfo.txt[] 164-- 165 166[open,refpage='VkPipelineMultisampleStateCreateFlags',desc='Reserved for future use',type='enums'] 167-- 168include::../api/flags/VkPipelineMultisampleStateCreateFlags.txt[] 169 170sname:VkPipelineMultisampleStateCreateFlags is a bitmask type for setting a 171mask, but is currently reserved for future use. 172-- 173 174Rasterization only produces fragments corresponding to pixels in the 175framebuffer. 176Fragments which would be produced by application of any of the primitive 177rasterization rules described below but which lie outside the framebuffer 178are not produced, nor are they processed by any later stage of the pipeline, 179including any of the early per-fragment tests described in 180<<fragops-early,Early Per-Fragment Tests>>. 181 182Surviving fragments are processed by fragment shaders. 183Fragment shaders determine associated data for fragments, and can: also 184modify or replace their assigned depth values. 185 186ifndef::VK_AMD_mixed_attachment_samples[] 187ifndef::VK_NV_framebuffer_mixed_samples[] 188 189If the subpass for which this pipeline is being created uses color and/or 190depth/stencil attachments, then pname:rasterizationSamples must: be the same 191as the sample count for those subpass attachments. 192 193endif::VK_NV_framebuffer_mixed_samples[] 194endif::VK_AMD_mixed_attachment_samples[] 195 196ifdef::VK_AMD_mixed_attachment_samples[] 197 198If the subpass for which this pipeline is being created uses color and/or 199depth/stencil attachments, then pname:rasterizationSamples must: be the same 200as the maximum of the sample counts of those subpass attachments. 201 202endif::VK_AMD_mixed_attachment_samples[] 203 204If the subpass for which this pipeline is being created does not use color 205or depth/stencil attachments, pname:rasterizationSamples must: follow the 206rules for a <<renderpass-noattachments, zero-attachment subpass>>. 207 208 209[[primsrast-discard]] 210== Discarding Primitives Before Rasterization 211 212Primitives are discarded before rasterization if the 213pname:rasterizerDiscardEnable member of 214slink:VkPipelineRasterizationStateCreateInfo is enabled. 215When enabled, primitives are discarded after they are processed by the last 216active shader stage in the pipeline before rasterization. 217 218 219[[primrast-order]] 220== Rasterization Order 221 222Within a subpass of a <<renderpass,render pass instance>>, for a given 223(x,y,layer,sample) sample location, the following operations are guaranteed 224to execute in _rasterization order_, for each separate primitive that 225includes that sample location: 226 227 . <<fragops-scissor,Scissor test>> 228 . <<fragops-samplemask,Sample mask generation>> 229 . <<fragops-dbt,Depth bounds test>> 230 . <<fragops-stencil, Stencil test, stencil op and stencil write>> 231 . <<fragops-depth, Depth test and depth write>> 232 . <<fragops-samplecount,Sample counting>> for 233 <<queries-occlusion,occlusion queries>> 234ifdef::VK_NV_fragment_coverage_to_color[] 235 . <<fragops-coverage-to-color,Fragment Coverage To Color>> 236endif::VK_NV_fragment_coverage_to_color[] 237 . <<fragops-coverage-reduction,coverage reduction>> 238 . <<framebuffer-blending, Blending>>, <<framebuffer-logicop, logic 239 operations>>, and color writes 240 241Each of these operations is atomically executed for each primitive and 242sample location. 243 244Execution of these operations for each primitive in a subpass occurs in 245ifndef::VK_AMD_rasterization_order[] 246<<drawing-primitive-order, primitive order>>. 247endif::VK_AMD_rasterization_order[] 248ifdef::VK_AMD_rasterization_order[] 249an order determined by the application. 250 251[open,refpage='VkPipelineRasterizationStateRasterizationOrderAMD',desc='Structure defining rasterization order for a graphics pipeline',type='structs'] 252-- 253 254The rasterization order to use for a graphics pipeline is specified by 255adding a sname:VkPipelineRasterizationStateRasterizationOrderAMD structure 256to the pname:pNext chain of a slink:VkPipelineRasterizationStateCreateInfo 257structure. 258 259The sname:VkPipelineRasterizationStateRasterizationOrderAMD structure is 260defined as: 261 262include::../api/structs/VkPipelineRasterizationStateRasterizationOrderAMD.txt[] 263 264 * pname:sType is the type of this structure. 265 * pname:pNext is `NULL` or a pointer to an extension-specific structure. 266 * pname:rasterizationOrder is a elink:VkRasterizationOrderAMD value 267 specifying the primitive rasterization order to use. 268 269include::../validity/structs/VkPipelineRasterizationStateRasterizationOrderAMD.txt[] 270 271If the `<<VK_AMD_rasterization_order>>` device extension is not enabled or 272the application does not request a particular rasterization order through 273specifying a sname:VkPipelineRasterizationStateRasterizationOrderAMD 274structure then the rasterization order used by the graphics pipeline 275defaults to ename:VK_RASTERIZATION_ORDER_STRICT_AMD. 276 277-- 278 279[open,refpage='VkRasterizationOrderAMD',desc='Specify rasterization order for a graphics pipeline',type='enums'] 280-- 281 282Possible values of 283slink:VkPipelineRasterizationStateRasterizationOrderAMD::pname:rasterizationOrder, 284specifying the primitive rasterization order, are: 285 286include::../api/enums/VkRasterizationOrderAMD.txt[] 287 288 * ename:VK_RASTERIZATION_ORDER_STRICT_AMD specifies that operations for 289 each primitive in a subpass must: occur in <<drawing-primitive-order, 290 primitive order>>. 291 * ename:VK_RASTERIZATION_ORDER_RELAXED_AMD specifies that operations for 292 each primitive in a subpass may: not occur in <<drawing-primitive-order, 293 primitive order>>. 294 295-- 296 297endif::VK_AMD_rasterization_order[] 298 299 300[[primsrast-multisampling]] 301== Multisampling 302 303Multisampling is a mechanism to antialias all Vulkan primitives: points, 304lines, and polygons. 305The technique is to sample all primitives multiple times at each pixel. 306Each sample in each framebuffer attachment has storage for a color, depth, 307and/or stencil value, such that per-fragment operations apply to each sample 308independently. 309The color sample values can: be later _resolved_ to a single color (see 310<<copies-resolve,Resolving Multisample Images>> and the <<renderpass,Render 311Pass>> chapter for more details on how to resolve multisample images to 312non-multisample images). 313 314Vulkan defines rasterization rules for single-sample modes in a way that is 315equivalent to a multisample mode with a single sample in the center of each 316pixel. 317 318Each fragment includes a coverage value with pname:rasterizationSamples bits 319(see <<fragops-samplemask,Sample Mask>>). 320Each fragment includes pname:rasterizationSamples depth values and sets of 321associated data. 322An implementation may: choose to assign the same associated data to more 323than one sample. 324The location for evaluating such associated data may: be anywhere within the 325pixel including the pixel center or any of the sample locations. 326When pname:rasterizationSamples is ename:VK_SAMPLE_COUNT_1_BIT, the pixel 327center must: be used. 328The different associated data values need not all be evaluated at the same 329location. 330Each pixel fragment thus consists of integer x and y grid coordinates, 331pname:rasterizationSamples depth values and sets of associated data, and a 332coverage value with pname:rasterizationSamples bits. 333 334It is understood that each pixel has pname:rasterizationSamples locations 335associated with it. 336These locations are exact positions, rather than regions or areas, and each 337is referred to as a sample point. 338The sample points associated with a pixel must: be located inside or on the 339boundary of the unit square that is considered to bound the pixel. 340Furthermore, the relative locations of sample points may: be identical for 341each pixel in the framebuffer, or they may: differ. 342If the current pipeline includes a fragment shader with one or more 343variables in its interface decorated with code:Sample and code:Input, the 344data associated with those variables will be assigned independently for each 345sample. 346The values for each sample must: be evaluated at the location of the sample. 347The data associated with any other variables not decorated with code:Sample 348and code:Input need not be evaluated independently for each sample. 349 350If the pname:standardSampleLocations member of slink:VkPhysicalDeviceLimits 351is ename:VK_TRUE, then the sample counts ename:VK_SAMPLE_COUNT_1_BIT, 352ename:VK_SAMPLE_COUNT_2_BIT, ename:VK_SAMPLE_COUNT_4_BIT, 353ename:VK_SAMPLE_COUNT_8_BIT, and ename:VK_SAMPLE_COUNT_16_BIT have sample 354locations as listed in the following table, with the [eq]##i##th entry in 355the table corresponding to bit [eq]#i# in the sample masks. 356ename:VK_SAMPLE_COUNT_32_BIT and ename:VK_SAMPLE_COUNT_64_BIT do not have 357standard sample locations. 358Locations are defined relative to an origin in the upper left corner of the 359pixel. 360 361<<< 362 363.Standard sample locations 364[align="center"] 365|==== 366|ename:VK_SAMPLE_COUNT_1_BIT|ename:VK_SAMPLE_COUNT_2_BIT|ename:VK_SAMPLE_COUNT_4_BIT|ename:VK_SAMPLE_COUNT_8_BIT|ename:VK_SAMPLE_COUNT_16_BIT 367| 368[eq]#(0.5,0.5)# 369| 370[eq]#(0.75,0.75)# + 371[eq]#(0.25,0.25)# 372| 373[eq]#(0.375, 0.125)# + 374[eq]#(0.875, 0.375)# + 375[eq]#(0.125, 0.625)# + 376[eq]#(0.625, 0.875)# 377| 378[eq]#(0.5625, 0.3125)# + 379[eq]#(0.4375, 0.6875)# + 380[eq]#(0.8125, 0.5625)# + 381[eq]#(0.3125, 0.1875)# + 382[eq]#(0.1875, 0.8125)# + 383[eq]#(0.0625, 0.4375)# + 384[eq]#(0.6875, 0.9375)# + 385[eq]#(0.9375, 0.0625)# 386| 387[eq]#(0.5625, 0.5625)# + 388[eq]#(0.4375, 0.3125)# + 389[eq]#(0.3125, 0.625)# + 390[eq]#(0.75, 0.4375)# + 391[eq]#(0.1875, 0.375)# + 392[eq]#(0.625, 0.8125)# + 393[eq]#(0.8125, 0.6875)# + 394[eq]#(0.6875, 0.1875)# + 395[eq]#(0.375, 0.875)# + 396[eq]#(0.5, 0.0625)# + 397[eq]#(0.25, 0.125)# + 398[eq]#(0.125, 0.75)# + 399[eq]#(0.0, 0.5)# + 400[eq]#(0.9375, 0.25)# + 401[eq]#(0.875, 0.9375)# + 402[eq]#(0.0625, 0.0)# 403|image:images/sample_count_1.svg[align="center"] 404|image:images/sample_count_2.svg[align="center"] 405|image:images/sample_count_4.svg[align="center"] 406|image:images/sample_count_8.svg[align="center"] 407|image:images/sample_count_16.svg[align="center"] 408|==== 409 410ifdef::VK_AMD_shader_fragment_mask[] 411Color images created with multiple samples per pixel use a compression 412technique where there are two arrays of data associated with each pixel. 413The first array contains one element per sample where each element stores an 414index to the second array defining the _fragment mask_ of the pixel. 415The second array contains one element per _color fragment_ and each element 416stores a unique color value in the format of the image. 417With this compression technique it's not always necessary to actually use 418unique storage locations for each color sample: when multiple samples share 419the same color value the fragment mask may: have two samples referring to 420the same color fragment. 421The number of color fragments is determined by the pname:samples member of 422the slink:VkImageCreateInfo structure used to create the image. 423The `<<VK_AMD_shader_fragment_mask>>` device extension provides shader 424instructions enabling the application to get direct access to the fragment 425mask and the individual color fragment values. 426 427[[vk-amd-shader-fragment-mask-diagram]] 428[%inline] 429image::images/fragment_mask.svg[align="center",title="Fragment Mask",align="center"] 430 431endif::VK_AMD_shader_fragment_mask[] 432 433ifdef::VK_EXT_sample_locations[] 434 435[[primrast-samplelocations]] 436== Custom Sample Locations 437 438[open,refpage='VkPipelineSampleLocationsStateCreateInfoEXT',desc='Structure specifying sample locations for a pipeline',type='structs'] 439-- 440 441Applications can: also control the sample locations used for rasterization. 442 443If the pname:pNext chain of the slink:VkPipelineMultisampleStateCreateInfo 444structure specified at pipeline creation time includes an instance of the 445sname:VkPipelineSampleLocationsStateCreateInfoEXT structure, then that 446structure controls the sample locations used when rasterizing primitives 447with the pipeline. 448 449The sname:VkPipelineSampleLocationsStateCreateInfoEXT structure is defined 450as: 451 452include::../api/structs/VkPipelineSampleLocationsStateCreateInfoEXT.txt[] 453 454 * pname:sType is the type of this structure. 455 * pname:pNext is `NULL` or a pointer to an extension-specific structure. 456 * pname:sampleLocationsEnable controls whether custom sample locations are 457 used. 458 If pname:sampleLocationsEnable is ename:VK_FALSE, the default sample 459 locations are used and the values specified in pname:sampleLocationsInfo 460 are ignored. 461 * pname:sampleLocationsInfo is the sample locations to use during 462 rasterization if pname:sampleLocationsEnable is ename:VK_TRUE and the 463 graphics pipeline is not created with 464 ename:VK_DYNAMIC_STATE_SAMPLE_LOCATIONS_EXT. 465 466include::../validity/structs/VkPipelineSampleLocationsStateCreateInfoEXT.txt[] 467-- 468 469[open,refpage='VkSampleLocationsInfoEXT',desc='Structure specifying a set of sample locations',type='structs'] 470-- 471 472The sname:VkSampleLocationsInfoEXT structure is defined as: 473 474include::../api/structs/VkSampleLocationsInfoEXT.txt[] 475 476 * pname:sType is the type of this structure. 477 * pname:pNext is `NULL` or a pointer to an extension-specific structure. 478 * pname:sampleLocationsPerPixel is a elink:VkSampleCountFlagBits 479 specifying the number of sample locations per pixel. 480 * pname:sampleLocationGridSize is the size of the sample location grid to 481 select custom sample locations for. 482 * pname:sampleLocationsCount is the number of sample locations in 483 pname:pSampleLocations. 484 * pname:pSampleLocations is an array of pname:sampleLocationsCount 485 slink:VkSampleLocationEXT structures. 486 487This structure can: be used either to specify the sample locations to be 488used for rendering or to specify the set of sample locations an image 489subresource has been last rendered with for the purposes of layout 490transitions of depth/stencil images created with 491ename:VK_IMAGE_CREATE_SAMPLE_LOCATIONS_COMPATIBLE_DEPTH_BIT_EXT. 492 493The sample locations in pname:pSampleLocations specify 494pname:sampleLocationsPerPixel number of sample locations for each pixel in 495the grid of the size specified in pname:sampleLocationGridSize. 496The sample location for sample [eq]#i# at the pixel grid location 497[eq]#(x,y)# is taken from [eq]#pname:pSampleLocations[(x + y * 498pname:sampleLocationGridSize.width) 499* pname:sampleLocationsPerPixel + i]#. 500 501.Valid Usage 502**** 503 * [[VUID-VkSampleLocationsInfoEXT-sampleLocationsPerPixel-01526]] 504 pname:sampleLocationsPerPixel must: be a bit value that is set in 505 slink:VkPhysicalDeviceSampleLocationsPropertiesEXT::pname:sampleLocationSampleCounts 506 * [[VUID-VkSampleLocationsInfoEXT-sampleLocationsCount-01527]] 507 pname:sampleLocationsCount must: equal 508 [eq]#pname:sampleLocationsPerPixel {times} 509 pname:sampleLocationGridSize.width {times} 510 pname:sampleLocationGridSize.height# 511**** 512 513include::../validity/structs/VkSampleLocationsInfoEXT.txt[] 514-- 515 516[open,refpage='VkSampleLocationEXT',desc='Structure specifying the coordinates of a sample location',type='structs'] 517-- 518 519The sname:VkSampleLocationEXT structure is defined as: 520 521include::../api/structs/VkSampleLocationEXT.txt[] 522 523 * pname:x is the horizontal coordinate of the sample's location. 524 * pname:y is the vertical coordinate of the sample's location. 525 526The domain space of the sample location coordinates has an upper-left origin 527within the pixel in framebuffer space. 528 529The values specified in a sname:VkSampleLocationEXT structure are always 530clamped to the implementation-dependent sample location coordinate range 531[eq]#[pname:sampleLocationCoordinateRange[0],pname:sampleLocationCoordinateRange[1]]# 532that can: be queried by chaining the 533slink:VkPhysicalDeviceSampleLocationsPropertiesEXT structure to the 534pname:pNext chain of slink:VkPhysicalDeviceProperties2. 535 536include::../validity/structs/VkSampleLocationEXT.txt[] 537-- 538 539[open,refpage='vkCmdSetSampleLocationsEXT',desc='Set the dynamic sample locations state',type='protos'] 540-- 541The custom sample locations used for rasterization when 542sname:VkPipelineSampleLocationsStateCreateInfoEXT::pname:sampleLocationsEnable 543is ename:VK_TRUE are specified by the 544sname:VkPipelineSampleLocationsStateCreateInfoEXT::pname:sampleLocationsInfo 545property of the bound graphics pipeline, if the pipeline was not created 546with ename:VK_DYNAMIC_STATE_SAMPLE_LOCATIONS_EXT enabled. 547 548Otherwise, the sample locations used for rasterization are set by calling 549fname:vkCmdSetSampleLocationsEXT: 550 551include::../api/protos/vkCmdSetSampleLocationsEXT.txt[] 552 553 * pname:commandBuffer is the command buffer into which the command will be 554 recorded. 555 * pname:pSampleLocationsInfo is the sample locations state to set. 556 557.Valid Usage 558**** 559 * [[VUID-vkCmdSetSampleLocationsEXT-None-01528]] 560 The bound graphics pipeline must: have been created with the 561 ename:VK_DYNAMIC_STATE_SAMPLE_LOCATIONS_EXT dynamic state enabled 562 * [[VUID-vkCmdSetSampleLocationsEXT-sampleLocationsPerPixel-01529]] 563 The pname:sampleLocationsPerPixel member of pname:pSampleLocationsInfo 564 must: equal the pname:rasterizationSamples member of the 565 slink:VkPipelineMultisampleStateCreateInfo structure the bound graphics 566 pipeline has been created with 567 * [[VUID-vkCmdSetSampleLocationsEXT-variableSampleLocations-01530]] 568 If 569 slink:VkPhysicalDeviceSampleLocationsPropertiesEXT::pname:variableSampleLocations 570 is ename:VK_FALSE then the current render pass must: have been begun by 571 specifying a slink:VkRenderPassSampleLocationsBeginInfoEXT structure 572 whose pname:pPostSubpassSampleLocations member contains an element with 573 a pname:subpassIndex matching the current subpass index and the 574 pname:sampleLocationsInfo member of that element must: match the sample 575 locations state pointed to by pname:pSampleLocationsInfo 576**** 577 578include::../validity/protos/vkCmdSetSampleLocationsEXT.txt[] 579-- 580 581endif::VK_EXT_sample_locations[] 582 583 584[[primsrast-sampleshading]] 585== Sample Shading 586 587Sample shading can: be used to specify a minimum number of unique samples to 588process for each fragment. 589If sample shading is enabled an implementation must: provide a minimum of 590[eq]#max({lceil} pname:minSampleShadingFactor {times} pname:totalSamples 591{rceil}, 1)# unique associated data for each fragment, where 592pname:minSampleShadingFactor is the minimum fraction of sample shading and 593pname:totalSamples is 594ifdef::VK_AMD_mixed_attachment_samples[] 595the number of samples of the color attachments used in the subpass or, if 596the subpass does not use any color attachments, 597endif::VK_AMD_mixed_attachment_samples[] 598the value of 599slink:VkPipelineMultisampleStateCreateInfo::pname:rasterizationSamples 600specified at pipeline creation time. 601These are associated with the samples in an implementation-dependent manner. 602When pname:minSampleShadingFactor is `1.0`, a separate set of associated 603data are evaluated for each sample, and each set of values is evaluated at 604the sample location. 605 606Sample shading is enabled for a graphics pipeline: 607 608 * If the interface of the fragment shader entry point of the graphics 609 pipeline includes an input variable decorated with code:SampleId or 610 code:SamplePosition. 611 In this case pname:minSampleShadingFactor takes the value `1.0`. 612 * Else if the pname:sampleShadingEnable member of the 613 slink:VkPipelineMultisampleStateCreateInfo structure specified when 614 creating the graphics pipeline is set to ename:VK_TRUE. 615 In this case pname:minSampleShadingFactor takes the value of 616 slink:VkPipelineMultisampleStateCreateInfo::pname:minSampleShading. 617 618Otherwise, sample shading is considered disabled. 619 620 621[[primsrast-points]] 622== Points 623 624A point is drawn by generating a set of fragments in the shape of a square 625centered around the vertex of the point. 626Each vertex has an associated point size that controls the width/height of 627that square. 628The point size is taken from the (potentially clipped) shader built-in 629code:PointSize written by: 630 631 * the geometry shader, if active; 632 * the tessellation evaluation shader, if active and no geometry shader is 633 active; 634 * the vertex shader, otherwise 635 636and clamped to the implementation-dependent point size range 637[eq]#[pname:pointSizeRange[0],pname:pointSizeRange[1]]#. 638If the value written to code:PointSize is less than or equal to zero, or if 639no value was written to code:PointSize, results are undefined. 640 641Not all point sizes need be supported, but the size 1.0 must: be supported. 642The range of supported sizes and the size of evenly-spaced gradations within 643that range are implementation-dependent. 644The range and gradations are obtained from the pname:pointSizeRange and 645pname:pointSizeGranularity members of slink:VkPhysicalDeviceLimits. 646If, for instance, the size range is from 0.1 to 2.0 and the gradation size 647is 0.1, then the size 0.1, 0.2, ..., 1.9, 2.0 are supported. 648Additional point sizes may: also be supported. 649There is no requirement that these sizes be equally spaced. 650If an unsupported size is requested, the nearest supported size is used 651instead. 652 653 654[[primsrast-points-basic]] 655=== Basic Point Rasterization 656 657Point rasterization produces a fragment for each framebuffer pixel with one 658or more sample points that intersect a region centered at the point's 659[eq]#(x~f~,y~f~)#. 660This region is a square with side equal to the current point size. 661Coverage bits that correspond to sample points that intersect the region are 6621, other coverage bits are 0. 663 664All fragments produced in rasterizing a point are assigned the same 665associated data, which are those of the vertex corresponding to the point. 666However, the fragment shader built-in code:PointCoord contains point sprite 667texture coordinates. 668The [eq]#s# and [eq]#t# point sprite texture coordinates vary from zero to 669one across the point horizontally left-to-right and top-to-bottom, 670respectively. 671The following formulas are used to evaluate [eq]#s# and [eq]#t#: 672 673[latexmath] 674++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 675s = {1 \over 2} + { \left( x_p - x_f \right) \over \text{size} } 676++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 677 678[latexmath] 679++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 680t = {1 \over 2} + { \left( y_p - y_f \right) \over \text{size} } 681++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 682 683where size is the point's size, [eq]#(x~p~,y~p~)# is the location at which 684the point sprite coordinates are evaluated - this may: be the framebuffer 685coordinates of the pixel center (i.e. at the half-integer) or the location 686of a sample, and [eq]#(x~f~,y~f~)# is the exact, unrounded framebuffer 687coordinate of the vertex for the point. 688When pname:rasterizationSamples is ename:VK_SAMPLE_COUNT_1_BIT, the pixel 689center must: be used. 690 691 692[[primsrast-lines]] 693== Line Segments 694 695A line is drawn by generating a set of fragments overlapping a rectangle 696centered on the line segment. 697Each line segment has an associated width that controls the width of that 698rectangle. 699 700[open,refpage='vkCmdSetLineWidth',desc='Set the dynamic line width state',type='protos'] 701-- 702 703The line width is specified by the 704slink:VkPipelineRasterizationStateCreateInfo::pname:lineWidth property of 705the currently active pipeline, if the pipeline was not created with 706ename:VK_DYNAMIC_STATE_LINE_WIDTH enabled. 707 708Otherwise, the line width is set by calling fname:vkCmdSetLineWidth: 709 710include::../api/protos/vkCmdSetLineWidth.txt[] 711 712 * pname:commandBuffer is the command buffer into which the command will be 713 recorded. 714 * pname:lineWidth is the width of rasterized line segments. 715 716.Valid Usage 717**** 718 * [[VUID-vkCmdSetLineWidth-None-00787]] 719 The bound graphics pipeline must: have been created with the 720 ename:VK_DYNAMIC_STATE_LINE_WIDTH dynamic state enabled 721 * [[VUID-vkCmdSetLineWidth-lineWidth-00788]] 722 If the <<features-features-wideLines,wide lines>> feature is not 723 enabled, pname:lineWidth must: be `1.0` 724**** 725 726include::../validity/protos/vkCmdSetLineWidth.txt[] 727-- 728 729Not all line widths need be supported for line segment rasterization, but 730width 1.0 antialiased segments must: be provided. 731The range and gradations are obtained from the pname:lineWidthRange and 732pname:lineWidthGranularity members of slink:VkPhysicalDeviceLimits. 733If, for instance, the size range is from 0.1 to 2.0 and the gradation size 734is 0.1, then the size 0.1, 0.2, ..., 1.9, 2.0 are supported. 735Additional line widths may: also be supported. 736There is no requirement that these widths be equally spaced. 737If an unsupported width is requested, the nearest supported width is used 738instead. 739 740 741[[primsrast-lines-basic]] 742=== Basic Line Segment Rasterization 743 744Rasterized line segments produce fragments which intersect a rectangle 745centered on the line segment. 746Two of the edges are parallel to the specified line segment; each is at a 747distance of one-half the current width from that segment in directions 748perpendicular to the direction of the line. 749The other two edges pass through the line endpoints and are perpendicular to 750the direction of the specified line segment. 751Coverage bits that correspond to sample points that intersect the rectangle 752are 1, other coverage bits are 0. 753 754Next we specify how the data associated with each rasterized fragment are 755obtained. 756Let [eq]#**p**~r~ = (x~d~, y~d~)# be the framebuffer coordinates at which 757associated data are evaluated. 758This may: be the pixel center of a fragment or the location of a sample 759within the fragment. 760When pname:rasterizationSamples is ename:VK_SAMPLE_COUNT_1_BIT, the pixel 761center must: be used. 762Let [eq]#**p**~a~ = (x~a~, y~a~)# and [eq]#**p**~b~ = (x~b~,y~b~)# be 763initial and final endpoints of the line segment, respectively. 764Set 765 766// Equation {linet:eq} 767[latexmath] 768++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 769t = {{( \mathbf{p}_r - \mathbf{p}_a ) \cdot ( \mathbf{p}_b - \mathbf{p}_a )} 770 \over {\| \mathbf{p}_b - \mathbf{p}_a \|^2 }} 771++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 772 773(Note that [eq]#t = 0# at [eq]#**p**_a# and [eq]#t = 1# at [eq]#**p**~b~#. 774Also note that this calculation projects the vector from [eq]#**p**~a~# to 775[eq]#**p**~r~# onto the line, and thus computes the normalized distance of 776the fragment along the line.) 777 778[[line_perspective_interpolation]] 779The value of an associated datum [eq]#f# for the fragment, whether it be a 780shader output or the clip [eq]#w# coordinate, must: be determined using 781_perspective interpolation_: 782 783[latexmath] 784++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 785f = {{ (1-t) {f_a / w_a} + t { f_b / w_b} } \over 786 {(1-t) / w_a + t / w_b }} 787++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 788 789where [eq]#f~a~# and [eq]#f~b~# are the data associated with the starting 790and ending endpoints of the segment, respectively; [eq]#w~a~# and [eq]#w~b~# 791are the clip [eq]#w# coordinates of the starting and ending endpoints of the 792segments, respectively. 793 794[[line_linear_interpolation]] 795Depth values for lines must: be determined using _linear interpolation_: 796 797 :: [eq]#z = (1 - t) z~a~ {plus} t z~b~# 798 799where [eq]#z~a~# and [eq]#z~b~# are the depth values of the starting and 800ending endpoints of the segment, respectively. 801 802The code:NoPerspective and code:Flat 803<<shaders-interpolation-decorations,interpolation decorations>> can: be used 804with fragment shader inputs to declare how they are interpolated. 805When neither decoration is applied, <<line_perspective_interpolation, 806perspective interpolation>> is performed as described above. 807When the code:NoPerspective decoration is used, <<line_linear_interpolation, 808linear interpolation>> is performed in the same fashion as for depth values, 809as described above. 810When the code:Flat decoration is used, no interpolation is performed, and 811outputs are taken from the corresponding input value of the 812<<vertexpostproc-flatshading,provoking vertex>> corresponding to that 813primitive. 814 815The above description documents the preferred method of line rasterization, 816and must: be used when the implementation advertises the pname:strictLines 817limit in slink:VkPhysicalDeviceLimits as ename:VK_TRUE. 818 819When pname:strictLines is ename:VK_FALSE, the edges of the lines are 820generated as a parallelogram surrounding the original line. 821The major axis is chosen by noting the axis in which there is the greatest 822distance between the line start and end points. 823If the difference is equal in both directions then the X axis is chosen as 824the major axis. 825Edges 2 and 3 are aligned to the minor axis and are centered on the 826endpoints of the line as in <<fig-non-strict-lines>>, and each is 827pname:lineWidth long. 828Edges 0 and 1 are parallel to the line and connect the endpoints of edges 2 829and 3. 830Coverage bits that correspond to sample points that intersect the 831parallelogram are 1, other coverage bits are 0. 832 833Samples that fall exactly on the edge of the parallelogram follow the 834polygon rasterization rules. 835 836Interpolation occurs as if the parallelogram was decomposed into two 837triangles where each pair of vertices at each end of the line has identical 838attributes. 839 840[[fig-non-strict-lines]] 841[%inline] 842image::images/non_strict_lines.svg[align="center",title="Non strict lines"] 843 844 845[[primsrast-polygons]] 846== Polygons 847 848A polygon results from the decomposition of a triangle strip, triangle fan 849or a series of independent triangles. 850Like points and line segments, polygon rasterization is controlled by 851several variables in the slink:VkPipelineRasterizationStateCreateInfo 852structure. 853 854 855[[primsrast-polygons-basic]] 856=== Basic Polygon Rasterization 857 858[open,refpage='VkFrontFace',desc='Interpret polygon front-facing orientation',type='enums'] 859-- 860 861The first step of polygon rasterization is to determine whether the triangle 862is _back-facing_ or _front-facing_. 863This determination is made based on the sign of the (clipped or unclipped) 864polygon's area computed in framebuffer coordinates. 865One way to compute this area is: 866 867[latexmath] 868++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 869a = -{1 \over 2}\sum_{i=0}^{n-1} 870 x_f^i y_f^{i \oplus 1} - 871 x_f^{i \oplus 1} y_f^i 872++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 873 874where latexmath:[x_f^i] and latexmath:[y_f^i] are the [eq]#x# and [eq]#y# 875framebuffer coordinates of the [eq]##i##th vertex of the [eq]#n#-vertex 876polygon (vertices are numbered starting at zero for the purposes of this 877computation) and [eq]#i {oplus} 1# is [eq]#(i {plus} 1) mod n#. 878 879The interpretation of the sign of [eq]#a# is determined by the 880slink:VkPipelineRasterizationStateCreateInfo::pname:frontFace property of 881the currently active pipeline. 882Possible values are: 883 884include::../api/enums/VkFrontFace.txt[] 885 886 * ename:VK_FRONT_FACE_COUNTER_CLOCKWISE specifies that a triangle with 887 positive area is considered front-facing. 888 * ename:VK_FRONT_FACE_CLOCKWISE specifies that a triangle with negative 889 area is considered front-facing. 890 891Any triangle which is not front-facing is back-facing, including zero-area 892triangles. 893 894-- 895 896[open,refpage='VkCullModeFlagBits',desc='Bitmask controlling triangle culling',type='enums'] 897-- 898 899Once the orientation of triangles is determined, they are culled according 900to the slink:VkPipelineRasterizationStateCreateInfo::pname:cullMode property 901of the currently active pipeline. 902Possible values are: 903 904include::../api/enums/VkCullModeFlagBits.txt[] 905 906 * ename:VK_CULL_MODE_NONE specifies that no triangles are discarded 907 * ename:VK_CULL_MODE_FRONT_BIT specifies that front-facing triangles are 908 discarded 909 * ename:VK_CULL_MODE_BACK_BIT specifies that back-facing triangles are 910 discarded 911 * ename:VK_CULL_MODE_FRONT_AND_BACK specifies that all triangles are 912 discarded. 913 914Following culling, fragments are produced for any triangles which have not 915been discarded. 916 917-- 918 919[open,refpage='VkCullModeFlags',desc='Bitmask of VkCullModeFlagBits',type='enums'] 920-- 921include::../api/flags/VkCullModeFlags.txt[] 922 923sname:VkCullModeFlags is a bitmask type for setting a mask of zero or more 924slink:VkCullModeFlagBits. 925-- 926 927The rule for determining which fragments are produced by polygon 928rasterization is called _point sampling_. 929The two-dimensional projection obtained by taking the x and y framebuffer 930coordinates of the polygon's vertices is formed. 931Fragments are produced for any pixels for which any sample points lie inside 932of this polygon. 933Coverage bits that correspond to sample points that satisfy the point 934sampling criteria are 1, other coverage bits are 0. 935Special treatment is given to a sample whose sample location lies on a 936polygon edge. 937In such a case, if two polygons lie on either side of a common edge (with 938identical endpoints) on which a sample point lies, then exactly one of the 939polygons must: result in a covered sample for that fragment during 940rasterization. 941As for the data associated with each fragment produced by rasterizing a 942polygon, we begin by specifying how these values are produced for fragments 943in a triangle. 944Define _barycentric coordinates_ for a triangle. 945Barycentric coordinates are a set of three numbers, [eq]#a#, [eq]#b#, and 946[eq]#c#, each in the range [eq]#[0,1]#, with [eq]#a {plus} b {plus} c = 1#. 947These coordinates uniquely specify any point [eq]#p# within the triangle or 948on the triangle's boundary as 949 950 :: [eq]#p = a p~a~ {plus} b p~b~ {plus} c p~c~# 951 952where [eq]#p~a~#, [eq]#p~b~#, and [eq]#p~c~# are the vertices of the 953triangle. 954[eq]#a#, [eq]#b#, and [eq]#c# are determined by: 955 956[latexmath] 957++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 958a = {{\mathrm{A}(p p_b p_c)} \over {\mathrm{A}(p_a p_b p_c)}}, \quad 959b = {{\mathrm{A}(p p_a p_c)} \over {\mathrm{A}(p_a p_b p_c)}}, \quad 960c = {{\mathrm{A}(p p_a p_b)} \over {\mathrm{A}(p_a p_b p_c)}}, 961++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 962 963where [eq]#A(lmn)# denotes the area in framebuffer coordinates of the 964triangle with vertices [eq]#l#, [eq]#m#, and [eq]#n#. 965 966Denote an associated datum at [eq]#p~a~#, [eq]#p~b~#, or [eq]#p~c~# as 967[eq]#f~a~#, [eq]#f~b~#, or [eq]#f~c~#, respectively. 968 969[[triangle_perspective_interpolation]] 970The value of an associated datum [eq]#f# for a fragment produced by 971rasterizing a triangle, whether it be a shader output or the clip [eq]#w# 972coordinate, must: be determined using perspective interpolation: 973 974[latexmath] 975++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 976f = { a {f_a / w_a} + b {f_b / w_b} + c {f_c / w_c} } \over 977 { {a / w_a} + {b / w_b} + {c / w_c} } 978++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 979 980where [eq]#w~a~#, [eq]#w~b~#, and [eq]#w~c~# are the clip [eq]#w# 981coordinates of [eq]#p~a~#, [eq]#p~b~#, and [eq]#p~c~#, respectively. 982[eq]#a#, [eq]#b#, and [eq]#c# are the barycentric coordinates of the 983location at which the data are produced - this must: be a pixel center or 984the location of a sample. 985When pname:rasterizationSamples is ename:VK_SAMPLE_COUNT_1_BIT, the pixel 986center must: be used. 987 988[[triangle_linear_interpolation]] 989Depth values for triangles must: be determined using linear interpolation: 990 991 :: [eq]#z = a z~a~ {plus} b z~b~ {plus} c z~c~# 992 993where [eq]#z~a~#, [eq]#z~b~#, and [eq]#z~c~# are the depth values of 994[eq]#p~a~#, [eq]#p~b~#, and [eq]#p~c~#, respectively. 995 996The code:NoPerspective and code:Flat 997<<shaders-interpolation-decorations,interpolation decorations>> can: be used 998with fragment shader inputs to declare how they are interpolated. 999When neither decoration is applied, <<triangle_perspective_interpolation, 1000perspective interpolation>> is performed as described above. 1001When the code:NoPerspective decoration is used, 1002<<triangle_linear_interpolation, linear interpolation>> is performed in the 1003same fashion as for depth values, as described above. 1004When the code:Flat decoration is used, no interpolation is performed, and 1005outputs are taken from the corresponding input value of the 1006<<vertexpostproc-flatshading,provoking vertex>> corresponding to that 1007primitive. 1008 1009ifdef::VK_AMD_shader_explicit_vertex_parameter[] 1010When the `<<VK_AMD_shader_explicit_vertex_parameter>>` device extension is 1011enabled the code:CustomInterpAMD <<shaders-interpolation-decorations, 1012interpolation decoration>> can: also be used with fragment shader inputs 1013which indicate that the decorated inputs can: only be accessed by the 1014extended instruction code:InterpolateAtVertexAMD and allows accessing the 1015value of the inputs for individual vertices of the primitive. 1016endif::VK_AMD_shader_explicit_vertex_parameter[] 1017 1018For a polygon with more than three edges, such as are produced by clipping a 1019triangle, a convex combination of the values of the datum at the polygon's 1020vertices must: be used to obtain the value assigned to each fragment 1021produced by the rasterization algorithm. 1022That is, it must: be the case that at every fragment 1023 1024[latexmath] 1025++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1026f = \sum_{i=1}^{n} a_i f_i 1027++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1028 1029where [eq]#n# is the number of vertices in the polygon and [eq]#f~i~# is the 1030value of [eq]#f# at vertex [eq]#i#. 1031For each [eq]#i#, [eq]#0 {leq} a~i~ {leq} 1# and 1032latexmath:[\sum_{i=1}^{n}a_i = 1]. 1033The values of [eq]#a~i~# may: differ from fragment to fragment, but at 1034vertex [eq]#i#, [eq]#a~i~ = 1# and [eq]#a~j~ = 0# for [eq]#j {neq} i#. 1035 1036[NOTE] 1037.Note 1038==== 1039One algorithm that achieves the required behavior is to triangulate a 1040polygon (without adding any vertices) and then treat each triangle 1041individually as already discussed. 1042A scan-line rasterizer that linearly interpolates data along each edge and 1043then linearly interpolates data across each horizontal span from edge to 1044edge also satisfies the restrictions (in this case, the numerator and 1045denominator of equation <<triangle_perspective_interpolation>> are iterated 1046independently and a division performed for each fragment). 1047==== 1048 1049 1050[[primsrast-polygonmode]] 1051=== Polygon Mode 1052 1053[open,refpage='VkPolygonMode',desc='Control polygon rasterization mode',type='enums'] 1054-- 1055 1056Possible values of the 1057slink:VkPipelineRasterizationStateCreateInfo::pname:polygonMode property of 1058the currently active pipeline, specifying the method of rasterization for 1059polygons, are: 1060 1061include::../api/enums/VkPolygonMode.txt[] 1062 1063 * ename:VK_POLYGON_MODE_POINT specifies that polygon vertices are drawn as 1064 points. 1065 * ename:VK_POLYGON_MODE_LINE specifies that polygon edges are drawn as 1066 line segments. 1067 * ename:VK_POLYGON_MODE_FILL specifies that polygons are rendered using 1068 the polygon rasterization rules in this section. 1069ifdef::VK_NV_fill_rectangle[] 1070 * ename:VK_POLYGON_MODE_FILL_RECTANGLE_NV specifies that polygons are 1071 rendered using polygon rasterization rules, modified to consider a 1072 sample within the primitive if the sample location is inside the 1073 axis-aligned bounding box of the triangle after projection. 1074 Note that the barycentric weights used in attribute interpolation can: 1075 extend outside the range [eq]#[0,1]# when these primitives are shaded. 1076 Special treatment is given to a sample position on the boundary edge of 1077 the bounding box. 1078 In such a case, if two rectangles lie on either side of a common edge 1079 (with identical endpoints) on which a sample position lies, then exactly 1080 one of the triangles must: produce a fragment that covers that sample 1081 during rasterization. 1082+ 1083Polygons rendered in ename:VK_POLYGON_MODE_FILL_RECTANGLE_NV mode may: be 1084 clipped by the frustum or by user clip planes. 1085 If clipping is applied, the triangle is culled rather than clipped. 1086+ 1087Area calculation and facingness are determined for 1088 ename:VK_POLYGON_MODE_FILL_RECTANGLE_NV mode using the triangle's 1089 vertices. 1090endif::VK_NV_fill_rectangle[] 1091 1092These modes affect only the final rasterization of polygons: in particular, 1093a polygon's vertices are shaded and the polygon is clipped and possibly 1094culled before these modes are applied. 1095 1096-- 1097 1098 1099[[primsrast-depthbias]] 1100=== Depth Bias 1101 1102[open,refpage='vkCmdSetDepthBias',desc='Set the depth bias dynamic state',type='protos'] 1103-- 1104 1105The depth values of all fragments generated by the rasterization of a 1106polygon can: be offset by a single value that is computed for that polygon. 1107This behavior is controlled by the pname:depthBiasEnable, 1108pname:depthBiasConstantFactor, pname:depthBiasClamp, and 1109pname:depthBiasSlopeFactor members of 1110slink:VkPipelineRasterizationStateCreateInfo, or by the corresponding 1111parameters to the fname:vkCmdSetDepthBias command if depth bias state is 1112dynamic. 1113 1114include::../api/protos/vkCmdSetDepthBias.txt[] 1115 1116 * pname:commandBuffer is the command buffer into which the command will be 1117 recorded. 1118 * pname:depthBiasConstantFactor is a scalar factor controlling the 1119 constant depth value added to each fragment. 1120 * pname:depthBiasClamp is the maximum (or minimum) depth bias of a 1121 fragment. 1122 * pname:depthBiasSlopeFactor is a scalar factor applied to a fragment's 1123 slope in depth bias calculations. 1124 1125If pname:depthBiasEnable is ename:VK_FALSE, no depth bias is applied and the 1126fragment's depth values are unchanged. 1127 1128pname:depthBiasSlopeFactor scales the maximum depth slope of the polygon, 1129and pname:depthBiasConstantFactor scales an implementation-dependent 1130constant that relates to the usable resolution of the depth buffer. 1131The resulting values are summed to produce the depth bias value which is 1132then clamped to a minimum or maximum value specified by 1133pname:depthBiasClamp. 1134pname:depthBiasSlopeFactor, pname:depthBiasConstantFactor, and 1135pname:depthBiasClamp can: each be positive, negative, or zero. 1136 1137The maximum depth slope [eq]#m# of a triangle is 1138 1139[latexmath] 1140++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1141m = \sqrt{ \left({{\partial z_f} \over {\partial x_f}}\right)^2 1142 + \left({{\partial z_f} \over {\partial y_f}}\right)^2} 1143++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1144 1145where [eq]#(x~f~, y~f~, z~f~)# is a point on the triangle. 1146[eq]#m# may: be approximated as 1147 1148[latexmath] 1149++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1150m = \max\left( \left| { {\partial z_f} \over {\partial x_f} } \right|, 1151 \left| { {\partial z_f} \over {\partial y_f} } \right| 1152 \right). 1153++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1154 1155The minimum resolvable difference [eq]#r# is an implementation-dependent 1156parameter that depends on the depth buffer representation. 1157It is the smallest difference in framebuffer coordinate [eq]#z# values that 1158is guaranteed to remain distinct throughout polygon rasterization and in the 1159depth buffer. 1160All pairs of fragments generated by the rasterization of two polygons with 1161otherwise identical vertices, but [eq]#pname:z~f~# values that differ by 1162[eq]#r#, will have distinct depth values. 1163 1164For fixed-point depth buffer representations, [eq]#r# is constant throughout 1165the range of the entire depth buffer. 1166For floating-point depth buffers, there is no single minimum resolvable 1167difference. 1168In this case, the minimum resolvable difference for a given polygon is 1169dependent on the maximum exponent, [eq]#e#, in the range of [eq]#z# values 1170spanned by the primitive. 1171If [eq]#n# is the number of bits in the floating-point mantissa, the minimum 1172resolvable difference, [eq]#r#, for the given primitive is defined as 1173 1174 :: [eq]#r = 2^e-n^# 1175 1176ifdef::VK_NV_fill_rectangle[] 1177If a triangle is rasterized using the 1178ename:VK_POLYGON_MODE_FILL_RECTANGLE_NV polygon mode, then this minimum 1179resolvable difference may: not be resolvable for samples outside of the 1180triangle, where the depth is extrapolated. 1181endif::VK_NV_fill_rectangle[] 1182 1183 1184If no depth buffer is present, [eq]#r# is undefined. 1185 1186The bias value [eq]#o# for a polygon is 1187 1188[latexmath] 1189++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1190o = 1191\begin{cases} 1192 m \times depthBiasSlopeFactor + 1193 r \times depthBiasConstantFactor & depthBiasClamp = 0\ or\ NaN \\ 1194 \min(m \times depthBiasSlopeFactor + 1195 r \times depthBiasConstantFactor, 1196 depthBiasClamp) & depthBiasClamp > 0 \\ 1197 \max(m \times depthBiasSlopeFactor + 1198 r \times depthBiasConstantFactor, 1199 depthBiasClamp) & depthBiasClamp < 0 \\ 1200\end{cases} 1201++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1202 1203[eq]#m# is computed as described above. 1204If the depth buffer uses a fixed-point representation, [eq]#m# is a function 1205of depth values in the range [eq]#[0,1]#, and [eq]#o# is applied to depth 1206values in the same range. 1207 1208For fixed-point depth buffers, fragment depth values are always limited to 1209the range [eq]#[0,1]# by clamping after depth bias addition is performed. 1210ifdef::VK_EXT_depth_range_unrestricted[] 1211Unless the `<<VK_EXT_depth_range_unrestricted>>` extension is enabled, 1212fragment depth values are clamped even when the depth buffer uses a 1213floating-point representation. 1214endif::VK_EXT_depth_range_unrestricted[] 1215ifndef::VK_EXT_depth_range_unrestricted[] 1216Fragment depth values are clamped even when the depth buffer uses a 1217floating-point representation. 1218endif::VK_EXT_depth_range_unrestricted[] 1219 1220.Valid Usage 1221**** 1222 * [[VUID-vkCmdSetDepthBias-None-00789]] 1223 The bound graphics pipeline must: have been created with the 1224 ename:VK_DYNAMIC_STATE_DEPTH_BIAS dynamic state enabled 1225 * [[VUID-vkCmdSetDepthBias-depthBiasClamp-00790]] 1226 If the <<features-features-depthBiasClamp,depth bias clamping>> feature 1227 is not enabled, pname:depthBiasClamp must: be `0.0` 1228**** 1229 1230include::../validity/protos/vkCmdSetDepthBias.txt[] 1231-- 1232 1233ifdef::VK_EXT_conservative_rasterization[] 1234[[primsrast-conservativeraster]] 1235=== Conservative Rasterization 1236 1237[open,refpage='VkPipelineRasterizationConservativeStateCreateInfoEXT',desc='Structure specifying conservative raster state',type='structs'] 1238-- 1239 1240Polygon rasterization can: be made conservative by setting 1241pname:conservativeRasterizationMode to 1242ename:VK_CONSERVATIVE_RASTERIZATION_MODE_OVERESTIMATE_EXT or 1243ename:VK_CONSERVATIVE_RASTERIZATION_MODE_UNDERESTIMATE_EXT in 1244sname:VkPipelineRasterizationConservativeStateCreateInfoEXT. 1245The sname:VkPipelineRasterizationConservativeStateCreateInfoEXT state is set 1246by adding an instance of this structure to the pname:pNext chain of an 1247instance of the sname:VkPipelineRasterizationStateCreateInfo structure when 1248creating the graphics pipeline. 1249Enabling these modes also affects line and point rasterization if the 1250implementation sets 1251sname:VkPhysicalDeviceConservativeRasterizationPropertiesEXT::pname:conservativePointAndLineRasterization 1252to pname:VK_TRUE. 1253 1254sname:VkPipelineRasterizationConservativeStateCreateInfoEXT is defined as: 1255 1256include::../api/structs/VkPipelineRasterizationConservativeStateCreateInfoEXT.txt[] 1257 1258 * pname:sType is the type of this structure. 1259 * pname:pNext is `NULL` or a pointer to an extension-specific structure. 1260 * pname:flags is reserved for future use. 1261 * pname:conservativeRasterizationMode is the conservative rasterization 1262 mode to use. 1263 * pname:extraPrimitiveOverestimationSize is the extra size in pixels to 1264 increase the generating primitive during conservative rasterization at 1265 each of its edges in `X` and `Y` equally in screen space beyond the base 1266 overestimation specified in 1267 sname:VkPhysicalDeviceConservativeRasterizationPropertiesEXT::pname:primitiveOverestimationSize. 1268 1269.Valid Usage 1270**** 1271 * [[VUID-VkPipelineRasterizationConservativeStateCreateInfoEXT-extraPrimitiveOverestimationSize-01769]] 1272 pname:extraPrimitiveOverestimationSize must: be in the range of `0.0` to 1273 sname:VkPhysicalDeviceConservativeRasterizationPropertiesEXT::pname:maxExtraPrimitiveOverestimationSize 1274 inclusive 1275**** 1276 1277include::../validity/structs/VkPipelineRasterizationConservativeStateCreateInfoEXT.txt[] 1278-- 1279 1280[open,refpage='VkPipelineRasterizationConservativeStateCreateFlagsEXT',desc='Reserved for future use',type='enums'] 1281-- 1282include::../api/flags/VkPipelineRasterizationConservativeStateCreateFlagsEXT.txt[] 1283 1284sname:VkPipelineRasterizationConservativeStateCreateFlagsEXT is a bitmask 1285type for setting a mask, but is currently reserved for future use. 1286-- 1287 1288[open,refpage='VkConservativeRasterizationModeEXT',desc='Specify the conservative rasterization mode',type='enums'] 1289-- 1290 1291Possible values of 1292slink:VkPipelineRasterizationConservativeStateCreateInfoEXT::pname:conservativeRasterizationMode, 1293specifying the conservative rasterization mode are: 1294 1295include::../api/enums/VkConservativeRasterizationModeEXT.txt[] 1296 1297 * ename:VK_CONSERVATIVE_RASTERIZATION_MODE_DISABLED_EXT specifies that 1298 conservative rasterization is disabled and rasterization proceeds as 1299 normal. 1300 * ename:VK_CONSERVATIVE_RASTERIZATION_MODE_OVERESTIMATE_EXT specifies that 1301 conservative rasterization is enabled in overestimation mode. 1302 * ename:VK_CONSERVATIVE_RASTERIZATION_MODE_UNDERESTIMATE_EXT specifies 1303 that conservative rasterization is enabled in underestimation mode. 1304 1305-- 1306 1307When overestimate conservative rasterization is enabled, rather than 1308evaluating coverage at individual sample locations, a determination is made 1309of whether any portion of the pixel (including its edges and corners) is 1310covered by the primitive. 1311If any portion of the pixel is covered, then all bits of the coverage sample 1312mask for the fragment are enabled. 1313ifdef::VK_EXT_post_depth_coverage[] 1314If the implementation supports 1315sname:VkPhysicalDeviceConservativeRasterizationPropertiesEXT::pname:conservativeRasterizationPostDepthCoverage 1316and the 1317<<shaders-fragment-earlytest-postdepthcoverage,code:PostDepthCoverage>> 1318execution mode is specified the code:SampleMask built-in input variable will 1319reflect the coverage after the early per-fragment depth and stencil tests 1320are applied. 1321endif::VK_EXT_post_depth_coverage[] 1322 1323For the purposes of evaluating which pixels are covered by the primitive, 1324implementations can: increase the size of the primitive by up to 1325sname:VkPhysicalDeviceConservativeRasterizationPropertiesEXT::pname:primitiveOverestimationSize 1326pixels at each of the primitive edges. 1327This may: increase the number of fragments generated by this primitive and 1328represents an overestimation of the pixel coverage. 1329 1330This overestimation size can be increased further by setting the 1331pname:extraPrimitiveOverestimationSize value above `0.0` in steps of 1332sname:VkPhysicalDeviceConservativeRasterizationPropertiesEXT::pname:extraPrimitiveOverestimationSizeGranularity 1333up to and including 1334sname:VkPhysicalDeviceConservativeRasterizationPropertiesEXT::pname:extraPrimitiveOverestimationSize. 1335This will: further increase the number of fragments generated by this 1336primitive. 1337 1338The actual precision of the overestimation size used for conservative 1339rasterization may: vary between implementations and produce results that 1340only approximate the pname:primitiveOverestimationSize and 1341pname:extraPrimitiveOverestimationSizeGranularity properties. 1342 1343For triangles if ename:VK_CONSERVATIVE_RASTERIZATION_MODE_OVERESTIMATE_EXT 1344is enabled, fragments will be generated if the primitive area covers any 1345portion of the pixel, including its edges or corners. 1346The tie-breaking rule described in <<primsrast-polygons-basic, Basic Polygon 1347Rasterization>> does not apply during conservative rasterization and 1348coverage is set for all fragments generated from shared edges of polygons. 1349Degenerate triangles that evaluate to zero area after rasterization, even 1350for pixels that contain a vertex or edge of the zero-area polygon, will be 1351culled if 1352sname:VkPhysicalDeviceConservativeRasterizationPropertiesEXT::pname:degenerateTrianglesRasterized 1353is ename:VK_FALSE or will generate fragments if 1354pname:degenerateTrianglesRasterized is ename:VK_TRUE. 1355The fragment input values for these degenerate triangles take their 1356attribute and depth values from the provoking vertex. 1357Degenerate triangles are considered backfacing and the application can: 1358enable backface culling if desired. 1359Triangles that are zero area before rasterization may: be culled regardless. 1360 1361For lines if ename:VK_CONSERVATIVE_RASTERIZATION_MODE_OVERESTIMATE_EXT is 1362enabled, and the implementation sets 1363sname:VkPhysicalDeviceConservativeRasterizationPropertiesEXT::pname:conservativePointAndLineRasterization 1364to ename:VK_TRUE, fragments will be generated if the line covers any portion 1365of the pixel, including its edges or corners. 1366Degenerate lines that evaluate to zero length after rasterization will be 1367culled if 1368sname:VkPhysicalDeviceConservativeRasterizationPropertiesEXT::pname:degenerateLinesRasterized 1369is ename:VK_FALSE or will generate fragments if 1370pname:degenerateLinesRasterized is ename:VK_TRUE. 1371The fragments input values for these degenerate lines take their attribute 1372and depth values from the provoking vertex. 1373Lines that are zero length before rasterization may: be culled regardless. 1374 1375For points if ename:VK_CONSERVATIVE_RASTERIZATION_MODE_OVERESTIMATE_EXT is 1376enabled, and the implementation sets 1377sname:VkPhysicalDeviceConservativeRasterizationPropertiesEXT::pname:conservativePointAndLineRasterization 1378to ename:VK_TRUE, fragments will be generated if the point square covers any 1379portion of the pixel square, including its edges or corners. 1380 1381When underestimate conservative rasterization is enabled, rather than 1382evaluating coverage at individual sample locations, a determination is made 1383of whether all of the pixel (including its edges and corners) is covered by 1384the primitive. 1385If the entire pixel is covered, then a fragment is generated with all bits 1386of its coverage sample mask enabled, otherwise the fragment is discarded 1387even if some portion of the pixel is covered. 1388ifdef::VK_EXT_post_depth_coverage[] 1389If the implementation supports 1390sname:VkPhysicalDeviceConservativeRasterizationPropertiesEXT::pname:conservativeRasterizationPostDepthCoverage 1391and the 1392<<shaders-fragment-earlytest-postdepthcoverage,code:PostDepthCoverage>> 1393execution mode is specified the code:SampleMask built-in input variable will 1394reflect the coverage after the early per-fragment depth and stencil tests 1395are applied. 1396endif::VK_EXT_post_depth_coverage[] 1397 1398For triangles, if ename:VK_CONSERVATIVE_RASTERIZATION_MODE_UNDERESTIMATE_EXT 1399is enabled, fragments will only be generated if they are fully covered by 1400the generating primitive, including its edges and corners. 1401 1402For lines, if ename:VK_CONSERVATIVE_RASTERIZATION_MODE_UNDERESTIMATE_EXT is 1403enabled, fragments will be generated if the entire pixel, including its 1404edges and corners is covered by the line. 1405 1406For points, if ename:VK_CONSERVATIVE_RASTERIZATION_MODE_UNDERESTIMATE_EXT is 1407enabled, fragments will only be generated for pixel squares that are fully 1408covered by the point square. 1409 1410For both overestimate and underestimate conservative rasterization modes a 1411pixel square that is fully covered by the generating primitive must: set 1412code:FullyCoveredEXT to pname:VK_TRUE if the implementation enables the 1413sname:VkPhysicalDeviceConservativeRasterizationPropertiesEXT::pname:fullyCoveredFragmentShaderInputVariable 1414feature. 1415 1416endif::VK_EXT_conservative_rasterization[] 1417
