Merge pull request #11441 from Calinou/shader-reference-avoid-texturesize

Document `textureSize()` should be avoided in Built-in functions

tutorials/shaders/shader_reference/canvas_item_shader.rst

@@ -127,7 +127,7 @@ is usually:
 +--------------------------------+----------------------------------------------------------------+
 | in vec2 **TEXTURE_PIXEL_SIZE** | Normalized pixel size of the default 2D texture.               |
 |                                | For a Sprite2D with a texture of size 64x32px,                 |
-|                                | **TEXTURE_PIXEL_SIZE** = ``vec2(1/64, 1/32)``                  |
+|                                | **TEXTURE_PIXEL_SIZE** = ``vec2(1.0/64.0, 1.0/32.0)``          |
 +--------------------------------+----------------------------------------------------------------+
 | inout vec2 **VERTEX**          | Vertex position, in local space.                               |
 +--------------------------------+----------------------------------------------------------------+

tutorials/shaders/shader_reference/shader_functions.rst

@@ -2254,9 +2254,9 @@ Texture functions
     +------------------+---------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+
     | | ivec2          | | :ref:`textureSize<shader_func_textureSize>`\ (\ |gsampler2D| s, int lod)                              | Get the size of a texture.                                          |
     | | ivec2          | | :ref:`textureSize<shader_func_textureSize>`\ (\ samplerCube s, int lod)                               |                                                                     |
-    | | ivec2          | | :ref:`textureSize<shader_func_textureSize>`\ (\ samplerCubeArray s, int lod)                          |                                                                     |
-    | | ivec3          | | :ref:`textureSize<shader_func_textureSize>`\ (\ |gsampler2DArray| s, int lod)                         |                                                                     |
-    | | ivec3          | | :ref:`textureSize<shader_func_textureSize>`\ (\ |gsampler3D| s, int lod)                              |                                                                     |
+    | | ivec2          | | :ref:`textureSize<shader_func_textureSize>`\ (\ samplerCubeArray s, int lod)                          | For performance reasons, this function should be avoided as it      |
+    | | ivec3          | | :ref:`textureSize<shader_func_textureSize>`\ (\ |gsampler2DArray| s, int lod)                         | always performs a full texture read. When possible, you should pass |
+    | | ivec3          | | :ref:`textureSize<shader_func_textureSize>`\ (\ |gsampler3D| s, int lod)                              | the texture size as a uniform instead.                              |
     +------------------+---------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+
     | | vec2           | | :ref:`textureQueryLod<shader_func_textureQueryLod>`\ (\ |gsampler2D| s, vec2 p)                       | Compute the level-of-detail that would be used to sample from a     |
     | | vec3           | | :ref:`textureQueryLod<shader_func_textureQueryLod>`\ (\ |gsampler2DArray| s, vec2 p)                  | texture.                                                            |