Shading language

If you are already familiar with GLSL, the 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:

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:

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

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[row][column] 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].

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));

Matrices can also be built from a matrix of another dimension. There are two rules : 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. If a smaller matrix is constructed from a larger matrix, the top, left submatrix of the larger matrix is used.

mat3 basis = mat3(WORLD_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:

It is possible to add precision modifiers to datatypes; use them for uniforms, variables, arguments and varyings:

lowp vec4 a = vec4(0.0, 1.0, 2.0, 3.0); // low precision, usually 8 bits per component mapped to 0-1
mediump vec4 a = vec4(0.0, 1.0, 2.0, 3.0); // medium precision, usually 16 bits or half float
highp vec4 a = vec4(0.0, 1.0, 2.0, 3.0); // high precision, uses full float or integer range (default)

Keep in mind that some architectures (mainly mobile) benefit a lot from this, but are also restricted (conversion between precisions has a cost). Please read the relevant documentation on the target architecture to find out more. In all honesty though, mobile drivers are buggy, so, to stay out of trouble, make simple shaders without specifying precision unless you really need to.

Godot shading language supports the same set of operators as GLSL ES 3.0. Below is the list of them in precedence order:

Flow control

Godot Shading language supports the most common types of flow control:

// if and else
} else {
}
// for loops
for (int i = 0; i < 10; i++) {
}
// while
while (true) {
}

Keep in mind that, in modern GPUs, an infinite loop can exist and can freeze your application (including editor). Godot can’t protect you from this, so be careful not to make this mistake!

Fragment and light functions can use the discard keyword. If used, the fragment is discarded and nothing is written.

Functions

It is possible to define functions in a Godot shader. They use the following syntax:

ret_type func_name(args) {
    return ret_type; // if returning a value
}
// a more specific example:
int sum2(int a, int b) {
    return a + b;
}

You can only use functions that have been defined above (higher in the editor) the function from which you are calling them.

Function arguments can have special qualifiers:

• in: Means the argument is only for reading (default).
• out: Means the argument is only for writing.
• inout: Means the argument is fully passed via reference.

Example below:

void sum2(int a, int b, inout int result) {
}

Varyings

To send data from the vertex to the fragment processor function, varyings are used. They are set for every primitive vertex in the vertex processor, and the value is interpolated for every pixel in the fragment processor.

Certain values are interpolated during the shading pipeline. You can modify how these interpolations are done by using interpolation qualifiers.

shader_type spatial;
varying flat vec3 our_color;
void vertex() {
    our_color = COLOR.rgb;
}
void fragment() {
    ALBEDO = our_color;
}

There are two possible interpolation qualifiers:

Uniforms

shader_type spatial;
uniform float some_value;

You can set uniforms in the editor in the material. Or you can set them through GDScript:

material.set_shader_param("some_value", some_value)

Note

The first argument to set_shader_param is the name of the uniform in the shader. It must match exactly to the name of the uniform in the shader or else it will not be recognized.

Any GLSL type except for void can be a uniform. Additionally, Godot provides optional shader hints to make the compiler understand for what the uniform is used.

shader_type spatial;
uniform vec4 color : hint_color;
uniform vec4 other_color : hint_color = vec4(1.0);

Full list of hints below:

GDScript uses different variable types than GLSL does, so when passing variables from GDScript to shaders, Godot converts the type automatically. Below is a table of the corresponding types:

Note

Be careful when setting shader uniforms from GDScript, no error will be thrown if the type does not match. Your shader will just exhibit undefined behaviour.

As Godot’s 3D engine renders in linear color space, it’s important to understand that textures that are supplied as color (i.e. albedo) need to be specified as such for proper sRGB->linear conversion.

Uniforms can also be assigned default values:

A large number of built-in functions are supported, conforming to GLSL ES 3.0. When vec_type (float), vec_int_type, vec_uint_type, vec_bool_type nomenclature is used, it can be scalar or vector.

Note