Browse Source

Clarify when to use BackBufferCopy in Screen-reading shaders

Hugo Locurcio 4 years ago
parent
commit
9d5a348c49
1 changed files with 14 additions and 7 deletions
  1. 14 7
      tutorials/shading/screen-reading_shaders.rst

+ 14 - 7
tutorials/shading/screen-reading_shaders.rst

@@ -6,7 +6,7 @@ Screen-reading shaders
 Introduction
 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
 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
 difficult because of internal hardware limitations. GPUs are extremely
 parallel, so reading and writing causes all sorts of cache and coherency
 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,
 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
 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
 SCREEN_TEXTURE built-in texture
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -42,7 +42,7 @@ of blur at no cost.
 .. note::
 .. note::
 
 
    Mipmaps are not generated in GLES2 due to poor performance and compatibility with older
    Mipmaps are not generated in GLES2 due to poor performance and compatibility with older
-   devices. 
+   devices.
 
 
 SCREEN_TEXTURE example
 SCREEN_TEXTURE example
 ~~~~~~~~~~~~~~~~~~~~~~
 ~~~~~~~~~~~~~~~~~~~~~~
@@ -101,13 +101,20 @@ With correct back-buffer copying, the two spheres blend correctly:
 
 
 .. image:: img/texscreen_demo2.png
 .. 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
 ``SCREEN_TEXTURE`` in 3D as it won't capture transparent objects and may capture
 some opaque objects that are in front of the object.
 some opaque objects that are in front of the object.
 
 
 You can reproduce the back-buffer logic in 3D by creating a :ref:`Viewport <class_Viewport>`
 You can reproduce the back-buffer logic in 3D by creating a :ref:`Viewport <class_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 <class_Viewport>` texture instead of ``SCREEN_TEXTURE``.
 :ref:`Viewport's <class_Viewport>` texture instead of ``SCREEN_TEXTURE``.
 
 
 Back-buffer logic
 Back-buffer logic
@@ -136,7 +143,7 @@ Godot:
 DEPTH_TEXTURE
 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
 the ``DEPTH_TEXTURE`` built-in is used. This texture is not linear; it must be
 converted via the inverse projection matrix.
 converted via the inverse projection matrix.