Шейдеры CanvasItem

Шейдеры CanvasItem используются для отрисовки всех 2D-элементов в Godot. К ним относятся все узлы, наследующие от CanvasItems, и все элементы графического интерфейса.

CanvasItem shaders contain fewer built-in variables and functionality than Spatial shaders, but they maintain the same basic structure with vertex, fragment, and light processor functions.

Режимы визуализации

Режим рендеринга	Описание
blеnd_mix	Режим смешивания (альфа как прозрачность), по умолчанию.
blеnd_add	Аддитивный режим наложения.
blеnd_sub	Режим наложения с вычитанием.
blеnd_mul	Режим наложения с умножением.
blеnd_premul_alpha	Режим наложения альфа с предварительным умножением.
blend_disabled	Отключить смешивание, значения (в том числе альфа) записываются как есть.
unshadеd	В результате получается просто альбедо. Никакого освещения/затенения в материале не происходит.
lіght_only	Only draw on light pass.
skіp_vertex_transform	`VERTEX` needs to be transformed manually in the `vertex()` function.
wоrld_vertex_coords	`VERTEX` is modified in world coordinates instead of local.

Встроенные функции

Values marked as in are read-only. Values marked as out can optionally be written to and will not necessarily contain sensible values. Values marked as inout provide a sensible default value, and can optionally be written to. Samplers cannot be written to so they are not marked.

Not all built-ins are available in all processing functions. To access a vertex built-in from the fragment() function, you can use a varying. The same applies for accessing fragment built-ins from the light() function.

Глобальные встроенные функции

Глобальные встроенные модули доступны везде, включая пользовательские функции.

Встроенный	Описание
in float TIME	Global time since the engine has started, in seconds. It repeats after every `3,600` seconds (which can be changed with the rollover setting). It's affected by time_scale but not by pausing. If you need a `TIME` variable that is not affected by time scale, add your own global shader uniform and update it each frame.
in float PI	A `PI` constant (`3.141592`). A ratio of a circle's circumference to its diameter and amount of radians in half turn.
in float TAU	Константа `TAU` (`6.283185`). Эквивалент `PI * 2` и количество радианов в полном обороте.
in float E	An `E` constant (`2.718281`). Euler's number and a base of the natural logarithm.

Вершинные встроенные константы

Данные вершин (VERTEX) представлены в локальном пространстве (пиксельные координаты, относительно начала координат Node2D). Если не записывать эти значения, то они не будут изменены и будут переданы в том виде, в котором пришли.

Пользователь может отключить встроенную модель для преобразования мира (мир на экран и проецирование все равно произойдет позже) и сделать это вручную с помощью следующего кода:

shader_type canvas_item;
render_mode skip_vertex_transform;

void vertex() {

    VERTEX = (MODEL_MATRIX * vec4(VERTEX, 0.0, 1.0)).xy;
}

Other built-ins, such as UV and COLOR, are also passed through to the fragment() function if not modified.

For instancing, the INSTANCE_CUSTOM variable contains the instance custom data. When using particles, this information is usually:

x: Угол поворота в радианах.
y: Phase during lifetime (0.0 to 1.0).
z: Кадр анимации.

Встроенный	Описание
mat4 MODEL_MATRIX	Трансформация локального пространства в мировое. Мировое пространство — это координаты, которые вы обычно используете в редакторе.
in mat4 CANVAS_MATRIX	World space to canvas space transform. In canvas space the origin is the upper-left corner of the screen and coordinates ranging from `(0.0, 0.0)` to viewport size.
in mat4 SCREEN_MATRIX	Canvas space to clip space. In clip space coordinates ranging from `(-1.0, -1.0)` to `(1.0, 1.0).`
in int INSTANCE_ID	Instance ID for instancing.
in vec4 INSTANCE_CUSTOM	Пользовательские данные экземпляра.
in bool AT_LIGHT_PASS	Всегда `false`.
in vec2 TEXTURE_PIXEL_SIZE	Нормализованный размер пикселя 2D-текстуры по умолчанию. Для Sprite2D с текстурой размером 64x32px, TEXTURE_PIXEL_SIZE = `vec2(1/64, 1/32)`
inout vec2 VERTEX	Vertex position, in local space.
in int VERTEX_ID	Индекс текущей вершины в буфере вершин.
inout vec2 UV	Normalized texture coordinates. Range from `0.0` to `1.0`.
inout vec4 COLOR	Color from vertex primitive multiplied by CanvasItem's modulate multiplied by CanvasItem's self_modulate.
inout float POINT_SIZE	Размер точки для отрисовки.
in vec4 CUSTOM0	Custom value from vertex primitive.
in vec4 CUSTOM1	Custom value from vertex primitive.

Фрагментные встроенные константы

COLOR and TEXTURE

The built-in variable COLOR is used for a few things:

In the vertex() function, COLOR contains the color from the vertex primitive multiplied by the CanvasItem's modulate multiplied by the CanvasItem's self_modulate.

In the fragment() function, the input value COLOR is that same value multiplied by the color from the default TEXTURE (if present).

In the fragment() function, COLOR is also the final output.

Certain nodes (for example, Sprite2D) display a texture by default, for example texture. When using a custom fragment() function, you have a few options on how to sample this texture.

To read only the contents of the default texture, ignoring the vertex COLOR:

void fragment() {
  COLOR = texture(TEXTURE, UV);
}

To read the contents of the default texture multiplied by vertex COLOR:

void fragment() {
  // Equivalent to an empty fragment() function, since COLOR is also the output variable.
  COLOR = COLOR;
}

To read only the vertex COLOR in fragment(), ignoring the main texture, you must pass COLOR as a varying, then read it in fragment():

varying vec4 vertex_color;
void vertex() {
  vertex_color = COLOR;
}
void fragment() {
  COLOR = vertex_color;
}

NORMAL

Similarly, if a normal map is used in the CanvasTexture, Godot uses it by default and assigns its value to the built-in NORMAL variable. If you are using a normal map meant for use in 3D, it will appear inverted. In order to use it in your shader, you must assign it to the NORMAL_MAP property. Godot will handle converting it for use in 2D and overwriting NORMAL.

NORMAL_MAP = texture(NORMAL_TEXTURE, UV).rgb;

Встроенный	Описание
vec4 FRAGCOORD	Coordinate of pixel center. In screen space. `xy` specifies position in viewport. Upper-left of the viewport is the origin, `(0.0, 0.0)`.
in vec2 SCREEN_PIXEL_SIZE	Размер отдельных пикселей. Равно обратному разрешению.
vec2 POINT_COORD	Координаты для отрисовки точек.
sampler2D TEXTURE	2D текстура по умолчанию.
in vec2 TEXTURE_PIXEL_SIZE	Normalized pixel size of default 2D texture. For a Sprite2D with a texture of size 64x32px, `TEXTURE_PIXEL_SIZE` = `vec2(1/64, 1/32)`
in bool AT_LIGHT_PASS	Всегда `false`.
sampler2D SPECULAR_SHININESS_TEXTURE	Текстура зеркального блеска этого объекта.
in vec4 SPECULAR_SHININESS	Цвет зеркального блеска, взятый из текстуры.
vec2 UV	UV from the `vertex()` function.
vec2 SCREEN_UV	Экранная UV-координата для текущего пикселя.
sampler2D SCREEN_TEXTURE	Убрано в Godot 4. Вместо этого используйте `sampler2D` с `hint_screen_texture`.
inout vec3 NORMAL	Normal read from `NORMAL_TEXTURE`. Writable.
sampler2D NORMAL_TEXTURE	2D текстура нормали по умолчанию.
out vec3 NORMAL_MAP	Configures normal maps meant for 3D for use in 2D. If used, overrides `NORMAL`.
out float NORMAL_MAP_DEPTH	Normal map depth for scaling.
inout vec2 VERTEX	Позиция пикселя в экранном пространстве.
inout vec2 SHADOW_VERTEX	Аналогичен `VERTEX`, но может быть записан для изменения теней.
inout vec3 LIGHT_VERTEX	Аналогичен `VERTEX`, но может быть записан для изменения освещения. Компонент Z представляет собой высоту.
inout vec4 COLOR	`COLOR` from the `vertex()` function multiplied by the `TEXTURE` color. Also output color value.

Встроенные константы шейдеров света

Функции светового процессора в Godot 4.x работают иначе, чем в Godot 3.x. В Godot 4.x всё освещение выполняется во время обычного прохода отрисовки. Другими словами, Godot больше не рисует объект заново для каждого освещения.

Use the unshaded render mode if you do not want the light() function to run. Use the light_only render mode if you only want to see the impact of lighting on an object; this can be useful when you only want the object visible where it is covered by light.

If you define a light() function it will replace the built-in light function, even if your light function is empty.

Ниже приведён пример шейдера света (light), который учитывает карту нормалей CanvasItem:

void light() {
  float cNdotL = max(0.0, dot(NORMAL, LIGHT_DIRECTION));
  LIGHT = vec4(LIGHT_COLOR.rgb * COLOR.rgb * LIGHT_ENERGY * cNdotL, LIGHT_COLOR.a);
}

Встроенный	Описание
vec4 FRAGCOORD	Coordinate of pixel center. In screen space. `xy` specifies position in viewport. Upper-left of the viewport is the origin, `(0.0, 0.0)`.
in vec3 NORMAL	Input normal.
vec4 COLOR	Input color. This is the output of the `fragment()` function.
vec2 UV	UV from the `vertex()` function, equivalent to the UV in the `fragment()` function.
sampler2D TEXTURE	Текущая текстура, используемая для CanvasItem.
in vec2 TEXTURE_PIXEL_SIZE	Normalized pixel size of `TEXTURE`. For a Sprite2D with a `TEXTURE` of size `64x32` pixels, TEXTURE_PIXEL_SIZE = `vec2(1/64, 1/32)`
vec2 SCREEN_UV	Экранная UV-координата для текущего пикселя.
vec2 POINT_COORD	UV for Point Sprite.
in vec4 LIGHT_COLOR	Color of the Light2D. If the light is a PointLight2D, multiplied by the light's texture.
in float LIGHT_ENERGY	Energy multiplier of the Light2D.
in vec3 LIGHT_POSITION	Position of the Light2D in screen space. If using a DirectionalLight2D this is always `(0.0, 0.0, 0.0)`.
in vec3 LIGHT_DIRECTION	Direction of the Light2D in screen space.
in bool LIGHT_IS_DIRECTIONAL	`true` if this pass is a DirectionalLight2D.
in vec3 LIGHT_VERTEX	Pixel position, in screen space as modified in the `fragment()` function.
inout vec4 LIGHT	Output color for this Light2D.
in vec4 SPECULAR_SHININESS	Зеркальный блеск, заданный текстурой объекта.
out vec4 SHADOW_MODULATE	Умножение теней, отбрасываемые в этой точке, на этот цвет.

SDF функции

There are a few additional functions implemented to sample an automatically generated Signed Distance Field texture. These functions available for the fragment() and light() functions of CanvasItem shaders. Custom functions may also use them as long as they called from supported functions.

Поле расстояния со знаком генерируется из узлов LightOccluder2D, присутствующих в сцене с включенным свойством SDF Collision (по умолчанию). Дополнительную информацию см. в документации 2D lights and shadows.

Функция	Описание
float texture_sdf (vec2 sdf_pos)	Выполняет поиск текстуры SDF.
vec2 texture_sdf_normal (vec2 sdf_pos)	Вычисляет нормаль из текстуры SDF.
vec2 sdf_to_screen_uv (vec2 sdf_pos)	Converts an SDF to screen UV.
vec2 screen_uv_to_sdf (vec2 uv)	Converts screen UV to an SDF.