Язык шейдеров

Введение

Godot использует язык шейдеров схожий с GLSL ES 3.0. Поддерживаются большинство типов данных и функций, а те что остались за бортом, скорее всего будет добавлены в будущем.

Если вы уже знакомы с GLSL, Руководство по переходу на шейдеры Godot поможет вам перейти на них с GLSL.

Типы данных

Поддерживаются большинство типов данных из GLSL ES 3.0:

Тип

Описание

void

Пустой тип данных, используется только для функций которые ничего не возвращают.

bool

Булевый (логический) тип данных, может содержать только "true" или "false".

bvec2

Двух-компонентный вектор из булевых значений.

bvec3

Трех-компонентный вектор из булевых значений.

bvec4

Четырех-компонентный вектор из булевых значений.

int

Целое число со знаком.

ivec2

Двух-компонентный вектор из целых чисел.

ivec3

Трех-компонентный вектор из целых чисел.

ivec4

Четырех-компонентный вектор из целых чисел.

uint

Целое число без знака; не может содержать отрицательных значений.

uvec2

Двух-компонентный вектор состоящий из беззнаковых чисел.

uvec3

Трех-компонентный вектор из беззнаковых целых чисел.

uvec4

Четырех-компонентный вектор из беззнаковых целых чисел.

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, с развёрсткой по столбцу.

mat3

Матрица 3x3, с развёрсткой по столбцу.

mat4

Матрица 4x4, с развёрсткой по столбцу.

sampler2D

Тип сэмплера, для связки 2D текстур, которые читаются через числа с плавающей точкой.

isampler2D

Тип сэмплера, для связки 2D текстур, которые читаются через целые числа.

usampler2D

Тип сэмплера, для связки 2D текстур, которые читаются через целые беззнаковые числа.

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

Тип сэмплера, для связки кубических текстур, которые читаются через числа с плавающей точкой.

Приведение переменных

Так же как и в GLSL ES 3.0, неявное приведение между скалярами и векторами одинакового размера но разного типа не разрешено. Приведение типов разной размерности также не разрешено. Конвертация должны быть произведена явно, через конструкторы.

Пример:

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

Числовые константы это целые числа по умолчанию, так что приведение всегда необходимо при конвертации в без-знаковое целое:

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

Доступ к компонентам

Доступ к каждому отдельному компоненту векторного типа может быть получен через свойства "x", "y", "z" и "w". Кроме этого, можно использовать эквивалентные им "r", "g", "b" и "a". Используйте то, что вы считаете лучшим для ваших задач.

Для матриц, используйте синтаксис m[ряд][колонка] для доступа к отдельному скаляру, или m[индекс] для доступа к целому вектору по индексу ряда. Например, для доступа к позиции объекта по оси y в mat4 используйте m[3][1].

Создание

При создании векторного типа вы всегда должны передавать:

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

Создание матрицы требует векторов той же размерности, что и матрица. Вы можете собрать диагональную матрицу, используя синтаксис matx(float). Соответственно, mat4(1.0) – это единичная матрица.

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

Матрица может также быть построена из матрицы другой размерности. Существует два правила: Если большая матрица была построена из меньшей матрицы, её дополнительные ряды и колонки будут заполнены значениями из единичной матрицы. Если меньшая матрица была построена из большей матрицы - будет использована лишь верхняя, левая часть большей матрицы.

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

Перестановка

Можно получить любую комбинацию компонентов в любом порядке, если в результате получается другой тип вектора (или скаляр). Это легче показать, чем объяснить:

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 = a.bgr; // "b" will be vec3(2.0, 1.0, 0.0).
vec3 b = a.xyz; // Also rgba, xyzw are equivalent.
vec3 b = a.stp; // And stpq (for texture coordinates).
float c = b.w; // Invalid, because "w" is not present in vec3 b.
vec3 c = b.xrt; // Invalid, mixing different styles is forbidden.
b.rrr = a.rgb; // Invalid, assignment with duplication.
b.bgr = a.rgb; // Valid assignment. "b"'s "blue" component will be "a"'s "red" and vice versa.

Точность

Можно добавить модификаторы точности к типам данных; используйте их для униформ, переменных, аргументов и вариаций:

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)

Использование более низкой точности для некоторых операций может ускорить вычисление (за счет меньшей точности). Это редко требуется в функции процессора вершин (где большую часть времени требуется полная точность), но часто полезно в процессоре фрагментов.

Some architectures (mainly mobile) can benefit significantly from this, but there are downsides such as the additional overhead of conversion between precisions. Refer to the documentation of the target architecture for further information. In many cases, mobile drivers cause inconsistent or unexpected behavior and it is best to avoid specifying precision unless necessary.

Массивы

Arrays are containers for multiple variables of a similar type. Note: As of Godot 3.2, only local and varying arrays have been implemented.

Local arrays

Local arrays are declared in functions. They can use all of the allowed datatypes, except samplers. The array declaration follows a C-style syntax: [const] + [precision] + typename + identifier + [array size].

void fragment() {
    float arr[3];
}

They can be initialized at the beginning like:

float float_arr[3] = float[3] (1.0, 0.5, 0.0); // first constructor

int int_arr[3] = int[] (2, 1, 0); // second constructor

vec2 vec2_arr[3] = { vec2(1.0, 1.0), vec2(0.5, 0.5), vec2(0.0, 0.0) }; // third constructor

bool bool_arr[] = { true, true, false }; // fourth constructor - size is defined automatically from the element count

You can declare multiple arrays (even with different sizes) in one expression:

float a[3] = float[3] (1.0, 0.5, 0.0),
b[2] = { 1.0, 0.5 },
c[] = { 0.7 },
d = 0.0,
e[5];

To access an array element, use the indexing syntax:

float arr[3];

arr[0] = 1.0; // setter

COLOR.r = arr[0]; // getter

Arrays also have a built-in function .length() (not to be confused with the built-in length() function). It doesn't accept any parameters and will return the array's size.

float arr[] = { 0.0, 1.0, 0.5, -1.0 };
for (int i = 0; i < arr.length(); i++) {
    // ...
}

Примечание

If you use an index below 0 or greater than array size - the shader will crash and break rendering. To prevent this, use length(), if, or clamp() functions to ensure the index is between 0 and the array's length. Always carefully test and check your code. If you pass a constant expression or a simple number, the editor will check its bounds to prevent this crash.

Константы

Use the const keyword before the variable declaration to make that variable immutable, which means that it cannot be modified. All basic types, except samplers can be declared as constants. Accessing and using a constant value is slightly faster than using a uniform. Constants must be initialized at their declaration.

const vec2 a = vec2(0.0, 1.0);
vec2 b;

a = b; // invalid
b = a; // valid

Constants cannot be modified and additionally cannot have hints, but multiple of them (if they have the same type) can be declared in a single expression e.g

const vec2 V1 = vec2(1, 1), V2 = vec2(2, 2);

Similar to variables, arrays can also be declared with const.

const float arr[] = { 1.0, 0.5, 0.0 };

arr[0] = 1.0; // invalid

COLOR.r = arr[0]; // valid

Constants can be declared both globally (outside of any function) or locally (inside a function). Global constants are useful when you want to have access to a value throughout your shader that does not need to be modified. Like uniforms, global constants are shared between all shader stages, but they are not accessible outside of the shader.

shader_type spatial;

const float PI = 3.14159265358979323846;

Операторы

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

Приоритет

Класс

Оператор

1 (highest)

parenthetical grouping

()

2

унарный (unary)

+, -, !, ~

3

мультипликативный (multiplicative)

/, *, %

4

аддитивный (additive)

+, -

5

bit-wise shift

<<, >>

6

реляционный (relational)

<, >, <=, >=

7

равенства (equality)

==, !=

8

bit-wise AND

&

9

bit-wise exclusive OR

^

10

bit-wise inclusive OR

|

11

logical AND

&&

12 (lowest)

logical inclusive OR

||

Flow control

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

// if and else
if (cond) {

} else {

}

// switch
switch(i) { // signed integer expression
    case -1:
        break;
    case 0:
        return; // break or return
    case 1: // pass-through
    case 2:
        break;
    //...
    default: // optional
        break;
}

// for loops
for (int i = 0; i < 10; i++) {

}

// while
while (true) {

}

// do while
do {

} 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!

Предупреждение

При экспорте проекта GLES2 в HTML5 будет использоваться WebGL 1.0. WebGL 1.0 не поддерживает динамические циклы, поэтому использующие их шейдеры там работать не будут.

Отбрасывание

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

Функции

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) {
    result = a + b;
}

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.

shader_type spatial;

varying vec3 some_color;
void vertex() {
    some_color = NORMAL; // Make the normal the color.
}

void fragment() {
    ALBEDO = some_color;
}

Varying can also be an array:

shader_type spatial;

varying float var_arr[3];
void vertex() {
    var_arr[0] = 1.0;
    var_arr[1] = 0.0;
}

void fragment() {
    ALBEDO = vec3(var_arr[0], var_arr[1], var_arr[2]); // red color
}

Interpolation qualifiers

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:

Квалификатор

Описание

flat

The value is not interpolated.

smooth

The value is interpolated in a perspective-correct fashion. This is the default.

Униформы

Passing values to shaders is possible. These are global to the whole shader and are called uniforms. When a shader is later assigned to a material, the uniforms will appear as editable parameters in it. Uniforms can't be written from within the shader.

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)

Примечание

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 float amount : hint_range(0, 1);
uniform vec4 other_color : hint_color = vec4(1.0);

It's important to understand that textures that are supplied as color require hints for proper sRGB->linear conversion (i.e. hint_albedo), as Godot's 3D engine renders in linear color space.

Full list of hints below:

Тип

Подсказка

Описание

vec4

hint_color

Used as color

int, float

hint_range(min, max[, step])

Used as range (with min/max/step)

sampler2D

hint_albedo

Used as albedo color, default white

sampler2D

hint_black_albedo

Used as albedo color, default black

sampler2D

hint_normal

Used as normalmap

sampler2D

hint_white

As value, default to white.

sampler2D

hint_black

As value, default to black

sampler2D

hint_aniso

As flowmap, default to right.

GDScript использует переменные, отличающиеся от GLSL, поэтому при передаче переменных из GDScript в шейдер Godot автоматически преобразует тип. В таблице ниже указаны соответствующие типы:

GDScript type

GLSL type

bool

bool

int

int

float

float

Vector2

vec2

Vector3

vec3

Color

vec4

Transform

mat4

Transform2D

mat4

Примечание

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 behavior.

Uniforms can also be assigned default values:

shader_type spatial;

uniform vec4 some_vector = vec4(0.0);
uniform vec4 some_color : hint_color = vec4(1.0);

Built-in variables

A large number of built-in variables are available, like UV, COLOR and VERTEX. What variables are available depends on the type of shader (spatial, canvas_item or particle) and the function used (vertex, fragment or light). For a list of the build-in variables that are available, please see the corresponding pages:

Built-in functions

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.

Примечание

For a list of the functions that are not available in the GLES2 backend, please see the Differences between GLES2 and GLES3 doc.

Функция

Описание

vec_type radians (vec_type degrees)

Convert degrees to radians

vec_type degrees (vec_type radians)

Преобразование радианов в градусы

vec_type sin (vec_type x)

Синус

vec_type cos (vec_type x)

Косинус

vec_type tan (vec_type x)

Тангенс

vec_type asin (vec_type x)

Arcsine

vec_type acos (vec_type x)

Arccosine

vec_type atan (vec_type y_over_x)

Arctangent

vec_type atan (vec_type y, vec_type x)

Arctangent to convert vector to angle

vec_type sinh (vec_type x)

Hyperbolic sine

vec_type cosh (vec_type x)

Hyperbolic cosine

vec_type tanh (vec_type x)

Hyperbolic tangent

vec_type asinh (vec_type x)

Inverse hyperbolic sine

vec_type acosh (vec_type x)

Inverse hyperbolic cosine

vec_type atanh (vec_type x)

Inverse hyperbolic tangent

vec_type pow (vec_type x, vec_type y)

Power (undefined if x < 0 or if x = 0 and y <= 0)

vec_type exp (vec_type x)

Base-e exponential

vec_type exp2 (vec_type x)

Base-2 exponential

vec_type log (vec_type x)

Natural logarithm

vec_type log2 (vec_type x)

Base-2 logarithm

vec_type sqrt (vec_type x)

Square root

vec_type inversesqrt (vec_type x)

Inverse square root

vec_type abs (vec_type x)

Абсолют

ivec_type abs (ivec_type x)

Абсолют

vec_type sign (vec_type x)

Знак

ivec_type sign (ivec_type x)

Знак

vec_type floor (vec_type x)

Пол

vec_type round (vec_type x)

Округление

vec_type roundEven (vec_type x)

Round to the nearest even number

vec_type trunc (vec_type x)

Truncation

vec_type ceil (vec_type x)

Ceil

vec_type fract (vec_type x)

Дробный

vec_type mod (vec_type x, vec_type y)

Остаток

vec_type mod (vec_type x , float y)

Остаток

vec_type modf (vec_type x, out vec_type i)

Fractional of x, with i as integer part

vec_type min (vec_type a, vec_type b)

Минимум

vec_type max (vec_type a, vec_type b)

Максимум

vec_type clamp (vec_type x, vec_type min, vec_type max)

Clamp to min..max

float mix (float a, float b, float c)

Linear interpolate

vec_type mix (vec_type a, vec_type b, float c)

Linear interpolate (scalar coefficient)

vec_type mix (vec_type a, vec_type b, vec_type c)

Linear interpolate (vector coefficient)

vec_type mix (vec_type a, vec_type b, bvec_type c)

Linear interpolate (boolean-vector selection)

vec_type step (vec_type a, vec_type b)

b[i] < a[i] ? 0.0 : 1.0

vec_type step (float a, vec_type b)

b[i] < a ? 0.0 : 1.0

vec_type smoothstep (vec_type a, vec_type b, vec_type c)

Hermite interpolate

vec_type smoothstep (float a, float b, vec_type c)

Hermite interpolate

bvec_type isnan (vec_type x)

Returns true if scalar or vector component is NaN

bvec_type isinf (vec_type x)

Returns true if scalar or vector component is INF

ivec_type floatBitsToInt (vec_type x)

Float->Int bit copying, no conversion

uvec_type floatBitsToUint (vec_type x)

Float->UInt bit copying, no conversion

vec_type intBitsToFloat (ivec_type x)

Int->Float bit copying, no conversion

vec_type uintBitsToFloat (uvec_type x)

UInt->Float bit copying, no conversion

float length (vec_type x)

Vector length

float distance (vec_type a, vec_type b)

Расстояние между векторами, т.е. length(a - b)

float dot (vec_type a, vec_type b)

Скалярное произведение

vec3 cross (vec3 a, vec3 b)

Векторное произведение

vec_type normalize (vec_type x)

Normalize to unit length

vec3 reflect (vec3 I, vec3 N)

Отражение

vec3 refract (vec3 I, vec3 N, float eta)

Преломление

vec_type faceforward (vec_type N, vec_type I, vec_type Nref)

If dot(Nref, I) < 0, return N, otherwise –N

mat_type matrixCompMult (mat_type x, mat_type y)

Matrix component multiplication

mat_type outerProduct (vec_type column, vec_type row)

Matrix outer product

mat_type transpose (mat_type m)

Transpose matrix

float determinant (mat_type m)

Matrix determinant

mat_type inverse (mat_type m)

Inverse matrix

bvec_type lessThan (vec_type x, vec_type y)

Bool vector comparison on < int/uint/float vectors

bvec_type greaterThan (vec_type x, vec_type y)

Bool vector comparison on > int/uint/float vectors

bvec_type lessThanEqual (vec_type x, vec_type y)

Bool vector comparison on <= int/uint/float vectors

bvec_type greaterThanEqual (vec_type x, vec_type y)

Bool vector comparison on >= int/uint/float vectors

bvec_type equal (vec_type x, vec_type y)

Bool vector comparison on == int/uint/float vectors

bvec_type notEqual (vec_type x, vec_type y)

Bool vector comparison on != int/uint/float vectors

bool any (bvec_type x)

Any component is true

bool all (bvec_type x)

All components are true

bvec_type not (bvec_type x)

Invert boolean vector

ivec2 textureSize (sampler2D_type s, int lod)

Get the size of a 2D texture

ivec3 textureSize (sampler2DArray_type s, int lod)

Get the size of a 2D texture array

ivec3 textureSize (sampler3D s, int lod)

Get the size of a 3D texture

ivec2 textureSize (samplerCube s, int lod)

Get the size of a cubemap texture

vec4_type texture (sampler2D_type s, vec2 uv [, float bias])

Perform a 2D texture read

vec4_type texture (sampler2DArray_type s, vec3 uv [, float bias])

Perform a 2D texture array read

vec4_type texture (sampler3D_type s, vec3 uv [, float bias])

Perform a 3D texture read

vec4 texture (samplerCube s, vec3 uv [, float bias])

Perform a cubemap texture read

vec4_type textureProj (sampler2D_type s, vec3 uv [, float bias])

Perform a 2D texture read with projection

vec4_type textureProj (sampler2D_type s, vec4 uv [, float bias])

Perform a 2D texture read with projection

vec4_type textureProj (sampler3D_type s, vec4 uv [, float bias])

Perform a 3D texture read with projection

vec4_type textureLod (sampler2D_type s, vec2 uv, float lod)

Perform a 2D texture read at custom mipmap

vec4_type textureLod (sampler2DArray_type s, vec3 uv, float lod)

Perform a 2D texture array read at custom mipmap

vec4_type textureLod (sampler3D_type s, vec3 uv, float lod)

Perform a 3D texture read at custom mipmap

vec4 textureLod (samplerCube s, vec3 uv, float lod)

Perform a 3D texture read at custom mipmap

vec4_type textureProjLod (sampler2D_type s, vec3 uv, float lod)

Perform a 2D texture read with projection/LOD

vec4_type textureProjLod (sampler2D_type s, vec4 uv, float lod)

Perform a 2D texture read with projection/LOD

vec4_type textureProjLod (sampler3D_type s, vec4 uv, float lod)

Perform a 3D texture read with projection/LOD

vec4_type texelFetch (sampler2D_type s, ivec2 uv, int lod)

Fetch a single texel using integer coordinates

vec4_type texelFetch (sampler2DArray_type s, ivec3 uv, int lod)

Fetch a single texel using integer coordinates

vec4_type texelFetch (sampler3D_type s, ivec3 uv, int lod)

Fetch a single texel using integer coordinates

vec_type dFdx (vec_type p)

Derivative in x using local differencing

vec_type dFdy (vec_type p)

Derivative in y using local differencing

vec_type fwidth (vec_type p)

Sum of absolute derivative in x and y