Update Viewports tutorial for Godot 4 (#8210)

Co-authored-by: Hugo Locurcio <[email protected]>

tutorials/rendering/viewports.rst

@@ -1,5 +1,3 @@
-:article_outdated: True
-
 .. _doc_viewports:
 
 Using Viewports
@@ -9,22 +7,19 @@ Introduction
 ------------
 
 Think of a :ref:`Viewport <class_Viewport>` as a screen onto which the game is projected. In order
-to see the game, we need to have a surface on which to draw it; that surface is
-the Root :ref:`Viewport <class_Viewport>`.
-
-.. image:: img/viewportnode.png
+to see the game, we need to have a surface on which to draw it. That surface is
+the Root Viewport.
 
+.. image:: img/subviewportnode.webp
 
-:ref:`Viewports <class_Viewport>` can also be added to the scene so that there
-are multiple surfaces to draw on. When we are drawing to a :ref:`Viewport <class_Viewport>`
-that is not the Root, we call it a render target. We can access the contents
-of a render target by accessing its corresponding :ref:`texture <class_ViewportTexture>`.
-By using a :ref:`Viewport <class_Viewport>` as a render target,
-we can either render multiple scenes simultaneously or we can render to
-a :ref:`texture <class_ViewportTexture>` which is applied to an object in the scene, for example a dynamic
+:ref:`SubViewports <class_SubViewport>` are a kind of Viewport that can be added to the scene so that there
+are multiple surfaces to draw on. When we are drawing to a SubViewport, we call it a render target. We can access the contents
+of a render target by accessing its corresponding :ref:`texture <class_Viewport_method_get_texture>`.
+By using a SubViewport as render target, we can either render multiple scenes simultaneously or we can render to
+a :ref:`ViewportTexture <class_ViewportTexture>` which is applied to an object in the scene, for example a dynamic
 skybox.
 
-:ref:`Viewports <class_Viewport>` have a variety of use cases, including:
+:ref:`SubViewports <class_SubViewport>` have a variety of use cases, including:
 
 - Rendering 3D objects within a 2D game
 - Rendering 2D elements in a 3D game
@@ -36,6 +31,9 @@ What all these use cases have in common is that you are given the ability to
 draw objects to a texture as if it were another screen and can then choose
 what to do with the resulting texture.
 
+Another kind of Viewports in Godot are :ref:`Windows <class_Window>`. They allow their content to be projected onto a window. While the Root Viewport is a Window, they are less
+flexible. If you want to use the texture of a Viewport, you'll be working with :ref:`SubViewports <class_SubViewport>` most of the time.
+
 Input
 -----
 
@@ -45,37 +43,37 @@ automatically receive input, unless they receive it from their direct
 :ref:`SubViewportContainer <class_SubViewportContainer>` parent node. In this case, input can be
 disabled with the :ref:`Disable Input <class_Viewport_property_gui_disable_input>` property.
 
-.. image:: img/input.png
+.. image:: img/input.webp
 
-For more information on how Godot handles input, please read the :ref:`Input Event Tutorial<doc_inputevent>`.
+For more information on how Godot handles input, please read the :ref:`Input Event Tutorial <doc_inputevent>`.
 
 Listener
 --------
 
-Godot supports 3D sound (in both 2D and 3D nodes); more on this can be
-found in the :ref:`Audio Streams Tutorial<doc_audio_streams>`. For this type of sound to be
+Godot supports 3D sound (in both 2D and 3D nodes). More on this can be
+found in the :ref:`Audio Streams Tutorial <doc_audio_streams>`. For this type of sound to be
 audible, the :ref:`Viewport <class_Viewport>` needs to be enabled as a listener (for 2D or 3D).
-If you are using a custom :ref:`Viewport <class_Viewport>` to display your :ref:`World3D <class_World3D>` or
+If you are using a :ref:`SubViewport <class_SubViewport>` to display your :ref:`World3D <class_World3D>` or
 :ref:`World2D <class_World2D>`, don't forget to enable this!
 
 Cameras (2D & 3D)
 -----------------
 
-When using a :ref:`Camera3D <class_Camera3D>` /
-:ref:`Camera2D <class_Camera2D>`, cameras will always display on the
+When using a :ref:`Camera3D <class_Camera3D>` or
+:ref:`Camera2D <class_Camera2D>`, it will always display on the
 closest parent :ref:`Viewport <class_Viewport>` (going towards the root). For example, in the
 following hierarchy:
 
-.. image:: img/cameras.png
+.. image:: img/cameras.webp
 
-CameraA will display on the Root :ref:`Viewport <class_Viewport>` and it will draw MeshA. CameraB
-will be captured by the :ref:`Viewport <class_Viewport>` Node along with MeshB. Even though MeshB is in the scene
-hierarchy, it will still not be drawn to the Root :ref:`Viewport <class_Viewport>`. Similarly MeshA will not
-be visible from the :ref:`Viewport <class_Viewport>` node because :ref:`Viewport <class_Viewport>` nodes only
+``CameraA`` will display on the Root :ref:`Viewport <class_Viewport>` and it will draw ``MeshA``. ``CameraB``
+will be captured by the :ref:`SubViewport <class_SubViewport>` along with ``MeshB``. Even though ``MeshB`` is in the scene
+hierarchy, it will still not be drawn to the Root Viewport. Similarly, ``MeshA`` will not
+be visible from the SubViewport because SubViewports only
 capture nodes below them in the hierarchy.
 
 There can only be one active camera per :ref:`Viewport <class_Viewport>`, so if there is more
-than one, make sure that the desired one has the "current" property set,
+than one, make sure that the desired one has the :ref:`current <class_Camera3D_property_current>` property set,
 or make it the current camera by calling:
 
 ::
@@ -90,65 +88,63 @@ property to restrict which objects are rendered.
 Scale & stretching
 ------------------
 
-:ref:`Viewports <class_Viewport>` have a "size" property, which represents the size of the :ref:`Viewport <class_Viewport>`
-in pixels. For :ref:`Viewports <class_Viewport>` which are children of :ref:`SubViewportContainers <class_SubViewportContainer>`,
+:ref:`SubViewports <class_SubViewport>` have a :ref:`size<class_SubViewport_property_size>` property, which represents the size of the SubViewport
+in pixels. For SubViewports which are children of :ref:`SubViewportContainers <class_SubViewportContainer>`,
 these values are overridden, but for all others, this sets their resolution.
 
-It is also possible to scale the 2D content and make the :ref:`Viewport <class_Viewport>` resolution
+It is also possible to scale the 2D content and make the :ref:`SubViewport <class_SubViewport>` resolution
 different from the one specified in size, by calling:
 
 ::
 
-    viewport.set_size_override(true, Vector2(width, height)) # Custom size for 2D.
-    viewport.set_size_override_stretch(true) # Enable stretch for custom size.
+    sub_viewport.set_size_2d_override(Vector2i(width, height)) # Custom size for 2D.
+    sub_viewport.set_size_2d_override_stretch(true) # Enable stretch for custom size.
 
-The root :ref:`Viewport <class_Viewport>` uses this for the stretch options in the project
-settings. For more information on scaling and stretching visit the :ref:`Multiple Resolutions Tutorial <doc_multiple_resolutions>`
+For information on scaling and stretching with the Root Viewport visit the :ref:`Multiple Resolutions Tutorial <doc_multiple_resolutions>`
 
 Worlds
 ------
 
 For 3D, a :ref:`Viewport <class_Viewport>` will contain a :ref:`World3D <class_World3D>`. This
 is basically the universe that links physics and rendering together.
-Node3D-based nodes will register using the :ref:`World3D <class_World3D>` of the closest :ref:`Viewport <class_Viewport>`.
-By default, newly created :ref:`Viewports <class_Viewport>` do not contain a :ref:`World3D <class_World3D>` but
-use the same as their parent :ref:`Viewport <class_Viewport>` (the root :ref:`Viewport <class_Viewport>` always contains a
-:ref:`World3D <class_World3D>`, which is the one objects are rendered to by default). A :ref:`World3D <class_World3D>` can
-be set in a :ref:`Viewport <class_Viewport>` using the "world" property, and that will separate
-all children nodes of that :ref:`Viewport <class_Viewport>` from interacting with the parent
-:ref:`Viewport's <class_Viewport>` :ref:`World3D <class_World3D>`. This is especially useful in scenarios where, for
+Node3D-based nodes will register using the World3D of the closest Viewport.
+By default, newly created Viewports do not contain a World3D but
+use the same as their parent Viewport. The Root Viewport always contains a
+World3D, which is the one objects are rendered to by default.
+
+A :ref:`World3D <class_World3D>` can
+be set in a :ref:`Viewport <class_Viewport>` using the :ref:`World 3D<class_Viewport_property_world_3d>` property, that will separate
+all children nodes of this :ref:`Viewport <class_Viewport>` and will prevent them from interacting with the parent
+Viewport's World3D. This is especially useful in scenarios where, for
 example, you might want to show a separate character in 3D imposed over
 the game (like in StarCraft).
 
 As a helper for situations where you want to create :ref:`Viewports <class_Viewport>` that
-display single objects and don't want to create a :ref:`World3D <class_World3D>`, :ref:`Viewport <class_Viewport>` has
-the option to use its own :ref:`World3D <class_World3D>`. This is useful when you want to
-instance 3D characters or objects in a 2D :ref:`World2D <class_World2D>`.
+display single objects and don't want to create a :ref:`World3D <class_World3D>`, Viewport has
+the option to use its :ref:`Own World3D <class_Viewport_property_own_world_3d>`. This is useful when you want to
+instance 3D characters or objects in :ref:`World2D <class_World2D>`.
 
 For 2D, each :ref:`Viewport <class_Viewport>` always contains its own :ref:`World2D <class_World2D>`.
 This suffices in most cases, but in case sharing them may be desired, it
-is possible to do so by setting the :ref:`Viewport's <class_Viewport>` :ref:`World2D <class_World2D>` manually.
+is possible to do so by setting :ref:`world_2d<class_Viewport_property_world_2d>` on the Viewport through code.
 
 For an example of how this works, see the demo projects `3D in 2D <https://github.com/godotengine/godot-demo-projects/tree/master/viewport/3d_in_2d>`_ and `2D in 3D <https://github.com/godotengine/godot-demo-projects/tree/master/viewport/2d_in_3d>`_ respectively.
 
 Capture
 -------
 
-It is possible to query a capture of the :ref:`Viewport <class_Viewport>` contents. For the root
-:ref:`Viewport <class_Viewport>`, this is effectively a screen capture. This is done with the
+It is possible to query a capture of the :ref:`Viewport <class_Viewport>` contents. For the Root
+Viewport, this is effectively a screen capture. This is done with the
 following code:
 
 ::
 
    # Retrieve the captured Image using get_image().
    var img = get_viewport().get_texture().get_image()
-   # Flip on the Y axis.
-   # You can also set "V Flip" to true if not on the root Viewport.
-   img.flip_y()
    # Convert Image to ImageTexture.
    var tex = ImageTexture.create_from_image(img)
    # Set sprite texture.
-   $sprite.texture = tex
+   sprite.texture = tex
 
 But if you use this in ``_ready()`` or from the first frame of the :ref:`Viewport's <class_Viewport>` initialization,
 you will get an empty texture because there is nothing to get as texture. You can deal with
@@ -163,93 +159,92 @@ it using (for example):
 Viewport Container
 ------------------
 
-If the :ref:`Viewport <class_Viewport>` is a child of a :ref:`SubViewportContainer <class_SubViewportContainer>`, it will become active and display anything it has inside. The layout looks like this:
+If the :ref:`SubViewport <class_SubViewport>` is a child of a :ref:`SubViewportContainer <class_SubViewportContainer>`, it will become active and display anything it has inside. The layout looks like this:
+
+.. image:: img/container.webp
 
-.. image:: img/container.png
+The :ref:`SubViewport <class_SubViewport>` will cover the area of its parent :ref:`SubViewportContainer <class_SubViewportContainer>` completely
+if :ref:`Stretch<class_SubViewportContainer_property_stretch>` is set to ``true`` in the SubViewportContainer.
 
-The :ref:`Viewport <class_Viewport>` will cover the area of its parent :ref:`SubViewportContainer <class_SubViewportContainer>` completely
-if :ref:`Stretch<class_SubViewportContainer_property_stretch>` is set to ``true`` in :ref:`SubViewportContainer <class_SubViewportContainer>`.
-Note: The size of the :ref:`SubViewportContainer <class_SubViewportContainer>` cannot be smaller than the size of the :ref:`Viewport <class_Viewport>`.
+.. note::
+
+    The size of the :ref:`SubViewportContainer <class_SubViewportContainer>` cannot be smaller than the size of the :ref:`SubViewport <class_SubViewport>`.
 
 Rendering
 ---------
 
 Due to the fact that the :ref:`Viewport <class_Viewport>` is an entryway into another rendering surface, it exposes a few
-rendering properties that can be different from the project settings. The first is MSAA; you can
-choose to use a different level of MSAA for each :ref:`Viewport <class_Viewport>`; the default behavior is DISABLED.
-You can also set the :ref:`Viewport <class_Viewport>` to use HDR, HDR is very useful for when you want to store values in the texture that are outside the range 0.0 - 1.0.
+rendering properties that can be different from the project settings. You can
+choose to use a different level of :ref:`MSAA <class_Viewport_property_msaa_2d>` for each Viewport. The default behavior is ``Disabled``.
 
-If you know how the :ref:`Viewport <class_Viewport>` is going to be used, you can set its Usage to either 3D or 2D. Godot will then
-restrict how the :ref:`Viewport <class_Viewport>` is drawn to in accordance with your choice; default is 3D.
-The 2D usage mode is slightly faster and uses less memory compared to the 3D one. It's a good idea to set the :ref:`Viewport <class_Viewport>`'s Usage property to 2D if your viewport doesn't render anything in 3D.
+If you know that the :ref:`Viewport <class_Viewport>` is only going to be used for 2D, you can :ref:`Disable 3D<class_Viewport_property_disable_3d>`. Godot will then
+restrict how the Viewport is drawn.
+Disabling 3D is slightly faster and uses less memory compared to enabled 3D. It's a good idea to disable 3D if your viewport doesn't render anything in 3D.
 
 .. note::
 
-    If you need to render 3D shadows in the viewport, make sure to set the viewport's *Shadow Atlas Size* property to a value higher than 0.
-    Otherwise, shadows won't be rendered. For reference, the Project Settings define it to 4096 by default.
+    If you need to render 3D shadows in the viewport, make sure to set the viewport's :ref:`positional_shadow_atlas_size<class_Viewport_property_positional_shadow_atlas_size>` property to a value higher than ``0``.
+    Otherwise, shadows won't be rendered. By default, the equivalent project setting is set to ``4096`` on desktop platforms and ``2048`` on mobile platforms.
 
-Godot also provides a way of customizing how everything is drawn inside :ref:`Viewports <class_Viewport>` using "Debug Draw".
-Debug Draw allows you to specify one of four options for how the :ref:`Viewport <class_Viewport>` will display things drawn
-inside it. Debug Draw is disabled by default.
+Godot also provides a way of customizing how everything is drawn inside :ref:`Viewports <class_Viewport>` using :ref:`Debug Draw<class_Viewport_property_debug_draw>`.
+Debug Draw allows you to specify a mode which determines how the Viewport will display things drawn
+inside it. Debug Draw is ``Disabled`` by default. Some other options are ``Unshaded``, ``Overdraw``, and ``Wireframe``. For a full list, refer to the :ref:`Viewport Documentation<class_Viewport_property_debug_draw>`.
 
-.. image:: img/default_scene.png
+-  **Debug Draw = Disabled** (default): The scene is drawn normally.
 
-*A scene drawn with Debug Draw disabled*
+  .. image:: img/default_scene.webp
 
-The other three options are Unshaded, Overdraw, and Wireframe. Unshaded draws the scene
-without using lighting information so all the objects appear flatly colored the color of
-their albedo.
+-  **Debug Draw = Unshaded**: Unshaded draws the scene without using lighting information so all the objects appear flatly colored in their albedo color.
 
-.. image:: img/unshaded.png
+  .. image:: img/unshaded.webp
 
-*The same scene with Debug Draw set to Unshaded*
+-  **Debug Draw = Overdraw**: Overdraw draws the meshes semi-transparent with an additive blend so you can see how the meshes overlap.
 
-Overdraw draws the meshes semi-transparent with an additive blend so you can see how the meshes overlap.
+  .. image:: img/overdraw.webp
 
-.. image:: img/overdraw.png
+-  **Debug Draw = Wireframe**: Wireframe draws the scene using only the edges of triangles in the meshes.
 
-*The same scene with Debug Draw set to Overdraw*
-
-Lastly, Wireframe draws the scene using only the edges of triangles in the meshes.
+  .. image:: img/wireframe.webp
 
 .. note::
 
-    The effects of the Wireframe mode are only visible in the editor, not while the project is running.
+    Debug Draw modes are currently **not** supported when using the
+    Compatibility rendering method. They will appear as regular draw modes.
 
 Render target
 -------------
 
-When rendering to a :ref:`Viewport <class_Viewport>`, whatever is inside will not be
-visible in the scene editor. To display the contents, you have to draw the :ref:`Viewport's <class_Viewport>` :ref:`ViewportTexture <class_ViewportTexture>` somewhere.
+When rendering to a :ref:`SubViewport <class_SubViewport>`, whatever is inside will not be
+visible in the scene editor. To display the contents, you have to draw the SubViewport's :ref:`ViewportTexture <class_ViewportTexture>` somewhere.
 This can be requested via code using (for example):
 
 ::
 
     # This gives us the ViewportTexture.
-    var rtt = viewport.get_texture()
-    sprite.texture = rtt
+    var tex = viewport.get_texture()
+    sprite.texture = tex
 
 Or it can be assigned in the editor by selecting "New ViewportTexture"
 
-.. image:: img/texturemenu.png
+.. image:: img/texturemenu.webp
 
 and then selecting the :ref:`Viewport <class_Viewport>` you want to use.
 
-.. image:: img/texturepath.png
+.. image:: img/texturepath.webp
 
-Every frame, the :ref:`Viewport <class_Viewport>`'s texture is cleared away with the default clear color (or a transparent
-color if :ref:`Transparent Bg<class_Viewport_property_transparent_bg>` is set to ``true``). This can be changed by setting ``Clear Mode`` to Never or Next Frame.
+Every frame, the :ref:`Viewport's <class_Viewport>` texture is cleared away with the default clear color (or a transparent
+color if :ref:`Transparent BG<class_Viewport_property_transparent_bg>` is set to ``true``). This can be changed by setting :ref:`Clear Mode<class_SubViewport_property_render_target_clear_mode>` to ``Never`` or ``Next Frame``.
 As the name implies, Never means the texture will never be cleared, while next frame will
 clear the texture on the next frame and then set itself to Never.
 
-By default, re-rendering of the :ref:`Viewport <class_Viewport>` happens when the
-:ref:`Viewport <class_Viewport>`'s :ref:`ViewportTexture <class_ViewportTexture>` has been drawn in a frame. If visible, it will be
-rendered; otherwise, it will not. This behavior can be changed to manual
-rendering (once), or always render, no matter if visible or not. This flexibility
-allows users to render an image once and then use the texture without
-incurring the cost of rendering every frame.
+By default, re-rendering of the :ref:`SubViewport <class_SubViewport>` happens when
+its :ref:`ViewportTexture <class_ViewportTexture>` has been drawn in a frame. If visible, it will be
+rendered, otherwise, it will not. This behavior can be changed by setting :ref:`Update Mode<class_SubViewport_property_render_target_update_mode>` to ``Never``, ``Once``, ``Always``, or ``When Parent Visible``.
+Never and Always will never or always re-render respectively. Once will re-render the next frame and change to Never afterwards. This can be used to manually update the Viewport.
+This flexibility allows users to render an image once and then use the texture without incurring the cost of rendering every frame.
 
+.. note::
 
-Make sure to check the Viewport demos! Viewport folder in the demos
-archive available to download, or
-https://github.com/godotengine/godot-demo-projects/tree/master/viewport
+    Make sure to check the Viewport demos. They are available in the 
+    viewport folder of the demos archive, or at
+    https://github.com/godotengine/godot-demo-projects/tree/master/viewport.