From 3342e5fb766381cbd45e276df2de1a9bcbac6d8b Mon Sep 17 00:00:00 2001 From: clayjohn Date: Sun, 19 Aug 2018 19:06:22 -0700 Subject: [PATCH 1/2] added migration reference --- tutorials/shading/index.rst | 1 + .../migrating_to_godot_shader_language.rst | 211 ++++++++++++++++++ 2 files changed, 212 insertions(+) create mode 100644 tutorials/shading/migrating_to_godot_shader_language.rst diff --git a/tutorials/shading/index.rst b/tutorials/shading/index.rst index 773b26e89..1f7b2f653 100644 --- a/tutorials/shading/index.rst +++ b/tutorials/shading/index.rst @@ -8,3 +8,4 @@ Shading shading_language shader_materials screen-reading_shaders + migrating_to_godot_shader_language diff --git a/tutorials/shading/migrating_to_godot_shader_language.rst b/tutorials/shading/migrating_to_godot_shader_language.rst new file mode 100644 index 000000000..1a6d446ae --- /dev/null +++ b/tutorials/shading/migrating_to_godot_shader_language.rst @@ -0,0 +1,211 @@ +.. _doc_migrating_to_godot_shader_language: + +Migrating to Godot shading language +=================================== + +Introduction +------------ + +This document will explain the differences between Godot's shading language +and glsl as well as give 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. + +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. + +Shader Programs +^^^^^^^^^^^^^^^ + +In glsl each shader uses a seperate program. So 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 use a default for 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 +for when varyings are used. + +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. + +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``. + +Constants +^^^^^^^^^ + +Godot currently does not support constants. You can fake the functionality by using a uniform initialized +to the value, but you will not benefit from the increased speed from using a constant. + +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 becuase they run during the +pre-processing stage of compilation. + +Variables +^^^^^^^^^ + +Glsl has many built in variables that are hard-coded in. These variables are not uniforms, so they +are not editable from the main program. + ++---------------------+---------+------------------------+-----------------------------------------------------+ +|Variable |Type |Equivalent |Description | ++=====================+=========+========================+=====================================================+ +|gl_FragColor |out vec4 |COLOR |Output color for each pixel. | ++---------------------+---------+------------------------+-----------------------------------------------------+ +|gl_FragCoord |vec4 |FRAGCOORD |For full screen quads, for smaller quads use UV. | ++---------------------+---------+------------------------+-----------------------------------------------------+ +|gl_Position |vec4 |VERTEX |Position of Vertex, output from Vertex Shader. | ++---------------------+---------+------------------------+-----------------------------------------------------+ +|gl_PointSize |float |POINT_SIZE |Size of Point primitive. | ++---------------------+---------+------------------------+-----------------------------------------------------+ +|gl_PointCoord |vec2 |POINT_COORD |Position on point when drawing Point primitives. | ++---------------------+---------+------------------------+-----------------------------------------------------+ +|gl_FrontFacing |bool |FRONT_FACING |True if front face of primitive. | ++---------------------+---------+------------------------+-----------------------------------------------------+ + +.. _glsl_coordinates: + +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. + +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. + +Shadertoy +--------- + +`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 only allows the user to write a +fragment shader. It handles all 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. + +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. + +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 becuase Godot has chosen not to make them available by default. +This is okay becuase Godot gives you the ability to make your own uniforms. For variables whose +equivalents are listed as "Provide with Uniform", the user is responsible for creating that +uniform themself. The description gives the reader a hint about what they can pass in as a substitute. + ++---------------------+---------+------------------------+-----------------------------------------------------+ +|Variable |Type |Equivalent |Description | ++=====================+=========+========================+=====================================================+ +|fragColor |out vec4 |COLOR |Output color for each pixel. | ++---------------------+---------+------------------------+-----------------------------------------------------+ +|fragCoord |vec2 |FRAGCOORD |For full screen quads, for smaller quads use UV. | ++---------------------+---------+------------------------+-----------------------------------------------------+ +|iResolution |vec3 |1.0 / SCREEN_PIXEL_SIZE |Can also pass in manually. | ++---------------------+---------+------------------------+-----------------------------------------------------+ +|iTime |float |TIME |Time since shader starts. | ++---------------------+---------+------------------------+-----------------------------------------------------+ +|iTimeDelta |float |Provide with Uniform |Time to render previous frame. | ++---------------------+---------+------------------------+-----------------------------------------------------+ +|iFrame |float |Provide with Uniform |Frame number. | ++---------------------+---------+------------------------+-----------------------------------------------------+ +|iChannelTime[4] |float |Provide with Uniform |Time since that particular texture started | ++---------------------+---------+------------------------+-----------------------------------------------------+ +|iMouse |vec4 |Provide with Uniform |Mouse position in pixel coordinates. | ++---------------------+---------+------------------------+-----------------------------------------------------+ +|iDate |vec4 |Provide with Uniform |Current date, expressed in seconds. | ++---------------------+---------+------------------------+-----------------------------------------------------+ +|iChannelResolution[4]|vec3 |1.0 / TEXTURE_PIXEL_SIZE|Resolution of particular texture. | ++---------------------+---------+------------------------+-----------------------------------------------------+ +|iChanneli |Sampler2D|TEXTURE |Godot provides only one built in, user can make more.| ++---------------------+---------+------------------------+-----------------------------------------------------+ + +Coordinates +^^^^^^^^^^^ +``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 for the user to interact with. 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. + +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. + +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. + +Variables +^^^^^^^^^ + +The Book of Shaders sticks closer to plain glsl than Shadertoy does. It also implements fewer uniforms than +Shadertoy. + ++---------------------+---------+------------------------+-----------------------------------------------------+ +|Variable |Type |Equivalent |Description | ++=====================+=========+========================+=====================================================+ +|gl_FragColor |out vec4 |COLOR |Output color for each pixel. | ++---------------------+---------+------------------------+-----------------------------------------------------+ +|gl_FragCoord |vec4 |FRAGCOORD |For full screen quads, for smaller quads use UV. | ++---------------------+---------+------------------------+-----------------------------------------------------+ +|u_resolution |vec2 |1.0 / SCREEN_PIXEL_SIZE |Can also pass in manually. | ++---------------------+---------+------------------------+-----------------------------------------------------+ +|u_time |float |TIME |Time since shader starts. | ++---------------------+---------+------------------------+-----------------------------------------------------+ +|u_mouse |vec2 |Provide with Uniform |Mouse position in pixel coordinates. | ++---------------------+---------+------------------------+-----------------------------------------------------+ + +Coordinates +^^^^^^^^^^^ + +The Book of Shaders uses the same coordinate system as :ref:`glsl `. + From 8605975ad6a3ac39fd19fb3eaf04ad65941d0447 Mon Sep 17 00:00:00 2001 From: clayjohn Date: Tue, 21 Aug 2018 21:19:14 -0700 Subject: [PATCH 2/2] typo fixes --- .../migrating_to_godot_shader_language.rst | 58 +++++++++---------- 1 file changed, 29 insertions(+), 29 deletions(-) diff --git a/tutorials/shading/migrating_to_godot_shader_language.rst b/tutorials/shading/migrating_to_godot_shader_language.rst index 1a6d446ae..c98c12298 100644 --- a/tutorials/shading/migrating_to_godot_shader_language.rst +++ b/tutorials/shading/migrating_to_godot_shader_language.rst @@ -6,41 +6,41 @@ Migrating to Godot shading language Introduction ------------ -This document will explain the differences between Godot's shading language -and glsl as well as give practical advice on how to migrate shaders from other +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. -Glsl +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 seperate program. So 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 use a default for 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 -for when varyings are used. +shaders in one file. In GLSL the vertex and fragment programs cannot share variables except +when varyings are used. 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 +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 +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``. @@ -53,16 +53,16 @@ to the value, but you will not benefit from the increased speed from using a con Macros ^^^^^^ -In keeping with its similarity to C, glsl lets you use macros. Commonly ``#define`` is used to define +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 becuase they run during the +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 in. These variables are not uniforms, so they +GLSL has many built in variables that are hard-coded. These variables are not uniforms, so they are not editable from the main program. +---------------------+---------+------------------------+-----------------------------------------------------+ @@ -70,7 +70,7 @@ are not editable from the main program. +=====================+=========+========================+=====================================================+ |gl_FragColor |out vec4 |COLOR |Output color for each pixel. | +---------------------+---------+------------------------+-----------------------------------------------------+ -|gl_FragCoord |vec4 |FRAGCOORD |For full screen quads, for smaller quads use UV. | +|gl_FragCoord |vec4 |FRAGCOORD |For full screen quads. For smaller quads use UV. | +---------------------+---------+------------------------+-----------------------------------------------------+ |gl_Position |vec4 |VERTEX |Position of Vertex, output from Vertex Shader. | +---------------------+---------+------------------------+-----------------------------------------------------+ @@ -86,13 +86,13 @@ are not editable from the main program. Coordinates ^^^^^^^^^^^ -``gl_FragCoord`` in glsl and ``FRAGCOORD`` in the Godot shading language use the same coordinate system. +``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 +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. @@ -110,7 +110,7 @@ shader. Types ^^^^^ -Shadertoy uses the webgl spec so it runs a slightly different version of glsl. However, it still +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 @@ -135,17 +135,17 @@ uniform themself. The description gives the reader a hint about what they can pa +=====================+=========+========================+=====================================================+ |fragColor |out vec4 |COLOR |Output color for each pixel. | +---------------------+---------+------------------------+-----------------------------------------------------+ -|fragCoord |vec2 |FRAGCOORD |For full screen quads, for smaller quads use UV. | +|fragCoord |vec2 |FRAGCOORD |For full screen quads. For smaller quads use UV. | +---------------------+---------+------------------------+-----------------------------------------------------+ |iResolution |vec3 |1.0 / SCREEN_PIXEL_SIZE |Can also pass in manually. | +---------------------+---------+------------------------+-----------------------------------------------------+ -|iTime |float |TIME |Time since shader starts. | +|iTime |float |TIME |Time since shader started. | +---------------------+---------+------------------------+-----------------------------------------------------+ |iTimeDelta |float |Provide with Uniform |Time to render previous frame. | +---------------------+---------+------------------------+-----------------------------------------------------+ |iFrame |float |Provide with Uniform |Frame number. | +---------------------+---------+------------------------+-----------------------------------------------------+ -|iChannelTime[4] |float |Provide with Uniform |Time since that particular texture started | +|iChannelTime[4] |float |Provide with Uniform |Time since that particular texture started. | +---------------------+---------+------------------------+-----------------------------------------------------+ |iMouse |vec4 |Provide with Uniform |Mouse position in pixel coordinates. | +---------------------+---------+------------------------+-----------------------------------------------------+ @@ -158,7 +158,7 @@ uniform themself. The description gives the reader a hint about what they can pa 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. @@ -175,19 +175,19 @@ a `page `_ on running shaders in various framew Types ^^^^^ -The Book of Shaders uses the webgl spec so it runs a slightly different version of glsl. However, it still +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 +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 +The Book of Shaders sticks closer to plain GLSL than Shadertoy does. It also implements fewer uniforms than Shadertoy. +---------------------+---------+------------------------+-----------------------------------------------------+ @@ -195,11 +195,11 @@ Shadertoy. +=====================+=========+========================+=====================================================+ |gl_FragColor |out vec4 |COLOR |Output color for each pixel. | +---------------------+---------+------------------------+-----------------------------------------------------+ -|gl_FragCoord |vec4 |FRAGCOORD |For full screen quads, for smaller quads use UV. | +|gl_FragCoord |vec4 |FRAGCOORD |For full screen quads. For smaller quads use UV. | +---------------------+---------+------------------------+-----------------------------------------------------+ |u_resolution |vec2 |1.0 / SCREEN_PIXEL_SIZE |Can also pass in manually. | +---------------------+---------+------------------------+-----------------------------------------------------+ -|u_time |float |TIME |Time since shader starts. | +|u_time |float |TIME |Time since shader started. | +---------------------+---------+------------------------+-----------------------------------------------------+ |u_mouse |vec2 |Provide with Uniform |Mouse position in pixel coordinates. | +---------------------+---------+------------------------+-----------------------------------------------------+ @@ -207,5 +207,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 `.