Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add newly shader built-ins to docs backport #6152

Merged
merged 1 commit into from
Sep 8, 2022
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
119 changes: 60 additions & 59 deletions tutorials/shaders/shader_reference/spatial_shader.rst
Original file line number Diff line number Diff line change
Expand Up @@ -135,50 +135,58 @@ is usually:
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). |
+--------------------------------------+-------------------------------------------------------+
| inout mat4 **WORLD_MATRIX** | Model space to world space transform. |
+--------------------------------------+-------------------------------------------------------+
| in mat4 **INV_CAMERA_MATRIX** | World space to view space transform. |
+--------------------------------------+-------------------------------------------------------+
| inout mat4 **PROJECTION_MATRIX** | View space to clip space transform. |
+--------------------------------------+-------------------------------------------------------+
| in mat4 **CAMERA_MATRIX** | View space to world space transform. |
+--------------------------------------+-------------------------------------------------------+
| inout mat4 **MODELVIEW_MATRIX** | Model space to view space transform (use if possible).|
+--------------------------------------+-------------------------------------------------------+
| inout mat4 **INV_PROJECTION_MATRIX** | Clip space to view space transform. |
+--------------------------------------+-------------------------------------------------------+
| inout vec3 **VERTEX** | Vertex in local coordinates. |
+--------------------------------------+-------------------------------------------------------+
| out vec4 **POSITION** | If written to, overrides final vertex position. |
+--------------------------------------+-------------------------------------------------------+
| inout vec3 **NORMAL** | Normal in local coordinates. |
+--------------------------------------+-------------------------------------------------------+
| inout vec3 **TANGENT** | Tangent in local coordinates. |
+--------------------------------------+-------------------------------------------------------+
| inout vec3 **BINORMAL** | Binormal in local coordinates. |
+--------------------------------------+-------------------------------------------------------+
| out float **ROUGHNESS** | Roughness for vertex lighting. |
+--------------------------------------+-------------------------------------------------------+
| inout vec2 **UV** | UV main channel. |
+--------------------------------------+-------------------------------------------------------+
| inout vec2 **UV2** | UV secondary channel. |
+--------------------------------------+-------------------------------------------------------+
| in bool **OUTPUT_IS_SRGB** | ``true`` when calculations happen in sRGB color space |
| | (``true`` in GLES2, ``false`` in GLES3). |
+--------------------------------------+-------------------------------------------------------+
| inout vec4 **COLOR** | Color from vertices. |
+--------------------------------------+-------------------------------------------------------+
| inout 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). |
+--------------------------------------+-------------------------------------------------------+
+--------------------------------------+--------------------------------------------------------+
| Built-in | Description |
+======================================+========================================================+
| in vec2 **VIEWPORT_SIZE** | Size of viewport (in pixels). |
+--------------------------------------+--------------------------------------------------------+
| inout mat4 **WORLD_MATRIX** | Model space to world space transform. |
+--------------------------------------+--------------------------------------------------------+
| in mat4 **INV_CAMERA_MATRIX** | World space to view space transform. |
+--------------------------------------+--------------------------------------------------------+
| inout mat4 **PROJECTION_MATRIX** | View space to clip space transform. |
+--------------------------------------+--------------------------------------------------------+
| in mat4 **CAMERA_MATRIX** | View space to world space transform. |
+--------------------------------------+--------------------------------------------------------+
| inout mat4 **MODELVIEW_MATRIX** | Model space to view space transform (use if possible). |
+--------------------------------------+--------------------------------------------------------+
| inout mat4 **INV_PROJECTION_MATRIX** | Clip space to view space transform. |
+--------------------------------------+--------------------------------------------------------+
| in vec3 **NODE_POSITION_WORLD** | Node position, in world space. |
+--------------------------------------+--------------------------------------------------------+
| in vec3 **NODE_POSITION_VIEW** | Node position, in view space. |
+--------------------------------------+--------------------------------------------------------+
| in vec3 **CAMERA_POSITION_WORLD** | Camera position, in world space. |
+--------------------------------------+--------------------------------------------------------+
| in vec3 **CAMERA_DIRECTION_WORLD** | Camera direction, in world space. |
+--------------------------------------+--------------------------------------------------------+
| inout vec3 **VERTEX** | Vertex in local coordinates. |
+--------------------------------------+--------------------------------------------------------+
| out vec4 **POSITION** | If written to, overrides final vertex position. |
+--------------------------------------+--------------------------------------------------------+
| inout vec3 **NORMAL** | Normal in local coordinates. |
+--------------------------------------+--------------------------------------------------------+
| inout vec3 **TANGENT** | Tangent in local coordinates. |
+--------------------------------------+--------------------------------------------------------+
| inout vec3 **BINORMAL** | Binormal in local coordinates. |
+--------------------------------------+--------------------------------------------------------+
| out float **ROUGHNESS** | Roughness for vertex lighting. |
+--------------------------------------+--------------------------------------------------------+
| inout vec2 **UV** | UV main channel. |
+--------------------------------------+--------------------------------------------------------+
| inout vec2 **UV2** | UV secondary channel. |
+--------------------------------------+--------------------------------------------------------+
| in bool **OUTPUT_IS_SRGB** | ``true`` when calculations happen in sRGB color space |
| | (``true`` in GLES2, ``false`` in GLES3). |
+--------------------------------------+--------------------------------------------------------+
| inout vec4 **COLOR** | Color from vertices. |
+--------------------------------------+--------------------------------------------------------+
| inout 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). |
+--------------------------------------+--------------------------------------------------------+

.. note::

Expand All @@ -191,21 +199,6 @@ The default use of a Godot fragment processor function is to set up the material
and to let the built-in renderer handle the final shading. However, you are not required to use all
these properties, and if you don't write to them, Godot will optimize away the corresponding functionality.

Below are examples of common variables calculated using the built-ins:

.. code-block:: glsl

vec3 model_world_space = WORLD_MATRIX[3].xyz; // Object's world space position. This is the equivalent to global_transform.origin in GDScript.
mat3 model_transform_basis = mat3(WORLD_MATRIX); // Object's world space transform basis. This is the equivalent to global_transform.basis in GDScript.
vec3 camera_world_space = CAMERA_MATRIX[3].xyz; // Camera's world space position. This is the equivalent to camera.global_transform.origin in GDScript.
vec3 camera_eye_world_space = INV_CAMERA_MATRIX[3].xyz; // Camera eye vector in world space direction of the camera.
vec3 camera_to_object_world_space = normalize(WORLD_MATRIX[3].xyz - CAMERA_MATRIX[3].xyz); // Camera's direction to the object in world space.

.. note::

A commonly used alternative to ``WORLD_MATRIX[3].xyz`` is to use ``vec3 origin = (WORLD_MATRIX * vec4(0,0,0,1)).xyz``. It is more efficient to use ``WORLD_MATRIX[3].xyz`` as it avoids the matrix multiplication.


+-----------------------------------+--------------------------------------------------------------------------------------------------+
| Built-in | Description |
+===================================+==================================================================================================+
Expand All @@ -224,6 +217,14 @@ Below are examples of common variables calculated using the built-ins:
+-----------------------------------+--------------------------------------------------------------------------------------------------+
| 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 vec3 **VERTEX** | Vertex that comes from vertex function (default, in view space). |
+-----------------------------------+--------------------------------------------------------------------------------------------------+
| in vec3 **VIEW** | Vector from camera to fragment position (in view space). |
Expand Down