godot-docs/reference/shading_language.rst

Shading Language
================

Introduction
------------

Godot uses a simplified shader language (almost a subset of GLSL).
Shaders can be used for:

-  Materials
-  Post-Processing
-  2D

and are divided in *Vertex*, *Fragment* and *Light* sections.

Language
--------

Typing
~~~~~~

The language is statically type and supports only a few operations.
Arrays, classes, structures, etc are not supported. Several built-in
datatypes are provided:

Data Types
~~~~~~~~~~

+-------------------+--------------------------------------------------------------+
| DataType          | Description                                                  |
+===================+==============================================================+
| *void*            | Void                                                         |
+-------------------+--------------------------------------------------------------+
| *bool*            | boolean (true or false)                                      |
+-------------------+--------------------------------------------------------------+
| *float*           | floating point                                               |
+-------------------+--------------------------------------------------------------+
| *vec2*            | 2-component vector, float subindices (x,y or r,g )           |
+-------------------+--------------------------------------------------------------+
| *vec3*            | 3-component vector, float subindices (x,y,z or r,g,b )       |
+-------------------+--------------------------------------------------------------+
| *vec4*, *color*   | 4-component vector, float subindices (x,y,z,w or r,g,b,a )   |
+-------------------+--------------------------------------------------------------+
| *mat2*            | 2x2 matrix, vec3 subindices (x,y)                            |
+-------------------+--------------------------------------------------------------+
| *mat3*            | 3x3 matrix, vec3 subindices (x,y,z)                          |
+-------------------+--------------------------------------------------------------+
| *mat4*            | 4x4 matrix, vec4 subindices (x,y,z,w)                        |
+-------------------+--------------------------------------------------------------+
| *texture*         | texture sampler, can only be used as uniform                 |
+-------------------+--------------------------------------------------------------+
| *cubemap*         | cubemap sampler, can only be used as uniform                 |
+-------------------+--------------------------------------------------------------+

Syntax
~~~~~~

| The syntax is similar to C, with statements ending in ; , and comments
  as // and /\* \*/.
| Example:

::

    float a = 3;
    vec3 b;
    b.x = a;

Swizzling
~~~~~~~~~

It is possible to use swizzling to reasigning subindices or groups of
subindices, in order:

::

    vec3 a = vec3(1,2,3);
    vec3 b = a.zyx; // b will contain vec3(3,2,1)
    vec2 c = a.xy; // c will contain vec2(1,2)
    vec4 d = a.xyzz; // d will contain vec4(1,2,3,3)

Constructors
~~~~~~~~~~~~

Constructors take the regular amount of elements, but can also accept
less if the element has more subindices, for example:

::

    vec3 a = vec3( 1, vec2(2,3) );
    vec3 b = vec3( a );
    vec3 c = vec3( vec2(2,3), 1 );
    vec4 d = vec4( a, 5 );
    mat3 m = mat3( a,b,c );

Conditionals
~~~~~~~~~~~~

For now, only the "if" conditional is supported. Example:

::

    if (a < b) {
       c = b;
    }

Uniforms
~~~~~~~~

A variable can be declared as uniform. In this case, it's value will
come from outside the shader (it will be the responsibility of the
material or whatever using the shader to provide it).

::

    uniform vec3 direction;
    uniform color tint;

    vec3 result = tint.rgb * direction;

Functions
~~~~~~~~~

Simple support for functions is provided. Functions can't access
uniforms or other shader variables.

::

    vec3 addtwo( vec3 a, vec3 b) {

        return a+b;
    }

    vec3 c = addtwo(vec3(1,1,1)+vec3(2,2,2));

Built-In Functions
------------------

Several Built-in functions are provided for convenience, listed as
follows:

| \|\ *. Function \|*. Description \|
| \| float *sin*\ ( float ) \| Sine \|
| \| float *cos*\ ( float ) \| Cosine \|
| \| float *tan*\ ( float ) \| Tangent \|
| \| float *asin*\ ( float ) \| arc-Sine \|
| \| float *acos*\ ( float ) \| arc-Cosine \|
| \| float *atan*\ ( float ) \| arc-Tangent \|
| \| vec\_type *pow*\ ( vec\_type, float ) \| Power \|
| \| vec\_type *pow*\ ( vec\_type, vec\_type ) \| Power (Vec. Exponent)
  \|
| \| vec\_type *exp*\ ( vec\_type ) \| Base-e Exponential \|
| \| vec\_type *log*\ ( vec\_type ) \| Natural Logarithm \|
| \| vec\_type *sqrt*\ ( vec\_type ) \| Square Root \|
| \| vec\_type *abs*\ ( vec\_type ) \| Absolute \|
| \| vec\_type *sign*\ ( vec\_type ) \| Sign \|
| \| vec\_type *floor*\ ( vec\_type ) \| Floor \|
| \| vec\_type *trunc*\ ( vec\_type ) \| Trunc \|
| \| vec\_type *ceil*\ ( vec\_type ) \| Ceiling \|
| \| vec\_type *fract*\ ( vec\_type ) \| Fractional \|
| \| vec\_type *mod*\ ( vec\_type,vec\_type ) \| Remainder \|
| \| vec\_type *min*\ ( vec\_type,vec\_type ) \| Minimum \|
| \| vec\_type *min*\ ( vec\_type,vec\_type ) \| Maximum \|
| \| vec\_type *clamp*\ ( vec\_type value,vec\_type min, vec\_type max )
  \| Clamp to Min-Max \|
| \| vec\_type *mix*\ ( vec\_type a,vec\_type b, float c ) \| Linear
  Interpolate \|
| \| vec\_type *mix*\ ( vec\_type a,vec\_type b, vec\_type c ) \| Linear
  Interpolate (Vector Coef.)\|
| \| vec\_type *step*\ ( vec\_type a,vec\_type b) \| \` a[i] < b[i] ?
  0.0 : 1.0\`\|
| \| vec\_type *smoothstep*\ ( vec\_type a,vec\_type b,vec\_type c) \|
  \|
| \| float *length*\ ( vec\_type ) \| Vector Length \|
| \| float *distance*\ ( vec\_type, vec\_type ) \| Distance between
  vector. \|
| \| float *dot*\ ( vec\_type, vec\_type ) \| Dot Product \|
| \| vec3 *dot*\ ( vec3, vec3 ) \| Cross Product \|
| \| vec\_type *normalize*\ ( vec\_type ) \| Normalize to unit length \|
| \| vec3 *reflect*\ ( vec3, vec3 ) \| Reflect \|
| \| color *tex*\ ( texture, vec2 ) \| Read from a texture in
  noormalized coords \|
| \| color *texcube*\ ( texture, vec3 ) \| Read from a cubemap \|
| \| color *texscreen*\ ( vec2 ) \| Read from screen (generates a copy)
  \|

Built-In Variables
------------------

Depending on the shader type, several built-in variables are available,
listed as follows:

Material - VertexShader
~~~~~~~~~~~~~~~~~~~~~~~

| \|\ *. Variable \|*. Description \|
| \| const vec3 *SRC\_VERTEX* \| Model-Space Vertex \|
| \| const vec3 *SRC\_NORMAL* \| Model-Space Normal \|
| \| const vec3 *SRC\_TANGENT* \| Model-Space Tangent \|
| \| const float *SRC\_BINORMALF* \| Direction to Compute Binormal \|
| \| vec3 *VERTEX* \| View-Space Vertex \|
| \| vec3 *NORMAL* \| View-Space Normal \|
| \| vec3 *TANGENT* \| View-Space Tangent \|
| \| vec3 *BINORMAL* \| View-Space Binormal \|
| \| vec2 *UV* \| UV \|
| \| vec2 *UV2* \| UV2 \|
| \| color *COLOR* \| Vertex Color \|
| \| out vec4 *VAR1* \| Varying 1 Output \|
| \| out vec4 *VAR2* \| Varying 2 Output \|
| \| out float *SPEC\_EXP* \| Specular Exponent (for Vertex Lighting) \|
| \| out float *POINT\_SIZE* \| Point Size (for points) \|
| \| const mat4 *WORLD\_MATRIX* \| Object World Matrix \|
| \| const mat4 *INV\_CAMERA\_MATRIX* \| Inverse Camera Matrix \|
| \| const mat4 *PROJECTION\_MATRIX* \| Projection Matrix \|
| \| const mat4 *MODELVIEW\_MATRIX* \| (InvCamera \* Projection) \|
| \| const float *INSTANCE\_ID* \| Instance ID (for multimesh)\|
| \| const float *TIME* \| Time (in seconds) \|

Material - FragmentShader
~~~~~~~~~~~~~~~~~~~~~~~~~

+----------------------------------+----------------------------------------------------------------------------------+
| Variable                         | Description                                                                      |
+==================================+==================================================================================+
| const vec3 *VERTEX*              | View-Space vertex                                                                |
+----------------------------------+----------------------------------------------------------------------------------+
| const vec4 *POSITION*            | View-Space Position                                                              |
+----------------------------------+----------------------------------------------------------------------------------+
| const vec3 *NORMAL*              | View-Space Normal                                                                |
+----------------------------------+----------------------------------------------------------------------------------+
| const vec3 *TANGENT*             | View-Space Tangent                                                               |
+----------------------------------+----------------------------------------------------------------------------------+
| const vec3 *BINORMAL*            | View-Space Binormal                                                              |
+----------------------------------+----------------------------------------------------------------------------------+
| const vec3 *NORMALMAP*           | Alternative to NORMAL, use for normal texture output.                            |
+----------------------------------+----------------------------------------------------------------------------------+
| const vec3 *NORMALMAP\_DEPTH*    | Complementary to the above, allows changing depth of normalmap.                  |
+----------------------------------+----------------------------------------------------------------------------------+
| const vec2 *UV*                  | UV                                                                               |
+----------------------------------+----------------------------------------------------------------------------------+
| const vec2 *UV2*                 | UV2                                                                              |
+----------------------------------+----------------------------------------------------------------------------------+
| const color *COLOR*              | Vertex Color                                                                     |
+----------------------------------+----------------------------------------------------------------------------------+
| const vec4 *VAR1*                | Varying 1                                                                        |
+----------------------------------+----------------------------------------------------------------------------------+
| const vec4 *VAR2*                | Varying 2                                                                        |
+----------------------------------+----------------------------------------------------------------------------------+
| const vec2 *SCREEN\_UV*          | Screen Texture Coordinate (for using with texscreen)                             |
+----------------------------------+----------------------------------------------------------------------------------+
| const float *TIME*               | Time (in seconds)                                                                |
+----------------------------------+----------------------------------------------------------------------------------+
| const vec2 *POINT\_COORD*        | UV for point, when drawing point sprites.                                        |
+----------------------------------+----------------------------------------------------------------------------------+
| out vec3 *DIFFUSE*               | Diffuse Color                                                                    |
+----------------------------------+----------------------------------------------------------------------------------+
| out vec4 *DIFFUSE\_ALPHA*        | Diffuse Color with Alpha (using this sends geometry to alpha pipeline)           |
+----------------------------------+----------------------------------------------------------------------------------+
| out vec3 *SPECULAR*              | Specular Color                                                                   |
+----------------------------------+----------------------------------------------------------------------------------+
| out vec3 *EMISSION*              | Emission Color                                                                   |
+----------------------------------+----------------------------------------------------------------------------------+
| out float *SPEC\_EXP*            | Specular Exponent (Fragment Version)                                             |
+----------------------------------+----------------------------------------------------------------------------------+
| out float *GLOW*                 | Glow                                                                             |
+----------------------------------+----------------------------------------------------------------------------------+
| out mat4 *INV\_CAMERA\_MATRIX*   | Inverse camera matrix, can be used to obtain world coords (see example below).   |
+----------------------------------+----------------------------------------------------------------------------------+

Material - LightShader
~~~~~~~~~~~~~~~~~~~~~~

+--------------------------------+-------------------------------+
| Variable                       | Description                   |
+================================+===============================+
| const vec3 *NORMAL*            | View-Space normal             |
+--------------------------------+-------------------------------+
| const vec3 *LIGHT\_DIR*        | View-Space Light Direction    |
+--------------------------------+-------------------------------+
| const vec3 *EYE\_VEC*          | View-Space Eye-Point Vector   |
+--------------------------------+-------------------------------+
| const vec3 *DIFFUSE*           | Material Diffuse Color        |
+--------------------------------+-------------------------------+
| const vec3 *LIGHT\_DIFFUSE*    | Light Diffuse Color           |
+--------------------------------+-------------------------------+
| const vec3 *SPECULAR*          | Material Specular Color       |
+--------------------------------+-------------------------------+
| const vec3 *LIGHT\_SPECULAR*   | Light Specular Color          |
+--------------------------------+-------------------------------+
| const float *SPECULAR\_EXP*    | Specular Exponent             |
+--------------------------------+-------------------------------+
| const vec1 *SHADE\_PARAM*      | Generic Shade Parameter       |
+--------------------------------+-------------------------------+
| const vec2 *POINT\_COORD*      | Current UV for Point Sprite   |
+--------------------------------+-------------------------------+
| out vec2 *LIGHT*               | Resulting Light               |
+--------------------------------+-------------------------------+
| const float *TIME*             | Time (in seconds)             |
+--------------------------------+-------------------------------+

CanvasItem (2D) - VertexShader
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

| \|\ *. Variable \|*. Description \|
| \| const vec2 *SRC\_VERTEX* \| CanvasItem space vertex. \|
| \| vec2 *UV* \| UV \|
| \| out vec2 *VERTEX* \| Output LocalSpace vertex. \|
| \| out vec2 *WORLD\_VERTEX* \| Output WorldSpace vertex. (use this or
  the one above) \|
| \| color *COLOR* \| Vertex Color \|
| \| out vec4 *VAR1* \| Varying 1 Output \|
| \| out vec4 *VAR2* \| Varying 2 Output \|
| \| out float *POINT\_SIZE* \| Point Size (for points) \|
| \| const mat4 *WORLD\_MATRIX* \| Object World Matrix \|
| \| const mat4 *EXTRA\_MATRIX* \| Extra (user supplied) matrix via
  `CanvasItem.draw\_set\_transform() <https://github.com/okamstudio/godot/wiki/class_canvasitem#draw_set_transform>`__.
  Identity by default. \|
| \| const mat4 *PROJECTION\_MATRIX* \| Projection Matrix (model coords
  to screen).\|
| \| const float *TIME* \| Time (in seconds) \|

CanvasItem (2D) - FragmentShader
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

| \|\ *. Variable \|*. Description \|
| \| const vec4 *SRC\_COLOR* \| Vertex color \|
| \| const vec4 *POSITION* \| Screen Position \|
| \| vec2 *UV* \| UV \|
| \| out color *COLOR* \| Output Color \|
| \| out vec3 *NORMAL* \| Optional Normal (used for 2D Lighting) \|
| \| out vec3 *NORMALMAP* \| Optional Normal in standard normalmap
  format (flipped y and Z from 0 to 1) \|
| \| out float *NORMALMAP\_DEPTH* \| Depth option for above normalmap
  output, default value is 1.0 \|
| \| const texture *TEXTURE* \| Current texture in use for CanvasItem \|
| \| const vec2 *TEXTURE\_PIXEL\_SIZE* \| Pixel size for current 2D
  texture \|
| \| in vec4 *VAR1* \| Varying 1 Output \|
| \| in vec4 *VAR2* \| Varying 2 Output \|
| \| const vec2 *SCREEN\_UV*\ \| Screen Texture Coordinate (for using
  with texscreen) \|
| \| const vec2 *POINT\_COORD* \| Current UV for Point Sprite \|
| \| const float *TIME*\ \| Time (in seconds) \|

CanvasItem (2D) - LightShader
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

| \|\ *. Variable \|*. Description \|
| \| const vec4 *POSITION* \| Screen Position \|
| \| in vec3 *NORMAL* \| Input Normal \|
| \| in vec2 *UV* \| UV \|
| \| in color *COLOR* \| Input Color \|
| \| const texture *TEXTURE* \| Current texture in use for CanvasItem \|
| \| const vec2 *TEXTURE\_PIXEL\_SIZE* \| Pixel size for current 2D
  texture \|
| \| in vec4 *VAR1* \| Varying 1 Output \|
| \| in vec4 *VAR2* \| Varying 2 Output \|
| \| const vec2 *SCREEN\_UV*\ \| Screen Texture Coordinate (for using
  with texscreen) \|
| \| const vec2 *POINT\_COORD* \| Current UV for Point Sprite \|
| \| const float *TIME*\ \| Time (in seconds) \|
| \| vec2 *LIGHT\_VEC* \| Vector from light to fragment, can be modified
  to alter shadow computation. \|
| \| const float *LIGHT\_HEIGHT* \| Height of Light \|
| \| const color *LIGHT\_COLOR* \| Color of Light \|
| \| out vec4 *LIGHT* \| Light Ouput (shader is ignored if this is not
  used) \|

Examples
--------

Material that reads a texture, a color and multiples them, fragment
program:

::

    uniform color modulate;
    uniform texture source;

    DIFFUSE = modulate.rgb * tex(source,UV).rgb;

Material that glows from red to white:

::

    DIFFUSE = vec3(1,0,0) + vec(1,1,1)*mod(TIME,1.0);

Standard Blinn Lighting Shader

::

    float NdotL = max(0.0,dot( NORMAL, LIGHT_DIR ));
    vec3 half_vec = normalize(LIGHT_DIR + EYE_VEC);
    float eye_light = max(dot(NORMAL, half_vec),0.0);
    LIGHT = LIGHT_DIFFUSE + DIFFUSE + NdotL;
    if (NdotL > 0.0) {
        LIGHT+=LIGHT_SPECULAR + SPECULAR + pow( eye_light, SPECULAR_EXP );
    };

Obtaining world-space normal and position in material fragment program:

::

    //use reverse multiply because INV_CAMERA_MATRIX is world2cam

    vec3 world_normal = NORMAL * mat3(INV_CAMERA_MATRIX);
    vec3 world_pos = (VERTEX-INV_CAMERA_MATRIX.w.xyz) * mat3(INV_CAMERA_MATRIX);

Notes
-----

| \* **Do not** use DIFFUSE\_ALPHA unless you really intend to use
  transparency. Transparent materials must be sorted by depth and slow
  down the rendering pipeline. For opaque materials, just use DIFFUSE.
| \* **Do not** use DISCARD unless you really need it. Discard makes
  rendering slower, specially on mobile devices.
| \* TIME may reset after a while (may last an hour or so), it's meant
  for effects that vary over time.
| \* In general, every built-in variable not used results in less shader
  code generated, so writing a single giant shader with a lot of code
  and optional scenarios is often not a good idea.