diff --git a/tutorials/rendering/img/cameras.png b/tutorials/rendering/img/cameras.png deleted file mode 100644 index ab1542985e7..00000000000 Binary files a/tutorials/rendering/img/cameras.png and /dev/null differ diff --git a/tutorials/rendering/img/cameras.webp b/tutorials/rendering/img/cameras.webp new file mode 100644 index 00000000000..382b1cc7b79 Binary files /dev/null and b/tutorials/rendering/img/cameras.webp differ diff --git a/tutorials/rendering/img/container.png b/tutorials/rendering/img/container.png deleted file mode 100644 index c79a2932273..00000000000 Binary files a/tutorials/rendering/img/container.png and /dev/null differ diff --git a/tutorials/rendering/img/container.webp b/tutorials/rendering/img/container.webp new file mode 100644 index 00000000000..552605940b4 Binary files /dev/null and b/tutorials/rendering/img/container.webp differ diff --git a/tutorials/rendering/img/default_scene.png b/tutorials/rendering/img/default_scene.png deleted file mode 100644 index e4567b2b8fa..00000000000 Binary files a/tutorials/rendering/img/default_scene.png and /dev/null differ diff --git a/tutorials/rendering/img/default_scene.webp b/tutorials/rendering/img/default_scene.webp new file mode 100644 index 00000000000..6e5d2545c32 Binary files /dev/null and b/tutorials/rendering/img/default_scene.webp differ diff --git a/tutorials/rendering/img/input.png b/tutorials/rendering/img/input.png deleted file mode 100644 index 0956d702f59..00000000000 Binary files a/tutorials/rendering/img/input.png and /dev/null differ diff --git a/tutorials/rendering/img/input.webp b/tutorials/rendering/img/input.webp new file mode 100644 index 00000000000..bb3f5acb268 Binary files /dev/null and b/tutorials/rendering/img/input.webp differ diff --git a/tutorials/rendering/img/overdraw.png b/tutorials/rendering/img/overdraw.png deleted file mode 100644 index 99c374e6696..00000000000 Binary files a/tutorials/rendering/img/overdraw.png and /dev/null differ diff --git a/tutorials/rendering/img/overdraw.webp b/tutorials/rendering/img/overdraw.webp new file mode 100644 index 00000000000..7f834f061d7 Binary files /dev/null and b/tutorials/rendering/img/overdraw.webp differ diff --git a/tutorials/rendering/img/subviewportnode.webp b/tutorials/rendering/img/subviewportnode.webp new file mode 100644 index 00000000000..44584a51c43 Binary files /dev/null and b/tutorials/rendering/img/subviewportnode.webp differ diff --git a/tutorials/rendering/img/texturemenu.png b/tutorials/rendering/img/texturemenu.png deleted file mode 100644 index 9c5611709fe..00000000000 Binary files a/tutorials/rendering/img/texturemenu.png and /dev/null differ diff --git a/tutorials/rendering/img/texturemenu.webp b/tutorials/rendering/img/texturemenu.webp new file mode 100644 index 00000000000..cbf727d5cb9 Binary files /dev/null and b/tutorials/rendering/img/texturemenu.webp differ diff --git a/tutorials/rendering/img/texturepath.png b/tutorials/rendering/img/texturepath.png deleted file mode 100644 index 9f7842a873f..00000000000 Binary files a/tutorials/rendering/img/texturepath.png and /dev/null differ diff --git a/tutorials/rendering/img/texturepath.webp b/tutorials/rendering/img/texturepath.webp new file mode 100644 index 00000000000..0f3f69c08df Binary files /dev/null and b/tutorials/rendering/img/texturepath.webp differ diff --git a/tutorials/rendering/img/unshaded.png b/tutorials/rendering/img/unshaded.png deleted file mode 100644 index 4b569918a42..00000000000 Binary files a/tutorials/rendering/img/unshaded.png and /dev/null differ diff --git a/tutorials/rendering/img/unshaded.webp b/tutorials/rendering/img/unshaded.webp new file mode 100644 index 00000000000..0908a04f3f0 Binary files /dev/null and b/tutorials/rendering/img/unshaded.webp differ diff --git a/tutorials/rendering/img/viewportnode.png b/tutorials/rendering/img/viewportnode.png deleted file mode 100644 index 88bde0592c7..00000000000 Binary files a/tutorials/rendering/img/viewportnode.png and /dev/null differ diff --git a/tutorials/rendering/img/wireframe.webp b/tutorials/rendering/img/wireframe.webp new file mode 100644 index 00000000000..ce2f842354b Binary files /dev/null and b/tutorials/rendering/img/wireframe.webp differ diff --git a/tutorials/rendering/viewports.rst b/tutorials/rendering/viewports.rst index 443a7b9196a..9a108d759f0 100644 --- a/tutorials/rendering/viewports.rst +++ b/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 ` 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 `. - -.. 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 ` can also be added to the scene so that there -are multiple surfaces to draw on. When we are drawing to a :ref:`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 `. -By using a :ref:`Viewport ` as a render target, -we can either render multiple scenes simultaneously or we can render to -a :ref:`texture ` which is applied to an object in the scene, for example a dynamic +:ref:`SubViewports ` 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 `. +By using a SubViewport as render target, we can either render multiple scenes simultaneously or we can render to +a :ref:`ViewportTexture ` which is applied to an object in the scene, for example a dynamic skybox. -:ref:`Viewports ` have a variety of use cases, including: +:ref:`SubViewports ` 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 `. 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 ` most of the time. + Input ----- @@ -45,37 +43,37 @@ automatically receive input, unless they receive it from their direct :ref:`SubViewportContainer ` parent node. In this case, input can be disabled with the :ref:`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`. +For more information on how Godot handles input, please read the :ref:`Input Event Tutorial `. Listener -------- -Godot supports 3D sound (in both 2D and 3D nodes); more on this can be -found in the :ref:`Audio Streams Tutorial`. 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 `. For this type of sound to be audible, the :ref:`Viewport ` needs to be enabled as a listener (for 2D or 3D). -If you are using a custom :ref:`Viewport ` to display your :ref:`World3D ` or +If you are using a :ref:`SubViewport ` to display your :ref:`World3D ` or :ref:`World2D `, don't forget to enable this! Cameras (2D & 3D) ----------------- -When using a :ref:`Camera3D ` / -:ref:`Camera2D `, cameras will always display on the +When using a :ref:`Camera3D ` or +:ref:`Camera2D `, it will always display on the closest parent :ref:`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 ` and it will draw MeshA. CameraB -will be captured by the :ref:`Viewport ` Node along with MeshB. Even though MeshB is in the scene -hierarchy, it will still not be drawn to the Root :ref:`Viewport `. Similarly MeshA will not -be visible from the :ref:`Viewport ` node because :ref:`Viewport ` nodes only +``CameraA`` will display on the Root :ref:`Viewport ` and it will draw ``MeshA``. ``CameraB`` +will be captured by the :ref:`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 `, 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 ` 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 ` have a "size" property, which represents the size of the :ref:`Viewport ` -in pixels. For :ref:`Viewports ` which are children of :ref:`SubViewportContainers `, +:ref:`SubViewports ` have a :ref:`size` property, which represents the size of the SubViewport +in pixels. For SubViewports which are children of :ref:`SubViewportContainers `, 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 ` resolution +It is also possible to scale the 2D content and make the :ref:`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 ` uses this for the stretch options in the project -settings. For more information on scaling and stretching visit the :ref:`Multiple Resolutions Tutorial ` +For information on scaling and stretching with the Root Viewport visit the :ref:`Multiple Resolutions Tutorial ` Worlds ------ For 3D, a :ref:`Viewport ` will contain a :ref:`World3D `. This is basically the universe that links physics and rendering together. -Node3D-based nodes will register using the :ref:`World3D ` of the closest :ref:`Viewport `. -By default, newly created :ref:`Viewports ` do not contain a :ref:`World3D ` but -use the same as their parent :ref:`Viewport ` (the root :ref:`Viewport ` always contains a -:ref:`World3D `, which is the one objects are rendered to by default). A :ref:`World3D ` can -be set in a :ref:`Viewport ` using the "world" property, and that will separate -all children nodes of that :ref:`Viewport ` from interacting with the parent -:ref:`Viewport's ` :ref:`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 ` can +be set in a :ref:`Viewport ` using the :ref:`World 3D` property, that will separate +all children nodes of this :ref:`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 ` that -display single objects and don't want to create a :ref:`World3D `, :ref:`Viewport ` has -the option to use its own :ref:`World3D `. This is useful when you want to -instance 3D characters or objects in a 2D :ref:`World2D `. +display single objects and don't want to create a :ref:`World3D `, Viewport has +the option to use its :ref:`Own World3D `. This is useful when you want to +instance 3D characters or objects in :ref:`World2D `. For 2D, each :ref:`Viewport ` always contains its own :ref:`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 ` :ref:`World2D ` manually. +is possible to do so by setting :ref:`world_2d` on the Viewport through code. For an example of how this works, see the demo projects `3D in 2D `_ and `2D in 3D `_ respectively. Capture ------- -It is possible to query a capture of the :ref:`Viewport ` contents. For the root -:ref:`Viewport `, this is effectively a screen capture. This is done with the +It is possible to query a capture of the :ref:`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 ` 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 ` is a child of a :ref:`SubViewportContainer `, it will become active and display anything it has inside. The layout looks like this: +If the :ref:`SubViewport ` is a child of a :ref:`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 ` will cover the area of its parent :ref:`SubViewportContainer ` completely +if :ref:`Stretch` is set to ``true`` in the SubViewportContainer. -The :ref:`Viewport ` will cover the area of its parent :ref:`SubViewportContainer ` completely -if :ref:`Stretch` is set to ``true`` in :ref:`SubViewportContainer `. -Note: The size of the :ref:`SubViewportContainer ` cannot be smaller than the size of the :ref:`Viewport `. +.. note:: + + The size of the :ref:`SubViewportContainer ` cannot be smaller than the size of the :ref:`SubViewport `. Rendering --------- Due to the fact that the :ref:`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 `; the default behavior is DISABLED. -You can also set the :ref:`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 ` for each Viewport. The default behavior is ``Disabled``. -If you know how the :ref:`Viewport ` is going to be used, you can set its Usage to either 3D or 2D. Godot will then -restrict how the :ref:`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 `'s Usage property to 2D if your viewport doesn't render anything in 3D. +If you know that the :ref:`Viewport ` is only going to be used for 2D, you can :ref:`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` 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 ` using "Debug Draw". -Debug Draw allows you to specify one of four options for how the :ref:`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 ` using :ref:`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`. -.. 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 `, whatever is inside will not be -visible in the scene editor. To display the contents, you have to draw the :ref:`Viewport's ` :ref:`ViewportTexture ` somewhere. +When rendering to a :ref:`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 ` 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 ` you want to use. -.. image:: img/texturepath.png +.. image:: img/texturepath.webp -Every frame, the :ref:`Viewport `'s texture is cleared away with the default clear color (or a transparent -color if :ref:`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 ` texture is cleared away with the default clear color (or a transparent +color if :ref:`Transparent BG` is set to ``true``). This can be changed by setting :ref:`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 ` happens when the -:ref:`Viewport `'s :ref:`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 ` happens when +its :ref:`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` 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.