status-im/Vulkan-Docs
2
0
Fork 0
mirror of https://github.com/status-im/Vulkan-Docs.git synced 2025-02-22 02:58:16 +00:00
Code Issues Projects Releases Wiki Activity
Vulkan-Docs/doc/specs/vulkan/chapters/fxvertex.txt
Jon Leech ce60b9c887 Change log for March 7, 2018 Vulkan 1.1.70 spec update: 
* Vulkan 1.1 initial release. Bump API patch number and header version
    number to 70 for this update. The patch number will be used for both
    Vulkan 1.1 and Vulkan 1.0 updates, and continues to increment
    continuously from the previous Vulkan 1.0.69 update.

    NOTE: We are not publishing an updated 1.0.70 specification, or 1.1
    reference pages, along with 1.1.70. There are still minor issues to work
    out with those build targets. However, we will soon generate all three
    types of documents as part of the regular spec update cycle.

    NOTE: The GitHub KhronosGroup/Vulkan-Docs repository now maintains the
    current specification in the `master` branch. The `1.0` branch is out of
    date and will not be maintained, since we will be generating both 1.1
    and 1.0 specifications from the `master` branch in the future.

Github Issues:

  * Clarify how mapped memory ranges are flushed in
    flink:vkFlushMappedMemoryRanges (public issue 127).
  * Specify that <<synchronization-pipeline-stages, Pipeline Stages>> are a
    list of tasks that each command performs, rather than necessarily being
    discrete pieces of hardware that one task flows through. Add a
    "`synchronization command`" pipeline type which all synchronization
    command execute (it's just TOP + BOTTOM), with an explanatory note
    (public issue 554).

Internal Issues:

  * Regenerate all images used in the spec in Inkscape with a consistent
    look-and-feel, and adjust image size attributes so they're all legible,
    and not too large with respect to the spec body text (internal issue
    701).
  * Document in the <<extensions,extensions>> appendix and in the style
    guide that `KHX` extensions are no longer supported or used in the
    Vulkan 1.1 timeframe (internal issue 714).
  * Remove the leftover equations_temp directory after PDF build completes
    (internal issue 925).
  * Update the <<credits, Credits (Informative)>> appendix to include
    contributors to Vulkan 1.1, and to list them according to the API
    version(s) they contributed to (internal issue 987).
  * Add a NOTE to the introduction explaining that interfaces defined by
    extensions which were promoted to Vulkan 1.1 are now expressed as
    aliases of the Vulkan 1.1 type (internal issue 991).
  * Instrument spec source conditionals so spec can be built with 1.1
    features, extensions promoted to 1.1, or both (internal issues 992,
    998).
  * Modify the XML schema and tools to support explicit aliasing of types,
    structures, and commands, and use this to express the promotion of 1.0
    extensions to 1.1 core features, by making the extension interfaces
    aliases of the core features they were promoted to. Mark up promoted
    interfaces to allow still generating 1.0 + extension specifications
    (internal issue 991).
  * Platform names, along with corresponding preprocessor symbols to enable
    extensions specific to those platforms, are now reserved in vk.xml using
    the <platform> tag. Update the registry schema and schema specification
    to match (internal issue 1011).
  * Updated the <<textures-texel-replacement, Texel Replacement>> section to
    clarify that reads from invalid texels for image resources result in
    undefined values (internal issue 1014).
  * Modify description of patch version so it continues to increment across
    minor version changes (internal issue 1033).
  * Clarify and unify language describing physical device-level core and
    extension functionality in the <<fundamentals-validusage-extensions,
    Valid Usage for Extensions>>, <<fundamentals-validusage-versions, Valid
    Usage for Newer Core Versions>>, <<initialization-functionpointers
    Command Function Pointers>>, <<initialization-phys-dev-extensions,
    Extending Physical Device From Device Extensions>>
    <<extended-functionality-instance-extensions-and-devices, Instance
    Extensions and Device Extensions>> sections and for
    flink:vkGetPhysicalDeviceImageFormatProperties2. This documents that
    instance-level functionality is tied to the loader, and independent of
    the ICD; physical device-level functionality is tied to the ICD, and
    associated with device extensions; physical devices are treated more
    uniformly between core and extensions; and instance and physical
    versions can be different (internal issue 1048).
  * Updated the <<commandbuffers-lifecycle, Command Buffer Lifecycle>>
    section to clarify the ability for pending command buffers to transition
    to the invalid state after submission, and add a command buffer
    lifecycle diagram (internal issue 1050).
  * Clarify that some flink:VkDescriptorUpdateTemplateCreateInfo parameters
    are ignored when push descriptors are not supported (internal issue
    1054).
  * Specify that flink:vkCreateImage will return an error if the image is
    too large, in a NOTE in the slink:VkImageFormatProperties description
    (internal issue 1078).
  * Remove near-duplicate NOTEs about when to query function pointers
    dynamically in the <<initialization, Initialization>> chapter and
    replace by extending the NOTE in the <<fundamentals-abi, Application
    Binary Interface>> section (internal issue 1085).
  * Restore missing references to "`Sparse Resource Features`" in the
    flink:VkBufferCreateFlagBits description (internal issue 1086).
  * Tidy up definitions of descriptor types in the `GL_KHR_vulkan_glsl`
    specification, the <<descriptorsets, Resource Descriptors>> section and
    its subsections, and the <<interfaces-resources-descset, Descriptor Set
    Interface>> for consistency, reduction of duplicate information, and
    removal of GLSL correspondance/examples (internal issue 1090).
  * Correctly describe code:PrimitiveId as an Input for tessellation control
    and evaluation shaders, not an Output (internal issue 1109).
  * Relax the requirements on chroma offsets for nearest filtering in
    <<textures-implict-reconstruction, Implicit Reconstruction>> (internal
    issue 1116).

Other Issues:

  * Clarify the intended relationship between specification language and
    certain terms defined in the Khronos Intellectual Property Rights
    policy. Specific changes include:
  ** Rewrote IP/Copyright preamble and introduction to better agree with
     normative language both as laid out in the introduction, and the
     Khronos IPR policy.
  ** Added notion of fully informative sections, which are now tagged with
     "`(Informative)`" in their titles.
  ** Removed non-normative uses of the phrase "`not required`"
  ** Clarified the distinction between terms "`optional`" and "`not
     required:`" as they relate to the IPR Policy, and updated specification
     text to use terms consistent with the intent.
  ** Reduced additions to RFC 2119, and ensured the specification agreed
     with the leaner language.
  ** Removed the terms "`hardware`", "`software`", "`CPU`", and "`GPU`" from
     normative text.
  ** Moved several paragraphs that should not have been normative to
     informative notes.
  ** Clarified a number of definitions in the Glossary.
  ** Updated the document writing guide to match new terminology changes.
  * Explicitly state in the <<fundamentals-objectmodel-lifetime-acquire,
    application memory lifetime>> language that that for objects other than
    descriptor sets, a slink:VkDescriptorSetLayout object used in the
    creation of another object (such as slink:VkPipelineLayout or
    slink:VkDescriptorUpdateTemplateKHR) is only in use during the creation
    of that object and can be safely destroyed afterwards.
  * Updated the <<textures-scale-factor, Scale Factor Operation>> section to
    use the ratio of anisotropy, rather than the integer sample rate, to
    perform the LOD calculation. The spec still allows use of the sample
    rate as the value used to calculate the LOD, but no longer requires it.
  * Update `vulkan_ext.c` to include all platform-related definitions from
    the Vulkan platform headers, following the split of the headers into
    platform-specific and non-platform-specific files.
  * Fix bogus anchor name in the <<commandbuffers, Command Buffers>> chapter
    which accidentally duplicated an anchor in the pipelines chapter. There
    were no reference to this anchor, fortunately.
  * Add valid usage statement for slink:VkWriteDescriptorSet and
    slink:VkCopyDescriptorSet requiring that the slink:VkDescriptorSetLayout
    used to allocate the source and destination sets must not have been
    destroyed at the time flink:vkUpdateDescriptorSets is called.
  * Document mapping of subgroup barrier functions to SPIR-V, and clarify a
    place where subgroupBarrier sounds like it's execution-only in the
    standalone `GL_KHR_shader_subgroup` specification.
  * Use an HTML stylesheet derived from the Asciidoctor `colony` theme, with
    the default Arial font family replaced by the sans-serif Noto font
    family.
  * Numerous minor updates to README.adoc, build scripts, Makefiles, and
    registry and style guide specifications to support Vulkan 1.1 outputs,
    use them as defaults, and remove mention of `KHX` extensions, which are
    no longer supported.

New Extensions:

  * `VK_EXT_vertex_attrib_divisor`
2018-03-07 04:18:52 -08:00

631 lines
29 KiB
Plaintext
Raw Blame History

// Copyright (c) 2015-2018 Khronos Group. This work is licensed under a
// Creative Commons Attribution 4.0 International License; see
// http://creativecommons.org/licenses/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 scalar or vector 32-bit
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
<<fxvertex-attrib-components>>.
Any 32-bit scalar or vector input will consume a single location.
For 32-bit data types, missing components are filled in with default values
as described <<fxvertex-input-extraction,below>>.
[[fxvertex-attrib-components]]
.Input attribute components accessed by 32-bit input variables
[width="65%",cols="<5,<3,<3",options="header"]
|====
| 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 <<fxvertex-attrib-matrix>>.
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 <<fxvertex-attrib-double>>.
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 <<fxvertex-attrib-double>>.
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.
The slink:VkGraphicsPipelineCreateInfo::pname:pVertexInputState points to a
structure of type sname:VkPipelineVertexInputStateCreateInfo.
[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::../api/structs/VkPipelineVertexInputStateCreateInfo.txt[]
* pname:sType is the type of this structure.
* pname:pNext is `NULL` or a pointer to an extension-specific 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::../validity/structs/VkPipelineVertexInputStateCreateInfo.txt[]
--
[open,refpage='VkPipelineVertexInputStateCreateFlags',desc='Reserved for future use',type='enums']
--
include::../api/flags/VkPipelineVertexInputStateCreateFlags.txt[]
sname:VkPipelineVertexInputStateCreateFlags is a bitmask type for setting a
mask, but is currently reserved for future use.
--
Each vertex input binding is specified by an instance of the
sname:VkVertexInputBindingDescription structure.
[open,refpage='VkVertexInputBindingDescription',desc='Structure specifying vertex input binding description',type='structs']
--
The sname:VkVertexInputBindingDescription structure is defined as:
include::../api/structs/VkVertexInputBindingDescription.txt[]
* pname:binding is the binding number that this structure describes.
* pname:stride is the distance in bytes between two 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
****
include::../validity/structs/VkVertexInputBindingDescription.txt[]
--
[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::../api/enums/VkVertexInputRate.txt[]
* 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 an instance of the
sname:VkVertexInputAttributeDescription structure.
The sname:VkVertexInputAttributeDescription structure is defined as:
include::../api/structs/VkVertexInputAttributeDescription.txt[]
* pname:location is the shader binding 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
****
include::../validity/structs/VkVertexInputAttributeDescription.txt[]
--
[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 draw
commands, call:
include::../api/protos/vkCmdBindVertexBuffers.txt[]
* 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 draw
commands.
.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
****
include::../validity/protos/vkCmdBindVertexBuffers.txt[]
--
ifdef::VK_EXT_vertex_attribute_divisor[]
== Vertex Attribute Divisor in Instanced Rendering
If 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::../api/structs/VkPipelineVertexInputDivisorStateCreateInfoEXT.txt[]
* pname:sType is the type of this structure
* pname:pNext is `NULL` or a pointer to an extension-specific 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, which specifies the
divisor value for each binding.
include::../validity/structs/VkPipelineVertexInputDivisorStateCreateInfoEXT.txt[]
--
The individual divisor values per binding are specified using the
sname:VkVertexInputBindingDivisorDescriptionEXT structure which is defined as:
include::../api/structs/VkVertexInputBindingDivisorDescriptionEXT.txt[]
* pname:binding is the binding number for which the divisor is specified.
* pname:divisor is the 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 applied to N
successive instances before moving on to the next vertex attribute.
If a value of 0 is used for the divisor, then the first vertex attribute
will be applied to all instances.
The maximum value of divisor is implementation dependent and can be queried
using sname:VkPhysicalDeviceVertexAttributeDivisorPropertiesEXT::pname:maxVertexAttribDivisor.
.Valid Usage
****
* pname:binding must: be less than
sname:VkPhysicalDeviceLimits::pname:maxVertexInputBindings
* pname:divisor must: be a value between `0` and
sname:VkPhysicalDeviceVertexAttributeDivisorPropertiesEXT::pname:maxVertexAttribDivisor,
inclusive.
* slink:VkVertexInputBindingDescription::pname:inputRate must: be of type
ename:VK_VERTEX_INPUT_RATE_INSTANCE for this pname:binding.
****
include::../validity/structs/VkVertexInputBindingDivisorDescriptionEXT.txt[]
--
If this structure is not used to define a divisor value for an attribute then
the divisor has a logical default value of 1.
endif::VK_EXT_vertex_attribute_divisor[]
The address of each attribute for each code:vertexIndex and
code:instanceIndex is calculated as follows:
* Let code:attribDesc be the member of
sname:VkPipelineVertexInputStateCreateInfo::pname:pVertexAttributeDescriptions
with sname:VkVertexInputAttributeDescription::pname:location equal to
the vertex input attribute number.
* Let code:bindingDesc be the member of
sname: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 for
fname:vkCmdDrawIndexed), and let code:instanceIndex be the instance
number of the draw (a value between pname:firstInstance and
pname:firstInstance+pname:instanceCount).
ifdef::VK_EXT_vertex_attribute_divisor[]
* Let code:divisor be the member of
sname: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)
vertexOffset = vertexIndex * bindingDesc.stride;
else
ifndef::VK_EXT_vertex_attribute_divisor[]
vertexOffset = instanceIndex * bindingDesc.stride;
endif::VK_EXT_vertex_attribute_divisor[]
ifdef::VK_EXT_vertex_attribute_divisor[]
if (divisor == 0)
vertexOffset = 0;
else
vertexOffset = (instanceIndex / divisor) * bindingDesc.stride;
endif::VK_EXT_vertex_attribute_divisor[]
attribAddress = bufferBindingAddress + vertexOffset + attribDesc.offset;
---------------------------------------------------
[[fxvertex-input-extraction]]
For each attribute, raw data is extracted starting at `attribAddress` and is
converted from the sname:VkVertexInputAttributeDescription's pname:format to
either to 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.
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
<<features-formats-packed,Packed Formats>>.
Otherwise, `attribAddress` must: be a multiple of the size in bytes of the
component type indicated by pname:format (see <<features-formats,Formats>>).
If the format does not include G, B, or A components, then those are filled
with [eq]#(0,0,1)# as needed (using either 1.0f or integer 1 based on the
format) for attributes that are not 64-bit data types.
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.
[[fxvertex-example]]
== Example
To create a graphics pipeline that uses the following vertex description:
[source,c++]
---------------------------------------------------
struct Vertex
{
float x, y, z, w;
uint8_t u, v;
};
---------------------------------------------------
The application could use the following set of structures:
[source,c++]
---------------------------------------------------
const VkVertexInputBindingDescription binding =
{
0, // binding
sizeof(Vertex), // stride
VK_VERTEX_INPUT_RATE_VERTEX // inputRate
};
const VkVertexInputAttributeDescription attributes[] =
{
{
0, // location
binding.binding, // binding
VK_FORMAT_R32G32B32A32_SFLOAT, // format
0 // offset
},
{
1, // location
binding.binding, // binding
VK_FORMAT_R8G8_UNORM, // format
4 * sizeof(float) // offset
}
};
const VkPipelineVertexInputStateCreateInfo viInfo =
{
VK_STRUCTURE_TYPE_PIPELINE_VERTEX_INPUT_CREATE_INFO, // sType
NULL, // pNext
0, // flags
1, // vertexBindingDescriptionCount
&binding, // pVertexBindingDescriptions
2, // vertexAttributeDescriptionCount
&attributes[0] // pVertexAttributeDescriptions
};
---------------------------------------------------
Reference in New Issue View Git Blame Copy Permalink