View source for Layout Qualifier (GLSL)

{{shader float}}

A number of [[OpenGL Shading Language]] variables and definitions can have '''layout qualifiers''' associated with them. Layout qualifiers affect where the storage for a variable comes from, as well as other user-facing properties of a particular definition.

All layout qualifiers are defined with a common syntax:

 layout({{param|qualifier1}}, {{param|qualifier2}} = ''value'', ...) ''variable definition''

The {{param|qualifier}} values are specific to a particular use of layouts. The qualifiers are order-independent, unless otherwise noted. Some qualifiers can have values assigned to them, as with {{param|qualifier2}} in the above example.

In the above, ''value'' must be an integer literal, unless you are using {{require|4.4|enhanced_layouts}}, in which case it may be an [[Integral Constant Expression]] (aka: a compile-time constant).

Layout qualifiers are sometimes used to define [[#Shader stage options|various options for different shader stages]]. These shader stage options apply to the input of the shader stage or the output. In these definitions, ''variable definition'' will just be {{code|in}} or {{code|out}}.

In {{require|4.2|shading_language_420pack}}, a definition can have multiple {{code|layout()}} segments to qualify the definition, and and the same {{param|qualifier}} can appear multiple times for the same definition. When this happens, the last defined value for mutually-exclusive qualifiers or for numeric qualifiers prevails.

== Interface layouts ==

[[Type_Qualifier#Shader_stage_inputs_and_outputs|Shader stage input and output variables]] define a shader stage's interface. Depending on the available feature set, these variables can have layout qualifiers that define what resources they use.

=== Vertex shader attribute index ===

[[Vertex Attributes|Vertex shader inputs]] can specify the attribute index that the particular input uses. This is done with this syntax:

 layout(location = ''attribute index'') in vec3 position;

With this syntax, you can forgo the use of {{apifunc|glBindAttribLocation}} entirely. If you try to combine the two and they conflict, the layout qualifier always wins.

Attributes that take up multiple attribute slots will be given a sequential block of that number of attributes in order starting with the given attribute. For example:

<source lang="glsl">
 layout(location = 2) in vec3 values[4];
</source>

This will allocate the attribute indices 2, 3, 4, and 5.

=== Fragment shader buffer output ===
[[Fragment Shader Output Buffer|Fragment shader outputs]] can specify the buffer index that a particular output writes to. This uses the same syntax as vertex shader attributes:

 layout(location = ''output index'') out vec4 outColor;

As with vertex shader inputs, this allows the user to forgo the use of {{apifunc|glBindFragDataLocation}}. Similarly, the values in the shader override the values provided by this function.

For [[Dual Source Blending|dual source blending]], the syntax includes a second qualifier:

 layout(location = ''output index'', index = ''dual output index'') out vec4 outColor;

Again, this allows one to forgo the use of {{apifunc|glBindFragDataLocationIndexed}}.

=== Program separation linkage ===
{{infobox feature
| name = Program Separation
| core = 4.1
| core_extension = {{extref|separate_shader_objects}}
}}

When dynamically using separate programs, the correspondence between the outputs of one program and the inputs of the next is important. This correspondence typically happens the same way as when doing dynamic linkage: inputs and outputs must match by name, type, and qualifiers exactly (with a few exceptions).

However, it is possible to tag variables with an index, such that they correspond by the index instead of by name. This [[Separate Program Interface Match|changes the interface matching process]] a bit, allowing outputs that aren't consumed by the next stage and so forth.

This index is provided by {{code|location}} qualifier. This applies to loose input/output variables. [[Interface Block (GLSL)|Input and output#Interface block variables]] need [[#Block member locations|additional functionality]] to use these.

For example, given a vertex shader that provides these outputs:

<source lang="glsl">
layout(location = 0) out vec4 color;
layout(location = 1) out vec2 texCoord;
layout(location = 2) out vec3 normal;
</source>

This allows the consuming shader to use different names and even types:

<source lang="glsl">
layout(location = 0) in vec4 diffuseAlbedo;
layout(location = 1) in vec2 texCoord
layout(location = 2) in vec3 cameraSpaceNormal;
</source>

This still results in an interface match.

{{note|The {{extref|separate_shader_objects}} extension was released in a form where this kind of layout location linking outside of separate shaders did not work. That is, if you specified location indices, they were effectively ignored unless you were linking a separate program. The spec was changed to fix this, so that linkage would be the same whether separate or together; if location indices are specified, they are always used. However, AMD implemented the old behavior for a time, and it is not clear that their implementation was updated to fix this.}}

'''Location sizes''': Interfaces between programs can be of various types, even user-defined structs and arrays. Some such types consume multiple locations. When a type that consumes multiple locations is used, they will consume locations sequentially. It is a compile/link-time error to have ranges of variables overlap their locations (unless they have different [[#Interface components|components specifiers]] and don't overlap their component usage).

Scalars and vector types that are not doubles all take up one location. The {{code|double}} and {{code|dvec2}} types also take one location, while {{code|dvec3}} and {{code|dvec4}} take up 2 locations. Structs take up locations based on their member types, in-order. Arrays also take up locations based on their array sizes.

Here are some examples:

<source lang="cpp">
struct OutData
{
  vec3 data1;
  dvec4 data2;
  float val[3];
};
</source>
<source lang="glsl">
layout(location = 0) out vec3 vals[4];    // Consumes 4 locations
layout(location = 4) out OutData myOut;   // Consumes 6 locations. dvec4 uses 2, and `val[3]` uses 3 total
layout(location = 10) out vec2 texCoord;  // Consumes 1 location
</source>

The number of available locations is implementation-defined, and it cannot be queried. However, it will be at least one-fourth of {{enum|GL_MAX_VARYING_COMPONENTS}}.

==== Block member locations ====
{{infobox feature
| name = Block member locations
| core = 4.4
| core_extension = {{extref|enhanced_layouts}}
}}

With this feature, The {{code|location}} qualifier can be used on input/output [[Interface Block (GLSL)|interface block definitions and members]].

{{note|This feature ''does not'' exist to allow separate linking to work differently for interface blocks. So even if an interface block uses location qualifiers, the linking will ''still'' require an exact match between the blocks. This feature is here to support [[#Interface components|component specifications and location aliasing]], which requires specifying an explicit location.}}

The block as a whole can have a {{code|location}} qualifier. This will allocate a sequential sets of locations, giving the first member the given location and incrementing from there. The size of the individual members is computed the same way as above.

A particular member of a block can have a {{code|location}} qualifier. However, this only works if the block itself is qualified or if ''all members'' of the block have a qualifier.

If the block has a qualifier, then a member's qualifier overrides the block computed qualifier. It also resets the block's computed qualifier, so that subsequent unqualified members will be computed relative to the most recent explicit qualifier. Here is an example:

<source lang="glsl">
layout(location = 0) out Block
{
  vec2 first;                        // Location 0.
  dvec4 second[3];                   // Location 1.
  vec4 third;                        // Location 7; dvec4 takes 2 each, and the prior one has 3 array members.
  layout(location = 10) vec2 fourth; // Location 10.
  dvec4 fifth;                       // Location 11. Starts from the most recent explicit location.
  layout(location = 8) dvec3 sixth;  // Location 8.
  vec3 seventh;                      // Location 10, overlaps with `fourth`, so causes an error.
};
</source>

=== Interface components ===
{{infobox feature
| name = Interface components
| core = 4.4
| core_extension = {{extref|enhanced_layouts}}
}}
There are limits on the locations of input and output variables (of all kinds). These limits are based on an implicit assumption in the API that the resources being passed around are done so as groups of 4-element vectors of data. This is why a {{code|mat2}} takes up 2 locations, while a {{code|vec4}} only takes up 1, even though they both are 4 floats in size. The {{code|mat2}} is considered to be passed as two {{code|vec4}}s; the last two components of each vector simply go unused.

It is possible to reclaim some of this unused space. To do this, you declare two (or more) variables that use the same location, but use different components within that location.

This is done using the {{code|component}} layout qualifier. You ''must'' use a {{code|location}} qualifier when using {{code|component}}, even if the variable would have an implicitly assigned location from [[#Block member locations|an interface block declaration]]. If a variable does not have an explicit {{code|component}} qualifier, it is as through it were set to 0.

The {{code|component}} qualifier specifies the starting component that the variable will use. It is illegal to set the component on a variable whose type would cause it to exceed the boundaries of a 4-element vector. So if you have a {{code|vec3}}, the {{code|component}} can only be 0 or 1.

If you set two interface variables to the same location, the variables must use components such that the used space in that location does not overlap. So you can't pack a {{code|vec3}} in the same location with a {{code|vec2}}, but you can pack two {{code|floats}} with a {{code|vec2}}.

Arrays (and arrays of arrays) can also have components assigned. This will assign the component to each location that the array covers. So it is possible to do the following:

<source lang="glsl">
layout(location = 0) out vec2 arr1[5];
layout(location = 0, component = 2) out vec2 arr2[4]; //Different sizes are fine.
layout(location = 4, component = 2) out float val;    //A non-array takes the last two fields from location 4.
</source>

Two (or more) variables that share the same location must satisfy the following conditions:

* Share the same base data type. So you can have alias locations for floating-point types, or integer types (signed and unsigned does not matter for this), but you cannot have a float sit alongside an integer.
* Use the same [[Interpolation qualifier|interpolation qualifiers]].

The {{code|component}} qualifier can be used for any shader stage input/output declaration. This includes interfaces between shaders, fragment shader outputs, tessellation {{code|patch}} variables, and so forth. However, it may not be used on:

* Variables of matrix types
* Variables of structs types
* [[Interface Block (GLSL)|Interface blocks]] (this qualifier can be on members of a block, but not on the block itself)
* Arrays of types on this list (arrays of non-matrix basic types are fine).

For [[Vertex Attribute]]s and [[Fragment Shader Output]]s, OpenGL still treats each location as though it were a single variable. So {{apifunc|glVertexAttribPointer}} feeds data to all of the input variables for that location. Any components used by the shader that are not provided by the array are filled in as normal (with zeros, except for the last which gets a 1). And {{apifunc|glDrawBuffers}} pulls data from all of the output variables for that location.

{{note|Previously, it was stated that it is illegal for two interface variables to use the same location and overlap their components. That is not ''entirely'' true. It is legal to do so for vertex shader inputs and fragment shader outputs. But only so long as any particular vertex shader invocation cannot read from both of the overlapping inputs, and any particular fragment shader invocation does not write to both overlapping outputs. You are advised to forget that this is possible; there's not much point to it.}}

== Binding points ==
{{infobox feature
| name = Binding points
| core = 4.2
| core_extension = {{extref|shading_language_420pack}}
}}

[[Interface_Block_(GLSL)#Buffer_backed|Buffer backed interface blocks]] and all [[Opaque Type|opaque types]] have a setting which represents an index in the GL context where a buffer or texture object is bound so that it can be accessed through that interface. These binding points, like input attribute indices and output data locations, can be set from within the shader. This is done by using the "binding" layout qualifier:

{{clear float}}
<source lang="glsl">
layout(binding = 3) uniform sampler2D mainTexture;
layout(binding = 1, std140) uniform MainBlock
{
  vec3 data;
};
</source>

The first line is the equivalent of getting the uniform location for "mainTexture" and setting its uniform value to "3". Similarly, the second line is the equivalent of getting the "MainBlock" block location and setting its block index to "1".

This capacity only sets the initial binding index. OpenGL code can later modify it if it wishes.

== Image formats ==
{{infobox feature
| name = Image variable formats
| core = 4.2
| core_extension = {{extref|shader_image_load_store}}
}}

[[Image Load Store|Image uniform variables]] have qualifiers that define the format that all reading operations will convert the data into and all writing operations will convert the data from. They are grouped into 3 categories: floating-point, signed-integer, and unsigned-integer formats. These are the possible values:

{{div col}}
{{layout image formats}}
{{div col end}}

== Atomic counter storage ==
{{infobox feature
| name = Atomic Counters
| core = 4.2
| core_extension = {{extref|shader_atomic_counters}}
}}
{{main|Atomic Counter}}

Atomic Counter variables have special layout settings that define where within a buffer object a particular variable comes from. These are ''required''; there are no alternate methods to set these fields.

{{snippet|:Atomic Counter/Layout Parameters}}

== Interface block memory layout ==
{{main|Interface Block (GLSL)#Memory_layout}}

Variables declared in interface blocks that get their storage from buffers ([[Uniform Buffer Object|uniform blocks]] or [[Shader Storage Buffer Object|shader storage blocks]]) have a number of layout qualifiers to define the packing and ordering of the variables defined in the block.

== Explicit uniform location ==
{{infobox feature
| name = Explicit Uniform Location
| core = 4.3
| core_extension = {{extref|explicit_uniform_location}}
}}
{{snippet|:Uniform (GLSL)/Explicit Uniform Location}}

== Subroutine qualifiers ==
{{infobox feature
| name = Subroutine qualifiers
| core = 4.3
| core_extension = {{extref|explicit_uniform_location}}
}}
{{main|Shader Subroutine}}
{{snippet|:Shader Subroutine/Layout Qualifier}}

== Transform feedback qualifiers ==
{{infobox feature
| name = Transform feedback qualifiers
| core = 4.4
| core_extension = {{extref|enhanced_layouts}}
}}
{{snippet|:Transform Feedback/In Shader Specification}}

== Shader stage options ==

Many [[Shader|shader stages]] have options that control some aspect of how they work. These are defined within the shader using layout qualifiers.

=== Tessellation control output vertex count ===
{{infobox feature
| name = Tessellation Control Shader
| core = 4.0
| core_extension = {{extref|tessellation_shader}}
}}

[[Tessellation Control Shader]]s (TCS) output patches with a particular vertex count. This is defined by a layout qualifier:

 layout(vertices = {{param|vertex_count}}) out;

The TCS will be invoked once for each vertex output.

=== Tessellation evaluation options ===
{{main|Tessellation Evaluation Shader#Tessellation options}}

The Tessellation Evaluation Shader (requires GL 4.0 or {{extref|tessellation_shader}}) has a large number of special layout qualifiers that control its behavior.

=== Geometry shader primitives ===

[[Geometry Shader]]s take a particular primitive type as input and return a particular primitive type as outputs. Also, geometry shaders have a defined maximum number of vertices that they can output. These specifications cannot be used on a variable definition; it can only be used on the qualifiers {{code|in}} and {{code|out}} as a whole.

  layout({{param|primitive type}}) in;
  layout({{param|primitive type}}, max_vertices = ''integer value'') out;

For inputs, the {{param|primitive type}} can be any of the following:

* points
* lines
* lines_adjacency
* triangles
* triangles_adjacency

For outputs, the {{param|primitive type}} can be any of the following:

* points
* line_strip
* triangle_strip

The value of {{param|max_vertices}} defines the maximum number of vertices the geometry shader can every output in a single invocation.

=== Fragment shader coordinate origin ===

The {{code|gl_FragCoord}} [[Built-in Variable (GLSL)|built-in variable]] represents the location of the fragment in window-space. There are two layout qualifiers that can affect this. These are specified by [[Variable Redeclaration|redeclaring]] the predefined variable.

The qualifier {{code|origin_upper_left}} specifies that {{code|gl_FragCoord}} will have the origin (0, 0) in the upper-left of the screen. The standard OpenGL convention is to have it in the lower-left. This does not change the Z or W of the {{code|gl_FragCoord}} value.

The qualifier {{code|pixel_center_integer}} specifies that the X and Y of {{code|gl_FragCoord}} will be shifted by a half-pixel, so that the center of each pixel is an integer value. The standard OpenGL convention puts the integer values at the corner of the pixel.

These are used as follows:

<source lang="cpp">
layout(origin_upper_left) in vec4 gl_FragCoord;
</source>

=== Early fragment tests ===
{{infobox feature
| name = Forced early fragment tests
| core = 4.2
| core_extension = {{extref|shader_image_load_store}}
}}
{{main|Early Depth Test#Explicit specification}}

By the OpenGL specification, the depth and stencil tests are performed after the fragment shader's execution ([[Early Depth Test|implementations can and will do it before the fragment shader]], but only if it won't affect the apparent output). However, with a fragment shader's ability to write to arbitrary images and buffers in OpenGL 4.2+, it is useful to be able to enforce early tests. This can be done in GL 4.2 (or with ARB_shader_image_load_store):

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

Any writes to {{code|gl_FragDepth}} in a shader that defines this will be ''ignored''.



[[Category:OpenGL Shading Language]]