diff --git a/tutorials/shaders/index.rst b/tutorials/shaders/index.rst index e0c8627..9d1dca5 100644 --- a/tutorials/shaders/index.rst +++ b/tutorials/shaders/index.rst @@ -9,7 +9,6 @@ Shaders shader_reference/index your_first_shader/index shader_materials - visual_shaders screen-reading_shaders converting_glsl_to_godot_shaders shaders_style_guide diff --git a/tutorials/shaders/shader_reference/index.rst b/tutorials/shaders/shader_reference/index.rst index 50875a6..3ebd792 100644 --- a/tutorials/shaders/shader_reference/index.rst +++ b/tutorials/shaders/shader_reference/index.rst @@ -8,4 +8,3 @@ Shading reference shading_language spatial_shader canvas_item_shader - particle_shader diff --git a/tutorials/shaders/shader_reference/particle_shader.rst b/tutorials/shaders/shader_reference/particle_shader.rst deleted file mode 100644 index d0eb682..0000000 --- a/tutorials/shaders/shader_reference/particle_shader.rst +++ /dev/null @@ -1,92 +0,0 @@ -.. _doc_particle_shader: - -Particle shaders -================ - -Particle shaders are a special type of vertex shader that runs before the -object is drawn. They are used for calculating material properties such as -color, position, and rotation. They are drawn with any regular material for -CanvasItem or Spatial, depending on whether they are 2D or 3D. - -Particle shaders are unique because they are not used to draw the object -itself; they are used to calculate particle properties, which are then used -by the CanvasItem of Spatial shader. They contain only a vertex processor -function that outputs multiple properties (see built-ins below). - -Particle shaders use a transform feedback shader, which is a special type of -vertex shader that runs on its own. It takes in data in a buffer like a regular -vertex shader does, but it also outputs to data buffers instead of outputting -to the fragment shader for pixel-processing. Because of this, transform feedback -shaders can build on themselves each run, unlike other shaders that discard the -data they have calculated once they draw to the frame buffer. - -.. note:: Particle shaders are only available in the GLES3 backend. If you need - particles in GLES2, use :ref:`CPUParticles `. - -Render modes -^^^^^^^^^^^^ - -+---------------------------------+----------------------------------------------------------------------+ -| Render mode | Description | -+=================================+======================================================================+ -| **keep_data** | Do not clear previous data on restart. | -+---------------------------------+----------------------------------------------------------------------+ -| **disable_force** | Disable attractor force. (Not currently implemented in 3.1) | -+---------------------------------+----------------------------------------------------------------------+ -| **disable_velocity** | Ignore **VELOCITY** value. | -+---------------------------------+----------------------------------------------------------------------+ - -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. - -Global built-ins -^^^^^^^^^^^^^^^^ - -Global built-ins are available everywhere, including custom functions. - -+-------------------+--------------------------+ -| Built-in | Description | -+===================+==========================+ -| in float **TIME** | Global time, in seconds. | -+-------------------+--------------------------+ - -Vertex built-ins -^^^^^^^^^^^^^^^^ - -In order to use the ``COLOR`` variable in a SpatialMaterial, set ``use_vertex_as_albedo`` -to ``true``. In a ShaderMaterial, access it with the ``COLOR`` variable. - -+---------------------------------+-------------------------------------------------------------------------------------+ -| Built-in | Description | -+=================================+=====================================================================================+ -| inout vec4 **COLOR** | Particle color, can be written to and accessed in mesh's vertex function. | -+---------------------------------+-------------------------------------------------------------------------------------+ -| inout vec3 **VELOCITY** | Particle velocity, can be modified. | -+---------------------------------+-------------------------------------------------------------------------------------+ -| out float **MASS** | Particle mass, use for attractors (not implemented in 3.1). | -+---------------------------------+-------------------------------------------------------------------------------------+ -| inout bool **ACTIVE** | ``true`` when Particle is active, can be set to ``false``. | -+---------------------------------+-------------------------------------------------------------------------------------+ -| in bool **RESTART** | ``true`` when particle must restart (lifetime cycled). | -+---------------------------------+-------------------------------------------------------------------------------------+ -| inout vec4 **CUSTOM** | Custom particle data. Accessible from shader of mesh as **INSTANCE_CUSTOM**. | -+---------------------------------+-------------------------------------------------------------------------------------+ -| inout mat4 **TRANSFORM** | Particle transform. | -+---------------------------------+-------------------------------------------------------------------------------------+ -| in float **LIFETIME** | Particle lifetime. | -+---------------------------------+-------------------------------------------------------------------------------------+ -| in float **DELTA** | Delta process time. | -+---------------------------------+-------------------------------------------------------------------------------------+ -| in uint **NUMBER** | Unique number since emission start. | -+---------------------------------+-------------------------------------------------------------------------------------+ -| in int **INDEX** | Particle index (from total particles). | -+---------------------------------+-------------------------------------------------------------------------------------+ -| in mat4 **EMISSION_TRANSFORM** | Emitter transform (used for non-local systems). | -+---------------------------------+-------------------------------------------------------------------------------------+ -| in uint **RANDOM_SEED** | Random seed used as base for random. | -+---------------------------------+-------------------------------------------------------------------------------------+ diff --git a/tutorials/shaders/visual_shaders.rst b/tutorials/shaders/visual_shaders.rst deleted file mode 100644 index bbde126..0000000 --- a/tutorials/shaders/visual_shaders.rst +++ /dev/null @@ -1,161 +0,0 @@ -.. _doc_visual_shaders: - -Using VisualShaders -=================== - -Just as VisualScript is an alternative for users that prefer a graphical -approach to coding, VisualShaders are the visual alternative for creating -shaders. - -As shaders are inherently linked to visuals, the graph-based approach with -previews of textures, materials, etc. offers a lot of additional convenience -compared to purely script-based shaders. On the other hand, VisualShaders do not -expose all features of the shader script and using both in parallel might be -necessary for specific effects. - -.. note:: - - If you are not familiar with shaders, start by reading - :ref:`doc_introduction_to_shaders`. - -Creating a VisualShader ------------------------ - -VisualShaders can be created in any :ref:`class_ShaderMaterial`. To begin using -VisualShaders, create a new ``ShaderMaterial`` in an object of your choice. - -.. image:: img/shader_material_create_mesh.png - -Then assign a :ref:`class_VisualShader` resource to the ``Shader`` property. - -.. image:: img/visual_shader_create.png - -Click on the new ``VisualShader`` resource and the Visual Shader Editor will -open automatically. The layout of the Visual Shader Editor comprises two parts: -the upper toolbar and the graph itself. - -.. image:: img/visual_shader_editor2.png - -From left to right in the toolbar: - -- The ``Add Node`` button displays a popup menu to let you add nodes to the - shader graph. -- The drop-down menu is the shader type: Vertex, Fragment and Light. Like for - script shaders, it defines what built-in nodes will be available. -- The following buttons and number input control the zooming level, grid - snapping and distance between grid lines (in pixels). -- The last icon shows the generated shader code corresponding to your graph. - -.. note:: - - Although VisualShaders do not require coding, they share the same logic with - script shaders. It is advised to learn the basics of both to have a good - understanding of the shading pipeline. - - The visual shader graph is converted to a script shader behind the scene, - and you can see this code by pressing the last button in the toolbar. This - can be convenient to understand what a given node does and how to reproduce - it in scripts. - -Using the Visual Shader Editor ------------------------------- - -By default, every new ``VisualShader`` will have an output node. Every node -connection ends at one of the output node's sockets. A node is the basic unit to -create your shader. To add a new node, click on the ``Add Node`` button on the -upper left corner or right click on any empty location in the graph, and a menu -will pop up. - -.. image:: img/vs_popup.png - -This popup has the following properties: - -- If you right-click on the graph, this menu will be called at the cursor - position and the created node, in that case, will also be placed under that - position; otherwise, it will be created at the graph's center. -- It can be resized horizontally and vertically allowing more content to be - shown. Size transform and tree content position are saved between the calls, - so if you suddenly closed the popup you can easily restore its previous state. -- The ``Expand All`` and ``Collapse All`` options in the drop-down option menu - can be used to easily list the available nodes. -- You can also drag and drop nodes from the popup onto the graph. - -While the popup has nodes sorted in categories, it can seem overwhelming at -first. Try to add some of the nodes, plug them in the output socket and observe -what happens. - -When connecting any ``scalar`` output to a ``vector`` input, all components of -the vector will take the value of the scalar. - -When connecting any ``vector`` output to a ``scalar`` input, the value of the -scalar will be the average of the vector's components. - -Visual Shader nodes -------------------- - -Below are some special nodes that are worth knowing about. The list is not -exhaustive and might be expanded with more nodes and examples. - -Expression node -+++++++++++++++ - -The ``Expression`` node allows you to write Godot Shading Language (GLSL-like) -expressions inside your visual shaders. The node has buttons to add any amount -of required input and output ports and can be resized. You can also set up the -name and type of each port. The expression you have entered will apply -immediately to the material (once the focus leaves the expression text box). Any -parsing or compilation errors will be printed to the Output tab. The outputs are -initialized to their zero value by default. The node is located under the -Special tab and can be used in all shader modes. - -.. image:: img/vs_expression.gif - -The possibilities of this node are almost limitless – you can write complex -procedures, and use all the power of text-based shaders, such as loops, the -``discard`` keyword, extended types, etc. For example: - -.. image:: img/vs_expression2.png - -Fresnel node -++++++++++++ - -The ``Fresnel`` node is designed to accept normal and view vectors and produces -a scalar which is the saturated dot product between them. Additionally, you can -setup the inversion and the power of equation. The ``Fresnel`` node is great for -adding a rim-like lighting effect to objects. - -.. image:: img/vs_fresnel.png - -Boolean node -++++++++++++ - -The ``Boolean`` node can be converted to ``Scalar`` or ``Vector`` to represent -``0`` or ``1`` and ``(0, 0, 0)`` or ``(1, 1, 1)`` respectively. This property -can be used to enable or disable some effect parts with one click. - -.. image:: img/vs_boolean.gif - -If node -+++++++ - -The ``If`` node allows you to setup a vector which will be returned the result -of the comparison between ``a`` and ``b``. There are three vectors which can be -returned: ``a == b`` (in that case the tolerance parameter is provided as a -comparison threshold – by default it is equal to the minimal value, i.e. -``0.00001``), ``a > b`` and ``a < b``. - -.. image:: img/vs_if.png - -Switch node -+++++++++++ - -The ``Switch`` node returns a vector if the boolean condition is ``true`` or -``false``. ``Boolean`` was introduced above. If you convert a vector to a true -boolean, all components of the vector should be above zero. - -.. image:: img/vs_switch.png - -.. note:: - - The ``Switch`` node is only available on the GLES3 backed. If you are - targeting GLES2 devices, you cannot use ``switch`` statements.