1// Copyright 2015-2024 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 870ifdef::VK_KHR_maintenance6[] 871If the <<features-maintenance6,pname:maintenance6>> feature is enabled, 872pname:buffer can: be dlink:VK_NULL_HANDLE. 873ifdef::VK_EXT_robustness2[] 874If pname:buffer is dlink:VK_NULL_HANDLE and the <<features-nullDescriptor, 875pname:nullDescriptor>> feature is enabled, every index fetched results in a 876value of zero. 877endif::VK_EXT_robustness2[] 878endif::VK_KHR_maintenance6[] 879 880.Valid Usage 881**** 882include::{chapters}/commonvalidity/bind_index_buffer_common.adoc[] 883**** 884 885include::{generated}/validity/protos/vkCmdBindIndexBuffer.adoc[] 886-- 887 888ifdef::VK_KHR_maintenance5[] 889[open,refpage='vkCmdBindIndexBuffer2KHR',desc='Bind an index buffer to a command buffer',type='protos'] 890-- 891:refpage: vkCmdBindIndexBuffer2KHR 892 893To bind an index buffer, along with its size, to a command buffer, call: 894 895include::{generated}/api/protos/vkCmdBindIndexBuffer2KHR.adoc[] 896 897 * pname:commandBuffer is the command buffer into which the command is 898 recorded. 899 * pname:buffer is the buffer being bound. 900 * pname:offset is the starting offset in bytes within pname:buffer used in 901 index buffer address calculations. 902 * pname:size is the size in bytes of index data bound from pname:buffer. 903 * pname:indexType is a elink:VkIndexType value specifying the size of the 904 indices. 905 906pname:size specifies the bound size of the index buffer starting from 907pname:offset. 908If pname:size is ename:VK_WHOLE_SIZE then the bound size is from 909pname:offset to the end of the pname:buffer. 910 911ifdef::VK_KHR_maintenance6[] 912If the <<features-maintenance6,pname:maintenance6>> feature is enabled, 913pname:buffer can: be dlink:VK_NULL_HANDLE. 914ifdef::VK_EXT_robustness2[] 915If pname:buffer is dlink:VK_NULL_HANDLE and the <<features-nullDescriptor, 916pname:nullDescriptor>> feature is enabled, every index fetched results in a 917value of zero. 918endif::VK_EXT_robustness2[] 919endif::VK_KHR_maintenance6[] 920 921.Valid Usage 922**** 923include::{chapters}/commonvalidity/bind_index_buffer_common.adoc[] 924 * [[VUID-vkCmdBindIndexBuffer2KHR-size-08767]] 925 If pname:size is not ename:VK_WHOLE_SIZE, pname:size must: be a multiple 926 of the size of the type indicated by pname:indexType 927 * [[VUID-vkCmdBindIndexBuffer2KHR-size-08768]] 928 If pname:size is not ename:VK_WHOLE_SIZE, the sum of pname:offset and 929 pname:size must: be less than or equal to the size of pname:buffer 930**** 931 932include::{generated}/validity/protos/vkCmdBindIndexBuffer2KHR.adoc[] 933-- 934endif::VK_KHR_maintenance5[] 935 936[open,refpage='VkIndexType',desc='Type of index buffer indices',type='enums'] 937-- 938Possible values of 939ifdef::VK_KHR_maintenance5[flink:vkCmdBindIndexBuffer2KHR::pname:indexType and] 940flink:vkCmdBindIndexBuffer::pname:indexType, specifying the size of indices, 941are: 942 943include::{generated}/api/enums/VkIndexType.adoc[] 944 945 * ename:VK_INDEX_TYPE_UINT16 specifies that indices are 16-bit unsigned 946 integer values. 947 * ename:VK_INDEX_TYPE_UINT32 specifies that indices are 32-bit unsigned 948 integer values. 949ifdef::VK_NV_ray_tracing,VK_KHR_acceleration_structure[] 950 * ename:VK_INDEX_TYPE_NONE_KHR specifies that no indices are provided. 951endif::VK_NV_ray_tracing,VK_KHR_acceleration_structure[] 952ifdef::VK_EXT_index_type_uint8[] 953 * ename:VK_INDEX_TYPE_UINT8_EXT specifies that indices are 8-bit unsigned 954 integer values. 955endif::VK_EXT_index_type_uint8[] 956-- 957 958The parameters for each drawing command are specified directly in the 959command or read from buffer memory, depending on the command. 960Drawing commands that source their parameters from buffer memory are known 961as _indirect_ drawing commands. 962 963All drawing commands interact with the <<features-robustBufferAccess, 964pname:robustBufferAccess>> feature. 965 966[open,refpage='vkCmdDraw',desc='Draw primitives',type='protos'] 967-- 968:refpage: vkCmdDraw 969 970To record a non-indexed draw, call: 971 972include::{generated}/api/protos/vkCmdDraw.adoc[] 973 974 * pname:commandBuffer is the command buffer into which the command is 975 recorded. 976 * pname:vertexCount is the number of vertices to draw. 977 * pname:instanceCount is the number of instances to draw. 978 * pname:firstVertex is the index of the first vertex to draw. 979 * pname:firstInstance is the instance ID of the first instance to draw. 980 981When the command is executed, primitives are assembled using the current 982primitive topology and pname:vertexCount consecutive vertex indices with the 983first code:vertexIndex value equal to pname:firstVertex. 984The primitives are drawn pname:instanceCount times with code:instanceIndex 985starting with pname:firstInstance and increasing sequentially for each 986instance. 987The assembled primitives execute the bound graphics pipeline. 988 989.Valid Usage 990**** 991include::{chapters}/commonvalidity/draw_common.adoc[] 992include::{chapters}/commonvalidity/draw_dispatch_nonindirect_common.adoc[] 993include::{chapters}/commonvalidity/draw_vertex_binding.adoc[] 994include::{chapters}/commonvalidity/draw_instance_common.adoc[] 995**** 996 997include::{generated}/validity/protos/vkCmdDraw.adoc[] 998-- 999 1000[open,refpage='vkCmdDrawIndexed',desc='Draw primitives with indexed vertices',type='protos'] 1001-- 1002:refpage: vkCmdDrawIndexed 1003 1004To record an indexed draw, call: 1005 1006include::{generated}/api/protos/vkCmdDrawIndexed.adoc[] 1007 1008 * pname:commandBuffer is the command buffer into which the command is 1009 recorded. 1010 * pname:indexCount is the number of vertices to draw. 1011 * pname:instanceCount is the number of instances to draw. 1012 * pname:firstIndex is the base index within the index buffer. 1013 * pname:vertexOffset is the value added to the vertex index before 1014 indexing into the vertex buffer. 1015 * pname:firstInstance is the instance ID of the first instance to draw. 1016 1017When the command is executed, primitives are assembled using the current 1018primitive topology and pname:indexCount vertices whose indices are retrieved 1019from the index buffer. 1020The index buffer is treated as an array of tightly packed unsigned integers 1021of size defined by the 1022ifdef::VK_KHR_maintenance5[flink:vkCmdBindIndexBuffer2KHR::pname:indexType or the] 1023flink:vkCmdBindIndexBuffer::pname:indexType parameter with which the buffer 1024was bound. 1025 1026The first vertex index is at an offset of [eq]#pname:firstIndex {times} 1027code:indexSize {plus} pname:offset# within the bound index buffer, where 1028pname:offset is the offset specified by fname:vkCmdBindIndexBuffer 1029ifdef::VK_KHR_maintenance5[or fname:vkCmdBindIndexBuffer2KHR,] 1030and code:indexSize is the byte size of the type specified by 1031pname:indexType. 1032Subsequent index values are retrieved from consecutive locations in the 1033index buffer. 1034Indices are first compared to the primitive restart value, then zero 1035extended to 32 bits (if the code:indexType is 1036ifdef::VK_EXT_index_type_uint8[] 1037ename:VK_INDEX_TYPE_UINT8_EXT or 1038endif::VK_EXT_index_type_uint8[] 1039ename:VK_INDEX_TYPE_UINT16) and have pname:vertexOffset added to them, 1040before being supplied as the code:vertexIndex value. 1041 1042The primitives are drawn pname:instanceCount times with code:instanceIndex 1043starting with pname:firstInstance and increasing sequentially for each 1044instance. 1045The assembled primitives execute the bound graphics pipeline. 1046 1047.Valid Usage 1048**** 1049include::{chapters}/commonvalidity/draw_common.adoc[] 1050include::{chapters}/commonvalidity/draw_dispatch_nonindirect_common.adoc[] 1051include::{chapters}/commonvalidity/draw_vertex_binding.adoc[] 1052include::{chapters}/commonvalidity/draw_indexed_common.adoc[] 1053include::{chapters}/commonvalidity/draw_instance_common.adoc[] 1054include::{chapters}/commonvalidity/draw_index_binding.adoc[] 1055**** 1056 1057include::{generated}/validity/protos/vkCmdDrawIndexed.adoc[] 1058-- 1059 1060ifdef::VK_EXT_multi_draw[] 1061[open,refpage='vkCmdDrawMultiEXT',desc='Draw primitives',type='protos'] 1062-- 1063:refpage: vkCmdDrawMultiEXT 1064 1065To record an ordered sequence of draws which have no state changes between 1066them, call: 1067 1068include::{generated}/api/protos/vkCmdDrawMultiEXT.adoc[] 1069 1070 * pname:commandBuffer is the command buffer into which the command is 1071 recorded. 1072 * pname:drawCount is the number of draws to execute, and can: be zero. 1073 * pname:pVertexInfo is a pointer to an array of slink:VkMultiDrawInfoEXT 1074 with vertex information to be drawn. 1075 * pname:instanceCount is the number of instances per draw. 1076 * pname:firstInstance is the instance ID of the first instance in each 1077 draw. 1078 * pname:stride is the byte stride between consecutive elements of 1079 pname:pVertexInfo. 1080 1081The number of draws recorded is pname:drawCount, with each draw reading, 1082sequentially, a pname:firstVertex and a pname:vertexCount from 1083pname:pVertexInfo. 1084For each recorded draw, primitives are assembled as for flink:vkCmdDraw, and 1085drawn pname:instanceCount times with code:instanceIndex starting with 1086pname:firstInstance and sequentially for each instance. 1087 1088.Valid Usage 1089**** 1090include::{chapters}/commonvalidity/draw_common.adoc[] 1091include::{chapters}/commonvalidity/draw_dispatch_nonindirect_common.adoc[] 1092include::{chapters}/commonvalidity/draw_vertex_binding.adoc[] 1093include::{chapters}/commonvalidity/draw_instance_common.adoc[] 1094 * [[VUID-vkCmdDrawMultiEXT-None-04933]] 1095 The <<features-multiDraw, pname:multiDraw>> feature must: be enabled 1096 * [[VUID-vkCmdDrawMultiEXT-drawCount-04934]] 1097 pname:drawCount must: be less than 1098 sname:VkPhysicalDeviceMultiDrawPropertiesEXT::pname:maxMultiDrawCount 1099 * [[VUID-vkCmdDrawMultiEXT-drawCount-04935]] 1100 If pname:drawCount is greater than zero, pname:pVertexInfo must: be a 1101 valid pointer to memory containing one or more valid instances of 1102 slink:VkMultiDrawInfoEXT structures 1103 * [[VUID-vkCmdDrawMultiEXT-stride-04936]] 1104 pname:stride must: be a multiple of 4 1105**** 1106 1107include::{generated}/validity/protos/vkCmdDrawMultiEXT.adoc[] 1108-- 1109 1110[open,refpage='vkCmdDrawMultiIndexedEXT',desc='Draw primitives',type='protos'] 1111-- 1112:refpage: vkCmdDrawMultiIndexedEXT 1113 1114To record an ordered sequence of indexed draws which have no state changes 1115between them, call: 1116 1117include::{generated}/api/protos/vkCmdDrawMultiIndexedEXT.adoc[] 1118 1119 * pname:commandBuffer is the command buffer into which the command is 1120 recorded. 1121 * pname:drawCount is the number of draws to execute, and can: be zero. 1122 * pname:pIndexInfo is a pointer to an array of 1123 slink:VkMultiDrawIndexedInfoEXT with index information to be drawn. 1124 * pname:instanceCount is the number of instances per draw. 1125 * pname:firstInstance is the instance ID of the first instance in each 1126 draw. 1127 * pname:stride is the byte stride between consecutive elements of 1128 pname:pIndexInfo. 1129 * pname:pVertexOffset is `NULL` or a pointer to the value added to the 1130 vertex index before indexing into the vertex buffer. 1131 When specified, sname:VkMultiDrawIndexedInfoEXT::pname:offset is 1132 ignored. 1133 1134The number of draws recorded is pname:drawCount, with each draw reading, 1135sequentially, a pname:firstIndex and an pname:indexCount from 1136pname:pIndexInfo. 1137For each recorded draw, primitives are assembled as for 1138flink:vkCmdDrawIndexed, and drawn pname:instanceCount times with 1139code:instanceIndex starting with pname:firstInstance and sequentially for 1140each instance. 1141If pname:pVertexOffset is `NULL`, a pname:vertexOffset is also read from 1142pname:pIndexInfo, otherwise the value from dereferencing pname:pVertexOffset 1143is used. 1144 1145.Valid Usage 1146**** 1147include::{chapters}/commonvalidity/draw_common.adoc[] 1148include::{chapters}/commonvalidity/draw_dispatch_nonindirect_common.adoc[] 1149include::{chapters}/commonvalidity/draw_vertex_binding.adoc[] 1150include::{chapters}/commonvalidity/draw_indexed_common.adoc[] 1151include::{chapters}/commonvalidity/draw_instance_common.adoc[] 1152include::{chapters}/commonvalidity/draw_index_binding.adoc[] 1153 * [[VUID-vkCmdDrawMultiIndexedEXT-None-04937]] 1154 The <<features-multiDraw, pname:multiDraw>> feature must: be enabled 1155 * [[VUID-vkCmdDrawMultiIndexedEXT-drawCount-04939]] 1156 pname:drawCount must: be less than 1157 sname:VkPhysicalDeviceMultiDrawPropertiesEXT::pname:maxMultiDrawCount 1158 * [[VUID-vkCmdDrawMultiIndexedEXT-drawCount-04940]] 1159 If pname:drawCount is greater than zero, pname:pIndexInfo must: be a 1160 valid pointer to memory containing one or more valid instances of 1161 slink:VkMultiDrawIndexedInfoEXT structures 1162 * [[VUID-vkCmdDrawMultiIndexedEXT-stride-04941]] 1163 pname:stride must: be a multiple of 4 1164**** 1165 1166include::{generated}/validity/protos/vkCmdDrawMultiIndexedEXT.adoc[] 1167-- 1168 1169[open,refpage='VkMultiDrawInfoEXT',desc='Structure specifying a multi-draw command',type='structs',xrefs='vkCmdDrawMultiEXT'] 1170-- 1171The sname:VkMultiDrawInfoEXT structure is defined as: 1172 1173include::{generated}/api/structs/VkMultiDrawInfoEXT.adoc[] 1174 1175 * pname:firstVertex is the first vertex to draw. 1176 * pname:vertexCount is the number of vertices to draw. 1177 1178The members of sname:VkMultiDrawInfoEXT have the same meaning as the 1179pname:firstVertex and pname:vertexCount parameters in flink:vkCmdDraw. 1180 1181include::{generated}/validity/structs/VkMultiDrawInfoEXT.adoc[] 1182-- 1183 1184[open,refpage='VkMultiDrawIndexedInfoEXT',desc='Structure specifying a multi-draw command',type='structs',xrefs='vkCmdDrawMultiIndexedEXT'] 1185-- 1186The sname:VkMultiDrawIndexedInfoEXT structure is defined as: 1187 1188include::{generated}/api/structs/VkMultiDrawIndexedInfoEXT.adoc[] 1189 1190 * pname:firstIndex is the first index to draw. 1191 * pname:indexCount is the number of vertices to draw. 1192 * pname:vertexOffset is the value added to the vertex index before 1193 indexing into the vertex buffer for indexed multidraws. 1194 1195The pname:firstIndex, pname:indexCount, and pname:vertexOffset members of 1196sname:VkMultiDrawIndexedInfoEXT have the same meaning as the 1197pname:firstIndex, pname:indexCount, and pname:vertexOffset parameters, 1198respectively, of flink:vkCmdDrawIndexed. 1199 1200include::{generated}/validity/structs/VkMultiDrawIndexedInfoEXT.adoc[] 1201 1202-- 1203endif::VK_EXT_multi_draw[] 1204 1205[open,refpage='vkCmdDrawIndirect',desc='Draw primitives with indirect parameters',type='protos'] 1206-- 1207:refpage: vkCmdDrawIndirect 1208 1209To record a non-indexed indirect drawing command, call: 1210 1211include::{generated}/api/protos/vkCmdDrawIndirect.adoc[] 1212 1213 * pname:commandBuffer is the command buffer into which the command is 1214 recorded. 1215 * pname:buffer is the buffer containing draw parameters. 1216 * pname:offset is the byte offset into pname:buffer where parameters 1217 begin. 1218 * pname:drawCount is the number of draws to execute, and can: be zero. 1219 * pname:stride is the byte stride between successive sets of draw 1220 parameters. 1221 1222fname:vkCmdDrawIndirect behaves similarly to flink:vkCmdDraw except that the 1223parameters are read by the device from a buffer during execution. 1224pname:drawCount draws are executed by the command, with parameters taken 1225from pname:buffer starting at pname:offset and increasing by pname:stride 1226bytes for each successive draw. 1227The parameters of each draw are encoded in an array of 1228slink:VkDrawIndirectCommand structures. 1229If pname:drawCount is less than or equal to one, pname:stride is ignored. 1230 1231.Valid Usage 1232**** 1233include::{chapters}/commonvalidity/draw_common.adoc[] 1234include::{chapters}/commonvalidity/draw_vertex_binding.adoc[] 1235include::{chapters}/commonvalidity/draw_dispatch_indirect_common.adoc[] 1236include::{chapters}/commonvalidity/draw_indirect_drawcount.adoc[] 1237 * [[VUID-vkCmdDrawIndirect-drawCount-00476]] 1238 If pname:drawCount is greater than `1`, pname:stride must: be a multiple 1239 of `4` and must: be greater than or equal to 1240 code:sizeof(sname:VkDrawIndirectCommand) 1241 * [[VUID-vkCmdDrawIndirect-drawCount-00487]] 1242 If pname:drawCount is equal to `1`, [eq]#(pname:offset {plus} 1243 code:sizeof(slink:VkDrawIndirectCommand))# must: be less than or equal 1244 to the size of pname:buffer 1245 * [[VUID-vkCmdDrawIndirect-drawCount-00488]] 1246 If pname:drawCount is greater than `1`, [eq]#(pname:stride {times} 1247 (pname:drawCount - 1) {plus} pname:offset {plus} 1248 code:sizeof(slink:VkDrawIndirectCommand))# must: be less than or equal 1249 to the size of pname:buffer 1250**** 1251 1252include::{generated}/validity/protos/vkCmdDrawIndirect.adoc[] 1253-- 1254 1255[open,refpage='VkDrawIndirectCommand',desc='Structure specifying a indirect drawing command',type='structs',xrefs='vkCmdDrawIndirect'] 1256-- 1257:refpage: VkDrawIndirectCommand 1258 1259The sname:VkDrawIndirectCommand structure is defined as: 1260 1261include::{generated}/api/structs/VkDrawIndirectCommand.adoc[] 1262 1263 * pname:vertexCount is the number of vertices to draw. 1264 * pname:instanceCount is the number of instances to draw. 1265 * pname:firstVertex is the index of the first vertex to draw. 1266 * pname:firstInstance is the instance ID of the first instance to draw. 1267 1268The members of sname:VkDrawIndirectCommand have the same meaning as the 1269similarly named parameters of flink:vkCmdDraw. 1270 1271.Valid Usage 1272**** 1273include::{chapters}/commonvalidity/draw_instance_common.adoc[] 1274 * [[VUID-VkDrawIndirectCommand-None-00500]] 1275 For a given vertex buffer binding, any attribute data fetched must: be 1276 entirely contained within the corresponding vertex buffer binding, as 1277 described in <<fxvertex-input>> 1278 * [[VUID-VkDrawIndirectCommand-firstInstance-00501]] 1279 If the <<features-drawIndirectFirstInstance, 1280 pname:drawIndirectFirstInstance>> feature is not enabled, 1281 pname:firstInstance must: be code:0 1282**** 1283 1284include::{generated}/validity/structs/VkDrawIndirectCommand.adoc[] 1285-- 1286 1287ifdef::VK_VERSION_1_2,VK_KHR_draw_indirect_count[] 1288[open,refpage='vkCmdDrawIndirectCount',desc='Draw primitives with indirect parameters and draw count',type='protos',alias='vkCmdDrawIndirectCountKHR vkCmdDrawIndirectCountAMD'] 1289-- 1290:refpage: vkCmdDrawIndirectCount 1291 1292To record a non-indexed draw call with a draw call count sourced from a 1293buffer, call: 1294 1295ifdef::VK_VERSION_1_2[] 1296include::{generated}/api/protos/vkCmdDrawIndirectCount.adoc[] 1297endif::VK_VERSION_1_2[] 1298 1299// Jon: conditional logic on connective clauses with 3 forms of the command including VK_VERSION_1_2 needs work. 1300ifdef::VK_VERSION_1_2+VK_KHR_draw_indirect_count[or the equivalent command] 1301 1302ifdef::VK_KHR_draw_indirect_count[] 1303include::{generated}/api/protos/vkCmdDrawIndirectCountKHR.adoc[] 1304endif::VK_KHR_draw_indirect_count[] 1305 1306ifdef::VK_KHR_draw_indirect_count+VK_AMD_draw_indirect_count[or the equivalent command] 1307 1308ifdef::VK_AMD_draw_indirect_count[] 1309include::{generated}/api/protos/vkCmdDrawIndirectCountAMD.adoc[] 1310endif::VK_AMD_draw_indirect_count[] 1311 1312 * pname:commandBuffer is the command buffer into which the command is 1313 recorded. 1314 * pname:buffer is the buffer containing draw parameters. 1315 * pname:offset is the byte offset into pname:buffer where parameters 1316 begin. 1317 * pname:countBuffer is the buffer containing the draw count. 1318 * pname:countBufferOffset is the byte offset into pname:countBuffer where 1319 the draw count begins. 1320 * pname:maxDrawCount specifies the maximum number of draws that will be 1321 executed. 1322 The actual number of executed draw calls is the minimum of the count 1323 specified in pname:countBuffer and pname:maxDrawCount. 1324 * pname:stride is the byte stride between successive sets of draw 1325 parameters. 1326 1327fname:vkCmdDrawIndirectCount behaves similarly to flink:vkCmdDrawIndirect 1328except that the draw count is read by the device from a buffer during 1329execution. 1330The command will read an unsigned 32-bit integer from pname:countBuffer 1331located at pname:countBufferOffset and use this as the draw count. 1332 1333.Valid Usage 1334**** 1335include::{chapters}/commonvalidity/draw_common.adoc[] 1336include::{chapters}/commonvalidity/draw_vertex_binding.adoc[] 1337include::{chapters}/commonvalidity/draw_dispatch_indirect_common.adoc[] 1338include::{chapters}/commonvalidity/draw_indirect_count_common.adoc[] 1339 * [[VUID-vkCmdDrawIndirectCount-stride-03110]] 1340 pname:stride must: be a multiple of `4` and must: be greater than or 1341 equal to sizeof(sname:VkDrawIndirectCommand) 1342 * [[VUID-vkCmdDrawIndirectCount-maxDrawCount-03111]] 1343 If pname:maxDrawCount is greater than or equal to `1`, 1344 [eq]#(pname:stride {times} (pname:maxDrawCount - 1) {plus} pname:offset 1345 {plus} sizeof(sname:VkDrawIndirectCommand))# must: be less than or equal 1346 to the size of pname:buffer 1347 * [[VUID-vkCmdDrawIndirectCount-countBuffer-03121]] 1348 If the count stored in pname:countBuffer is equal to `1`, 1349 [eq]#(pname:offset {plus} sizeof(sname:VkDrawIndirectCommand))# must: be 1350 less than or equal to the size of pname:buffer 1351 * [[VUID-vkCmdDrawIndirectCount-countBuffer-03122]] 1352 If the count stored in pname:countBuffer is greater than `1`, 1353 [eq]#(pname:stride {times} (pname:drawCount - 1) {plus} pname:offset 1354 {plus} sizeof(sname:VkDrawIndirectCommand))# must: be less than or equal 1355 to the size of pname:buffer 1356**** 1357 1358include::{generated}/validity/protos/vkCmdDrawIndirectCount.adoc[] 1359 1360-- 1361endif::VK_VERSION_1_2,VK_KHR_draw_indirect_count[] 1362 1363[open,refpage='vkCmdDrawIndexedIndirect',desc='Draw primitives with indirect parameters and indexed vertices',type='protos'] 1364-- 1365:refpage: vkCmdDrawIndexedIndirect 1366 1367To record an indexed indirect drawing command, call: 1368 1369include::{generated}/api/protos/vkCmdDrawIndexedIndirect.adoc[] 1370 1371 * pname:commandBuffer is the command buffer into which the command is 1372 recorded. 1373 * pname:buffer is the buffer containing draw parameters. 1374 * pname:offset is the byte offset into pname:buffer where parameters 1375 begin. 1376 * pname:drawCount is the number of draws to execute, and can: be zero. 1377 * pname:stride is the byte stride between successive sets of draw 1378 parameters. 1379 1380fname:vkCmdDrawIndexedIndirect behaves similarly to flink:vkCmdDrawIndexed 1381except that the parameters are read by the device from a buffer during 1382execution. 1383pname:drawCount draws are executed by the command, with parameters taken 1384from pname:buffer starting at pname:offset and increasing by pname:stride 1385bytes for each successive draw. 1386The parameters of each draw are encoded in an array of 1387slink:VkDrawIndexedIndirectCommand structures. 1388If pname:drawCount is less than or equal to one, pname:stride is ignored. 1389 1390.Valid Usage 1391**** 1392include::{chapters}/commonvalidity/draw_common.adoc[] 1393include::{chapters}/commonvalidity/draw_vertex_binding.adoc[] 1394include::{chapters}/commonvalidity/draw_dispatch_indirect_common.adoc[] 1395include::{chapters}/commonvalidity/draw_indirect_drawcount.adoc[] 1396include::{chapters}/commonvalidity/draw_indexed_common.adoc[] 1397 * [[VUID-vkCmdDrawIndexedIndirect-drawCount-00528]] 1398 If pname:drawCount is greater than `1`, pname:stride must: be a multiple 1399 of `4` and must: be greater than or equal to 1400 code:sizeof(sname:VkDrawIndexedIndirectCommand) 1401 * [[VUID-vkCmdDrawIndexedIndirect-drawCount-00539]] 1402 If pname:drawCount is equal to `1`, [eq]#(pname:offset {plus} 1403 code:sizeof(sname:VkDrawIndexedIndirectCommand))# must: be less than or 1404 equal to the size of pname:buffer 1405 * [[VUID-vkCmdDrawIndexedIndirect-drawCount-00540]] 1406 If pname:drawCount is greater than `1`, [eq]#(pname:stride {times} 1407 (pname:drawCount - 1) {plus} pname:offset {plus} 1408 code:sizeof(sname:VkDrawIndexedIndirectCommand))# must: be less than or 1409 equal to the size of pname:buffer 1410**** 1411 1412include::{generated}/validity/protos/vkCmdDrawIndexedIndirect.adoc[] 1413-- 1414 1415[open,refpage='VkDrawIndexedIndirectCommand',desc='Structure specifying a indexed indirect drawing command',type='structs',xrefs='vkCmdDrawIndexedIndirect'] 1416-- 1417:refpage: VkDrawIndexedIndirectCommand 1418 1419The sname:VkDrawIndexedIndirectCommand structure is defined as: 1420 1421include::{generated}/api/structs/VkDrawIndexedIndirectCommand.adoc[] 1422 1423 * pname:indexCount is the number of vertices to draw. 1424 * pname:instanceCount is the number of instances to draw. 1425 * pname:firstIndex is the base index within the index buffer. 1426 * pname:vertexOffset is the value added to the vertex index before 1427 indexing into the vertex buffer. 1428 * pname:firstInstance is the instance ID of the first instance to draw. 1429 1430The members of sname:VkDrawIndexedIndirectCommand have the same meaning as 1431the similarly named parameters of flink:vkCmdDrawIndexed. 1432 1433.Valid Usage 1434**** 1435include::{chapters}/commonvalidity/draw_instance_common.adoc[] 1436include::{chapters}/commonvalidity/draw_index_binding.adoc[] 1437 * [[VUID-VkDrawIndexedIndirectCommand-None-00552]] 1438 For a given vertex buffer binding, any attribute data fetched must: be 1439 entirely contained within the corresponding vertex buffer binding, as 1440 described in <<fxvertex-input>> 1441 * [[VUID-VkDrawIndexedIndirectCommand-firstInstance-00554]] 1442 If the <<features-drawIndirectFirstInstance, 1443 pname:drawIndirectFirstInstance>> feature is not enabled, 1444 pname:firstInstance must: be code:0 1445**** 1446 1447include::{generated}/validity/structs/VkDrawIndexedIndirectCommand.adoc[] 1448-- 1449 1450ifdef::VK_VERSION_1_2,VK_KHR_draw_indirect_count[] 1451[open,refpage='vkCmdDrawIndexedIndirectCount',desc='Draw parameters with indirect parameters, indexed vertices, and draw count',type='protos',alias='vkCmdDrawIndexedIndirectCountKHR vkCmdDrawIndexedIndirectCountAMD'] 1452-- 1453:refpage: vkCmdDrawIndexedIndirectCount 1454 1455To record an indexed draw call with a draw call count sourced from a buffer, 1456call: 1457 1458ifdef::VK_VERSION_1_2[] 1459include::{generated}/api/protos/vkCmdDrawIndexedIndirectCount.adoc[] 1460endif::VK_VERSION_1_2[] 1461 1462// Jon: conditional logic on connective clauses with 3 forms of the command including VK_VERSION_1_2 needs work. 1463ifdef::VK_VERSION_1_2+VK_KHR_draw_indirect_count[or the equivalent command] 1464 1465ifdef::VK_KHR_draw_indirect_count[] 1466include::{generated}/api/protos/vkCmdDrawIndexedIndirectCountKHR.adoc[] 1467endif::VK_KHR_draw_indirect_count[] 1468 1469ifdef::VK_KHR_draw_indirect_count+VK_AMD_draw_indirect_count[or the equivalent command] 1470 1471ifdef::VK_AMD_draw_indirect_count[] 1472include::{generated}/api/protos/vkCmdDrawIndexedIndirectCountAMD.adoc[] 1473endif::VK_AMD_draw_indirect_count[] 1474 1475 * pname:commandBuffer is the command buffer into which the command is 1476 recorded. 1477 * pname:buffer is the buffer containing draw parameters. 1478 * pname:offset is the byte offset into pname:buffer where parameters 1479 begin. 1480 * pname:countBuffer is the buffer containing the draw count. 1481 * pname:countBufferOffset is the byte offset into pname:countBuffer where 1482 the draw count begins. 1483 * pname:maxDrawCount specifies the maximum number of draws that will be 1484 executed. 1485 The actual number of executed draw calls is the minimum of the count 1486 specified in pname:countBuffer and pname:maxDrawCount. 1487 * pname:stride is the byte stride between successive sets of draw 1488 parameters. 1489 1490fname:vkCmdDrawIndexedIndirectCount behaves similarly to 1491flink:vkCmdDrawIndexedIndirect except that the draw count is read by the 1492device from a buffer during execution. 1493The command will read an unsigned 32-bit integer from pname:countBuffer 1494located at pname:countBufferOffset and use this as the draw count. 1495 1496.Valid Usage 1497**** 1498include::{chapters}/commonvalidity/draw_common.adoc[] 1499include::{chapters}/commonvalidity/draw_vertex_binding.adoc[] 1500include::{chapters}/commonvalidity/draw_dispatch_indirect_common.adoc[] 1501include::{chapters}/commonvalidity/draw_indirect_count_common.adoc[] 1502include::{chapters}/commonvalidity/draw_indexed_common.adoc[] 1503 * [[VUID-vkCmdDrawIndexedIndirectCount-stride-03142]] 1504 pname:stride must: be a multiple of `4` and must: be greater than or 1505 equal to sizeof(sname:VkDrawIndexedIndirectCommand) 1506 * [[VUID-vkCmdDrawIndexedIndirectCount-maxDrawCount-03143]] 1507 If pname:maxDrawCount is greater than or equal to `1`, 1508 [eq]#(pname:stride {times} (pname:maxDrawCount - 1) {plus} pname:offset 1509 {plus} sizeof(sname:VkDrawIndexedIndirectCommand))# must: be less than 1510 or equal to the size of pname:buffer 1511 * [[VUID-vkCmdDrawIndexedIndirectCount-countBuffer-03153]] 1512 If count stored in pname:countBuffer is equal to `1`, [eq]#(pname:offset 1513 {plus} sizeof(sname:VkDrawIndexedIndirectCommand))# must: be less than 1514 or equal to the size of pname:buffer 1515 * [[VUID-vkCmdDrawIndexedIndirectCount-countBuffer-03154]] 1516 If count stored in pname:countBuffer is greater than `1`, 1517 [eq]#(pname:stride {times} (pname:drawCount - 1) {plus} pname:offset 1518 {plus} sizeof(sname:VkDrawIndexedIndirectCommand))# must: be less than 1519 or equal to the size of pname:buffer 1520**** 1521 1522include::{generated}/validity/protos/vkCmdDrawIndexedIndirectCount.adoc[] 1523-- 1524endif::VK_VERSION_1_2,VK_KHR_draw_indirect_count[] 1525 1526 1527ifdef::VK_EXT_transform_feedback[] 1528[[drawing-transform-feedback]] 1529=== Drawing Transform Feedback 1530 1531It is possible to draw vertex data that was previously captured during 1532active <<vertexpostproc-transform-feedback,transform feedback>> by binding 1533one or more of the transform feedback buffers as vertex buffers. 1534A pipeline barrier is required between using the buffers as transform 1535feedback buffers and vertex buffers to ensure all writes to the transform 1536feedback buffers are visible when the data is read as vertex attributes. 1537The source access is ename:VK_ACCESS_TRANSFORM_FEEDBACK_WRITE_BIT_EXT and 1538the destination access is ename:VK_ACCESS_VERTEX_ATTRIBUTE_READ_BIT for the 1539pipeline stages ename:VK_PIPELINE_STAGE_TRANSFORM_FEEDBACK_BIT_EXT and 1540ename:VK_PIPELINE_STAGE_VERTEX_INPUT_BIT respectively. 1541The value written to the counter buffer by 1542flink:vkCmdEndTransformFeedbackEXT can: be used to determine the vertex 1543count for the draw. 1544A pipeline barrier is required between using the counter buffer for 1545fname:vkCmdEndTransformFeedbackEXT and fname:vkCmdDrawIndirectByteCountEXT 1546where the source access is 1547ename:VK_ACCESS_TRANSFORM_FEEDBACK_COUNTER_WRITE_BIT_EXT and the destination 1548access is ename:VK_ACCESS_INDIRECT_COMMAND_READ_BIT for the pipeline stages 1549ename:VK_PIPELINE_STAGE_TRANSFORM_FEEDBACK_BIT_EXT and 1550ename:VK_PIPELINE_STAGE_DRAW_INDIRECT_BIT respectively. 1551 1552[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'] 1553-- 1554:refpage: vkCmdDrawIndirectByteCountEXT 1555 1556To record a non-indexed draw call, where the vertex count is based on a byte 1557count read from a buffer and the passed in vertex stride parameter, call: 1558 1559include::{generated}/api/protos/vkCmdDrawIndirectByteCountEXT.adoc[] 1560 1561 * pname:commandBuffer is the command buffer into which the command is 1562 recorded. 1563 * pname:instanceCount is the number of instances to draw. 1564 * pname:firstInstance is the instance ID of the first instance to draw. 1565 * pname:counterBuffer is the buffer handle from where the byte count is 1566 read. 1567 * pname:counterBufferOffset is the offset into the buffer used to read the 1568 byte count, which is used to calculate the vertex count for this draw 1569 call. 1570 * pname:counterOffset is subtracted from the byte count read from the 1571 pname:counterBuffer at the pname:counterBufferOffset 1572 * pname:vertexStride is the stride in bytes between each element of the 1573 vertex data that is used to calculate the vertex count from the counter 1574 value. 1575 This value is typically the same value that was used in the graphics 1576 pipeline state when the transform feedback was captured as the 1577 code:XfbStride. 1578 1579When the command is executed, primitives are assembled in the same way as 1580done with flink:vkCmdDraw except the pname:vertexCount is calculated based 1581on the byte count read from pname:counterBuffer at offset 1582pname:counterBufferOffset. 1583The assembled primitives execute the bound graphics pipeline. 1584 1585The effective pname:vertexCount is calculated as follows: 1586 1587[source,c] 1588---- 1589const uint32_t * counterBufferPtr = (const uint8_t *)counterBuffer.address + counterBufferOffset; 1590vertexCount = floor(max(0, (*counterBufferPtr - counterOffset)) / vertexStride); 1591---- 1592 1593The effective pname:firstVertex is zero. 1594 1595.Valid Usage 1596**** 1597include::{chapters}/commonvalidity/draw_common.adoc[] 1598include::{chapters}/commonvalidity/draw_vertex_binding.adoc[] 1599include::{chapters}/commonvalidity/draw_instance_common.adoc[] 1600 * [[VUID-vkCmdDrawIndirectByteCountEXT-transformFeedback-02287]] 1601 sname:VkPhysicalDeviceTransformFeedbackFeaturesEXT::pname:transformFeedback 1602 must: be enabled 1603 * [[VUID-vkCmdDrawIndirectByteCountEXT-transformFeedbackDraw-02288]] 1604 The implementation must: support 1605 sname:VkPhysicalDeviceTransformFeedbackPropertiesEXT::pname:transformFeedbackDraw 1606 * [[VUID-vkCmdDrawIndirectByteCountEXT-vertexStride-02289]] 1607 pname:vertexStride must: be greater than 0 and less than or equal to 1608 sname:VkPhysicalDeviceTransformFeedbackPropertiesEXT::pname:maxTransformFeedbackBufferDataStride 1609 * [[VUID-vkCmdDrawIndirectByteCountEXT-counterBuffer-04567]] 1610 If pname:counterBuffer is non-sparse then it must: be bound completely 1611 and contiguously to a single sname:VkDeviceMemory object 1612 * [[VUID-vkCmdDrawIndirectByteCountEXT-counterBuffer-02290]] 1613 pname:counterBuffer must: have been created with the 1614 ename:VK_BUFFER_USAGE_INDIRECT_BUFFER_BIT bit set 1615 * [[VUID-vkCmdDrawIndirectByteCountEXT-counterBufferOffset-04568]] 1616 pname:counterBufferOffset must: be a multiple of `4` 1617 * [[VUID-vkCmdDrawIndirectByteCountEXT-counterOffset-09474]] 1618 pname:counterOffset must: be a multiple of `4` 1619 * [[VUID-vkCmdDrawIndirectByteCountEXT-vertexStride-09475]] 1620 pname:vertexStride must: be a multiple of `4` 1621ifdef::VK_VERSION_1_1[] 1622 * [[VUID-vkCmdDrawIndirectByteCountEXT-commandBuffer-02646]] 1623 pname:commandBuffer must: not be a protected command buffer 1624endif::VK_VERSION_1_1[] 1625**** 1626 1627include::{generated}/validity/protos/vkCmdDrawIndirectByteCountEXT.adoc[] 1628-- 1629endif::VK_EXT_transform_feedback[] 1630 1631 1632ifdef::VK_EXT_conditional_rendering[] 1633[[drawing-conditional-rendering]] 1634== Conditional Rendering 1635 1636Certain rendering commands can: be executed conditionally based on a value 1637in buffer memory. 1638These rendering commands are limited to <<drawing,drawing commands>>, 1639<<dispatch,dispatching commands>>, and clearing attachments with 1640flink:vkCmdClearAttachments within a conditional rendering block which is 1641defined by commands flink:vkCmdBeginConditionalRenderingEXT and 1642flink:vkCmdEndConditionalRenderingEXT. 1643Other rendering commands remain unaffected by conditional rendering. 1644 1645[[active-conditional-rendering]] 1646After beginning conditional rendering, it is considered _active_ within the 1647command buffer it was called until it is ended with 1648flink:vkCmdEndConditionalRenderingEXT. 1649 1650Conditional rendering must: begin and end in the same command buffer. 1651When conditional rendering is active, a primary command buffer can: execute 1652secondary command buffers if the <<features-inheritedConditionalRendering, 1653pname:inheritedConditionalRendering>> feature is enabled. 1654For a secondary command buffer to be executed while conditional rendering is 1655active in the primary command buffer, it must: set the 1656pname:conditionalRenderingEnable flag of 1657slink:VkCommandBufferInheritanceConditionalRenderingInfoEXT, as described in 1658the <<commandbuffers-recording, Command Buffer Recording>> section. 1659 1660Conditional rendering must: also either begin and end inside the same 1661subpass of a render pass instance, or must: both begin and end outside of a 1662render pass instance (i.e. contain entire render pass instances). 1663 1664[open,refpage='vkCmdBeginConditionalRenderingEXT',desc='Define the beginning of a conditional rendering block',type='protos'] 1665-- 1666To begin conditional rendering, call: 1667 1668include::{generated}/api/protos/vkCmdBeginConditionalRenderingEXT.adoc[] 1669 1670 * pname:commandBuffer is the command buffer into which this command will 1671 be recorded. 1672 * pname:pConditionalRenderingBegin is a pointer to a 1673 slink:VkConditionalRenderingBeginInfoEXT structure specifying parameters 1674 of conditional rendering. 1675 1676.Valid Usage 1677**** 1678 * [[VUID-vkCmdBeginConditionalRenderingEXT-None-01980]] 1679 Conditional rendering must: not already be 1680 <<active-conditional-rendering,active>> 1681**** 1682 1683include::{generated}/validity/protos/vkCmdBeginConditionalRenderingEXT.adoc[] 1684-- 1685 1686[open,refpage='VkConditionalRenderingBeginInfoEXT',desc='Structure specifying conditional rendering begin information',type='structs'] 1687-- 1688The sname:VkConditionalRenderingBeginInfoEXT structure is defined as: 1689 1690include::{generated}/api/structs/VkConditionalRenderingBeginInfoEXT.adoc[] 1691 1692 * pname:sType is a elink:VkStructureType value identifying this structure. 1693 * pname:pNext is `NULL` or a pointer to a structure extending this 1694 structure. 1695 * pname:buffer is a buffer containing the predicate for conditional 1696 rendering. 1697 * pname:offset is the byte offset into pname:buffer where the predicate is 1698 located. 1699 * pname:flags is a bitmask of tlink:VkConditionalRenderingFlagsEXT 1700 specifying the behavior of conditional rendering. 1701 1702If the 32-bit value at pname:offset in pname:buffer memory is zero, then the 1703rendering commands are discarded, otherwise they are executed as normal. 1704If the value of the predicate in buffer memory changes while conditional 1705rendering is active, the rendering commands may: be discarded in an 1706implementation-dependent way. 1707Some implementations may latch the value of the predicate upon beginning 1708conditional rendering while others may read it before every rendering 1709command. 1710 1711.Valid Usage 1712**** 1713 * [[VUID-VkConditionalRenderingBeginInfoEXT-buffer-01981]] 1714 If pname:buffer is non-sparse then it must: be bound completely and 1715 contiguously to a single sname:VkDeviceMemory object 1716 * [[VUID-VkConditionalRenderingBeginInfoEXT-buffer-01982]] 1717 pname:buffer must: have been created with the 1718 ename:VK_BUFFER_USAGE_CONDITIONAL_RENDERING_BIT_EXT bit set 1719 * [[VUID-VkConditionalRenderingBeginInfoEXT-offset-01983]] 1720 pname:offset must: be less than the size of pname:buffer by at least 32 1721 bits 1722 * [[VUID-VkConditionalRenderingBeginInfoEXT-offset-01984]] 1723 pname:offset must: be a multiple of 4 1724**** 1725 1726include::{generated}/validity/structs/VkConditionalRenderingBeginInfoEXT.adoc[] 1727-- 1728 1729[open,refpage='VkConditionalRenderingFlagBitsEXT',desc='Specify the behavior of conditional rendering',type='enums'] 1730-- 1731Bits which can: be set in 1732flink:vkCmdBeginConditionalRenderingEXT::pname:flags, specifying the 1733behavior of conditional rendering, are: 1734 1735include::{generated}/api/enums/VkConditionalRenderingFlagBitsEXT.adoc[] 1736 1737 * ename:VK_CONDITIONAL_RENDERING_INVERTED_BIT_EXT specifies the condition 1738 used to determine whether to discard rendering commands or not. 1739 That is, if the 32-bit predicate read from pname:buffer memory at 1740 pname:offset is zero, the rendering commands are not discarded, and if 1741 non zero, then they are discarded. 1742-- 1743 1744[open,refpage='VkConditionalRenderingFlagsEXT',desc='Bitmask of VkConditionalRenderingFlagBitsEXT',type='flags'] 1745-- 1746include::{generated}/api/flags/VkConditionalRenderingFlagsEXT.adoc[] 1747 1748tname:VkConditionalRenderingFlagsEXT is a bitmask type for setting a mask of 1749zero or more elink:VkConditionalRenderingFlagBitsEXT. 1750-- 1751 1752[open,refpage='vkCmdEndConditionalRenderingEXT',desc='Define the end of a conditional rendering block',type='protos'] 1753-- 1754To end conditional rendering, call: 1755 1756include::{generated}/api/protos/vkCmdEndConditionalRenderingEXT.adoc[] 1757 1758 * pname:commandBuffer is the command buffer into which this command will 1759 be recorded. 1760 1761Once ended, conditional rendering becomes inactive. 1762 1763.Valid Usage 1764**** 1765 * [[VUID-vkCmdEndConditionalRenderingEXT-None-01985]] 1766 Conditional rendering must: be <<active-conditional-rendering,active>> 1767 * [[VUID-vkCmdEndConditionalRenderingEXT-None-01986]] 1768 If conditional rendering was made 1769 <<active-conditional-rendering,active>> outside of a render pass 1770 instance, it must: not be ended inside a render pass instance 1771 * [[VUID-vkCmdEndConditionalRenderingEXT-None-01987]] 1772 If conditional rendering was made 1773 <<active-conditional-rendering,active>> within a subpass it must: be 1774 ended in the same subpass 1775**** 1776 1777include::{generated}/validity/protos/vkCmdEndConditionalRenderingEXT.adoc[] 1778-- 1779endif::VK_EXT_conditional_rendering[] 1780 1781ifdef::VK_NV_mesh_shader,VK_EXT_mesh_shader[] 1782include::{chapters}/VK_NV_mesh_shader/drawing.adoc[] 1783endif::VK_NV_mesh_shader,VK_EXT_mesh_shader[] 1784 1785ifdef::VK_HUAWEI_cluster_culling_shader[] 1786include::{chapters}/VK_HUAWEI_cluster_culling_shader/drawing.adoc[] 1787endif::VK_HUAWEI_cluster_culling_shader[] 1788
