Spatial shaders

Spatial shaders are used for shading 3D objects. They are the most complex type of shader Godot offers. Spatial shaders are highly configurable with different render modes and different rendering options (e.g. Subsurface Scattering, Transmission, Ambient Occlusion, Rim lighting etc). Users can optionally write vertex, fragment, and light processor functions to affect how objects are drawn.

Render modes

Render mode

Description

blend_mix

Mix blend mode (alpha is transparency), default.

blend_add

Additive blend mode.

blend_sub

Subtractive blend mode.

blend_mul

Multiplicative blend mode.

depth_draw_opaque

Only draw depth for opaque geometry (not transparent).

depth_draw_always

Always draw depth (opaque and transparent).

depth_draw_never

Never draw depth.

depth_prepass_alpha

Do opaque depth pre-pass for transparent geometry.

depth_test_disabled

Disable depth testing.

sss_mode_skin

Subsurface Scattering mode for skin.

cull_back

Cull back-faces (default).

cull_front

Cull front-faces.

cull_disabled

Culling disabled (double sided).

unshaded

Result is just albedo. No lighting/shading happens in material.

wireframe

Geometry draws using lines.

diffuse_lambert

Lambert shading for diffuse (default).

diffuse_lambert_wrap

Lambert wrapping (roughness dependent) for diffuse.

diffuse_burley

Burley (Disney PBS) for diffuse.

diffuse_toon

Toon shading for diffuse.

specular_schlick_ggx

Schlick-GGX for specular (default).

specular_blinn

Blinn for specular (compatibility).

specular_phong

Phong for specular (compatibility).

specular_toon

Toon for specular.

specular_disabled

Disable specular.

skip_vertex_transform

VERTEX/NORMAL/etc. need to be transformed manually in vertex function.

world_vertex_coords

VERTEX/NORMAL/etc. are modified in world coordinates instead of local.

ensure_correct_normals

Use when non-uniform scale is applied to mesh.

shadows_disabled

Disable computing shadows in shader.

ambient_light_disabled

Disable contribution from ambient light and radiance map.

shadow_to_opacity

Lighting modifies the alpha so shadowed areas are opaque and non-shadowed areas are transparent. Useful for overlaying shadows onto a camera feed in AR.

vertex_lighting

Use vertex-based lighting.

particle_trails

Enables the trails when used on particles geometry.

alpha_to_coverage

Alpha antialiasing mode, see here for more.

alpha_to_coverage_and_one

Alpha antialiasing mode, see here for more.

fog_disabled

Disable receiving depth-based or volumetric fog. Useful for blend_add materials like particles.

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.

Built-in

Description

in float TIME

Global time, in seconds.

in float PI

A PI constant (3.141592). A ration of circle's circumference to its diameter and amount of radians in half turn.

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.

Vertex built-ins

Vertex data (VERTEX, NORMAL, TANGENT, BITANGENT) are presented in local model space. If not written to, these values will not be modified and be passed through as they came.

They can optionally be presented in world space by using the world_vertex_coords render mode.

Users can disable the built-in modelview transform (projection will still happen later) and do it manually with the following code:

shader_type spatial;
render_mode skip_vertex_transform;

void vertex() {
    VERTEX = (MODELVIEW_MATRIX * vec4(VERTEX, 1.0)).xyz;
    NORMAL = normalize((MODELVIEW_MATRIX * vec4(NORMAL, 0.0)).xyz);
    // same as above for binormal and tangent, if normal mapping is used
}

Other built-ins, such as UV, UV2 and COLOR, are also passed through to the fragment function if not modified.

Users can override the modelview and projection transforms using the POSITION built-in. When POSITION is used, the value from VERTEX is ignored and projection does not happen. However, the value passed to the fragment shader still comes from VERTEX.

For instancing, the INSTANCE_CUSTOM variable contains the instance custom data. When using particles, this information is usually:

  • x: Rotation angle in radians.

  • y: Phase during lifetime (0 to 1).

  • z: Animation frame.

This allows you to easily adjust the shader to a particle system using default particles material. When writing a custom particle shader, this value can be used as desired.

Built-in

Description

in vec2 VIEWPORT_SIZE

Size of viewport (in pixels).

in mat4 VIEW_MATRIX

World space to view space transform.

in mat4 INV_VIEW_MATRIX

View space to world space transform.

in mat4 INV_PROJECTION_MATRIX

Clip space to view space transform.

in vec3 NODE_POSITION_WORLD

Node world space position.

in vec3 NODE_POSITION_VIEW

Node view space position.

in vec3 CAMERA_POSITION_WORLD

Camera world space position.

in vec3 CAMERA_DIRECTION_WORLD

Camera world space direction.

in bool OUTPUT_IS_SRGB

true when output is in sRGB color space (this is true in the Compatibility renderer, false in Forward+ and Forward Mobile).

in int INSTANCE_ID

Instance ID for instancing.

in vec4 INSTANCE_CUSTOM

Instance custom data (for particles, mostly).

in int VIEW_INDEX

The view that we are rendering. VIEW_MONO_LEFT (0) for Mono (not multiview) or left eye, VIEW_RIGHT (1) for right eye.

in int VIEW_MONO_LEFT

Constant for Mono or left eye, always 0.

in int VIEW_RIGHT

Constant for right eye, always 1.

in vec3 EYE_OFFSET

Position offset for the eye being rendered. Only applicable for multiview rendering.

inout vec3 VERTEX

Vertex in local coordinates.

in int VERTEX_ID

The index of the current vertex in the vertex buffer.

inout vec3 NORMAL

Normal in local coordinates.

inout vec3 TANGENT

Tangent in local coordinates.

inout vec3 BINORMAL

Binormal in local coordinates.

out vec4 POSITION

If written to, overrides final vertex position.

inout vec2 UV

UV main channel.

inout vec2