Difference between revisions of "Layout Qualifier (GLSL)"

From OpenGL.org
Jump to: navigation, search
m (Linking to layout qualifier)
(Formatting and reconfiguring)
Line 1: Line 1:
Uniforms, buffer, inputs, and outputs can also have layout qualifiers. Different stages have their own layout qualifiers, and the different types can have their own as well.
+
A number of OpenGL 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:
 
All layout qualifiers are defined with a common syntax:
Line 5: Line 5:
 
  layout({{param|qualifier1}}, {{param|qualifier2}} = ''value'', ...) ''variable definition''
 
  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.
  
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. These values must be literals.
+
In the above, ''value'' must be an integer literal, unless you are using OpenGL 4.4/{{extref|enhanced_layouts}}, in which case it must be an [[Integral Constant Expression]] (aka: a compile-time constant).
  
Some layout qualifiers can apply to all inputs or outputs. In which case, the ''variable definition'' can just be {{code|in}} or {{code|out}}.
+
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}}.
  
=== Vertex shader attribute index ===
+
In OpenGL 4.2/{{extref|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.
 +
 
 +
== Vertex shader attribute index ==
  
 
Vertex shader inputs can specify the attribute index that the particular input uses. This is done with this syntax:
 
Vertex shader inputs can specify the attribute index that the particular input uses. This is done with this syntax:
Line 26: Line 29:
 
This will allocate the attribute indices 2, 3, 4, and 5.
 
This will allocate the attribute indices 2, 3, 4, and 5.
  
=== Tessellation control output vertex count ===
+
== Fragment shader buffer output ==
{{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 [[Type Qualifier (GLSL)#Built-in_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''.
+
 
+
=== Fragment shader buffer output ===
+
 
+
 
Fragment shader outputs can specify the buffer index that a particular output writes to. This uses the same syntax as vertex shader attributes:
 
Fragment shader outputs can specify the buffer index that a particular output writes to. This uses the same syntax as vertex shader attributes:
  
Line 111: Line 42:
 
Again, this allows one to forgo the use of {{apifunc|glBindFragDataLocationIndexed}}.
 
Again, this allows one to forgo the use of {{apifunc|glBindFragDataLocationIndexed}}.
  
=== Program separation linkage ===
+
== Program separation linkage ==
 
{{infobox feature
 
{{infobox feature
 
| name = Program Separation
 
| name = Program Separation
Line 140: Line 71:
 
{{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.}}
 
{{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.}}
  
=== Interface block memory layout ===
+
=== Interface member locations ===
{{main|GLSL_Interface_Block#Memory_layout}}
+
{{infobox feature
 +
| name = Interface member locations
 +
| core = 4.4
 +
| core_version = {{extref|enhanced_layouts}}
 +
}}
 +
{{todo}}
  
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.
+
== Interface member components ==
 +
{{infobox feature
 +
| name = Interface member locations
 +
| core = 4.4
 +
| core_version = {{extref|enhanced_layouts}}
 +
}}
 +
{{todo}}
  
=== Binding points ===
+
== Binding points ==
 
{{infobox feature
 
{{infobox feature
 
| name = Binding points
 
| name = Binding points
Line 164: Line 106:
 
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 only sets the initial value; source code can modify it later.
 
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 only sets the initial value; source code can modify it later.
  
=== Image formats ===
+
== Image formats ==
 
{{infobox feature
 
{{infobox feature
 
| name = Forced early fragment tests
 
| name = Forced early fragment tests
Line 177: Line 119:
 
{{div col end}}
 
{{div col end}}
  
=== Atomic counter storage ===
+
== Atomic counter storage ==
 
{{infobox feature
 
{{infobox feature
 
| name = Atomic Counters
 
| name = Atomic Counters
Line 189: Line 131:
 
{{snippet|:Atomic counter layout parameters}}
 
{{snippet|:Atomic counter layout parameters}}
  
=== Explicit uniform location ===
+
== 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
 
{{infobox feature
 
| name = Explicit Uniform Location
 
| name = Explicit Uniform Location
Line 195: Line 142:
 
| core_extension = {{extref|explicit_uniform_location}}
 
| core_extension = {{extref|explicit_uniform_location}}
 
}}
 
}}
 +
{{todo}}
 +
 +
== Shader stage options ==
 +
 +
Many [[Shader|shader stages]] have options that control how some aspect of how they function. 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 [[Type Qualifier (GLSL)#Built-in_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]]
 
[[Category:OpenGL Shading Language]]

Revision as of 03:54, 1 August 2013

A number of OpenGL 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.

In the above, value must be an integer literal, unless you are using OpenGL 4.4/ARB_enhanced_layouts, in which case it must be an Integral Constant Expression (aka: a compile-time constant).

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/ARB_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.

Vertex shader attribute index

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

layout(location = 2) in vec3 values[4];

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

Fragment shader buffer output

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 glBindFragDataLocation. Similarly, the values in the shader override the values provided by this function.

For 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 glBindFragDataLocationIndexed.

Program separation linkage

Program Separation
Core in version 4.5
Core since version 4.1
Core ARB extension ARB_separate_shader_objects

Normally, when linking shaders into a program, the output variables from one stage are matched with the input variables from another stage. However, when linking programs together dynamically in a program pipeline object, an alternative method of linking is allowed. The name linking is allowed, but so is linking by location.

Input and output variables for communication between shader stages (ie: not vertex shader input or fragment shader output) can have a location associated with them. This is used instead of a name when linking between two shader stages (whether statically or dynamically via a program pipeline). This is provided by the layout location​ qualifier.

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

layout(location = 0) out vec4 color;
layout(location = 1) out vec2 texCoord;
layout(location = 2) out vec3 normal;

Normally, the fragment shader would have to use exactly those names. This is not required when using separate programs. If an output has a location specified, the next stage can provide that location with a different name. So a matching fragment shader could look like this:

layout(location = 0) in vec4 diffuseAlbedo;
layout(location = 1) in vec2 texCoord
layout(location = 2) in vec3 cameraSpaceNormal;
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.

Interface member locations

Interface member locations
Core in version 4.5
Core since version 4.4

Interface member components

Interface member locations
Core in version 4.5
Core since version 4.4

Binding points

Binding points
Core in version 4.5
Core since version 4.2
Core ARB extension ARB_shading_language_420pack

Uniform and shader storage blocks, and all opaque types have a value 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 bound in the shader when using GLSL 4.20 or the GL_ARB_shading_language_420pack extension. This is done by using the "binding" syntax:

layout(binding = 3) uniform sampler2D mainTexture;
layout(binding = 1, std140) uniform MainBlock
{
  vec3 data;
};

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 only sets the initial value; source code can modify it later.

Image formats

Forced early fragment tests
Core in version 4.5
Core since version 4.2
Core ARB extension ARB_shader_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:

  • Floating-point layout image formats:
    • rgba32f
    • rgba16f
    • rg32f
    • rg16f
    • r11f_g11f_b10f
    • r32f
    • r16f
    • rgba16
    • rgb10_a2
    • rgba8
    • rg16
    • rg8
    • r16
    • r8
    • rgba16_snorm
    • rgba8_snorm
    • rg16_snorm
    • rg8_snorm
    • r16_snorm
    • r8_snorm
  • Signed integer layout image formats:
    • rgba32i
    • rgba16i
    • rgba8i
    • rg32i
    • rg16i
    • rg8i
    • r32i
    • r16i
    • r8i
  • Unsigned integer layout image formats:
    • rgba32ui
    • rgba16ui
    • rgb10_a2ui
    • rgba8ui
    • rg32ui
    • rg16ui
    • rg8ui
    • r32ui
    • r16ui
    • r8ui

Atomic counter storage

Atomic Counters
Core in version 4.5
Core since version 4.2
Core ARB extension ARB_shader_atomic_counters

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.


V · E

Atomic counter layout parameters

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

Explicit Uniform Location
Core in version 4.5
Core since version 4.3
Core ARB extension ARB_explicit_uniform_location

Shader stage options

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

Tessellation control output vertex count

Tessellation Control Shader
Core in version 4.5
Core since version 4.0
Core ARB extension ARB_tessellation_shader

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

layout(vertices = vertex_count​) out;

The TCS will be invoked once for each vertex output.

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.

 layout(primitive type​) in;
 layout(primitive type​, max_vertices = integer value) out;

For inputs, the primitive type​ can be any of the following:

  • points
  • lines
  • lines_adjacency
  • triangles
  • triangles_adjacency

For outputs, the primitive type​ can be any of the following:

  • points
  • line_strip
  • triangle_strip

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_FragCoord​ 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 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) in vec4 gl_FragCoord;

Early fragment tests

Forced early fragment tests
Core in version 4.5
Core since version 4.2
Core ARB extension ARB_shader_image_load_store

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.