Skip to content

Commit 37a5a9b

Browse files
mhilbrunnermhilbrunner
authored
Merge pull request godotengine#8506 from clayjohn/shaders-CI-particles
Update shader reference pages for canvas_item shaders and particle shaders for 4.2
2 parents bdd27be + da93553 commit 37a5a9b

File tree

2 files changed

+133
-108
lines changed

2 files changed

+133
-108
lines changed

‎tutorials/shaders/shader_reference/canvas_item_shader.rst‎

Lines changed: 34 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -32,7 +32,9 @@ Render modes
3232
+---------------------------------+----------------------------------------------------------------------+
3333
| **light_only** | Only draw on light pass. |
3434
+---------------------------------+----------------------------------------------------------------------+
35-
| **skip_vertex_transform** | VERTEX/NORMAL/etc need to be transformed manually in vertex function.|
35+
| **skip_vertex_transform** | VERTEX needs to be transformed manually in vertex function. |
36+
+---------------------------------+----------------------------------------------------------------------+
37+
| **world_vertex_coords** | VERTEX is modified in world coordinates instead of local. |
3638
+---------------------------------+----------------------------------------------------------------------+
3739

3840
Built-ins
@@ -117,7 +119,7 @@ is usually:
117119
+--------------------------------+----------------------------------------------------+
118120
| in vec2 **TEXTURE_PIXEL_SIZE** | Normalized pixel size of default 2D texture. |
119121
| | For a Sprite2D with a texture of size 64x32px, |
120-
| | **TEXTURE_PIXEL_SIZE** = :code:`vec2(1/64, 1/32)` |
122+
| | **TEXTURE_PIXEL_SIZE** = ``vec2(1/64, 1/32)`` |
121123
+--------------------------------+----------------------------------------------------+
122124
| inout vec2 **VERTEX** | Vertex, in local space. |
123125
+--------------------------------+----------------------------------------------------+
@@ -134,16 +136,17 @@ is usually:
134136
Fragment built-ins
135137
^^^^^^^^^^^^^^^^^^
136138

137-
Certain Nodes (for example, :ref:`Sprite2Ds <class_Sprite2D>`) display a texture by default. However,
138-
when a custom fragment function is attached to these nodes, the texture lookup needs to be done
139-
manually. Godot does not provide the texture color in the ``COLOR`` built-in variable; to read
140-
the texture color for such nodes, use:
139+
Certain Nodes (for example, :ref:`Sprite2Ds <class_Sprite2D>`) display a texture
140+
by default. However, when a custom fragment function is attached to these nodes,
141+
the texture lookup needs to be done manually. Godot provides the texture color
142+
in the ``COLOR`` built-in variable multiplied by the node's color. To read the
143+
texture color by itself, you can use:
141144

142145
.. code-block:: glsl
143146
144147
COLOR = texture(TEXTURE, UV);
145148
146-
This differs from the behavior of the built-in normal map. If a normal map is attached, Godot uses
149+
Similarly, if a normal map is used in the :ref:`CanvasTexture <class_CanvasTexture>`, Godot uses
147150
it by default and assigns its value to the built-in ``NORMAL`` variable. If you are using a normal
148151
map meant for use in 3D, it will appear inverted. In order to use it in your shader, you must assign
149152
it to the ``NORMALMAP`` property. Godot will handle converting it for use in 2D and overwriting ``NORMAL``.
@@ -167,7 +170,7 @@ it to the ``NORMALMAP`` property. Godot will handle converting it for use in 2D
167170
+---------------------------------------------+---------------------------------------------------------------+
168171
| in vec2 **TEXTURE_PIXEL_SIZE** | Normalized pixel size of default 2D texture. |
169172
| | For a Sprite2D with a texture of size 64x32px, |
170-
| | **TEXTURE_PIXEL_SIZE** = :code:`vec2(1/64, 1/32)` |
173+
| | **TEXTURE_PIXEL_SIZE** = ``vec2(1/64, 1/32)`` |
171174
+---------------------------------------------+---------------------------------------------------------------+
172175
| in bool **AT_LIGHT_PASS** | Always ``false``. |
173176
+---------------------------------------------+---------------------------------------------------------------+
@@ -198,8 +201,8 @@ it to the ``NORMALMAP`` property. Godot will handle converting it for use in 2D
198201
| inout vec3 **LIGHT_VERTEX** | Same as ``VERTEX`` but can be written to alter lighting. |
199202
| | Z component represents height. |
200203
+---------------------------------------------+---------------------------------------------------------------+
201-
| inout vec4 **COLOR** | Color from vertex function and output fragment color. If |
202-
| | unused, will be set to **TEXTURE** color. |
204+
| inout vec4 **COLOR** | Color from vertex function multiplied by the **TEXTURE** |
205+
| | color. Also output color value. |
203206
+---------------------------------------------+---------------------------------------------------------------+
204207

205208
Light built-ins
@@ -212,7 +215,10 @@ words, Godot no longer draws the object again for each light.
212215
Use render_mode ``unshaded`` if you do not want the light processor function to
213216
run. Use render_mode ``light_only`` if you only want to see the impact of
214217
lighting on an object; this can be useful when you only want the object visible
215-
where it is covered by light.
218+
where it is covered by light.
219+
220+
If you define a light function it will replace the built in light function,
221+
even if your light function is empty.
216222

217223
Below is an example of a light shader that takes a CanvasItem's normal map into account:
218224

@@ -232,22 +238,21 @@ Below is an example of a light shader that takes a CanvasItem's normal map into
232238
+----------------------------------+------------------------------------------------------------------------------+
233239
| in vec3 **NORMAL** | Input Normal. |
234240
+----------------------------------+------------------------------------------------------------------------------+
235-
| in vec4 **COLOR** | Input Color. |
236-
| | This is the output of the fragment function with final modulation applied. |
241+
| in vec4 **COLOR** | Input Color. This is the output of the fragment function. |
237242
+----------------------------------+------------------------------------------------------------------------------+
238243
| in vec2 **UV** | UV from vertex function, equivalent to the UV in the fragment function. |
239244
+----------------------------------+------------------------------------------------------------------------------+
240245
| sampler2D **TEXTURE** | Current texture in use for CanvasItem. |
241246
+----------------------------------+------------------------------------------------------------------------------+
242-
| in vec2 **TEXTURE_PIXEL_SIZE** | Normalized pixel size of default 2D texture. |
243-
| | For a Sprite2D with a texture of size 64x32px, |
244-
| | **TEXTURE_PIXEL_SIZE** = :code:`vec2(1/64, 1/32)` |
247+
| in vec2 **TEXTURE_PIXEL_SIZE** | Normalized pixel size of **TEXTURE**. |
248+
| | For a Sprite2D with a **TEXTURE** of size 64x32px, |
249+
| | **TEXTURE_PIXEL_SIZE** = ``vec2(1/64, 1/32)`` |
245250
+----------------------------------+------------------------------------------------------------------------------+
246251
| in vec2 **SCREEN_UV** | Screen UV coordinate for current pixel. |
247252
+----------------------------------+------------------------------------------------------------------------------+
248253
| in vec2 **POINT_COORD** | UV for Point Sprite. |
249254
+----------------------------------+------------------------------------------------------------------------------+
250-
| in vec4 **LIGHT_COLOR** | Color of Light. |
255+
| in vec4 **LIGHT_COLOR** | Color of Light multiplied by Light's texture. |
251256
+----------------------------------+------------------------------------------------------------------------------+
252257
| in float **LIGHT_ENERGY** | Energy multiplier of Light. |
253258
+----------------------------------+------------------------------------------------------------------------------+
@@ -260,8 +265,7 @@ Below is an example of a light shader that takes a CanvasItem's normal map into
260265
+----------------------------------+------------------------------------------------------------------------------+
261266
| in vec3 **LIGHT_VERTEX** | Pixel position, in screen space as modified in the fragment function. |
262267
+----------------------------------+------------------------------------------------------------------------------+
263-
| inout vec4 **LIGHT** | Value from the Light texture and output color. Can be modified. If not used, |
264-
| | the light function is ignored. |
268+
| inout vec4 **LIGHT** | Output color for this Light. |
265269
+----------------------------------+------------------------------------------------------------------------------+
266270
| in vec4 **SPECULAR_SHININESS** | Specular shininess, as set in the object's texture. |
267271
+----------------------------------+------------------------------------------------------------------------------+
@@ -280,14 +284,14 @@ present in the scene with the **SDF Collision** property enabled (which is the
280284
default). See the :ref:`2D lights and shadows <doc_2d_lights_and_shadows_setting_up_shadows>`
281285
documentation for more information.
282286

283-
+-----------------------------------------------+----------------------------------------+
284-
| Function | Description |
285-
+===============================================+========================================+
286-
| float **texture_sdf** (vec2 sdf_pos) | Performs an SDF texture lookup. |
287-
+-----------------------------------------------+----------------------------------------+
288-
| vec2 **texture_sdf_normal** (vec2 sdf_pos) | Performs an SDF normal texture lookup. |
289-
+-----------------------------------------------+----------------------------------------+
290-
| vec2 **sdf_to_screen_uv** (vec2 sdf_pos) | Converts a SDF to screen UV. |
291-
+-----------------------------------------------+----------------------------------------+
292-
| vec2 **screen_uv_to_sdf** (vec2 uv) | Converts screen UV to a SDF. |
293-
+-----------------------------------------------+----------------------------------------+
287+
+-----------------------------------------------+-------------------------------------------+
288+
| Function | Description |
289+
+===============================================+===========================================+
290+
| float **texture_sdf** (vec2 sdf_pos) | Performs an SDF texture lookup. |
291+
+-----------------------------------------------+-------------------------------------------+
292+
| vec2 **texture_sdf_normal** (vec2 sdf_pos) | Calculates a normal from the SDF texture. |
293+
+-----------------------------------------------+-------------------------------------------+
294+
| vec2 **sdf_to_screen_uv** (vec2 sdf_pos) | Converts a SDF to screen UV. |
295+
+-----------------------------------------------+-------------------------------------------+
296+
| vec2 **screen_uv_to_sdf** (vec2 uv) | Converts screen UV to a SDF. |
297+
+-----------------------------------------------+-------------------------------------------+

0 commit comments

Comments
 (0)