Merge pull request #9940 from tetrapod00/shader-upgrading

Add 3->4 upgrading information about NDC, light(), and reverse-z

tutorials/migrating/upgrading_to_godot_4.rst

@@ -509,13 +509,15 @@ environment effect and its visual knobs remain within the Environment resource.
 Updating shaders
 ^^^^^^^^^^^^^^^^
 
-There have been some changes to shaders that aren't covered by the upgrade tool.
+There have been some changes to shaders that aren't covered by the upgrade tool. 
+You will need to make some manual changes, especially if your shader uses coordinate
+space transformations or a custom ``light()`` function.
 
 The ``.shader`` file extension is no longer supported, which means you must
 rename ``.shader`` files to ``.gdshader`` and update references accordingly in
 scene/resource files using an external text editor.
 
-Some notable renames you will need to perform in shaders are:
+Some notable changes you will need to perform in shaders are:
 
 - Texture filter and repeat modes are now set on individual uniforms, rather
   than the texture files themselves.
@@ -524,9 +526,22 @@ Some notable renames you will need to perform in shaders are:
 - :ref:`Built in matrix variables were renamed. <doc_spatial_shader>`
 - Particles shaders no longer use the ``vertex()`` processor function. Instead
   they use ``start()`` and ``process()``.
+- In the Forward+ and Mobile renderers, normalized device coordinates now have a Z-range of ``[0.0,1.0]``
+  instead of ``[-1.0,1.0]``. When reconstructing NDC from ``SCREEN_UV`` and depth, use 
+  ``vec3 ndc = vec3(SCREEN_UV * 2.0 - 1.0, depth);`` instead of 
+  ``vec3 ndc = vec3(SCREEN_UV, depth) * 2.0 - 1.0;``. The Compatibility renderer is unchanged,
+  using the same NDC Z-range as 3.x.
+- The lighting model changed. If your shader has a custom ``light()`` function,
+  you may need to make changes to get the same visual result.
+- In 4.3 and up, the reverse Z depth buffer technique is now implemented, which 
+  may break advanced shaders. See 
+  `Introducing Reverse Z (AKA I'm sorry for breaking your shader) <https://godotengine.org/article/introducing-reverse-z/>`__.
 
 See :ref:`doc_shading_language` for more information.
 
+This list is not exhaustive. If you made all the changes mentioned here and your 
+shader still doesn't work, try asking for help in one of the `community channels <https://godotengine.org/community/>`__.
+
 Updating scripts to take backwards-incompatible changes into account
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^