Difference between revisions of "Vertex Shader"

From OpenGL.org
Jump to: navigation, search
(Outputs)
(Outputs)
(7 intermediate revisions by the same user not shown)
Line 1: Line 1:
'''Vertex Shaders''' are [[Shader|shaders]] that handle vertex processing. They receive a sequence of [[Vertex Attributes]] and produce an equal length sequence of vertex data. There must be a 1:1 mapping from input vertices to output vertices.
+
{{pipeline float}}
 +
The '''Vertex Shader''' is the programmable stage in the [[Rendering Pipeline Overview|rendering pipeline]] that handles the processing of individual vertices. A vertex shader receives a single vertex composed of a series of [[Vertex Attributes]]. This input vertex is processed arbitrarily to produce an output vertex. There must be a 1:1 mapping from input vertices to output vertices.
  
 
== Overview ==
 
== Overview ==
Line 7: Line 8:
 
== Inputs ==
 
== Inputs ==
  
Input values to the vertex shader provided by issuing a [[Vertex rendering|rendering command]] while an appropriate [[Vertex Specification|vertex array object]] is bound.
+
Input values to the vertex shader provided by issuing a [[Vertex Rendering|rendering 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}} [[GLSL Type Qualifiers|type qualifier]]. Vertex Shader inputs cannot be aggregated into [[Interface Block]]s.
 
Vertex shader input variables are defined as normal for shader stages, using the {{code|in}} [[GLSL Type Qualifiers|type qualifier]]. Vertex Shader inputs cannot be aggregated into [[Interface Block]]s.
  
Each 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; the first takes precedence over the later ones.
+
Each 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
 
; In-shader specification
: The shader defines the attribute index. This is done using the {{code|layout(location = #)}} syntax:
+
: The shader defines the attribute index. This is done using the {{code|layout(location {{=}} #)}} syntax:
 
<source lang="glsl">
 
<source lang="glsl">
layout(location = 2) vec4 a_vec;
+
layout(location = 2) in vec4 a_vec;
 
</source>
 
</source>
 
: This assigns the attribute {{code|a_vec}} the index 2.
 
: This assigns the attribute {{code|a_vec}} the index 2.
 
; Pre-link specification
 
; Pre-link specification
: Before linking, the user may tell OpenGL to assign a particular attribute to a partcular index. This is done with the following function:
+
: 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}});
 
   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.
 
: {{param|index}} is the attribute index to assign. {{param|name}} is the name of the vertex shader input to assign the given index to.
Line 33: Line 34:
 
=== Multiple attributes ===
 
=== Multiple attributes ===
  
Vertex shader inputs may be arrays, matrices, or double-precision types (if GL 4.1/{{extref|vertex_attrib_64bit}} is available). These types require that the input variable be assigned to multiple attribute indices.
+
Vertex shader inputs may be arrays, matrices, and double-precision types (if GL 4.1/{{extref|vertex_attrib_64bit}} is available). Or combinations of any of these. Some of these types require that the input variable be assigned to multiple attribute indices.
  
 
Matrix inputs take up one attribute index for every column. Array inputs take one attribute index for every .
 
Matrix inputs take up one attribute index for every column. Array inputs take one attribute index for every .
  
Double-precision input variables take up two attribute indices, but only if they have a vector length of 3 or 4. So a {{code|dvec2}} takes up only 1 attribute, but {{code|dvec3}} takes up two.
+
Double-precision input variables of {{code|double}} or {{code|dvec}} types ''always'' take up one attribute. Even if they are {{code|dvec4}}.
  
Double-precision matrices and/or arrays combine these. Matrices/arrays are broken down into individual vectors. So a {{code|dmat2x4}} is equivalent to two {{code|dvec4}}s; thus, it requires 4 attribute indices. A {{code|dmat2x4[2]}} array is broken into four {{code|dvec4}}s, and thus requires 8 attribute indices.
+
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.
  
Each input is only ever given a single attribute index. If that input variable needs multiple attribute indices, the rest are assigned sequentially starting at the given index. Consider:
+
When an input requires multiple indices, it will always be assigned ''sequential'' indices starting from the given index. Consider:
  
 
<source lang="glsl">
 
<source lang="glsl">
layout(location = 3) mat4 a_matrix;
+
layout(location = 3) in mat4 a_matrix;
 
</source>
 
</source>
  
Line 52: Line 53:
  
 
<source lang="glsl">
 
<source lang="glsl">
layout(location = 0) mat4 a_matrix;
+
layout(location = 0) in mat4 a_matrix;
layout(location = 3) vec4 a_vec;
+
layout(location = 3) in vec4 a_vec;
 
</source>
 
</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 attributes, and thus a linking error will occur.
 
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 attributes, and thus a linking error will occur.
 +
 +
This will also fail:
 +
 +
<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 available attribute indices 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 attribute indices in a row. 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}}, which in virtually all hardware will be 16.
 +
 +
There is a case which makes this more complex: double-precision attributes (if GL 4.1/{{extref|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 arrays of 2 column {{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 ===
 
=== Other inputs ===
Line 71: Line 91:
 
{{note|It is not entirely clear from the specification how [[Vertex_Rendering#Base_Index|base vertex]] applies to this. That is, whether {{code|gl_VertexID}} includes the base vertex or not.}}
 
{{note|It is not entirely clear from the specification how [[Vertex_Rendering#Base_Index|base vertex]] applies to this. That is, whether {{code|gl_VertexID}} includes the base vertex or not.}}
  
{{code|gl_InstanceID}} is the index of the current instance when doing some form of [[Vertex_Rendering#Instancing|instanced rendering]]. If instancing is not being used, this value is 0.
+
{{code|gl_InstanceID}} is the index of the current instance when doing some form of [[Vertex_Rendering#Instancing|instanced rendering]]. Note that if instanced rendering (or base-instance calls) are not being used, this value is 0.
  
 
== Outputs ==
 
== Outputs ==
  
Output variables from the vertex shader are passed on to the [[Tessellation Shader|Tessellation Evaluation Shader]] or [[Geometry Shader]]. If neither of those shaders is active, then they are passed on to the [[Vertex_Post-Processing|next stages in the rendering pipeline]].
+
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]]. A [[Tessellation Control Shader]] or the tessellator itself may pick things up. If so, then the [[Tessellation Evaluation Shader]] could go to work.
 +
# [[Geometry Shader]]
 +
# [[Vertex Post-Processing]]
  
User-defined output variables can have [[GLSL_Type_Qualifiers#Interpolation_qualifiers|interpolation qualifiers]] (though these only matter if the output is not bieng passed to a Tessellation or Geometry shader. Vertex shader outputs can also be aggregated into [[Interface Block]]s.
+
User-defined output variables can have [[GLSL_Type_Qualifiers#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.
  
 
There are several pre-defined vertex shader outputs, which have specialized semantics. These variables ''only'' have these special semantics if the vertex shader is passing its outputs directly to the fixed-function post-vertex processing stages. If there is an active tessellation or geometry shader, these variables can still be used, but they have only whatever meaning those later stages choose to give them.
 
There are several pre-defined vertex shader outputs, which have specialized semantics. These variables ''only'' have these special semantics if the vertex shader is passing its outputs directly to the fixed-function post-vertex processing stages. If there is an active tessellation or geometry shader, these variables can still be used, but they have only whatever meaning those later stages choose to give them.
Line 96: Line 120:
 
== See also ==
 
== See also ==
  
* The previous pipeline stage: [[Vertex Specification]]
 
** [[Vertex Attribute]]
 
* The possible next pipeline stages:
 
** [[Tessellation Shader]]s
 
** [[Geometry Shader]]s
 
** [[Vertex Post-Processing]]
 
 
* [[Fragment Shader]]s
 
* [[Fragment Shader]]s
 +
* [[Vertex Attribute]]
  
 
[[Category:Shaders]]
 
[[Category:Shaders]]
 
[[Category:OpenGL Shading Language]]
 
[[Category:OpenGL Shading Language]]

Revision as of 02:52, 3 November 2012

The Vertex Shader is the programmable stage in the rendering pipeline that handles the processing of individual vertices. A vertex shader receives a single vertex composed of a series of Vertex Attributes. This input vertex is processed arbitrarily to produce an output vertex. There must be a 1:1 mapping from input vertices to output vertices.

Overview

Vertex shaders are fed Vertex Attribute data, as specified from a vertex array object by a rendering command. A vertex shader receives a single vertex from the vertex stream and generates a single vertex to the output vertex stream.

Inputs

Input values to the vertex shader provided by issuing a rendering command while an appropriate vertex array object is bound.

Vertex shader input variables are defined as normal for shader stages, using the in​ type qualifier. Vertex Shader inputs cannot be aggregated into Interface Blocks.

Each 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 layout(location = #)​ syntax:
layout(location = 2) in vec4 a_vec;
This assigns the attribute 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 glBindAttribLocation(GLuint program​, GLuint index​, const GLchar *name​);
index​ is the attribute index to assign. name​ is the name of the vertex shader input to assign the given index to.
Note that it is perfectly legal to assign names to indices that are not mentioned in the vertex shader. The linking process will only use the names that are actually mentioned in 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 you attempt to link a program that uses both names.
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 uniforms, vertex inputs 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.

The number of active input variables can queried with glGetProgram using GL_ACTIVE_ATTRIBUTES. The names of these inputs can be queried with glGetActiveAttrib, and the attribute index can be queried by providing the attribute name to glGetAttribLocation.

Multiple attributes

Vertex shader inputs may be arrays, matrices, and double-precision types (if GL 4.1/ARB_vertex_attrib_64bit is available). Or combinations of any of these. Some of these types require that the input variable be assigned to multiple attribute indices.

Matrix inputs take up one attribute index for every column. Array inputs take one attribute index for every .

Double-precision input variables of double​ or dvec​ types always take up one attribute. Even if they are dvec4​.

These combine with each other. A mat2x4[2]​ array is broken up into four 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:

layout(location = 3) in mat4 a_matrix;

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 input names collide when they are assigned a range of attribute indices. Thus, this will fail to link:

layout(location = 0) in mat4 a_matrix;
layout(location = 3) in vec4 a_vec;

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

This will also fail:

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;

Even though there are 4 available attribute indices after the a_matrix*​ indices are assigned, they cannot be assigned sequentially. There is no attribute index for bad_matrix​ that will allow it to get 4 attribute indices in a row. 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 GL_MAX_VERTEX_ATTRIBS, which in virtually all hardware will be 16.

There is a case which makes this more complex: double-precision attributes (if GL 4.1/ARB_vertex_attrib_64bit is available). dvec3​ and 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 dmat2x3[4]​ will only take up 8 attribute indices (4 arrays of 2 column 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 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

There are a few other input variables to the vertex shader stage. These are built-in inputs.

in int gl_VertexID;
in int gl_InstanceID;

gl_VertexID​ is the index of the vertex currently being processed. When using non-indexed rendering, it is the effective index of the current vertex (the number of vertices processed + the first​ value). For indexed rendering, it is the index used to fetch this vertex from the buffer.

Note: It is not entirely clear from the specification how base vertex applies to this. That is, whether gl_VertexID​ includes the base vertex or not.

gl_InstanceID​ is the index of the current instance when doing some form of instanced rendering. Note that if instanced rendering (or base-instance calls) are not being used, this value is 0.

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:

  1. Tessellation. A Tessellation Control Shader or the tessellator itself may pick things up. If so, then the Tessellation Evaluation Shader could go to work.
  2. Geometry Shader
  3. Vertex Post-Processing

User-defined output variables can have 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 Blocks.

There are several pre-defined vertex shader outputs, which have specialized semantics. These variables only have these special semantics if the vertex shader is passing its outputs directly to the fixed-function post-vertex processing stages. If there is an active tessellation or geometry shader, these variables can still be used, but they have only whatever meaning those later stages choose to give them.

out gl_PerVertex
{
  vec4 gl_Position;
  float gl_PointSize;
  float gl_ClipDistance[];
}

gl_Position​ is the clip-space vertex position. gl_PointSize​ is the size in pixels of this point (only useful when rendering GL_POINTS primitives). gl_ClipDistance​ is used for doing triangle clipping against user-defiend clip planes.

If no shading stages happen between the vertex shader and the rasterizer, and GL_RASTERIZER_DISCARD is not enabled, then the vertex shader must write to gl_Position​.

See also