From f7853345fb6bd90c22bb2d5fe2d98e90b82f6ceb Mon Sep 17 00:00:00 2001
From: Hei <40064911+Lielay9@users.noreply.github.com>
Date: Fri, 6 Jun 2025 03:39:14 +0300
Subject: [PATCH] Document POSITION built-in in canvas-item shader reference

Documentation for PR: https://github.com/godotengine/godot/pull/107152
---
 .../shaders/shader_reference/canvas_item_shader.rst      | 9 ++++++++-
 1 file changed, 8 insertions(+), 1 deletion(-)

diff --git a/tutorials/shaders/shader_reference/canvas_item_shader.rst b/tutorials/shaders/shader_reference/canvas_item_shader.rst
index bd82d24124b..0fb26652266 100644
--- a/tutorials/shaders/shader_reference/canvas_item_shader.rst
+++ b/tutorials/shaders/shader_reference/canvas_item_shader.rst
@@ -91,12 +91,16 @@ happen later) and do it manually with the following code:
     render_mode skip_vertex_transform;
 
     void vertex() {
-
         VERTEX = (MODEL_MATRIX * vec4(VERTEX, 0.0, 1.0)).xy;
     }
 
 Other built-ins, such as ``UV`` and ``COLOR``, are also passed through to the ``fragment()`` function if not modified.
 
+The default canvas to clip space transform can be skipped using the ``POSITION`` built-in. If ``POSITION`` is written
+to anywhere in the shader, the value of ``VERTEX`` is ignored and not used in the vertex stage. However, ``VERTEX`` 
+can still be written a value that is transformed to canvas space, interpolated based on the **w** component of 
+``POSITION`` and passed to the fragment shader.
+
 For instancing, the ``INSTANCE_CUSTOM`` variable contains the instance custom data. When using particles, this information
 is usually:
 
@@ -134,6 +138,9 @@ is usually:
 | in int **VERTEX_ID**           | The index of the current vertex in the vertex                  |
 |                                | buffer.                                                        |
 +--------------------------------+----------------------------------------------------------------+
+| out vec4 **POSITION**          | If written to, overrides the final vertex position             |
+|                                | in clip space.                                                 |
++--------------------------------+----------------------------------------------------------------+
 | inout vec2 **UV**              | Normalized texture coordinates. Range from ``0.0``             |
 |                                | to ``1.0``.                                                    |
 +--------------------------------+----------------------------------------------------------------+