Viewports

Introducción

Piensa en las Viewports como una pantalla en la que se proyecta el juego. Para ver el juego necesitamos tener una superficie sobre la que dibujarlo, esta superficie es el Root :ref:`Viewport <class_Viewport>`(nodo raíz).

../../_images/viewportnode.png

Los Viewports también se puede añadir a la escena para que haya múltiples superficies sobre las que dibujar. Cuando estamos dibujando a un Viewport que no es el Root lo llamamos un render target(objetivo de renderizado). Podemos acceder al contenido de un render target accediendo a su correspondiente Texture. Usando un Viewport como objetivo de render podemos renderizar múltiples escenas simultáneamente o podemos renderizar a una Texture que se aplica a un objeto de la escena, por ejemplo un skybox dinámico.

Los Viewports tienen una variedad de casos de uso, incluyendo:

  • Renderización de objetos 3D dentro de un juego 2D
  • Renderizar elementos 2D en un juego 3D
  • Renderizado de texturas dinámicas
  • Generación de texturas de procedimiento en tiempo de ejecución
  • Renderizado de varias cámaras en la misma escena

Lo que todos estos casos de uso tienen en común es que se da la capacidad de dibujar objetos a una textura como si fuera otra pantalla y luego puedes elegir qué hacer con la textura resultante.

Entrada

Los Viewports son también responsables de entregar eventos de entrada correctamente ajustados y escalados a todos sus nodos hijos. Típicamente la entrada es recibida por el Viewport más cercano en el árbol, pero puedes establecer Viewports para que no reciba entradas al marcar “Disable Input” en activado, esto permitirá que el siguiente Viewport más cercano en el árbol capture la entrada.

../../_images/input.png

Para más información sobre cómo maneja Godot las entradas, por favor lee el Tutorial de Eventos de Entrada.

Listener

Godot supports 3D sound (in both 2D and 3D nodes); more on this can be found in the Audio Streams Tutorial. For this type of sound to be audible, the Viewport needs to be enabled as a listener (for 2D or 3D). If you are using a custom Viewport to display your World, don’t forget to enable this!

Cameras (2D & 3D)

When using a Camera / Camera2D, cameras will always display on the closest parent Viewport (going towards the root). For example, in the following hierarchy:

../../_images/cameras.png

CameraA will display on the Root Viewport and it will draw MeshA. CameraB will be captured by the Viewport Node 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 Viewport node because Viewport nodes only capture nodes below them in the hierarchy.

There can only be one active camera per Viewport, so if there is more than one, make sure that the desired one has the «current» property set, or make it the current camera by calling:

camera.make_current()

By default, cameras will render all objects in their world. In 3D, cameras can use their cull_mask property combined with the VisualInstance’s layer property to restrict which objects are rendered.

Scale & stretching

El Viewport tiene una propiedad «size», la que representa el tamaño del Viewport en pixeles. Para Viewport que son hijos de un ref:ViewportContainer <class_viewportcontainer>, esos valores son sobreescritos pero esto define su resolución.

It is also possible to scale the 2D content and make the Viewport 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.

The root Viewport uses this for the stretch options in the project settings. For more information on scaling and stretching visit the Multiple Resolutions Tutorial

Worlds

For 3D, a Viewport will contain a World. This is basically the universe that links physics and rendering together. Spatial-base nodes will register using the World of the closest Viewport. By default, newly created Viewports do not contain a World but use the same as their parent Viewport (the root Viewport always contains a World, which is the one objects are rendered to by default). A World can be set in a Viewport using the «world» property, and that will separate all children nodes of that Viewport from interacting with the parent Viewport’s World. 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).

Como ayudante para situaciones en las que se quiera crear Viewports que muestren objetos individuales y no se quiera crear un World, Viewport tiene la opción de usar su propio World. Esto es muy útil cuando se desea crear personajes u objetos 3D en un 2D World.

For 2D, each Viewport always contains its own World2D. This suffices in most cases, but in case sharing them may be desired, it is possible to do so by setting the Viewport’s World2D manually.

For an example of how this works, see the demo projects 3D in 2D and 2D in 3D respectively.

Captura

It is possible to query a capture of the 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_data().
var img = get_viewport().get_texture().get_data()
# 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.new()
tex.create_from_image(img)
# Set Sprite Texture.
$sprite.texture = tex

But if you use this in _ready() or from the first frame of the Viewport’s initialization, you will get an empty texture because there is nothing to get as texture. You can deal with it using (for example):

# Wait until the frame has finished before getting the texture
yield(VisualServer, "frame_post_draw")
# You can get the image after this.

Viewport Container

If the Viewport is a child of a ViewportContainer, it will become active and display anything it has inside. The layout looks like this:

../../_images/container.png

El Viewport abarcará completamente el área de su padre ViewportContainer si stretch está ajustado a true en ViewportContainer. Nota: El tamaño del ViewportContainer no puede ser menor que el tamaño del Viewport.

Renderización

Due to the fact that the 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 Viewport; the default behavior is DISABLED. You can also set the 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.

If you know how the Viewport is going to be used, you can set its Usage to either 3D or 2D. Godot will then restrict how the 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 Viewport’s Usage property to 2D if your viewport doesn’t render anything in 3D.

Nota

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.

Godot also provides a way of customizing how everything is drawn inside Viewports using “Debug Draw”. Debug Draw allows you to specify one of four options for how the Viewport will display things drawn inside it. Debug Draw is disabled by default.

../../_images/default_scene.png

A scene drawn with Debug Draw disabled

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.

../../_images/unshaded.png

The same scene with Debug Draw set to Unshaded

Overdraw draws the meshes semi-transparent with an additive blend so you can see how the meshes overlap.

../../_images/overdraw.png

The same scene with Debug Draw set to Overdraw

Lastly, Wireframe draws the scene using only the edges of triangles in the meshes.

Nota

The effects of the Wireframe mode are only visible in the editor, not while the project is running.

Render target

When rendering to a Viewport, whatever is inside will not be visible in the scene editor. To display the contents, you have to draw the Viewport’s ViewportTexture somewhere. This can be requested via code using (for example):

# This gives us the ViewportTexture.
var rtt = viewport.get_texture()
sprite.texture = rtt

Or it can be assigned in the editor by selecting «New ViewportTexture»

../../_images/texturemenu.png

and then selecting the Viewport you want to use.

../../_images/texturepath.png

Every frame, the Viewport’s texture is cleared away with the default clear color (or a transparent color if Transparent BG is set to true). This can be changed by setting 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 Viewport happens when the Viewport’s 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.

¡Asegúrate de revisar las demos de Viewport! Carpeta Viewport en el archivo de demos disponible para descargar, o https://github.com/godotengine/godot-demo-projects/tree/master/viewport