From 9d5a348c49ef9e17ebabfa684aebb85a72f1cde2 Mon Sep 17 00:00:00 2001 From: Hugo Locurcio Date: Tue, 6 Jul 2021 08:32:53 +0200 Subject: [PATCH] Clarify when to use BackBufferCopy in Screen-reading shaders --- tutorials/shading/screen-reading_shaders.rst | 21 +++++++++++++------- 1 file changed, 14 insertions(+), 7 deletions(-) diff --git a/tutorials/shading/screen-reading_shaders.rst b/tutorials/shading/screen-reading_shaders.rst index bfd9b17a0..2ef250f31 100644 --- a/tutorials/shading/screen-reading_shaders.rst +++ b/tutorials/shading/screen-reading_shaders.rst @@ -6,7 +6,7 @@ Screen-reading shaders Introduction ~~~~~~~~~~~~ -Very often, it is desired to make a shader that reads from the same +It is often desired to make a shader that reads from the same screen to which it's writing. 3D APIs, such as OpenGL or DirectX, make this very difficult because of internal hardware limitations. GPUs are extremely parallel, so reading and writing causes all sorts of cache and coherency @@ -15,7 +15,7 @@ properly. The workaround is to make a copy of the screen, or a part of the screen, to a back-buffer and then read from it while drawing. Godot provides a -few tools that make this process easy! +few tools that make this process easy. SCREEN_TEXTURE built-in texture ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -42,7 +42,7 @@ of blur at no cost. .. note:: Mipmaps are not generated in GLES2 due to poor performance and compatibility with older - devices. + devices. SCREEN_TEXTURE example ~~~~~~~~~~~~~~~~~~~~~~ @@ -101,13 +101,20 @@ With correct back-buffer copying, the two spheres blend correctly: .. image:: img/texscreen_demo2.png -In 3D, there is less flexibility to solve this particular issue because the -``SCREEN_TEXTURE`` is only captured once. Be careful when using +.. warning: + + Materials that use ``SCREEN_TEXTURE`` are considered transparent themselves and + will not appear in the resulting ``SCREEN_TEXTURE`` of other materials. + If you plan to instance a scene that uses a material with ``SCREEN_TEXTURE``, + you will need to use a BackBufferCopy node. + +In 3D, there is less flexibility to solve this particular issue because the +``SCREEN_TEXTURE`` is only captured once. Be careful when using ``SCREEN_TEXTURE`` in 3D as it won't capture transparent objects and may capture some opaque objects that are in front of the object. You can reproduce the back-buffer logic in 3D by creating a :ref:`Viewport ` -with a camera in the same position as your object, and then use the +with a camera in the same position as your object, and then use the :ref:`Viewport's ` texture instead of ``SCREEN_TEXTURE``. Back-buffer logic @@ -136,7 +143,7 @@ Godot: DEPTH_TEXTURE ~~~~~~~~~~~~~ -For 3D Shaders, it's also possible to access the screen depth buffer. For this, +For 3D shaders, it's also possible to access the screen depth buffer. For this, the ``DEPTH_TEXTURE`` built-in is used. This texture is not linear; it must be converted via the inverse projection matrix.