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(qualifier1​, qualifier2​ = value, ...) variable definition

The 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 qualifier2​ in the above example.

Layout qualifiers are sometimes used to define 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 in or out.

In OpenGL 4.2 orARB_shading_language_420pack, a definition can have multiple layout() segments to qualify the definition, and and the same 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.

Program separation linkage

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 changes the interface matching process a bit, allowing outputs that aren't consumed by the next stage and so forth.

Note: The ARB_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 components specifiers and don't overlap their component usage).

Scalars and vector types that are not doubles all take up one location. The double and dvec2 types also take one location, while dvec3 and 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.

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 component specifications and location aliasing, which requires specifying an explicit location.

The block as a whole can have a 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 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:

Interface components

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 mat2 takes up 2 locations, while a vec4 only takes up 1, even though they both are 4 floats in size. The mat2 is considered to be passed as two vec4s; 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 component layout qualifier. You must use a location qualifier when using component, even if the variable would have an implicitly assigned location from an interface block declaration. If a variable does not have an explicit component qualifier, it is as through it were set to 0.

The 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 vec3, the 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 vec3 in the same location with a vec2, but you can pack two floats with a 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:

layout(location=0)outvec2arr1[5];layout(location=0,component=2)outvec2arr2[4];//Different sizes are fine.layout(location=4,component=2)outfloatval;//A non-array takes the last two fields from location 4.

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.

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

Variables of matrix types

Variables of structs types

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 Attributes and Fragment Shader Outputs, OpenGL still treats each location as though it were a single variable. So 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 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

Buffer backed interface blocks and all opaque types have a setting which represents the location in the GL context where an object that is to be read/modified is stored. 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:

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

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:

Atomic counters use two layout qualifier parameters. The binding defines which Buffer Object bound to the given index in the indexed target GL_ATOMIC_COUNTER_BUFFER​ will provide the storage for this atomic counter. The binding parameter is not optional.

Atomic counters also have an optional offset parameter. The offset is the byte offset from the beginning of the range bound to the target to the location where this variable gets its 32-bits of storage.

The offset parameter is not required. If it is not specified, then the offset will be 4 bytes larger than the offset previously used for that binding, starting at 0 if none were previously specified. For example:

Interface block memory layout

Variables declared in interface blocks that get their storage from buffers (uniform blocks or 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

Uniforms defined outside of Interface Blocks have a location. This location can be directly assigned in the shader, using this syntax:

layout(location=2)uniformmat4modelToWorldMatrix;

Calling glGetUniformLocation(prog, "modelToWorldMatrix") is guaranteed to return 2. It is illegal to assign the same uniform location to two uniforms in the same shader or the same program. Even if those two uniforms have the same name and type, and are defined in different shader stages, it is not legal to explicitly assign them the same uniform location; a linker error will occur.

All non-array/struct types will be assigned a single location. Arrays and structs will be assigned sequentially increasing locations, starting with the given location. Given this:

layout(location=2)uniformmat4some_mats[10];

some_mats will be assigned all of the uniform locations on the half-open range [2, 12). This will apply for nested types. Consider the following:

Each Thingy takes up 4 uniform locations; the first three going to an_array and the fourth going to foo. Thus, some_thingies takes up 24 uniform locations.

Uploading arrays of uniforms with one of the glUniform*v functions will work. For example, uniform location 2 represents the array `some_thingies[0].an_array`. As such, you can upload an array of vec4s to this array with glUniform4fv(2, 3, ...);.

No two uniform declarations in a program can be explicitly assigned the same location. This also means that explicit uniform location ranges cannot overlap. So this is illegal:

Warning: While it is clear that two uniforms with different definitions (names and types) in different stages of the same program may not have the same explicit uniform location, what is less clear is whether two uniforms with the same name and type may exist in different stages. If you declare a uniform with the same name/type in two stages of the same program, OpenGL considers them to be the same uniform, with a single uniform location. The question is whether you can get this functionality when providing an explicit location for that uniform. Some parts of the specification suggest that you cannot, while other parts suggest that you can. Some implementations permit this, but the spec itself is ambiguous. This issue is [under active review].

The maximum number of available locations within a single program is GL_MAX_UNIFORM_LOCATIONS, which will be at least 1024 locations. You may not use a uniform location outside of the range [0, GL_MAX_UNIFORM_LOCATIONS), nor may the sequential assignment of uniform locations due to array/struct aggregation go outside of this range.

Subroutine qualifiers

Shader Subroutines use a number of resources that can be automatically assigned to each shader stage at link time. However, the user can explicitly define them within the shader text as well, to avoid having to query them.

Subroutine functions each have a specific index that identifies that particular subroutine among all subroutines in a shader stage. This subroutine can be set from within a shader using the index layout qualifier:

layout(index=2)subroutine(SubroutineTypeName,...)...;

This sets the particular subroutine function definition to index 2. No two subroutine functions may have the same index. Also, this index is subject to the limitations on the number of subroutines in a shader stage.

Each subroutine uniform variable within a shader stage has a particular position in that stage's list of subroutine uniforms. This location in the array can be set using the location layout qualifer:

This means that array index 1 in the call to glUniformSubroutines refers to the variable subroutineVariableName.

The number of active subroutine uniforms for this shader stage will be the largest location + 1. This means that some "active" uniform locations may be unused. If the above example were the only subroutine uniform, then the number of active subroutine uniforms will be considered to be 2, with location 0 going unusued.

If some uniforms are user-assigned and some are linker-assigned, the linker will fill in the unused indices first, before increasing the number of active uniforms. So the number of active subroutine uniforms can be larger than this. The linker will never assign a subroutine uniform to a user-assigned subroutine uniform, even if the user-assigned one is not active.

The linking can fail if user-defined subroutine uniform assignments do not leave enough room for linker-assigned ones. Linker-assigned subroutine uniform locations for arrays must also be consecutively assigned, so if there is insufficient space to assign that many uniform locations, the linking will fail.

Transform feedback qualifiers

Layout qualifiers can be used to define which output variables are captured in Transform Feedback operations. When these qualifiers are set in a shader, they completely override any attempt to set the transform feedback outputs from OpenGL via glTransformFeedbackVaryings.

Any output variable or output interface block declared with the xfb_offset layout qualifier will be part of the transform feedback output. This qualifier must be specified with an integer byte offset. The offset is the number of bytes from the beginning of a vertex to be written to the current buffer to this particular output variable.

The offsets of contained values (whether in arrays, structs, or members of an interface block if the whole block has an offset) are computed, based on the sizes of prior components to pack them in the order specified. Any explicitly provided offsets are not allowed to violate alignment restrictions. So if a definition contains a double (either directly or indirectly), the offset must be 8-byte aligned.

Members of interface blocks can have their offsets specified directly on them, which overrides any computed offsets. Also, all members of an interface block are not required to be written to outputs (though that will happens if you set the xfb_offset on the block itself). Stream assignments for a geometry shader are required to be the same for all members of a block, but offsets are not.

Different variables being captured are assigned to buffer binding indices. Offset assignments are separate for the separate buffers. It is a linker error for two variables captured by the same buffer to have overlapping byte offsets, whether automatically computed or explicitly assigned.

An explicit buffer assignment is made by using the xfb_buffer qualifier on the same declaration as the offset qualifier. This takes an integer which defines the buffer binding index that the captured output(s) is/are associated with. The integer must be less than GL_MAX_TRANSFORM_FEEDBACK_BUFFERS.

Any offsets for global variables or interface blocks that do not specify a buffer explicitly will use the current buffer. The current buffer is set as follows:

layout(xfb_buffer=1)out;

All following offsets for globals that do not explicitly specify a buffer will use 1 as their buffer. The initial current buffer for a shader is 0.

Variables can have xfb_buffer assigned to them without xfb_offset. This does nothing and will be ignored.

Interface blocks have a special association with buffers. Each interface block is associated with a buffer, regardless of whether any of its members are captured. The buffer is either the current buffer as defined above or a buffer explicitly specified by xfb_buffer.

As previously stated, all members of a block do not have to be captured. However, if any members of a block are captured, they must all be captured to the same buffer. Specifically, the buffer associated with that block. It is an error to use xfb_buffer on a member if the buffer index you provide is different from the index used by the block.

As an example:

layout(xfb_buffer=2)out;// Default buffer of 2.outOutputBlock1// Block buffer index is implicitly 2.{floatval1;layout(xfb_buffer=2,xfb_offset=0)first;// The provided index is the same as the block's index.layout(xfb_buffer=1,xfb_offset=0)other;// Compile error, due to changing the buffer index for a block member.};

Each buffer has the concept of a stride. This represents the byte count from the beginning of one captured vertex to the beginning of the next. It is computed by taking the output with the highest xfb_offset value, adding its size to that offset, and then aligning the computed value to the base alignment of the buffer. The buffer's alignment is 4, unless it captures any double-precision values in which case it is 8. This means you do not need to manually pad structures for alignment, as you did with outside shader setting.

The stride for a buffer can also be explicitly set using the xfb_stride layout qualifier. This allows you to add extra space at the end, perhaps to skip data that will not change. A compilation error will result if the stride you specify is:

Too small, given the offsets and computed sizes of the captured data for that buffer.

Not properly aligned. It must be at least 4 byte aligned, and it must be 8 byte aligned if the buffer captures any double-precision values.

Compiler/linker errors will result if you are using Geometry Shader output streams and two outputs from different streams are routed to the same buffer.

Note: When using ARB_enhanced_layouts as an extension (on older hardware), if ARB_transform_feedback3 is not also available, you may only output to a single buffer. You can still use offsets to put space between vertex attribute data, but you cannot set xbf_buffer to any value other than 0.

Shader stage options

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

Tessellation evaluation options

The Tessellation Evaluation Shader (requires GL 4.0 or ARB_tessellation_shader) has a large number of special layout qualifiers that control its behavior.

Geometry shader primitives

Geometry Shaders 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 in and out as a whole.

The value of max_vertices​ defines the maximum number of vertices the geometry shader can every output in a single invocation.

Fragment shader coordinate origin

The gl_FragCoordbuilt-in variable represents the location of the fragment in window-space. There are two layout qualifiers that can affect this. These are specified by redeclaring the predefined variable.

The qualifier origin_upper_left specifies that 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 gl_FragCoord value.

The qualifier pixel_center_integer specifies that the X and Y of 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:

layout(origin_upper_left)invec4gl_FragCoord;

Early fragment tests

By the OpenGL specification, the depth and stencil tests are performed after the fragment shader's execution (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):

layout(early_fragment_tests)in;

Any writes to gl_FragDepth in a shader that defines this will be ignored.