Migrating to Godot's shading language


本文档解释了Godot的着色语言和GLSL之间的区别,并提供了有关如何将着色器从其他来源(如Shadertoy和The Book of Shaders)迁移到Godot着色器的实用建议。

For detailed information on Godot's shading language, please refer to the Shading Language reference.


Godot使用基于GLSL的着色语言,增加了一些生活质量特征。 因此,GLSL中提供的大多数功能都可以使用Godot的着色语言。

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.


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

In Godot, VERTEX specifies the vertex position in model space at the beginning of the vertex function. Godot also handles the final conversion to clip space after the user-defined vertex function is run. If you want to skip the conversion from model to view space, you can set the render_mode to skip_vertex_transform. If you want to skip all transforms, set render_mode to skip_vertex_transform and set the PROJECTION_MATRIX to mat4(1.0) in order to nullify the final transform from view space to clip space.


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

In keeping with its similarity to C, GLSL lets you use macros. Commonly #define is used to define constants or small functions. There is no straightforward way to translate defines to Godot's shading language. If it is a function that is defined, then replace with a function, and if it is a constant, then replace with a uniform. For other macros (#if, #ifdef, etc.), there is no equivalent because they run during the pre-processing stage of compilation.


GLSL has many built-in variables that are hard-coded. These variables are not uniforms, so they are not editable from the main program.

变量 类型 等价物 描述
gl_FragColor out vec4 COLOR 每个像素的输出颜色。
gl_FragCoord vec4 FRAGCOORD For full screen quads. For smaller quads, use UV.
gl_Position vec4 VERTEX 顶点的位置,从顶点着色器输出。
gl_PointSize float POINT_SIZE Point原语的大小。
gl_PointCoord vec2 POINT_COORD 绘制Point基元时在点上的位置。
gl_FrontFacing bool FRONT_FACING 如果原始的正面,则为真。


GLSL中的`gl_FragCoord``和Godot着色语言中的``FRAGCOORD``使用相同的坐标系。 如果在Godot中使用UV,则y坐标将颠倒翻转。


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.


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.


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.


In order to make writing fragment shaders straightforward and easy, Shadertoy handles passing a lot of helpful information from the main program into the fragment shader for you. A few of these have no equivalents in Godot because Godot has chosen not to make them available by default. This is okay because Godot gives you the ability to make your own uniforms. For variables whose equivalents are listed as "Provide with Uniform", users are responsible for creating that uniform themselves. The description gives the reader a hint about what they can pass in as a substitute.

变量 类型 等价物 描述
fragColor out vec4 COLOR 每个像素的输出颜色。
fragColor vec2 FRAGCOORD.xy For full screen quads. For smaller quads, use UV.
iResolution vec3 1.0 / SCREEN_PIXEL_SIZE 也可以手动传递。
iTime float TIME 着色器启动后的时间。
iTimeDelta float 提供统一 渲染前一帧的时间。
iFrame float 提供统一 帧号。
iChannelTime[4] float 提供统一 帧号。
iMouse vec4 提供统一 鼠标在像素坐标中的位置。
iDate vec4 提供统一 当前日期,以秒为单位表示。
iChannelResolution[4] vec3 1.0 / TEXTURE_PIXEL_SIZE 特殊纹理的分辨率。
iChanneli Sampler2D TEXTURE Godot provides only one built-in; user can make more.


fragCoord``的行为与``gl_FragCoord``相同 :ref:`GLSL <glsl_coordinates>` 和Godot中的 ``FRAGCOORD


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.

有关将着色器移植到各种框架的进一步帮助,The Book of Shaders在各种框架中运行着色器时提供了一个“page <https://thebookofshaders.com/04>`_ 。


The Book of Shaders使用webgl规范,因此它运行的GLSL略有不同。 但是,它仍然具有常规类型,包括常量和宏。


Book of Shaders片段着色器的入口点是 main ,就像在GLSL中一样。 使用着色器 main 函数编写的所有内容都应该复制到Godot的 fragment 函数中。


着色书比Shadertoy更接近普通GLSL。 它也比Shadertoy实施更少的制服。

变量 类型 等价物 描述
gl_FragColor out vec4 COLOR 每个像素的输出颜色。
gl_FragCoord vec4 FRAGCOORD For full screen quads. For smaller quads, use UV.
u_resolution vec2 1.0 / SCREEN_PIXEL_SIZE 也可以手动传递。
u_time float TIME 着色器启动后的时间。
u_mouse vec2 提供统一 鼠标在像素坐标中的位置。


Shaders使用相同的坐标系 GLSL