Merge pull request #4217 from NathanLovato/refactor/move-pages

Move and rename shader pages

about/docs_changelog.rst

@@ -50,7 +50,7 @@ Shading
 ^^^^^^^
 
 - Your First Shader Series:
-    - :ref:`doc_what_are_shaders`
+    - :ref:`doc_introduction_to_shaders`
     - :ref:`doc_your_first_canvasitem_shader`
     - :ref:`doc_your_first_spatial_shader`
     - :ref:`doc_your_second_spatial_shader`
@@ -169,7 +169,7 @@ Viewports
 Shading
 ^^^^^^^
 
-- :ref:`doc_migrating_to_godot_shader_language`
+- :ref:`doc_converting_glsl_to_godot_shaders`
 - :ref:`doc_advanced_postprocessing`
 
 Shading Reference:

classes/class_shader.rst

@@ -25,7 +25,7 @@ Tutorials
 
 - :doc:`../tutorials/shading/index`
 
-- :doc:`../tutorials/shading/your_first_shader/what_are_shaders`
+- :ref:`doc_introduction_to_shaders`
 
 Properties
 ----------

tutorials/shading/migrating_to_godot_shader_language.rst → tutorials/shading/converting_glsl_to_godot_shaders.rst

@@ -1,86 +1,92 @@
-.. _doc_migrating_to_godot_shader_language:
+.. _doc_converting_glsl_to_godot_shaders:
 
-Migrating to Godot's shading language
-=====================================
+Converting GLSL to Godot shaders
+================================
 
-Introduction
-------------
+This document explains the differences between Godot's shading language and GLSL
+and gives practical advice on how to migrate shaders from other sources, such as
+Shadertoy and The Book of Shaders, into Godot shaders.
 
-This document explains the differences between Godot's shading language
-and GLSL and gives practical advice on how to migrate shaders from other
-sources, such as Shadertoy and The Book of Shaders, into Godot shaders.
-
-For detailed information on Godot's shading language, please refer to the :ref:`Shading Language <doc_shading_language>`
-reference.
+For detailed information on Godot's shading language, please refer to the
+:ref:`Shading Language <doc_shading_language>` reference.
 
 GLSL
 ----
 
-Godot uses a shading language based on GLSL with the addition of a few quality-of-life features.
-Accordingly, most features available in GLSL are available in Godot's shading language.
+Godot uses a shading language based on GLSL with the addition of a few
+quality-of-life features. Accordingly, most features available in GLSL are
+available in Godot's shading language.
 
 Shader programs
 ^^^^^^^^^^^^^^^
 
-In GLSL, each shader uses a separate program. You have one program for the vertex shader and one
-for the fragment shader. In Godot, you have a single shader that contains a ``vertex`` and/or a
-``fragment`` function. If you only choose to write one, Godot will supply the other.
+In GLSL, each shader uses a separate program. You have one program for the
+vertex shader and one for the fragment shader. In Godot, you have a single
+shader that contains a ``vertex`` and/or a ``fragment`` function. If you only
+choose to write one, Godot will supply the other.
 
-Godot allows uniform variables and functions to be shared by defining the fragment and vertex
-shaders in one file. In GLSL, the vertex and fragment programs cannot share variables except
-when varyings are used.
+Godot allows uniform variables and functions to be shared by defining the
+fragment and vertex shaders in one file. In GLSL, the vertex and fragment
+programs cannot share variables except when varyings are used.
 
 Vertex attributes
 ^^^^^^^^^^^^^^^^^
 
-In GLSL, you can pass in per-vertex information using attributes and have the flexibility to
-pass in as much or as little as you want. In Godot, you have a set number of input attributes,
-including ``VERTEX`` (position), ``COLOR``, ``UV``, ``UV2``, ``NORMAL``. For a complete list,
-see the :ref:`Shading language reference <doc_shading_language>`.
+In GLSL, you can pass in per-vertex information using attributes and have the
+flexibility to pass in as much or as little as you want. In Godot, you have a
+set number of input attributes, including ``VERTEX`` (position), ``COLOR``,
+``UV``, ``UV2``, ``NORMAL``. For a complete list, see the :ref:`Shading language
+reference <doc_shading_language>`.
 
 gl_Position
 ^^^^^^^^^^^
 
-``gl_Position`` receives the final position of a vertex specified in the vertex shader.
-It is specified by the user in clip space. Typically, in GLSL, the model space vertex position
-is passed in using a vertex attribute called ``position`` and you handle the
-conversion from model space to clip space manually.
+``gl_Position`` receives the final position of a vertex specified in the vertex
+shader. It is specified by the user in clip space. Typically, in GLSL, the model
+space vertex position is passed in using a vertex attribute called ``position``
+and you handle the conversion from model space to clip space manually.
 
-In Godot, ``VERTEX`` specifies the vertex position in model space at the beginning of the ``vertex``
-function. Godot also handles the final conversion to clip space after the user-defined ``vertex``
-function is run. If you want to skip the conversion from model to view space, you can set the
-``render_mode`` to ``skip_vertex_transform``. If you want to skip all transforms, set
-``render_mode`` to ``skip_vertex_transform`` and set the ``PROJECTION_MATRIX`` to ``mat4(1.0)``
-in order to nullify the final transform from view space to clip space.
+In Godot, ``VERTEX`` specifies the vertex position in model space at the
+beginning of the ``vertex`` function. Godot also handles the final conversion to
+clip space after the user-defined ``vertex`` function is run. If you want to
+skip the conversion from model to view space, you can set the ``render_mode`` to
+``skip_vertex_transform``. If you want to skip all transforms, set
+``render_mode`` to ``skip_vertex_transform`` and set the ``PROJECTION_MATRIX``
+to ``mat4(1.0)`` in order to nullify the final transform from view space to clip
+space.
 
 Varyings
 ^^^^^^^^
 
-Varyings are a type of variable that can be passed from the vertex shader to the fragment shader. In
-modern GLSL (3.0 and up), varyings are defined with the ``in`` and ``out`` keywords. A variable going
-out of the vertex shader is defined with ``out`` in the vertex shader and ``in`` inside the fragment shader.
+Varyings are a type of variable that can be passed from the vertex shader to the
+fragment shader. In modern GLSL (3.0 and up), varyings are defined with the
+``in`` and ``out`` keywords. A variable going out of the vertex shader is
+defined with ``out`` in the vertex shader and ``in`` inside the fragment shader.
 
 Main
 ^^^^
 
-In GLSL, each shader program looks like a self-contained C-style program. Accordingly, the main entry point
-is ``main``. If you are copying a vertex shader, rename ``main`` to ``vertex`` and if you are copying a
-fragment shader, rename ``main`` to ``fragment``.
+In GLSL, each shader program looks like a self-contained C-style program.
+Accordingly, the main entry point is ``main``. If you are copying a vertex
+shader, rename ``main`` to ``vertex`` and if you are copying a fragment shader,
+rename ``main`` to ``fragment``.
 
 Macros
 ^^^^^^
 
-In keeping with its similarity to C, GLSL lets you use macros. Commonly ``#define`` is used to define
-constants or small functions. There is no straightforward way to translate defines to Godot's shading language.
-If it is a function that is defined, then replace with a function, and if it is a constant, then replace with
-a uniform. For other macros (``#if``, ``#ifdef``, etc.), there is no equivalent because they run during the
-pre-processing stage of compilation.
+In keeping with its similarity to C, GLSL lets you use macros. Commonly
+``#define`` is used to define constants or small functions. There is no
+straightforward way to translate defines to Godot's shading language. If it is a
+function that is defined, then replace with a function, and if it is a constant,
+then replace with a uniform. For other macros (``#if``, ``#ifdef``, etc.), there
+is no equivalent because they run during the pre-processing stage of
+compilation.
 
 Variables
 ^^^^^^^^^
 
-GLSL has many built-in variables that are hard-coded. These variables are not uniforms, so they
-are not editable from the main program.
+GLSL has many built-in variables that are hard-coded. These variables are not
+uniforms, so they are not editable from the main program.
 
 +---------------------+---------+------------------------+-----------------------------------------------------+
 |Variable             |Type     |Equivalent              |Description                                          |
@@ -103,21 +109,25 @@ are not editable from the main program.
 Coordinates
 ^^^^^^^^^^^
 
-``gl_FragCoord`` in GLSL and ``FRAGCOORD`` in the Godot shading language use the same coordinate system.
-If using UV in Godot, the y-coordinate will be flipped upside down.
+``gl_FragCoord`` in GLSL and ``FRAGCOORD`` in the Godot shading language use the
+same coordinate system. If using UV in Godot, the y-coordinate will be flipped
+upside down.
 
 Precision
 ^^^^^^^^^
 
-In GLSL, you can define the precision of a given type (float or int) at the top of the shader with the
-``precision`` keyword. In Godot, you can set the precision of individual variables as you need by placing
-precision qualifiers ``lowp``, ``mediump``, and ``highp`` before the type when defining the variable. For
-more information, see the :ref:`Shading Language <doc_shading_language>` reference.
+In GLSL, you can define the precision of a given type (float or int) at the top
+of the shader with the ``precision`` keyword. In Godot, you can set the
+precision of individual variables as you need by placing precision qualifiers
+``lowp``, ``mediump``, and ``highp`` before the type when defining the variable.
+For more information, see the :ref:`Shading Language <doc_shading_language>`
+reference.
 
 Shadertoy
 ---------
 
-`Shadertoy <https://www.shadertoy.com/results?query=&sort=popular&from=10&num=4>`_ is a website that makes it easy to write fragment shaders and
+`Shadertoy <https://www.shadertoy.com/results?query=&sort=popular&from=10&num=4>`_
+is a website that makes it easy to write fragment shaders and
 create `pure magic <https://www.shadertoy.com/view/4tjGRh>`_.
 
 Shadertoy does not give the user full control over the shader. It handles all
@@ -126,27 +136,30 @@ the input and uniforms and only lets the user write the fragment shader.
 Types
 ^^^^^
 
-Shadertoy uses the webgl spec, so it runs a slightly different version of GLSL. However, it still
-has the regular types, including constants and macros.
+Shadertoy uses the webgl spec, so it runs a slightly different version of GLSL.
+However, it still has the regular types, including constants and macros.
 
 mainImage
 ^^^^^^^^^
 
-The main point of entry to a Shadertoy shader is the ``mainImage`` function. ``mainImage`` has two
-parameters, ``fragColor`` and ``fragCoord``, which correspond to ``COLOR`` and ``FRAGCOORD`` in Godot,
-respectively. These parameters are handled automatically in Godot, so you do not need to include them
-as parameters yourself. Anything in the ``mainImage`` function should be copied into the ``fragment``
-function when porting to Godot.
+The main point of entry to a Shadertoy shader is the ``mainImage`` function.
+``mainImage`` has two parameters, ``fragColor`` and ``fragCoord``, which
+correspond to ``COLOR`` and ``FRAGCOORD`` in Godot, respectively. These
+parameters are handled automatically in Godot, so you do not need to include
+them as parameters yourself. Anything in the ``mainImage`` function should be
+copied into the ``fragment`` function when porting to Godot.
 
 Variables
 ^^^^^^^^^
 
-In order to make writing fragment shaders straightforward and easy, Shadertoy handles passing a lot
-of helpful information from the main program into the fragment shader for you. A few of these
-have no equivalents in Godot because Godot has chosen not to make them available by default.
-This is okay because Godot gives you the ability to make your own uniforms. For variables whose
-equivalents are listed as "Provide with Uniform", users are responsible for creating that
-uniform themselves. The description gives the reader a hint about what they can pass in as a substitute.
+In order to make writing fragment shaders straightforward and easy, Shadertoy
+handles passing a lot of helpful information from the main program into the
+fragment shader for you. A few of these have no equivalents in Godot because
+Godot has chosen not to make them available by default. This is okay because
+Godot gives you the ability to make your own uniforms. For variables whose
+equivalents are listed as "Provide with Uniform", users are responsible for
+creating that uniform themselves. The description gives the reader a hint about
+what they can pass in as a substitute.
 
 +---------------------+---------+------------------------+-----------------------------------------------------+
 |Variable             |Type     |Equivalent              |Description                                          |
@@ -177,36 +190,41 @@ uniform themselves. The description gives the reader a hint about what they can
 Coordinates
 ^^^^^^^^^^^
 
-``fragCoord`` behaves the same as ``gl_FragCoord`` in :ref:`GLSL <glsl_coordinates>` and ``FRAGCOORD`` in Godot.
+``fragCoord`` behaves the same as ``gl_FragCoord`` in :ref:`GLSL
+<glsl_coordinates>` and ``FRAGCOORD`` in Godot.
 
 
 The Book of Shaders
 -------------------
 
-Similar to Shadertoy, `The Book of Shaders <https://thebookofshaders.com>`_ provides access to a fragment
-shader in the web browser, with which the user may interact. The user is restricted to writing fragment
-shader code with a set list of uniforms passed in and with no ability to add additional uniforms.
+Similar to Shadertoy, `The Book of Shaders <https://thebookofshaders.com>`_
+provides access to a fragment shader in the web browser, with which the user may
+interact. The user is restricted to writing fragment shader code with a set list
+of uniforms passed in and with no ability to add additional uniforms.
 
-For further help on porting shaders to various frameworks generally, The Book of Shaders provides
-a `page <https://thebookofshaders.com/04>`_ on running shaders in various frameworks.
+For further help on porting shaders to various frameworks generally, The Book of
+Shaders provides a `page <https://thebookofshaders.com/04>`_ on running shaders
+in various frameworks.
 
 Types
 ^^^^^
 
-The Book of Shaders uses the webgl spec, so it runs a slightly different version of GLSL. However, it still
-has the regular types, including constants and macros.
+The Book of Shaders uses the webgl spec, so it runs a slightly different version
+of GLSL. However, it still has the regular types, including constants and
+macros.
 
 Main
 ^^^^
 
-The entry point for a Book of Shaders fragment shader is ``main``, just like in GLSL. Everything written in
-a Book of Shaders ``main`` function should be copied into Godot's ``fragment`` function.
+The entry point for a Book of Shaders fragment shader is ``main``, just like in
+GLSL. Everything written in a Book of Shaders ``main`` function should be copied
+into Godot's ``fragment`` function.
 
 Variables
 ^^^^^^^^^
 
-The Book of Shaders sticks closer to plain GLSL than Shadertoy does. It also implements fewer uniforms than
-Shadertoy.
+The Book of Shaders sticks closer to plain GLSL than Shadertoy does. It also
+implements fewer uniforms than Shadertoy.
 
 +---------------------+---------+------------------------+-----------------------------------------------------+
 |Variable             |Type     |Equivalent              |Description                                          |
@@ -225,4 +243,5 @@ Shadertoy.
 Coordinates
 ^^^^^^^^^^^
 
-The Book of Shaders uses the same coordinate system as :ref:`GLSL <glsl_coordinates>`.
+The Book of Shaders uses the same coordinate system as
+:ref:`GLSL <glsl_coordinates>`.

tutorials/shading/index.rst

@@ -5,12 +5,13 @@ Shading
    :maxdepth: 1
    :name: toc-learn-features-shading
 
+   introduction_to_shaders
    shading_reference/index
    your_first_shader/index
    shader_materials
    visual_shaders
    screen-reading_shaders
-   migrating_to_godot_shader_language
+   converting_glsl_to_godot_shaders
    shaders_style_guide
    advanced_postprocessing
    using_viewport_as_texture

tutorials/shading/your_first_shader/what_are_shaders.rst → tutorials/shading/introduction_to_shaders.rst

@@ -1,7 +1,7 @@
-.. _doc_what_are_shaders:
+.. _doc_introduction_to_shaders:
 
-What are shaders?
-=================
+Introduction to shaders
+=======================
 
 Introduction
 ------------

tutorials/shading/shading_reference/shading_language.rst

@@ -9,7 +9,7 @@ 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.
 
-If you are already familiar with GLSL, the :ref:`Godot Shader Migration Guide<doc_migrating_to_godot_shader_language>`
+If you are already familiar with GLSL, the :ref:`Godot Shader Migration Guide<doc_converting_glsl_to_godot_shaders>`
 is a resource that will help you transition from regular GLSL to Godot's shading language.
 
 Data types

tutorials/shading/visual_shaders.rst

@@ -16,7 +16,7 @@ necessary for specific effects.
 .. note::
 
     If you are not familiar with shaders, start by reading
-    :ref:`doc_what_are_shaders`.
+    :ref:`doc_introduction_to_shaders`.
 
 Creating a VisualShader
 -----------------------

tutorials/shading/your_first_shader/index.rst

@@ -7,9 +7,6 @@ with the basics. This tutorial will not cover advanced topics and it is not
 comprehensive. For a comprehensive and detailed overview of shaders in Godot see the
 :ref:`Shading Reference Page <toc-shading-reference>`.
 
-"What are shaders" gives you a high-level overview of what shaders are and how they fit
-into the rendering pipeline.
-
 The "your first shader" tutorials walk you through the process of writing a shader
 step-by-step.
 
@@ -20,7 +17,6 @@ For a more general introduction into shaders and the OpenGL Shading Language, us
    :maxdepth: 1
    :name: toc-your-first-shader
 
-   what_are_shaders
    your_first_2d_shader
    your_first_3d_shader
    your_second_3d_shader

tutorials/shading/your_first_shader/your_first_2d_shader.rst

@@ -9,7 +9,7 @@ Introduction
 Shaders are special programs that execute on the GPU and are used for rendering
 graphics. All modern rendering is done with shaders. For a more detailed
 description of what shaders are please see :ref:`What are shaders
-<doc_what_are_shaders>`.
+<doc_introduction_to_shaders>`.
 
 This tutorial will focus on the practical aspects of writing shader programs by
 walking you through the process of writing a shader with both vertex and