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