// Copyright 2015-2022 The Khronos Group Inc. // // SPDX-License-Identifier: CC-BY-4.0 [[fxvertex]] = Fixed-Function Vertex Processing Vertex fetching is controlled via configurable state, as a logically distinct graphics pipeline stage. [[fxvertex-attrib]] == Vertex Attributes Vertex shaders can: define input variables, which receive _vertex attribute_ data transferred from one or more sname:VkBuffer(s) by drawing commands. Vertex shader input variables are bound to buffers via an indirect binding where the vertex shader associates a _vertex input attribute_ number with each variable, vertex input attributes are associated to _vertex input bindings_ on a per-pipeline basis, and vertex input bindings are associated with specific buffers on a per-draw basis via the fname:vkCmdBindVertexBuffers command. Vertex input attribute and vertex input binding descriptions also contain format information controlling how data is extracted from buffer memory and converted to the format expected by the vertex shader. There are sname:VkPhysicalDeviceLimits::pname:maxVertexInputAttributes number of vertex input attributes and sname:VkPhysicalDeviceLimits::pname:maxVertexInputBindings number of vertex input bindings (each referred to by zero-based indices), where there are at least as many vertex input attributes as there are vertex input bindings. Applications can: store multiple vertex input attributes interleaved in a single buffer, and use a single vertex input binding to access those attributes. In GLSL, vertex shaders associate input variables with a vertex input attribute number using the code:location layout qualifier. The code:component layout qualifier associates components of a vertex shader input variable with components of a vertex input attribute. .GLSL example [source,glsl] --------------------------------------------------- // Assign location M to variableName layout (location=M, component=2) in vec2 variableName; // Assign locations [N,N+L) to the array elements of variableNameArray layout (location=N) in vec4 variableNameArray[L]; --------------------------------------------------- In SPIR-V, vertex shaders associate input variables with a vertex input attribute number using the code:Location decoration. The code:Component decoration associates components of a vertex shader input variable with components of a vertex input attribute. The code:Location and code:Component decorations are specified via the code:OpDecorate instruction. .SPIR-V example [source,spirv] --------------------------------------------------- ... %1 = OpExtInstImport "GLSL.std.450" ... OpName %9 "variableName" OpName %15 "variableNameArray" OpDecorate %18 BuiltIn VertexIndex OpDecorate %19 BuiltIn InstanceIndex OpDecorate %9 Location M OpDecorate %9 Component 2 OpDecorate %15 Location N ... %2 = OpTypeVoid %3 = OpTypeFunction %2 %6 = OpTypeFloat 32 %7 = OpTypeVector %6 2 %8 = OpTypePointer Input %7 %9 = OpVariable %8 Input %10 = OpTypeVector %6 4 %11 = OpTypeInt 32 0 %12 = OpConstant %11 L %13 = OpTypeArray %10 %12 %14 = OpTypePointer Input %13 %15 = OpVariable %14 Input ... --------------------------------------------------- [[fxvertex-attrib-location]] === Attribute Location and Component Assignment Vertex shaders allow code:Location and code:Component decorations on input variable declarations. The code:Location decoration specifies which vertex input attribute is used to read and interpret the data that a variable will consume. The code:Component decoration allows the location to be more finely specified for scalars and vectors, down to the individual components within a location that are consumed. The components within a location are 0, 1, 2, and 3. A variable starting at component N will consume components N, N+1, N+2, ... up through its size. For single precision types, it is invalid if the sequence of components gets larger than 3. When a vertex shader input variable declared using a 16- or 32-bit scalar or vector data type is assigned a location, its value(s) are taken from the components of the input attribute specified with the corresponding sname:VkVertexInputAttributeDescription::pname:location. The components used depend on the type of variable and the code:Component decoration specified in the variable declaration, as identified in <>. Any 16-bit or 32-bit scalar or vector input will consume a single location. For 16-bit and 32-bit data types, missing components are filled in with default values as described <>. [[fxvertex-attrib-components]] .Input attribute components accessed by 16-bit and 32-bit input variables [width="65%",cols="<5,<3,<3",options="header"] |==== | 16-bit or 32-bit data type | code:Component decoration | Components consumed | scalar | 0 or unspecified | (x, o, o, o) | scalar | 1 | (o, y, o, o) | scalar | 2 | (o, o, z, o) | scalar | 3 | (o, o, o, w) | two-component vector | 0 or unspecified | (x, y, o, o) | two-component vector | 1 | (o, y, z, o) | two-component vector | 2 | (o, o, z, w) | three-component vector | 0 or unspecified | (x, y, z, o) | three-component vector | 1 | (o, y, z, w) | four-component vector | 0 or unspecified | (x, y, z, w) |==== Components indicated by "`o`" are available for use by other input variables which are sourced from the same attribute, and if used, are either filled with the corresponding component from the input format (if present), or the default value. When a vertex shader input variable declared using a 32-bit floating point matrix type is assigned a location _i_, its values are taken from consecutive input attributes starting with the corresponding sname:VkVertexInputAttributeDescription::pname:location. Such matrices are treated as an array of column vectors with values taken from the input attributes identified in <>. The sname:VkVertexInputAttributeDescription::pname:format must: be specified with a elink:VkFormat that corresponds to the appropriate type of column vector. The code:Component decoration must: not be used with matrix types. [[fxvertex-attrib-matrix]] .Input attributes accessed by 32-bit input matrix variables [width="100%",cols="<10%,<24%,<21%,<45%",options="header"] |==== | Data type | Column vector type | Locations consumed | Components consumed | mat2 | two-component vector | i, i+1 | (x, y, o, o), (x, y, o, o) | mat2x3 | three-component vector | i, i+1 | (x, y, z, o), (x, y, z, o) | mat2x4 | four-component vector | i, i+1 | (x, y, z, w), (x, y, z, w) | mat3x2 | two-component vector | i, i+1, i+2 | (x, y, o, o), (x, y, o, o), (x, y, o, o) | mat3 | three-component vector | i, i+1, i+2 | (x, y, z, o), (x, y, z, o), (x, y, z, o) | mat3x4 | four-component vector | i, i+1, i+2 | (x, y, z, w), (x, y, z, w), (x, y, z, w) | 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) | 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) | 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) |==== Components indicated by "`o`" are available for use by other input variables which are sourced from the same attribute, and if used, are either filled with the corresponding component from the input (if present), or the default value. When a vertex shader input variable declared using a scalar or vector 64-bit data type is assigned a location _i_, its values are taken from consecutive input attributes starting with the corresponding sname:VkVertexInputAttributeDescription::pname:location. The locations and components used depend on the type of variable and the code:Component decoration specified in the variable declaration, as identified in <>. For 64-bit data types, no default attribute values are provided. Input variables must: not use more components than provided by the attribute. Input attributes which have one- or two-component 64-bit formats will consume a single location. Input attributes which have three- or four-component 64-bit formats will consume two consecutive locations. A 64-bit scalar data type will consume two components, and a 64-bit two-component vector data type will consume all four components available within a location. A three- or four-component 64-bit data type must: not specify a component. A three-component 64-bit data type will consume all four components of the first location and components 0 and 1 of the second location. This leaves components 2 and 3 available for other component-qualified declarations. A four-component 64-bit data type will consume all four components of the first location and all four components of the second location. It is invalid for a scalar or two-component 64-bit data type to specify a component of 1 or 3. [[fxvertex-attrib-double]] .Input attribute locations and components accessed by 64-bit input variables [width="100%",cols="<18%,^12%,<25%,^14%,^18%,<13%",options="header"] |==== ^.^| Input format | Locations consumed ^.^| 64-bit data type |code:Location decoration |code:Component decoration ^| 32-bit components consumed | R64 | i | scalar | i | 0 or unspecified | (x, y, -, -) .3+<.^| R64G64 .3+^.^| i | scalar | i | 0 or unspecified | (x, y, o, o) | scalar | i | 2 | (o, o, z, w) | two-component vector | i | 0 or unspecified | (x, y, z, w) .5+<.^| R64G64B64 .5+^.^| i, i+1 | scalar | i | 0 or unspecified | (x, y, o, o), (o, o, -, -) | scalar | i | 2 | (o, o, z, w), (o, o, -, -) | scalar | i+1 | 0 or unspecified | (o, o, o, o), (x, y, -, -) | two-component vector | i | 0 or unspecified | (x, y, z, w), (o, o, -, -) | three-component vector | i | unspecified | (x, y, z, w), (x, y, -, -) .8+<.^| R64G64B64A64 .8+^.^| i, i+1 | scalar | i | 0 or unspecified | (x, y, o, o), (o, o, o, o) | scalar | i | 2 | (o, o, z, w), (o, o, o, o) | scalar | i+1 | 0 or unspecified | (o, o, o, o), (x, y, o, o) | scalar | i+1 | 2 | (o, o, o, o), (o, o, z, w) | two-component vector | i | 0 or unspecified | (x, y, z, w), (o, o, o, o) | two-component vector | i+1 | 0 or unspecified | (o, o, o, o), (x, y, z, w) | three-component vector | i | unspecified | (x, y, z, w), (x, y, o, o) | four-component vector | i | unspecified | (x, y, z, w), (x, y, z, w) |==== Components indicated by "`o`" are available for use by other input variables which are sourced from the same attribute. Components indicated by "`-`" are not available for input variables as there are no default values provided for 64-bit data types, and there is no data provided by the input format. When a vertex shader input variable declared using a 64-bit floating-point matrix type is assigned a location _i_, its values are taken from consecutive input attribute locations. Such matrices are treated as an array of column vectors with values taken from the input attributes as shown in <>. Each column vector starts at the location immediately following the last location of the previous column vector. The number of attributes and components assigned to each matrix is determined by the matrix dimensions and ranges from two to eight locations. When a vertex shader input variable declared using an array type is assigned a location, its values are taken from consecutive input attributes starting with the corresponding sname:VkVertexInputAttributeDescription::pname:location. The number of attributes and components assigned to each element are determined according to the data type of the array elements and code:Component decoration (if any) specified in the declaration of the array, as described above. Each element of the array, in order, is assigned to consecutive locations, but all at the same specified component within each location. Only input variables declared with the data types and component decorations as specified above are supported. _Location aliasing_ is causing two variables to have the same location number. _Component aliasing_ is assigning the same (or overlapping) component number for two location aliases. Location aliasing is allowed only if it does not cause component aliasing. Further, when location aliasing, the aliases sharing the location must: all have the same SPIR-V floating-point component type or all have the same width integer-type components. [[fxvertex-input]] == Vertex Input Description Applications specify vertex input attribute and vertex input binding descriptions as part of graphics pipeline creation by setting the slink:VkGraphicsPipelineCreateInfo::pname:pVertexInputState pointer to a slink:VkPipelineVertexInputStateCreateInfo structure. ifdef::VK_EXT_vertex_input_dynamic_state[] Alternatively, if the graphics pipeline is created with the ename:VK_DYNAMIC_STATE_VERTEX_INPUT_EXT dynamic state enabled, then the vertex input attribute and vertex input binding descriptions are specified dynamically with flink:vkCmdSetVertexInputEXT, and the slink:VkGraphicsPipelineCreateInfo::pname:pVertexInputState pointer is ignored. endif::VK_EXT_vertex_input_dynamic_state[] [open,refpage='VkPipelineVertexInputStateCreateInfo',desc='Structure specifying parameters of a newly created pipeline vertex input state',type='structs'] -- The sname:VkPipelineVertexInputStateCreateInfo structure is defined as: include::{generated}/api/structs/VkPipelineVertexInputStateCreateInfo.adoc[] * pname:sType is the type of this structure. * pname:pNext is `NULL` or a pointer to a structure extending this structure. * pname:flags is reserved for future use. * pname:vertexBindingDescriptionCount is the number of vertex binding descriptions provided in pname:pVertexBindingDescriptions. * pname:pVertexBindingDescriptions is a pointer to an array of sname:VkVertexInputBindingDescription structures. * pname:vertexAttributeDescriptionCount is the number of vertex attribute descriptions provided in pname:pVertexAttributeDescriptions. * pname:pVertexAttributeDescriptions is a pointer to an array of sname:VkVertexInputAttributeDescription structures. .Valid Usage **** * [[VUID-VkPipelineVertexInputStateCreateInfo-vertexBindingDescriptionCount-00613]] pname:vertexBindingDescriptionCount must: be less than or equal to sname:VkPhysicalDeviceLimits::pname:maxVertexInputBindings * [[VUID-VkPipelineVertexInputStateCreateInfo-vertexAttributeDescriptionCount-00614]] pname:vertexAttributeDescriptionCount must: be less than or equal to sname:VkPhysicalDeviceLimits::pname:maxVertexInputAttributes * [[VUID-VkPipelineVertexInputStateCreateInfo-binding-00615]] For every pname:binding specified by each element of pname:pVertexAttributeDescriptions, a sname:VkVertexInputBindingDescription must: exist in pname:pVertexBindingDescriptions with the same value of pname:binding * [[VUID-VkPipelineVertexInputStateCreateInfo-pVertexBindingDescriptions-00616]] All elements of pname:pVertexBindingDescriptions must: describe distinct binding numbers * [[VUID-VkPipelineVertexInputStateCreateInfo-pVertexAttributeDescriptions-00617]] All elements of pname:pVertexAttributeDescriptions must: describe distinct attribute locations **** include::{generated}/validity/structs/VkPipelineVertexInputStateCreateInfo.adoc[] -- [open,refpage='VkPipelineVertexInputStateCreateFlags',desc='Reserved for future use',type='flags'] -- include::{generated}/api/flags/VkPipelineVertexInputStateCreateFlags.adoc[] tname:VkPipelineVertexInputStateCreateFlags is a bitmask type for setting a mask, but is currently reserved for future use. -- [open,refpage='VkVertexInputBindingDescription',desc='Structure specifying vertex input binding description',type='structs'] -- Each vertex input binding is specified by the sname:VkVertexInputBindingDescription structure, defined as: include::{generated}/api/structs/VkVertexInputBindingDescription.adoc[] * pname:binding is the binding number that this structure describes. * pname:stride is the byte stride between consecutive elements within the buffer. * pname:inputRate is a elink:VkVertexInputRate value specifying whether vertex attribute addressing is a function of the vertex index or of the instance index. .Valid Usage **** * [[VUID-VkVertexInputBindingDescription-binding-00618]] pname:binding must: be less than sname:VkPhysicalDeviceLimits::pname:maxVertexInputBindings * [[VUID-VkVertexInputBindingDescription-stride-00619]] pname:stride must: be less than or equal to sname:VkPhysicalDeviceLimits::pname:maxVertexInputBindingStride ifdef::VK_KHR_portability_subset[] * [[VUID-VkVertexInputBindingDescription-stride-04456]] If the `apiext:VK_KHR_portability_subset` extension is enabled, pname:stride must: be a multiple of, and at least as large as, slink:VkPhysicalDevicePortabilitySubsetPropertiesKHR::pname:minVertexInputBindingStrideAlignment endif::VK_KHR_portability_subset[] **** include::{generated}/validity/structs/VkVertexInputBindingDescription.adoc[] -- [open,refpage='VkVertexInputRate',desc='Specify rate at which vertex attributes are pulled from buffers',type='enums'] -- Possible values of slink:VkVertexInputBindingDescription::pname:inputRate, specifying the rate at which vertex attributes are pulled from buffers, are: include::{generated}/api/enums/VkVertexInputRate.adoc[] * ename:VK_VERTEX_INPUT_RATE_VERTEX specifies that vertex attribute addressing is a function of the vertex index. * ename:VK_VERTEX_INPUT_RATE_INSTANCE specifies that vertex attribute addressing is a function of the instance index. -- [open,refpage='VkVertexInputAttributeDescription',desc='Structure specifying vertex input attribute description',type='structs'] -- Each vertex input attribute is specified by the sname:VkVertexInputAttributeDescription structure, defined as: include::{generated}/api/structs/VkVertexInputAttributeDescription.adoc[] * pname:location is the shader input location number for this attribute. * pname:binding is the binding number which this attribute takes its data from. * pname:format is the size and type of the vertex attribute data. * pname:offset is a byte offset of this attribute relative to the start of an element in the vertex input binding. .Valid Usage **** * [[VUID-VkVertexInputAttributeDescription-location-00620]] pname:location must: be less than sname:VkPhysicalDeviceLimits::pname:maxVertexInputAttributes * [[VUID-VkVertexInputAttributeDescription-binding-00621]] pname:binding must: be less than sname:VkPhysicalDeviceLimits::pname:maxVertexInputBindings * [[VUID-VkVertexInputAttributeDescription-offset-00622]] pname:offset must: be less than or equal to sname:VkPhysicalDeviceLimits::pname:maxVertexInputAttributeOffset * [[VUID-VkVertexInputAttributeDescription-format-00623]] pname:format must: be allowed as a vertex buffer format, as specified by the ename:VK_FORMAT_FEATURE_VERTEX_BUFFER_BIT flag in sname:VkFormatProperties::pname:bufferFeatures returned by fname:vkGetPhysicalDeviceFormatProperties ifdef::VK_KHR_portability_subset[] * [[VUID-VkVertexInputAttributeDescription-vertexAttributeAccessBeyondStride-04457]] If the `apiext:VK_KHR_portability_subset` extension is enabled, and slink:VkPhysicalDevicePortabilitySubsetFeaturesKHR::pname:vertexAttributeAccessBeyondStride is ename:VK_FALSE, the sum of pname:offset plus the size of the vertex attribute data described by pname:format must: not be greater than pname:stride in the slink:VkVertexInputBindingDescription referenced in pname:binding endif::VK_KHR_portability_subset[] **** include::{generated}/validity/structs/VkVertexInputAttributeDescription.adoc[] -- ifdef::VK_EXT_vertex_input_dynamic_state[] [open,refpage='vkCmdSetVertexInputEXT',desc='Set the vertex input state dynamically for a command buffer',type='protos'] -- To <> the vertex input attribute and vertex input binding descriptions, call: include::{generated}/api/protos/vkCmdSetVertexInputEXT.adoc[] * pname:commandBuffer is the command buffer into which the command will be recorded. * pname:vertexBindingDescriptionCount is the number of vertex binding descriptions provided in pname:pVertexBindingDescriptions. * pname:pVertexBindingDescriptions is a pointer to an array of sname:VkVertexInputBindingDescription2EXT structures. * pname:vertexAttributeDescriptionCount is the number of vertex attribute descriptions provided in pname:pVertexAttributeDescriptions. * pname:pVertexAttributeDescriptions is a pointer to an array of sname:VkVertexInputAttributeDescription2EXT structures. This command sets the vertex input attribute and vertex input binding descriptions state for subsequent drawing commands when the graphics pipeline is created with ename:VK_DYNAMIC_STATE_VERTEX_INPUT_EXT set in slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. Otherwise, this state is specified by the slink:VkGraphicsPipelineCreateInfo::pname:pVertexInputState values used to create the currently active pipeline. ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[] If the bound pipeline state object was also created with the ename:VK_DYNAMIC_STATE_VERTEX_INPUT_BINDING_STRIDE dynamic state enabled, then flink:vkCmdBindVertexBuffers2 can be used instead of fname:vkCmdSetVertexInputEXT to dynamically set the stride. endif::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[] .Valid Usage **** * [[VUID-vkCmdSetVertexInputEXT-None-04790]] The <> feature must: be enabled * [[VUID-vkCmdSetVertexInputEXT-vertexBindingDescriptionCount-04791]] pname:vertexBindingDescriptionCount must: be less than or equal to sname:VkPhysicalDeviceLimits::pname:maxVertexInputBindings * [[VUID-vkCmdSetVertexInputEXT-vertexAttributeDescriptionCount-04792]] pname:vertexAttributeDescriptionCount must: be less than or equal to sname:VkPhysicalDeviceLimits::pname:maxVertexInputAttributes * [[VUID-vkCmdSetVertexInputEXT-binding-04793]] For every pname:binding specified by each element of pname:pVertexAttributeDescriptions, a sname:VkVertexInputBindingDescription2EXT must: exist in pname:pVertexBindingDescriptions with the same value of pname:binding * [[VUID-vkCmdSetVertexInputEXT-pVertexBindingDescriptions-04794]] All elements of pname:pVertexBindingDescriptions must: describe distinct binding numbers * [[VUID-vkCmdSetVertexInputEXT-pVertexAttributeDescriptions-04795]] All elements of pname:pVertexAttributeDescriptions must: describe distinct attribute locations **** include::{generated}/validity/protos/vkCmdSetVertexInputEXT.adoc[] -- [open,refpage='VkVertexInputBindingDescription2EXT',desc='Structure specifying the extended vertex input binding description',type='structs'] -- The sname:VkVertexInputBindingDescription2EXT structure is defined as: include::{generated}/api/structs/VkVertexInputBindingDescription2EXT.adoc[] * pname:sType is the type of this structure. * pname:pNext is `NULL` or a pointer to a structure extending this structure. * pname:binding is the binding number that this structure describes. * pname:stride is the byte stride between consecutive elements within the buffer. * pname:inputRate is a elink:VkVertexInputRate value specifying whether vertex attribute addressing is a function of the vertex index or of the instance index. ifdef::VK_EXT_vertex_attribute_divisor[] * pname:divisor is the number of successive instances that will use the same value of the vertex attribute when instanced rendering is enabled. This member can: be set to a value other than `1` if the <> feature is enabled. For example, if the divisor is N, the same vertex attribute will be applied to N successive instances before moving on to the next vertex attribute. The maximum value of pname:divisor is implementation-dependent and can be queried using sname:VkPhysicalDeviceVertexAttributeDivisorPropertiesEXT::pname:maxVertexAttribDivisor. A value of `0` can: be used for the divisor if the <> feature is enabled. In this case, the same vertex attribute will be applied to all instances. endif::VK_EXT_vertex_attribute_divisor[] ifndef::VK_EXT_vertex_attribute_divisor[] * pname:divisor must: be set to `1` endif::VK_EXT_vertex_attribute_divisor[] .Valid Usage **** * [[VUID-VkVertexInputBindingDescription2EXT-binding-04796]] pname:binding must: be less than sname:VkPhysicalDeviceLimits::pname:maxVertexInputBindings * [[VUID-VkVertexInputBindingDescription2EXT-stride-04797]] pname:stride must: be less than or equal to sname:VkPhysicalDeviceLimits::pname:maxVertexInputBindingStride * [[VUID-VkVertexInputBindingDescription2EXT-divisor-04798]] If the <> feature is not enabled, pname:divisor must: not be `0` * [[VUID-VkVertexInputBindingDescription2EXT-divisor-04799]] If the <> feature is not enabled, pname:divisor must: be `1` * [[VUID-VkVertexInputBindingDescription2EXT-divisor-06226]] pname:divisor must: be a value between `0` and sname:VkPhysicalDeviceVertexAttributeDivisorPropertiesEXT::pname:maxVertexAttribDivisor, inclusive * [[VUID-VkVertexInputBindingDescription2EXT-divisor-06227]] If pname:divisor is not `1` then pname:inputRate must: be of type ename:VK_VERTEX_INPUT_RATE_INSTANCE **** include::{generated}/validity/structs/VkVertexInputBindingDescription2EXT.adoc[] -- [open,refpage='VkVertexInputAttributeDescription2EXT',desc='Structure specifying the extended vertex input attribute description',type='structs'] -- The sname:VkVertexInputAttributeDescription2EXT structure is defined as: include::{generated}/api/structs/VkVertexInputAttributeDescription2EXT.adoc[] * pname:sType is the type of this structure. * pname:pNext is `NULL` or a pointer to a structure extending this structure. * pname:location is the shader input location number for this attribute. * pname:binding is the binding number which this attribute takes its data from. * pname:format is the size and type of the vertex attribute data. * pname:offset is a byte offset of this attribute relative to the start of an element in the vertex input binding. .Valid Usage **** * [[VUID-VkVertexInputAttributeDescription2EXT-location-06228]] pname:location must: be less than sname:VkPhysicalDeviceLimits::pname:maxVertexInputAttributes * [[VUID-VkVertexInputAttributeDescription2EXT-binding-06229]] pname:binding must: be less than sname:VkPhysicalDeviceLimits::pname:maxVertexInputBindings * [[VUID-VkVertexInputAttributeDescription2EXT-offset-06230]] pname:offset must: be less than or equal to sname:VkPhysicalDeviceLimits::pname:maxVertexInputAttributeOffset * [[VUID-VkVertexInputAttributeDescription2EXT-format-04805]] pname:format must: be allowed as a vertex buffer format, as specified by the ename:VK_FORMAT_FEATURE_VERTEX_BUFFER_BIT flag in sname:VkFormatProperties::pname:bufferFeatures returned by fname:vkGetPhysicalDeviceFormatProperties ifdef::VK_KHR_portability_subset[] * [[VUID-VkVertexInputAttributeDescription2EXT-vertexAttributeAccessBeyondStride-04806]] If the `apiext:VK_KHR_portability_subset` extension is enabled, and slink:VkPhysicalDevicePortabilitySubsetFeaturesKHR::pname:vertexAttributeAccessBeyondStride is ename:VK_FALSE, the sum of pname:offset plus the size of the vertex attribute data described by pname:format must: not be greater than pname:stride in the slink:VkVertexInputBindingDescription2EXT referenced in pname:binding endif::VK_KHR_portability_subset[] **** include::{generated}/validity/structs/VkVertexInputAttributeDescription2EXT.adoc[] -- endif::VK_EXT_vertex_input_dynamic_state[] [open,refpage='vkCmdBindVertexBuffers',desc='Bind vertex buffers to a command buffer',type='protos'] -- To bind vertex buffers to a command buffer for use in subsequent drawing commands, call: include::{generated}/api/protos/vkCmdBindVertexBuffers.adoc[] * pname:commandBuffer is the command buffer into which the command is recorded. * pname:firstBinding is the index of the first vertex input binding whose state is updated by the command. * pname:bindingCount is the number of vertex input bindings whose state is updated by the command. * pname:pBuffers is a pointer to an array of buffer handles. * pname:pOffsets is a pointer to an array of buffer offsets. The values taken from elements [eq]#i# of pname:pBuffers and pname:pOffsets replace the current state for the vertex input binding [eq]#pname:firstBinding {plus} i#, for [eq]#i# in [eq]#[0, pname:bindingCount)#. The vertex input binding is updated to start at the offset indicated by pname:pOffsets[i] from the start of the buffer pname:pBuffers[i]. All vertex input attributes that use each of these bindings will use these updated addresses in their address calculations for subsequent drawing commands. ifdef::VK_EXT_robustness2[] If the <> feature is enabled, elements of pname:pBuffers can: be dlink:VK_NULL_HANDLE, and can: be used by the vertex shader. If a vertex input attribute is bound to a vertex input binding that is dlink:VK_NULL_HANDLE, the values taken from memory are considered to be zero, and missing G, B, or A components are <>. endif::VK_EXT_robustness2[] .Valid Usage **** * [[VUID-vkCmdBindVertexBuffers-firstBinding-00624]] pname:firstBinding must: be less than sname:VkPhysicalDeviceLimits::pname:maxVertexInputBindings * [[VUID-vkCmdBindVertexBuffers-firstBinding-00625]] The sum of pname:firstBinding and pname:bindingCount must: be less than or equal to sname:VkPhysicalDeviceLimits::pname:maxVertexInputBindings * [[VUID-vkCmdBindVertexBuffers-pOffsets-00626]] All elements of pname:pOffsets must: be less than the size of the corresponding element in pname:pBuffers * [[VUID-vkCmdBindVertexBuffers-pBuffers-00627]] All elements of pname:pBuffers must: have been created with the ename:VK_BUFFER_USAGE_VERTEX_BUFFER_BIT flag * [[VUID-vkCmdBindVertexBuffers-pBuffers-00628]] Each element of pname:pBuffers that is non-sparse must: be bound completely and contiguously to a single sname:VkDeviceMemory object * [[VUID-vkCmdBindVertexBuffers-pBuffers-04001]] If the <> feature is not enabled, all elements of pname:pBuffers must: not be dlink:VK_NULL_HANDLE ifdef::VK_EXT_robustness2[] * [[VUID-vkCmdBindVertexBuffers-pBuffers-04002]] If an element of pname:pBuffers is dlink:VK_NULL_HANDLE, then the corresponding element of pname:pOffsets must: be zero endif::VK_EXT_robustness2[] **** include::{generated}/validity/protos/vkCmdBindVertexBuffers.adoc[] -- ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[] [open,refpage='vkCmdBindVertexBuffers2',desc='Bind vertex buffers to a command buffer and dynamically set strides',type='protos',alias='vkCmdBindVertexBuffers2EXT'] -- Alternatively, to bind vertex buffers, along with their sizes and strides, to a command buffer for use in subsequent drawing commands, call: ifdef::VK_VERSION_1_3[] include::{generated}/api/protos/vkCmdBindVertexBuffers2.adoc[] endif::VK_VERSION_1_3[] ifdef::VK_VERSION_1_3+VK_EXT_extended_dynamic_state[or the equivalent command] ifdef::VK_EXT_extended_dynamic_state[] include::{generated}/api/protos/vkCmdBindVertexBuffers2EXT.adoc[] endif::VK_EXT_extended_dynamic_state[] * pname:commandBuffer is the command buffer into which the command is recorded. * pname:firstBinding is the index of the first vertex input binding whose state is updated by the command. * pname:bindingCount is the number of vertex input bindings whose state is updated by the command. * pname:pBuffers is a pointer to an array of buffer handles. * pname:pOffsets is a pointer to an array of buffer offsets. * pname:pSizes is `NULL` or a pointer to an array of the size in bytes of vertex data bound from pname:pBuffers. * pname:pStrides is `NULL` or a pointer to an array of buffer strides. The values taken from elements [eq]#i# of pname:pBuffers and pname:pOffsets replace the current state for the vertex input binding [eq]#pname:firstBinding {plus} i#, for [eq]#i# in [eq]#[0, pname:bindingCount)#. The vertex input binding is updated to start at the offset indicated by pname:pOffsets[i] from the start of the buffer pname:pBuffers[i]. If pname:pSizes is not `NULL` then pname:pSizes[i] specifies the bound size of the vertex buffer starting from the corresponding elements of pname:pBuffers[i] plus pname:pOffsets[i]. All vertex input attributes that use each of these bindings will use these updated addresses in their address calculations for subsequent drawing commands. ifdef::VK_EXT_robustness2[] If the <> feature is enabled, elements of pname:pBuffers can: be dlink:VK_NULL_HANDLE, and can: be used by the vertex shader. If a vertex input attribute is bound to a vertex input binding that is dlink:VK_NULL_HANDLE, the values taken from memory are considered to be zero, and missing G, B, or A components are <>. endif::VK_EXT_robustness2[] This command also <> the byte strides between consecutive elements within buffer pname:pBuffers[i] to the corresponding pname:pStrides[i] value when the graphics pipeline is created with ename:VK_DYNAMIC_STATE_VERTEX_INPUT_BINDING_STRIDE set in slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. Otherwise, strides are specified by the sname:VkVertexInputBindingDescription::pname:stride values used to create the currently active pipeline. ifdef::VK_EXT_vertex_input_dynamic_state[] If the bound pipeline state object was also created with the ename:VK_DYNAMIC_STATE_VERTEX_INPUT_EXT dynamic state enabled then flink:vkCmdSetVertexInputEXT can: be used instead of fname:vkCmdBindVertexBuffers2 to set the stride. endif::VK_EXT_vertex_input_dynamic_state[] .Valid Usage **** * [[VUID-vkCmdBindVertexBuffers2-firstBinding-03355]] pname:firstBinding must: be less than sname:VkPhysicalDeviceLimits::pname:maxVertexInputBindings * [[VUID-vkCmdBindVertexBuffers2-firstBinding-03356]] The sum of pname:firstBinding and pname:bindingCount must: be less than or equal to sname:VkPhysicalDeviceLimits::pname:maxVertexInputBindings * [[VUID-vkCmdBindVertexBuffers2-pOffsets-03357]] All elements of pname:pOffsets must: be less than the size of the corresponding element in pname:pBuffers * [[VUID-vkCmdBindVertexBuffers2-pSizes-03358]] If pname:pSizes is not `NULL`, all elements of pname:pOffsets plus pname:pSizes must: be less than or equal to the size of the corresponding element in pname:pBuffers * [[VUID-vkCmdBindVertexBuffers2-pBuffers-03359]] All elements of pname:pBuffers must: have been created with the ename:VK_BUFFER_USAGE_VERTEX_BUFFER_BIT flag * [[VUID-vkCmdBindVertexBuffers2-pBuffers-03360]] Each element of pname:pBuffers that is non-sparse must: be bound completely and contiguously to a single sname:VkDeviceMemory object * [[VUID-vkCmdBindVertexBuffers2-pBuffers-04111]] If the <> feature is not enabled, all elements of pname:pBuffers must: not be dlink:VK_NULL_HANDLE ifdef::VK_EXT_robustness2[] * [[VUID-vkCmdBindVertexBuffers2-pBuffers-04112]] If an element of pname:pBuffers is dlink:VK_NULL_HANDLE, then the corresponding element of pname:pOffsets must: be zero endif::VK_EXT_robustness2[] * [[VUID-vkCmdBindVertexBuffers2-pStrides-03362]] If pname:pStrides is not `NULL` each element of pname:pStrides must: be less than or equal to sname:VkPhysicalDeviceLimits::pname:maxVertexInputBindingStride * [[VUID-vkCmdBindVertexBuffers2-pStrides-06209]] If pname:pStrides is not `NULL` each element of pname:pStrides must: be either 0 or greater than or equal to the maximum extent of all vertex input attributes fetched from the corresponding binding, where the extent is calculated as the slink:VkVertexInputAttributeDescription::pname:offset plus slink:VkVertexInputAttributeDescription::pname:format size **** include::{generated}/validity/protos/vkCmdBindVertexBuffers2.adoc[] -- endif::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[] ifdef::VK_EXT_vertex_attribute_divisor[] [[fxvertex-attribute_divisor]] == Vertex Attribute Divisor in Instanced Rendering [open,refpage='VkPipelineVertexInputDivisorStateCreateInfoEXT',desc='Structure specifying vertex attributes assignment during instanced rendering',type='structs'] -- If the <> feature is enabled and the pname:pNext chain of slink:VkPipelineVertexInputStateCreateInfo includes a sname:VkPipelineVertexInputDivisorStateCreateInfoEXT structure, then that structure controls how vertex attributes are assigned to an instance when instanced rendering is enabled. The sname:VkPipelineVertexInputDivisorStateCreateInfoEXT structure is defined as: include::{generated}/api/structs/VkPipelineVertexInputDivisorStateCreateInfoEXT.adoc[] * pname:sType is the type of this structure. * pname:pNext is `NULL` or a pointer to a structure extending this structure. * pname:vertexBindingDivisorCount is the number of elements in the pname:pVertexBindingDivisors array. * pname:pVertexBindingDivisors is a pointer to an array of sname:VkVertexInputBindingDivisorDescriptionEXT structures specifying the divisor value for each binding. include::{generated}/validity/structs/VkPipelineVertexInputDivisorStateCreateInfoEXT.adoc[] -- [open,refpage='VkVertexInputBindingDivisorDescriptionEXT',desc='Structure specifying a divisor used in instanced rendering',type='structs'] -- The individual divisor values per binding are specified using the sname:VkVertexInputBindingDivisorDescriptionEXT structure which is defined as: include::{generated}/api/structs/VkVertexInputBindingDivisorDescriptionEXT.adoc[] * pname:binding is the binding number for which the divisor is specified. * pname:divisor is the number of successive instances that will use the same value of the vertex attribute when instanced rendering is enabled. For example, if the divisor is N, the same vertex attribute will be applied to N successive instances before moving on to the next vertex attribute. The maximum value of pname:divisor is implementation-dependent and can be queried using sname:VkPhysicalDeviceVertexAttributeDivisorPropertiesEXT::pname:maxVertexAttribDivisor. A value of `0` can: be used for the divisor if the <> feature is enabled. In this case, the same vertex attribute will be applied to all instances. If this structure is not used to define a divisor value for an attribute, then the divisor has a logical default value of 1. .Valid Usage **** * [[VUID-VkVertexInputBindingDivisorDescriptionEXT-binding-01869]] pname:binding must: be less than sname:VkPhysicalDeviceLimits::pname:maxVertexInputBindings * [[VUID-VkVertexInputBindingDivisorDescriptionEXT-vertexAttributeInstanceRateZeroDivisor-02228]] If the pname:vertexAttributeInstanceRateZeroDivisor feature is not enabled, pname:divisor must: not be `0` * [[VUID-VkVertexInputBindingDivisorDescriptionEXT-vertexAttributeInstanceRateDivisor-02229]] If the pname:vertexAttributeInstanceRateDivisor feature is not enabled, pname:divisor must: be `1` * [[VUID-VkVertexInputBindingDivisorDescriptionEXT-divisor-01870]] pname:divisor must: be a value between `0` and sname:VkPhysicalDeviceVertexAttributeDivisorPropertiesEXT::pname:maxVertexAttribDivisor, inclusive * [[VUID-VkVertexInputBindingDivisorDescriptionEXT-inputRate-01871]] slink:VkVertexInputBindingDescription::pname:inputRate must: be of type ename:VK_VERTEX_INPUT_RATE_INSTANCE for this pname:binding **** include::{generated}/validity/structs/VkVertexInputBindingDivisorDescriptionEXT.adoc[] -- endif::VK_EXT_vertex_attribute_divisor[] [[fxvertex-input-address-calculation]] == Vertex Input Address Calculation The address of each attribute for each code:vertexIndex and code:instanceIndex is calculated as follows: * Let code:attribDesc be the member of slink:VkPipelineVertexInputStateCreateInfo::pname:pVertexAttributeDescriptions with sname:VkVertexInputAttributeDescription::pname:location equal to the vertex input attribute number. * Let code:bindingDesc be the member of slink:VkPipelineVertexInputStateCreateInfo::pname:pVertexBindingDescriptions with sname:VkVertexInputAttributeDescription::pname:binding equal to code:attribDesc.binding. * Let code:vertexIndex be the index of the vertex within the draw (a value between pname:firstVertex and pname:firstVertex+pname:vertexCount for fname:vkCmdDraw, or a value taken from the index buffer plus pname:vertexOffset for fname:vkCmdDrawIndexed), and let code:instanceIndex be the instance number of the draw (a value between pname:firstInstance and pname:firstInstance+pname:instanceCount). * Let code:offset be an array of offsets into the currently bound vertex buffers specified during fname:vkCmdBindVertexBuffers ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[or fname:vkCmdBindVertexBuffers2] with pname:pOffsets. ifdef::VK_EXT_vertex_attribute_divisor[] * Let code:divisor be the member of slink:VkPipelineVertexInputDivisorStateCreateInfoEXT::pname:pVertexBindingDivisors with sname:VkVertexInputBindingDivisorDescriptionEXT::pname:binding equal to code:attribDesc.binding. endif::VK_EXT_vertex_attribute_divisor[] [source,c] --------------------------------------------------- bufferBindingAddress = buffer[binding].baseAddress + offset[binding]; if (bindingDesc.inputRate == VK_VERTEX_INPUT_RATE_VERTEX) effectiveVertexOffset = vertexIndex * bindingDesc.stride; else ifndef::VK_EXT_vertex_attribute_divisor[] effectiveVertexOffset = instanceIndex * bindingDesc.stride; endif::VK_EXT_vertex_attribute_divisor[] ifdef::VK_EXT_vertex_attribute_divisor[] if (divisor == 0) effectiveVertexOffset = firstInstance * bindingDesc.stride; else effectiveVertexOffset = (firstInstance + ((instanceIndex - firstInstance) / divisor)) * bindingDesc.stride; endif::VK_EXT_vertex_attribute_divisor[] attribAddress = bufferBindingAddress + effectiveVertexOffset + attribDesc.offset; --------------------------------------------------- [[fxvertex-input-extraction]] === Vertex Input Extraction For each attribute, raw data is extracted starting at `attribAddress` and is converted from the sname:VkVertexInputAttributeDescription's pname:format to either floating-point, unsigned integer, or signed integer based on the base type of the format; the base type of the format must: match the base type of the input variable in the shader. The input variable in the shader must: be declared as a 64-bit data type if and only if pname:format is a 64-bit data type. If pname:format is a packed format, `attribAddress` must: be a multiple of the size in bytes of the whole attribute data type as described in <>. Otherwise, `attribAddress` must: be a multiple of the size in bytes of the component type indicated by pname:format (see <>). For attributes that are not 64-bit data types, each component is converted to the format of the input variable based on its type and size (as defined in the <> section for each elink:VkFormat), using the appropriate equations in <>, <>, <>, <>, and <>. Signed integer components smaller than 32 bits are sign-extended. Attributes that are not 64-bit data types are expanded to four components in the same way as described in <>. The number of components in the vertex shader input variable need not exactly match the number of components in the format. If the vertex shader has fewer components, the extra components are discarded.