Built-in Variable (GLSL)

From OpenGL.org
Revision as of 04:48, 25 March 2011 by Alfonse (Talk | contribs) (Initial data. Not finished.)

Jump to: navigation, search

The OpenGL Shading Language defines a number of special variables for the various shader stages. These variables have special properties. They are usually for communicating with certain fixed-functionality. By convention, all predefined variables start with "gl_"; no user-defined variables may start with this.

Vertex shader inputs

Vertex shaders have the following predefined inputs.

in int gl_VertexID;
in int gl_InstanceID;

The gl_VertexID is the index of the current vertex being processed. For array rendering, this value is the index of the current vertex. For indexed rendering, this is the index fetched from the element buffer for this vertex.

The gl_InstanceID specifies which instance is being rendered, when using instanced rendering.

Vertex shader outputs

Vertex shaders have the following predefined outputs.

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

This defines an interface block for outputs. The block is defined so that prefixing the names is not required.

gl_Position is the output position of the current vertex (in clip-space, if there is no geometry shader). It is not necessary to write to this value in a vertex shader, though if you do not, don't be surprised if the primitives you get are not reasonable. You can reasonably omit writing to this variable if you are using transform feedback and shutting off rasterization, or if you are using a geometry shader that will use user-defined outputs to generate positions.

gl_PointSize is the pixel width/height of the point being rasterized. It is only necessary to write to this when rendering points.

gl_ClipDistance allows the shader to set the distance from a vertex to each clip plane. A positive distance means that the vertex is inside/behind the clip plane, and a negative distance means it is outside/in front of the clip plane.

In order to use this variable, the user must manually redeclare it with a size.

Geometry shader inputs

in gl_PerVertex
{
  vec4 gl_Position;
  float gl_PointSize;
  float gl_ClipDistance[];
} gl_in[];
 
in int gl_PrimitiveIDIn;

The gl_PerVertex variables contain the values passed from the previous vertex shader stages. Note that in the geometry shader, they must be prefixed by gl_in, which is an interface block array. The size of this array is based on the layout qualifier used for inputs for this geometry shader. You do not have to redeclare this block with a specific size; the system does this for you. As with any array, you can get its length with the length() function.

gl_PrimitiveIDIn is the number of the current primitive being worked on during this rendering call. That is, the number of primitives previously processed by this glDraw* call.

GLSL 4.00 and above also have the following definitions:

in int gl_InvocationID;

Geometry shaders can be invoked multiple times; this value specifies the current invocation.

Geometry shader outputs

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

The gl_PerVertex has the same meaning as from the vertex shader stage.

gl_PrimitiveID is a user-defined identifier for the primitive. It is passed directly to the fragment shader (see below). If the fragment shader uses its corresponding input, the value is undefined if the geometry shader does not write to it (OpenGL will automatically fill it in if there is no geometry shader).

The geometry shader should write to this value for the provoking vertex of the output primitive.

gl_Layer is used for rendering to layered framebuffer objects. It specifies the layer that the particular primitive is rendered to.

The gl_Layer variable is assigned to each vertex. If different vertices of a primitive get a different layer value, then OpenGL states that which layer is rendered to is undefined. Therefore, you should set it for each vertex emitted.

Note that all of the output variables are cleared when EmitVertex() is called from the geometry shader.