1// Copyright 2015-2023 The Khronos Group Inc. 2// 3// SPDX-License-Identifier: CC-BY-4.0 4 5[[drawing]] 6= Drawing Commands 7 8_Drawing commands_ (commands with ftext:Draw in the name) provoke work in a 9graphics pipeline. 10Drawing commands are recorded into a command buffer and when executed by a 11queue, will produce work which executes according to the bound graphics 12ifndef::VK_EXT_shader_object[pipeline.] 13ifdef::VK_EXT_shader_object[] 14pipeline, or if the <<features-shaderObject, pname:shaderObject>> feature is 15enabled, any <<shaders-objects, shader objects>> bound to graphics stages. 16endif::VK_EXT_shader_object[] 17A graphics pipeline 18ifdef::VK_EXT_shader_object[] 19or a combination of one or more graphics shader objects 20endif::VK_EXT_shader_object[] 21must: be bound to a command buffer before any drawing commands are recorded 22in that command buffer. 23 24[open,refpage='VkPipelineInputAssemblyStateCreateInfo',desc='Structure specifying parameters of a newly created pipeline input assembly state',type='structs'] 25-- 26ifdef::VK_NV_mesh_shader,VK_EXT_mesh_shader[] 27Drawing can be achieved in two modes: 28 29 * <<drawing-mesh-shading,Programmable Mesh Shading>>, the mesh shader 30 assembles primitives, or 31 * <<drawing-primitive-shading,Programmable Primitive Shading>>, the input 32 primitives are assembled as follows. 33 34endif::VK_NV_mesh_shader,VK_EXT_mesh_shader[] 35 36Each draw is made up of zero or more vertices and zero or more instances, 37which are processed by the device and result in the assembly of primitives. 38Primitives are assembled according to the pname:pInputAssemblyState member 39of the slink:VkGraphicsPipelineCreateInfo structure, which is of type 40sname:VkPipelineInputAssemblyStateCreateInfo: 41 42include::{generated}/api/structs/VkPipelineInputAssemblyStateCreateInfo.adoc[] 43 44 * pname:sType is a elink:VkStructureType value identifying this structure. 45 * pname:pNext is `NULL` or a pointer to a structure extending this 46 structure. 47 * pname:flags is reserved for future use. 48 * pname:topology is a elink:VkPrimitiveTopology defining the primitive 49 topology, as described below. 50 * pname:primitiveRestartEnable controls whether a special vertex index 51 value is treated as restarting the assembly of primitives. 52 This enable only applies to indexed draws (flink:vkCmdDrawIndexed, 53ifdef::VK_EXT_multi_draw[] 54 flink:vkCmdDrawMultiIndexedEXT, 55endif::VK_EXT_multi_draw[] 56 and flink:vkCmdDrawIndexedIndirect), and the special index value is 57 either 0xFFFFFFFF when the pname:indexType parameter of 58ifdef::VK_KHR_maintenance5[fname:vkCmdBindIndexBuffer2KHR or] 59 fname:vkCmdBindIndexBuffer is equal to ename:VK_INDEX_TYPE_UINT32, 60ifdef::VK_EXT_index_type_uint8[] 61 0xFF when pname:indexType is equal to ename:VK_INDEX_TYPE_UINT8_EXT, 62endif::VK_EXT_index_type_uint8[] 63 or 0xFFFF when pname:indexType is equal to ename:VK_INDEX_TYPE_UINT16. 64ifndef::VK_EXT_primitive_topology_list_restart[] 65 Primitive restart is not allowed for "`list`" topologies. 66endif::VK_EXT_primitive_topology_list_restart[] 67ifdef::VK_EXT_primitive_topology_list_restart[] 68 Primitive restart is not allowed for "`list`" topologies, unless one of 69 the features <<features-primitiveTopologyPatchListRestart, 70 pname:primitiveTopologyPatchListRestart>> (for 71 ename:VK_PRIMITIVE_TOPOLOGY_PATCH_LIST) or 72 <<features-primitiveTopologyListRestart, 73 pname:primitiveTopologyListRestart>> (for all other list topologies) is 74 enabled. 75endif::VK_EXT_primitive_topology_list_restart[] 76 77Restarting the assembly of primitives discards the most recent index values 78if those elements formed an incomplete primitive, and restarts the primitive 79assembly using the subsequent indices, but only assembling the immediately 80following element through the end of the originally specified elements. 81The primitive restart index value comparison is performed before adding the 82pname:vertexOffset value to the index value. 83 84.Valid Usage 85**** 86 * [[VUID-VkPipelineInputAssemblyStateCreateInfo-topology-06252]] 87 If 88ifdef::VK_EXT_primitive_topology_list_restart[] 89 the <<features-primitiveTopologyListRestart, 90 pname:primitiveTopologyListRestart>> feature is not enabled, and 91endif::VK_EXT_primitive_topology_list_restart[] 92 pname:topology is ename:VK_PRIMITIVE_TOPOLOGY_POINT_LIST, 93 ename:VK_PRIMITIVE_TOPOLOGY_LINE_LIST, 94 ename:VK_PRIMITIVE_TOPOLOGY_TRIANGLE_LIST, 95 ename:VK_PRIMITIVE_TOPOLOGY_LINE_LIST_WITH_ADJACENCY, or 96 ename:VK_PRIMITIVE_TOPOLOGY_TRIANGLE_LIST_WITH_ADJACENCY, 97 pname:primitiveRestartEnable must: be ename:VK_FALSE 98 * [[VUID-VkPipelineInputAssemblyStateCreateInfo-topology-06253]] 99 If 100ifdef::VK_EXT_primitive_topology_list_restart[] 101 the <<features-primitiveTopologyPatchListRestart, 102 pname:primitiveTopologyPatchListRestart>> feature is not enabled, and 103endif::VK_EXT_primitive_topology_list_restart[] 104 pname:topology is ename:VK_PRIMITIVE_TOPOLOGY_PATCH_LIST, 105 pname:primitiveRestartEnable must: be ename:VK_FALSE 106 * [[VUID-VkPipelineInputAssemblyStateCreateInfo-topology-00429]] 107 If the <<features-geometryShader, pname:geometryShader>> feature is not 108 enabled, pname:topology must: not be any of 109 ename:VK_PRIMITIVE_TOPOLOGY_LINE_LIST_WITH_ADJACENCY, 110 ename:VK_PRIMITIVE_TOPOLOGY_LINE_STRIP_WITH_ADJACENCY, 111 ename:VK_PRIMITIVE_TOPOLOGY_TRIANGLE_LIST_WITH_ADJACENCY or 112 ename:VK_PRIMITIVE_TOPOLOGY_TRIANGLE_STRIP_WITH_ADJACENCY 113 * [[VUID-VkPipelineInputAssemblyStateCreateInfo-topology-00430]] 114 If the <<features-tessellationShader, pname:tessellationShader>> feature 115 is not enabled, pname:topology must: not be 116 ename:VK_PRIMITIVE_TOPOLOGY_PATCH_LIST 117ifdef::VK_KHR_portability_subset[] 118 * [[VUID-VkPipelineInputAssemblyStateCreateInfo-triangleFans-04452]] 119 If the `apiext:VK_KHR_portability_subset` extension is enabled, and 120 slink:VkPhysicalDevicePortabilitySubsetFeaturesKHR::pname:triangleFans 121 is ename:VK_FALSE, pname:topology must: not be 122 ename:VK_PRIMITIVE_TOPOLOGY_TRIANGLE_FAN 123endif::VK_KHR_portability_subset[] 124**** 125 126include::{generated}/validity/structs/VkPipelineInputAssemblyStateCreateInfo.adoc[] 127-- 128 129[open,refpage='VkPipelineInputAssemblyStateCreateFlags',desc='Reserved for future use',type='flags'] 130-- 131include::{generated}/api/flags/VkPipelineInputAssemblyStateCreateFlags.adoc[] 132 133tname:VkPipelineInputAssemblyStateCreateFlags is a bitmask type for setting 134a mask, but is currently reserved for future use. 135-- 136 137ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state2,VK_EXT_shader_object[] 138[open,refpage='vkCmdSetPrimitiveRestartEnable',desc='Set primitive assembly restart state dynamically for a command buffer',type='protos',alias='vkCmdSetPrimitiveRestartEnableEXT'] 139-- 140To <<pipelines-dynamic-state, dynamically control>> whether a special vertex 141index value is treated as restarting the assembly of primitives, call: 142 143ifdef::VK_VERSION_1_3[] 144include::{generated}/api/protos/vkCmdSetPrimitiveRestartEnable.adoc[] 145 146ifdef::VK_EXT_extended_dynamic_state2,VK_EXT_shader_object[or the equivalent command] 147endif::VK_VERSION_1_3[] 148 149ifdef::VK_EXT_extended_dynamic_state2,VK_EXT_shader_object[] 150include::{generated}/api/protos/vkCmdSetPrimitiveRestartEnableEXT.adoc[] 151endif::VK_EXT_extended_dynamic_state2,VK_EXT_shader_object[] 152 153 * pname:commandBuffer is the command buffer into which the command will be 154 recorded. 155 * pname:primitiveRestartEnable controls whether a special vertex index 156 value is treated as restarting the assembly of primitives. 157 It behaves in the same way as 158 sname:VkPipelineInputAssemblyStateCreateInfo::pname:primitiveRestartEnable 159 160This command sets the primitive restart enable for subsequent drawing 161commands 162ifdef::VK_EXT_shader_object[] 163ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state2[when drawing using <<shaders-objects, shader objects>>, or] 164ifndef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state2[when drawing using <<shaders-objects, shader objects>>.] 165endif::VK_EXT_shader_object[] 166ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state2[] 167when the graphics pipeline is created with 168ename:VK_DYNAMIC_STATE_PRIMITIVE_RESTART_ENABLE set in 169slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. 170endif::VK_VERSION_1_3,VK_EXT_extended_dynamic_state2[] 171Otherwise, this state is specified by the 172slink:VkPipelineInputAssemblyStateCreateInfo::pname:primitiveRestartEnable 173value used to create the currently active pipeline. 174 175:refpage: vkCmdSetPrimitiveRestartEnable 176 177.Valid Usage 178**** 179include::{chapters}/commonvalidity/dynamic_state2_feature_common.adoc[] 180**** 181 182include::{generated}/validity/protos/vkCmdSetPrimitiveRestartEnable.adoc[] 183-- 184endif::VK_VERSION_1_3,VK_EXT_extended_dynamic_state2,VK_EXT_shader_object[] 185 186 187[[drawing-primitive-topologies]] 188== Primitive Topologies 189 190_Primitive topology_ determines how consecutive vertices are organized into 191primitives, and determines the type of primitive that is used at the 192beginning of the graphics pipeline. 193The effective topology for later stages of the pipeline is altered by 194tessellation or geometry shading (if either is in use) and depends on the 195execution modes of those shaders. 196ifdef::VK_NV_mesh_shader,VK_EXT_mesh_shader[] 197In the case of mesh shading the only effective topology is defined by the 198execution mode of the mesh shader. 199endif::VK_NV_mesh_shader,VK_EXT_mesh_shader[] 200 201[open,refpage='VkPrimitiveTopology',desc='Supported primitive topologies',type='enums'] 202-- 203The primitive topologies defined by elink:VkPrimitiveTopology are: 204 205include::{generated}/api/enums/VkPrimitiveTopology.adoc[] 206 207 * ename:VK_PRIMITIVE_TOPOLOGY_POINT_LIST specifies a series of 208 <<drawing-point-lists,separate point primitives>>. 209 * ename:VK_PRIMITIVE_TOPOLOGY_LINE_LIST specifies a series of 210 <<drawing-line-lists,separate line primitives>>. 211 * ename:VK_PRIMITIVE_TOPOLOGY_LINE_STRIP specifies a series of 212 <<drawing-line-strips,connected line primitives>> with consecutive lines 213 sharing a vertex. 214 * ename:VK_PRIMITIVE_TOPOLOGY_TRIANGLE_LIST specifies a series of 215 <<drawing-triangle-lists,separate triangle primitives>>. 216 * ename:VK_PRIMITIVE_TOPOLOGY_TRIANGLE_STRIP specifies a series of 217 <<drawing-triangle-strips,connected triangle primitives>> with 218 consecutive triangles sharing an edge. 219 * ename:VK_PRIMITIVE_TOPOLOGY_TRIANGLE_FAN specifies a series of 220 <<drawing-triangle-fans,connected triangle primitives>> with all 221 triangles sharing a common vertex. 222ifdef::VK_KHR_portability_subset[] 223 If the `apiext:VK_KHR_portability_subset` extension is enabled, and 224 slink:VkPhysicalDevicePortabilitySubsetFeaturesKHR::pname:triangleFans 225 is ename:VK_FALSE, then triangle fans are not supported by the 226 implementation, and ename:VK_PRIMITIVE_TOPOLOGY_TRIANGLE_FAN must: not 227 be used. 228endif::VK_KHR_portability_subset[] 229 * ename:VK_PRIMITIVE_TOPOLOGY_LINE_LIST_WITH_ADJACENCY specifies a series 230 of <<drawing-line-lists-with-adjacency,separate line primitives with 231 adjacency>>. 232 * ename:VK_PRIMITIVE_TOPOLOGY_LINE_STRIP_WITH_ADJACENCY specifies a series 233 of <<drawing-line-strips-with-adjacency,connected line primitives with 234 adjacency>>, with consecutive primitives sharing three vertices. 235 * ename:VK_PRIMITIVE_TOPOLOGY_TRIANGLE_LIST_WITH_ADJACENCY specifies a 236 series of <<drawing-triangle-lists-with-adjacency,separate triangle 237 primitives with adjacency>>. 238 * ename:VK_PRIMITIVE_TOPOLOGY_TRIANGLE_STRIP_WITH_ADJACENCY specifies 239 <<drawing-triangle-strips-with-adjacency,connected triangle primitives 240 with adjacency>>, with consecutive triangles sharing an edge. 241 * ename:VK_PRIMITIVE_TOPOLOGY_PATCH_LIST specifies 242 <<drawing-patch-lists,separate patch primitives>>. 243 244Each primitive topology, and its construction from a list of vertices, is 245described in detail below with a supporting diagram, according to the 246following key: 247 248[cols="1,2,9"] 249|==== 250^.^| image:{images}/primitive_topology_key_vertex.svg[pdfwidth=6pt,align="center",opts="{imageopts}"] 251.^| Vertex 252| A point in 3-dimensional space. 253 Positions chosen within the diagrams are arbitrary and for 254 illustration only. 255 256^.^| image:{images}/primitive_topology_key_vertex_number.svg[pdfwidth=6pt,align="center",opts="{imageopts}"] 257.^| Vertex Number 258| Sequence position of a vertex within the provided vertex data. 259 260^.^| image:{images}/primitive_topology_key_provoking_vertex.svg[pdfwidth=30pt,align="center",opts="{imageopts}"] 261.^| Provoking Vertex 262| Provoking vertex within the main primitive. 263 The tail is angled towards the relevant primitive. 264 Used in <<vertexpostproc-flatshading, flat shading>>. 265 266^.^| image:{images}/primitive_topology_key_edge.svg[pdfwidth=30pt,align="center",opts="{imageopts}"] 267.^| Primitive Edge 268| An edge connecting the points of a main primitive. 269 270^.^| image:{images}/primitive_topology_key_adjacency_edge.svg[pdfwidth=30pt,align="center",opts="{imageopts}"] 271.^| Adjacency Edge 272| Points connected by these lines do not contribute to a main primitive, 273 and are only accessible in a <<geometry,geometry shader>>. 274 275^.^| image:{images}/primitive_topology_key_winding_order.svg[pdfwidth=30pt,align="center",opts="{imageopts}"] 276.^| Winding Order 277| The relative order in which vertices are defined within a primitive, 278 used in the <<primsrast-polygons-basic,facing determination>>. 279 This ordering has no specific start or end point. 280|==== 281 282The diagrams are supported with mathematical definitions where the vertices 283([eq]#v#) and primitives ([eq]#p#) are numbered starting from [eq]#0#; 284[eq]#v~0~# is the first vertex in the provided data and [eq]#p~0~# is the 285first primitive in the set of primitives defined by the vertices and 286topology. 287-- 288 289ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state,VK_EXT_shader_object[] 290[open,refpage='vkCmdSetPrimitiveTopology',desc='Set primitive topology state dynamically for a command buffer',type='protos',alias='vkCmdSetPrimitiveTopologyEXT'] 291-- 292To <<pipelines-dynamic-state, dynamically set>> primitive topology, call: 293 294ifdef::VK_VERSION_1_3[] 295include::{generated}/api/protos/vkCmdSetPrimitiveTopology.adoc[] 296 297ifdef::VK_EXT_extended_dynamic_state,VK_EXT_shader_object[or the equivalent command] 298endif::VK_VERSION_1_3[] 299 300ifdef::VK_EXT_extended_dynamic_state,VK_EXT_shader_object[] 301include::{generated}/api/protos/vkCmdSetPrimitiveTopologyEXT.adoc[] 302endif::VK_EXT_extended_dynamic_state,VK_EXT_shader_object[] 303 304 * pname:commandBuffer is the command buffer into which the command will be 305 recorded. 306 * pname:primitiveTopology specifies the primitive topology to use for 307 drawing. 308 309This command sets the primitive topology for subsequent drawing commands 310ifdef::VK_EXT_shader_object[] 311ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[when drawing using <<shaders-objects, shader objects>>, or] 312ifndef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[when drawing using <<shaders-objects, shader objects>>.] 313endif::VK_EXT_shader_object[] 314ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[] 315when the graphics pipeline is created with 316ename:VK_DYNAMIC_STATE_PRIMITIVE_TOPOLOGY set in 317slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. 318endif::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[] 319Otherwise, this state is specified by the 320slink:VkPipelineInputAssemblyStateCreateInfo::pname:topology value used to 321create the currently active pipeline. 322 323:refpage: vkCmdSetPrimitiveTopology 324 325.Valid Usage 326**** 327include::{chapters}/commonvalidity/dynamic_state_feature_common.adoc[] 328**** 329 330include::{generated}/validity/protos/vkCmdSetPrimitiveTopology.adoc[] 331-- 332 333 334[[drawing-primitive-topology-class]] 335=== Topology Class 336 337The primitive topologies are grouped into the following topology classes: 338 339[[topology-classes]] 340.Topology classes 341[options="header"] 342|=== 343| Topology Class | Primitive Topology 344| Point | ename:VK_PRIMITIVE_TOPOLOGY_POINT_LIST 345| Line | ename:VK_PRIMITIVE_TOPOLOGY_LINE_LIST, 346 ename:VK_PRIMITIVE_TOPOLOGY_LINE_STRIP, 347 ename:VK_PRIMITIVE_TOPOLOGY_LINE_LIST_WITH_ADJACENCY, 348 ename:VK_PRIMITIVE_TOPOLOGY_LINE_STRIP_WITH_ADJACENCY 349| Triangle | ename:VK_PRIMITIVE_TOPOLOGY_TRIANGLE_LIST, 350 ename:VK_PRIMITIVE_TOPOLOGY_TRIANGLE_STRIP, 351 ename:VK_PRIMITIVE_TOPOLOGY_TRIANGLE_FAN, 352 ename:VK_PRIMITIVE_TOPOLOGY_TRIANGLE_LIST_WITH_ADJACENCY, 353 ename:VK_PRIMITIVE_TOPOLOGY_TRIANGLE_STRIP_WITH_ADJACENCY 354| Patch | ename:VK_PRIMITIVE_TOPOLOGY_PATCH_LIST 355|=== 356endif::VK_VERSION_1_3,VK_EXT_extended_dynamic_state,VK_EXT_shader_object[] 357 358 359[[drawing-point-lists]] 360=== Point Lists 361 362When the topology is ename:VK_PRIMITIVE_TOPOLOGY_POINT_LIST, each 363consecutive vertex defines a single point primitive, according to the 364equation: 365 366 {empty}:: [eq]#p~i~ = {v~i~}# 367 368As there is only one vertex, that vertex is the provoking vertex. 369The number of primitives generated is equal to [eq]#pname:vertexCount#. 370 371image::{images}/primitive_topology_point_list.svg[align="center",opts="{imageopts}"] 372 373 374[[drawing-line-lists]] 375=== Line Lists 376 377When the primitive topology is ename:VK_PRIMITIVE_TOPOLOGY_LINE_LIST, each 378consecutive pair of vertices defines a single line primitive, according to 379the equation: 380 381 {empty}:: [eq]#p~i~ = {v~2i~, v~2i+1~}# 382 383The number of primitives generated is equal to 384[eq]#{lfloor}pname:vertexCount/2{rfloor}#. 385 386ifdef::VK_EXT_provoking_vertex[] 387When the pname:provokingVertexMode is 388ename:VK_PROVOKING_VERTEX_MODE_FIRST_VERTEX_EXT, the 389endif::VK_EXT_provoking_vertex[] 390ifndef::VK_EXT_provoking_vertex[] 391The 392endif::VK_EXT_provoking_vertex[] 393provoking vertex for [eq]#p~i~# is [eq]#v~2i~#. 394 395image::{images}/primitive_topology_line_list.svg[align="center",opts="{imageopts}"] 396 397ifdef::VK_EXT_provoking_vertex[] 398When the pname:provokingVertexMode is 399ename:VK_PROVOKING_VERTEX_MODE_LAST_VERTEX_EXT, the provoking vertex for 400[eq]#p~i~# is [eq]#v~2i+1~#. 401 402image::{images}/primitive_topology_line_list_last.svg[align="center",opts="{imageopts}"] 403endif::VK_EXT_provoking_vertex[] 404 405 406[[drawing-line-strips]] 407=== Line Strips 408 409When the primitive topology is ename:VK_PRIMITIVE_TOPOLOGY_LINE_STRIP, one 410line primitive is defined by each vertex and the following vertex, according 411to the equation: 412 413 {empty}:: [eq]#p~i~ = {v~i~, v~i+1~}# 414 415The number of primitives generated is equal to 416[eq]#max(0,pname:vertexCount-1)#. 417 418ifdef::VK_EXT_provoking_vertex[] 419When the pname:provokingVertexMode is 420ename:VK_PROVOKING_VERTEX_MODE_FIRST_VERTEX_EXT, the 421endif::VK_EXT_provoking_vertex[] 422ifndef::VK_EXT_provoking_vertex[] 423The 424endif::VK_EXT_provoking_vertex[] 425provoking vertex for [eq]#p~i~# is [eq]#v~i~#. 426 427image::{images}/primitive_topology_line_strip.svg[align="center",opts="{imageopts}"] 428 429ifdef::VK_EXT_provoking_vertex[] 430When the pname:provokingVertexMode is 431ename:VK_PROVOKING_VERTEX_MODE_LAST_VERTEX_EXT, the provoking vertex for 432[eq]#p~i~# is [eq]#v~i+1~#. 433 434image::{images}/primitive_topology_line_strip_last.svg[align="center",opts="{imageopts}"] 435endif::VK_EXT_provoking_vertex[] 436 437 438[[drawing-triangle-lists]] 439=== Triangle Lists 440 441When the primitive topology is ename:VK_PRIMITIVE_TOPOLOGY_TRIANGLE_LIST, 442each consecutive set of three vertices defines a single triangle primitive, 443according to the equation: 444 445 {empty}:: [eq]#p~i~ = {v~3i~, v~3i+1~, v~3i+2~}# 446 447The number of primitives generated is equal to 448[eq]#{lfloor}pname:vertexCount/3{rfloor}#. 449 450ifdef::VK_EXT_provoking_vertex[] 451When the pname:provokingVertexMode is 452ename:VK_PROVOKING_VERTEX_MODE_FIRST_VERTEX_EXT, the 453endif::VK_EXT_provoking_vertex[] 454ifndef::VK_EXT_provoking_vertex[] 455The 456endif::VK_EXT_provoking_vertex[] 457provoking vertex for [eq]#p~i~# is [eq]#v~3i~#. 458 459image::{images}/primitive_topology_triangle_list.svg[align="center",opts="{imageopts}"] 460 461ifdef::VK_EXT_provoking_vertex[] 462When the pname:provokingVertexMode is 463ename:VK_PROVOKING_VERTEX_MODE_LAST_VERTEX_EXT, the provoking vertex for 464[eq]#p~i~# is [eq]#v~3i+2~#. 465 466image::{images}/primitive_topology_triangle_list_last.svg[align="center",opts="{imageopts}"] 467endif::VK_EXT_provoking_vertex[] 468 469 470[[drawing-triangle-strips]] 471=== Triangle Strips 472 473When the primitive topology is ename:VK_PRIMITIVE_TOPOLOGY_TRIANGLE_STRIP, 474one triangle primitive is defined by each vertex and the two vertices that 475follow it, according to the equation: 476 477 {empty}:: [eq]#p~i~ = {v~i~, v~i+(1+i%2)~, v~i+(2-i%2)~}# 478 479The number of primitives generated is equal to 480[eq]#max(0,pname:vertexCount-2)#. 481 482ifdef::VK_EXT_provoking_vertex[] 483When the pname:provokingVertexMode is 484ename:VK_PROVOKING_VERTEX_MODE_FIRST_VERTEX_EXT, the 485endif::VK_EXT_provoking_vertex[] 486ifndef::VK_EXT_provoking_vertex[] 487The 488endif::VK_EXT_provoking_vertex[] 489provoking vertex for [eq]#p~i~# is [eq]#v~i~#. 490 491image::{images}/primitive_topology_triangle_strip.svg[align="center",opts="{imageopts}"] 492 493ifdef::VK_EXT_provoking_vertex[] 494When the pname:provokingVertexMode is 495ename:VK_PROVOKING_VERTEX_MODE_LAST_VERTEX_EXT, the provoking vertex for 496[eq]#p~i~# is [eq]#v~i+2~#. 497 498image::{images}/primitive_topology_triangle_strip_last.svg[align="center",opts="{imageopts}"] 499endif::VK_EXT_provoking_vertex[] 500 501[NOTE] 502.Note 503==== 504The ordering of the vertices in each successive triangle is reversed, so 505that the winding order is consistent throughout the strip. 506==== 507 508 509[[drawing-triangle-fans]] 510=== Triangle Fans 511 512When the primitive topology is ename:VK_PRIMITIVE_TOPOLOGY_TRIANGLE_FAN, 513triangle primitives are defined around a shared common vertex, according to 514the equation: 515 516 {empty}:: [eq]#p~i~ = {v~i+1~, v~i+2~, v~0~}# 517 518The number of primitives generated is equal to 519[eq]#max(0,pname:vertexCount-2)#. 520 521ifdef::VK_EXT_provoking_vertex[] 522When the pname:provokingVertexMode is 523ename:VK_PROVOKING_VERTEX_MODE_FIRST_VERTEX_EXT, the 524endif::VK_EXT_provoking_vertex[] 525ifndef::VK_EXT_provoking_vertex[] 526The 527endif::VK_EXT_provoking_vertex[] 528provoking vertex for [eq]#p~i~# is [eq]#v~i+1~#. 529 530image::{images}/primitive_topology_triangle_fan.svg[align="center",opts="{imageopts}"] 531 532ifdef::VK_EXT_provoking_vertex[] 533When the pname:provokingVertexMode is 534ename:VK_PROVOKING_VERTEX_MODE_LAST_VERTEX_EXT, the provoking vertex for 535[eq]#p~i~# is [eq]#v~i+2~#. 536 537image::{images}/primitive_topology_triangle_fan_last.svg[align="center",opts="{imageopts}"] 538endif::VK_EXT_provoking_vertex[] 539 540ifdef::VK_KHR_portability_subset[] 541[NOTE] 542.Note 543==== 544If the `apiext:VK_KHR_portability_subset` extension is enabled, and 545slink:VkPhysicalDevicePortabilitySubsetFeaturesKHR::pname:triangleFans is 546ename:VK_FALSE, then triangle fans are not supported by the implementation, 547and ename:VK_PRIMITIVE_TOPOLOGY_TRIANGLE_FAN must: not be used. 548==== 549endif::VK_KHR_portability_subset[] 550 551 552[[drawing-line-lists-with-adjacency]] 553=== Line Lists With Adjacency 554 555When the primitive topology is 556ename:VK_PRIMITIVE_TOPOLOGY_LINE_LIST_WITH_ADJACENCY, each consecutive set 557of four vertices defines a single line primitive with adjacency, according 558to the equation: 559 560 {empty}:: [eq]#p~i~ = {v~4i~, v~4i+1~, v~4i+2~,v~4i+3~}# 561 562A line primitive is described by the second and third vertices of the total 563primitive, with the remaining two vertices only accessible in a 564<<geometry,geometry shader>>. 565 566The number of primitives generated is equal to 567[eq]#{lfloor}pname:vertexCount/4{rfloor}#. 568 569ifdef::VK_EXT_provoking_vertex[] 570When the pname:provokingVertexMode is 571ename:VK_PROVOKING_VERTEX_MODE_FIRST_VERTEX_EXT, the 572endif::VK_EXT_provoking_vertex[] 573ifndef::VK_EXT_provoking_vertex[] 574The 575endif::VK_EXT_provoking_vertex[] 576provoking vertex for [eq]#p~i~# is [eq]#v~4i+1~#. 577 578image::{images}/primitive_topology_line_list_with_adjacency.svg[align="center",opts="{imageopts}"] 579 580ifdef::VK_EXT_provoking_vertex[] 581When the pname:provokingVertexMode is 582ename:VK_PROVOKING_VERTEX_MODE_LAST_VERTEX_EXT, the provoking vertex for 583[eq]#p~i~# is [eq]#v~4i+2~#. 584 585image::{images}/primitive_topology_line_list_with_adjacency_last.svg[align="center",opts="{imageopts}"] 586endif::VK_EXT_provoking_vertex[] 587 588 589[[drawing-line-strips-with-adjacency]] 590=== Line Strips With Adjacency 591 592When the primitive topology is 593ename:VK_PRIMITIVE_TOPOLOGY_LINE_STRIP_WITH_ADJACENCY, one line primitive 594with adjacency is defined by each vertex and the following vertex, according 595to the equation: 596 597 {empty}:: [eq]#p~i~ = {v~i~, v~i+1~, v~i+2~, v~i+3~}# 598 599A line primitive is described by the second and third vertices of the total 600primitive, with the remaining two vertices only accessible in a 601<<geometry,geometry shader>>. 602 603The number of primitives generated is equal to 604[eq]#max(0,pname:vertexCount-3)#. 605 606ifdef::VK_EXT_provoking_vertex[] 607When the pname:provokingVertexMode is 608ename:VK_PROVOKING_VERTEX_MODE_FIRST_VERTEX_EXT, the 609endif::VK_EXT_provoking_vertex[] 610ifndef::VK_EXT_provoking_vertex[] 611The 612endif::VK_EXT_provoking_vertex[] 613provoking vertex for [eq]#p~i~# is [eq]#v~i+1~#. 614 615image::{images}/primitive_topology_line_strip_with_adjacency.svg[align="center",opts="{imageopts}"] 616 617ifdef::VK_EXT_provoking_vertex[] 618When the pname:provokingVertexMode is 619ename:VK_PROVOKING_VERTEX_MODE_LAST_VERTEX_EXT, the provoking vertex for 620[eq]#p~i~# is [eq]#v~i+2~#. 621 622image::{images}/primitive_topology_line_strip_with_adjacency_last.svg[align="center",opts="{imageopts}"] 623endif::VK_EXT_provoking_vertex[] 624 625 626[[drawing-triangle-lists-with-adjacency]] 627=== Triangle Lists With Adjacency 628 629When the primitive topology is 630ename:VK_PRIMITIVE_TOPOLOGY_TRIANGLE_LIST_WITH_ADJACENCY, each consecutive 631set of six vertices defines a single triangle primitive with adjacency, 632according to the equations: 633 634 {empty}:: [eq]#p~i~ = {v~6i~, v~6i+1~, v~6i+2~, v~6i+3~, v~6i+4~, 635 v~6i+5~}# 636 637A triangle primitive is described by the first, third, and fifth vertices of 638the total primitive, with the remaining three vertices only accessible in a 639<<geometry,geometry shader>>. 640 641The number of primitives generated is equal to 642[eq]#{lfloor}pname:vertexCount/6{rfloor}#. 643 644ifdef::VK_EXT_provoking_vertex[] 645When the pname:provokingVertexMode is 646ename:VK_PROVOKING_VERTEX_MODE_FIRST_VERTEX_EXT, the 647endif::VK_EXT_provoking_vertex[] 648ifndef::VK_EXT_provoking_vertex[] 649The 650endif::VK_EXT_provoking_vertex[] 651provoking vertex for [eq]#p~i~# is [eq]#v~6i~#. 652 653image::{images}/primitive_topology_triangle_list_with_adjacency.svg[align="center",opts="{imageopts}"] 654 655ifdef::VK_EXT_provoking_vertex[] 656When the pname:provokingVertexMode is 657ename:VK_PROVOKING_VERTEX_MODE_LAST_VERTEX_EXT, the provoking vertex for 658[eq]#p~i~# is [eq]#v~6i+4~#. 659 660image::{images}/primitive_topology_triangle_list_with_adjacency_last.svg[align="center",opts="{imageopts}"] 661endif::VK_EXT_provoking_vertex[] 662 663 664[[drawing-triangle-strips-with-adjacency]] 665=== Triangle Strips With Adjacency 666 667When the primitive topology is 668ename:VK_PRIMITIVE_TOPOLOGY_TRIANGLE_STRIP_WITH_ADJACENCY, one triangle 669primitive with adjacency is defined by each vertex and the following 5 670vertices. 671 672The number of primitives generated, [eq]#n#, is equal to [eq]#{lfloor}max(0, 673pname:vertexCount - 4)/2{rfloor}#. 674 675If [eq]#n=1#, the primitive is defined as: 676 677 {empty}:: [eq]#p = {v~0~, v~1~, v~2~, v~5~, v~4~, v~3~}# 678 679If [eq]#n>1#, the total primitive consists of different vertices according 680to where it is in the strip: 681 682 {empty}:: [eq]#p~i~ = {v~2i~, v~2i+1~, v~2i+2~, v~2i+6~, v~2i+4~, 683 v~2i+3~}# when [eq]#i=0# 684 {empty}:: [eq]#p~i~ = {v~2i~, v~2i+3~, v~2i+4~, v~2i+6~, v~2i+2~, 685 v~2i-2~}# when [eq]#i>0#, [eq]#i<n-1#, and [eq]#i%2=1# 686 {empty}:: [eq]#p~i~ = {v~2i~, v~2i-2~, v~2i+2~, v~2i+6~, v~2i+4~, 687 v~2i+3~}# when [eq]#i>0#, [eq]#i<n-1#, and [eq]#i%2=0# 688 {empty}:: [eq]#p~i~ = {v~2i~, v~2i+3~, v~2i+4~, v~2i+5~, v~2i+2~, 689 v~2i-2~}# when [eq]#i=n-1# and [eq]#i%2=1# 690 {empty}:: [eq]#p~i~ = {v~2i~, v~2i-2~, v~2i+2~, v~2i+5~, v~2i+4~, 691 v~2i+3~}# when [eq]#i=n-1# and [eq]#i%2=0# 692 693A triangle primitive is described by the first, third, and fifth vertices of 694the total primitive in all cases, with the remaining three vertices only 695accessible in a <<geometry,geometry shader>>. 696 697[NOTE] 698.Note 699==== 700The ordering of the vertices in each successive triangle is altered so that 701the winding order is consistent throughout the strip. 702==== 703 704ifdef::VK_EXT_provoking_vertex[] 705When the pname:provokingVertexMode is 706ename:VK_PROVOKING_VERTEX_MODE_FIRST_VERTEX_EXT, the 707endif::VK_EXT_provoking_vertex[] 708ifndef::VK_EXT_provoking_vertex[] 709The 710endif::VK_EXT_provoking_vertex[] 711provoking vertex for [eq]#p~i~# is always [eq]#v~2i~#. 712 713image::{images}/primitive_topology_triangle_strip_with_adjacency.svg[align="center",opts="{imageopts}"] 714 715ifdef::VK_EXT_provoking_vertex[] 716When the pname:provokingVertexMode is 717ename:VK_PROVOKING_VERTEX_MODE_LAST_VERTEX_EXT, the provoking vertex for 718[eq]#p~i~# is always [eq]#v~2i+4~#. 719 720image::{images}/primitive_topology_triangle_strip_with_adjacency_last.svg[align="center",opts="{imageopts}"] 721endif::VK_EXT_provoking_vertex[] 722 723 724[[drawing-patch-lists]] 725=== Patch Lists 726 727When the primitive topology is ename:VK_PRIMITIVE_TOPOLOGY_PATCH_LIST, each 728consecutive set of [eq]#m# vertices defines a single patch primitive, 729according to the equation: 730 731 {empty}:: [eq]#p~i~ = {v~mi~, v~mi+1~, ..., v~mi+(m-2)~, v~mi+(m-1)~}# 732 733where [eq]#m# is equal to 734slink:VkPipelineTessellationStateCreateInfo::pname:patchControlPoints. 735 736Patch lists are never passed to <<vertexpostproc, vertex post-processing>>, 737and as such no provoking vertex is defined for patch primitives. 738The number of primitives generated is equal to 739[eq]#{lfloor}pname:vertexCount/m{rfloor}#. 740 741The vertices comprising a patch have no implied geometry, and are used as 742inputs to tessellation shaders and the fixed-function tessellator to 743generate new point, line, or triangle primitives. 744 745 746[[drawing-primitive-order]] 747== Primitive Order 748 749Primitives generated by <<drawing, drawing commands>> progress through the 750stages of the <<synchronization-pipeline-graphics, graphics pipeline>> in 751_primitive order_. 752Primitive order is initially determined in the following way: 753 754 . Submission order determines the initial ordering 755 . For indirect drawing commands, the order in which accessed instances of 756 the slink:VkDrawIndirectCommand are stored in pname:buffer, from lower 757 indirect buffer addresses to higher addresses. 758 . If a drawing command includes multiple instances, the order in which 759 instances are executed, from lower numbered instances to higher. 760 . The order in which primitives are specified by a drawing command: 761 ** For non-indexed draws, from vertices with a lower numbered 762 code:vertexIndex to a higher numbered code:vertexIndex. 763 ** For indexed draws, vertices sourced from a lower index buffer addresses 764 to higher addresses. 765ifdef::VK_NV_mesh_shader,VK_EXT_mesh_shader[] 766 ** For draws using mesh shaders, the order is provided by <<mesh-ordering, 767 mesh shading>>. 768endif::VK_NV_mesh_shader,VK_EXT_mesh_shader[] 769ifdef::VK_HUAWEI_cluster_culling_shader[] 770 ** For draws using cluster culling shaders, the order is provided by 771 <<cluster-culling-cluster-ordering, cluster culling shading>>. 772endif::VK_HUAWEI_cluster_culling_shader[] 773 774Within this order implementations further sort primitives: 775 776[start=5] 777 . If tessellation shading is active, by an implementation-dependent order 778 of new primitives generated by <<tessellation-primitive-order, 779 tessellation>>. 780 . If geometry shading is active, by the order new primitives are generated 781 by <<geometry-ordering, geometry shading>>. 782 . If the <<primsrast-polygonmode,polygon mode>> is not 783 ename:VK_POLYGON_MODE_FILL, 784ifdef::VK_NV_fill_rectangle[] 785 or ename:VK_POLYGON_MODE_FILL_RECTANGLE_NV, 786endif::VK_NV_fill_rectangle[] 787 by an implementation-dependent ordering of the new primitives generated 788 within the original primitive. 789 790Primitive order is later used to define <<primsrast-order, rasterization 791order>>, which determines the order in which fragments output results to a 792framebuffer. 793 794 795[[drawing-primitive-shading]] 796== Programmable Primitive Shading 797 798Once primitives are assembled, they proceed to the vertex shading stage of 799the pipeline. 800If the draw includes multiple instances, then the set of primitives is sent 801to the vertex shading stage multiple times, once for each instance. 802 803It is implementation-dependent whether vertex shading occurs on vertices 804that are discarded as part of incomplete primitives, but if it does occur 805then it operates as if they were vertices in complete primitives and such 806invocations can: have side effects. 807 808Vertex shading receives two per-vertex inputs from the primitive assembly 809stage - the code:vertexIndex and the code:instanceIndex. 810How these values are generated is defined below, with each command. 811 812Drawing commands fall roughly into two categories: 813 814 * Non-indexed drawing commands present a sequential code:vertexIndex to 815 the vertex shader. 816 The sequential index is generated automatically by the device (see 817 <<fxvertex,Fixed-Function Vertex Processing>> for details on both 818 specifying the vertex attributes indexed by code:vertexIndex, as well as 819 binding vertex buffers containing those attributes to a command buffer). 820 These commands are: 821 ** flink:vkCmdDraw 822 ** flink:vkCmdDrawIndirect 823ifdef::VK_VERSION_1_2[] 824 ** flink:vkCmdDrawIndirectCount 825endif::VK_VERSION_1_2[] 826ifdef::VK_KHR_draw_indirect_count[] 827 ** flink:vkCmdDrawIndirectCountKHR 828endif::VK_KHR_draw_indirect_count[] 829ifdef::VK_AMD_draw_indirect_count[] 830 ** flink:vkCmdDrawIndirectCountAMD 831endif::VK_AMD_draw_indirect_count[] 832ifdef::VK_EXT_multi_draw[] 833 ** flink:vkCmdDrawMultiEXT 834endif::VK_EXT_multi_draw[] 835 * Indexed drawing commands read index values from an _index buffer_ and 836 use this to compute the code:vertexIndex value for the vertex shader. 837 These commands are: 838 ** flink:vkCmdDrawIndexed 839 ** flink:vkCmdDrawIndexedIndirect 840ifdef::VK_VERSION_1_2[] 841 ** flink:vkCmdDrawIndexedIndirectCount 842endif::VK_VERSION_1_2[] 843ifdef::VK_KHR_draw_indirect_count[] 844 ** flink:vkCmdDrawIndexedIndirectCountKHR 845endif::VK_KHR_draw_indirect_count[] 846ifdef::VK_AMD_draw_indirect_count[] 847 ** flink:vkCmdDrawIndexedIndirectCountAMD 848endif::VK_AMD_draw_indirect_count[] 849ifdef::VK_EXT_multi_draw[] 850 ** flink:vkCmdDrawMultiIndexedEXT 851endif::VK_EXT_multi_draw[] 852 853 854[open,refpage='vkCmdBindIndexBuffer',desc='Bind an index buffer to a command buffer',type='protos'] 855-- 856:refpage: vkCmdBindIndexBuffer 857 858To bind an index buffer to a command buffer, call: 859 860include::{generated}/api/protos/vkCmdBindIndexBuffer.adoc[] 861 862 * pname:commandBuffer is the command buffer into which the command is 863 recorded. 864 * pname:buffer is the buffer being bound. 865 * pname:offset is the starting offset in bytes within pname:buffer used in 866 index buffer address calculations. 867 * pname:indexType is a elink:VkIndexType value specifying the size of the 868 indices. 869 870.Valid Usage 871**** 872include::{chapters}/commonvalidity/bind_index_buffer_common.adoc[] 873**** 874 875include::{generated}/validity/protos/vkCmdBindIndexBuffer.adoc[] 876-- 877 878ifdef::VK_KHR_maintenance5[] 879[open,refpage='vkCmdBindIndexBuffer2KHR',desc='Bind an index buffer to a command buffer',type='protos'] 880-- 881:refpage: vkCmdBindIndexBuffer2KHR 882 883To bind an index buffer, along with its size, to a command buffer, call: 884 885include::{generated}/api/protos/vkCmdBindIndexBuffer2KHR.adoc[] 886 887 * pname:commandBuffer is the command buffer into which the command is 888 recorded. 889 * pname:buffer is the buffer being bound. 890 * pname:offset is the starting offset in bytes within pname:buffer used in 891 index buffer address calculations. 892 * pname:size is the size in bytes of index data bound from pname:buffer. 893 * pname:indexType is a elink:VkIndexType value specifying the size of the 894 indices. 895 896pname:size specifies the bound size of the index buffer starting from 897pname:offset. 898If pname:size is ename:VK_WHOLE_SIZE then the bound size is from 899pname:offset to the end of the pname:buffer. 900 901.Valid Usage 902**** 903include::{chapters}/commonvalidity/bind_index_buffer_common.adoc[] 904 * [[VUID-vkCmdBindIndexBuffer2KHR-size-08767]] 905 If pname:size is not ename:VK_WHOLE_SIZE, pname:size must: be a multiple 906 of the size of the type indicated by pname:indexType 907 * [[VUID-vkCmdBindIndexBuffer2KHR-size-08768]] 908 If pname:size is not ename:VK_WHOLE_SIZE, the sum of pname:offset and 909 pname:size must: be less than or equal to the size of pname:buffer 910**** 911 912include::{generated}/validity/protos/vkCmdBindIndexBuffer2KHR.adoc[] 913-- 914endif::VK_KHR_maintenance5[] 915 916[open,refpage='VkIndexType',desc='Type of index buffer indices',type='enums'] 917-- 918Possible values of 919ifdef::VK_KHR_maintenance5[flink:vkCmdBindIndexBuffer2KHR::pname:indexType and] 920flink:vkCmdBindIndexBuffer::pname:indexType, specifying the size of indices, 921are: 922 923include::{generated}/api/enums/VkIndexType.adoc[] 924 925 * ename:VK_INDEX_TYPE_UINT16 specifies that indices are 16-bit unsigned 926 integer values. 927 * ename:VK_INDEX_TYPE_UINT32 specifies that indices are 32-bit unsigned 928 integer values. 929ifdef::VK_NV_ray_tracing,VK_KHR_acceleration_structure[] 930 * ename:VK_INDEX_TYPE_NONE_KHR specifies that no indices are provided. 931endif::VK_NV_ray_tracing,VK_KHR_acceleration_structure[] 932ifdef::VK_EXT_index_type_uint8[] 933 * ename:VK_INDEX_TYPE_UINT8_EXT specifies that indices are 8-bit unsigned 934 integer values. 935endif::VK_EXT_index_type_uint8[] 936-- 937 938The parameters for each drawing command are specified directly in the 939command or read from buffer memory, depending on the command. 940Drawing commands that source their parameters from buffer memory are known 941as _indirect_ drawing commands. 942 943All drawing commands interact with the <<features-robustBufferAccess, 944pname:robustBufferAccess>> feature. 945 946[open,refpage='vkCmdDraw',desc='Draw primitives',type='protos'] 947-- 948:refpage: vkCmdDraw 949 950To record a non-indexed draw, call: 951 952include::{generated}/api/protos/vkCmdDraw.adoc[] 953 954 * pname:commandBuffer is the command buffer into which the command is 955 recorded. 956 * pname:vertexCount is the number of vertices to draw. 957 * pname:instanceCount is the number of instances to draw. 958 * pname:firstVertex is the index of the first vertex to draw. 959 * pname:firstInstance is the instance ID of the first instance to draw. 960 961When the command is executed, primitives are assembled using the current 962primitive topology and pname:vertexCount consecutive vertex indices with the 963first code:vertexIndex value equal to pname:firstVertex. 964The primitives are drawn pname:instanceCount times with code:instanceIndex 965starting with pname:firstInstance and increasing sequentially for each 966instance. 967The assembled primitives execute the bound graphics pipeline. 968 969.Valid Usage 970**** 971include::{chapters}/commonvalidity/draw_common.adoc[] 972include::{chapters}/commonvalidity/draw_dispatch_nonindirect_common.adoc[] 973include::{chapters}/commonvalidity/draw_vertex_binding.adoc[] 974**** 975 976include::{generated}/validity/protos/vkCmdDraw.adoc[] 977-- 978 979[open,refpage='vkCmdDrawIndexed',desc='Draw primitives with indexed vertices',type='protos'] 980-- 981:refpage: vkCmdDrawIndexed 982 983To record an indexed draw, call: 984 985include::{generated}/api/protos/vkCmdDrawIndexed.adoc[] 986 987 * pname:commandBuffer is the command buffer into which the command is 988 recorded. 989 * pname:indexCount is the number of vertices to draw. 990 * pname:instanceCount is the number of instances to draw. 991 * pname:firstIndex is the base index within the index buffer. 992 * pname:vertexOffset is the value added to the vertex index before 993 indexing into the vertex buffer. 994 * pname:firstInstance is the instance ID of the first instance to draw. 995 996When the command is executed, primitives are assembled using the current 997primitive topology and pname:indexCount vertices whose indices are retrieved 998from the index buffer. 999The index buffer is treated as an array of tightly packed unsigned integers 1000of size defined by the 1001ifdef::VK_KHR_maintenance5[flink:vkCmdBindIndexBuffer2KHR::pname:indexType or the] 1002flink:vkCmdBindIndexBuffer::pname:indexType parameter with which the buffer 1003was bound. 1004 1005The first vertex index is at an offset of [eq]#pname:firstIndex {times} 1006code:indexSize {plus} pname:offset# within the bound index buffer, where 1007pname:offset is the offset specified by fname:vkCmdBindIndexBuffer 1008ifdef::VK_KHR_maintenance5[or fname:vkCmdBindIndexBuffer2KHR,] 1009and code:indexSize is the byte size of the type specified by 1010pname:indexType. 1011Subsequent index values are retrieved from consecutive locations in the 1012index buffer. 1013Indices are first compared to the primitive restart value, then zero 1014extended to 32 bits (if the code:indexType is 1015ifdef::VK_EXT_index_type_uint8[] 1016ename:VK_INDEX_TYPE_UINT8_EXT or 1017endif::VK_EXT_index_type_uint8[] 1018ename:VK_INDEX_TYPE_UINT16) and have pname:vertexOffset added to them, 1019before being supplied as the code:vertexIndex value. 1020 1021The primitives are drawn pname:instanceCount times with code:instanceIndex 1022starting with pname:firstInstance and increasing sequentially for each 1023instance. 1024The assembled primitives execute the bound graphics pipeline. 1025 1026.Valid Usage 1027**** 1028include::{chapters}/commonvalidity/draw_common.adoc[] 1029include::{chapters}/commonvalidity/draw_dispatch_nonindirect_common.adoc[] 1030include::{chapters}/commonvalidity/draw_vertex_binding.adoc[] 1031include::{chapters}/commonvalidity/draw_indexed_common.adoc[] 1032include::{chapters}/commonvalidity/draw_index_binding.adoc[] 1033**** 1034 1035include::{generated}/validity/protos/vkCmdDrawIndexed.adoc[] 1036-- 1037 1038ifdef::VK_EXT_multi_draw[] 1039[open,refpage='vkCmdDrawMultiEXT',desc='Draw primitives',type='protos'] 1040-- 1041:refpage: vkCmdDrawMultiEXT 1042 1043To record an ordered sequence of draws which have no state changes between 1044them, call: 1045 1046include::{generated}/api/protos/vkCmdDrawMultiEXT.adoc[] 1047 1048 * pname:commandBuffer is the command buffer into which the command is 1049 recorded. 1050 * pname:drawCount is the number of draws to execute, and can: be zero. 1051 * pname:pVertexInfo is a pointer to an array of slink:VkMultiDrawInfoEXT 1052 with vertex information to be drawn. 1053 * pname:instanceCount is the number of instances per draw. 1054 * pname:firstInstance is the instance ID of the first instance in each 1055 draw. 1056 * pname:stride is the byte stride between consecutive elements of 1057 pname:pVertexInfo. 1058 1059The number of draws recorded is pname:drawCount, with each draw reading, 1060sequentially, a pname:firstVertex and a pname:vertexCount from 1061pname:pVertexInfo. 1062For each recorded draw, primitives are assembled as for flink:vkCmdDraw, and 1063drawn pname:instanceCount times with code:instanceIndex starting with 1064pname:firstInstance and sequentially for each instance. 1065 1066.Valid Usage 1067**** 1068include::{chapters}/commonvalidity/draw_common.adoc[] 1069include::{chapters}/commonvalidity/draw_dispatch_nonindirect_common.adoc[] 1070include::{chapters}/commonvalidity/draw_vertex_binding.adoc[] 1071 * [[VUID-vkCmdDrawMultiEXT-None-04933]] 1072 The <<features-multiDraw, pname:multiDraw>> feature must: be enabled 1073 * [[VUID-vkCmdDrawMultiEXT-drawCount-04934]] 1074 pname:drawCount must: be less than 1075 sname:VkPhysicalDeviceMultiDrawPropertiesEXT::pname:maxMultiDrawCount 1076 * [[VUID-vkCmdDrawMultiEXT-drawCount-04935]] 1077 If pname:drawCount is greater than zero, pname:pVertexInfo must: be a 1078 valid pointer to memory containing one or more valid instances of 1079 slink:VkMultiDrawInfoEXT structures 1080 * [[VUID-vkCmdDrawMultiEXT-stride-04936]] 1081 pname:stride must be a multiple of 4 1082**** 1083 1084include::{generated}/validity/protos/vkCmdDrawMultiEXT.adoc[] 1085-- 1086 1087[open,refpage='vkCmdDrawMultiIndexedEXT',desc='Draw primitives',type='protos'] 1088-- 1089:refpage: vkCmdDrawMultiIndexedEXT 1090 1091To record an ordered sequence of indexed draws which have no state changes 1092between them, call: 1093 1094include::{generated}/api/protos/vkCmdDrawMultiIndexedEXT.adoc[] 1095 1096 * pname:commandBuffer is the command buffer into which the command is 1097 recorded. 1098 * pname:drawCount is the number of draws to execute, and can: be zero. 1099 * pname:pIndexInfo is a pointer to an array of 1100 slink:VkMultiDrawIndexedInfoEXT with index information to be drawn. 1101 * pname:instanceCount is the number of instances per draw. 1102 * pname:firstInstance is the instance ID of the first instance in each 1103 draw. 1104 * pname:stride is the byte stride between consecutive elements of 1105 pname:pIndexInfo. 1106 * pname:pVertexOffset is `NULL` or a pointer to the value added to the 1107 vertex index before indexing into the vertex buffer. 1108 When specified, sname:VkMultiDrawIndexedInfoEXT::pname:offset is 1109 ignored. 1110 1111The number of draws recorded is pname:drawCount, with each draw reading, 1112sequentially, a pname:firstIndex and an pname:indexCount from 1113pname:pIndexInfo. 1114For each recorded draw, primitives are assembled as for 1115flink:vkCmdDrawIndexed, and drawn pname:instanceCount times with 1116code:instanceIndex starting with pname:firstInstance and sequentially for 1117each instance. 1118If pname:pVertexOffset is `NULL`, a pname:vertexOffset is also read from 1119pname:pIndexInfo, otherwise the value from dereferencing pname:pVertexOffset 1120is used. 1121 1122.Valid Usage 1123**** 1124include::{chapters}/commonvalidity/draw_common.adoc[] 1125include::{chapters}/commonvalidity/draw_dispatch_nonindirect_common.adoc[] 1126include::{chapters}/commonvalidity/draw_vertex_binding.adoc[] 1127include::{chapters}/commonvalidity/draw_indexed_common.adoc[] 1128include::{chapters}/commonvalidity/draw_index_binding.adoc[] 1129 * [[VUID-vkCmdDrawMultiIndexedEXT-None-04937]] 1130 The <<features-multiDraw, pname:multiDraw>> feature must: be enabled 1131 * [[VUID-vkCmdDrawMultiIndexedEXT-drawCount-04939]] 1132 pname:drawCount must: be less than 1133 sname:VkPhysicalDeviceMultiDrawPropertiesEXT::pname:maxMultiDrawCount 1134 * [[VUID-vkCmdDrawMultiIndexedEXT-drawCount-04940]] 1135 If pname:drawCount is greater than zero, pname:pIndexInfo must: be a 1136 valid pointer to memory containing one or more valid instances of 1137 slink:VkMultiDrawIndexedInfoEXT structures 1138 * [[VUID-vkCmdDrawMultiIndexedEXT-stride-04941]] 1139 pname:stride must be a multiple of 4 1140**** 1141 1142include::{generated}/validity/protos/vkCmdDrawMultiIndexedEXT.adoc[] 1143-- 1144 1145[open,refpage='VkMultiDrawInfoEXT',desc='Structure specifying a multi-draw command',type='structs',xrefs='vkCmdDrawMultiEXT'] 1146-- 1147The sname:VkMultiDrawInfoEXT structure is defined as: 1148 1149include::{generated}/api/structs/VkMultiDrawInfoEXT.adoc[] 1150 1151 * pname:firstVertex is the first vertex to draw. 1152 * pname:vertexCount is the number of vertices to draw. 1153 1154The members of sname:VkMultiDrawInfoEXT have the same meaning as the 1155pname:firstVertex and pname:vertexCount parameters in flink:vkCmdDraw. 1156 1157include::{generated}/validity/structs/VkMultiDrawInfoEXT.adoc[] 1158-- 1159 1160[open,refpage='VkMultiDrawIndexedInfoEXT',desc='Structure specifying a multi-draw command',type='structs',xrefs='vkCmdDrawMultiIndexedEXT'] 1161-- 1162The sname:VkMultiDrawIndexedInfoEXT structure is defined as: 1163 1164include::{generated}/api/structs/VkMultiDrawIndexedInfoEXT.adoc[] 1165 1166 * pname:firstIndex is the first index to draw. 1167 * pname:indexCount is the number of vertices to draw. 1168 * pname:vertexOffset is the value added to the vertex index before 1169 indexing into the vertex buffer for indexed multidraws. 1170 1171The pname:firstIndex, pname:indexCount, and pname:vertexOffset members of 1172sname:VkMultiDrawIndexedInfoEXT have the same meaning as the 1173pname:firstIndex, pname:indexCount, and pname:vertexOffset parameters, 1174respectively, of flink:vkCmdDrawIndexed. 1175 1176include::{generated}/validity/structs/VkMultiDrawIndexedInfoEXT.adoc[] 1177 1178-- 1179endif::VK_EXT_multi_draw[] 1180 1181[open,refpage='vkCmdDrawIndirect',desc='Draw primitives with indirect parameters',type='protos'] 1182-- 1183:refpage: vkCmdDrawIndirect 1184 1185To record a non-indexed indirect drawing command, call: 1186 1187include::{generated}/api/protos/vkCmdDrawIndirect.adoc[] 1188 1189 * pname:commandBuffer is the command buffer into which the command is 1190 recorded. 1191 * pname:buffer is the buffer containing draw parameters. 1192 * pname:offset is the byte offset into pname:buffer where parameters 1193 begin. 1194 * pname:drawCount is the number of draws to execute, and can: be zero. 1195 * pname:stride is the byte stride between successive sets of draw 1196 parameters. 1197 1198fname:vkCmdDrawIndirect behaves similarly to flink:vkCmdDraw except that the 1199parameters are read by the device from a buffer during execution. 1200pname:drawCount draws are executed by the command, with parameters taken 1201from pname:buffer starting at pname:offset and increasing by pname:stride 1202bytes for each successive draw. 1203The parameters of each draw are encoded in an array of 1204slink:VkDrawIndirectCommand structures. 1205If pname:drawCount is less than or equal to one, pname:stride is ignored. 1206 1207.Valid Usage 1208**** 1209include::{chapters}/commonvalidity/draw_common.adoc[] 1210include::{chapters}/commonvalidity/draw_vertex_binding.adoc[] 1211include::{chapters}/commonvalidity/draw_dispatch_indirect_common.adoc[] 1212include::{chapters}/commonvalidity/draw_indirect_drawcount.adoc[] 1213 * [[VUID-vkCmdDrawIndirect-drawCount-00476]] 1214 If pname:drawCount is greater than `1`, pname:stride must: be a multiple 1215 of `4` and must: be greater than or equal to 1216 code:sizeof(sname:VkDrawIndirectCommand) 1217 * [[VUID-vkCmdDrawIndirect-drawCount-00487]] 1218 If pname:drawCount is equal to `1`, [eq]#(pname:offset {plus} 1219 code:sizeof(slink:VkDrawIndirectCommand))# must: be less than or equal 1220 to the size of pname:buffer 1221 * [[VUID-vkCmdDrawIndirect-drawCount-00488]] 1222 If pname:drawCount is greater than `1`, [eq]#(pname:stride {times} 1223 (pname:drawCount - 1) {plus} pname:offset {plus} 1224 code:sizeof(slink:VkDrawIndirectCommand))# must: be less than or equal 1225 to the size of pname:buffer 1226**** 1227 1228include::{generated}/validity/protos/vkCmdDrawIndirect.adoc[] 1229-- 1230 1231[open,refpage='VkDrawIndirectCommand',desc='Structure specifying a indirect drawing command',type='structs',xrefs='vkCmdDrawIndirect'] 1232-- 1233The sname:VkDrawIndirectCommand structure is defined as: 1234 1235include::{generated}/api/structs/VkDrawIndirectCommand.adoc[] 1236 1237 * pname:vertexCount is the number of vertices to draw. 1238 * pname:instanceCount is the number of instances to draw. 1239 * pname:firstVertex is the index of the first vertex to draw. 1240 * pname:firstInstance is the instance ID of the first instance to draw. 1241 1242The members of sname:VkDrawIndirectCommand have the same meaning as the 1243similarly named parameters of flink:vkCmdDraw. 1244 1245.Valid Usage 1246**** 1247 * [[VUID-VkDrawIndirectCommand-None-00500]] 1248 For a given vertex buffer binding, any attribute data fetched must: be 1249 entirely contained within the corresponding vertex buffer binding, as 1250 described in <<fxvertex-input>> 1251 * [[VUID-VkDrawIndirectCommand-firstInstance-00501]] 1252 If the <<features-drawIndirectFirstInstance, 1253 pname:drawIndirectFirstInstance>> feature is not enabled, 1254 pname:firstInstance must: be code:0 1255**** 1256 1257include::{generated}/validity/structs/VkDrawIndirectCommand.adoc[] 1258-- 1259 1260ifdef::VK_VERSION_1_2,VK_KHR_draw_indirect_count[] 1261[open,refpage='vkCmdDrawIndirectCount',desc='Draw primitives with indirect parameters and draw count',type='protos',alias='vkCmdDrawIndirectCountKHR vkCmdDrawIndirectCountAMD'] 1262-- 1263:refpage: vkCmdDrawIndirectCount 1264 1265To record a non-indexed draw call with a draw call count sourced from a 1266buffer, call: 1267 1268ifdef::VK_VERSION_1_2[] 1269include::{generated}/api/protos/vkCmdDrawIndirectCount.adoc[] 1270endif::VK_VERSION_1_2[] 1271 1272// Jon: conditional logic on connective clauses with 3 forms of the command including VK_VERSION_1_2 needs work. 1273ifdef::VK_VERSION_1_2+VK_KHR_draw_indirect_count[or the equivalent command] 1274 1275ifdef::VK_KHR_draw_indirect_count[] 1276include::{generated}/api/protos/vkCmdDrawIndirectCountKHR.adoc[] 1277endif::VK_KHR_draw_indirect_count[] 1278 1279ifdef::VK_KHR_draw_indirect_count+VK_AMD_draw_indirect_count[or the equivalent command] 1280 1281ifdef::VK_AMD_draw_indirect_count[] 1282include::{generated}/api/protos/vkCmdDrawIndirectCountAMD.adoc[] 1283endif::VK_AMD_draw_indirect_count[] 1284 1285 * pname:commandBuffer is the command buffer into which the command is 1286 recorded. 1287 * pname:buffer is the buffer containing draw parameters. 1288 * pname:offset is the byte offset into pname:buffer where parameters 1289 begin. 1290 * pname:countBuffer is the buffer containing the draw count. 1291 * pname:countBufferOffset is the byte offset into pname:countBuffer where 1292 the draw count begins. 1293 * pname:maxDrawCount specifies the maximum number of draws that will be 1294 executed. 1295 The actual number of executed draw calls is the minimum of the count 1296 specified in pname:countBuffer and pname:maxDrawCount. 1297 * pname:stride is the byte stride between successive sets of draw 1298 parameters. 1299 1300fname:vkCmdDrawIndirectCount behaves similarly to flink:vkCmdDrawIndirect 1301except that the draw count is read by the device from a buffer during 1302execution. 1303The command will read an unsigned 32-bit integer from pname:countBuffer 1304located at pname:countBufferOffset and use this as the draw count. 1305 1306.Valid Usage 1307**** 1308include::{chapters}/commonvalidity/draw_common.adoc[] 1309include::{chapters}/commonvalidity/draw_vertex_binding.adoc[] 1310include::{chapters}/commonvalidity/draw_dispatch_indirect_common.adoc[] 1311include::{chapters}/commonvalidity/draw_indirect_count_common.adoc[] 1312 * [[VUID-vkCmdDrawIndirectCount-stride-03110]] 1313 pname:stride must: be a multiple of `4` and must: be greater than or 1314 equal to sizeof(sname:VkDrawIndirectCommand) 1315 * [[VUID-vkCmdDrawIndirectCount-maxDrawCount-03111]] 1316 If pname:maxDrawCount is greater than or equal to `1`, 1317 [eq]#(pname:stride {times} (pname:maxDrawCount - 1) {plus} pname:offset 1318 {plus} sizeof(sname:VkDrawIndirectCommand))# must: be less than or equal 1319 to the size of pname:buffer 1320 * [[VUID-vkCmdDrawIndirectCount-countBuffer-03121]] 1321 If the count stored in pname:countBuffer is equal to `1`, 1322 [eq]#(pname:offset {plus} sizeof(sname:VkDrawIndirectCommand))# must: be 1323 less than or equal to the size of pname:buffer 1324 * [[VUID-vkCmdDrawIndirectCount-countBuffer-03122]] 1325 If the count stored in pname:countBuffer is greater than `1`, 1326 [eq]#(pname:stride {times} (pname:drawCount - 1) {plus} pname:offset 1327 {plus} sizeof(sname:VkDrawIndirectCommand))# must: be less than or equal 1328 to the size of pname:buffer 1329**** 1330 1331include::{generated}/validity/protos/vkCmdDrawIndirectCount.adoc[] 1332 1333-- 1334endif::VK_VERSION_1_2,VK_KHR_draw_indirect_count[] 1335 1336[open,refpage='vkCmdDrawIndexedIndirect',desc='Draw primitives with indirect parameters and indexed vertices',type='protos'] 1337-- 1338:refpage: vkCmdDrawIndexedIndirect 1339 1340To record an indexed indirect drawing command, call: 1341 1342include::{generated}/api/protos/vkCmdDrawIndexedIndirect.adoc[] 1343 1344 * pname:commandBuffer is the command buffer into which the command is 1345 recorded. 1346 * pname:buffer is the buffer containing draw parameters. 1347 * pname:offset is the byte offset into pname:buffer where parameters 1348 begin. 1349 * pname:drawCount is the number of draws to execute, and can: be zero. 1350 * pname:stride is the byte stride between successive sets of draw 1351 parameters. 1352 1353fname:vkCmdDrawIndexedIndirect behaves similarly to flink:vkCmdDrawIndexed 1354except that the parameters are read by the device from a buffer during 1355execution. 1356pname:drawCount draws are executed by the command, with parameters taken 1357from pname:buffer starting at pname:offset and increasing by pname:stride 1358bytes for each successive draw. 1359The parameters of each draw are encoded in an array of 1360slink:VkDrawIndexedIndirectCommand structures. 1361If pname:drawCount is less than or equal to one, pname:stride is ignored. 1362 1363.Valid Usage 1364**** 1365include::{chapters}/commonvalidity/draw_common.adoc[] 1366include::{chapters}/commonvalidity/draw_vertex_binding.adoc[] 1367include::{chapters}/commonvalidity/draw_dispatch_indirect_common.adoc[] 1368include::{chapters}/commonvalidity/draw_indirect_drawcount.adoc[] 1369include::{chapters}/commonvalidity/draw_indexed_common.adoc[] 1370 * [[VUID-vkCmdDrawIndexedIndirect-drawCount-00528]] 1371 If pname:drawCount is greater than `1`, pname:stride must: be a multiple 1372 of `4` and must: be greater than or equal to 1373 code:sizeof(sname:VkDrawIndexedIndirectCommand) 1374 * [[VUID-vkCmdDrawIndexedIndirect-drawCount-00539]] 1375 If pname:drawCount is equal to `1`, [eq]#(pname:offset {plus} 1376 code:sizeof(sname:VkDrawIndexedIndirectCommand))# must: be less than or 1377 equal to the size of pname:buffer 1378 * [[VUID-vkCmdDrawIndexedIndirect-drawCount-00540]] 1379 If pname:drawCount is greater than `1`, [eq]#(pname:stride {times} 1380 (pname:drawCount - 1) {plus} pname:offset {plus} 1381 code:sizeof(sname:VkDrawIndexedIndirectCommand))# must: be less than or 1382 equal to the size of pname:buffer 1383**** 1384 1385include::{generated}/validity/protos/vkCmdDrawIndexedIndirect.adoc[] 1386-- 1387 1388[open,refpage='VkDrawIndexedIndirectCommand',desc='Structure specifying a indexed indirect drawing command',type='structs',xrefs='vkCmdDrawIndexedIndirect'] 1389-- 1390:refpage: VkDrawIndexedIndirectCommand 1391 1392The sname:VkDrawIndexedIndirectCommand structure is defined as: 1393 1394include::{generated}/api/structs/VkDrawIndexedIndirectCommand.adoc[] 1395 1396 * pname:indexCount is the number of vertices to draw. 1397 * pname:instanceCount is the number of instances to draw. 1398 * pname:firstIndex is the base index within the index buffer. 1399 * pname:vertexOffset is the value added to the vertex index before 1400 indexing into the vertex buffer. 1401 * pname:firstInstance is the instance ID of the first instance to draw. 1402 1403The members of sname:VkDrawIndexedIndirectCommand have the same meaning as 1404the similarly named parameters of flink:vkCmdDrawIndexed. 1405 1406.Valid Usage 1407**** 1408include::{chapters}/commonvalidity/draw_index_binding.adoc[] 1409 * [[VUID-VkDrawIndexedIndirectCommand-None-00552]] 1410 For a given vertex buffer binding, any attribute data fetched must: be 1411 entirely contained within the corresponding vertex buffer binding, as 1412 described in <<fxvertex-input>> 1413 * [[VUID-VkDrawIndexedIndirectCommand-firstInstance-00554]] 1414 If the <<features-drawIndirectFirstInstance, 1415 pname:drawIndirectFirstInstance>> feature is not enabled, 1416 pname:firstInstance must: be code:0 1417**** 1418 1419include::{generated}/validity/structs/VkDrawIndexedIndirectCommand.adoc[] 1420-- 1421 1422ifdef::VK_VERSION_1_2,VK_KHR_draw_indirect_count[] 1423[open,refpage='vkCmdDrawIndexedIndirectCount',desc='Draw parameters with indirect parameters, indexed vertices, and draw count',type='protos',alias='vkCmdDrawIndexedIndirectCountKHR vkCmdDrawIndexedIndirectCountAMD'] 1424-- 1425:refpage: vkCmdDrawIndexedIndirectCount 1426 1427To record an indexed draw call with a draw call count sourced from a buffer, 1428call: 1429 1430ifdef::VK_VERSION_1_2[] 1431include::{generated}/api/protos/vkCmdDrawIndexedIndirectCount.adoc[] 1432endif::VK_VERSION_1_2[] 1433 1434// Jon: conditional logic on connective clauses with 3 forms of the command including VK_VERSION_1_2 needs work. 1435ifdef::VK_VERSION_1_2+VK_KHR_draw_indirect_count[or the equivalent command] 1436 1437ifdef::VK_KHR_draw_indirect_count[] 1438include::{generated}/api/protos/vkCmdDrawIndexedIndirectCountKHR.adoc[] 1439endif::VK_KHR_draw_indirect_count[] 1440 1441ifdef::VK_KHR_draw_indirect_count+VK_AMD_draw_indirect_count[or the equivalent command] 1442 1443ifdef::VK_AMD_draw_indirect_count[] 1444include::{generated}/api/protos/vkCmdDrawIndexedIndirectCountAMD.adoc[] 1445endif::VK_AMD_draw_indirect_count[] 1446 1447 * pname:commandBuffer is the command buffer into which the command is 1448 recorded. 1449 * pname:buffer is the buffer containing draw parameters. 1450 * pname:offset is the byte offset into pname:buffer where parameters 1451 begin. 1452 * pname:countBuffer is the buffer containing the draw count. 1453 * pname:countBufferOffset is the byte offset into pname:countBuffer where 1454 the draw count begins. 1455 * pname:maxDrawCount specifies the maximum number of draws that will be 1456 executed. 1457 The actual number of executed draw calls is the minimum of the count 1458 specified in pname:countBuffer and pname:maxDrawCount. 1459 * pname:stride is the byte stride between successive sets of draw 1460 parameters. 1461 1462fname:vkCmdDrawIndexedIndirectCount behaves similarly to 1463flink:vkCmdDrawIndexedIndirect except that the draw count is read by the 1464device from a buffer during execution. 1465The command will read an unsigned 32-bit integer from pname:countBuffer 1466located at pname:countBufferOffset and use this as the draw count. 1467 1468.Valid Usage 1469**** 1470include::{chapters}/commonvalidity/draw_common.adoc[] 1471include::{chapters}/commonvalidity/draw_vertex_binding.adoc[] 1472include::{chapters}/commonvalidity/draw_dispatch_indirect_common.adoc[] 1473include::{chapters}/commonvalidity/draw_indirect_count_common.adoc[] 1474include::{chapters}/commonvalidity/draw_indexed_common.adoc[] 1475 * [[VUID-vkCmdDrawIndexedIndirectCount-stride-03142]] 1476 pname:stride must: be a multiple of `4` and must: be greater than or 1477 equal to sizeof(sname:VkDrawIndexedIndirectCommand) 1478 * [[VUID-vkCmdDrawIndexedIndirectCount-maxDrawCount-03143]] 1479 If pname:maxDrawCount is greater than or equal to `1`, 1480 [eq]#(pname:stride {times} (pname:maxDrawCount - 1) {plus} pname:offset 1481 {plus} sizeof(sname:VkDrawIndexedIndirectCommand))# must: be less than 1482 or equal to the size of pname:buffer 1483 * [[VUID-vkCmdDrawIndexedIndirectCount-countBuffer-03153]] 1484 If count stored in pname:countBuffer is equal to `1`, [eq]#(pname:offset 1485 {plus} sizeof(sname:VkDrawIndexedIndirectCommand))# must: be less than 1486 or equal to the size of pname:buffer 1487 * [[VUID-vkCmdDrawIndexedIndirectCount-countBuffer-03154]] 1488 If count stored in pname:countBuffer is greater than `1`, 1489 [eq]#(pname:stride {times} (pname:drawCount - 1) {plus} pname:offset 1490 {plus} sizeof(sname:VkDrawIndexedIndirectCommand))# must: be less than 1491 or equal to the size of pname:buffer 1492**** 1493 1494include::{generated}/validity/protos/vkCmdDrawIndexedIndirectCount.adoc[] 1495-- 1496endif::VK_VERSION_1_2,VK_KHR_draw_indirect_count[] 1497 1498 1499ifdef::VK_EXT_transform_feedback[] 1500[[drawing-transform-feedback]] 1501=== Drawing Transform Feedback 1502 1503It is possible to draw vertex data that was previously captured during 1504active <<vertexpostproc-transform-feedback,transform feedback>> by binding 1505one or more of the transform feedback buffers as vertex buffers. 1506A pipeline barrier is required between using the buffers as transform 1507feedback buffers and vertex buffers to ensure all writes to the transform 1508feedback buffers are visible when the data is read as vertex attributes. 1509The source access is ename:VK_ACCESS_TRANSFORM_FEEDBACK_WRITE_BIT_EXT and 1510the destination access is ename:VK_ACCESS_VERTEX_ATTRIBUTE_READ_BIT for the 1511pipeline stages ename:VK_PIPELINE_STAGE_TRANSFORM_FEEDBACK_BIT_EXT and 1512ename:VK_PIPELINE_STAGE_VERTEX_INPUT_BIT respectively. 1513The value written to the counter buffer by 1514flink:vkCmdEndTransformFeedbackEXT can: be used to determine the vertex 1515count for the draw. 1516A pipeline barrier is required between using the counter buffer for 1517fname:vkCmdEndTransformFeedbackEXT and fname:vkCmdDrawIndirectByteCountEXT 1518where the source access is 1519ename:VK_ACCESS_TRANSFORM_FEEDBACK_COUNTER_WRITE_BIT_EXT and the destination 1520access is ename:VK_ACCESS_INDIRECT_COMMAND_READ_BIT for the pipeline stages 1521ename:VK_PIPELINE_STAGE_TRANSFORM_FEEDBACK_BIT_EXT and 1522ename:VK_PIPELINE_STAGE_DRAW_INDIRECT_BIT respectively. 1523 1524[open,refpage='vkCmdDrawIndirectByteCountEXT',desc='Draw primitives with indirect parameters where the vertex count is derived from the counter byte value in the counter buffer',type='protos'] 1525-- 1526:refpage: vkCmdDrawIndirectByteCountEXT 1527 1528To record a non-indexed draw call, where the vertex count is based on a byte 1529count read from a buffer and the passed in vertex stride parameter, call: 1530 1531include::{generated}/api/protos/vkCmdDrawIndirectByteCountEXT.adoc[] 1532 1533 * pname:commandBuffer is the command buffer into which the command is 1534 recorded. 1535 * pname:instanceCount is the number of instances to draw. 1536 * pname:firstInstance is the instance ID of the first instance to draw. 1537 * pname:counterBuffer is the buffer handle from where the byte count is 1538 read. 1539 * pname:counterBufferOffset is the offset into the buffer used to read the 1540 byte count, which is used to calculate the vertex count for this draw 1541 call. 1542 * pname:counterOffset is subtracted from the byte count read from the 1543 pname:counterBuffer at the pname:counterBufferOffset 1544 * pname:vertexStride is the stride in bytes between each element of the 1545 vertex data that is used to calculate the vertex count from the counter 1546 value. 1547 This value is typically the same value that was used in the graphics 1548 pipeline state when the transform feedback was captured as the 1549 code:XfbStride. 1550 1551When the command is executed, primitives are assembled in the same way as 1552done with flink:vkCmdDraw except the pname:vertexCount is calculated based 1553on the byte count read from pname:counterBuffer at offset 1554pname:counterBufferOffset. 1555The assembled primitives execute the bound graphics pipeline. 1556 1557The effective pname:vertexCount is calculated as follows: 1558 1559[source,c] 1560---- 1561const uint32_t * counterBufferPtr = (const uint8_t *)counterBuffer.address + counterBufferOffset; 1562vertexCount = floor(max(0, (*counterBufferPtr - counterOffset)) / vertexStride); 1563---- 1564 1565The effective pname:firstVertex is zero. 1566 1567.Valid Usage 1568**** 1569include::{chapters}/commonvalidity/draw_common.adoc[] 1570include::{chapters}/commonvalidity/draw_vertex_binding.adoc[] 1571 * [[VUID-vkCmdDrawIndirectByteCountEXT-transformFeedback-02287]] 1572 sname:VkPhysicalDeviceTransformFeedbackFeaturesEXT::pname:transformFeedback 1573 must: be enabled 1574 * [[VUID-vkCmdDrawIndirectByteCountEXT-transformFeedbackDraw-02288]] 1575 The implementation must: support 1576 sname:VkPhysicalDeviceTransformFeedbackPropertiesEXT::pname:transformFeedbackDraw 1577 * [[VUID-vkCmdDrawIndirectByteCountEXT-vertexStride-02289]] 1578 pname:vertexStride must: be greater than 0 and less than or equal to 1579 sname:VkPhysicalDeviceTransformFeedbackPropertiesEXT::pname:maxTransformFeedbackBufferDataStride 1580 * [[VUID-vkCmdDrawIndirectByteCountEXT-counterBuffer-04567]] 1581 If pname:counterBuffer is non-sparse then it must: be bound completely 1582 and contiguously to a single sname:VkDeviceMemory object 1583 * [[VUID-vkCmdDrawIndirectByteCountEXT-counterBuffer-02290]] 1584 pname:counterBuffer must: have been created with the 1585 ename:VK_BUFFER_USAGE_INDIRECT_BUFFER_BIT bit set 1586 * [[VUID-vkCmdDrawIndirectByteCountEXT-counterBufferOffset-04568]] 1587 pname:counterBufferOffset must: be a multiple of `4` 1588ifdef::VK_VERSION_1_1[] 1589 * [[VUID-vkCmdDrawIndirectByteCountEXT-commandBuffer-02646]] 1590 pname:commandBuffer must: not be a protected command buffer 1591endif::VK_VERSION_1_1[] 1592**** 1593 1594include::{generated}/validity/protos/vkCmdDrawIndirectByteCountEXT.adoc[] 1595-- 1596endif::VK_EXT_transform_feedback[] 1597 1598 1599ifdef::VK_EXT_conditional_rendering[] 1600[[drawing-conditional-rendering]] 1601== Conditional Rendering 1602 1603Certain rendering commands can: be executed conditionally based on a value 1604in buffer memory. 1605These rendering commands are limited to <<drawing,drawing commands>>, 1606<<dispatch,dispatching commands>>, and clearing attachments with 1607flink:vkCmdClearAttachments within a conditional rendering block which is 1608defined by commands flink:vkCmdBeginConditionalRenderingEXT and 1609flink:vkCmdEndConditionalRenderingEXT. 1610Other rendering commands remain unaffected by conditional rendering. 1611 1612[[active-conditional-rendering]] 1613After beginning conditional rendering, it is considered _active_ within the 1614command buffer it was called until it is ended with 1615flink:vkCmdEndConditionalRenderingEXT. 1616 1617Conditional rendering must: begin and end in the same command buffer. 1618When conditional rendering is active, a primary command buffer can: execute 1619secondary command buffers if the <<features-inheritedConditionalRendering, 1620pname:inheritedConditionalRendering>> feature is enabled. 1621For a secondary command buffer to be executed while conditional rendering is 1622active in the primary command buffer, it must: set the 1623pname:conditionalRenderingEnable flag of 1624slink:VkCommandBufferInheritanceConditionalRenderingInfoEXT, as described in 1625the <<commandbuffers-recording, Command Buffer Recording>> section. 1626 1627Conditional rendering must: also either begin and end inside the same 1628subpass of a render pass instance, or must: both begin and end outside of a 1629render pass instance (i.e. contain entire render pass instances). 1630 1631[open,refpage='vkCmdBeginConditionalRenderingEXT',desc='Define the beginning of a conditional rendering block',type='protos'] 1632-- 1633To begin conditional rendering, call: 1634 1635include::{generated}/api/protos/vkCmdBeginConditionalRenderingEXT.adoc[] 1636 1637 * pname:commandBuffer is the command buffer into which this command will 1638 be recorded. 1639 * pname:pConditionalRenderingBegin is a pointer to a 1640 slink:VkConditionalRenderingBeginInfoEXT structure specifying parameters 1641 of conditional rendering. 1642 1643.Valid Usage 1644**** 1645 * [[VUID-vkCmdBeginConditionalRenderingEXT-None-01980]] 1646 Conditional rendering must: not already be 1647 <<active-conditional-rendering,active>> 1648**** 1649 1650include::{generated}/validity/protos/vkCmdBeginConditionalRenderingEXT.adoc[] 1651-- 1652 1653[open,refpage='VkConditionalRenderingBeginInfoEXT',desc='Structure specifying conditional rendering begin information',type='structs'] 1654-- 1655The sname:VkConditionalRenderingBeginInfoEXT structure is defined as: 1656 1657include::{generated}/api/structs/VkConditionalRenderingBeginInfoEXT.adoc[] 1658 1659 * pname:sType is a elink:VkStructureType value identifying this structure. 1660 * pname:pNext is `NULL` or a pointer to a structure extending this 1661 structure. 1662 * pname:buffer is a buffer containing the predicate for conditional 1663 rendering. 1664 * pname:offset is the byte offset into pname:buffer where the predicate is 1665 located. 1666 * pname:flags is a bitmask of tlink:VkConditionalRenderingFlagsEXT 1667 specifying the behavior of conditional rendering. 1668 1669If the 32-bit value at pname:offset in pname:buffer memory is zero, then the 1670rendering commands are discarded, otherwise they are executed as normal. 1671If the value of the predicate in buffer memory changes while conditional 1672rendering is active, the rendering commands may: be discarded in an 1673implementation-dependent way. 1674Some implementations may latch the value of the predicate upon beginning 1675conditional rendering while others may read it before every rendering 1676command. 1677 1678.Valid Usage 1679**** 1680 * [[VUID-VkConditionalRenderingBeginInfoEXT-buffer-01981]] 1681 If pname:buffer is non-sparse then it must: be bound completely and 1682 contiguously to a single sname:VkDeviceMemory object 1683 * [[VUID-VkConditionalRenderingBeginInfoEXT-buffer-01982]] 1684 pname:buffer must: have been created with the 1685 ename:VK_BUFFER_USAGE_CONDITIONAL_RENDERING_BIT_EXT bit set 1686 * [[VUID-VkConditionalRenderingBeginInfoEXT-offset-01983]] 1687 pname:offset must: be less than the size of pname:buffer by at least 32 1688 bits 1689 * [[VUID-VkConditionalRenderingBeginInfoEXT-offset-01984]] 1690 pname:offset must: be a multiple of 4 1691**** 1692 1693include::{generated}/validity/structs/VkConditionalRenderingBeginInfoEXT.adoc[] 1694-- 1695 1696[open,refpage='VkConditionalRenderingFlagBitsEXT',desc='Specify the behavior of conditional rendering',type='enums'] 1697-- 1698Bits which can: be set in 1699flink:vkCmdBeginConditionalRenderingEXT::pname:flags, specifying the 1700behavior of conditional rendering, are: 1701 1702include::{generated}/api/enums/VkConditionalRenderingFlagBitsEXT.adoc[] 1703 1704 * ename:VK_CONDITIONAL_RENDERING_INVERTED_BIT_EXT specifies the condition 1705 used to determine whether to discard rendering commands or not. 1706 That is, if the 32-bit predicate read from pname:buffer memory at 1707 pname:offset is zero, the rendering commands are not discarded, and if 1708 non zero, then they are discarded. 1709-- 1710 1711[open,refpage='VkConditionalRenderingFlagsEXT',desc='Bitmask of VkConditionalRenderingFlagBitsEXT',type='flags'] 1712-- 1713include::{generated}/api/flags/VkConditionalRenderingFlagsEXT.adoc[] 1714 1715tname:VkConditionalRenderingFlagsEXT is a bitmask type for setting a mask of 1716zero or more elink:VkConditionalRenderingFlagBitsEXT. 1717-- 1718 1719[open,refpage='vkCmdEndConditionalRenderingEXT',desc='Define the end of a conditional rendering block',type='protos'] 1720-- 1721To end conditional rendering, call: 1722 1723include::{generated}/api/protos/vkCmdEndConditionalRenderingEXT.adoc[] 1724 1725 * pname:commandBuffer is the command buffer into which this command will 1726 be recorded. 1727 1728Once ended, conditional rendering becomes inactive. 1729 1730.Valid Usage 1731**** 1732 * [[VUID-vkCmdEndConditionalRenderingEXT-None-01985]] 1733 Conditional rendering must: be <<active-conditional-rendering,active>> 1734 * [[VUID-vkCmdEndConditionalRenderingEXT-None-01986]] 1735 If conditional rendering was made 1736 <<active-conditional-rendering,active>> outside of a render pass 1737 instance, it must: not be ended inside a render pass instance 1738 * [[VUID-vkCmdEndConditionalRenderingEXT-None-01987]] 1739 If conditional rendering was made 1740 <<active-conditional-rendering,active>> within a subpass it must: be 1741 ended in the same subpass 1742**** 1743 1744include::{generated}/validity/protos/vkCmdEndConditionalRenderingEXT.adoc[] 1745-- 1746endif::VK_EXT_conditional_rendering[] 1747 1748ifdef::VK_NV_mesh_shader,VK_EXT_mesh_shader[] 1749include::{chapters}/VK_NV_mesh_shader/drawing.adoc[] 1750endif::VK_NV_mesh_shader,VK_EXT_mesh_shader[] 1751 1752ifdef::VK_HUAWEI_cluster_culling_shader[] 1753include::{chapters}/VK_HUAWEI_cluster_culling_shader/drawing.adoc[] 1754endif::VK_HUAWEI_cluster_culling_shader[] 1755
