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 |
in float TAU |
A |
in float E |
A |
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 |
|
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.
|
in int VIEW_MONO_LEFT |
Constant for Mono or left eye, always |
in int VIEW_RIGHT |
Constant for right eye, always |
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 |