luma.gl/docs/api-reference/shadertools/glsl-reference.md

GLSL Reference

This page is an attempt to provide a reference for both GLSL 3.00 ES and GLSL 1.00 ES on a single page, with clear information on what has changed between the two language versions (the differences are often not emphasized in other sources).

Main sources of information for this page comes the Khronos WebGL reference cards and GLSL language specs:

• WebGL2/GLSL 3.00 ES
• WebGL1/GLSL 1.00 ES
• GLSL 3.00 Spec

Types

Basic Types

Type	GLSL 1.00	Description
void		no function return value or empty parameter list
bool		Boolean
int		signed integer
float		floating scalar
vec2, vec3, vec4		floating point vectors
bvec2, bvec3, bvec4		boolean vectors
ivec2, ivec3, ivec4		signed integer vectors
uvec2, uvec3, uvec4	N/A	unsigned integer vectors
mat2, mat3, mat4		2x2, 3x3, 4x4 float matrix
mat2x2, mat2x3, mat2x4	N/A	2x2, 2x3, 2x4 float matrix
mat3x2, mat3x3, mat3x4	N/A	3x2, 3x3, 3x4 float matrix
mat4x2, mat4x3, mat4x4	N/A	4x2, 4x3, 4x4 float matrix

Floating Point Sampler Types

Type	GLSL 1.00	Description
sampler2D		access a 2D (or 3D) texture
sampler3D	N/A	access a 2D or 3D texture
samplerCube		access cube mapped texture
samplerCubeShadow	N/A	access cube map depth texture with comparison
sampler2DShadow	N/A	access 2D depth texture with comparison
sampler2DArray	N/A	access 2D array texture
sampler2DArrayShadow	N/A	access 2D array depth texture with comparison

Signed Integer Sampler Types

Type	GLSL 1.00	Description
isampler2D, isampler3D	N/A	access an integer 2D or 3D texture
isamplerCube	N/A	access integer cube mapped texture
isampler2DArray	N/A	access integer 2D array texture

Unsigned Integer Sampler Types

Type	GLSL 1.00	Description
usampler2D, usampler3D	N/A	access unsigned integer 2D or 3D texture
usamplerCube	N/A	access unsigned integer cube mapped texture
usampler2DArray	N/A	access unsigned integer 2D array texture

Structures and Arrays

Structures

struct type-name {
 members
} struct-name[]; // optional variable declaration, optionally an array

Arrays

float foo[3];

Notes:

• Structures and blocks can be arrays
• Only 1-dimensional arrays supported
• Structure members can be arrays

Qualifiers

Storage Qualifiers [4.3] Variable declarations may be preceded by one storage qualifier. none (Default) local read/write memory, or input parameter const Compile-time constant, or read-only function parameter in centroid in Linkage into a shader from a previous stage out centroid out Linkage out of a shader to a subsequent stage uniform Value does not change across the primitive being processed, uniforms form the linkage between a shader, OpenGL ES, and the application The following interpolation qualifiers for shader outputs and inputs may procede in, centroid in, out, or centroid out. smooth Perspective correct interpolation flat No interpolation

Interface Blocks

Uniform variable declarations can be grouped into named interface blocks, for example:

uniform Transform {
 mat4 ModelViewProjectionMatrix;
 uniform mat3 NormalMatrix; // restatement of qualifier
 float Deformation;
}

Layout Qualifiers (GLSL 3.00)

layout(layout-qualifier) block-declaration
layout(layout-qualifier) in/out/uniform
layout(layout-qualifier) in/out/uniform
 declaration

For all shader stages:

location = integer-constant

Uniform Block Layout Qualifiers (GLSL 3.00)

Layout qualifier identifiers for uniform blocks:

shared, packed, std140, row_major, column_major

Parameter Qualifiers

Input values are copied in at function call time, output values are copied out at function return time.

| none (Default) | same as in | | in | For function parameters passed into a function | | out | For function parameters passed back out of a function, but not initialized for use when passed in | | inout | For function parameters passed both into and out of a function |

Precision and Precision Qualifiers

Any floating point, integer, or sampler declaration can have the type preceded by one of these precision qualifiers:

| highp | Satisfies minimum requirements for the vertex language. | | mediump | Range and precision is between that provided by lowp and highp. | | lowp | Range and precision can be less than mediump, but still represents all color values for any color channel. |

Ranges and precisions for precision qualifiers (FP=floating point):

	FP Range	FP Magnitude Range	FP Precision	Integer Range Signed	Integer Range Unsigned
highp	(−2126 , 2127)	0.0, (2^–126 , 2^127)	Relative 2^–24	[−2^31, 2^31 −1]	[0, 2^32 −1]
mediump	(−214 , 214)	(2^–14 , 2^14)	Relative 2^–10	[−2^15, 2^15 −1]	[0, 2^16 −1]
lowp	(−2, 2)	(2^–8 , 2)	Absolute 26–8	[−2^7, 2^7 −1]	[0, 2^8 −1]

A precision statement establishes a default precision qualifier for subsequent int, float, and sampler declarations, e.g.: precision highp int;

Invariant Qualifiers Examples

| #pragma STDGL invariant(all) | Force all output variables to be invariant | | invariant gl_Position; | Qualify a previously declared variable | | invariant centroid out vec3 Color; | Qualify as part of a variable declaration |

Order of Qualification

When multiple qualifications are present, they must follow a strict order. This order is either:

• invariant, interpolation, storage, precision
• storage, parameter, precision

Preprocessor

Preprocessor Directives

The number sign (#) can be immediately preceded or followed in its line by spaces or horizontal tabs.

# #define #undef #if #ifdef #ifndef #else #elif #endif #error #pragma #extension #version #line

Examples of Preprocessor Directives

• #version 100 in a shader program specifies that the program is written in GLSL ES version 1.00. It is optional. If used, it must occur before anything else in the program other than whitespace or comments.
• #extension extension_name : behavior, where behavior can be require, enable, warn, or disable; and where extension_name is an extension supported by the compiler
• #pragma optimize({on, off}) - enable or disable shader optimization (default on) - GLSL 3.00
• #pragma debug({on, off}) - enable or disable compiling shaders with debug information (default off) - GLSL 3.00

Predefined Macros

Macro	Description
__LINE__	Decimal integer constant that is one more than the number of preceding new-lines in the current
source string
__FILE__	Decimal integer constant that says which source string number is currently being processed
__VERSION__	Decimal integer: 100 or 300
GL_ES	Defined and set to integer 1 if running on an OpenGL-ES Shading Language. Always 1 in WebGL, mainly useful if sharing shader code with non-ES environments.
GL_FRAGMENT_PRECISION_HIGH	1 if highp is supported in the fragment language, else undefined

Built-In Inputs, Outputs, and Constants

Shader programs use special variables and constants to communicate with fixed-function parts of the pipeline.

Notes:

• Output Special Variables may be read back after writing.
• Input Special Variables are read-only.
• All Special Variables have global scope.

Built-in Vertex Shader Variables

Inputs:

Variable	Type	Description	Units or coordinate system
gl_VertexID	int	integer index (GLSL 3.00 only)
gl_InstanceID	int	instance number (GLSL 3.00 only)

Outputs:

Variable	Type	Description	Units or coordinate system
gl_Position	highp vec4	transformed vertex position	clip coordinates
gl_PointSize	mediump float	transformed point size (point rasterization only)	pixels

Built-in Fragment Shader Variables

Inputs:

Variable	Type	Description	Units or coordinate system
gl_FragCoord	mediump vec4	fragment position within frame buffer	window coordinates
gl_FrontFacing	bool	fragment belongs to a front-facing primitive	Boolean
gl_PointCoord	mediump vec2	fragment position within a point (point rasterization only)	0.0 to 1.0 for each component

Outputs (GLSL 1.00 es only):

Variable	Type	Description	Units or coordinate system
gl_FragColor	mediump vec4	fragment color	RGBA color
gl_FragData[n]	mediump vec4	fragment color for color attachment n	RGBA color

Notes:

• In GLSL 3.00 es there are no built-in variables for fragment shader outputs, they are declared by the shader using the out syntax.
• Fragment shaders may write to gl_FragColor or to one or more elements of gl_FragData[], but not both.
• The size of the gl_FragData array is given by the built-in constant gl_MaxDrawBuffers.

Built-In Constants

Constant	Type	WebGL1	WebGL2
gl_MaxVertexAttribs	const mediump int	8	16
gl_MaxVertexUniformVectors	const mediump int	128	256
gl_MaxVaryingVectors	const mediump int	8	N/A
gl_MaxVertexOutputVectors	const mediump int	N/A	16
gl_MaxVertexTextureImageUnits	const mediump int	0	16
gl_MaxCombinedTextureImageUnits	const mediump int	8	32
gl_MaxTextureImageUnits	const mediump int	8	16
gl_MaxFragmentInputVectors	const mediump int	N/A	15
gl_MaxFragmentUniformVectors	const mediump int	16	224
gl_MaxDrawBuffers	const mediump int	1	4
gl_MinProgramTexelOffset	const mediump int	N/A	-8
gl_MaxProgramTexelOffset	const mediump int	N/A	7

Built-in Uniforms

Uniform	Type	Description
gl_DepthRange	gl_DepthRangeParameters	Specifies depth range in window coordinates. If an implementation does not support highp precision in the fragment language, and state is listed as highp, then that state will only be available as mediump in the fragment language.

struct gl_DepthRangeParameters {
  highp float near; // n
  highp float far; // f
  highp float diff; // f - n
};

GLSL Built-in Functions

Common Functions

T can be float, vec2, vec3, vec4. Component-wise operation on vectors.

| T abs(T x) | absolute value | | T sign(T x) | returns -1.0, 0.0, or 1.0 | | T floor(T x) | nearest integer <= x | | T ceil(T x) | | | T fract(T x) | x - floor(x) | | T mod(T x, T y) | modulus | | T mod(T x, float y) | | | T min(T x, T y) | minimum value | | T min(T x, float y) | | | T max(T x, T y) | maximum value | | T max(T x, float y) | | | T clamp(T x, T minVal, T maxVal) | min(max(x, minVal), maxVal) | | T clamp(T x, float minVal, float maxVal) | | | T mix(T x, T y, T a) | linear blend of x and y | | T mix(T x, T y, float a) | | | T step(T edge, T x) | 0.0 if x < edge, else 1.0 | | T step(float edge, T x) | | | T smoothstep(T edge0, T edge1, T x) | clip and smooth | | T smoothstep(float edge0, float edge1, T x) | |

Geometric Functions

T can be float, vec2, vec3, vec4. These functions operate on vectors as vectors, not component-wise.

| float length(T x) | length of vector | | float distance(T p0, T p1) | distance between points | | float dot(T x, T y) | dot product | | vec3 cross(vec3 x, vec3 y) | cross product | | T normalize(T x) | normalize vector to length 1 | | T faceforward(T N, T I, T Nref) | returns N if dot(Nref, I) < 0, else -N | | T reflect(T I, T N) | reflection direction I - 2 * dot(N,I) * N | | T refract(T I, T N, float eta) | refraction vector |

Matrix Functions

Type mat is any matrix type.

| mat matrixCompMult(mat x, mat y) | multiply x by y component-wise |

Vector Relational Functions

Compare x and y component-wise. Sizes of input and return vectors for a particular call must match. Type bvec is bvecn; vec is vecn; ivec is ivecn (where n is 2, 3, or 4). T is the union of vec and ivec.

| bvec lessThan(T x, T y) | x < y | | bvec lessThanEqual(T x, T y) | x <= y | | bvec greaterThan(T x, T y) | x > y | | bvec greaterThanEqual(T x, T y) | x >= y | | bvec equal(T x, T y) | | | bvec equal(bvec x, bvec y) | x == y | | bvec notEqual(T x, T y) | | | bvec notEqual(bvec x, bvec y) | x != y | | bool any(bvec x) | true if any component of x is true | | bool all(bvec x) | true if all components of x are true | | bvec not(bvec x) | logical complement of x |

Texture Lookup Functions

Available in vertex and fragment shaders:

| vec4 texture2D(sampler2D sampler, vec2 coord) | | vec4 texture2DProj(sampler2D sampler, vec3 coord) | | vec4 texture2DProj(sampler2D sampler, vec4 coord) | | vec4 textureCube(samplerCube sampler, vec3 coord) |

Available only in vertex shaders.

| vec4 texture2DLod(sampler2D sampler, vec2 coord, float lod) | | vec4 texture2DProjLod(sampler2D sampler, vec3 coord, float lod) | | vec4 texture2DProjLod(sampler2D sampler, vec4 coord, float lod) | | vec4 textureCubeLod(samplerCube sampler, vec3 coord, float lod) |

Available only in fragment shaders.

| vec4 texture2D(sampler2D sampler, vec2 coord, float bias) | | vec4 texture2DProj(sampler2D sampler, vec3 coord, float bias) | | vec4 texture2DProj(sampler2D sampler, vec4 coord, float bias) | | vec4 textureCube(samplerCube sampler, vec3 coord, float bias) |