Shading language

Introduction

Godot uses a shading language similar to GLSL ES 3.0. Most datatypes and functions are supported, and the few remaining ones will likely be added over time.

If you are already familiar with GLSL, the Godot Shader Migration Guide is a resource that will help you transition from regular GLSL to Godot's shading language.

Data types

Most GLSL ES 3.0 datatypes are supported:

Type	Description
void	Void datatype, useful only for functions that return nothing.
bool	Boolean datatype, can only contain true or false.
bvec2	Two-component vector of booleans.
bvec3	Three-component vector of booleans.
bvec4	Four-component vector of booleans.
int	Signed scalar integer.
ivec2	Two-component vector of signed integers.
ivec3	Three-component vector of signed integers.
ivec4	Four-component vector of signed integers.
uint	Unsigned scalar integer; can't contain negative numbers.
uvec2	Two-component vector of unsigned integers.
uvec3	Three-component vector of unsigned integers.
uvec4	Four-component vector of unsigned integers.
float	Floating-point scalar.
vec2	Two-component vector of floating-point values.
vec3	Three-component vector of floating-point values.
vec4	Four-component vector of floating-point values.
mat2	2x2 matrix, in column major order.
mat3	3x3 matrix, in column major order.
mat4	4x4 matrix, in column major order.
sampler2D	Sampler type for binding 2D textures, which are read as float.
isampler2D	Sampler type for binding 2D textures, which are read as signed integer.
usampler2D	Sampler type for binding 2D textures, which are read as unsigned integer.
sampler2DArray	Sampler type for binding 2D texture arrays, which are read as float.
isampler2DArray	Sampler type for binding 2D texture arrays, which are read as signed integer.
usampler2DArray	Sampler type for binding 2D texture arrays, which are read as unsigned integer.
sampler3D	Sampler type for binding 3D textures, which are read as float.
isampler3D	Sampler type for binding 3D textures, which are read as signed integer.
usampler3D	Sampler type for binding 3D textures, which are read as unsigned integer.
samplerCube	Sampler type for binding Cubemaps, which are read as float.
samplerCubeArray	Sampler type for binding Cubemap arrays, which are read as float.

Casting

Just like GLSL ES 3.0, implicit casting between scalars and vectors of the same size but different type is not allowed. Casting of types of different size is also not allowed. Conversion must be done explicitly via constructors.

Example:

float a = 2; // invalid
float a = 2.0; // valid
float a = float(2); // valid

Default integer constants are signed, so casting is always needed to convert to unsigned:

int a = 2; // valid
uint a = 2; // invalid
uint a = uint(2); // valid

Members

Individual scalar members of vector types are accessed via the "x", "y", "z" and "w" members. Alternatively, using "r", "g", "b" and "a" also works and is equivalent. Use whatever fits best for your needs.

For matrices, use the m[column][row] indexing syntax to access each scalar, or m[idx] to access a vector by row index. For example, for accessing the y position of an object in a mat4 you use m[3][1].

Constructing

Construction of vector types must always pass:

// The required amount of scalars
vec4 a = vec4(0.0, 1.0, 2.0, 3.0);
// Complementary vectors and/or scalars
vec4 a = vec4(vec2(0.0, 1.0), vec2(2.0, 3.0));
vec4 a = vec4(vec3(0.0, 1.0, 2.0), 3.0);
// A single scalar for the whole vector
vec4 a = vec4(0.0);

Construction of matrix types requires vectors of the same dimension as the matrix. You can also build a diagonal matrix using matx(float) syntax. Accordingly, mat4(1.0) is an identity matrix.

mat2 m2 = mat2(vec2(1.0, 0.0), vec2(0.0, 1.0));
mat3 m3 = mat3(vec3(1.0, 0.0, 0.0), vec3(0.0, 1.0, 0.0), vec3(0.0, 0.0, 1.0));
mat4 identity = mat4(1.0);

Matrices can also be built from a matrix of another dimension. There are two rules:

1. If a larger matrix is constructed from a smaller matrix, the additional rows and columns are set to the values they would have in an identity matrix. 2. If a smaller matrix is constructed from a larger matrix, the top, left submatrix of the larger matrix is used.

mat3 basis = mat3(MODEL_MATRIX);
mat4 m4 = mat4(basis);
mat2 m2 = mat2(m4);

Swizzling

It is possible to obtain any combination of components in any order, as long as the result is another vector type (or scalar). This is easier shown than explained:

vec4 a = vec4(0.0, 1.0, 2.0, 3.0);
vec3 b = a.rgb; // Creates a vec3 with vec4 components.
vec3 b = a.ggg; // Also valid; creates a vec3 and fills it with a single vec4 component.
vec3 b