View source for Fragment Shader

{{pipeline float}}

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 ==

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 ==

Unlike every other shader stage, fragment shaders have implicit derivatives generated. As such, they can [[Implicit Derivative|use the majority of the texturing functions]]. You still need to watch out for [[Non-Uniform Control Flow|non-uniform flow control]].

Fragment shaders also have access to the {{code|discard}} command. When executed, this command causes the fragment's output values to be [[Fragment Discard|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 {{code|discard}}, on actual systems, it may continue. Such systems are required to prevent [[Image Load Store|image store]], [[Atomic Counter]], and [[Shader Storage Buffer Object]] writes issued after the {{code|discard}} from working (such operations performed before the {{code|discard}} work as expected).

Normally, most of the [[Per-Sample Processing]] steps happen after the fragment shader. However, with {{require|4.2|shader_image_load_store}}, the shader can enforce [[Early Fragment Test]]ing, 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:

<source lang="glsl">
layout(early_fragment_tests) in;
</source>

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 {{code|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 [[Stencil Function|operations]] are set.}}

== Inputs ==

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|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|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 ===

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

== Outputs ==

User-defined output variables in the fragment shader can only be the following [[Data Type (GLSL)|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 Block (GLSL)|interface blocks]].

=== Output buffers ===

User-defined outputs from a fragment shader represent a series of "colors". These color values are directed into specific buffers based on the {{apifunc|glDrawBuffers}} state. These are called "[[Fragment#Fragment_shader_outputs|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 `{{apifunc|glDrawBuffers}}`.

Much like [[Vertex Shader#Input|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 {{code|layout}} syntax:
<source lang="glsl">
layout(location = 3) out vec4 diffuseColor;
</source>
: This sets the {{code|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 {{apifunc|glBindFragDataLocation}}(GLuint {{param|program}}, GLuint {{param|colorNumber}}, const char * {{param|name}});
: {{param|colorNumber}} is the fragment color to assign. {{param|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 {{apifunc|glDrawBuffers}}. You are very likely to use the same [[Framebuffer]] for many different programs (while you will probably frequently change VAOs); changing {{apifunc|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 Shader Large Attribute|vertex attributes]].

The limit on the number of fragment colors is defined by {{enum|GL_MAX_DRAW_BUFFERS}}, or {{enum|GL_MAX_DUAL_SOURCE_DRAW_BUFFERS}} when using [[#Dual-source blending|dual-source blending as below]].

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

<source lang="cpp">
const GLenum buffers[] = {GL_COLOR_ATTACHMENT4, GL_COLOR_ATTACHMENT2, GL_NONE, GL_COLOR_ATTACHMENT0};
glDrawBuffers(4, buffers);
</source>

And we set up our output variables like this:

<source lang="glsl">
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;
</source>

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

{| class="wikitable"
! Output name
! Color attachment
|-
| materialID
| {{enum|GL_COLOR_ATTACHMENT2}}
|-
| normal
| {{enum|GL_NONE}}
|-
| diffuseColor
| {{enum|GL_COLOR_ATTACHMENT4}}
|-
| position
| {{enum|GL_COLOR_ATTACHMENT0}}
|-
| specularColor
| {{enum|GL_NONE}}
|}

{{code|normal}} is assigned {{enum|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 {{apifunc|glDrawBuffers}}. All of those indices implicitly use {{enum|GL_NONE}}. {{code|specularColor}} is assigned {{enum|GL_NONE}} because that is what was given for the 2nd index (zero-based) of the array.


=== Dual-source blending ===
{{main|Blending#Dual_Source_Blending}}

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 {{enum|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:

<source lang="glsl">
layout(location = 0, index = 1) out vec4 diffuseColor1;
layout(location = 0) out vec4 diffuseColor0;
</source>

When an {{param|index}} is not assigned, the default index of 0 is used. Thus, {{code|diffuseColor0}} is assigned to fragment color 0, index 0, while {{code|diffuseColor1}} is assigned fragment color 0, index 1.

The index can also be assigned pre-link, with {{apifunc|glBindFragDataLocationIndexed}}. The precedence rules work the same way as for {{apifunc|glBindFragDataLocation}}. Speaking of which, {{apifunc|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 ===
{{snippet|:Fragment Shader/Defined Outputs}}

== See also ==

* The previous pipeline stages:
** [[Vertex Post-Processing]]
** [[Rasterization]]
* The next pipeline stage:
** [[Per-Sample Processing]]

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