Converting GLSL to Godot shaders¶
This document explains the differences between Godot's shading language and GLSL and gives practical advice on how to migrate shaders from other sources, such as Shadertoy and The Book of Shaders, into Godot shaders.
For detailed information on Godot's shading language, please refer to the Shading Language reference.
GLSL¶
Godot uses a shading language based on GLSL with the addition of a few quality-of-life features. Accordingly, most features available in GLSL are available in Godot's shading language.
Shader programs¶
In GLSL, each shader uses a separate program. You have one program for the
vertex shader and one for the fragment shader. In Godot, you have a single
shader that contains a vertex
and/or a fragment
function. If you only
choose to write one, Godot will supply the other.
Godot allows uniform variables and functions to be shared by defining the fragment and vertex shaders in one file. In GLSL, the vertex and fragment programs cannot share variables except when varyings are used.
Vertex attributes¶
In GLSL, you can pass in per-vertex information using attributes and have the
flexibility to pass in as much or as little as you want. In Godot, you have a
set number of input attributes, including VERTEX
(position), COLOR
,
UV
, UV2
, NORMAL
. For a complete list, see the Shading language
reference.
gl_Position¶
gl_Position
receives the final position of a vertex specified in the vertex
shader. It is specified by the user in clip space. Typically, in GLSL, the model
space vertex position is passed in using a vertex attribute called position
and you handle the conversion from model space to clip space manually.
В Godot, VERTEX
определяет положение вершины в пространстве модели в начале функции vertex
. Godot также обрабатывает окончательное преобразование в пространство клипа после выполнения пользовательской функции vertex
. Если вы хотите пропустить преобразование из пространства модели в пространство вида, вы можете установить render_mode
на skip_vertex_transform
. Если вы хотите пропустить все преобразования, установите render_mode
в skip_vertex_transform
и установите PROJECTION_MATRIX
в mat4(1.0)
, чтобы обнулить окончательное преобразование из пространства вида в пространство клипа.
Varуings¶
Varyings are a type of variable that can be passed from the vertex shader to the
fragment shader. In modern GLSL (3.0 and up), varyings are defined with the
in
and out
keywords. A variable going out of the vertex shader is
defined with out
in the vertex shader and in
inside the fragment shader.
Главная¶
In GLSL, each shader program looks like a self-contained C-style program.
Accordingly, the main entry point is main
. If you are copying a vertex
shader, rename main
to vertex
and if you are copying a fragment shader,
rename main
to fragment
.
Константы¶
Global array constants are not supported in Godot 3.x. You can fake the functionality by using a uniform initialized to the value, but you will not benefit from the increased speed from using a constant.
Macros¶
В соответствии со своим сходством с языком C, GLSL позволяет использовать макросы. Обычно #define
используется для определения констант или небольших функций. Не существует прямого способа перевести определения на язык затенения Godot. Если определяется функция, то замените на функцию, а если константа, то замените на форму. Для других макросов (#if
, #ifdef
и т.д.) нет эквивалента, потому что они выполняются на этапе предварительной обработки компиляции.
Переменные¶
GLSL has many built-in variables that are hard-coded. These variables are not uniforms, so they are not editable from the main program.
Переменная |
Тип |
Equivalent |
Описание |
---|---|---|---|
gl_FragColor |
out vec4 |
COLOR |
Output color for each pixel. |
gl_FragCoord |
vec4 |
FRAGCOORD |
For full screen quads. For smaller quads, use UV. |
gl_Position |
vec4 |
VERTEX |
Position of Vertex, output from Vertex Shader. |
gl_PointSize |
float |
POINT_SIZE |
Size of Point primitive. |
gl_PointCoord |
vec2 |
POINT_COORD |
Position on point when drawing Point primitives. |
gl_FrontFаcing |
bool |
FRONT_FACING |
True if front face of primitive. |
Координаты¶
gl_FragCoord
in GLSL and FRAGCOORD
in the Godot shading language use the
same coordinate system. If using UV in Godot, the y-coordinate will be flipped
upside down.
Точность¶
In GLSL, you can define the precision of a given type (float or int) at the top
of the shader with the precision
keyword. In Godot, you can set the
precision of individual variables as you need by placing precision qualifiers
lowp
, mediump
, and highp
before the type when defining the variable.
For more information, see the Shading Language
reference.
Shаdertoy¶
Shadertoy is a website that makes it easy to write fragment shaders and create pure magic.
Shadertoy does not give the user full control over the shader. It handles all the input and uniforms and only lets the user write the fragment shader.
Типы¶
Shadertoy uses the webgl spec, so it runs a slightly different version of GLSL. However, it still has the regular types, including constants and macros.
mаinImage¶
The main point of entry to a Shadertoy shader is the mainImage
function.
mainImage
has two parameters, fragColor
and fragCoord
, which
correspond to COLOR
and FRAGCOORD
in Godot, respectively. These
parameters are handled automatically in Godot, so you do not need to include
them as parameters yourself. Anything in the mainImage
function should be
copied into the fragment
function when porting to Godot.
Переменные¶
Чтобы сделать написание фрагментных шейдеров простым и легким, Shadertoy обрабатывает передачу множества полезной информации из основной программы в фрагментный шейдер за вас. Некоторые из них не имеют аналогов в Godot, потому что Godot решил не делать их доступными по умолчанию. Это нормально, потому что Godot дает вам возможность создавать свои собственные формы. Для переменных, эквиваленты которых перечислены как "Provide with Uniform", пользователи сами отвечают за создание такой формы. Описание дает читателю подсказку о том, что можно передать в качестве замены.
Переменная |
Тип |
Equivalent |
Описание |
---|---|---|---|
frаgColor |
out vec4 |
COLOR |
Output color for each pixel. |
fragCoord |
vec2 |
FRAGCOORD.xy |
For full screen quads. For smaller quads, use UV. |
iRеsolution |
vec3 |
1.0 / SCREEN_PIXEL_SIZE |
Can also pass in manually. |
iTime |
float |
TIME |
Time since shader started. |
iTimeDelta |
float |
Provide with Uniform |
Time to render previous frame. |
iFrame |
float |
Provide with Uniform |
Frame number. |
iChannelTime[4] |
float |
Provide with Uniform |
Time since that particular texture started. |
iMouse |
vec4 |
Provide with Uniform |
Mouse position in pixel coordinates. |
iDate |
vec4 |
Provide with Uniform |
Current date, expressed in seconds. |
iChannelResolution[4] |
vec3 |
1.0 / TEXTURE_PIXEL_SIZE |
Resolution of particular texture. |
iChanneli |
Sampler2D |
TEXTURE |
Godot provides only one built-in; user can make more. |
Координаты¶
fragCoord
behaves the same as gl_FragCoord
in GLSL and FRAGCOORD
in Godot.
The Book of Shaders¶
Similar to Shadertoy, The Book of Shaders provides access to a fragment shader in the web browser, with which the user may interact. The user is restricted to writing fragment shader code with a set list of uniforms passed in and with no ability to add additional uniforms.
For further help on porting shaders to various frameworks generally, The Book of Shaders provides a page on running shaders in various frameworks.
Типы¶
The Book of Shaders uses the webgl spec, so it runs a slightly different version of GLSL. However, it still has the regular types, including constants and macros.
Главная¶
The entry point for a Book of Shaders fragment shader is main
, just like in
GLSL. Everything written in a Book of Shaders main
function should be copied
into Godot's fragment
function.
Переменные¶
The Book of Shaders sticks closer to plain GLSL than Shadertoy does. It also implements fewer uniforms than Shadertoy.
Переменная |
Тип |
Equivalent |
Описание |
---|---|---|---|
gl_FragColor |
out vec4 |
COLOR |
Output color for each pixel. |
gl_FragCoord |
vec4 |
FRAGCOORD |
For full screen quads. For smaller quads, use UV. |
u_resolution |
vec2 |
1.0 / SCREEN_PIXEL_SIZE |
Can also pass in manually. |
u_time |
float |
TIME |
Time since shader started. |
u_mouse |
vec2 |
Provide with Uniform |
Mouse position in pixel coordinates. |
Координаты¶
The Book of Shaders uses the same coordinate system as GLSL.