Up to date

This page is up to date for Godot 4.2. If you still find outdated information, please open an issue.

天空着色器¶

Sky shaders are a special type of shader used for drawing sky backgrounds and for updating radiance cubemaps which are used for image-based lighting (IBL). Sky shaders only have one processing function, the sky() function.

There are three places the sky shader is used.

First the sky shader is used to draw the sky when you have selected to use a Sky as the background in your scene.
Second, the sky shader is used to update the radiance cubemap when using the Sky for ambient color or reflections.
Third, the sky shader is used to draw the lower res subpasses which can be used in the high-res background or cubemap pass.

In total, this means the sky shader can run up to six times per frame, however, in practice it will be much less than that because the radiance cubemap does not need to be updated every frame, and not all subpasses will be used. You can change the behavior of the shader based on where it is called by checking the AT_*_PASS booleans. For example:

shader_type sky;

void sky() {
    if (AT_CUBEMAP_PASS) {
        // Sets the radiance cubemap to a nice shade of blue instead of doing
        // expensive sky calculations
        COLOR = vec3(0.2, 0.6, 1.0);
    } else {
        // Do expensive sky calculations for background sky only
        COLOR = get_sky_color(EYEDIR);
    }
}

When using the sky shader to draw a background, the shader will be called for all non-occluded fragments on the screen. However, for the background's subpasses, the shader will be called for every pixel of the subpass.

When using the sky shader to update the radiance cubemap, the sky shader will be called for every pixel in the cubemap. On the other hand, the shader will only be called when the radiance cubemap needs to be updated. The radiance cubemap needs to be updated when any of the shader parameters are updated. For example, if TIME is used in the shader, then the radiance cubemap will update every frame. The following list of changes force an update of the radiance cubemap:

TIME is used.
POSITION is used and the camera position changes.
If any LIGHTX_* properties are used and any DirectionalLight3D changes.
If any uniform is changed in the shader.
If the screen is resized and either of the subpasses are used.

Try to avoid updating the radiance cubemap needlessly. If you do need to update the radiance cubemap each frame, make sure your Sky process mode is set to REALTIME.

Note that the process mode only affects the rendering of the radiance cubemap. The visible sky is always rendered by calling the fragment shader for every pixel. With complex fragment shaders, this can result in a high rendering overhead. If the sky is static (the conditions listed above are met) or changes slowly, running the full fragment shader every frame is not needed. This can be avoided by rendering the full sky into the radiance cubemap, and reading from this cubemap when rendering the visible sky. With a completely static sky, this means that it needs to be rendered only once.

The following code renders the full sky into the radiance cubemap and reads from that cubemap for displaying the visible sky:

shader_type sky;

void sky() {
    if (AT_CUBEMAP_PASS) {
        vec3 dir = EYEDIR;

        vec4 col = vec4(0.0);

        // Complex color calculation

        COLOR = col.xyz;
        ALPHA = 1.0;
    } else {
        COLOR = texture(RADIANCE, EYEDIR).rgb;
    }
}

This way, the complex calculations happen only in the cubemap pass, which can be optimized by setting the sky's process mode and the radiance size to get the desired balance between performance and visual fidelity.

渲染模式¶

Subpasses allow you to do more expensive calculations at a lower resolution to speed up your shaders. For example the following code renders clouds at a lower resolution than the rest of the sky:

shader_type sky;
render_mode use_half_res_pass;

void sky() {
    if (AT_HALF_RES_PASS) {
        // Run cloud calculation for 1/4 of the pixels
        vec4 color = generate_clouds(EYEDIR);
        COLOR = color.rgb;
        ALPHA = color.a;
    } else {
        // At full resolution pass, blend sky and clouds together
        vec3 color = generate_sky(EYEDIR);
        COLOR = color + HALF_RES_COLOR.rgb * HALF_RES_COLOR.a;
    }
}

渲染模式	描述
use_half_res_pass	允许着色器对半分辨率阶段进行写入和访问。
use_quarter_res_pass	允许着色器对四分之一分辨率阶段进行写入和访问。
disable_fog	使用后，雾不会影响天空。

内置¶

Values marked as "in" are read-only. Values marked as "out" are for optional writing and will not necessarily contain sensible values. Samplers cannot be written to so they are not marked.

全局内置¶

Global built-ins are available everywhere, including in custom functions.

LIGHTX 灯光有 4 个，可以通过 LIGHT0、LIGHT1、LIGHT2、LIGHT3 访问。

内置	描述
in float TIME	全球时间, 以秒为单位.
in vec3 POSITION	相机位置，使用世界空间
samplerCube RADIANCE	辐射度立方体贴图。只能在背景阶段读取。使用前请检查 `!AT_CUBEMAP_PASS`。
in bool AT_HALF_RES_PASS	目前正在渲染半分辨率阶段。
in bool AT_QUARTER_RES_PASS	目前正在渲染四分之一分辨率阶段。
in bool AT_CUBEMAP_PASS	目前正在渲染辐射度立方体贴图。
in bool LIGHTX_ENABLED	场景中存在 `LightX` 并且可见。如果为 `false`，则其他灯光属性可能为垃圾值。
in float LIGHTX_ENERGY	`LIGHTX` 的能量乘数。
in vec3 LIGHTX_DIRECTION	`LIGHTX` 面朝的方向。
in vec3 LIGHTX_COLOR	`LIGHTX` 的颜色。
in float LIGHTX_SIZE	Angular diameter of `LIGHTX` in the sky. Expressed in degrees. For reference, the sun from earth is about 0.5 degrees.
in float PI	圆周率常量 `PI`（`3.141592`）。圆的周长与直径的比值，转半圈的弧度值。
in float TAU	A `TAU` constant (`6.283185`). An equivalent of `PI * 2` and amount of radians in full turn.
in float E	A `E` constant (`2.718281`). Euler's number and a base of the natural logarithm.

Sky built-ins¶

内置	描述
in vec3 EYEDIR	Normalized direction of current pixel. Use this as your basic direction for procedural effects.
in vec2 SCREEN_UV	Screen UV coordinate for current pixel. Used to map a texture to the full screen.
in vec2 SKY_COORDS	Sphere UV. Used to map a panorama texture to the sky.
in vec4 HALF_RES_COLOR	Color value of corresponding pixel from half resolution pass. Uses linear filter.
in vec4 QUARTER_RES_COLOR	Color value of corresponding pixel from quarter resolution pass. Uses linear filter.
out vec3 COLOR	输出颜色。
out float ALPHA	Output alpha value, can only be used in subpasses.
out vec4 FOG