From d51a91ad3d819be630bbdca7f0a6a33f86a5ebbd Mon Sep 17 00:00:00 2001 From: Nathan Lovato Date: Tue, 6 Oct 2020 20:25:48 -0600 Subject: [PATCH 1/4] Move and rename what_are_shaders.rst Closes #4179 --- about/docs_changelog.rst | 2 +- classes/class_shader.rst | 2 +- tutorials/shading/index.rst | 1 + ...haders.rst => introduction_to_shaders.rst} | 6 +- tutorials/shading/visual_shaders.rst | 2 +- .../your_first_canvasitem_shader.rst | 220 ++++++++++++++++++ 6 files changed, 227 insertions(+), 6 deletions(-) rename tutorials/shading/{your_first_shader/what_are_shaders.rst => introduction_to_shaders.rst} (98%) create mode 100644 tutorials/shading/your_first_shader/your_first_canvasitem_shader.rst diff --git a/about/docs_changelog.rst b/about/docs_changelog.rst index c06c3c960..88850f1c4 100644 --- a/about/docs_changelog.rst +++ b/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` diff --git a/classes/class_shader.rst b/classes/class_shader.rst index 32fbe4a21..32f81eff9 100644 --- a/classes/class_shader.rst +++ b/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 ---------- diff --git a/tutorials/shading/index.rst b/tutorials/shading/index.rst index bfc29c273..d696b3047 100644 --- a/tutorials/shading/index.rst +++ b/tutorials/shading/index.rst @@ -5,6 +5,7 @@ Shading :maxdepth: 1 :name: toc-learn-features-shading + introduction_to_shaders shading_reference/index your_first_shader/index shader_materials diff --git a/tutorials/shading/your_first_shader/what_are_shaders.rst b/tutorials/shading/introduction_to_shaders.rst similarity index 98% rename from tutorials/shading/your_first_shader/what_are_shaders.rst rename to tutorials/shading/introduction_to_shaders.rst index 56ff4e044..4408a70f3 100644 --- a/tutorials/shading/your_first_shader/what_are_shaders.rst +++ b/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 ------------ diff --git a/tutorials/shading/visual_shaders.rst b/tutorials/shading/visual_shaders.rst index 243233eff..c148159b9 100644 --- a/tutorials/shading/visual_shaders.rst +++ b/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 ----------------------- diff --git a/tutorials/shading/your_first_shader/your_first_canvasitem_shader.rst b/tutorials/shading/your_first_shader/your_first_canvasitem_shader.rst new file mode 100644 index 000000000..c6f983d81 --- /dev/null +++ b/tutorials/shading/your_first_shader/your_first_canvasitem_shader.rst @@ -0,0 +1,220 @@ +.. _doc_your_first_canvasitem_shader: + +Your first CanvasItem shader +============================ + +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:`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 fragment functions. +This tutorial targets absolute beginners to shaders. + +.. note:: If you have experience writing shaders and are just looking for + an overview of how shaders work in Godot, see the :ref:`Shading Reference `. + +Setup +----- + +:ref:`CanvasItem ` shaders are used to draw all 2D objects in Godot, +while :ref:`Spatial ` shaders are used to draw all 3D objects. + +In order to use a shader it must be attached inside a :ref:`Material ` +which must be attached to an object. Materials are a type of :ref:`Resource `. +To draw multiple objects with the same material, the material must be attached to each object. + +All objects derived from a :ref:`CanvasItem ` have a material property. +This includes all :ref:`GUI elements `, :ref:`Sprites `, :ref:`TileMaps `, +:ref:`MeshInstance2Ds ` etc. +They also have an option to inherit their parent's material. This can be useful if you have +a large number of nodes that you want to use the same material. + +To begin, create a Sprite node. You can use any CanvasItem, but for this tutorial we will +use a Sprite. + +In the Inspector, click beside "Texture" where it says "[empty]" and select "Load", then select +"Icon.png". For new projects, this is the Godot icon. You should now see the icon in the viewport. + +Next, look down in the Inspector, under the CanvasItem section, click beside "Material" and select +"New ShaderMaterial". This creates a new Material resource. Click on the sphere that appears. Godot currently +doesn't know whether you are writing a CanvasItem Shader or a Spatial Shader and it previews the output +of spatial shaders. So what you are seeing is the output of the default Spatial Shader. + +Click beside "Shader" and select "New Shader". Finally, click on the new shader resource and the shader +editor will open. You are now ready to begin writing your first shader. + +Your first CanvasItem shader +---------------------------- + +In Godot, all shaders start with a line specifying what type of shader they are. It uses +the following format: + +.. code-block:: glsl + + shader_type canvas_item; + +Because we are writing a CanvasItem shader, we specify ``canvas_item`` in the first line. All our code will +go beneath this declaration. + +This line tells the engine which built-in variables and functionality to supply you with. + +In Godot you can override three functions to control how the shader operates; ``vertex``, ``fragment``, and ``light``. +This tutorial will walk you through writing a shader with both vertex and fragment functions. Light +functions are significantly more complex than vertex and fragment functions and so will not be covered here. + +Your first fragment function +---------------------------- + +The fragment function runs for every pixel in a Sprite and determines what color that pixel should be. + +They are restricted to the pixels covered by the Sprite, that means you cannot use one to, for example, +create an outline around a Sprite. + +The most basic fragment function does nothing except assign a single color to every pixel. + +We do so by writing a ``vec4`` to the built-in variable ``COLOR``. ``vec4`` is shorthand for constructing +a vector with 4 numbers. For more information about vectors see the :ref:`Vector math tutorial ` +``COLOR`` is both an input variable to the fragment function and the final output from it. + +.. code-block:: glsl + + void fragment(){ + COLOR = vec4(0.4, 0.6, 0.9, 1.0); + } + +.. image:: img/blue-box.png + +Congratulations! You're done. You have successfully written your first shader in Godot. + +Now let's make things more complex. + +There are many inputs to the fragment function that you can use for calculating ``COLOR``. +``UV`` is one of them. UV coordinates are specified in your Sprite (without you knowing it!) +and they tell the shader where to read from textures for each part of the mesh. + +In the fragment function you can only read from ``UV``, but you can use it in other functions +or to assign values to ``COLOR`` directly. + +``UV`` varies between 0-1 from left-right and from top-bottom. + +.. image:: img/iconuv.png + +.. code-block:: glsl + + void fragment() { + COLOR = vec4(UV, 0.5, 1.0); + } + +.. image:: img/UV.png + +Using ``TEXTURE`` built-in +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +When you want to adjust a color in a Sprite you cannot just adjust the color from the texture +manually like in the code below. + +.. code-block:: glsl + + void fragment(){ + //this shader will result in an all white rectangle + COLOR.b = 1.0; + } + +The default fragment function reads from a texture and displays it. When you overwrite the default fragment function, +you lose that functionality, so you have to implement it yourself. You read from textures using the +``texture`` function. Certain nodes, like Sprites, have a dedicated texture variable that can be accessed in the shader +using ``TEXTURE``. Use it together with ``UV`` and ``texture`` to draw the Sprite. + +.. code-block:: glsl + + void fragment(){ + COLOR = texture(TEXTURE, UV); //read from texture + COLOR.b = 1.0; //set blue channel to 1.0 + } + +.. image:: img/blue-tex.png + +Uniform input +^^^^^^^^^^^^^ + +Uniform input is used to pass data into a shader that will be the same across the entire shader. + +You can use uniforms by defining them at the top of your shader like so: + +.. code-block:: glsl + + uniform float size; + +For more information about usage see the :ref:`Shading Language doc `. + +Add a uniform to change the amount of blue in our Sprite. + +.. code-block:: glsl + + uniform float blue = 1.0; // you can assign a default value to uniforms + + void fragment(){ + COLOR = texture(TEXTURE, UV); //read from texture + COLOR.b = blue; + } + +Now you can change the amount of blue in the Sprite from the editor. Look back at the Inspector +under where you created your shader. You should see a section called "Shader Param". Unfold that +section and you will see the uniform you just declared. If you change the value in the editor, it +will overwrite the default value you provided in the shader. + +Interacting with shaders from code +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +You can change uniforms from code using the function ``set_shader_param()`` which is called on the node's +material resource. With a Sprite node, the following code can be used to set the ``blue`` uniform. + +:: + + var blue_value = 1.0 + material.set_shader_param("blue", blue_value) + +Note that the name of the uniform is a string. The string must match exactly with how it is +written in the shader, including spelling and case. + +Your first vertex function +-------------------------- + +Now that we have a fragment function, let's write a vertex function. + +Use the vertex function to calculate where on the screen each vertex should end up. + +The most important variable in the vertex function is ``VERTEX``. Initially, it specifies +the vertex coordinates in your model, but you also write to it to determine where to actually +draw those vertices. ``VERTEX`` is a ``vec2`` that is initially presented in local-space +(i.e. not relative to the camera, viewport, or parent nodes). + +You can offset the vertices by directly adding to ``VERTEX``. + +.. code-block:: glsl + + void vertex() { + VERTEX += vec2(10.0, 0.0); + } + +Combined with the ``TIME`` built-in variable, this can be used for simple animation. + +.. code-block:: glsl + + void vertex() { + // Animate Sprite moving in big circle around its location + VERTEX += vec2(cos(TIME)*100.0, sin(TIME)*100.0); + } + +Conclusion +---------- + +At their core, shaders do what you have seen so far, they compute ``VERTEX`` and ``COLOR``. It is +up to you to dream up more complex mathematical strategies for assigning values to those variables. + +For inspiration, take a look at some of the more advanced shader tutorials, and look at other sites +like `Shadertoy `_ and `The Book of Shaders `_. From d09969f87181289e83ba257f26b67baa1d56f935 Mon Sep 17 00:00:00 2001 From: Nathan Lovato Date: Tue, 6 Oct 2020 20:32:29 -0600 Subject: [PATCH 2/4] Rename migrating_to_godot_shader_language.rst Also wrap lines in the document at 80 characters Closes #4178 --- about/docs_changelog.rst | 2 +- ...t => converting_glsl_to_godot_shaders.rst} | 177 ++++++++++-------- .../shading_reference/shading_language.rst | 2 +- 3 files changed, 100 insertions(+), 81 deletions(-) rename tutorials/shading/{migrating_to_godot_shader_language.rst => converting_glsl_to_godot_shaders.rst} (62%) diff --git a/about/docs_changelog.rst b/about/docs_changelog.rst index 88850f1c4..39542a732 100644 --- a/about/docs_changelog.rst +++ b/about/docs_changelog.rst @@ -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: diff --git a/tutorials/shading/migrating_to_godot_shader_language.rst b/tutorials/shading/converting_glsl_to_godot_shaders.rst similarity index 62% rename from tutorials/shading/migrating_to_godot_shader_language.rst rename to tutorials/shading/converting_glsl_to_godot_shaders.rst index 960d965d9..a31241437 100644 --- a/tutorials/shading/migrating_to_godot_shader_language.rst +++ b/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 ` -reference. +For detailed information on Godot's shading language, please refer to the +:ref:`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 `. +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 `. 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 ` 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 ` +reference. Shadertoy --------- -`Shadertoy `_ is a website that makes it easy to write fragment shaders and +`Shadertoy `_ +is a website that makes it easy to write fragment shaders and create `pure magic `_. 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 ` and ``FRAGCOORD`` in Godot. +``fragCoord`` behaves the same as ``gl_FragCoord`` in :ref:`GLSL +` and ``FRAGCOORD`` in Godot. The Book of Shaders ------------------- -Similar to Shadertoy, `The Book of Shaders `_ 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 `_ +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 `_ on running shaders in various frameworks. +For further help on porting shaders to various frameworks generally, The Book of +Shaders provides a `page `_ 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 `. +The Book of Shaders uses the same coordinate system as +:ref:`GLSL `. diff --git a/tutorials/shading/shading_reference/shading_language.rst b/tutorials/shading/shading_reference/shading_language.rst index 3681aca2e..819861818 100644 --- a/tutorials/shading/shading_reference/shading_language.rst +++ b/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` +If you are already familiar with GLSL, the :ref:`Godot Shader Migration Guide` is a resource that will help you transition from regular GLSL to Godot's shading language. Data types From 4a052e0e04253b6104cf29b4727bc3f8fe168525 Mon Sep 17 00:00:00 2001 From: Nathan Lovato Date: Thu, 8 Oct 2020 13:48:33 -0600 Subject: [PATCH 3/4] Fix errors after rebasing the branch on master --- tutorials/shading/index.rst | 2 +- .../your_first_canvasitem_shader.rst | 220 ------------------ 2 files changed, 1 insertion(+), 221 deletions(-) delete mode 100644 tutorials/shading/your_first_shader/your_first_canvasitem_shader.rst diff --git a/tutorials/shading/index.rst b/tutorials/shading/index.rst index d696b3047..f4c7728eb 100644 --- a/tutorials/shading/index.rst +++ b/tutorials/shading/index.rst @@ -11,7 +11,7 @@ Shading 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 diff --git a/tutorials/shading/your_first_shader/your_first_canvasitem_shader.rst b/tutorials/shading/your_first_shader/your_first_canvasitem_shader.rst deleted file mode 100644 index c6f983d81..000000000 --- a/tutorials/shading/your_first_shader/your_first_canvasitem_shader.rst +++ /dev/null @@ -1,220 +0,0 @@ -.. _doc_your_first_canvasitem_shader: - -Your first CanvasItem shader -============================ - -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:`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 fragment functions. -This tutorial targets absolute beginners to shaders. - -.. note:: If you have experience writing shaders and are just looking for - an overview of how shaders work in Godot, see the :ref:`Shading Reference `. - -Setup ------ - -:ref:`CanvasItem ` shaders are used to draw all 2D objects in Godot, -while :ref:`Spatial ` shaders are used to draw all 3D objects. - -In order to use a shader it must be attached inside a :ref:`Material ` -which must be attached to an object. Materials are a type of :ref:`Resource `. -To draw multiple objects with the same material, the material must be attached to each object. - -All objects derived from a :ref:`CanvasItem ` have a material property. -This includes all :ref:`GUI elements `, :ref:`Sprites `, :ref:`TileMaps `, -:ref:`MeshInstance2Ds ` etc. -They also have an option to inherit their parent's material. This can be useful if you have -a large number of nodes that you want to use the same material. - -To begin, create a Sprite node. You can use any CanvasItem, but for this tutorial we will -use a Sprite. - -In the Inspector, click beside "Texture" where it says "[empty]" and select "Load", then select -"Icon.png". For new projects, this is the Godot icon. You should now see the icon in the viewport. - -Next, look down in the Inspector, under the CanvasItem section, click beside "Material" and select -"New ShaderMaterial". This creates a new Material resource. Click on the sphere that appears. Godot currently -doesn't know whether you are writing a CanvasItem Shader or a Spatial Shader and it previews the output -of spatial shaders. So what you are seeing is the output of the default Spatial Shader. - -Click beside "Shader" and select "New Shader". Finally, click on the new shader resource and the shader -editor will open. You are now ready to begin writing your first shader. - -Your first CanvasItem shader ----------------------------- - -In Godot, all shaders start with a line specifying what type of shader they are. It uses -the following format: - -.. code-block:: glsl - - shader_type canvas_item; - -Because we are writing a CanvasItem shader, we specify ``canvas_item`` in the first line. All our code will -go beneath this declaration. - -This line tells the engine which built-in variables and functionality to supply you with. - -In Godot you can override three functions to control how the shader operates; ``vertex``, ``fragment``, and ``light``. -This tutorial will walk you through writing a shader with both vertex and fragment functions. Light -functions are significantly more complex than vertex and fragment functions and so will not be covered here. - -Your first fragment function ----------------------------- - -The fragment function runs for every pixel in a Sprite and determines what color that pixel should be. - -They are restricted to the pixels covered by the Sprite, that means you cannot use one to, for example, -create an outline around a Sprite. - -The most basic fragment function does nothing except assign a single color to every pixel. - -We do so by writing a ``vec4`` to the built-in variable ``COLOR``. ``vec4`` is shorthand for constructing -a vector with 4 numbers. For more information about vectors see the :ref:`Vector math tutorial ` -``COLOR`` is both an input variable to the fragment function and the final output from it. - -.. code-block:: glsl - - void fragment(){ - COLOR = vec4(0.4, 0.6, 0.9, 1.0); - } - -.. image:: img/blue-box.png - -Congratulations! You're done. You have successfully written your first shader in Godot. - -Now let's make things more complex. - -There are many inputs to the fragment function that you can use for calculating ``COLOR``. -``UV`` is one of them. UV coordinates are specified in your Sprite (without you knowing it!) -and they tell the shader where to read from textures for each part of the mesh. - -In the fragment function you can only read from ``UV``, but you can use it in other functions -or to assign values to ``COLOR`` directly. - -``UV`` varies between 0-1 from left-right and from top-bottom. - -.. image:: img/iconuv.png - -.. code-block:: glsl - - void fragment() { - COLOR = vec4(UV, 0.5, 1.0); - } - -.. image:: img/UV.png - -Using ``TEXTURE`` built-in -^^^^^^^^^^^^^^^^^^^^^^^^^^ - -When you want to adjust a color in a Sprite you cannot just adjust the color from the texture -manually like in the code below. - -.. code-block:: glsl - - void fragment(){ - //this shader will result in an all white rectangle - COLOR.b = 1.0; - } - -The default fragment function reads from a texture and displays it. When you overwrite the default fragment function, -you lose that functionality, so you have to implement it yourself. You read from textures using the -``texture`` function. Certain nodes, like Sprites, have a dedicated texture variable that can be accessed in the shader -using ``TEXTURE``. Use it together with ``UV`` and ``texture`` to draw the Sprite. - -.. code-block:: glsl - - void fragment(){ - COLOR = texture(TEXTURE, UV); //read from texture - COLOR.b = 1.0; //set blue channel to 1.0 - } - -.. image:: img/blue-tex.png - -Uniform input -^^^^^^^^^^^^^ - -Uniform input is used to pass data into a shader that will be the same across the entire shader. - -You can use uniforms by defining them at the top of your shader like so: - -.. code-block:: glsl - - uniform float size; - -For more information about usage see the :ref:`Shading Language doc `. - -Add a uniform to change the amount of blue in our Sprite. - -.. code-block:: glsl - - uniform float blue = 1.0; // you can assign a default value to uniforms - - void fragment(){ - COLOR = texture(TEXTURE, UV); //read from texture - COLOR.b = blue; - } - -Now you can change the amount of blue in the Sprite from the editor. Look back at the Inspector -under where you created your shader. You should see a section called "Shader Param". Unfold that -section and you will see the uniform you just declared. If you change the value in the editor, it -will overwrite the default value you provided in the shader. - -Interacting with shaders from code -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -You can change uniforms from code using the function ``set_shader_param()`` which is called on the node's -material resource. With a Sprite node, the following code can be used to set the ``blue`` uniform. - -:: - - var blue_value = 1.0 - material.set_shader_param("blue", blue_value) - -Note that the name of the uniform is a string. The string must match exactly with how it is -written in the shader, including spelling and case. - -Your first vertex function --------------------------- - -Now that we have a fragment function, let's write a vertex function. - -Use the vertex function to calculate where on the screen each vertex should end up. - -The most important variable in the vertex function is ``VERTEX``. Initially, it specifies -the vertex coordinates in your model, but you also write to it to determine where to actually -draw those vertices. ``VERTEX`` is a ``vec2`` that is initially presented in local-space -(i.e. not relative to the camera, viewport, or parent nodes). - -You can offset the vertices by directly adding to ``VERTEX``. - -.. code-block:: glsl - - void vertex() { - VERTEX += vec2(10.0, 0.0); - } - -Combined with the ``TIME`` built-in variable, this can be used for simple animation. - -.. code-block:: glsl - - void vertex() { - // Animate Sprite moving in big circle around its location - VERTEX += vec2(cos(TIME)*100.0, sin(TIME)*100.0); - } - -Conclusion ----------- - -At their core, shaders do what you have seen so far, they compute ``VERTEX`` and ``COLOR``. It is -up to you to dream up more complex mathematical strategies for assigning values to those variables. - -For inspiration, take a look at some of the more advanced shader tutorials, and look at other sites -like `Shadertoy `_ and `The Book of Shaders `_. From 544e5a124253ee55280331dc5dd7132541daf359 Mon Sep 17 00:00:00 2001 From: Nathan Lovato Date: Thu, 8 Oct 2020 13:52:27 -0600 Subject: [PATCH 4/4] Remove what are shaders page and description from your_first_shader/ --- tutorials/shading/your_first_shader/index.rst | 4 ---- tutorials/shading/your_first_shader/your_first_2d_shader.rst | 2 +- 2 files changed, 1 insertion(+), 5 deletions(-) diff --git a/tutorials/shading/your_first_shader/index.rst b/tutorials/shading/your_first_shader/index.rst index 48aea32f0..00bc69ead 100644 --- a/tutorials/shading/your_first_shader/index.rst +++ b/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 `. -"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 diff --git a/tutorials/shading/your_first_shader/your_first_2d_shader.rst b/tutorials/shading/your_first_shader/your_first_2d_shader.rst index deee4eeb5..6339a2b7e 100644 --- a/tutorials/shading/your_first_shader/your_first_2d_shader.rst +++ b/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 -`. +`. 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