Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

Шейдери CanvasItem

Шейдери CanvasItem використовуються для малювання всіх 2D-елементів у Godot. До них належать усі вузли, які успадковуються від CanvasItems, і всі елементи GUI.

Шейдери CanvasItem містять менше вбудованих змінних і функцій, ніж Spatial shaders, але вони зберігають ту саму базову структуру з функціями вершинного, фрагментного та світлового процесорів.

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

Режим візуалізації	Опис
Blend_mix	Режим змішування (альфа — це прозорість), за замовчуванням.
Blend_add	Режим адитивного змішування.
Blend_sub	Режим субтрактивного змішування.
Blend_mul	Мультиплікативний режим змішування.
Blend_premul_alpha	Режим альфа-змішування з попереднім множенням.
Blend_disabled	Вимкнути змішування, значення (включаючи альфа) записуються як є.
Unshaded	Результат - просто альбедо. У матеріалі немає освітлення/затінення.
Light_only	Малюйте лише світловий прохід.
Skip_vertex_transform	`VERTEX` потрібно перетворити вручну у функції `vertex()`.
World_vertex_coords	`VERTEX` змінено у світових координатах замість локальних.

Вбудовані

Значення, позначені як in, доступні лише для читання. Значення, помічені як out, можуть бути записані за бажанням і не обов’язково міститимуть розумні значення. Значення, помічені як inout, забезпечують розумне значення за замовчуванням і, за бажанням, можуть бути записані. До семплерів не можна писати, тому вони не позначені.

Не всі вбудовані функції доступні у всіх функціях обробки. Щоб отримати доступ до вбудованої вершини з функції fragment(), ви можете використовувати varying. Те саме стосується доступу до вбудованих фрагментів із функції light().

Глобальні вбудовані функції

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

Вбудований	Опис
In float TIME	Глобальний час з моменту запуску двигуна, у секундах. Повторюється кожні `3600` секунд (що можна змінити за допомогою налаштування rollover). На нього впливає time_scale, але не пауза. Якщо вам потрібна змінна `TIME`, на яку не впливає шкала часу, додайте власну global shader uniform та оновлюйте її кожного кадру.
у float PI	Константа типу `PI` (`3,141592`). Відношення довжини кола до його діаметра та кількість радіан за півоберту.
у float TAU	Константа типу `TAU` (`6.283185`). Еквівалентна `PI * 2` та кількості радіан у повному оберті.
у float E	Константа `E` (`2.718281`). Число Ейлера, основа натурального логарифма.

Вбудовані вершини

Дані вершини (VERTEX) представлені в локальному просторі (координати пікселів відносно початку Node2D). Якщо не записувати, ці значення не будуть змінені та передадуться так, як вони надійшли.

Користувач може вимкнути вбудовану модель для перетворення світу (світ на екран і проекція все одно відбудеться пізніше) і зробити це вручну за допомогою наступного коду:

shader_type canvas_item;
render_mode skip_vertex_transform;

void vertex() {

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

Інші вбудовані функції, такі як UV і COLOR, також передаються до функції fragment(), якщо не змінено.

Для створення екземплярів змінна INSTANCE_CUSTOM містить користувацькі дані екземпляра. При використанні частинок ця інформація зазвичай така:

x: Кут повороту в радіанах.
y: Фаза протягом життя (0,0 до 1,0).
z: рамка анімації.

Вбудований	Опис
In mat4 MODEL_MATRIX	Трансформація локального простору у світовий простір. Світовий простір - це координати, які ви зазвичай використовуєте в редакторі.
In mat4 CANVAS_MATRIX	Перетворення світового простору на простір полотна. У просторі полотна початком координат є верхній лівий кут екрана, а координати варіюються від `(0.0, 0.0)` до розміру області перегляду.
In mat4 SCREEN_MATRIX	Трансформація простору полотна в простір кліпу. Координати в просторі кліпу варіюються від `(-1.0, -1.0)` до `(1.0, 1.0).`
In int INSTANCE_ID	Ідентифікатор екземпляра для створення екземпляра.
In vec4 INSTANCE_CUSTOM	Спеціальні дані екземпляра.
In bool AT_LIGHT_PASS	Завжди `false`.
In vec2 TEXTURE_PIXEL_SIZE	Normalized pixel size of the default 2D texture. For a Sprite2D with a texture of size 64×32 pixels, `TEXTURE_PIXEL_SIZE` = `vec2(1.0 / 64.0, 1.0 / 32.0)`.
Inout vec2 VERTEX	Положення вершини в локальному просторі.
In int VERTEX_ID	Індекс поточної вершини в буфері вершин.
Inout vec2 UV	Нормалізовані координати текстури. Діапазон від `0.0` до `1.0`.
Inout vec4 COLOR	Колір з примітиву вершини, помножений на modulate об'єкта CanvasItem, помножений на self_modulate об'єкта CanvasItem.
Inout float POINT_SIZE	Розмір точки для малювання точки.
In vec4 CUSTOM0	Спеціальне значення з примітиву вершини.
In vec4 CUSTOM1	Спеціальне значення з примітиву вершини.

Фрагмент вбудованих

КОЛІР і ТЕКСТУРА

Вбудована змінна COLOR використовується для кількох речей:

У функції vertex() COLOR містить колір із примітиву вершини, помножений на CanvasItem modulate, помножений на CanvasItem self_modulate.

У функції fragment() вхідним значенням COLOR є те саме значення, помножене на колір із TEXTURE за замовчуванням (якщо є).

У функції fragment() COLOR також є кінцевим результатом.

Певні вузли (наприклад, Sprite2D) відображають текстуру за замовчуванням, наприклад texture. Використовуючи спеціальну функцію fragment(), у вас є кілька варіантів того, як взяти цю текстуру.

Щоб прочитати лише вміст типової текстури, ігноруючи вершину COLOR:

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

Щоб прочитати вміст типової текстури, помноженої на вершину COLOR:

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

Щоб прочитати лише вершину COLOR у fragment(), ігноруючи основну текстуру, ви повинні передати COLOR як змінну, а потім прочитати його у fragment():

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

НОРМАЛЬНО

Подібним чином, якщо в CanvasTexture використовується карта нормалей, Godot використовує її за замовчуванням і призначає її значення вбудованій змінній NORMAL. Якщо ви використовуєте звичайну карту, призначену для використання в 3D, вона відображатиметься перевернутою. Щоб використовувати його у вашому шейдері, ви повинні призначити його властивості NORMAL_MAP. Godot перетворить його для використання у 2D і перезапише NORMAL.

NORMAL_MAP = texture(NORMAL_TEXTURE, UV).rgb;

Вбудований	Опис
In 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)`. Bottom-right of the viewport is `(1.0, 1.0)`.
In vec2 SCREEN_PIXEL_SIZE	Розмір окремих пікселів. Дорівнює оберненій роздільній здатності.
in vec4 REGION_RECT	Visible area of the sprite region in format `(x, y, width, height)`. Varies according to Sprite2D's `region_enabled` property. Values are normalized; for example, a 600×400 region on a 1000×800 texture with a 100×100 offset would be `vec4(0.1, 0.125, 0.6, 0.5)`. Values may exceed the 0.0 to 1.0 range if the X/Y offset is negative, or if the size exceeds the texture's size.
In vec2 POINT_COORD	Coordinate for drawing points in the 0.0 to 1.0 range.
Sampler2D TEXTURE	Двовимірна текстура за замовчуванням.
In vec2 TEXTURE_PIXEL_SIZE	Normalized pixel size of the default 2D texture. For a Sprite2D with a texture of size 64×32 pixels, `TEXTURE_PIXEL_SIZE` = `vec2(1.0 / 64.0, 1.0 / 32.0)`.
In bool AT_LIGHT_PASS	Завжди `false`.
Sampler2D SPECULAR_SHININESS_TEXTURE	Текстура дзеркального блиску цього об'єкта.
In vec4 SPECULAR_SHININESS	Колір дзеркального блиску, взятий із текстури.
In vec2 UV	UV з функції `vertex()`. Для Sprite2D з увімкненою областю це призведе до вибірки всієї текстури. Використовуйте `REGION_RECT` для вибірки лише області, визначеної у властивостях Sprite2D.
In vec2 SCREEN_UV	UV-координата екрану для поточного пікселя.
Sampler2D SCREEN_TEXTURE	Видалено в Godot 4. Замість цього використовуйте `sampler2D` з `hint_screen_texture`.
Inout vec3 NORMAL	Нормальне читання з `NORMAL_TEXTURE`. Можливість запису.
Sampler2D NORMAL_TEXTURE	Стандартна 2D звичайна текстура.
Out vec3 NORMAL_MAP	Налаштовує карти нормалей, призначені для 3D, для використання у 2D. Якщо використовується, замінює `NORMAL`.
Out float NORMAL_MAP_DEPTH	Нормальна глибина карти для масштабування.
Inout vec2 VERTEX	Розташування пікселя в просторі екрана.
Inout vec2 SHADOW_VERTEX	Те саме, що `VERTEX`, але його можна записати для зміни тіней.
Inout vec3 LIGHT_VERTEX	Те саме, що `VERTEX`, але його можна записати для зміни освітлення. Компонент Z представляє висоту.
Inout vec4 COLOR	`COLOR` з функції `vertex()`, помножений на колір `TEXTURE`. Також виведіть значення кольору.

Легкі вбудовані

Функції світлового процесора працюють інакше в Godot 4.x, ніж у Godot 3.x. У Godot 4.x усе освітлення здійснюється під час звичайного проходу розіграшу. Іншими словами, Godot більше не малює об’єкт знову для кожного світла.

Використовуйте режим візуалізації unshaded, якщо ви не хочете, щоб функція light() запускалася. Використовуйте режим візуалізації light_only, якщо ви хочете побачити лише вплив освітлення на об’єкт; це може бути корисно, коли ви бажаєте, щоб об’єкт було видно лише там, де він покритий світлом.

Якщо ви визначите функцію 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);
}

Вбудований	Опис
In 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)`. Bottom-right of the viewport is `(1.0, 1.0)`.
In vec3 NORMAL	Введення нормальне.
In vec4 COLOR	Колір введення. Це вихід функції `fragment()`.
In vec2 UV	UV від функції `vertex()`, еквівалентне UV у функції `fragment()`.
Sampler2D TEXTURE	Поточна текстура, що використовується для CanvasItem.
In vec2 TEXTURE_PIXEL_SIZE	Normalized pixel size of `TEXTURE`. For a Sprite2D with a `TEXTURE` of size 64×32 pixels, `TEXTURE_PIXEL_SIZE` = `vec2(1.0 / 64.0, 1.0 / 32.0)`.
In vec2 SCREEN_UV	UV-координата екрану для поточного пікселя.
In vec2 POINT_COORD	УФ для точкового спрайта.
In vec4 LIGHT_COLOR	Color Light2D. Якщо світло є class_PointLight2D, помножене на texture світла.
In float LIGHT_ENERGY	Energy multiplier з Light2D.
In vec3 LIGHT_POSITION	Позиція Light2D в екранному просторі. Якщо використовується DirectionalLight2D, це завжди `(0.0, 0.0, 0.0)`.
In vec3 LIGHT_DIRECTION	Напрямок Light2D в просторі екрана.
In bool LIGHT_IS_DIRECTIONAL	`true`, якщо цей пропуск є DirectionalLight2D.
In vec3 LIGHT_VERTEX	Позиція пікселів у просторі екрана, змінена функцією `fragment()`.
Inout vec4 LIGHT	Вихідний колір для цього Light2D.
In vec4 SPECULAR_SHININESS	Дзеркальне сяйво, встановлене в текстурі об'єкта.
Out vec4 SHADOW_MODULATE	Помножте тіні, що відкидаються в цій точці, на цей колір.

Функції SDF

Реалізовано кілька додаткових функцій для семплування автоматично згенерованої текстури Signed Distance Field. Ці функції доступні у функціях fragment() та light() шейдерів CanvasItem. Користувацькі функції також можуть використовувати їх, якщо вони викликаються з підтримуваних функцій.

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

Function	Опис
Float texture_sdf (vec2 sdf_pos)	Виконує пошук текстури SDF.
Vec2 texture_sdf_normal (vec2 sdf_pos)	Обчислює нормаль із текстури SDF.
Vec2 sdf_to_screen_uv (vec2 sdf_pos)	Перетворює SDF на УФ екран.
Vec2 screen_uv_to_sdf (vec2 uv)	Перетворює УФ екрана на SDF.