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