fxvertex.txt
1 // Copyright (c) 2015-2019 Khronos Group. This work is licensed under a 2 // Creative Commons Attribution 4.0 International License; see 3 // http://creativecommons.org/licenses/by/4.0/ 4 5 [[fxvertex]] 6 = Fixed-Function Vertex Processing 7 8 Vertex fetching is controlled via configurable state, as a logically 9 distinct graphics pipeline stage. 10 11 12 [[fxvertex-attrib]] 13 == Vertex Attributes 14 15 Vertex shaders can: define input variables, which receive _vertex attribute_ 16 data transferred from one or more sname:VkBuffer(s) by drawing commands. 17 Vertex shader input variables are bound to buffers via an indirect binding 18 where the vertex shader associates a _vertex input attribute_ number with 19 each variable, vertex input attributes are associated to _vertex input 20 bindings_ on a per-pipeline basis, and vertex input bindings are associated 21 with specific buffers on a per-draw basis via the 22 fname:vkCmdBindVertexBuffers command. 23 Vertex input attribute and vertex input binding descriptions also contain 24 format information controlling how data is extracted from buffer memory and 25 converted to the format expected by the vertex shader. 26 27 There are sname:VkPhysicalDeviceLimits::pname:maxVertexInputAttributes 28 number of vertex input attributes and 29 sname:VkPhysicalDeviceLimits::pname:maxVertexInputBindings number of vertex 30 input bindings (each referred to by zero-based indices), where there are at 31 least as many vertex input attributes as there are vertex input bindings. 32 Applications can: store multiple vertex input attributes interleaved in a 33 single buffer, and use a single vertex input binding to access those 34 attributes. 35 36 In GLSL, vertex shaders associate input variables with a vertex input 37 attribute number using the code:location layout qualifier. 38 The code:component layout qualifier associates components of a vertex shader 39 input variable with components of a vertex input attribute. 40 41 .GLSL example 42 [source,glsl] 43 --------------------------------------------------- 44 // Assign location M to variableName 45 layout (location=M, component=2) in vec2 variableName; 46 47 // Assign locations [N,N+L) to the array elements of variableNameArray 48 layout (location=N) in vec4 variableNameArray[L]; 49 --------------------------------------------------- 50 51 In SPIR-V, vertex shaders associate input variables with a vertex input 52 attribute number using the code:Location decoration. 53 The code:Component decoration associates components of a vertex shader input 54 variable with components of a vertex input attribute. 55 The code:Location and code:Component decorations are specified via the 56 code:OpDecorate instruction. 57 58 .SPIR-V example 59 [source,spirv] 60 --------------------------------------------------- 61 ... 62 %1 = OpExtInstImport "GLSL.std.450" 63 ... 64 OpName %9 "variableName" 65 OpName %15 "variableNameArray" 66 OpDecorate %18 BuiltIn VertexIndex 67 OpDecorate %19 BuiltIn InstanceIndex 68 OpDecorate %9 Location M 69 OpDecorate %9 Component 2 70 OpDecorate %15 Location N 71 ... 72 %2 = OpTypeVoid 73 %3 = OpTypeFunction %2 74 %6 = OpTypeFloat 32 75 %7 = OpTypeVector %6 2 76 %8 = OpTypePointer Input %7 77 %9 = OpVariable %8 Input 78 %10 = OpTypeVector %6 4 79 %11 = OpTypeInt 32 0 80 %12 = OpConstant %11 L 81 %13 = OpTypeArray %10 %12 82 %14 = OpTypePointer Input %13 83 %15 = OpVariable %14 Input 84 ... 85 --------------------------------------------------- 86 87 88 [[fxvertex-attrib-location]] 89 === Attribute Location and Component Assignment 90 91 Vertex shaders allow code:Location and code:Component decorations on input 92 variable declarations. 93 The code:Location decoration specifies which vertex input attribute is used 94 to read and interpret the data that a variable will consume. 95 The code:Component decoration allows the location to be more finely 96 specified for scalars and vectors, down to the individual components within 97 a location that are consumed. 98 The components within a location are 0, 1, 2, and 3. 99 A variable starting at component N will consume components N, N+1, N+2, ... 100 up through its size. 101 For single precision types, it is invalid if the sequence of components gets 102 larger than 3. 103 104 When a vertex shader input variable declared using a scalar or vector 32-bit 105 data type is assigned a location, its value(s) are taken from the components 106 of the input attribute specified with the corresponding 107 sname:VkVertexInputAttributeDescription::pname:location. 108 The components used depend on the type of variable and the code:Component 109 decoration specified in the variable declaration, as identified in 110 <<fxvertex-attrib-components>>. 111 Any 32-bit scalar or vector input will consume a single location. 112 For 32-bit data types, missing components are filled in with default values 113 as described <<fxvertex-input-extraction,below>>. 114 115 116 [[fxvertex-attrib-components]] 117 .Input attribute components accessed by 32-bit input variables 118 [width="65%",cols="<5,<3,<3",options="header"] 119 |==== 120 | 32-bit data type | code:Component decoration | Components consumed 121 | scalar | 0 or unspecified | (x, o, o, o) 122 | scalar | 1 | (o, y, o, o) 123 | scalar | 2 | (o, o, z, o) 124 | scalar | 3 | (o, o, o, w) 125 | two-component vector | 0 or unspecified | (x, y, o, o) 126 | two-component vector | 1 | (o, y, z, o) 127 | two-component vector | 2 | (o, o, z, w) 128 | three-component vector| 0 or unspecified | (x, y, z, o) 129 | three-component vector| 1 | (o, y, z, w) 130 | four-component vector | 0 or unspecified | (x, y, z, w) 131 |==== 132 133 Components indicated by "`o`" are available for use by other input variables 134 which are sourced from the same attribute, and if used, are either filled 135 with the corresponding component from the input format (if present), or the 136 default value. 137 138 When a vertex shader input variable declared using a 32-bit floating point 139 matrix type is assigned a location _i_, its values are taken from 140 consecutive input attributes starting with the corresponding 141 sname:VkVertexInputAttributeDescription::pname:location. 142 Such matrices are treated as an array of column vectors with values taken 143 from the input attributes identified in <<fxvertex-attrib-matrix>>. 144 The sname:VkVertexInputAttributeDescription::pname:format must: be specified 145 with a elink:VkFormat that corresponds to the appropriate type of column 146 vector. 147 The code:Component decoration must: not be used with matrix types. 148 149 [[fxvertex-attrib-matrix]] 150 .Input attributes accessed by 32-bit input matrix variables 151 [width="100%",cols="<10%,<24%,<21%,<45%",options="header"] 152 |==== 153 | Data type | Column vector type | Locations consumed | Components consumed 154 | mat2 | two-component vector | i, i+1 | (x, y, o, o), (x, y, o, o) 155 | mat2x3 | three-component vector | i, i+1 | (x, y, z, o), (x, y, z, o) 156 | mat2x4 | four-component vector | i, i+1 | (x, y, z, w), (x, y, z, w) 157 | mat3x2 | two-component vector | i, i+1, i+2 | (x, y, o, o), (x, y, o, o), (x, y, o, o) 158 | mat3 | three-component vector | i, i+1, i+2 | (x, y, z, o), (x, y, z, o), (x, y, z, o) 159 | mat3x4 | four-component vector | i, i+1, i+2 | (x, y, z, w), (x, y, z, w), (x, y, z, w) 160 | mat4x2 | two-component vector | i, i+1, i+2, i+3 | (x, y, o, o), (x, y, o, o), (x, y, o, o), (x, y, o, o) 161 | mat4x3 | three-component vector | i, i+1, i+2, i+3 | (x, y, z, o), (x, y, z, o), (x, y, z, o), (x, y, z, o) 162 | mat4 | four-component vector | i, i+1, i+2, i+3 | (x, y, z, w), (x, y, z, w), (x, y, z, w), (x, y, z, w) 163 |==== 164 165 Components indicated by "`o`" are available for use by other input variables 166 which are sourced from the same attribute, and if used, are either filled 167 with the corresponding component from the input (if present), or the default 168 value. 169 170 When a vertex shader input variable declared using a scalar or vector 64-bit 171 data type is assigned a location _i_, its values are taken from consecutive 172 input attributes starting with the corresponding 173 sname:VkVertexInputAttributeDescription::pname:location. 174 The locations and components used depend on the type of variable and the 175 code:Component decoration specified in the variable declaration, as 176 identified in <<fxvertex-attrib-double>>. 177 For 64-bit data types, no default attribute values are provided. 178 Input variables must: not use more components than provided by the 179 attribute. 180 Input attributes which have one- or two-component 64-bit formats will 181 consume a single location. 182 Input attributes which have three- or four-component 64-bit formats will 183 consume two consecutive locations. 184 A 64-bit scalar data type will consume two components, and a 64-bit 185 two-component vector data type will consume all four components available 186 within a location. 187 A three- or four-component 64-bit data type must: not specify a component. 188 A three-component 64-bit data type will consume all four components of the 189 first location and components 0 and 1 of the second location. 190 This leaves components 2 and 3 available for other component-qualified 191 declarations. 192 A four-component 64-bit data type will consume all four components of the 193 first location and all four components of the second location. 194 It is invalid for a scalar or two-component 64-bit data type to specify a 195 component of 1 or 3. 196 197 [[fxvertex-attrib-double]] 198 .Input attribute locations and components accessed by 64-bit input variables 199 [width="100%",cols="<18%,^12%,<25%,^14%,^18%,<13%",options="header"] 200 |==== 201 ^.^| Input format | Locations consumed 202 ^.^| 64-bit data type |code:Location decoration |code:Component decoration ^| 32-bit components consumed 203 | R64 | i 204 | scalar | i | 0 or unspecified | (x, y, -, -) 205 .3+<.^| R64G64 .3+^.^| i 206 | scalar | i | 0 or unspecified | (x, y, o, o) 207 | scalar | i | 2 | (o, o, z, w) 208 | two-component vector | i | 0 or unspecified | (x, y, z, w) 209 .5+<.^| R64G64B64 .5+^.^| i, i+1 210 | scalar | i | 0 or unspecified | (x, y, o, o), (o, o, -, -) 211 | scalar | i | 2 | (o, o, z, w), (o, o, -, -) 212 | scalar | i+1 | 0 or unspecified | (o, o, o, o), (x, y, -, -) 213 | two-component vector | i | 0 or unspecified | (x, y, z, w), (o, o, -, -) 214 | three-component vector | i | unspecified | (x, y, z, w), (x, y, -, -) 215 .8+<.^| R64G64B64A64 .8+^.^| i, i+1 216 | scalar | i | 0 or unspecified | (x, y, o, o), (o, o, o, o) 217 | scalar | i | 2 | (o, o, z, w), (o, o, o, o) 218 | scalar | i+1 | 0 or unspecified | (o, o, o, o), (x, y, o, o) 219 | scalar | i+1 | 2 | (o, o, o, o), (o, o, z, w) 220 | two-component vector | i | 0 or unspecified | (x, y, z, w), (o, o, o, o) 221 | two-component vector | i+1 | 0 or unspecified | (o, o, o, o), (x, y, z, w) 222 | three-component vector | i | unspecified | (x, y, z, w), (x, y, o, o) 223 | four-component vector | i | unspecified | (x, y, z, w), (x, y, z, w) 224 |==== 225 226 Components indicated by "`o`" are available for use by other input variables 227 which are sourced from the same attribute. 228 Components indicated by "`-`" are not available for input variables as there 229 are no default values provided for 64-bit data types, and there is no data 230 provided by the input format. 231 232 When a vertex shader input variable declared using a 64-bit floating-point 233 matrix type is assigned a location _i_, its values are taken from 234 consecutive input attribute locations. 235 Such matrices are treated as an array of column vectors with values taken 236 from the input attributes as shown in <<fxvertex-attrib-double>>. 237 Each column vector starts at the location immediately following the last 238 location of the previous column vector. 239 The number of attributes and components assigned to each matrix is 240 determined by the matrix dimensions and ranges from two to eight locations. 241 242 When a vertex shader input variable declared using an array type is assigned 243 a location, its values are taken from consecutive input attributes starting 244 with the corresponding 245 sname:VkVertexInputAttributeDescription::pname:location. 246 The number of attributes and components assigned to each element are 247 determined according to the data type of the array elements and 248 code:Component decoration (if any) specified in the declaration of the 249 array, as described above. 250 Each element of the array, in order, is assigned to consecutive locations, 251 but all at the same specified component within each location. 252 253 Only input variables declared with the data types and component decorations 254 as specified above are supported. 255 _Location aliasing_ is causing two variables to have the same location 256 number. 257 _Component aliasing_ is assigning the same (or overlapping) component number 258 for two location aliases. 259 Location aliasing is allowed only if it does not cause component aliasing. 260 Further, when location aliasing, the aliases sharing the location must: all 261 have the same SPIR-V floating-point component type or all have the same 262 width integer-type components. 263 264 265 [[fxvertex-input]] 266 == Vertex Input Description 267 268 Applications specify vertex input attribute and vertex input binding 269 descriptions as part of graphics pipeline creation. 270 The slink:VkGraphicsPipelineCreateInfo::pname:pVertexInputState points to a 271 structure of type sname:VkPipelineVertexInputStateCreateInfo. 272 273 [open,refpage='VkPipelineVertexInputStateCreateInfo',desc='Structure specifying parameters of a newly created pipeline vertex input state',type='structs'] 274 -- 275 276 The sname:VkPipelineVertexInputStateCreateInfo structure is defined as: 277 278 include::{generated}/api/structs/VkPipelineVertexInputStateCreateInfo.txt[] 279 280 * pname:sType is the type of this structure. 281 * pname:pNext is `NULL` or a pointer to an extension-specific structure. 282 * pname:flags is reserved for future use. 283 * pname:vertexBindingDescriptionCount is the number of vertex binding 284 descriptions provided in pname:pVertexBindingDescriptions. 285 * pname:pVertexBindingDescriptions is a pointer to an array of 286 sname:VkVertexInputBindingDescription structures. 287 * pname:vertexAttributeDescriptionCount is the number of vertex attribute 288 descriptions provided in pname:pVertexAttributeDescriptions. 289 * pname:pVertexAttributeDescriptions is a pointer to an array of 290 sname:VkVertexInputAttributeDescription structures. 291 292 .Valid Usage 293 **** 294 * [[VUID-VkPipelineVertexInputStateCreateInfo-vertexBindingDescriptionCount-00613]] 295 pname:vertexBindingDescriptionCount must: be less than or equal to 296 sname:VkPhysicalDeviceLimits::pname:maxVertexInputBindings 297 * [[VUID-VkPipelineVertexInputStateCreateInfo-vertexAttributeDescriptionCount-00614]] 298 pname:vertexAttributeDescriptionCount must: be less than or equal to 299 sname:VkPhysicalDeviceLimits::pname:maxVertexInputAttributes 300 * [[VUID-VkPipelineVertexInputStateCreateInfo-binding-00615]] 301 For every pname:binding specified by each element of 302 pname:pVertexAttributeDescriptions, a 303 sname:VkVertexInputBindingDescription must: exist in 304 pname:pVertexBindingDescriptions with the same value of pname:binding 305 * [[VUID-VkPipelineVertexInputStateCreateInfo-pVertexBindingDescriptions-00616]] 306 All elements of pname:pVertexBindingDescriptions must: describe distinct 307 binding numbers 308 * [[VUID-VkPipelineVertexInputStateCreateInfo-pVertexAttributeDescriptions-00617]] 309 All elements of pname:pVertexAttributeDescriptions must: describe 310 distinct attribute locations 311 **** 312 313 include::{generated}/validity/structs/VkPipelineVertexInputStateCreateInfo.txt[] 314 -- 315 316 [open,refpage='VkPipelineVertexInputStateCreateFlags',desc='Reserved for future use',type='flags'] 317 -- 318 include::{generated}/api/flags/VkPipelineVertexInputStateCreateFlags.txt[] 319 320 tname:VkPipelineVertexInputStateCreateFlags is a bitmask type for setting a 321 mask, but is currently reserved for future use. 322 -- 323 324 Each vertex input binding is specified by an instance of the 325 sname:VkVertexInputBindingDescription structure. 326 327 [open,refpage='VkVertexInputBindingDescription',desc='Structure specifying vertex input binding description',type='structs'] 328 -- 329 330 The sname:VkVertexInputBindingDescription structure is defined as: 331 332 include::{generated}/api/structs/VkVertexInputBindingDescription.txt[] 333 334 * pname:binding is the binding number that this structure describes. 335 * pname:stride is the distance in bytes between two consecutive elements 336 within the buffer. 337 * pname:inputRate is a elink:VkVertexInputRate value specifying whether 338 vertex attribute addressing is a function of the vertex index or of the 339 instance index. 340 341 .Valid Usage 342 **** 343 * [[VUID-VkVertexInputBindingDescription-binding-00618]] 344 pname:binding must: be less than 345 sname:VkPhysicalDeviceLimits::pname:maxVertexInputBindings 346 * [[VUID-VkVertexInputBindingDescription-stride-00619]] 347 pname:stride must: be less than or equal to 348 sname:VkPhysicalDeviceLimits::pname:maxVertexInputBindingStride 349 **** 350 351 include::{generated}/validity/structs/VkVertexInputBindingDescription.txt[] 352 -- 353 354 [open,refpage='VkVertexInputRate',desc='Specify rate at which vertex attributes are pulled from buffers',type='enums'] 355 -- 356 357 Possible values of slink:VkVertexInputBindingDescription::pname:inputRate, 358 specifying the rate at which vertex attributes are pulled from buffers, are: 359 360 include::{generated}/api/enums/VkVertexInputRate.txt[] 361 362 * ename:VK_VERTEX_INPUT_RATE_VERTEX specifies that vertex attribute 363 addressing is a function of the vertex index. 364 * ename:VK_VERTEX_INPUT_RATE_INSTANCE specifies that vertex attribute 365 addressing is a function of the instance index. 366 367 -- 368 369 [open,refpage='VkVertexInputAttributeDescription',desc='Structure specifying vertex input attribute description',type='structs'] 370 -- 371 372 Each vertex input attribute is specified by an instance of the 373 sname:VkVertexInputAttributeDescription structure. 374 375 The sname:VkVertexInputAttributeDescription structure is defined as: 376 377 include::{generated}/api/structs/VkVertexInputAttributeDescription.txt[] 378 379 * pname:location is the shader binding location number for this attribute. 380 * pname:binding is the binding number which this attribute takes its data 381 from. 382 * pname:format is the size and type of the vertex attribute data. 383 * pname:offset is a byte offset of this attribute relative to the start of 384 an element in the vertex input binding. 385 386 .Valid Usage 387 **** 388 * [[VUID-VkVertexInputAttributeDescription-location-00620]] 389 pname:location must: be less than 390 sname:VkPhysicalDeviceLimits::pname:maxVertexInputAttributes 391 * [[VUID-VkVertexInputAttributeDescription-binding-00621]] 392 pname:binding must: be less than 393 sname:VkPhysicalDeviceLimits::pname:maxVertexInputBindings 394 * [[VUID-VkVertexInputAttributeDescription-offset-00622]] 395 pname:offset must: be less than or equal to 396 sname:VkPhysicalDeviceLimits::pname:maxVertexInputAttributeOffset 397 * [[VUID-VkVertexInputAttributeDescription-format-00623]] 398 pname:format must: be allowed as a vertex buffer format, as specified by 399 the ename:VK_FORMAT_FEATURE_VERTEX_BUFFER_BIT flag in 400 sname:VkFormatProperties::pname:bufferFeatures returned by 401 fname:vkGetPhysicalDeviceFormatProperties 402 **** 403 404 include::{generated}/validity/structs/VkVertexInputAttributeDescription.txt[] 405 -- 406 407 [open,refpage='vkCmdBindVertexBuffers',desc='Bind vertex buffers to a command buffer',type='protos'] 408 -- 409 410 To bind vertex buffers to a command buffer for use in subsequent draw 411 commands, call: 412 413 include::{generated}/api/protos/vkCmdBindVertexBuffers.txt[] 414 415 * pname:commandBuffer is the command buffer into which the command is 416 recorded. 417 * pname:firstBinding is the index of the first vertex input binding whose 418 state is updated by the command. 419 * pname:bindingCount is the number of vertex input bindings whose state is 420 updated by the command. 421 * pname:pBuffers is a pointer to an array of buffer handles. 422 * pname:pOffsets is a pointer to an array of buffer offsets. 423 424 The values taken from elements [eq]#i# of pname:pBuffers and pname:pOffsets 425 replace the current state for the vertex input binding 426 [eq]#pname:firstBinding {plus} i#, for [eq]#i# in [eq]#[0, 427 pname:bindingCount)#. 428 The vertex input binding is updated to start at the offset indicated by 429 pname:pOffsets[i] from the start of the buffer pname:pBuffers[i]. 430 All vertex input attributes that use each of these bindings will use these 431 updated addresses in their address calculations for subsequent draw 432 commands. 433 434 .Valid Usage 435 **** 436 * [[VUID-vkCmdBindVertexBuffers-firstBinding-00624]] 437 pname:firstBinding must: be less than 438 sname:VkPhysicalDeviceLimits::pname:maxVertexInputBindings 439 * [[VUID-vkCmdBindVertexBuffers-firstBinding-00625]] 440 The sum of pname:firstBinding and pname:bindingCount must: be less than 441 or equal to sname:VkPhysicalDeviceLimits::pname:maxVertexInputBindings 442 * [[VUID-vkCmdBindVertexBuffers-pOffsets-00626]] 443 All elements of pname:pOffsets must: be less than the size of the 444 corresponding element in pname:pBuffers 445 * [[VUID-vkCmdBindVertexBuffers-pBuffers-00627]] 446 All elements of pname:pBuffers must: have been created with the 447 ename:VK_BUFFER_USAGE_VERTEX_BUFFER_BIT flag 448 * [[VUID-vkCmdBindVertexBuffers-pBuffers-00628]] 449 Each element of pname:pBuffers that is non-sparse must: be bound 450 completely and contiguously to a single sname:VkDeviceMemory object 451 **** 452 453 include::{generated}/validity/protos/vkCmdBindVertexBuffers.txt[] 454 -- 455 456 ifdef::VK_EXT_vertex_attribute_divisor[] 457 458 == Vertex Attribute Divisor in Instanced Rendering 459 460 [open,refpage='VkPipelineVertexInputDivisorStateCreateInfoEXT',desc='Structure specifying vertex attributes assignment during instanced rendering',type='structs'] 461 -- 462 463 If 464 <<features-vertexAttributeInstanceRateDivisor,pname:vertexAttributeInstanceRateDivisor>> 465 feature is enabled and the pname:pNext chain of 466 slink:VkPipelineVertexInputStateCreateInfo includes a 467 sname:VkPipelineVertexInputDivisorStateCreateInfoEXT structure, then that 468 structure controls how vertex attributes are assigned to an instance when 469 instanced rendering is enabled. 470 471 The sname:VkPipelineVertexInputDivisorStateCreateInfoEXT structure is 472 defined as: 473 474 include::{generated}/api/structs/VkPipelineVertexInputDivisorStateCreateInfoEXT.txt[] 475 476 * pname:sType is the type of this structure 477 * pname:pNext is `NULL` or a pointer to an extension-specific structure 478 * pname:vertexBindingDivisorCount is the number of elements in the 479 pname:pVertexBindingDivisors array. 480 * pname:pVertexBindingDivisors is a pointer to an array of 481 sname:VkVertexInputBindingDivisorDescriptionEXT structures, which 482 specifies the divisor value for each binding. 483 484 include::{generated}/validity/structs/VkPipelineVertexInputDivisorStateCreateInfoEXT.txt[] 485 -- 486 487 [open,refpage='VkVertexInputBindingDivisorDescriptionEXT',desc='Structure specifying a divisor used in instanced rendering',type='structs'] 488 -- 489 The individual divisor values per binding are specified using the 490 sname:VkVertexInputBindingDivisorDescriptionEXT structure which is defined 491 as: 492 493 include::{generated}/api/structs/VkVertexInputBindingDivisorDescriptionEXT.txt[] 494 495 * pname:binding is the binding number for which the divisor is specified. 496 * pname:divisor is the number of successive instances that will use the 497 same value of the vertex attribute when instanced rendering is enabled. 498 For example, if the divisor is N, the same vertex attribute will applied 499 to N successive instances before moving on to the next vertex attribute. 500 The maximum value of divisor is implementation dependent and can be 501 queried using 502 sname:VkPhysicalDeviceVertexAttributeDivisorPropertiesEXT::pname:maxVertexAttribDivisor. 503 A value of `0` can: be used for the divisor if the 504 <<features-vertexAttributeInstanceRateZeroDivisor,pname:vertexAttributeInstanceRateZeroDivisor>> 505 feature is enabled. 506 In this case, the same vertex attribute will be applied to all 507 instances. 508 509 If this structure is not used to define a divisor value for an attribute 510 then the divisor has a logical default value of 1. 511 512 .Valid Usage 513 **** 514 * [[VUID-VkVertexInputBindingDivisorDescriptionEXT-binding-01869]] 515 pname:binding must: be less than 516 sname:VkPhysicalDeviceLimits::pname:maxVertexInputBindings 517 * [[VUID-VkVertexInputBindingDivisorDescriptionEXT-vertexAttributeInstanceRateZeroDivisor-02228]] 518 If the pname:vertexAttributeInstanceRateZeroDivisor feature is not 519 enabled, pname:divisor must: not be `0` 520 * [[VUID-VkVertexInputBindingDivisorDescriptionEXT-vertexAttributeInstanceRateDivisor-02229]] 521 If the pname:vertexAttributeInstanceRateDivisor feature is not enabled, 522 pname:divisor must: be `1` 523 * [[VUID-VkVertexInputBindingDivisorDescriptionEXT-divisor-01870]] 524 pname:divisor must: be a value between `0` and 525 sname:VkPhysicalDeviceVertexAttributeDivisorPropertiesEXT::pname:maxVertexAttribDivisor, 526 inclusive. 527 * [[VUID-VkVertexInputBindingDivisorDescriptionEXT-inputRate-01871]] 528 slink:VkVertexInputBindingDescription::pname:inputRate must: be of type 529 ename:VK_VERTEX_INPUT_RATE_INSTANCE for this pname:binding. 530 **** 531 532 include::{generated}/validity/structs/VkVertexInputBindingDivisorDescriptionEXT.txt[] 533 -- 534 535 endif::VK_EXT_vertex_attribute_divisor[] 536 537 The address of each attribute for each code:vertexIndex and 538 code:instanceIndex is calculated as follows: 539 540 * Let code:attribDesc be the member of 541 sname:VkPipelineVertexInputStateCreateInfo::pname:pVertexAttributeDescriptions 542 with sname:VkVertexInputAttributeDescription::pname:location equal to 543 the vertex input attribute number. 544 * Let code:bindingDesc be the member of 545 sname:VkPipelineVertexInputStateCreateInfo::pname:pVertexBindingDescriptions 546 with sname:VkVertexInputAttributeDescription::pname:binding equal to 547 code:attribDesc.binding. 548 * Let code:vertexIndex be the index of the vertex within the draw (a value 549 between pname:firstVertex and pname:firstVertex+pname:vertexCount for 550 fname:vkCmdDraw, or a value taken from the index buffer for 551 fname:vkCmdDrawIndexed), and let code:instanceIndex be the instance 552 number of the draw (a value between pname:firstInstance and 553 pname:firstInstance+pname:instanceCount). 554 ifdef::VK_EXT_vertex_attribute_divisor[] 555 * Let code:divisor be the member of 556 sname:VkPipelineVertexInputDivisorStateCreateInfoEXT::pname:pVertexBindingDivisors 557 with sname:VkVertexInputBindingDivisorDescriptionEXT::pname:binding 558 equal to code:attribDesc.binding. 559 endif::VK_EXT_vertex_attribute_divisor[] 560 561 [source,c] 562 --------------------------------------------------- 563 bufferBindingAddress = buffer[binding].baseAddress + offset[binding]; 564 565 if (bindingDesc.inputRate == VK_VERTEX_INPUT_RATE_VERTEX) 566 vertexOffset = vertexIndex * bindingDesc.stride; 567 else 568 ifndef::VK_EXT_vertex_attribute_divisor[] 569 vertexOffset = instanceIndex * bindingDesc.stride; 570 endif::VK_EXT_vertex_attribute_divisor[] 571 ifdef::VK_EXT_vertex_attribute_divisor[] 572 if (divisor == 0) 573 vertexOffset = firstInstance * bindingDesc.stride; 574 else 575 vertexOffset = (firstInstance + ((instanceIndex - firstInstance) / divisor)) * bindingDesc.stride; 576 endif::VK_EXT_vertex_attribute_divisor[] 577 578 attribAddress = bufferBindingAddress + vertexOffset + attribDesc.offset; 579 --------------------------------------------------- 580 581 [[fxvertex-input-extraction]] 582 For each attribute, raw data is extracted starting at `attribAddress` and is 583 converted from the sname:VkVertexInputAttributeDescription's pname:format to 584 either to floating-point, unsigned integer, or signed integer based on the 585 base type of the format; the base type of the format must: match the base 586 type of the input variable in the shader. 587 If pname:format is a packed format, `attribAddress` must: be a multiple of 588 the size in bytes of the whole attribute data type as described in 589 <<formats-packed,Packed Formats>>. 590 Otherwise, `attribAddress` must: be a multiple of the size in bytes of the 591 component type indicated by pname:format (see <<formats,Formats>>). 592 If the format does not include G, B, or A components, then those are filled 593 with [eq]#(0,0,1)# as needed (using either 1.0f or integer 1 based on the 594 format) for attributes that are not 64-bit data types. 595 The number of components in the vertex shader input variable need not 596 exactly match the number of components in the format. 597 If the vertex shader has fewer components, the extra components are 598 discarded. 599 600 [[fxvertex-example]] 601 == Example 602 603 To create a graphics pipeline that uses the following vertex description: 604 605 [source,c++] 606 --------------------------------------------------- 607 struct Vertex 608 { 609 float x, y, z, w; 610 uint8_t u, v; 611 }; 612 --------------------------------------------------- 613 614 The application could use the following set of structures: 615 616 [source,c++] 617 --------------------------------------------------- 618 const VkVertexInputBindingDescription binding = 619 { 620 0, // binding 621 sizeof(Vertex), // stride 622 VK_VERTEX_INPUT_RATE_VERTEX // inputRate 623 }; 624 625 const VkVertexInputAttributeDescription attributes[] = 626 { 627 { 628 0, // location 629 binding.binding, // binding 630 VK_FORMAT_R32G32B32A32_SFLOAT, // format 631 0 // offset 632 }, 633 { 634 1, // location 635 binding.binding, // binding 636 VK_FORMAT_R8G8_UNORM, // format 637 4 * sizeof(float) // offset 638 } 639 }; 640 641 const VkPipelineVertexInputStateCreateInfo viInfo = 642 { 643 VK_STRUCTURE_TYPE_PIPELINE_VERTEX_INPUT_CREATE_INFO, // sType 644 NULL, // pNext 645 0, // flags 646 1, // vertexBindingDescriptionCount 647 &binding, // pVertexBindingDescriptions 648 2, // vertexAttributeDescriptionCount 649 &attributes[0] // pVertexAttributeDescriptions 650 }; 651 ---------------------------------------------------