View source for Vertex Shader

{{pipeline float}}
The '''Vertex Shader''' is the programmable [[Shader]] stage in the [[Rendering Pipeline Overview|rendering pipeline]] that handles the processing of individual vertices. Vertex shaders are fed [[Vertex Attribute]] data, as specified from a [[Vertex Specification|vertex array object]] by a [[Vertex Rendering|drawing command]]. A vertex shader receives a single vertex from the vertex stream and generates a single vertex to the output vertex stream. There must be a 1:1 mapping from input vertices to output vertices.

Vertex shaders typically perform transformations to post-projection space, for consumption by the [[Vertex Post-Processing]] stage. They can also be used to do per-vertex lighting, or to perform setup work for later shader stages.

== Invocation frequency ==

The OpenGL specification is fairly lenient on the number of times a vertex shader is invoked by the rendering system. [[Vertex Specification]] and [[Vertex Rendering]] define a vertex stream: an ordered sequence of vertices to be consumed. The vertex shader will be executed ''roughly'' once for every vertex in the stream.

A vertex shader is (usually) [[Invariance|invariant]] with its input. That is, within a single [[Drawing Command]], two vertex shader invocations that get the exact same [[#Inputs|input attributes]] will return binary identical results. Because of this, if OpenGL can detect that a vertex shader invocation is being given the same inputs as a previous invocation, it is allowed to reuse the results of the previous invocation, instead of wasting valuable time executing something that it already knows the answer to.

OpenGL implementations generally do not do this by actually comparing the input values (that would take far too long). Instead, this optimization typically only happens when using [[Vertex Specification|indexed rendering]] [[Vertex Rendering|functions]]. If a particular index is specified more than once (within the same [[Instanced Rendering]]), then this vertex is guaranteed to result in the exact same input data.

Therefore, implementations employ a [[Post Transform Cache|cache on the results of vertex shaders]]. If an index/instance pair comes up again, and the result is still in the cache, then the vertex shader is not executed again. Thus, there can be fewer vertex shader invocations than there are vertices specified.

However, you are guaranteed to have at least one vertex shader invocation for every unique set of attributes you use.

{{note|It is entire possible that the invocation frequency of the vertex shader can change if [[Tessellation]] is active. Particularly if a [[Tessellation Control Shader]] is active. So the tricks you might play to save vertex shader invocations may not work when tessellating. Then again, they may work just as well. However, it is assured that they ''will not'' save you TCS invocations, as the TCS cannot use these optimizations.}}

== Inputs ==

User-defined input values to vertex shaders are sometimes called "vertex attributes". Their values are provided by issuing a [[Vertex Rendering|drawing command]] while an appropriate [[Vertex Specification|vertex array object]] is bound.

Vertex shader input variables are defined as normal for shader stages, using the {{code|in}} [[Type Qualifier (GLSL)|type qualifier]]. Vertex Shader inputs cannot be aggregated into [[Interface Block]]s.

Each user-defined input variable is assigned one or more vertex attribute indices. These can be explicitly assigned in one of three ways. The methods for assigning these are listed in priority order, with the highest priority first. The higher priority methods take precedence over the later ones.

; In-shader specification
: The shader defines the attribute index. This is done using the {{code|layout(location {{=}} #)}} syntax:
<source lang="glsl">
layout(location = 2) in vec4 a_vec;
</source>
: This assigns the attribute {{code|a_vec}} the index 2.
; Pre-link specification
: Before linking a program that includes a vertex shader, the user may tell OpenGL to assign a particular attribute to a particular index. This is done with the following function:
  void {{apifunc|glBindAttribLocation}}(GLuint {{param|program}}, GLuint {{param|index}}, const GLchar *{{param|name}});
: {{param|index}} is the attribute index to assign. {{param|name}} is the name of the vertex shader input to assign the given index to.
: Note that it is perfectly legal to use this function to assign indices to names that are not mentioned in the vertex shader. The linking process will only use the names that are actually used by the vertex shader. Because of that, it is also perfectly legal to assign multiple names to the ''same index''; this is only an error if a shader attempts to use both of the names that use the same index.
; Automatic assignment
: If neither of the prior two methods assign an input to an attribute index, then the index is automatically assigned by OpenGL when the program is linked. The index assigned is completely arbitrary and may be different for different programs that are linked, even if they use the exact same vertex shader code.

Note that like [[Uniform (GLSL)|uniforms]], vertex attributes can be "active" and non-active. Active inputs are those that the compiler/linker detects are actually in use. The vertex shader and GLSL program linking process can decide that some input are not in use and therefore they are not active. This is done even if an explicit attribute index is assigned in the vertex shader.

The active attributes can be queried via program introspection, either through the [[Program Interface Query|new, generic API]] or the [[Program_Introspection#Attributes|old API]].

=== Multiple attributes ===

Attributes may be arrays, matrices, and double-precision types (if {{require|4.1|vertex_attrib_64bit}} is available). Or combinations of any of these. Some of these types are large enough to require that the input variable be assigned to multiple attribute indices.

Matrix inputs take up one attribute index for every column. Array attributes take up one index per element, even if the array is a {{code|float}} and could have use up to 4 indices.

Double-precision input variables of {{code|double}} or {{code|dvec}} types ''always'' take up one attribute. Even if they are {{code|dvec4}}.

These combine with each other. A {{code|mat2x4[2]}} array is broken up into four {{code|vec4}} values, each of which is assigned an index. Thus, it takes up 4 indices; the first two indices specify the two columns of array index 0, and the next two indices specify the two columns of array index 1.

When an input requires multiple indices, it will always be assigned ''sequential'' indices starting from the given index. Consider:

<source lang="glsl">
layout(location = 3) in mat4 a_matrix;
</source>

{{code|a_matrix}} will be assigned attribute indices 3, 4, 5, and 6. This works regardless of what methods you use to assign vertex attribute indices to input variables.

Linking will fail if any index ranges collide. Thus, this will fail to link:

<source lang="glsl">
layout(location = 0) in mat4 a_matrix;
layout(location = 3) in vec4 a_vec;
</source>

Because {{code|a_matrix}} has four columns, it will take up the attribute indices on the range [0, 3]. That overlaps with {{code|a_vec}}'s attribute index, and thus a linking error will occur.

This will also fail, assuming the implementation only allows 16 attribute indices:

<source lang="glsl">
layout(location = 0) in mat4 a_matrix1;
layout(location = 5) in mat4 a_matrix2;
layout(location = 10) in mat4 a_matrix3;
in mat4 bad_matrix;
</source>

Even though there are 4 total attribute indices available after the {{code|a_matrix*}} indices are assigned, they cannot be assigned ''sequentially''. There is no attribute index for {{code|bad_matrix}} that will allow it to get 4 sequential indices. Thus, the linker will fail.

=== Attribute limits ===

In general, the number of attribute indices ''are'' the limitation on them. No attribute can be assigned an index higher than {{enum|GL_MAX_VERTEX_ATTRIBS}}.

There is a case which makes this more complex: double-precision attributes (if {{require|4.1|vertex_attrib_64bit}} is available). {{code|dvec3}} and {{code|dvec4}} only take up one attribute index. But implementations are allowed to count them ''twice'' when determining the limits on the number of attributes. Thus, while a {{code|dmat2x3[4]}} will only take up 8 attribute indices (4 array elements of 2 columns of {{code|dvec3}}s), the implementation is allowed to consider this as taking up 16 indices when determining if a shader is using up too many attribute indices. As such, a {{code|dmat2x3['''5''']}} may fail to link even though it only uses 10 attribute indices.

Note the use of the word "allowed". The implementation is free to count them only once, but you can't ''rely'' on it. So you need to assume that these will consume two input resources, even though they only use one index. Since there is no way to query whether any particular implementation will count them twice, you ''must assume'' that they will take up two resources.

=== Other inputs ===

{{snippet|:Vertex Shader/Defined Inputs}}

== Outputs ==

Output variables from the vertex shader are passed to the next section of the pipeline. Many of the next stages are optional, so if they are not present, then the outputs are passed to the next one that is. They are in this order:

# [[Tessellation]]. If no [[Tessellation Control Shader]] is present, the [[Tessellation Evaluation Shader]] will get them.
# [[Geometry Shader]]
# [[Vertex Post-Processing]]

User-defined output variables can have [[Interpolation qualifiers|interpolation qualifiers]] (though these only matter if the output is being passed directly to the [[Vertex Post-Processing]] stage). Vertex shader outputs can also be aggregated into [[Interface Block]]s.

{{snippet|:Vertex Shader/Defined Outputs}}

== See also ==

* [[Fragment Shader]]s
* [[Vertex Attribute]]

[[Category:Shaders]]
[[Category:Vertex Processing]]
[[Category:OpenGL Shading Language]]