Skip to content

Commit 0723c00

Browse files
tetrapod00tetrapod00
committed
Standardize style within spatial_shader.rst, etc
1 parent d3f3c4f commit 0723c00

5 files changed

Lines changed: 196 additions & 193 deletions

File tree

‎tutorials/shaders/shader_reference/canvas_item_shader.rst‎

Lines changed: 44 additions & 40 deletions
Original file line numberDiff line numberDiff line change
@@ -6,9 +6,9 @@ CanvasItem shaders
66
CanvasItem shaders are used to draw all 2D elements in Godot. These include
77
all nodes that inherit from CanvasItems, and all GUI elements.
88

9-
CanvasItem shaders contain less built-in variables and functionality than Spatial
10-
shaders, but they maintain the same basic structure with vertex, fragment, and
11-
light processor functions.
9+
CanvasItem shaders contain less built-in variables and functionality than
10+
:ref:`Spatial shaders<doc_spatial_shader>`, but they maintain the same basic structure
11+
with vertex, fragment, and light processor functions.
1212

1313
Render modes
1414
^^^^^^^^^^^^
@@ -32,18 +32,18 @@ Render modes
3232
+---------------------------------+----------------------------------------------------------------------+
3333
| **light_only** | Only draw on light pass. |
3434
+---------------------------------+----------------------------------------------------------------------+
35-
| **skip_vertex_transform** | VERTEX needs to be transformed manually in vertex function. |
35+
| **skip_vertex_transform** | ``VERTEX`` needs to be transformed manually in the ``vertex()`` |
36+
| | function. |
3637
+---------------------------------+----------------------------------------------------------------------+
37-
| **world_vertex_coords** | VERTEX is modified in world coordinates instead of local. |
38+
| **world_vertex_coords** | ``VERTEX`` is modified in world coordinates instead of local. |
3839
+---------------------------------+----------------------------------------------------------------------+
3940

4041
Built-ins
4142
^^^^^^^^^
4243

43-
Values marked as "in" are read-only. Values marked as "out" are for optional writing and will
44-
not necessarily contain sensible values. Values marked as "inout" provide a sensible default
45-
value, and can optionally be written to. Samplers are not subjects of writing and they are
46-
not marked.
44+
Values marked as ``in`` are read-only. Values marked as ``out`` can optionally be written to and will
45+
not necessarily contain sensible values. Values marked as ``inout`` provide a sensible default
46+
value, and can optionally be written to. Samplers cannot be written to so they are not marked.
4747

4848
Global built-ins
4949
^^^^^^^^^^^^^^^^
@@ -53,7 +53,7 @@ Global built-ins are available everywhere, including custom functions.
5353
+-------------------+-----------------------------------------------------------------------------------------+
5454
| Built-in | Description |
5555
+===================+=========================================================================================+
56-
| in float **TIME** | Global time since the engine has started, in seconds. It repeats after every 3,600 |
56+
| in float **TIME** | Global time since the engine has started, in seconds. It repeats after every ``3,600`` |
5757
| | seconds (which can be changed with the |
5858
| | :ref:`rollover<class_ProjectSettings_property_rendering/limits/time/time_rollover_secs>`|
5959
| | setting). It's not affected by :ref:`time_scale<class_Engine_property_time_scale>` or |
@@ -62,7 +62,7 @@ Global built-ins are available everywhere, including custom functions.
6262
| | frame. |
6363
+-------------------+-----------------------------------------------------------------------------------------+
6464
| in float **PI** | A ``PI`` constant (``3.141592``). |
65-
| | A ration of circle's circumference to its diameter and amount of radians in half turn. |
65+
| | A ratio of a circle's circumference to its diameter and amount of radians in half turn. |
6666
+-------------------+-----------------------------------------------------------------------------------------+
6767
| in float **TAU** | A ``TAU`` constant (``6.283185``). |
6868
| | An equivalent of ``PI * 2`` and amount of radians in full turn. |
@@ -90,9 +90,9 @@ happen later) and do it manually with the following code:
9090
VERTEX = (MODEL_MATRIX * vec4(VERTEX, 0.0, 1.0)).xy;
9191
}
9292
93-
Other built-ins, such as UV and COLOR, are also passed through to the fragment function if not modified.
93+
Other built-ins, such as ``UV`` and ``COLOR``, are also passed through to the ``fragment()`` function if not modified.
9494

95-
For instancing, the INSTANCE_CUSTOM variable contains the instance custom data. When using particles, this information
95+
For instancing, the ``INSTANCE_CUSTOM`` variable contains the instance custom data. When using particles, this information
9696
is usually:
9797

9898
* **x**: Rotation angle in radians.
@@ -107,11 +107,12 @@ is usually:
107107
+--------------------------------+----------------------------------------------------+
108108
| in mat4 **CANVAS_MATRIX** | World space to canvas space transform. In canvas |
109109
| | space the origin is the upper-left corner of the |
110-
| | screen and coordinates ranging from (0, 0) to |
110+
| | screen and coordinates ranging from ``(0, 0)`` to |
111111
| | viewport size. |
112112
+--------------------------------+----------------------------------------------------+
113113
| in mat4 **SCREEN_MATRIX** | Canvas space to clip space. In clip space |
114-
| | coordinates ranging from (-1, -1) to (1, 1). |
114+
| | coordinates ranging from ``(-1, -1)`` to |
115+
| | ``(1, 1).`` |
115116
+--------------------------------+----------------------------------------------------+
116117
| in int **INSTANCE_ID** | Instance ID for instancing. |
117118
+--------------------------------+----------------------------------------------------+
@@ -123,12 +124,13 @@ is usually:
123124
| | For a Sprite2D with a texture of size 64x32px, |
124125
| | **TEXTURE_PIXEL_SIZE** = ``vec2(1/64, 1/32)`` |
125126
+--------------------------------+----------------------------------------------------+
126-
| inout vec2 **VERTEX** | Vertex, in local space. |
127+
| inout vec2 **VERTEX** | Vertex position, in local space. |
127128
+--------------------------------+----------------------------------------------------+
128129
| in int **VERTEX_ID** | The index of the current vertex in the vertex |
129130
| | buffer. |
130131
+--------------------------------+----------------------------------------------------+
131-
| inout vec2 **UV** | Normalized texture coordinates. Range from 0 to 1. |
132+
| inout vec2 **UV** | Normalized texture coordinates. Range from ``0.0`` |
133+
| | to ``1.0`` |
132134
+--------------------------------+----------------------------------------------------+
133135
| inout vec4 **COLOR** | Color from vertex primitive. |
134136
+--------------------------------+----------------------------------------------------+
@@ -143,7 +145,7 @@ Fragment built-ins
143145
^^^^^^^^^^^^^^^^^^
144146

145147
Certain Nodes (for example, :ref:`Sprite2Ds <class_Sprite2D>`) display a texture
146-
by default. However, when a custom fragment function is attached to these nodes,
148+
by default. However, when a custom ``fragment()`` function is attached to these nodes,
147149
the texture lookup needs to be done manually. Godot provides the texture color
148150
in the ``COLOR`` built-in variable multiplied by the node's color. To read the
149151
texture color by itself, you can use:
@@ -155,17 +157,18 @@ texture color by itself, you can use:
155157
Similarly, if a normal map is used in the :ref:`CanvasTexture <class_CanvasTexture>`, Godot uses
156158
it by default and assigns its value to the built-in ``NORMAL`` variable. If you are using a normal
157159
map meant for use in 3D, it will appear inverted. In order to use it in your shader, you must assign
158-
it to the ``NORMALMAP`` property. Godot will handle converting it for use in 2D and overwriting ``NORMAL``.
160+
it to the ``NORMAL_MAP`` property. Godot will handle converting it for use in 2D and overwriting ``NORMAL``.
159161

160162
.. code-block:: glsl
161163
162-
NORMALMAP = texture(NORMAL_TEXTURE, UV).rgb;
164+
NORMAL_MAP = texture(NORMAL_TEXTURE, UV).rgb;
163165
164166
+---------------------------------------------+---------------------------------------------------------------+
165167
| Built-in | Description |
166168
+=============================================+===============================================================+
167169
| in vec4 **FRAGCOORD** | Coordinate of pixel center. In screen space. ``xy`` specifies |
168-
| | position in window. Origin is upper-left. |
170+
| | position in window. Upper-left of the screen is the origin, |
171+
| | ``(0.0,0.0)``. |
169172
+---------------------------------------------+---------------------------------------------------------------+
170173
| in vec2 **SCREEN_PIXEL_SIZE** | Size of individual pixels. Equal to inverse of resolution. |
171174
+---------------------------------------------+---------------------------------------------------------------+
@@ -183,19 +186,19 @@ it to the ``NORMALMAP`` property. Godot will handle converting it for use in 2D
183186
+---------------------------------------------+---------------------------------------------------------------+
184187
| in vec4 **SPECULAR_SHININESS** | Specular shininess color, as sampled from the texture. |
185188
+---------------------------------------------+---------------------------------------------------------------+
186-
| in vec2 **UV** | UV from vertex function. |
189+
| in vec2 **UV** | UV from the ``vertex()`` function. |
187190
+---------------------------------------------+---------------------------------------------------------------+
188191
| in vec2 **SCREEN_UV** | Screen UV coordinate for current pixel. |
189192
+---------------------------------------------+---------------------------------------------------------------+
190193
| sampler2D **SCREEN_TEXTURE** | Removed in Godot 4. Use a ``sampler2D`` with |
191194
| | ``hint_screen_texture`` instead. |
192195
+---------------------------------------------+---------------------------------------------------------------+
193-
| inout vec3 **NORMAL** | Normal read from **NORMAL_TEXTURE**. Writable. |
196+
| inout vec3 **NORMAL** | Normal read from ``NORMAL_TEXTURE``. Writable. |
194197
+---------------------------------------------+---------------------------------------------------------------+
195198
| sampler2D **NORMAL_TEXTURE** | Default 2D normal texture. |
196199
+---------------------------------------------+---------------------------------------------------------------+
197200
| out vec3 **NORMAL_MAP** | Configures normal maps meant for 3D for use in 2D. If used, |
198-
| | overrides **NORMAL**. |
201+
| | overrides ``NORMAL``. |
199202
+---------------------------------------------+---------------------------------------------------------------+
200203
| out float **NORMAL_MAP_DEPTH** | Normalmap depth for scaling. |
201204
+---------------------------------------------+---------------------------------------------------------------+
@@ -206,8 +209,8 @@ it to the ``NORMALMAP`` property. Godot will handle converting it for use in 2D
206209
| inout vec3 **LIGHT_VERTEX** | Same as ``VERTEX`` but can be written to alter lighting. |
207210
| | Z component represents height. |
208211
+---------------------------------------------+---------------------------------------------------------------+
209-
| inout vec4 **COLOR** | Color from vertex function multiplied by the **TEXTURE** |
210-
| | color. Also output color value. |
212+
| inout vec4 **COLOR** | Color from the ``vertex()`` function multiplied by the |
213+
| | ``TEXTURE`` color. Also output color value. |
211214
+---------------------------------------------+---------------------------------------------------------------+
212215

213216
Light built-ins
@@ -217,12 +220,12 @@ Light processor functions work differently in Godot 4.x than they did in Godot
217220
3.x. In Godot 4.x all lighting is done during the regular draw pass. In other
218221
words, Godot no longer draws the object again for each light.
219222

220-
Use render_mode ``unshaded`` if you do not want the light processor function to
221-
run. Use render_mode ``light_only`` if you only want to see the impact of
223+
Use render mode ``unshaded`` if you do not want the ``light()`` function to
224+
run. Use render mode ``light_only`` if you only want to see the impact of
222225
lighting on an object; this can be useful when you only want the object visible
223226
where it is covered by light.
224227

225-
If you define a light function it will replace the built in light function,
228+
If you define a ``light()`` function it will replace the built in light function,
226229
even if your light function is empty.
227230

228231
Below is an example of a light shader that takes a CanvasItem's normal map into account:
@@ -238,18 +241,19 @@ Below is an example of a light shader that takes a CanvasItem's normal map into
238241
| Built-in | Description |
239242
+==================================+==============================================================================+
240243
| in vec4 **FRAGCOORD** | Coordinate of pixel center. In screen space. ``xy`` specifies |
241-
| | position in window. Origin is lower-left. |
244+
| | position in window. Lower-left of the screen is the origin, ``(0.0,0.0)``. |
242245
+----------------------------------+------------------------------------------------------------------------------+
243-
| in vec3 **NORMAL** | Input Normal. |
246+
| in vec3 **NORMAL** | Input normal. |
244247
+----------------------------------+------------------------------------------------------------------------------+
245-
| in vec4 **COLOR** | Input Color. This is the output of the fragment function. |
248+
| in vec4 **COLOR** | Input color. This is the output of the ``fragment()`` function. |
246249
+----------------------------------+------------------------------------------------------------------------------+
247-
| in vec2 **UV** | UV from vertex function, equivalent to the UV in the fragment function. |
250+
| in vec2 **UV** | UV from the ``vertex()`` function, equivalent to the UV in the |
251+
| | ``fragment()`` function. |
248252
+----------------------------------+------------------------------------------------------------------------------+
249253
| sampler2D **TEXTURE** | Current texture in use for CanvasItem. |
250254
+----------------------------------+------------------------------------------------------------------------------+
251-
| in vec2 **TEXTURE_PIXEL_SIZE** | Normalized pixel size of **TEXTURE**. |
252-
| | For a Sprite2D with a **TEXTURE** of size 64x32px, |
255+
| in vec2 **TEXTURE_PIXEL_SIZE** | Normalized pixel size of ``TEXTURE``. |
256+
| | For a Sprite2D with a ``TEXTURE`` of size ``64x32`` pixels, |
253257
| | **TEXTURE_PIXEL_SIZE** = ``vec2(1/64, 1/32)`` |
254258
+----------------------------------+------------------------------------------------------------------------------+
255259
| in vec2 **SCREEN_UV** | Screen UV coordinate for current pixel. |
@@ -260,14 +264,14 @@ Below is an example of a light shader that takes a CanvasItem's normal map into
260264
+----------------------------------+------------------------------------------------------------------------------+
261265
| in float **LIGHT_ENERGY** | Energy multiplier of Light. |
262266
+----------------------------------+------------------------------------------------------------------------------+
263-
| in vec3 **LIGHT_POSITION** | Position of Light in screen space. If using a ``DirectionalLight2D`` |
267+
| in vec3 **LIGHT_POSITION** | Position of Light in screen space. If using a :ref:`class_DirectionalLight2D`|
264268
| | this is always ``vec3(0,0,0)``. |
265269
+----------------------------------+------------------------------------------------------------------------------+
266270
| in vec3 **LIGHT_DIRECTION** | Direction of Light in screen space. |
267271
+----------------------------------+------------------------------------------------------------------------------+
268-
| in bool **LIGHT_IS_DIRECTIONAL** | ``true`` if this pass is a ``DirectionalLight2D``. |
272+
| in bool **LIGHT_IS_DIRECTIONAL** | ``true`` if this pass is a :ref:`class_DirectionalLight2D`. |
269273
+----------------------------------+------------------------------------------------------------------------------+
270-
| in vec3 **LIGHT_VERTEX** | Pixel position, in screen space as modified in the fragment function. |
274+
| in vec3 **LIGHT_VERTEX** | Pixel position, in screen space as modified in the ``fragment()`` function. |
271275
+----------------------------------+------------------------------------------------------------------------------+
272276
| inout vec4 **LIGHT** | Output color for this Light. |
273277
+----------------------------------+------------------------------------------------------------------------------+
@@ -280,8 +284,8 @@ SDF functions
280284
^^^^^^^^^^^^^
281285

282286
There are a few additional functions implemented to sample an automatically
283-
generated Signed Distance Field texture. These functions available for Fragment
284-
and Light functions of CanvasItem shaders.
287+
generated Signed Distance Field texture. These functions available for the ``fragment()``
288+
and ``light()`` functions of CanvasItem shaders.
285289

286290
The signed distance field is generated from :ref:`class_LightOccluder2D` nodes
287291
present in the scene with the **SDF Collision** property enabled (which is the

0 commit comments

Comments
 (0)