Sky shaders

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 fragment() 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 fragment() {
    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.

Render modes

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 fragment() {
    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;
    }
}
Render mode Description
use_half_res_pass Allows the shader to write to and access the half resolution pass.
use_quarter_res_pass Allows the shader to write to and access the quarter resolution pass.

Built-ins

Values marked as "in" are read-only. Values marked as "out" are for optional writing and will not necessarily contain sensible values. Values marked as "inout" provide a sensible default value, and can optionally be written to. Samplers are not subjects of writing and they are not marked.

Global built-ins

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

There are 4 LIGHTX lights, accessed as LIGHT0, LIGHT1, LIGHT2, and LIGHT3.

Built-in Description
in float TIME Global time, in seconds.
in vec3 POSITION Camera position in world space
in SamplerCube RADIANCE Radiance cubemap. Can only be read from during background pass. Check !AT_CUBEMAP_PASS before using.
in bool AT_HALF_RES_PASS Currently rendering to half resolution pass.
in bool AT_QUARTER_RES_PASS Currently rendering to quarter resolution pass.
in bool AT_CUBEMAP_PASS Currently rendering to radiance cubemap.
in bool LIGHTX_ENABLED LightX is visible and in the scene. If false, other light properties may be garbage.
in float LIGHTX_ENERGY Energy multiplier for LIGHTX.
in vec3 LIGHTX_DIRECTION Direction that LIGHTX is facing.
in vec3 LIGHTX_COLOR Color of 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.

Fragment built-ins

Built-in Description
out vec3 COLOR Output color
out float ALPHA Output alpha value, can only be used in subpasses.
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.