Fragment Shader

From OpenGL Wiki
Jump to navigation Jump to search

A Fragment Shader is the Shader stage that will process a Fragment generated by the Rasterization into a set of colors and a single depth value.

The fragment shader is the OpenGL pipeline stage after a primitive is rasterized. For each sample of the pixels covered by a primitive, a "fragment" is generated. Each fragment has a Window Space position, a few other values, and it contains all of the interpolated per-vertex output values from the last Vertex Processing stage.

The output of a fragment shader is a depth value, a possible stencil value (unmodified by the fragment shader), and zero or more color values to be potentially written to the buffers in the current framebuffers.

Fragment shaders take a single fragment as input and produce a single fragment as output.

Optional[edit]

Fragment shaders are technically an optional shader stage. If no fragment shader is used, then the color values of the output Fragment have undefined values. However, the depth and stencil values for the output fragment have the same values as the inputs.

This is useful for doing rendering where the only useful output is the fragment's depth, and you want to use the depth computed by the system, rather than some other depth. Such depth-only rendering is used for shadow mapping operations as well as depth pre-pass optimizations.

Special operations[edit]

Unlike every other shader stage, fragment shaders have implicit derivatives generated. As such, they can use the majority of the texturing functions. You still need to watch out for non-uniform flow control.

Fragment shaders also have access to the discard command. When executed, this command causes the fragment's output values to be discarded. Thus, the fragment does not proceed on to the next pipeline stages, and any fragment shader outputs are lost. Though execution of the fragment shader is technically stopped by discard, on actual systems, it may continue. Such systems are required to prevent image store, Atomic Counter, and Shader Storage Buffer Object writes issued after the discard from working (such operations performed before the discard work as expected).

Normally, most of the Per-Sample Processing steps happen after the fragment shader. However, with OpenGL 4.2 or ARB_shader_image_load_store, the shader can enforce Early Fragment Testing, which ensures that the conditional per-sample tests that discard fragments happen before the fragment shader executes. To do this, the following syntax is used in the shader:

layout(early_fragment_tests) in;

This is useful to ensure that you only perform expensive load/store operations if the fragment is visible.

Warning: This does not mean that you can subvert the meaning of the Depth Test. You cannot, for example, perform the depth test with one value and then write a different value to the depth buffer than the one you tested. If you attempt to write to gl_FragDepth when you force early-fragment tests, then the value written will be ignored. The value written to the depth buffer will always be the value tested against the depth buffer. Similarly, if you discard a fragment, the Stencil Test will still result in updating the stencil buffer if the appropriate operations are set.

Inputs[edit]

The inputs to the fragment shader are either generated by the system or passed from prior fixed-function operations and potentially interpolated across the surface of the primitive.

The user-defined inputs received by this fragment shader will be interpolated according to the interpolation qualifiers declared on the input variables declared by this fragment shader. The fragment shader's input variables must be declared in accord with the interface matching rules between shader stages. Specifically, between this stage and the last Vertex Processing shader stage in the program or pipeline object.

System inputs[edit]

V · E

Fragment Shaders have the following built-in input variables.

in vec4 gl_FragCoord;
in bool gl_FrontFacing;
in vec2 gl_PointCoord;
gl_FragCoord
The location of the fragment in window space. The X, Y and Z components are the window-space position of the fragment. The Z value will be written to the depth buffer if gl_FragDepth is not written to by this shader stage. The W component of gl_FragCoord is 1/Wclip, where Wclip is the interpolated W component of the clip-space vertex position output to gl_Position from the last Vertex Processing stage.
The space of gl_FragCoord can be modified by redeclaring gl_FragCoord with special input layout qualifiers:
layout(origin_upper_left) in vec4 gl_FragCoord;
This means that the origin for gl_FragCoord's window-space will be the upper-left of the screen, rather than the usual lower-left.
layout(pixel_center_integer) in vec4 gl_FragCoord;
OpenGL window space is defined such that pixel centers are on half-integer boundaries. So the center of the lower-left pixel is (0.5, 0.5). Using pixel_center_integer​ adjust gl_FragCoord such that whole integer values represent pixel centers.
Both of these exist to be compatible with D3D's window space. Unless you need your shaders to have this compatibility, you are advised not to use these features.
gl_FrontFacing
This is false if the fragment was generated by the back-face of the primitive; it is true in all other cases (including Primitives that have no back face).
gl_PointCoord
The location within a point primitive that defines the position of the fragment relative to the side of the point. Points are effectively rasterized as window-space squares of a certain pixel size. Since points are defined by a single vertex, the only way to tell where in that square a particular fragment is is with gl_PointCoord.
The values of gl_PointCoord's coordinates range from [0, 1]. OpenGL uses a upper-left origin for point-coordinates by default, so (0, 0) is the upper-left. However, the origin can be switched to a bottom-left origin by calling glPointParameteri(GL_POINT_SPRITE_COORD_ORIGIN, GL_LOWER_LEFT);

OpenGL 4.0 and above define additional system-generated input values:

in int gl_SampleID;
in vec2 gl_SamplePosition;
in int gl_SampleMaskIn[];
gl_SampleID
This is an integer identifier for the current sample that this fragment is rasterized for.
Warning: Any use of this variable at all will force this shader to be evaluated per-sample. Since much of the point of multisampling is to avoid that, you should use it only when you must.
gl_SamplePosition
This is the location of the current sample for the fragment within the pixel's area, with values on the range [0, 1]. The origin is the bottom-left of the pixel area.
Warning: Any use of this variable at all will force this shader to be evaluated per-sample. Since much of the point of multisampling is to avoid that, you should use it only when you must.
gl_SampleMaskIn
When using multisampling, this variable contains a bitfield for the sample mask of the fragment being generated. The array is as long as needed to fill in the number of samples supported by the GL implementation.

Some Fragment shader built-in inputs will take values specified by OpenGL, but these values can be overridden by user control.

in float gl_ClipDistance[];
in int gl_PrimitiveID;
gl_ClipDistance
This array contains the interpolated clipping plane half-spaces, as output for vertices from the last Vertex Processing stage.
gl_PrimitiveID
This value is the index of the current primitive being rendered by this drawing command. This includes any Tessellation applied to the mesh, so each individual primitive will have a unique index.
However, if a Geometry Shader is active, then the gl_PrimitiveID is exactly and only what the GS provided as output. Normally, gl_PrimitiveID is guaranteed to be unique, so if two FS invocations have the same primitive ID, they come from the same primitive. But if a GS is active and outputs non-unique values, then different fragment shader invocations for different primitives will get the same value. If the GS did not output a value for gl_PrimitiveID, then the fragment shader gets an undefined value.

Warning: The above discussion of gl_PrimitiveID is based on a particular reading of the OpenGL 4.6 specification. However, the specification itself is somewhat inconsistent with this view, suggesting that the primitive ID may only get incremented based on data fed to the system, not data generated by, for example, the tessellator. And the Vulkan specification seems to concur with this interpretation, and at least one implementation is known to agree with that as well. Until there is some clarification on the issue, you should consider the above to be questionable.

GL 4.3 provides the following additional inputs:

in int gl_Layer;
in int gl_ViewportIndex;
gl_Layer
This is either 0 or the layer number for this primitive output by the Geometry Shader.
gl_ViewportIndex
This is either 0 or the viewport index for this primitive output by the Geometry Shader.

Outputs[edit]

User-defined output variables in the fragment shader can only be the following GLSL types: floats, integers, vectors of the same. They can also be arrays of one of these types, including arrays of arrays (though you are strongly encouraged to avoid this). User-defined output variables can also not be aggregated into interface blocks.

Output buffers[edit]

User-defined outputs from a fragment shader represent a series of "colors". These color values are directed into specific buffers based on the glDrawBuffers state. These are called "fragment colors", though you can treat them like any arbitrary data. Any fragment color values not written by the FS will have undefined values; such undefined values can still be routed to a buffer via `glDrawBuffers`.

Much like vertex shader input assignment, there are three ways to do associate an output variable with a color number. 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 internally defines the fragment colors. This is done using the following layout syntax:
layout(location = 3) out vec4 diffuseColor;
This sets the diffuseColor's fragment color to 3.
Pre-link specification
Before linking a program that includes a fragment shader, the user may tell OpenGL to assign a particular output variable to a particular fragment color. This is done with the following function:

void glBindFragDataLocation(GLuint program​, GLuint colorNumber​, const char * name​);

colorNumber​ is the fragment color to assign. name​ is the name of the fragment shader output to assign the given fragment color to.
Note that it is perfectly legal to assign names to fragment colors that are not mentioned in the fragment shader. The linking process will only use the names that are actually mentioned in the fragment shader. Because of that, it is also perfectly legal to assign multiple names to the same number; 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 output to a fragment color, then the fragment color is automatically assigned by OpenGL when the program is linked. The fragment color assigned is completely arbitrary and may be different for different programs that are linked, even if they use the exact same fragment shader code.
Automatic assignment for fragment shader outputs makes even less sense than for vertex shader inputs. The color numbers (as explained below) refer to a draw buffer as defined by glDrawBuffers. You are very likely to use the same Framebuffer for many different programs (while you will probably frequently change VAOs); changing glDrawBuffers state, and re-validating the FBO every time, is probably not a good idea.

Fragment color indices for array outputs are assigned consecutively, just as for vertex attributes.

The limit on the number of fragment colors is defined by GL_MAX_DRAW_BUFFERS​, or GL_MAX_DUAL_SOURCE_DRAW_BUFFERS when using dual-source blending as below.

The mapping between fragment colors and actual buffers within a Framebuffer is defined by glDrawBuffers, which is part of the framebuffer's state. For example, if we set our draw buffers up like this:

const GLenum buffers[] = {GL_COLOR_ATTACHMENT4, GL_COLOR_ATTACHMENT2, GL_NONE, GL_COLOR_ATTACHMENT0};
glDrawBuffers(4, buffers);

And we set up our output variables like this:

layout(location = 1) out int materialID;
layout(location = 4) out vec3 normal;
layout(location = 0) out vec4 diffuseColor;
layout(location = 3) out vec3 position;
layout(location = 2) out vec4 specularColor;

diffuseColor uses fragment color 0. The 0th index of the array passed to glDrawBuffers contains GL_COLOR_ATTACHMENT4. Therefore, the value written to diffuseColor will go to the buffer bound to the GL_COLOR_ATTACHMENT4 slot. Here's a table of the outputs and the associated buffers:

Output name Color attachment
materialID GL_COLOR_ATTACHMENT2
normal GL_NONE
diffuseColor GL_COLOR_ATTACHMENT4
position GL_COLOR_ATTACHMENT0
specularColor GL_NONE

normal is assigned GL_NONE (and therefore the written value is discard) because it attempts to access an index that was beyond the size of the array passed to glDrawBuffers. All of those indices implicitly use GL_NONE. specularColor is assigned GL_NONE because that is what was given for the 2nd index (zero-based) of the array.


Dual-source blending[edit]

Dual-source blending is a technique whereby two (or theoretically more) output values can be used on the same buffer via blending. It is a way to get more values into the blend equation.

This is achieved by assigning another parameter to fragment output variables: an index. All outputs have an index in addition to a fragment color number. If any of the outputs is assigned a non-zero index, then the fragment shader uses dual-source blending.

When a fragment shader provides dual-source output, it reduces the number of buffers it can write to. The new maximum fragment color output is GL_MAX_DUAL_SOURCE_DRAW_BUFFERS, which is 1 on every piece of hardware that supports this feature. In short: if you want dual-source blending, you can only write to one buffer from the fragment shader.

The index of a fragment shader output can be assigned similarly to the fragment color. There is an in-shader specification:

layout(location = 0, index = 1) out vec4 diffuseColor1;
layout(location = 0) out vec4 diffuseColor0;

When an index​ is not assigned, the default index of 0 is used. Thus, diffuseColor0 is assigned to fragment color 0, index 0, while diffuseColor1 is assigned fragment color 0, index 1.

The index can also be assigned pre-link, with glBindFragDataLocationIndexed. The precedence rules work the same way as for glBindFragDataLocation. Speaking of which, glBindFragDataLocation always assigns an index of 0.

If neither method is used, then the index assigned will always be 0. You can't get dual-source output without manual assignment of some kind.

Other outputs[edit]

V · E

Fragment Shaders have the following built-in output variables.

out float gl_FragDepth;
gl_FragDepth
This output is the fragment's depth. If the shader does not statically write this value, then it will take the value of gl_FragCoord.z.
To "statically write" to a variable means that you write to it anywhere in the program. Even if the writing code is technically unreachable for some reason, if there is a gl_FragDepth = ... expression anywhere in the shader, then it is statically written.
Warning: If the fragment shader statically writes to gl_FragDepth, then it is the responsibility of the shader to statically write to the value in all circumstances. No matter what branches may or may not be taken, the shader must ensure that the value is written. So, if you conditionally write to it in one place, you should at least make sure that there is a single non-conditional write sometime before that.

GLSL 4.20 or ARB_conservative_depth allows the user to specify that modifications to gl_FragDepth (relative to the gl_FragCoord.z value it would have otherwise had) will happen in certain ways. This allows the implementation the freedom to not turn off Early Depth Tests in certain situations.

This is done by re-declaring gl_FragDepth with a special layout qualifier:

layout (depth_<condition>) out float gl_FragDepth;

The condition​ can be one of the following:

any
The default. You may freely change the depth, but you lose the most potential performance.
greater
You will only make the depth larger, compared to gl_FragCoord.z.
less
You will only make the depth smaller, compared to gl_FragCoord.z.
unchanged
If you write to gl_FragDepth, you will write exactly gl_FragCoord.z.

Violating the condition​ yields undefined behavior.

GLSL 4.00 or ARB_sample_shading brings us:

out int gl_SampleMask[];
gl_SampleMask
This defines the sample mask for the fragment when performing mutlisampled rendering. If a shader does not statically write to it, then it will be filled in by gl_SampleMaskIn. The sample mask output here will be logically AND'd with the sample mask computed by the rasterizer.
Warning: Just as with gl_FragDepth, if a fragment shader writes to gl_SampleMask at all, it must make sure to write to the value for all execution paths. But it must also make sure to write to each element in the array. The array has the same size as gl_SampleMaskIn.

See also[edit]