godot-docs/tutorials/shading/your_first_shader/your_first_canvasitem_shader.rst

.. _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 <toc-shading-reference>`.

Setup
-----

:ref:`CanvasItem <doc_canvas_item_shader>` shaders are used to draw all 2D objects in Godot,
while :ref:`Spatial <doc_spatial_shader>` shaders are used to draw all 3D objects.

In order to use a shader it must be attached inside a :ref:`Material <class_material>`
which must be attached to an object. Materials are a type of :ref:`Resource <doc_resources>`.
To draw multiple objects with the same material, the material must be attached to each object.

All objects derived from a :ref:`CanvasItem <class_canvasitem>` have a material property.
This includes all :ref:`GUI elements <class_Control>`, :ref:`Sprites <class_sprite>`, :ref:`TileMaps <class_tilemap>`,
:ref:`MeshInstance2Ds <class_meshinstance2d>` 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 <doc_vector_math>`
``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 <doc_shading_language>`.

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 <https://www.shadertoy.com/results?query=&sort=popular&from=10&num=4>`_ and `The Book of Shaders <https://thebookofshaders.com>`_.