1// Copyright 2015-2023 The Khronos Group Inc. 2// 3// SPDX-License-Identifier: CC-BY-4.0 4 5[[vertexpostproc]] 6= Fixed-Function Vertex Post-Processing 7 8After <<pipelines-graphics-subsets-pre-rasterization,pre-rasterization 9shader stages>>, the following fixed-function operations are applied to 10vertices of the resulting primitives: 11 12ifdef::VK_EXT_transform_feedback[] 13 * Transform feedback (see <<vertexpostproc-transform-feedback,Transform 14 Feedback>>) 15endif::VK_EXT_transform_feedback[] 16ifdef::VK_NV_viewport_swizzle[] 17 * Viewport swizzle (see <<vertexpostproc-viewport-swizzle,Viewport 18 Swizzle>>) 19endif::VK_NV_viewport_swizzle[] 20 * Flat shading (see <<vertexpostproc-flatshading>>). 21 * Primitive clipping, including client-defined half-spaces (see 22 <<vertexpostproc-clipping,Primitive Clipping>>). 23 * Shader output attribute clipping (see 24 <<vertexpostproc-clipping-shader-outputs,Clipping Shader Outputs>>). 25ifdef::VK_NV_clip_space_w_scaling[] 26 * Clip space W scaling (see <<vertexpostproc-viewportwscaling,Controlling 27 Viewport W Scaling>>). 28endif::VK_NV_clip_space_w_scaling[] 29 * Perspective division on clip coordinates (see 30 <<vertexpostproc-coord-transform,Coordinate Transformations>>). 31 * Viewport mapping, including depth range scaling (see 32 <<vertexpostproc-viewport,Controlling the Viewport>>). 33 * Front face determination for polygon primitives (see 34 <<primsrast-polygons-basic,Basic Polygon Rasterization>>). 35 36ifdef::editing-notes[] 37[NOTE] 38.editing-note 39==== 40TODO:Odd that this one link to a different chapter is in this list. 41==== 42endif::editing-notes[] 43 44Next, rasterization is performed on primitives as described in chapter 45<<primsrast,Rasterization>>. 46 47 48ifdef::VK_EXT_transform_feedback[] 49[[vertexpostproc-transform-feedback]] 50== Transform Feedback 51 52Before any other fixed-function vertex post-processing, vertex outputs from 53the last shader in the 54<<pipelines-graphics-subsets-pre-rasterization,pre-rasterization shader 55stage>> can: be written out to one or more transform feedback buffers bound 56to the command buffer. 57To capture vertex outputs the last 58<<pipelines-graphics-subsets-pre-rasterization,pre-rasterization shader 59stage>> shader must: be declared with the code:Xfb execution mode. 60Outputs decorated with code:XfbBuffer will be written out to the 61corresponding transform feedback buffers bound to the command buffer when 62transform feedback is active. 63Transform feedback buffers are bound to the command buffer by using 64flink:vkCmdBindTransformFeedbackBuffersEXT. 65Transform feedback is made active by calling 66flink:vkCmdBeginTransformFeedbackEXT and made inactive by calling 67flink:vkCmdEndTransformFeedbackEXT. 68After vertex data is written it is possible to use 69flink:vkCmdDrawIndirectByteCountEXT to start a new draw where the 70pname:vertexCount is derived from the number of bytes written by a previous 71transform feedback. 72 73When an individual point, line, or triangle primitive reaches the transform 74feedback stage while transform feedback is active, the values of the 75specified output variables are assembled into primitives and appended to the 76bound transform feedback buffers. 77After activating transform feedback, the values of the first assembled 78primitive are written at the starting offsets of the bound transform 79feedback buffers, and subsequent primitives are appended to the buffer. 80If the optional pname:pCounterBuffers and pname:pCounterBufferOffsets 81parameters are specified, the starting points within the transform feedback 82buffers are adjusted so data is appended to the previously written values 83indicated by the value stored by the implementation in the counter buffer. 84 85For multi-vertex primitives, all values for a given vertex are written 86before writing values for any other vertex. 87ifdef::VK_EXT_provoking_vertex[] 88When <<features-transformFeedbackPreservesProvokingVertex, 89pname:transformFeedbackPreservesProvokingVertex>> is not enabled, 90implementations 91endif::VK_EXT_provoking_vertex[] 92ifndef::VK_EXT_provoking_vertex[] 93Implementations 94endif::VK_EXT_provoking_vertex[] 95may: write out any vertex within the primitive first, but all subsequent 96vertices for that primitive must: be written out in a consistent winding 97order defined as follows: 98 99 * If neither <<geometry,geometry>> or <<tessellation,tessellation 100 shading>> is active, vertices within a primitive are appended according 101 to the winding order described by the <<drawing-primitive-topologies, 102 primitive topology>> defined by the 103 slink:VkPipelineInputAssemblyStateCreateInfo:pname:topology used to 104 execute the <<drawing,drawing command>>. 105 * If <<geometry,geometry shading>> is active, vertices within a primitive 106 are appended according to the winding order described by the 107 <<drawing-primitive-topologies, primitive topology>> defined by the 108 <<drawing-point-lists, code:OutputPoints>>, <<drawing-line-strips, 109 code:OutputLineStrips>>, or <<drawing-triangle-strips, 110 code:OutputTriangleStrips>> execution mode. 111 * If <<tessellation,tessellation shading>> is active but 112 <<geometry,geometry shading>> is not, vertices within a primitive are 113 appended according to the winding order defined by 114 <<tessellation-triangle-tessellation, triangle tessellation>>, 115 <<tessellation-quad-tessellation, quad tessellation>>, and 116 <<tessellation-isoline-tessellation, isoline tessellation>>. 117 118ifdef::VK_EXT_provoking_vertex[] 119When <<features-transformFeedbackPreservesProvokingVertex, 120pname:transformFeedbackPreservesProvokingVertex>> is enabled, then in 121addition to writing vertices with a consistent winding order, the vertex 122order must: preserve the <<vertexpostproc-flatshading, provoking vertex>> of 123each primitive: 124 125 * When the 126 <<VkPipelineRasterizationProvokingVertexStateCreateInfoEXT,pipeline's 127 provoking vertex mode>> is 128 ename:VK_PROVOKING_VERTEX_MODE_FIRST_VERTEX_EXT, the primitive's 129 provoking vertex must be the first vertex written. 130 * When the 131 <<VkPipelineRasterizationProvokingVertexStateCreateInfoEXT,pipeline's 132 provoking vertex mode>> is 133 ename:VK_PROVOKING_VERTEX_MODE_LAST_VERTEX_EXT, the primitive's 134 provoking vertex must be the last vertex written. 135 136If <<limits-transformFeedbackPreservesTriangleFanProvokingVertex, 137pname:transformFeedbackPreservesTriangleFanProvokingVertex>> is 138ename:VK_FALSE, neither <<geometry, geometry>> nor <<tessellation, 139tessellation>> shading is active, and the <<drawing-primitive-topologies, 140primitive topology>> is ename:VK_PRIMITIVE_TOPOLOGY_TRIANGLE_FAN, then the 141first vertex written from each primitive is implementation-defined even when 142<<features-transformFeedbackPreservesProvokingVertex, 143pname:transformFeedbackPreservesProvokingVertex>> is enabled. 144 145endif::VK_EXT_provoking_vertex[] 146 147When capturing vertices, the stride associated with each transform feedback 148buffer, as indicated by the code:XfbStride decoration, indicates the number 149of bytes of storage reserved for each vertex in the transform feedback 150buffer. 151For every vertex captured, each output attribute with a code:Offset 152decoration will be written to the storage reserved for the vertex at the 153associated transform feedback buffer. 154When writing output variables that are arrays or structures, individual 155array elements or structure members are written tightly packed in order. 156For vector types, individual components are written in order. 157For matrix types, outputs are written as an array of column vectors. 158 159If any component of an output with an assigned transform feedback offset was 160not written to by its shader, the value recorded for that component is 161undefined:. 162All components of an output variable must: be written at an offset aligned 163to the size of the component. 164The size of each component of an output variable must: be at least 32-bits. 165When capturing a vertex, any portion of the reserved storage not associated 166with an output variable with an assigned transform feedback offset will be 167unmodified. 168 169When transform feedback is inactive, no vertices are recorded. 170If there is a valid counter buffer handle and counter buffer offset in the 171pname:pCounterBuffers and pname:pCounterBufferOffsets arrays, writes to the 172corresponding transform feedback buffer will start at the byte offset 173represented by the value stored in the counter buffer location. 174 175Individual lines or triangles of a strip or fan primitive will be extracted 176and recorded separately. 177Incomplete primitives are not recorded. 178 179When using a geometry shader that emits vertices to multiple vertex streams, 180a primitive will be assembled and output for each stream when there are 181enough vertices emitted for the output primitive type. 182All outputs assigned to a given transform feedback buffer are required to 183come from a single vertex stream. 184 185The sizes of the transform feedback buffers are defined by the 186flink:vkCmdBindTransformFeedbackBuffersEXT pname:pSizes parameter for each 187of the bound buffers, or the size of the bound buffer, whichever is the 188lesser. 189If there is less space remaining in any of the transform feedback buffers 190than the size of all of the vertex data for that primitive based on the 191code:XfbStride for that code:XfbBuffer then no vertex data of that primitive 192is recorded in any transform feedback buffer, and the value for the number 193of primitives written in the corresponding 194ename:VK_QUERY_TYPE_TRANSFORM_FEEDBACK_STREAM_EXT query for all transform 195feedback buffers is no longer incremented. 196 197Any outputs made to a code:XfbBuffer that is not bound to a transform 198feedback buffer is ignored. 199 200[open,refpage='vkCmdBindTransformFeedbackBuffersEXT',desc='Bind transform feedback buffers to a command buffer',type='protos'] 201-- 202To bind transform feedback buffers to a command buffer for use in subsequent 203drawing commands, call: 204 205include::{generated}/api/protos/vkCmdBindTransformFeedbackBuffersEXT.adoc[] 206 207 * pname:commandBuffer is the command buffer into which the command is 208 recorded. 209 * pname:firstBinding is the index of the first transform feedback binding 210 whose state is updated by the command. 211 * pname:bindingCount is the number of transform feedback bindings whose 212 state is updated by the command. 213 * pname:pBuffers is a pointer to an array of buffer handles. 214 * pname:pOffsets is a pointer to an array of buffer offsets. 215 * pname:pSizes is `NULL` or a pointer to an array of basetype:VkDeviceSize 216 buffer sizes, specifying the maximum number of bytes to capture to the 217 corresponding transform feedback buffer. 218 If pname:pSizes is `NULL`, or the value of the pname:pSizes array 219 element is ename:VK_WHOLE_SIZE, then the maximum number of bytes 220 captured will be the size of the corresponding buffer minus the buffer 221 offset. 222 223The values taken from elements [eq]#i# of pname:pBuffers, pname:pOffsets and 224pname:pSizes replace the current state for the transform feedback binding 225[eq]#pname:firstBinding {plus} i#, for [eq]#i# in [eq]#[0, 226pname:bindingCount)#. 227The transform feedback binding is updated to start at the offset indicated 228by pname:pOffsets[i] from the start of the buffer pname:pBuffers[i]. 229 230.Valid Usage 231**** 232 * [[VUID-vkCmdBindTransformFeedbackBuffersEXT-transformFeedback-02355]] 233 sname:VkPhysicalDeviceTransformFeedbackFeaturesEXT::pname:transformFeedback 234 must: be enabled 235 * [[VUID-vkCmdBindTransformFeedbackBuffersEXT-firstBinding-02356]] 236 pname:firstBinding must: be less than 237 sname:VkPhysicalDeviceTransformFeedbackPropertiesEXT::pname:maxTransformFeedbackBuffers 238 * [[VUID-vkCmdBindTransformFeedbackBuffersEXT-firstBinding-02357]] 239 The sum of pname:firstBinding and pname:bindingCount must: be less than 240 or equal to 241 sname:VkPhysicalDeviceTransformFeedbackPropertiesEXT::pname:maxTransformFeedbackBuffers 242 * [[VUID-vkCmdBindTransformFeedbackBuffersEXT-pOffsets-02358]] 243 All elements of pname:pOffsets must: be less than the size of the 244 corresponding element in pname:pBuffers 245 * [[VUID-vkCmdBindTransformFeedbackBuffersEXT-pOffsets-02359]] 246 All elements of pname:pOffsets must: be a multiple of 4 247 * [[VUID-vkCmdBindTransformFeedbackBuffersEXT-pBuffers-02360]] 248 All elements of pname:pBuffers must: have been created with the 249 ename:VK_BUFFER_USAGE_TRANSFORM_FEEDBACK_BUFFER_BIT_EXT flag 250 * [[VUID-vkCmdBindTransformFeedbackBuffersEXT-pSize-02361]] 251 If the optional pname:pSize array is specified, each element of 252 pname:pSizes must: either be ename:VK_WHOLE_SIZE, or be less than or 253 equal to 254 sname:VkPhysicalDeviceTransformFeedbackPropertiesEXT::pname:maxTransformFeedbackBufferSize 255 * [[VUID-vkCmdBindTransformFeedbackBuffersEXT-pSizes-02362]] 256 All elements of pname:pSizes must: be either ename:VK_WHOLE_SIZE, or 257 less than or equal to the size of the corresponding buffer in 258 pname:pBuffers 259 * [[VUID-vkCmdBindTransformFeedbackBuffersEXT-pOffsets-02363]] 260 All elements of pname:pOffsets plus pname:pSizes, where the 261 pname:pSizes, element is not ename:VK_WHOLE_SIZE, must: be less than or 262 equal to the size of the corresponding buffer in pname:pBuffers 263 * [[VUID-vkCmdBindTransformFeedbackBuffersEXT-pBuffers-02364]] 264 Each element of pname:pBuffers that is non-sparse must: be bound 265 completely and contiguously to a single sname:VkDeviceMemory object 266 * [[VUID-vkCmdBindTransformFeedbackBuffersEXT-None-02365]] 267 Transform feedback must: not be active when the 268 fname:vkCmdBindTransformFeedbackBuffersEXT command is recorded 269**** 270 271include::{generated}/validity/protos/vkCmdBindTransformFeedbackBuffersEXT.adoc[] 272-- 273 274[open,refpage='vkCmdBeginTransformFeedbackEXT',desc='Make transform feedback active in the command buffer',type='protos'] 275-- 276Transform feedback for specific transform feedback buffers is made active by 277calling: 278 279include::{generated}/api/protos/vkCmdBeginTransformFeedbackEXT.adoc[] 280 281 * pname:commandBuffer is the command buffer into which the command is 282 recorded. 283 * pname:firstCounterBuffer is the index of the first transform feedback 284 buffer corresponding to pname:pCounterBuffers[0] and 285 pname:pCounterBufferOffsets[0]. 286 * pname:counterBufferCount is the size of the pname:pCounterBuffers and 287 pname:pCounterBufferOffsets arrays. 288 * pname:pCounterBuffers is `NULL` or a pointer to an array of 289 slink:VkBuffer handles to counter buffers. 290 Each buffer contains a 4 byte integer value representing the byte offset 291 from the start of the corresponding transform feedback buffer from where 292 to start capturing vertex data. 293 If the byte offset stored to the counter buffer location was done using 294 flink:vkCmdEndTransformFeedbackEXT it can be used to resume transform 295 feedback from the previous location. 296 If pname:pCounterBuffers is `NULL`, then transform feedback will start 297 capturing vertex data to byte offset zero in all bound transform 298 feedback buffers. 299 For each element of pname:pCounterBuffers that is dlink:VK_NULL_HANDLE, 300 transform feedback will start capturing vertex data to byte zero in the 301 corresponding bound transform feedback buffer. 302 * pname:pCounterBufferOffsets is `NULL` or a pointer to an array of 303 basetype:VkDeviceSize values specifying offsets within each of the 304 pname:pCounterBuffers where the counter values were previously written. 305 The location in each counter buffer at these offsets must: be large 306 enough to contain 4 bytes of data. 307 This data is the number of bytes captured by the previous transform 308 feedback to this buffer. 309 If pname:pCounterBufferOffsets is `NULL`, then it is assumed the offsets 310 are zero. 311 312The active transform feedback buffers will capture primitives emitted from 313the corresponding code:XfbBuffer in the bound graphics pipeline. 314Any code:XfbBuffer emitted that does not output to an active transform 315feedback buffer will not be captured. 316 317.Valid Usage 318**** 319 * [[VUID-vkCmdBeginTransformFeedbackEXT-transformFeedback-02366]] 320 sname:VkPhysicalDeviceTransformFeedbackFeaturesEXT::pname:transformFeedback 321 must: be enabled 322 * [[VUID-vkCmdBeginTransformFeedbackEXT-None-02367]] 323 Transform feedback must: not be active 324 * [[VUID-vkCmdBeginTransformFeedbackEXT-firstCounterBuffer-02368]] 325 pname:firstCounterBuffer must: be less than 326 sname:VkPhysicalDeviceTransformFeedbackPropertiesEXT::pname:maxTransformFeedbackBuffers 327 * [[VUID-vkCmdBeginTransformFeedbackEXT-firstCounterBuffer-02369]] 328 The sum of pname:firstCounterBuffer and pname:counterBufferCount must: 329 be less than or equal to 330 sname:VkPhysicalDeviceTransformFeedbackPropertiesEXT::pname:maxTransformFeedbackBuffers 331 * [[VUID-vkCmdBeginTransformFeedbackEXT-counterBufferCount-02607]] 332 If pname:counterBufferCount is not `0`, and pname:pCounterBuffers is not 333 `NULL`, pname:pCounterBuffers must: be a valid pointer to an array of 334 pname:counterBufferCount sname:VkBuffer handles that are either valid or 335 dlink:VK_NULL_HANDLE 336 * [[VUID-vkCmdBeginTransformFeedbackEXT-pCounterBufferOffsets-02370]] 337 For each buffer handle in the array, if it is not dlink:VK_NULL_HANDLE 338 it must: reference a buffer large enough to hold 4 bytes at the 339 corresponding offset from the pname:pCounterBufferOffsets array 340 * [[VUID-vkCmdBeginTransformFeedbackEXT-pCounterBuffer-02371]] 341 If pname:pCounterBuffer is `NULL`, then pname:pCounterBufferOffsets 342 must: also be `NULL` 343 * [[VUID-vkCmdBeginTransformFeedbackEXT-pCounterBuffers-02372]] 344 For each buffer handle in the pname:pCounterBuffers array that is not 345 dlink:VK_NULL_HANDLE it must: have been created with a pname:usage value 346 containing 347 ename:VK_BUFFER_USAGE_TRANSFORM_FEEDBACK_COUNTER_BUFFER_BIT_EXT 348 * [[VUID-vkCmdBeginTransformFeedbackEXT-None-06233]] 349 A valid graphics pipeline must: be bound to 350 ename:VK_PIPELINE_BIND_POINT_GRAPHICS 351 * [[VUID-vkCmdBeginTransformFeedbackEXT-None-04128]] 352 The last 353 <<pipelines-graphics-subsets-pre-rasterization,pre-rasterization shader 354 stage>> of the bound graphics pipeline must: have been declared with the 355 code:Xfb execution mode 356ifdef::VK_VERSION_1_1,VK_KHR_multiview[] 357 * [[VUID-vkCmdBeginTransformFeedbackEXT-None-02373]] 358 Transform feedback must: not be made active in a render pass instance 359 with multiview enabled 360endif::VK_VERSION_1_1,VK_KHR_multiview[] 361**** 362 363include::{generated}/validity/protos/vkCmdBeginTransformFeedbackEXT.adoc[] 364-- 365 366[open,refpage='vkCmdEndTransformFeedbackEXT',desc='Make transform feedback inactive in the command buffer',type='protos'] 367-- 368Transform feedback for specific transform feedback buffers is made inactive 369by calling: 370 371include::{generated}/api/protos/vkCmdEndTransformFeedbackEXT.adoc[] 372 373 * pname:commandBuffer is the command buffer into which the command is 374 recorded. 375 * pname:firstCounterBuffer is the index of the first transform feedback 376 buffer corresponding to pname:pCounterBuffers[0] and 377 pname:pCounterBufferOffsets[0]. 378 * pname:counterBufferCount is the size of the pname:pCounterBuffers and 379 pname:pCounterBufferOffsets arrays. 380 * pname:pCounterBuffers is `NULL` or a pointer to an array of 381 slink:VkBuffer handles to counter buffers. 382 The counter buffers are used to record the current byte positions of 383 each transform feedback buffer where the next vertex output data would 384 be captured. 385 This can: be used by a subsequent flink:vkCmdBeginTransformFeedbackEXT 386 call to resume transform feedback capture from this position. 387 It can also be used by flink:vkCmdDrawIndirectByteCountEXT to determine 388 the vertex count of the draw call. 389 * pname:pCounterBufferOffsets is `NULL` or a pointer to an array of 390 basetype:VkDeviceSize values specifying offsets within each of the 391 pname:pCounterBuffers where the counter values can be written. 392 The location in each counter buffer at these offsets must: be large 393 enough to contain 4 bytes of data. 394 The data stored at this location is the byte offset from the start of 395 the transform feedback buffer binding where the next vertex data would 396 be written. 397 If pname:pCounterBufferOffsets is `NULL`, then it is assumed the offsets 398 are zero. 399 400.Valid Usage 401**** 402 * [[VUID-vkCmdEndTransformFeedbackEXT-transformFeedback-02374]] 403 sname:VkPhysicalDeviceTransformFeedbackFeaturesEXT::pname:transformFeedback 404 must: be enabled 405 * [[VUID-vkCmdEndTransformFeedbackEXT-None-02375]] 406 Transform feedback must: be active 407 * [[VUID-vkCmdEndTransformFeedbackEXT-firstCounterBuffer-02376]] 408 pname:firstCounterBuffer must: be less than 409 sname:VkPhysicalDeviceTransformFeedbackPropertiesEXT::pname:maxTransformFeedbackBuffers 410 * [[VUID-vkCmdEndTransformFeedbackEXT-firstCounterBuffer-02377]] 411 The sum of pname:firstCounterBuffer and pname:counterBufferCount must: 412 be less than or equal to 413 sname:VkPhysicalDeviceTransformFeedbackPropertiesEXT::pname:maxTransformFeedbackBuffers 414 * [[VUID-vkCmdEndTransformFeedbackEXT-counterBufferCount-02608]] 415 If pname:counterBufferCount is not `0`, and pname:pCounterBuffers is not 416 `NULL`, pname:pCounterBuffers must: be a valid pointer to an array of 417 pname:counterBufferCount sname:VkBuffer handles that are either valid or 418 dlink:VK_NULL_HANDLE 419 * [[VUID-vkCmdEndTransformFeedbackEXT-pCounterBufferOffsets-02378]] 420 For each buffer handle in the array, if it is not dlink:VK_NULL_HANDLE 421 it must: reference a buffer large enough to hold 4 bytes at the 422 corresponding offset from the pname:pCounterBufferOffsets array 423 * [[VUID-vkCmdEndTransformFeedbackEXT-pCounterBuffer-02379]] 424 If pname:pCounterBuffer is `NULL`, then pname:pCounterBufferOffsets 425 must: also be `NULL` 426 * [[VUID-vkCmdEndTransformFeedbackEXT-pCounterBuffers-02380]] 427 For each buffer handle in the pname:pCounterBuffers array that is not 428 dlink:VK_NULL_HANDLE it must: have been created with a pname:usage value 429 containing 430 ename:VK_BUFFER_USAGE_TRANSFORM_FEEDBACK_COUNTER_BUFFER_BIT_EXT 431**** 432 433include::{generated}/validity/protos/vkCmdEndTransformFeedbackEXT.adoc[] 434-- 435endif::VK_EXT_transform_feedback[] 436 437 438ifdef::VK_NV_viewport_swizzle[] 439[[vertexpostproc-viewport-swizzle]] 440== Viewport Swizzle 441 442[open,refpage='VkPipelineViewportSwizzleStateCreateInfoNV',desc='Structure specifying swizzle applied to primitive clip coordinates',type='structs'] 443-- 444Each primitive sent to a given viewport has a swizzle and optional: negation 445applied to its clip coordinates. 446The swizzle that is applied depends on the viewport index, and is controlled 447by the sname:VkPipelineViewportSwizzleStateCreateInfoNV pipeline state: 448 449include::{generated}/api/structs/VkPipelineViewportSwizzleStateCreateInfoNV.adoc[] 450 451 * pname:sType is a elink:VkStructureType value identifying this structure. 452 * pname:pNext is `NULL` or a pointer to a structure extending this 453 structure. 454 * pname:flags is reserved for future use. 455 * pname:viewportCount is the number of viewport swizzles used by the 456 pipeline. 457 * pname:pViewportSwizzles is a pointer to an array of 458 slink:VkViewportSwizzleNV structures, defining the viewport swizzles. 459 460.Valid Usage 461**** 462 * [[VUID-VkPipelineViewportSwizzleStateCreateInfoNV-viewportCount-01215]] 463 pname:viewportCount must: be greater than or equal to the 464 pname:viewportCount set in sname:VkPipelineViewportStateCreateInfo 465**** 466 467include::{generated}/validity/structs/VkPipelineViewportSwizzleStateCreateInfoNV.adoc[] 468-- 469 470[open,refpage='VkPipelineViewportSwizzleStateCreateFlagsNV',desc='Reserved for future use',type='flags'] 471-- 472include::{generated}/api/flags/VkPipelineViewportSwizzleStateCreateFlagsNV.adoc[] 473 474tname:VkPipelineViewportSwizzleStateCreateFlagsNV is a bitmask type for 475setting a mask, but is currently reserved for future use. 476-- 477 478The sname:VkPipelineViewportSwizzleStateCreateInfoNV state is set by adding 479this structure to the pname:pNext chain of a 480sname:VkPipelineViewportStateCreateInfo structure and setting the graphics 481pipeline state with flink:vkCreateGraphicsPipelines. 482 483ifdef::VK_EXT_extended_dynamic_state3,VK_EXT_shader_object[] 484 485[open,refpage='vkCmdSetViewportSwizzleNV',desc='Specify the viewport swizzle state dynamically for a command buffer',type='protos'] 486-- 487To <<pipelines-dynamic-state, dynamically set>> the viewport swizzle state, 488call: 489 490include::{generated}/api/protos/vkCmdSetViewportSwizzleNV.adoc[] 491 492 * pname:commandBuffer is the command buffer into which the command will be 493 recorded. 494 * pname:firstViewport is the index of the first viewport whose parameters 495 are updated by the command. 496 * pname:viewportCount is the number of viewports whose parameters are 497 updated by the command. 498 * pname:pViewportSwizzles is a pointer to an array of 499 slink:VkViewportSwizzleNV structures specifying viewport swizzles. 500 501This command sets the viewport swizzle state for subsequent drawing commands 502ifdef::VK_EXT_shader_object[] 503ifdef::VK_EXT_extended_dynamic_state3[when drawing using <<shaders-objects, shader objects>>, or] 504ifndef::VK_EXT_extended_dynamic_state3[when drawing using <<shaders-objects, shader objects>>.] 505endif::VK_EXT_shader_object[] 506ifdef::VK_EXT_extended_dynamic_state3[] 507when the graphics pipeline is created with 508ename:VK_DYNAMIC_STATE_VIEWPORT_SWIZZLE_NV set in 509slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. 510endif::VK_EXT_extended_dynamic_state3[] 511Otherwise, this state is specified by the 512slink:VkPipelineViewportSwizzleStateCreateInfoNV::pname:viewportCount, and 513slink:VkPipelineViewportSwizzleStateCreateInfoNV::pname:pViewportSwizzles 514values used to create the currently active pipeline. 515 516:refpage: vkCmdSetViewportSwizzleNV 517:requiredfeature: extendedDynamicState3ViewportSwizzle 518 519.Valid Usage 520**** 521include::{chapters}/commonvalidity/dynamic_state3_feature_common.adoc[] 522**** 523 524include::{generated}/validity/protos/vkCmdSetViewportSwizzleNV.adoc[] 525-- 526 527endif::VK_EXT_extended_dynamic_state3,VK_EXT_shader_object[] 528 529Each viewport specified from 0 to pname:viewportCount - 1 has its x,y,z,w 530swizzle state set to the corresponding pname:x, pname:y, pname:z and pname:w 531in the slink:VkViewportSwizzleNV structure. 532Each component is of type elink:VkViewportCoordinateSwizzleNV, which 533determines the type of swizzle for that component. 534The value of pname:x computes the new x component of the position as: 535 536[source,c] 537---- 538if (x == VK_VIEWPORT_COORDINATE_SWIZZLE_POSITIVE_X_NV) x' = x; 539if (x == VK_VIEWPORT_COORDINATE_SWIZZLE_NEGATIVE_X_NV) x' = -x; 540if (x == VK_VIEWPORT_COORDINATE_SWIZZLE_POSITIVE_Y_NV) x' = y; 541if (x == VK_VIEWPORT_COORDINATE_SWIZZLE_NEGATIVE_Y_NV) x' = -y; 542if (x == VK_VIEWPORT_COORDINATE_SWIZZLE_POSITIVE_Z_NV) x' = z; 543if (x == VK_VIEWPORT_COORDINATE_SWIZZLE_NEGATIVE_Z_NV) x' = -z; 544if (x == VK_VIEWPORT_COORDINATE_SWIZZLE_POSITIVE_W_NV) x' = w; 545if (x == VK_VIEWPORT_COORDINATE_SWIZZLE_NEGATIVE_W_NV) x' = -w; 546---- 547 548Similar selections are performed for the pname:y, pname:z, and pname:w 549coordinates. 550This swizzling is applied before clipping and perspective divide. 551If the swizzle for an active viewport index is not specified, the swizzle 552for pname:x is ename:VK_VIEWPORT_COORDINATE_SWIZZLE_POSITIVE_X_NV, pname:y 553is ename:VK_VIEWPORT_COORDINATE_SWIZZLE_POSITIVE_Y_NV, pname:z is 554ename:VK_VIEWPORT_COORDINATE_SWIZZLE_POSITIVE_Z_NV and pname:w is 555ename:VK_VIEWPORT_COORDINATE_SWIZZLE_POSITIVE_W_NV. 556 557Viewport swizzle parameters are specified by setting the pname:pNext pointer 558of sname:VkGraphicsPipelineCreateInfo to point to a 559sname:VkPipelineViewportSwizzleStateCreateInfoNV structure. 560slink:VkPipelineViewportSwizzleStateCreateInfoNV uses 561sname:VkViewportSwizzleNV to set the viewport swizzle parameters. 562 563[open,refpage='VkViewportSwizzleNV',desc='Structure specifying a viewport swizzle',type='structs'] 564-- 565The sname:VkViewportSwizzleNV structure is defined as: 566 567include::{generated}/api/structs/VkViewportSwizzleNV.adoc[] 568 569 * pname:x is a elink:VkViewportCoordinateSwizzleNV value specifying the 570 swizzle operation to apply to the x component of the primitive 571 * pname:y is a elink:VkViewportCoordinateSwizzleNV value specifying the 572 swizzle operation to apply to the y component of the primitive 573 * pname:z is a elink:VkViewportCoordinateSwizzleNV value specifying the 574 swizzle operation to apply to the z component of the primitive 575 * pname:w is a elink:VkViewportCoordinateSwizzleNV value specifying the 576 swizzle operation to apply to the w component of the primitive 577 578include::{generated}/validity/structs/VkViewportSwizzleNV.adoc[] 579-- 580 581[open,refpage='VkViewportCoordinateSwizzleNV',desc='Specify how a viewport coordinate is swizzled',type='enums'] 582-- 583Possible values of the slink:VkViewportSwizzleNV::pname:x, pname:y, pname:z, 584and pname:w members, specifying swizzling of the corresponding components of 585primitives, are: 586 587include::{generated}/api/enums/VkViewportCoordinateSwizzleNV.adoc[] 588 589These values are described in detail in <<vertexpostproc-viewport-swizzle, 590Viewport Swizzle>>. 591-- 592endif::VK_NV_viewport_swizzle[] 593 594 595[[vertexpostproc-flatshading]] 596== Flat Shading 597 598_Flat shading_ a vertex output attribute means to assign all vertices of the 599primitive the same value for that output. 600The output values assigned are those of the _provoking vertex_ of the 601primitive. 602Flat shading is applied to those vertex attributes that 603<<interfaces-iointerfaces-matching,match>> fragment input attributes which 604are decorated as code:Flat. 605 606If neither 607ifdef::VK_EXT_mesh_shader,VK_NV_mesh_shader[] 608<<mesh, mesh>>, 609endif::VK_EXT_mesh_shader,VK_NV_mesh_shader[] 610<<geometry,geometry>> nor <<tessellation,tessellation shading>> is active, 611the provoking vertex is determined by the <<drawing-primitive-topologies, 612primitive topology>> defined by 613slink:VkPipelineInputAssemblyStateCreateInfo:pname:topology used to execute 614the <<drawing,drawing command>>. 615 616ifdef::VK_NV_mesh_shader[] 617If a shader using code:MeshNV {ExecutionModel} is active, the provoking 618vertex is determined by the <<drawing-primitive-topologies, primitive 619topology>> defined by the <<drawing-point-lists, code:OutputPoints>>, 620<<drawing-line-lists, code:OutputLinesNV>>, or <<drawing-triangle-lists, 621code:OutputTrianglesNV>> execution mode. 622endif::VK_NV_mesh_shader[] 623 624ifdef::VK_EXT_mesh_shader[] 625If a shader using code:MeshEXT {ExecutionModel} is active, the provoking 626vertex is determined by the <<drawing-primitive-topologies, primitive 627topology>> defined by the <<drawing-point-lists, code:OutputPoints>>, 628<<drawing-line-lists, code:OutputLinesEXT>>, or <<drawing-triangle-lists, 629code:OutputTrianglesEXT>> execution mode. 630endif::VK_EXT_mesh_shader[] 631 632If <<geometry,geometry shading>> is active, the provoking vertex is 633determined by the <<drawing-primitive-topologies, primitive topology>> 634defined by the <<drawing-point-lists, code:OutputPoints>>, 635<<drawing-line-strips, code:OutputLineStrips>>, or 636<<drawing-triangle-strips, code:OutputTriangleStrips>> execution mode. 637 638If <<tessellation,tessellation shading>> is active but <<geometry,geometry 639shading>> is not, the provoking vertex may: be any of the vertices in each 640primitive. 641 642ifdef::VK_EXT_provoking_vertex[] 643[open,refpage='VkPipelineRasterizationProvokingVertexStateCreateInfoEXT',desc='Structure specifying provoking vertex mode used by a graphics pipeline',type='structs'] 644-- 645For a given primitive topology, the pipeline's provoking vertex mode 646determines which vertex is the provoking vertex. 647To specify the provoking vertex mode, include a 648sname:VkPipelineRasterizationProvokingVertexStateCreateInfoEXT structure in 649the slink:VkPipelineRasterizationStateCreateInfo::pname:pNext chain when 650creating the pipeline. 651 652The sname:VkPipelineRasterizationProvokingVertexStateCreateInfoEXT structure 653is defined as: 654 655include::{generated}/api/structs/VkPipelineRasterizationProvokingVertexStateCreateInfoEXT.adoc[] 656 657 * pname:sType is a elink:VkStructureType value identifying this structure. 658 * pname:pNext is `NULL` or a pointer to a structure extending this 659 structure. 660 * pname:provokingVertexMode is a elink:VkProvokingVertexModeEXT value 661 selecting the provoking vertex mode. 662 663If this struct is not provided when creating the pipeline, the pipeline will 664use the ename:VK_PROVOKING_VERTEX_MODE_FIRST_VERTEX_EXT mode. 665 666If the <<limits-provokingVertexModePerPipeline, 667pname:provokingVertexModePerPipeline>> limit is ename:VK_FALSE, then all 668pipelines bound within a render pass instance must: have the same 669pname:provokingVertexMode. 670 671.Valid Usage 672**** 673 * [[VUID-VkPipelineRasterizationProvokingVertexStateCreateInfoEXT-provokingVertexMode-04883]] 674 If pname:provokingVertexMode is 675 ename:VK_PROVOKING_VERTEX_MODE_LAST_VERTEX_EXT, then the 676 <<features-provokingVertexLast, pname:provokingVertexLast>> feature 677 must: be enabled 678**** 679 680include::{generated}/validity/structs/VkPipelineRasterizationProvokingVertexStateCreateInfoEXT.adoc[] 681-- 682 683[open,refpage='VkProvokingVertexModeEXT',desc='Specify which vertex in a primitive is the provoking vertex',type='enums'] 684-- 685Possible values of 686slink:VkPipelineRasterizationProvokingVertexStateCreateInfoEXT::pname:provokingVertexMode 687are: 688 689include::{generated}/api/enums/VkProvokingVertexModeEXT.adoc[] 690 691 * ename:VK_PROVOKING_VERTEX_MODE_FIRST_VERTEX_EXT specifies that the 692 provoking vertex is the first non-adjacency vertex in the list of 693 vertices used by a primitive. 694 * ename:VK_PROVOKING_VERTEX_MODE_LAST_VERTEX_EXT specifies that the 695 provoking vertex is the last non-adjacency vertex in the list of 696 vertices used by a primitive. 697 698These modes are described more precisely in 699<<drawing-primitive-topologies,Primitive Topologies>>. 700-- 701 702ifdef::VK_EXT_extended_dynamic_state3,VK_EXT_shader_object[] 703 704[open,refpage='vkCmdSetProvokingVertexModeEXT',desc='Specify the provoking vertex mode dynamically for a command buffer',type='protos'] 705-- 706To <<pipelines-dynamic-state, dynamically set>> the 707pname:provokingVertexMode state, call: 708 709include::{generated}/api/protos/vkCmdSetProvokingVertexModeEXT.adoc[] 710 711 * pname:commandBuffer is the command buffer into which the command will be 712 recorded. 713 * pname:provokingVertexMode specifies the pname:provokingVertexMode state. 714 715This command sets the pname:provokingVertexMode state for subsequent drawing 716commands 717ifdef::VK_EXT_shader_object[] 718ifdef::VK_EXT_extended_dynamic_state3[when drawing using <<shaders-objects, shader objects>>, or] 719ifndef::VK_EXT_extended_dynamic_state3[when drawing using <<shaders-objects, shader objects>>.] 720endif::VK_EXT_shader_object[] 721ifdef::VK_EXT_extended_dynamic_state3[] 722when the graphics pipeline is created with 723ename:VK_DYNAMIC_STATE_PROVOKING_VERTEX_MODE_EXT set in 724slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. 725endif::VK_EXT_extended_dynamic_state3[] 726Otherwise, this state is specified by the 727slink:VkPipelineRasterizationProvokingVertexStateCreateInfoEXT::pname:provokingVertexMode 728value used to create the currently active pipeline. 729 730:refpage: vkCmdSetProvokingVertexModeEXT 731:requiredfeature: extendedDynamicState3ProvokingVertexMode 732 733.Valid Usage 734**** 735include::{chapters}/commonvalidity/dynamic_state3_feature_common.adoc[] 736 * [[VUID-vkCmdSetProvokingVertexModeEXT-provokingVertexMode-07447]] 737 If pname:provokingVertexMode is 738 ename:VK_PROVOKING_VERTEX_MODE_LAST_VERTEX_EXT, then the 739 <<features-provokingVertexLast, pname:provokingVertexLast>> feature 740 must: be enabled 741**** 742 743include::{generated}/validity/protos/vkCmdSetProvokingVertexModeEXT.adoc[] 744-- 745 746endif::VK_EXT_extended_dynamic_state3,VK_EXT_shader_object[] 747 748endif::VK_EXT_provoking_vertex[] 749 750 751[[vertexpostproc-clipping]] 752== Primitive Clipping 753 754Primitives are culled against the _cull volume_ and then clipped to the 755_clip volume_. 756In clip coordinates, the _view volume_ is defined by: 757 758[latexmath] 759++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 760\begin{array}{c} 761-w_c \leq x_c \leq w_c \\ 762-w_c \leq y_c \leq w_c \\ 763z_m \leq z_c \leq w_c 764\end{array} 765++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 766 767where 768ifdef::VK_EXT_depth_clip_control[] 769if 770slink:VkPipelineViewportDepthClipControlCreateInfoEXT::pname:negativeOneToOne 771is ename:VK_TRUE [eq]#z~m~# is equal to [eq]#-w~c~# otherwise 772endif::VK_EXT_depth_clip_control[] 773[eq]#z~m~# is equal to zero. 774 775This view volume can: be further restricted by as many as 776sname:VkPhysicalDeviceLimits::pname:maxClipDistances client-defined 777half-spaces. 778 779The cull volume is the intersection of up to 780sname:VkPhysicalDeviceLimits::pname:maxCullDistances client-defined 781half-spaces (if no client-defined cull half-spaces are enabled, culling 782against the cull volume is skipped). 783 784A shader must: write a single cull distance for each enabled cull half-space 785to elements of the code:CullDistance array. 786If the cull distance for any enabled cull half-space is negative for all of 787the vertices of the primitive under consideration, the primitive is 788discarded. 789Otherwise the primitive is clipped against the clip volume as defined below. 790 791The clip volume is the intersection of up to 792sname:VkPhysicalDeviceLimits::pname:maxClipDistances client-defined 793half-spaces with the view volume (if no client-defined clip half-spaces are 794enabled, the clip volume is the view volume). 795 796A shader must: write a single clip distance for each enabled clip half-space 797to elements of the code:ClipDistance array. 798Clip half-space [eq]#i# is then given by the set of points satisfying the 799inequality 800 801 {empty}:: [eq]#c~i~(**P**) {geq} 0# 802 803where [eq]#c~i~(**P**)# is the clip distance [eq]#i# at point [eq]#**P**#. 804For point primitives, [eq]#c~i~(**P**)# is simply the clip distance for the 805vertex in question. 806For line and triangle primitives, per-vertex clip distances are interpolated 807using a weighted mean, with weights derived according to the algorithms 808described in sections <<primsrast-lines-basic,Basic Line Segment 809Rasterization>> and <<primsrast-polygons-basic,Basic Polygon 810Rasterization>>, using the perspective interpolation equations. 811 812The number of client-defined clip and cull half-spaces that are enabled is 813determined by the explicit size of the built-in arrays code:ClipDistance and 814code:CullDistance, respectively, declared as an output in the interface of 815the entry point of the final shader stage before clipping. 816 817ifdef::VK_EXT_depth_clip_enable[] 818If slink:VkPipelineRasterizationDepthClipStateCreateInfoEXT is present in 819the graphics pipeline state then depth clipping is disabled if 820slink:VkPipelineRasterizationDepthClipStateCreateInfoEXT::pname:depthClipEnable 821is ename:VK_FALSE. 822Otherwise, if slink:VkPipelineRasterizationDepthClipStateCreateInfoEXT is 823not present, depth clipping is disabled when 824slink:VkPipelineRasterizationStateCreateInfo::pname:depthClampEnable is 825ename:VK_TRUE. 826endif::VK_EXT_depth_clip_enable[] 827ifndef::VK_EXT_depth_clip_enable[] 828Depth clamping is enabled or disabled via the pname:depthClampEnable enable 829of the slink:VkPipelineRasterizationStateCreateInfo structure. 830Depth clipping is disabled when pname:depthClampEnable is ename:VK_TRUE. 831endif::VK_EXT_depth_clip_enable[] 832 833ifdef::VK_EXT_extended_dynamic_state3,VK_EXT_shader_object[] 834 835[open,refpage='vkCmdSetDepthClampEnableEXT',desc='Specify dynamically whether depth clamping is enabled in the command buffer',type='protos'] 836-- 837To <<pipelines-dynamic-state, dynamically set>> enable or disable depth 838clamping, call: 839 840include::{generated}/api/protos/vkCmdSetDepthClampEnableEXT.adoc[] 841 842 * pname:commandBuffer is the command buffer into which the command will be 843 recorded. 844 * pname:depthClampEnable specifies whether depth clamping is enabled. 845 846This command sets whether depth clamping is enabled or disabled for 847subsequent drawing commands 848ifdef::VK_EXT_shader_object[] 849ifdef::VK_EXT_extended_dynamic_state3[when drawing using <<shaders-objects, shader objects>>, or] 850ifndef::VK_EXT_extended_dynamic_state3[when drawing using <<shaders-objects, shader objects>>.] 851endif::VK_EXT_shader_object[] 852ifdef::VK_EXT_extended_dynamic_state3[] 853when the graphics pipeline is created with 854ename:VK_DYNAMIC_STATE_DEPTH_CLAMP_ENABLE_EXT set in 855slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. 856endif::VK_EXT_extended_dynamic_state3[] 857Otherwise, this state is specified by the 858slink:VkPipelineRasterizationStateCreateInfo::pname:depthClampEnable value 859used to create the currently active pipeline. 860 861If the depth clamping state is changed dynamically, and the pipeline was not 862created with ename:VK_DYNAMIC_STATE_DEPTH_CLIP_ENABLE_EXT enabled, then 863depth clipping is enabled when depth clamping is disabled and vice versa. 864 865:refpage: vkCmdSetDepthClampEnableEXT 866:requiredfeature: extendedDynamicState3DepthClampEnable 867 868.Valid Usage 869**** 870include::{chapters}/commonvalidity/dynamic_state3_feature_common.adoc[] 871 * [[VUID-vkCmdSetDepthClampEnableEXT-depthClamp-07449]] 872 If the <<features-depthClamp, pname:depthClamp>> feature is not enabled, 873 pname:depthClampEnable must be ename:VK_FALSE 874**** 875 876include::{generated}/validity/protos/vkCmdSetDepthClampEnableEXT.adoc[] 877-- 878 879ifdef::VK_EXT_depth_clip_enable[] 880[open,refpage='vkCmdSetDepthClipEnableEXT',desc='Specify dynamically whether depth clipping is enabled in the command buffer',type='protos'] 881-- 882To <<pipelines-dynamic-state, dynamically set>> enable or disable depth 883clipping, call: 884 885include::{generated}/api/protos/vkCmdSetDepthClipEnableEXT.adoc[] 886 887 * pname:commandBuffer is the command buffer into which the command will be 888 recorded. 889 * pname:depthClipEnable specifies whether depth clipping is enabled. 890 891This command sets whether depth clipping is enabled or disabled for 892subsequent drawing commands 893ifdef::VK_EXT_shader_object[] 894ifdef::VK_EXT_extended_dynamic_state3[when drawing using <<shaders-objects, shader objects>>, or] 895ifndef::VK_EXT_extended_dynamic_state3[when drawing using <<shaders-objects, shader objects>>.] 896endif::VK_EXT_shader_object[] 897ifdef::VK_EXT_extended_dynamic_state3[] 898when the graphics pipeline is created with 899ename:VK_DYNAMIC_STATE_DEPTH_CLIP_ENABLE_EXT set in 900slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. 901endif::VK_EXT_extended_dynamic_state3[] 902Otherwise, this state is specified by the 903slink:VkPipelineRasterizationDepthClipStateCreateInfoEXT::pname:depthClipEnable 904value used to create the currently active pipeline, or is set to the inverse 905of slink:VkPipelineRasterizationStateCreateInfo::pname:depthClampEnable if 906sname:VkPipelineRasterizationDepthClipStateCreateInfoEXT is not specified. 907 908:refpage: vkCmdSetDepthClipEnableEXT 909:requiredfeature: extendedDynamicState3DepthClipEnable 910 911.Valid Usage 912**** 913include::{chapters}/commonvalidity/dynamic_state3_feature_common.adoc[] 914 * [[VUID-vkCmdSetDepthClipEnableEXT-depthClipEnable-07451]] 915 The <<features-depthClipEnable, pname:depthClipEnable>> feature must: be 916 enabled 917**** 918 919include::{generated}/validity/protos/vkCmdSetDepthClipEnableEXT.adoc[] 920-- 921endif::VK_EXT_depth_clip_enable[] 922 923endif::VK_EXT_extended_dynamic_state3,VK_EXT_shader_object[] 924 925When depth clipping is disabled, the plane equation 926 927 {empty}:: [eq]#z~m~ {leq} z~c~ {leq} w~c~# 928 929(see the clip volume definition above) is ignored by view volume clipping 930(effectively, there is no near or far plane clipping). 931 932If the primitive under consideration is a point or line segment, then 933clipping passes it unchanged if its vertices lie entirely within the clip 934volume. 935 936ifndef::VK_VERSION_1_1,VK_KHR_maintenance2[] 937If a point's vertex lies outside of the clip volume, the entire primitive 938may: be discarded. 939endif::VK_VERSION_1_1,VK_KHR_maintenance2[] 940 941ifdef::VK_VERSION_1_1,VK_KHR_maintenance2[] 942[open,refpage='VkPointClippingBehavior',desc='Enum specifying the point clipping behavior',type='enums'] 943-- 944Possible values of 945slink:VkPhysicalDevicePointClippingProperties::pname:pointClippingBehavior, 946specifying clipping behavior of a point primitive whose vertex lies outside 947the clip volume, are: 948 949include::{generated}/api/enums/VkPointClippingBehavior.adoc[] 950 951ifdef::VK_KHR_maintenance2[] 952or the equivalent 953 954include::{generated}/api/enums/VkPointClippingBehaviorKHR.adoc[] 955endif::VK_KHR_maintenance2[] 956 957 * ename:VK_POINT_CLIPPING_BEHAVIOR_ALL_CLIP_PLANES specifies that the 958 primitive is discarded if the vertex lies outside any clip plane, 959 including the planes bounding the view volume. 960 * ename:VK_POINT_CLIPPING_BEHAVIOR_USER_CLIP_PLANES_ONLY specifies that 961 the primitive is discarded only if the vertex lies outside any user clip 962 plane. 963-- 964endif::VK_VERSION_1_1,VK_KHR_maintenance2[] 965 966If either of a line segment's vertices lie outside of the clip volume, the 967line segment may: be clipped, with new vertex coordinates computed for each 968vertex that lies outside the clip volume. 969A clipped line segment endpoint lies on both the original line segment and 970the boundary of the clip volume. 971 972This clipping produces a value, [eq]#0 {leq} t {leq} 1#, for each clipped 973vertex. 974If the coordinates of a clipped vertex are [eq]#**P**# and the unclipped 975line segment's vertex coordinates are [eq]#**P**~1~# and [eq]#**P**~2~#, 976then [eq]#t# satisfies the following equation 977 978 {empty}:: [eq]#**P** = t **P**~1~ {plus} (1-t) **P**~2~#. 979 980[eq]#t# is used to clip vertex output attributes as described in 981<<vertexpostproc-clipping-shader-outputs,Clipping Shader Outputs>>. 982 983If the primitive is a polygon, it passes unchanged if every one of its edges 984lies entirely inside the clip volume, and is either clipped or discarded 985otherwise. 986If the edges of the polygon intersect the boundary of the clip volume, the 987intersecting edges are reconnected by new edges that lie along the boundary 988of the clip volume - in some cases requiring the introduction of new 989vertices into a polygon. 990 991If a polygon intersects an edge of the clip volume's boundary, the clipped 992polygon must: include a point on this boundary edge. 993 994Primitives rendered with user-defined half-spaces must: satisfy a 995complementarity criterion. 996Suppose a series of primitives is drawn where each vertex [eq]#i# has a 997single specified clip distance [eq]#d~i~# (or a number of similarly 998specified clip distances, if multiple half-spaces are enabled). 999Next, suppose that the same series of primitives are drawn again with each 1000such clip distance replaced by [eq]#-d~i~# (and the graphics pipeline is 1001otherwise the same). 1002In this case, primitives must: not be missing any pixels, and pixels must: 1003not be drawn twice in regions where those primitives are cut by the clip 1004planes. 1005 1006ifdef::VK_EXT_depth_clip_control[] 1007[open,refpage='VkPipelineViewportDepthClipControlCreateInfoEXT',desc='Structure specifying parameters of a newly created pipeline depth clip control state',type='structs'] 1008-- 1009The sname:VkPipelineViewportDepthClipControlCreateInfoEXT structure is 1010defined as: 1011 1012include::{generated}/api/structs/VkPipelineViewportDepthClipControlCreateInfoEXT.adoc[] 1013 1014 * pname:sType is a elink:VkStructureType value identifying this structure. 1015 * pname:pNext is `NULL` or a pointer to a structure extending this 1016 structure. 1017 * pname:negativeOneToOne sets the [eq]#z~m~# in the _view volume_ to 1018 [eq]#-w~c~# 1019 1020.Valid Usage 1021**** 1022 * [[VUID-VkPipelineViewportDepthClipControlCreateInfoEXT-negativeOneToOne-06470]] 1023 If <<features-depthClipControl, pname:depthClipControl>> is not enabled, 1024 pname:negativeOneToOne must: be ename:VK_FALSE 1025**** 1026 1027include::{generated}/validity/structs/VkPipelineViewportDepthClipControlCreateInfoEXT.adoc[] 1028-- 1029 1030ifdef::VK_EXT_extended_dynamic_state3,VK_EXT_shader_object[] 1031[open,refpage='vkCmdSetDepthClipNegativeOneToOneEXT',desc='Specify the negative one to one depth clip mode dynamically for a command buffer',type='protos'] 1032-- 1033To <<pipelines-dynamic-state, dynamically set>> pname:negativeOneToOne, 1034call: 1035 1036include::{generated}/api/protos/vkCmdSetDepthClipNegativeOneToOneEXT.adoc[] 1037 1038 * pname:commandBuffer is the command buffer into which the command will be 1039 recorded. 1040 * pname:negativeOneToOne specifies the pname:negativeOneToOne state. 1041 1042This command sets the pname:negativeOneToOne state for subsequent drawing 1043commands 1044ifdef::VK_EXT_shader_object[] 1045ifdef::VK_EXT_extended_dynamic_state3[when drawing using <<shaders-objects, shader objects>>, or] 1046ifndef::VK_EXT_extended_dynamic_state3[when drawing using <<shaders-objects, shader objects>>.] 1047endif::VK_EXT_shader_object[] 1048ifdef::VK_EXT_extended_dynamic_state3[] 1049when the graphics pipeline is created with 1050ename:VK_DYNAMIC_STATE_DEPTH_CLIP_NEGATIVE_ONE_TO_ONE_EXT set in 1051slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. 1052endif::VK_EXT_extended_dynamic_state3[] 1053Otherwise, this state is specified by the 1054slink:VkPipelineViewportDepthClipControlCreateInfoEXT::pname:negativeOneToOne 1055value used to create the currently active pipeline. 1056 1057:refpage: vkCmdSetDepthClipNegativeOneToOneEXT 1058:requiredfeature: extendedDynamicState3DepthClipNegativeOneToOne 1059 1060.Valid Usage 1061**** 1062include::{chapters}/commonvalidity/dynamic_state3_feature_common.adoc[] 1063 * [[VUID-vkCmdSetDepthClipNegativeOneToOneEXT-depthClipControl-07453]] 1064 The <<features-depthClipControl, pname:depthClipControl>> feature must: 1065 be enabled 1066**** 1067 1068include::{generated}/validity/protos/vkCmdSetDepthClipNegativeOneToOneEXT.adoc[] 1069-- 1070endif::VK_EXT_extended_dynamic_state3,VK_EXT_shader_object[] 1071endif::VK_EXT_depth_clip_control[] 1072 1073 1074[[vertexpostproc-clipping-shader-outputs]] 1075== Clipping Shader Outputs 1076 1077Next, vertex output attributes are clipped. 1078The output values associated with a vertex that lies within the clip volume 1079are unaffected by clipping. 1080If a primitive is clipped, however, the output values assigned to vertices 1081produced by clipping are clipped. 1082 1083Let the output values assigned to the two vertices [eq]#**P**~1~# and 1084[eq]#**P**~2~# of an unclipped edge be [eq]#**c**~1~# and [eq]#**c**~2~#. 1085The value of [eq]#t# (see <<vertexpostproc-clipping,Primitive Clipping>>) 1086for a clipped point [eq]#**P**# is used to obtain the output value 1087associated with [eq]#**P**# as 1088 1089 {empty}:: [eq]#**c** = t **c**~1~ {plus} (1-t) **c**~2~#. 1090 1091(Multiplying an output value by a scalar means multiplying each of _x_, _y_, 1092_z_, and _w_ by the scalar.) 1093 1094Since this computation is performed in clip space before division by 1095[eq]#w~c~#, clipped output values are perspective-correct. 1096 1097Polygon clipping creates a clipped vertex along an edge of the clip volume's 1098boundary. 1099This situation is handled by noting that polygon clipping proceeds by 1100clipping against one half-space at a time. 1101Output value clipping is done in the same way, so that clipped points always 1102occur at the intersection of polygon edges (possibly already clipped) with 1103the clip volume's boundary. 1104 1105For vertex output attributes whose matching fragment input attributes are 1106decorated with code:NoPerspective, the value of [eq]#t# used to obtain the 1107output value associated with [eq]#**P**# will be adjusted to produce results 1108that vary linearly in framebuffer space. 1109 1110Output attributes of integer or unsigned integer type must: always be flat 1111shaded. 1112Flat shaded attributes are constant over the primitive being rasterized (see 1113<<primsrast-lines-basic,Basic Line Segment Rasterization>> and 1114<<primsrast-polygons-basic,Basic Polygon Rasterization>>), and no 1115interpolation is performed. 1116The output value [eq]#**c**# is taken from either [eq]#**c**~1~# or 1117[eq]#**c**~2~#, since flat shading has already occurred and the two values 1118are identical. 1119 1120ifdef::VK_NV_clip_space_w_scaling[] 1121include::{chapters}/VK_NV_clip_space_w_scaling/vertexpostproc.adoc[] 1122endif::VK_NV_clip_space_w_scaling[] 1123 1124 1125[[vertexpostproc-coord-transform]] 1126== Coordinate Transformations 1127 1128_Clip coordinates_ for a vertex result from shader execution, which yields a 1129vertex coordinate code:Position. 1130 1131Perspective division on clip coordinates yields _normalized device 1132coordinates_, followed by a _viewport_ transformation (see 1133<<vertexpostproc-viewport,Controlling the Viewport>>) to convert these 1134coordinates into _framebuffer coordinates_. 1135 1136If a vertex in clip coordinates has a position given by 1137 1138[latexmath] 1139++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1140\left(\begin{array}{c} 1141x_c \\ 1142y_c \\ 1143z_c \\ 1144w_c 1145\end{array}\right) 1146++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1147 1148then the vertex's normalized device coordinates are 1149[latexmath] 1150++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1151\left( 1152 \begin{array}{c} 1153 x_d \\ 1154 y_d \\ 1155 z_d 1156 \end{array} 1157\right) = 1158\left( 1159 \begin{array}{c} 1160 \frac{x_c}{w_c} \\ 1161 \frac{y_c}{w_c} \\ 1162 \frac{z_c}{w_c} 1163 \end{array} 1164\right) 1165++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1166 1167 1168ifdef::VK_QCOM_render_pass_transform[] 1169[[vertexpostproc-renderpass-transform]] 1170== Render Pass Transform 1171 1172A _render pass transform_ can: be enabled for render pass instances. 1173The clip coordinates [eq]#(x~c~, y~c~)# that result from vertex shader 1174execution are transformed by a rotation of 0, 90, 180, or 270 degrees in the 1175XY plane, centered at the origin. 1176 1177When _Render pass transform_ is enabled, the transform applies to all 1178primitives for all subpasses of the render pass. 1179The transformed vertex in clip coordinates has a position given by 1180 1181[latexmath] 1182++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1183\left( 1184 \begin{array}{c} 1185 x_{c_{trans}} \\ 1186 y_{c_{trans}} \\ 1187 z_{c_{trans}} 1188 \end{array} 1189\right) = 1190\left( 1191 \begin{array}{c} 1192 x_{c} \cos \theta - y_{c} \sin \theta \\ 1193 x_{c} \sin \theta + y_{c} \cos \theta \\ 1194 z_c 1195 \end{array} 1196\right) 1197++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1198 1199where 1200 1201 * _[eq]#{theta}#_ is 0 degrees for 1202 ename:VK_SURFACE_TRANSFORM_IDENTITY_BIT_KHR 1203 * _[eq]#{theta}#_ is 90 degrees for 1204 ename:VK_SURFACE_TRANSFORM_ROTATE_90_BIT_KHR 1205 * _[eq]#{theta}#_ is 180 degrees for 1206 ename:VK_SURFACE_TRANSFORM_ROTATE_180_BIT_KHR 1207 * _[eq]#{theta}#_ is 270 degrees for 1208 ename:VK_SURFACE_TRANSFORM_ROTATE_270_BIT_KHR 1209 1210 1211The transformed vertex's normalized device coordinates are 1212[latexmath] 1213++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1214\left( 1215 \begin{array}{c} 1216 x_d \\ 1217 y_d \\ 1218 z_d 1219 \end{array} 1220\right) = 1221\left( 1222 \begin{array}{c} 1223 \frac{x_{c_{trans}}}{w_c} \\ 1224 \frac{y_{c_{trans}}}{w_c} \\ 1225 \frac{z_{c_{trans}}}{w_c} 1226 \end{array} 1227\right) 1228++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1229 1230 1231When render pass transform is enabled for a render pass instance, the 1232following additional features are enabled: 1233 1234 * Each slink:VkViewport specified by either 1235 slink:VkPipelineViewportStateCreateInfo::pname:pViewports or 1236 flink:vkCmdSetViewport will have its width/height [eq]#(p~x~, p~y~)# and 1237 its center [eq]#(o~x~, o~y~)# similarly transformed by the 1238 implementation. 1239 * Each scissor specified by 1240 slink:VkPipelineViewportStateCreateInfo::pname:pScissors or 1241 flink:vkCmdSetScissor will have its [eq]#(offset~x~, offset~y~)# and 1242 [eq]#(extent~x~, extent~y~)# similarly transformed by the 1243 implementation. 1244 * The pname:renderArea specified in 1245 slink:VkCommandBufferInheritanceRenderPassTransformInfoQCOM and 1246 slink:VkRenderPassBeginInfo will be similarly transformed by the 1247 implementation. 1248 * The [eq]#(x, y)# components of shader variables with built-in 1249 decorations code:FragCoord, code:SamplePosition, or code:PointCoord will 1250 be similarly transformed by the implementation. 1251 * The [eq]#(x,y)# components of the code:offset operand of the 1252 code:InterpolateAtOffset extended instruction will be similarly 1253 transformed by the implementation. 1254 * The values returned by SPIR-V <<shaders-derivative-operations, 1255 derivative instructions>> code:OpDPdx, code:OpDPdy, code:OpDPdxCourse, 1256 code:OpDPdyCourse, code:OpDPdxFine, code:OpDPdyFine will be similarly 1257 transformed by the implementation. 1258 1259 1260The net result of the above, is that applications can: act as if rendering 1261to a framebuffer oriented with the 1262slink:VkSurfaceCapabilitiesKHR::pname:currentTransform. 1263In other words, applications can: act as if the presentation engine will be 1264performing the transformation of the swapchain image after rendering and 1265prior to presentation to the user. 1266In fact, the transformation of the various items cited above are being 1267handled by the implementation as the rendering takes place. 1268 1269endif::VK_QCOM_render_pass_transform[] 1270 1271 1272[[vertexpostproc-viewport]] 1273== Controlling the Viewport 1274 1275The viewport transformation is determined by the selected viewport's width 1276and height in pixels, [eq]#p~x~# and [eq]#p~y~#, respectively, and its 1277center [eq]#(o~x~, o~y~)# (also in pixels), as well as its depth range min 1278and max determining a depth range scale value [eq]#p~z~# and a depth range 1279bias value [eq]#o~z~# (defined below). 1280The vertex's framebuffer coordinates [eq]#(x~f~, y~f~, z~f~)# are given by 1281 1282 {empty}:: [eq]#x~f~ = (p~x~ / 2) x~d~ {plus} o~x~# 1283 {empty}:: [eq]#y~f~ = (p~y~ / 2) y~d~ {plus} o~y~# 1284 {empty}:: [eq]#z~f~ = p~z~ {times} z~d~ {plus} o~z~# 1285 1286Multiple viewports are available, numbered zero up to 1287sname:VkPhysicalDeviceLimits::pname:maxViewports minus one. 1288The number of viewports used by a pipeline is controlled by the 1289pname:viewportCount member of the sname:VkPipelineViewportStateCreateInfo 1290structure used in pipeline creation. 1291 1292[eq]#x~f~# and [eq]#y~f~# have limited precision, where the number of 1293fractional bits retained is specified by 1294sname:VkPhysicalDeviceLimits::pname:subPixelPrecisionBits. 1295ifdef::VK_EXT_line_rasterization[] 1296When rasterizing <<primsrast-lines,line segments>>, the number of fractional 1297bits is specified by 1298sname:VkPhysicalDeviceLineRasterizationPropertiesEXT::pname:lineSubPixelPrecisionBits. 1299endif::VK_EXT_line_rasterization[] 1300 1301[open,refpage='VkPipelineViewportStateCreateInfo',desc='Structure specifying parameters of a newly created pipeline viewport state',type='structs'] 1302-- 1303The sname:VkPipelineViewportStateCreateInfo structure is defined as: 1304 1305include::{generated}/api/structs/VkPipelineViewportStateCreateInfo.adoc[] 1306 1307 * pname:sType is a elink:VkStructureType value identifying this structure. 1308 * pname:pNext is `NULL` or a pointer to a structure extending this 1309 structure. 1310 * pname:flags is reserved for future use. 1311 * pname:viewportCount is the number of viewports used by the pipeline. 1312 * pname:pViewports is a pointer to an array of slink:VkViewport 1313 structures, defining the viewport transforms. 1314 If the viewport state is dynamic, this member is ignored. 1315 * pname:scissorCount is the number of <<fragops-scissor,scissors>> and 1316 must: match the number of viewports. 1317 * pname:pScissors is a pointer to an array of slink:VkRect2D structures 1318 defining the rectangular bounds of the scissor for the corresponding 1319 viewport. 1320 If the scissor state is dynamic, this member is ignored. 1321 1322.Valid Usage 1323**** 1324 * [[VUID-VkPipelineViewportStateCreateInfo-viewportCount-01216]] 1325 If the <<features-multiViewport, pname:multiViewport>> feature is not 1326 enabled, pname:viewportCount must: not be greater than `1` 1327 * [[VUID-VkPipelineViewportStateCreateInfo-scissorCount-01217]] 1328 If the <<features-multiViewport, pname:multiViewport>> feature is not 1329 enabled, pname:scissorCount must: not be greater than `1` 1330 * [[VUID-VkPipelineViewportStateCreateInfo-viewportCount-01218]] 1331 pname:viewportCount must: be less than or equal to 1332 sname:VkPhysicalDeviceLimits::pname:maxViewports 1333 * [[VUID-VkPipelineViewportStateCreateInfo-scissorCount-01219]] 1334 pname:scissorCount must: be less than or equal to 1335 sname:VkPhysicalDeviceLimits::pname:maxViewports 1336 * [[VUID-VkPipelineViewportStateCreateInfo-x-02821]] 1337 The pname:x and pname:y members of pname:offset member of any element of 1338 pname:pScissors must: be greater than or equal to `0` 1339 * [[VUID-VkPipelineViewportStateCreateInfo-offset-02822]] 1340 Evaluation of [eq]#(pname:offset.x {plus} pname:extent.width)# must: not 1341 cause a signed integer addition overflow for any element of 1342 pname:pScissors 1343 * [[VUID-VkPipelineViewportStateCreateInfo-offset-02823]] 1344 Evaluation of [eq]#(pname:offset.y {plus} pname:extent.height)# must: 1345 not cause a signed integer addition overflow for any element of 1346 pname:pScissors 1347 * [[VUID-VkPipelineViewportStateCreateInfo-scissorCount-04134]] 1348 If pname:scissorCount and pname:viewportCount are both not dynamic, then 1349 pname:scissorCount and pname:viewportCount must: be identical 1350ifndef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[] 1351 * [[VUID-VkPipelineViewportStateCreateInfo-viewportCount-arraylength]] 1352 pname:viewportCount must: be greater than `0` 1353 * [[VUID-VkPipelineViewportStateCreateInfo-scissorCount-arraylength]] 1354 pname:scissorCount must: be greater than `0` 1355endif::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[] 1356ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[] 1357 * [[VUID-VkPipelineViewportStateCreateInfo-viewportCount-04135]] 1358 If the graphics pipeline is being created with 1359 ename:VK_DYNAMIC_STATE_VIEWPORT_WITH_COUNT set then pname:viewportCount 1360 must: be `0`, otherwise it must: be greater than `0` 1361 * [[VUID-VkPipelineViewportStateCreateInfo-scissorCount-04136]] 1362 If the graphics pipeline is being created with 1363 ename:VK_DYNAMIC_STATE_SCISSOR_WITH_COUNT set then pname:scissorCount 1364 must: be `0`, otherwise it must: be greater than `0` 1365endif::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[] 1366ifdef::VK_NV_clip_space_w_scaling[] 1367 * [[VUID-VkPipelineViewportStateCreateInfo-viewportWScalingEnable-01726]] 1368 If the pname:viewportWScalingEnable member of a 1369 slink:VkPipelineViewportWScalingStateCreateInfoNV structure included in 1370 the pname:pNext chain is ename:VK_TRUE, the pname:viewportCount member 1371 of the slink:VkPipelineViewportWScalingStateCreateInfoNV structure must: 1372 be greater than or equal to 1373 slink:VkPipelineViewportStateCreateInfo::pname:viewportCount 1374endif::VK_NV_clip_space_w_scaling[] 1375**** 1376 1377include::{generated}/validity/structs/VkPipelineViewportStateCreateInfo.adoc[] 1378-- 1379 1380ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state,VK_EXT_shader_object[] 1381[open,refpage='vkCmdSetViewportWithCount',desc='Set the viewport count and viewports dynamically for a command buffer',type='protos',alias='vkCmdSetViewportWithCountEXT'] 1382-- 1383To <<pipelines-dynamic-state, dynamically set>> the viewport count and 1384viewports, call: 1385 1386ifdef::VK_VERSION_1_3[] 1387include::{generated}/api/protos/vkCmdSetViewportWithCount.adoc[] 1388 1389ifdef::VK_EXT_extended_dynamic_state,VK_EXT_shader_object[or the equivalent command] 1390endif::VK_VERSION_1_3[] 1391 1392ifdef::VK_EXT_extended_dynamic_state,VK_EXT_shader_object[] 1393include::{generated}/api/protos/vkCmdSetViewportWithCountEXT.adoc[] 1394endif::VK_EXT_extended_dynamic_state,VK_EXT_shader_object[] 1395 1396 * pname:commandBuffer is the command buffer into which the command will be 1397 recorded. 1398 * pname:viewportCount specifies the viewport count. 1399 * pname:pViewports specifies the viewports to use for drawing. 1400 1401This command sets the viewport count and viewports state for subsequent 1402drawing commands 1403ifdef::VK_EXT_shader_object[] 1404ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[when drawing using <<shaders-objects, shader objects>>, or] 1405ifndef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[when drawing using <<shaders-objects, shader objects>>.] 1406endif::VK_EXT_shader_object[] 1407ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[] 1408when the graphics pipeline is created with 1409ename:VK_DYNAMIC_STATE_VIEWPORT_WITH_COUNT set in 1410slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. 1411endif::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[] 1412Otherwise, this state is specified by the corresponding 1413slink:VkPipelineViewportStateCreateInfo::pname:viewportCount and 1414pname:pViewports values used to create the currently active pipeline. 1415 1416:refpage: vkCmdSetViewportWithCount 1417 1418.Valid Usage 1419**** 1420include::{chapters}/commonvalidity/dynamic_state_feature_common.adoc[] 1421 * [[VUID-vkCmdSetViewportWithCount-viewportCount-03394]] 1422 pname:viewportCount must: be between `1` and 1423 sname:VkPhysicalDeviceLimits::pname:maxViewports, inclusive 1424 * [[VUID-vkCmdSetViewportWithCount-viewportCount-03395]] 1425 If the <<features-multiViewport, pname:multiViewport>> feature is not 1426 enabled, pname:viewportCount must: be `1` 1427ifdef::VK_NV_inherited_viewport_scissor[] 1428 * [[VUID-vkCmdSetViewportWithCount-commandBuffer-04819]] 1429 pname:commandBuffer must: not have 1430 slink:VkCommandBufferInheritanceViewportScissorInfoNV::pname:viewportScissor2D 1431 enabled 1432endif::VK_NV_inherited_viewport_scissor[] 1433**** 1434 1435include::{generated}/validity/protos/vkCmdSetViewportWithCount.adoc[] 1436-- 1437 1438[open,refpage='vkCmdSetScissorWithCount',desc='Set the scissor count and scissor rectangular bounds dynamically for a command buffer',type='protos',alias='vkCmdSetScissorWithCountEXT'] 1439-- 1440To <<pipelines-dynamic-state, dynamically set>> the scissor count and 1441scissor rectangular bounds, call: 1442 1443ifdef::VK_VERSION_1_3[] 1444include::{generated}/api/protos/vkCmdSetScissorWithCount.adoc[] 1445 1446ifdef::VK_EXT_extended_dynamic_state,VK_EXT_shader_object[or the equivalent command] 1447endif::VK_VERSION_1_3[] 1448 1449ifdef::VK_EXT_extended_dynamic_state,VK_EXT_shader_object[] 1450include::{generated}/api/protos/vkCmdSetScissorWithCountEXT.adoc[] 1451endif::VK_EXT_extended_dynamic_state,VK_EXT_shader_object[] 1452 1453 * pname:commandBuffer is the command buffer into which the command will be 1454 recorded. 1455 * pname:scissorCount specifies the scissor count. 1456 * pname:pScissors specifies the scissors to use for drawing. 1457 1458This command sets the scissor count and scissor rectangular bounds state for 1459subsequent drawing commands 1460ifdef::VK_EXT_shader_object[] 1461ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[when drawing using <<shaders-objects, shader objects>>, or] 1462ifndef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[when drawing using <<shaders-objects, shader objects>>.] 1463endif::VK_EXT_shader_object[] 1464ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[] 1465when the graphics pipeline is created with 1466ename:VK_DYNAMIC_STATE_SCISSOR_WITH_COUNT set in 1467slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. 1468endif::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[] 1469Otherwise, this state is specified by the corresponding 1470slink:VkPipelineViewportStateCreateInfo::pname:scissorCount and 1471pname:pScissors values used to create the currently active pipeline. 1472 1473:refpage: vkCmdSetScissorWithCount 1474 1475.Valid Usage 1476**** 1477include::{chapters}/commonvalidity/dynamic_state_feature_common.adoc[] 1478 * [[VUID-vkCmdSetScissorWithCount-scissorCount-03397]] 1479 pname:scissorCount must: be between `1` and 1480 sname:VkPhysicalDeviceLimits::pname:maxViewports, inclusive 1481 * [[VUID-vkCmdSetScissorWithCount-scissorCount-03398]] 1482 If the <<features-multiViewport, pname:multiViewport>> feature is not 1483 enabled, pname:scissorCount must: be `1` 1484 * [[VUID-vkCmdSetScissorWithCount-x-03399]] 1485 The pname:x and pname:y members of pname:offset member of any element of 1486 pname:pScissors must: be greater than or equal to `0` 1487 * [[VUID-vkCmdSetScissorWithCount-offset-03400]] 1488 Evaluation of [eq]#(pname:offset.x {plus} pname:extent.width)# must: not 1489 cause a signed integer addition overflow for any element of 1490 pname:pScissors 1491 * [[VUID-vkCmdSetScissorWithCount-offset-03401]] 1492 Evaluation of [eq]#(pname:offset.y {plus} pname:extent.height)# must: 1493 not cause a signed integer addition overflow for any element of 1494 pname:pScissors 1495ifdef::VK_NV_inherited_viewport_scissor[] 1496 * [[VUID-vkCmdSetScissorWithCount-commandBuffer-04820]] 1497 pname:commandBuffer must: not have 1498 slink:VkCommandBufferInheritanceViewportScissorInfoNV::pname:viewportScissor2D 1499 enabled 1500endif::VK_NV_inherited_viewport_scissor[] 1501**** 1502 1503include::{generated}/validity/protos/vkCmdSetScissorWithCount.adoc[] 1504-- 1505endif::VK_VERSION_1_3,VK_EXT_extended_dynamic_state,VK_EXT_shader_object[] 1506 1507[open,refpage='VkPipelineViewportStateCreateFlags',desc='Reserved for future use',type='flags'] 1508-- 1509include::{generated}/api/flags/VkPipelineViewportStateCreateFlags.adoc[] 1510 1511tname:VkPipelineViewportStateCreateFlags is a bitmask type for setting a 1512mask, but is currently reserved for future use. 1513-- 1514 1515ifndef::VK_VERSION_1_2,VK_EXT_shader_viewport_index_layer,VK_NV_viewport_array2[] 1516If a geometry shader is active and has an output variable decorated with 1517code:ViewportIndex, the viewport transformation uses the viewport 1518corresponding to the value assigned to code:ViewportIndex taken from an 1519implementation-dependent vertex of each primitive. 1520If code:ViewportIndex is outside the range zero to pname:viewportCount minus 1521one for a primitive, or if the geometry shader did not assign a value to 1522code:ViewportIndex for all vertices of a primitive due to flow control, the 1523values resulting from the viewport transformation of the vertices of such 1524primitives are undefined:. 1525If no geometry shader is active, or if the geometry shader does not have an 1526output decorated with code:ViewportIndex, the viewport numbered zero is used 1527by the viewport transformation. 1528endif::VK_VERSION_1_2,VK_EXT_shader_viewport_index_layer,VK_NV_viewport_array2[] 1529 1530ifdef::VK_VERSION_1_2,VK_EXT_shader_viewport_index_layer,VK_NV_viewport_array2[] 1531ifdef::VK_NV_viewport_array2[] 1532A _<<pipelines-graphics-subsets-pre-rasterization,pre-rasterization shader 1533stage>>_ can: direct each primitive to zero or more viewports. 1534The destination viewports for a primitive are selected by the last active 1535<<pipelines-graphics-subsets-pre-rasterization,pre-rasterization shader 1536stage>> that has an output variable decorated with code:ViewportIndex 1537(selecting a single viewport) or code:ViewportMaskNV (selecting multiple 1538viewports). 1539The viewport transform uses the viewport corresponding to either the value 1540assigned to code:ViewportIndex or one of the bits set in 1541code:ViewportMaskNV, and taken from an implementation-dependent vertex of 1542each primitive. 1543If code:ViewportIndex or any of the bits in code:ViewportMaskNV are outside 1544the range zero to pname:viewportCount minus one for a primitive, or if the 1545last active <<pipelines-graphics-subsets-pre-rasterization,pre-rasterization 1546shader stage>> did not assign a value to either code:ViewportIndex or 1547code:ViewportMaskNV for all vertices of a primitive due to flow control, the 1548values resulting from the viewport transformation of the vertices of such 1549primitives are undefined:. 1550If the last <<pipelines-graphics-subsets-pre-rasterization,pre-rasterization 1551shader stage>> does not have an output decorated with code:ViewportIndex or 1552code:ViewportMaskNV, the viewport numbered zero is used by the viewport 1553transformation. 1554endif::VK_NV_viewport_array2[] 1555ifndef::VK_NV_viewport_array2[] 1556A _<<pipelines-graphics-subsets-pre-rasterization,pre-rasterization shader 1557stage>>_ can: direct each primitive to one of several viewports. 1558The destination viewport for a primitive is selected by the last active 1559<<pipelines-graphics-subsets-pre-rasterization,pre-rasterization shader 1560stage>> that has an output variable decorated with code:ViewportIndex. 1561The viewport transform uses the viewport corresponding to the value assigned 1562to code:ViewportIndex, and taken from an implementation-dependent vertex of 1563each primitive. 1564If code:ViewportIndex is outside the range zero to pname:viewportCount minus 1565one for a primitive, or if the last active 1566<<pipelines-graphics-subsets-pre-rasterization,pre-rasterization shader 1567stage>> did not assign a value to code:ViewportIndex for all vertices of a 1568primitive due to flow control, the values resulting from the viewport 1569transformation of the vertices of such primitives are undefined:. 1570If the last <<pipelines-graphics-subsets-pre-rasterization,pre-rasterization 1571shader stage>> does not have an output decorated with code:ViewportIndex, 1572the viewport numbered zero is used by the viewport transformation. 1573endif::VK_NV_viewport_array2[] 1574endif::VK_VERSION_1_2,VK_EXT_shader_viewport_index_layer,VK_NV_viewport_array2[] 1575 1576A single vertex can: be used in more than one individual primitive, in 1577primitives such as ename:VK_PRIMITIVE_TOPOLOGY_TRIANGLE_STRIP. 1578In this case, the viewport transformation is applied separately for each 1579primitive. 1580 1581[open,refpage='vkCmdSetViewport',desc='Set the viewport dynamically for a command buffer',type='protos'] 1582-- 1583To <<pipelines-dynamic-state, dynamically set>> the viewport transformation 1584parameters, call: 1585 1586include::{generated}/api/protos/vkCmdSetViewport.adoc[] 1587 1588 * pname:commandBuffer is the command buffer into which the command will be 1589 recorded. 1590 * pname:firstViewport is the index of the first viewport whose parameters 1591 are updated by the command. 1592 * pname:viewportCount is the number of viewports whose parameters are 1593 updated by the command. 1594 * pname:pViewports is a pointer to an array of slink:VkViewport structures 1595 specifying viewport parameters. 1596 1597This command sets the viewport transformation parameters state for 1598subsequent drawing commands 1599ifdef::VK_EXT_shader_object[when drawing using <<shaders-objects, shader objects>>, or] 1600when the graphics pipeline is created with ename:VK_DYNAMIC_STATE_VIEWPORT 1601set in slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. 1602Otherwise, this state is specified by the 1603sname:VkPipelineViewportStateCreateInfo::pname:pViewports values used to 1604create the currently active pipeline. 1605 1606The viewport parameters taken from element [eq]#i# of pname:pViewports 1607replace the current state for the viewport index [eq]#pname:firstViewport 1608{plus} i#, for [eq]#i# in [eq]#[0, pname:viewportCount)#. 1609 1610.Valid Usage 1611**** 1612 * [[VUID-vkCmdSetViewport-firstViewport-01223]] 1613 The sum of pname:firstViewport and pname:viewportCount must: be between 1614 `1` and sname:VkPhysicalDeviceLimits::pname:maxViewports, inclusive 1615 * [[VUID-vkCmdSetViewport-firstViewport-01224]] 1616 If the <<features-multiViewport, pname:multiViewport>> feature is not 1617 enabled, pname:firstViewport must: be `0` 1618 * [[VUID-vkCmdSetViewport-viewportCount-01225]] 1619 If the <<features-multiViewport, pname:multiViewport>> feature is not 1620 enabled, pname:viewportCount must: be `1` 1621ifdef::VK_NV_inherited_viewport_scissor[] 1622 * [[VUID-vkCmdSetViewport-commandBuffer-04821]] 1623 pname:commandBuffer must: not have 1624 slink:VkCommandBufferInheritanceViewportScissorInfoNV::pname:viewportScissor2D 1625 enabled 1626endif::VK_NV_inherited_viewport_scissor[] 1627**** 1628 1629include::{generated}/validity/protos/vkCmdSetViewport.adoc[] 1630-- 1631 1632Both slink:VkPipelineViewportStateCreateInfo and flink:vkCmdSetViewport use 1633sname:VkViewport to set the viewport transformation parameters. 1634 1635[open,refpage='VkViewport',desc='Structure specifying a viewport',type='structs'] 1636-- 1637The sname:VkViewport structure is defined as: 1638 1639include::{generated}/api/structs/VkViewport.adoc[] 1640 1641 * pname:x and pname:y are the viewport's upper left corner [eq]#(x,y)#. 1642 * pname:width and pname:height are the viewport's width and height, 1643 respectively. 1644 * pname:minDepth and pname:maxDepth are the depth range for the viewport. 1645 1646[NOTE] 1647.Note 1648==== 1649Despite their names, pname:minDepth can: be less than, equal to, or greater 1650than pname:maxDepth. 1651==== 1652 1653The framebuffer depth coordinate [eq]#pname:z~f~# may: be represented using 1654either a fixed-point or floating-point representation. 1655However, a floating-point representation must: be used if the depth/stencil 1656attachment has a floating-point depth component. 1657If an [eq]#m#-bit fixed-point representation is used, we assume that it 1658represents each value latexmath:[\frac{k}{2^m - 1}], where [eq]#k {elem} { 16590, 1, ..., 2^m^-1 }#, as [eq]#k# (e.g. 1.0 is represented in binary as a 1660string of all ones). 1661 1662The viewport parameters shown in the above equations are found from these 1663values as 1664 1665 {empty}:: [eq]#o~x~ = pname:x {plus} pname:width / 2# 1666 {empty}:: [eq]#o~y~ = pname:y {plus} pname:height / 2# 1667 {empty}:: [eq]#o~z~ = pname:minDepth# 1668ifdef::VK_EXT_depth_clip_control[] 1669 (or [eq]#(pname:maxDepth + pname:minDepth) / 2# if 1670 slink:VkPipelineViewportDepthClipControlCreateInfoEXT::pname:negativeOneToOne 1671 is ename:VK_TRUE) 1672endif::VK_EXT_depth_clip_control[] 1673 {empty}:: [eq]#p~x~ = pname:width# 1674 {empty}:: [eq]#p~y~ = pname:height# 1675 {empty}:: [eq]#p~z~ = pname:maxDepth - pname:minDepth# 1676ifdef::VK_EXT_depth_clip_control[] 1677 (or [eq]#(pname:maxDepth - pname:minDepth) / 2# if 1678 slink:VkPipelineViewportDepthClipControlCreateInfoEXT::pname:negativeOneToOne 1679 is ename:VK_TRUE) 1680endif::VK_EXT_depth_clip_control[] 1681 1682ifdef::VK_QCOM_render_pass_transform[] 1683If a render pass transform is enabled, the values [eq]#(p~x~,p~y~)# and 1684[eq]#(o~x~, o~y~)# defining the viewport are transformed as described in 1685<<vertexpostproc-renderpass-transform, render pass transform>> before 1686participating in the viewport transform. 1687endif::VK_QCOM_render_pass_transform[] 1688 1689ifdef::VK_VERSION_1_1,VK_KHR_maintenance1[] 1690The application can: specify a negative term for pname:height, which has the 1691effect of negating the y coordinate in clip space before performing the 1692transform. 1693When using a negative pname:height, the application should: also adjust the 1694pname:y value to point to the lower left corner of the viewport instead of 1695the upper left corner. 1696Using the negative pname:height allows the application to avoid having to 1697negate the y component of the code:Position output from the last 1698<<pipelines-graphics-subsets-pre-rasterization,pre-rasterization shader 1699stage>>. 1700endif::VK_VERSION_1_1,VK_KHR_maintenance1[] 1701 1702The width and height of the <<limits-maxViewportDimensions, 1703implementation-dependent maximum viewport dimensions>> must: be greater than 1704or equal to the width and height of the largest image which can: be created 1705and attached to a framebuffer. 1706 1707The floating-point viewport bounds are represented with an 1708<<limits-viewportSubPixelBits, implementation-dependent precision>>. 1709 1710.Valid Usage 1711**** 1712 * [[VUID-VkViewport-width-01770]] 1713 pname:width must: be greater than `0.0` 1714 * [[VUID-VkViewport-width-01771]] 1715 pname:width must: be less than or equal to 1716 sname:VkPhysicalDeviceLimits::pname:maxViewportDimensions[0] 1717ifndef::VKSC_VERSION_1_0[] 1718 * [[VUID-VkViewport-apiVersion-07917]] 1719 If the apiext:VK_KHR_maintenance1 extension is not enabled, the 1720 apiext:VK_AMD_negative_viewport_height extension is not enabled, and 1721 slink:VkPhysicalDeviceProperties::pname:apiVersion is less than Vulkan 1722 1.1, pname:height must: be greater than `0.0` 1723endif::VKSC_VERSION_1_0[] 1724 * [[VUID-VkViewport-height-01773]] 1725 The absolute value of pname:height must: be less than or equal to 1726 sname:VkPhysicalDeviceLimits::pname:maxViewportDimensions[1] 1727 * [[VUID-VkViewport-x-01774]] 1728 pname:x must: be greater than or equal to pname:viewportBoundsRange[0] 1729 * [[VUID-VkViewport-x-01232]] 1730 [eq]#(pname:x {plus} pname:width)# must: be less than or equal to 1731 pname:viewportBoundsRange[1] 1732 * [[VUID-VkViewport-y-01775]] 1733 pname:y must: be greater than or equal to pname:viewportBoundsRange[0] 1734ifdef::VK_VERSION_1_1,VK_KHR_maintenance1,VK_AMD_negative_viewport_height[] 1735 * [[VUID-VkViewport-y-01776]] 1736 pname:y must: be less than or equal to pname:viewportBoundsRange[1] 1737 * [[VUID-VkViewport-y-01777]] 1738 [eq]#(pname:y {plus} pname:height)# must: be greater than or equal to 1739 pname:viewportBoundsRange[0] 1740endif::VK_VERSION_1_1,VK_KHR_maintenance1,VK_AMD_negative_viewport_height[] 1741 * [[VUID-VkViewport-y-01233]] 1742 [eq]#(pname:y {plus} pname:height)# must: be less than or equal to 1743 pname:viewportBoundsRange[1] 1744ifdef::VK_EXT_depth_range_unrestricted[] 1745 * [[VUID-VkViewport-minDepth-01234]] 1746 If the `apiext:VK_EXT_depth_range_unrestricted` extension is not 1747 enabled, pname:minDepth must: be between `0.0` and `1.0`, inclusive 1748endif::VK_EXT_depth_range_unrestricted[] 1749ifndef::VK_EXT_depth_range_unrestricted[] 1750 * [[VUID-VkViewport-minDepth-02540]] 1751 pname:minDepth must: be between `0.0` and `1.0`, inclusive 1752endif::VK_EXT_depth_range_unrestricted[] 1753ifdef::VK_EXT_depth_range_unrestricted[] 1754 * [[VUID-VkViewport-maxDepth-01235]] 1755 If the `apiext:VK_EXT_depth_range_unrestricted` extension is not 1756 enabled, pname:maxDepth must: be between `0.0` and `1.0`, inclusive 1757endif::VK_EXT_depth_range_unrestricted[] 1758ifndef::VK_EXT_depth_range_unrestricted[] 1759 * [[VUID-VkViewport-maxDepth-02541]] 1760 pname:maxDepth must: be between `0.0` and `1.0`, inclusive 1761endif::VK_EXT_depth_range_unrestricted[] 1762**** 1763 1764include::{generated}/validity/structs/VkViewport.adoc[] 1765-- 1766