Shading language¶
Introduction¶
Godot uses a shading language similar to GLSL ES 3.0. Most datatypes and functions are supported, and the few remaining ones will likely be added over time.
Unlike the shader language in Godot 2.x, this implementation is much closer to the original.
Shader Types¶
Instead of supplying a general purpose configuration, Godot Shading Language must specify what a shader is intended for. Depending on the type, different render modes, built-in variables and processing functions are supported.
Any shader needs a first line specifying this type, in the following format:
shader_type <type>;
Valid types are:
- “spatial”: For 3D rendering.
- “canvas_item”: For 2D rendering.
- “particles”: For particle systems.
Render Modes¶
Different shader types support different render modes. They are optional but, if specified, must be after the shader_type. Example syntax is:
shader_type spatial;
render_mode unshaded, cull_disabled;
Data types¶
Most GLSL ES 3.0 datatypes are supported:
| Type | Description |
|---|---|
| void | Void datatype, useful only for functions that return nothing. |
| bool | Boolean datatype, can only contain “true” or “false” |
| bvec2 | Two component vector of booleans. |
| bvec3 | Three component vector of booleans. |
| bvec4 | Four component vector of booleans. |
| int | Signed scalar integer. |
| ivec2 | Two component vector of signed integers. |
| ivec3 | Three component vector of signed integers. |
| ivec4 | Four component vector of signed integers. |
| uint | Unsigned scalar integer, can’t contain negative numbers. |
| uvec2 | Two component vector of unsigned integers. |
| uvec3 | Three component vector of unsigned integers. |
| uvec4 | Four component vector of unsigned integers. |
| float | Floating point scalar. |
| vec2 | Two component vector of floating point values. |
| vec3 | Three component vector of floating point values. |
| vec4 | Four component vector of floating point values. |
| mat2 | 2x2 matrix, in column major order. |
| mat3 | 3x3 matrix, in column major order. |
| mat4 | 4x4 matrix, in column major order. |
| sampler2D | Sampler type, for binding 2D textures, which are read as float. |
| isampler2D | Sampler type for binding 2D textures, which are read as signed integer. |
| usampler2D | Sampler type for binding 2D textures, which are read as unsigned integer. |
| samplerCube | Sampler type for binding Cubemaps, which are read as floats. |
Casting¶
Just like GLSL ES 3.0, implicit casting between scalars and vectors of the same size but different type is not allowed. Casting of types of different size is also not allowed. Conversion must be done explicitly via constructors.
Example:
float a = 2; // valid
float a = 2.0; // valid
float a = float(2); // valid
Default integer constants are signed, so casting is always needed to convert to unsigned:
int a = 2; // valid
uint a = 2; // invalid
uint a = uint(2); // valid
Members¶
Individual scalar members of vector types are accessed via the “x”, “y”, “z” and “w” members. Alternatively, using “r”, “g”, “b” and “a” also works and is equivalent. Use whatever fits best for your use case.
For matrices, use m[row][column] indexing syntax to access each scalar, or m[idx] for access a vector by row index. For example, for accessing y position of object in mat4 you must use m[3][1] syntax.
Constructing¶
Construction of vector types must always pass:
// The required amount of scalars
vec4 a = vec4(0.0, 1.0, 2.0, 3.0);
// Complementary vectors and/or scalars
vec4 a = vec4(vec2(0.0, 1.0), vec2(2.0, 3.0));
vec4 a = vec4(vec3(0.0, 1.0, 2.0), 3.0);
// A single scalar for the whole vector
vec4 a = vec4(0.0);
Construction of matrix types requires pass vectors of same dimension as matrix. You could also build a diagonal matrix using matx(float) syntax. So the mat4(1.0) is an identity matrix.
mat2 m2 = mat2(vec2(1.0, 0.0), vec2(0.0, 1.0));
mat3 m3 = mat3(vec3(1.0, 0.0, 0.0), vec3(0.0, 1.0, 0.0), vec3(0.0, 0.0, 1.0));
mat4 identity = mat4(1.0);
Swizzling¶
It is possible to obtain any combination of them in any order, as long as the result is another vector type (or scalar). This is easier shown than explained:
vec4 a = vec4(0.0, 1.0, 2.0, 3.0);
vec3 b = a.rgb; // Creates a vec3 with vec4 components
vec3 b = a.aaa; // Also valid, creates a vec3 and fills it with "a".
vec3 b = a.bgr; // Order does not matter
vec3 b = a.xyz; // Also rgba, xyzw are equivalent
float c = b.w; // Invalid, because "w" is not present in vec3 b
Precision¶
It is possible to add precision modifiers to datatypes, use them for uniforms, variables, arguments and varyings:
lowp vec4 a = vec4(0.0, 1.0, 2.0, 3.0); // low precision, usually 8 bits per component mapped to 0-1
mediump vec4 a = vec4(0.0, 1.0, 2.0, 3.0); // medium precision, usually 16 bits or half float
highp vec4 a = vec4(0.0, 1.0, 2.0, 3.0); // high precision, uses full float or integer range (default)
Using lower precision for some operations can speed up the math involved (at the cost of, of course, less precision). This is rarely needed in the vertex shader (where full precision is needed most of the time), but often needed in the fragment one.
Keep in mind that some architectures (mainly mobile) benefit a lot from this, but are also restricted (conversion between precisions has a cost). Please read the relevant documentation on the target architecture to find out more. In all honesty though, mobile drivers are buggy so to stay out of trouble make simple shaders without specifying precision unless you really need to.
Operators:¶
Godot shading language supports the same set of operators as GLSL ES 3.0. Below is the list of them in precedence order:
| Precedence | Class | Operator |
| 1 (highest) | parenthetical grouping | () |
| 2 | unary | +, -, !, ~ |
| 3 | multiplicative | /, *, % |
| 4 | additive | +, - |
| 5 | bit-wise shift | <<, >> |
| 6 | relational | <, >, <=, >= |
| 7 | equality | ==, != |
| 8 | bit-wise and | & |
| 9 | bit-wise exclusive or | ^ |
| 10 | bit-wise inclusive or | | |
| 11 | logical and | && |
| 12 (lowest) | logical inclusive or | || |
Flow Control¶
Godot Shading language supports the most common types of flow control:
// if and else
if (cond) {
} else {
}
// for loops
for (int i = 0; i < 10; i++) {
}
// while
while (true) {
}
Keep in mind that, in modern GPUs, an infinite loop can exist and can freeze your application (including editor). Godot can’t protect you from this, so be careful to not make this mistake!
Discarding¶
Fragment and light functions can use the discard keyword. If used, the fragment is discarded and nothing is written.
Functions¶
It’s possible to define any function in a Godot shader. They take the following syntax:
ret_type func_name(args) {
return ret_type; // if returning a value
}
// a better example:
int sum2(int a, int b) {
return a + b;
}
Functions can be used from any other function that is below it.
Function argument can have special qualifiers:
- in: Means the argument is only for reading (default).
- out: Means the argument is only for writing.
- inout: Means the argument is fully passed via reference.
Example below:
void sum2(int a, int b, inout int result) {
result = a + b;
}
Processor Functions¶
Depending on shader type, processor functions may be available to optionally override. For “spatial” and “canvas_item”, it is possible to override “vertex”, “fragment” and “light”. For “particles”, only “vertex” can be overridden.
Vertex Processor¶
The “vertex” processing function is called for every vertex, 2D or 3D. For particles, it’s called for every particle.
Depending on shader type, a different set of built-in inputs and outputs are provided. In general, vertex functions are not that commonly used.
shader_type spatial;
void vertex() {
VERTEX.x += sin(TIME); // offset vertex x by sine function on time elapsed
}
Fragment Processor¶
The “fragment” processor is used to set up the Godot material parameters per pixel. This code runs on every visible pixel the object or primitive is drawn to.
shader_type spatial;
void fragment() {
ALBEDO = vec3(1.0, 0.0, 0.0); // use red for material albedo
}
Light Processor¶
The “light” processor runs per pixel too, but also runs for every light that affects the object ( and does not run if no lights affect the object).
shader_type spatial;
void light() {
DIFFUSE_LIGHT = vec3(0.0, 1.0, 0.0);
}
Varyings¶
To send data from vertex to fragment shader, varyings are used. They are set for every primitive vertex in the vertex processor, and the value is interpolated (and perspective corrected) when reaching every pixel in the fragment processor.
shader_type spatial;
varying vec3 some_color;
void vertex() {
some_color = NORMAL; // make the normal the color
}
void fragment() {
ALBEDO = some_color;
}
Interpolation qualifiers¶
Certain values are interpolated during the shading pipeline. You can modify how these interpolations are done by using interpolation qualifiers.
shader_type spatial;
varying flat vec3 our_color;
void vertex() {
our_color = COLOR.rgb;
}
void fragment() {
ALBEDO = our_color;
}
There are three possible interpolation qualifiers:
| Qualifier | Description |
|---|---|
| flat | The value is not interpolated |
| noperspective | The value is linearly interpolated in window-space |
| smooth | The value is interpolated in a perspective-correct fashion. This is the default |
Uniforms¶
Passing values to shaders is possible. These are global to the whole shader and called uniforms. When a shader is later assigned to a material, the uniforms will appear as editable parameters on it. Uniforms can’t be written from within the shader.
shader_type spatial;
uniform float some_value;
Any type except for void can be a uniform. Additionally, Godot provides optional shader hints to make the compiler understand what the uniform is used for.
shader_type spatial;
uniform vec4 color : hint_color;
uniform float amount : hint_range(0, 1);
uniform vec4 other_color : hint_color = vec4(1.0);
Full list of hints below:
| Type | Hint | Description |
|---|---|---|
| vec4 | hint_color | Used as color |
| int, float | hint_range(min,max [,step] ) | Used as range (with min/max/step) |
| sampler2D | hint_albedo | Used as albedo color, default white |
| sampler2D | hint_black_albedo | Used as albedo color, default black |
| sampler2D | hint_normal | Used as normalmap |
| sampler2D | hint_white | As value, default to white. |
| sampler2D | hint_black | As value, default to black |
| sampler2D | hint_aniso | As flowmap, default to right. |
As Godot 3D engine renders in linear color space, it’s important to understand that textures that are supplied as color (ie, albedo) need to be specified as such for proper SRGB->linear conversion.
Uniforms can also be assigned default values:
shader_type spatial;
uniform vec4 some_vector = vec4(0.0);
uniform vec4 some_color : hint_color = vec4(1.0);
Built-in Functions¶
A large number of built-in functions are supported, conforming mostly to GLSL ES 3.0. When vec_type (float), vec_int_type, vec_uint_type, vec_bool_type nomenclature is used, it can be scalar or vector.
| Function | Description |
|---|---|
| vec_type radians ( vec_type ) | Convert degrees to radians |
| vec_type degrees ( vec_type ) | Convert radians to degrees |
| vec_type sin ( vec_type ) | Sine |
| vec_type cos ( vec_type ) | Cosine |
| vec_type tan ( vec_type ) | Tangent |
| vec_type asin ( vec_type ) | Arc-Sine |
| vec_type acos ( vec_type ) | Arc-Cosine |
| vec_type atan ( vec_type ) | Arc-Tangent |
| vec_type atan ( vec_type x, vec_type y ) | Arc-Tangent to convert vector to angle |
| vec_type sinh ( vec_type ) | Hyperbolic-Sine |
| vec_type cosh ( vec_type ) | Hyperbolic-Cosine |
| vec_type tanh ( vec_type ) | Hyperbolic-Tangent |
| vec_type asinh ( vec_type ) | Inverse-Hyperbolic-Sine |
| vec_type acosh ( vec_type ) | Inverse-Hyperbolic-Cosine |
| vec_type atanh ( vec_type ) | Inverse-Hyperbolic-Tangent |
| vec_type pow ( vec_type, vec_type ) | Power |
| vec_type exp ( vec_type ) | Base-e Exponential |
| vec_type exp2 ( vec_type ) | Base-2 Exponential |
| vec_type log ( vec_type ) | Natural Logarithm |
| vec_type log2 ( vec_type ) | Base-2 Logarithm |
| vec_type sqrt ( vec_type ) | Square Root |
| vec_type inversesqrt ( vec_type ) | Inverse Square Root |
| vec_type abs ( vec_type ) | Absolute |
| vec_int_type abs ( vec_int_type ) | Absolute |
| vec_type sign ( vec_type ) | Sign |
| vec_int_type sign ( vec_int_type ) | Sign |
| vec_type floor ( vec_type ) | Floor |
| vec_type round ( vec_type ) | Round |
| vec_type roundEven ( vec_type ) | Round nearest even |
| vec_type trunc ( vec_type ) | Truncation |
| vec_type ceil ( vec_type ) | Ceiling |
| vec_type fract ( vec_type ) | Fractional |
| vec_type mod ( vec_type, vec_type ) | Remainder |
| vec_type mod ( vec_type, float ) | Remainder |
| vec_type modf ( vec_type x, out vec_type i ) | Fractional of x, with i has integer part |
| vec_scalar_type min ( vec_scalar_type a, vec_scalar_type b ) | Minimum |
| vec_scalar_type max ( vec_scalar_type a, vec_scalar_type b ) | Maximum |
| vec_scalar_type clamp ( vec_scalar_type value, vec_scalar_type min, vec_scalar_type max ) | Clamp to Min-Max |
| vec_type mix ( vec_type a, vec_type b, float c ) | Linear Interpolate (Scalar Coef.) |
| vec_type mix ( vec_type a, vec_type b, vec_type c ) | Linear Interpolate (Vector Coef.) |
| vec_type mix ( vec_type a, vec_type b, bool c ) | Linear Interpolate (Bool Selection) |
| vec_type mix ( vec_type a, vec_type b, vec_bool_type c ) | Linear Interpolate (Bool-Vector Selection) |
| vec_type step ( vec_type a, vec_type b ) | ` b[i] < a[i] ? 0.0 : 1.0 ` |
| vec_type step ( float a, vec_type b ) | ` b[i] < a ? 0.0 : 1.0 ` |
| vec_type smoothstep ( vec_type a, vec_type b, vec_type c ) | Hermite Interpolate |
| vec_type smoothstep ( float a, float b, vec_type c ) | Hermite Interpolate |
| vec_bool_type isnan ( vec_type ) | Scalar, or vector component being nan |
| vec_bool_type isinf ( vec_type ) | Scalar, or vector component being inf |
| vec_int_type floatBitsToInt ( vec_type ) | Float->Int bit copying, no conversion |
| vec_uint_type floatBitsToUint ( vec_type ) | Float->UInt bit copying, no conversion |
| vec_type intBitsToFloat ( vec_int_type ) | Int->Float bit copying, no conversion |
| vec_type uintBitsToFloat ( vec_uint_type ) | UInt->Float bit copying, no conversion |
| float length ( vec_type ) | Vector Length |
| float distance ( vec_type, vec_type ) | Distance between vector |
| float dot ( vec_type, vec_type ) | Dot Product |
| vec3 cross ( vec3, vec3 ) | Cross Product |
| vec_type normalize ( vec_type ) | Normalize to unit length |
| vec3 reflect ( vec3 I, vec3 N ) | Reflect |
| vec3 refract ( vec3 I, vec3 N, float eta ) | Refract |
| vec_type faceforward ( vec_type N, vec_type I, vec_type Nref ) | If dot(Nref, I) < 0 return N, otherwise –N |
| mat_type matrixCompMult ( mat_type, mat_type ) | Matrix Component Multiplication |
| mat_type outerProduct ( vec_type, vec_type ) | Matrix Outer Product |
| mat_type transpose ( mat_type ) | Transpose Matrix |
| float determinant ( mat_type ) | Matrix Determinant |
| mat_type inverse ( mat_type ) | Inverse Matrix |
| vec_bool_type lessThan ( vec_scalar_type, vec_scalar_type ) | Bool vector cmp on < int/uint/float vectors |
| vec_bool_type greaterThan ( vec_scalar_type, vec_scalar_type ) | Bool vector cmp on > int/uint/float vectors |
| vec_bool_type lessThanEqual ( vec_scalar_type, vec_scalar_type ) | Bool vector cmp on <= int/uint/float vectors |
| vec_bool_type greaterThanEqual ( vec_scalar_type, vec_scalar_type ) | Bool vector cmp on >= int/uint/float vectors |
| vec_bool_type equal ( vec_scalar_type, vec_scalar_type ) | Bool vector cmp on == int/uint/float vectors |
| vec_bool_type notEqual ( vec_scalar_type, vec_scalar_type ) | Bool vector cmp on != int/uint/float vectors |
| bool any ( vec_bool_type ) | Any component is true |
| bool all ( vec_bool_type ) | All components are true |
| bool not ( vec_bool_type ) | No components are true |
| ivec2 textureSize ( sampler2D_type s, int lod ) | Get the size of a texture |
| ivec2 textureSize ( samplerCube s, int lod ) | Get the size of a cubemap |
| vec4_type texture ( sampler2D_type s, vec2 uv [, float bias] ) | Perform a 2D texture read |
| vec4_type texture ( samplerCube s, vec3 uv [, float bias] ) | Perform a Cube texture read |
| vec4_type textureProj ( sampler2D_type s, vec3 uv [, float bias] ) | Perform a texture read with projection |
| vec4_type textureProj ( sampler2D_type s, vec4 uv [, float bias] ) | Perform a texture read with projection |
| vec4_type textureLod ( sampler2D_type s, vec2 uv, float lod ) | Perform a 2D texture read at custom mipmap |
| vec4_type textureLod ( samplerCube s, vec3 uv, float lod ) | Perform a Cube texture read at custom mipmap |
| vec4_type textureProjLod ( sampler2D_type s, vec3 uv, float lod ) | Perform a texture read with projection/lod |
| vec4_type textureProjLod ( sampler2D_type s, vec4 uv, float lod ) | Perform a texture read with projection/lod |
| vec4_type texelFetch ( sampler2D_type s, ivec2 uv, int lod ) | Fetch a single texel using integer coords |
| vec_type dFdx ( vec_type ) | Derivative in x using local differencing |
| vec_type dFdy ( vec_type ) | Derivative in y using local differencing |
| vec_type fwidth ( vec_type ) | Sum of absolute derivative in x and y |
Shader Types In-Depth¶
Spatial¶
Accepted render modes and built-ins for shader_type spatial;.
Render Modes¶
| Render Mode | Description |
|---|---|
| blend_mix | Mix blend mode (alpha is transparency), default. |
| blend_add | Additive blend mode. |
| blend_sub | Substractive 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_draw_alpha_prepass | Do opaque depth pre-pass for transparent geometry. |
| depth_test_disable | Disable depth testing. |
| cull_front | Cull front-faces. |
| cull_back | Cull back-faces (default). |
| cull_disabled | Culling disabled (double sided). |
| unshaded | Result is just albedo. No lighting/shading happens in material. |
| diffuse_lambert | Lambert shading for diffuse (default). |
| diffuse_lambert_wrap | Lambert wrapping (roughness dependent) for diffuse. |
| diffuse_oren_nayar | Oren Nayar 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 VS. |
| world_vertex_coords | VERTEX/NORMAL/etc are modified in world coordinates instead of local. |
| vertex_lighting | Use vertex-based lighting. |
Vertex Built-Ins¶
| Built-In | Description |
|---|---|
| out mat4 WORLD_MATRIX | Model space to world space transform. |
| in mat4 INV_CAMERA_MATRIX | World space to view space transform. |
| out mat4 PROJECTION_MATRIX | View space to clip space transform. |
| in mat4 CAMERA_MATRIX | View space to world space transform. |
| out mat4 MODELVIEW_MATRIX | Model space to view space transform (use if possible). |
| out mat4 INV_PROJECTION_MATRIX | Clip space to view space transform. |
| in float TIME | Elapsed total time in seconds. |
| in vec2 VIEWPORT_SIZE | Size of viewport (in pixels). |
| out vec3 VERTEX | Vertex in local coords (see doc below). |
| out vec3 NORMAL | Normal in local coords. |
| out vec3 TANGENT | Tangent in local coords. |
| out vec3 BINORMAL | Binormal in local coords. |
| out vec2 UV | UV main channel. |
| out vec2 UV2 | UV secondary channel. |
| out vec4 COLOR | Color from vertices. |
| out float POINT_SIZE | Point size for point rendering. |
| in int INSTANCE_ID | Instance ID for instancing. |
| in vec4 INSTANCE_CUSTOM | Instance custom data (for particles, mostly). |
| out float ROUGHNESS | Roughness for vertex lighting. |
Values marked as “in” are read-only. Values marked as “out” are for optional writing. Samplers are not subjects of writing and they are not marked.
Vertex data (VERTEX, NORMAL, TANGENT, BITANGENT) is presented in local model space. If not written to, these values will not be modified and be passed through as they came.
They can be optionally set to be presented in world space (after being transformed by world) by adding the world_vertex_coords render mode.
It is also possible to completely disable the built-in modelview transform (projection will still happen later, though) with the following code, so it can be done manually:
shader_type spatial;
render_mode skip_vertex_transform;
void vertex() {
VERTEX = (MODELVIEW_MATRIX * vec4(VERTEX, 1.0)).xyz;
NORMAL = (MODELVIEW_MATRIX * vec4(VERTEX, 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.
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 to easily adjust the shader to a particle system using default particles material. When writing a custom particles shader, this value can be used as desired.
Fragment Built-Ins¶
| Built-In | Description |
|---|---|
| in mat4 WORLD_MATRIX | Model space to world space transform. |
| in mat4 INV_CAMERA_MATRIX | World space to view space transform. |
| in mat4 PROJECTION_MATRIX | View space to clip space transform. |
| in mat4 INV_PROJECTION_MATRIX | Clip space to view space transform. |
| in float TIME | Elapsed total time in seconds. |
| in vec2 VIEWPORT_SIZE | Size of viewport (in pixels). |
| in vec3 VERTEX | Vertex that comes from vertex function, in view space. |
| in vec4 FRAGCOORD | Fragment coordinate, pixel adjusted. |
| in bool FRONT_FACING | true whether current face is front face. |
| out vec3 NORMAL | Normal that comes from vertex function, in view space. |
| out vec3 TANGENT | Tangent that comes from vertex function. |
| out vec3 BINORMAL | Binormal that comes from vertex function. |
| out vec3 NORMALMAP | Output this if reading normal from a texture instead of NORMAL. |
| out float NORMALMAP_DEPTH | Depth from variable above. Defaults to 1.0. |
| in vec2 UV | UV that comes from vertex function. |
| in vec2 UV2 | UV2 that comes from vertex function. |
| in vec4 COLOR | COLOR that comes from vertex function. |
| out vec3 ALBEDO | Albedo (default white). |
| out float ALPHA | Alpha (0..1), if written to the material will go to transparent pipeline. |
| out float METALLIC | Metallic (0..1). |
| out float SPECULAR | Specular. Defaults to 0.5, best to not modify unless you want to change IOR. |
| out float ROUGHNESS | Roughness (0..1). |
| out float RIM | Rim (0..1). |
| out float RIM_TINT | Rim Tint, goes from 0 (white) to 1 (albedo). |
| out float CLEARCOAT | Small added specular blob. |
| out float CLEARCOAT_GLOSS | Gloss of Clearcoat. |
| out float ANISOTROPY | For distorting the specular blob according to tangent space. |
| out vec2 ANISOTROPY_FLOW | Distortion direction, use with flowmaps. |
| out float SSS_STRENGTH | Strength of Subsurface Scattering (default 0). |
| out vec3 TRANSMISSION | Transmission mask (default 0,0,0). |
| out float AO | Ambient Occlusion (pre-baked). |
| out float AO_LIGHT_AFFECT | How much AO affects lights (0..1. default 0, none). |
| out vec3 EMISSION | Emission color (can go over 1,1,1 for HDR). |
| sampler2D SCREEN_TEXTURE | Built-in Texture for reading from the screen. Mipmaps contain increasingly blurred copies. |
| sampler2D DEPTH_TEXTURE | Built-in Texture for reading depth from the screen. Must convert to linear using INV_PROJECTION. |
| out vec2 SCREEN_UV | Screen UV coordinate for current pixel. |
| in vec2 POINT_COORD | Point Coord for drawing points with POINT_SIZE. |
| out float ALPHA_SCISSOR | If written to, values below a certain amount of alpha are discarded. |
Light Built-Ins¶
| Built-in | Description |
|---|---|
| in mat4 WORLD_MATRIX | Model space to world space transform. |
| in mat4 INV_CAMERA_MATRIX | World space to view space transform. |
| in mat4 PROJECTION_MATRIX | View space to clip space transform. |
| in mat4 INV_PROJECTION_MATRIX | Clip space to view space transform. |
| in float TIME | Elapsed total time in seconds. |
| in vec2 VIEWPORT_SIZE | Size of viewport (in pixels). |
| in vec3 NORMAL | Normal vector. |
| in vec3 VIEW | View vector. |
| in vec3 LIGHT | Light Vector. |
| in vec3 LIGHT_COLOR | Color of light multiplied by energy. |
| in vec3 ATTENUATION | Attenuation based on distance or shadow. |
| in vec3 ALBEDO | Base albedo. |
| in vec3 TRANSMISSION | Transmission mask. |
| in float ROUGHNESS | Roughness. |
| out vec3 DIFFUSE_LIGHT | Diffuse light result. |
| out vec3 SPECULAR_LIGHT | Specular light result. |
Writing light shaders is completely optional. Unlike other game engines, they don’t affect performance or force a specific pipeline.
To write a light shader, simply make sure to assign something to DIFFUSE_LIGHT or SPECULAR_LIGHT. Assigning nothing means no light is processed.
Canvas Item¶
Accepted render modes and built-ins for shader_type canvas_item;.
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. |
| blend_premul_alpha | Premultiplied alpha blend mode. |
| unshaded | Result is just albedo. No lighting/shading happens in material. |
| light_only | Only draw for light pass (when multipass is used). |
| skip_vertex_transform | VERTEX/NORMAL/etc need to be transformed manually in VS. |
Vertex Built-Ins¶
| Built-In | Description |
|---|---|
| in mat4 WORLD_MATRIX | Image to World transform. |
| in mat4 EXTRA_MATRIX | Extra transform. |
| in mat4 PROJECTION_MATRIX | World to view transform. |
| in float TIME | Global time, in seconds. |
| in vec4 INSTANCE_CUSTOM | Instance custom data. |
| in bool AT_LIGHT_PASS | True if this is a light pass (for multi-pass light rendering). |
| out vec2 VERTEX | Vertex in image space. |
| out vec2 UV | UV. |
| out vec4 COLOR | Color from vertex primitive. |
| out float POINT_SIZE | Point size for point drawing. |
Vertex data (VERTEX) is presented in local space. If not written to, these values will not be modified and be passed through as they came.
It is possible to completely disable the built-in modelview transform (projection will still happen later, though) with the following code, so it can be done manually:
shader_type canvas_item;
render_mode skip_vertex_transform;
void vertex() {
VERTEX = (EXTRA_MATRIX * (WORLD_MATRIX * vec4(VERTEX, 0.0, 1.0))).xy;
}
Other built-ins such as UV and COLOR are also passed through to the fragment function if not modified.
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 to easily adjust the shader to a particle system using default particles material. When writing a custom particles shader, this value can be used as desired.
Fragment Built-Ins¶
| Built-In | Description |
|---|---|
| in vec4 FRAGCOORD | Fragment coordinate, pixel adjusted. |
| out vec3 NORMAL | Normal, writable. |
| out vec3 NORMALMAP | Normal from texture, default is read from NORMAL_TEXTURE. |
| out float NORMALMAP_DEPTH | Normalmap depth for scaling. |
| in vec2 UV | UV from vertex function. |
| out vec4 COLOR | Color from vertex function. |
| sampler2D TEXTURE | Default 2D texture. |
| sampler2D NORMAL_TEXTURE | Default 2D normal texture. |
| in vec2 TEXTURE_PIXEL_SIZE | Default 2D texture pixel size. |
| in vec2 SCREEN_UV | Screen UV for use with SCREEN_TEXTURE. |
| in vec2 SCREEN_PIXEL_SIZE | Size of individual pixels. Equal to inverse of resolution. |
| in vec2 POINT_COORD | Coordinate for drawing points. |
| in float TIME | Global time in seconds. |
| in bool AT_LIGHT_PASS | True if this is a light pass (for multi-pass light rendering). |
| sampler2D SCREEN_TEXTURE | Screen texture, mipmaps contain gaussian blurred versions. |
Light Built-Ins¶
| Built-In | Description |
|---|---|
| in vec2 POSITION | Fragment coordinate, pixel adjusted. |
| in vec3 NORMAL | Input Normal. Although this value is passed in, normal calculation still happens outside of this function. |
| in vec2 UV | UV from vertex function, equivalent to the UV in the fragment function. |
| in vec4 COLOR | Input Color. This is the output of the fragment function with final modulation applied. |
| sampler2D TEXTURE | Current texture in use for CanvasItem. |
| in vec2 TEXTURE_PIXEL_SIZE | Pixel size for current 2D texture. |
| in vec2 SCREEN_UV | Screen Texture Coordinate (for using with texscreen). |
| in vec2 POINT_COORD | Current UV for Point Sprite. |
| in float TIME | Global time in seconds. |
| out vec2 LIGHT_VEC | Vector from light to fragment, can be modified to alter shadow computation. |
| out float LIGHT_HEIGHT | Height of Light. |
| out vec4 LIGHT_COLOR | Color of Light. |
| out vec2 LIGHT_UV | UV for Light texture. |
| out vec4 SHADOW_COLOR | Shadow Color of Light. (not yet implemented) |
| out vec4 LIGHT | Value from the Light texture. (shader is ignored if this is not used). Can be modified. |
Particles¶
Accepted render modes and built-ins for shader_type particles;.
Render Modes¶
| Render Mode | Description |
|---|---|
| keep_data | Do not clear previous data on restart. |
| disable_force | Disable force. |
| disable_velocity | Disable velocity. |
Vertex Built-Ins¶
| Built-In | Description |
|---|---|
| out vec4 COLOR | Particle color, can be written to. |
| out vec3 VELOCITY | Particle velocity, can be modified. |
| out float MASS | Particle mass, use for attractors (default 1). |
| out bool ACTIVE | Particle is active, can be set to false. |
| in bool RESTART | Set to true when particle must restart (lifetime cycled). |
| out vec4 CUSTOM | Custom particle data. |
| out mat4 TRANSFORM | Particle transform. |
| in float TIME | Global time in seconds. |
| in float LIFETIME | Particle lifetime. |
| in float DELTA | Delta process time. |
| in uint NUMBER | Unique number since emission start. |
| in int INDEX | Particle index (from total particles). |
| in mat4 EMISSION_TRANSFORM | Emitter transform (used for non-local systems). |
| in uint RANDOM_SEED | Random seed used as base for random. |
Particle shades only support vertex processing. They are drawn with any regular material for CanvasItem or Spatial, depending on whether they are 2D or 3D.