Add fog shaders to shader refererence

tutorials/shaders/introduction_to_shaders.rst

@@ -40,7 +40,8 @@ look like this.
 
 .. note::
 
-   The graphics card calls the ``fragment()`` function once or more for each pixel it has to draw. More on that below.
+   The graphics card calls the ``fragment()`` function once or more for each
+   pixel it has to draw. More on that below.
 
 Shaders in Godot
 ----------------
@@ -49,18 +50,39 @@ Godot provides a shading language based on the popular OpenGL Shading Language
 (GLSL) but simplified. The engine handles some of the lower-level initialization
 work for you, making it easier to write complex shaders.
 
-In Godot, shaders are made up of three main functions: ``vertex()``,
-``fragment()``, and ``light()``.
+In Godot, shaders are made up of main functions called "processor functions".
+Processor functions are the entry point for your shader into the program. There
+are seven different processor functions.
 
 1. The ``vertex()`` function runs over all the vertices in the mesh and sets
-   their positions and some other per-vertex variables.
+   their positions and some other per-vertex variables. Used in
+   :ref:`canvas_item shaders <doc_canvas_item_shader>` and
+   :ref:`spatial shaders <doc_spatial_shader>`.
 
 2. The ``fragment()`` function runs for every pixel covered by the mesh. It uses
    values output by the ``vertex()`` function, interpolated between the
-   vertices.
+   vertices. Used in :ref:`canvas_item shaders <doc_canvas_item_shader>` and
+   :ref:`spatial shaders <doc_spatial_shader>`.
 
 3. The ``light()`` function runs for every pixel and for every light. It takes
-   variables from the ``fragment()`` function and from its previous runs.
+   variables from the ``fragment()`` function and from its previous runs. Used
+   in :ref:`canvas_item shaders <doc_canvas_item_shader>` and
+   :ref:`spatial shaders <doc_spatial_shader>`.
+
+4. The ``start()`` function runs for every particle in a particle system once
+   when the particle is first spawned. Used in 
+   :ref:`particles shaders <doc_particle_shader>`.
+
+5. The ``process()`` function runs for every particle in a particle system for
+   each frame. Used in :ref:`particles shaders <doc_particle_shader>`.
+
+6. The ``sky()`` function runs for every pixel in the radiance cubemap when the
+   radiance cubemap needs to be updated, and for every pixel on the current
+   screen. Used in :ref:`sky shaders <doc_sky_shader>`.
+
+7. The ``fog()`` function runs for every froxel in the volumetric fog froxel
+   buffer that intersects with the :ref:`FogVolume <class_FogVolume>`. Used by
+   :ref:`fog shaders <doc_fog_shader>`.
 
 .. warning::
 
@@ -73,8 +95,9 @@ Shader types
 ------------
 
 Instead of supplying a general-purpose configuration for all uses (2D, 3D,
-particles), you must specify the type of shader you're writing. Different types
-support different render modes, built-in variables, and processing functions.
+particles, sky, fog), you must specify the type of shader you're writing.
+Different types support different render modes, built-in variables, and
+processing functions.
 
 In Godot, all shaders need to specify their type in the first line, like so:
 
@@ -88,6 +111,7 @@ Here are the available types:
 * :ref:`canvas_item <doc_canvas_item_shader>` for 2D rendering.
 * :ref:`particles <doc_particle_shader>` for particle systems.
 * :ref:`sky <doc_sky_shader>` to render :ref:`Skies <class_Sky>`.
+* :ref:`fog <doc_fog_shader>` to render :ref:`FogVolumes <class_FogVolume>`
 
 Render modes
 ------------
@@ -106,14 +130,6 @@ Render modes alter the way Godot applies the shader. For example, the
 Each shader type has different render modes. See the reference for each shader
 type for a complete list of render modes.
 
-Processor functions
--------------------
-
-Depending on the shader type, you can override different processor functions.
-For ``spatial`` and ``canvas_item``, you have access to ``vertex()``,
-``fragment()``, and ``light()``. For ``particles``, you only have access to
-``vertex()``. For ''sky'', you only have access to ''fragment()''.
-
 Vertex processor
 ^^^^^^^^^^^^^^^^
 

tutorials/shaders/screen-reading_shaders.rst

@@ -33,7 +33,7 @@ because it only shows what lies behind:
     }
 
 The reason why textureLod must be used is because, when Godot copies back
-a chunk of the screen, it also does an efficient separatable gaussian blur to its mipmaps.
+a chunk of the screen, it also does an efficient separable gaussian blur to its mipmaps.
 
 This allows for not only reading from the screen, but reading from it with different amounts
 of blur at no cost.

tutorials/shaders/shader_reference/fog_shader.rst

@@ -0,0 +1,80 @@
+.. _doc_fog_shader:
+
+Fog shaders
+===========
+
+Fog shaders are used to define how fog is added (or subtracted) from a scene in
+a given area. Fog shaders are always used together with
+:ref:`FogVolumes <class_FogVolume>` and volumetric fog. Fog shaders only have
+one processing function, the ``fog()`` function.
+
+The resolution of the fog shaders depends on the resolution of the
+volumetric fog froxel grid. Accordingly, the level of detail that a fog shader
+can add depends on how close the :ref:`FogVolume <class_FogVolume>` is to the
+camera.
+
+Fog shaders are a special form of compute shader that is called once for
+every froxel that is touched by an axis aligned bounding box of the associated
+:ref:`FogVolume <class_FogVolume>`. This means that froxels that just barely
+touch a given :ref:`FogVolume <class_FogVolume>` will still be used. 
+
+Built-ins
+^^^^^^^^^
+
+Values marked as "in" are read-only. Values marked as "out" are for optional
+writing and will not necessarily contain sensible values. Samplers cannot be 
+written to so they are not marked.
+
+
+Global built-ins
+^^^^^^^^^^^^^^^^
+
+Global built-ins are available everywhere, including in custom functions.
+
+
++---------------------------------+-----------------------------------------------------------------------------------------+
+| Built-in                        | Description                                                                             |
++=================================+=========================================================================================+
+| in float **TIME**               | Global time, in seconds.                                                                |
++---------------------------------+-----------------------------------------------------------------------------------------+
+| in float **PI**                 | A ``PI`` constant (``3.141592``).                                                       |
+|                                 | A ratio of a 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.                                     |
++---------------------------------+-----------------------------------------------------------------------------------------+
+
+Fog built-ins
+^^^^^^^^^^^^^
+
+All of the output values of fog volumes overlap one another. This allows
+:ref:`FogVolumes <class_FogVolume>` to be rendered efficiently as they can all
+be drawn at once.
+
++-------------------------------+-------------------------------------------------------------------------------------------------+
+| Built-in                      | Description                                                                                     |
++===============================+=================================================================================================+
+| in vec3 **WORLD_POSITION**    | Position of current froxel cell in world space.                                                 |
++-------------------------------+-------------------------------------------------------------------------------------------------+
+| in vec3 **OBJECT_POSITION**   | Position of current froxel cell relative to the center of the current                           |
+|                               | :ref:`FogVolume <class_FogVolume>`.                                                             |
++-------------------------------+-------------------------------------------------------------------------------------------------+
+| in vec3 **UVW**               | 3-dimensional uv, used to map a 3D texture to the current :ref:`FogVolume <class_FogVolume>`.   |
++-------------------------------+-------------------------------------------------------------------------------------------------+
+| in vec3 **EXTENTS**           | Color value of corresponding pixel from half resolution pass. Uses linear filter.               |
++-------------------------------+-------------------------------------------------------------------------------------------------+
+| in vec3 **SDF**               | Signed distance field to the surface of the :ref:`FogVolume <class_FogVolume>`. Negative if     |
+|                               | inside volume, positive otherwise.                                                              |
++-------------------------------+-------------------------------------------------------------------------------------------------+
+| out vec3 **ALBEDO**           | Output base color value, interacts with light to produce final color. Only written to fog       |
+|                               | volume if used.                                                                                 |
++-------------------------------+-------------------------------------------------------------------------------------------------+
+| out float **DENSITY**         | Output density value. Can be negative to allow subtracting one volume from another. Density     |
+|                               | must be used for fog shader to write anything at all.                                           |
++-------------------------------+-------------------------------------------------------------------------------------------------+
+| out vec3 **EMISSION**         | Output emission color value, added to color during light pass to produce final color. Only      |
+|                               | written to fog volume if used.                                                                  |
++-------------------------------+-------------------------------------------------------------------------------------------------+

tutorials/shaders/shader_reference/index.rst

@@ -10,3 +10,4 @@ Shading reference
    canvas_item_shader
    particle_shader
    sky_shader
+   fog_shader

tutorials/shaders/shader_reference/sky_shader.rst

@@ -5,7 +5,7 @@ Sky shaders
 
 Sky shaders are a special type of shader used for drawing sky backgrounds
 and for updating radiance cubemaps which are used for image-based lighting
-(IBL). Sky shaders only have one processing function, the ``fragment()``
+(IBL). Sky shaders only have one processing function, the ``sky()``
 function.
 
 There are three places the sky shader is used.
@@ -55,7 +55,7 @@ the radiance cubemap:
 * ``TIME`` is used.
 * ``POSITION`` is used and the camera position changes.
 * If any ``LIGHTX_*`` properties are used and any
-  :ref:`DirectionalLight3D <class_DirectionalLight>` changes.
+  :ref:`DirectionalLight3D <class_DirectionalLight3D>` changes.
 * If any uniform is changed in the shader.
 * If the screen is resized and either of the subpasses are used.
 
@@ -102,15 +102,14 @@ a lower resolution than the rest of the sky:
 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.
+Values marked as "in" are read-only. Values marked as "out" are for optional
+writing and will not necessarily contain sensible values. Samplers cannot be 
+written to so they are not marked.
 
 Global built-ins
 ^^^^^^^^^^^^^^^^
 
-Global built-ins are available everywhere, including custom functions.
+Global built-ins are available everywhere, including in custom functions.
 
 There are 4 ``LIGHTX`` lights, accessed as ``LIGHT0``, ``LIGHT1``, ``LIGHT2``, and ``LIGHT3``.
 
@@ -141,7 +140,7 @@ There are 4 ``LIGHTX`` lights, accessed as ``LIGHT0``, ``LIGHT1``, ``LIGHT2``, a
 | in float **LIGHTX_SIZE**        | Angular diameter of ``LIGHTX`` in the sky. Expressed in degrees. For reference, the sun from earth is about 0.5 degrees. |
 +---------------------------------+--------------------------------------------------------------------------------------------------------------------------+
 | in float **PI**                 | A ``PI`` constant (``3.141592``).                                                                                        |
-|                                 | A ration of circle's circumference to its diameter and amount of radians in half turn.                                   |
+|                                 | A ratio of a 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.                                                          |