Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

Utilizzo delle Viewport

Introduzione

Pensa a una Viewport come a uno schermo su cui viene proiettato il gioco. Per vedere il gioco, abbiamo bisogno di una superficie su cui disegnarlo. Questa superficie è la viewport radice (Root Viewport).

Le SubViewport sono un tipo di Viewport che si può aggiungere alla scena così da avere più superfici su cui disegnare. Quando disegniamo su una SubViewport, la chiamiamo destinazione di rendering. Possiamo accedere al contenuto di una destinazione di rendering accedendo alla sua texture corrispondente. Utilizzando una SubViewport come destinazione di rendering, possiamo renderizzare più scene contemporaneamente oppure renderizzare su una ViewportTexture applicata a un oggetto nella scena, ad esempio una skybox dinamica.

Le SubViewport hanno una varietà di casi d'uso, tra cui:

• Renderizzare oggetti 3D dentro un gioco 2D

• Renderizzare elementi 2D in un gioco 3D

• Renderizzare texture dinamiche

• Generare texture procedurali in fase di esecuzione

• Renderizzare più telecamere nella stessa scena

Ciò tutti questi casi d'uso hanno in comune è la possibilità di disegnare oggetti su una texture come se fosse un altro schermo e di scegliere poi cosa fare con la texture risultante.

Un altro tipo di Viewport in Godot sono le finestre (Window). Permettono di proiettare il loro contenuto su una finestra. Sebbene la viewport radice sia una finestra (Window), sono meno flessibili. Se si desidera utilizzare la texture di una Viewport, si lavorerà il più delle volte con le SubViewport.

Input

Le Viewport sono anche responsabili di distribuire gli eventi di input correttamente adattati ai rispettivi nodi figlio. Come predefinito, le SubViewport non ricevono automaticamente input, a meno che non lo ricevano dal loro nodo SubViewportContainer padre diretto. In questo caso, è possibile disabilitare gli 'input con la proprietà Disable Input.

Per ulteriori informazioni su come Godot gestisce gli input, leggere il Tutorial sugli eventi di input.

Ascoltatore

Godot supporta l'audio 3D (sia nei nodi 2D sia 3D). Maggiori informazioni sono disponibili nel Tutorial sui flussi audio. Affinché questo tipo di suono sia udibile, è necessario abilitare Viewport come ascoltatore (per 2D o 3D). Se si utilizza un SubViewport per visualizzare un World3D o un World2D, non dimenticare di abilitarlo!

Telecamere (2D e 3D)

Quando si utilizza una Camera3D o Camera2D, sarà sempre visualizzata sulla Viewport padre più vicina (verso la radice). Ad esempio, nella seguente gerarchia:

CameraA sarà visualizzata nella Viewport radice e disegnerà MeshA. CameraB sarà catturata dalla SubViewport insieme a MeshB. Anche se MeshB è nella gerarchia della scena, non sarà comunque disegnata nella Viewport radice. Analogamente, MeshA non sarà visibile dalla SubViewport perché le SubViewport catturano solo i nodi sottostanti nella gerarchia.

Può esserci una sola telecamera attiva per ciascuna Viewport, quindi se ce n'è più di una, assicurati che quella desiderata abbia la proprietà current impostata, oppure impostala come telecamera attuale chiamando:

GDScriptC#

camera.make_current()

Normalmente, le telecamere renderizzano tutti gli oggetti nel loro mondo. In 3D, le telecamere possono usare la loro proprietà cull_mask combinata con la proprietà layer di VisualInstance3D's per limitare quali oggetti sono renderizzati.

Scala e stiramento

Le SubViewport hanno una proprietà size, che rappresenta la dimensione delle SubViewport in pixel. Per le SubViewport figlie di SubViewportContainer, questi valori sono sovrascritti, ma per tutte le altre, questo imposta la loro risoluzione.

È anche possibile cambiare la scala del contenuto 2D e rendere la risoluzione della SubViewport diversa da quella specificata nelle dimensioni, chiamando:

GDScriptC#

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.

Per informazioni sul cambio di scala e lo stiramento con la Viewport radice, visita il Tutorial sulle risoluzioni multiple

Worlds

Per il 3D, un Viewport conterrà un World3D. Questo è essenzialmente l'universo che collega la fisica e il rendering. I nodi basati su Node3D si registreranno attraverso il World3D della Viewport più vicina. Come predefinito, i Viewport appena creati non contengono un World3D, ma utilizzano lo stesso della Viewport madre. Il Viewport radice contiene sempre un World3D, che è quello su cui sono renderizzati gli oggetti come predefinito.

È possibile impostare un World3D in una Viewport tramite la proprietà World 3D, che separerà tutti i nodi figlio di questa Viewport e impedirà loro di interagire con il World3D della Viewport padre. Questo è particolarmente utile in scenari in cui, ad esempio, si desidera mostrare un personaggio separato in 3D sovrapposto al gioco (come in StarCraft).

Come ausilio per le situazioni in cui si desidera creare Viewport che visualizzano singoli oggetti e non si desidera creare un World3D, Viewport offre l'opzione di utilizzare il proprio World3D. Questo è utile quando si desidera creare istanze di personaggi o oggetti 3D in World2D.

Per il 2D, ogni Viewport contiene sempre il proprio World2D. Questo è sufficiente nella maggior parte dei casi, ma se si desidera condividerli, è possibile farlo impostando world_2d sulla Viewport tramite codice.

Per un esempio di come funziona, vedere rispettivamente i progetti demo 3D in 2D e 2D in 3D.

Cattura (Capture)

È possibile richiedere una cattura del contenuto di una Viewport. Per la Viewport radice, si tratta di una vera e propria cattura dello schermo. Ciò si ottiene con il seguente codice:

GDScriptC#

# Retrieve the captured Image using get_image().
var img = get_viewport().get_texture().get_image()
# Convert Image to ImageTexture.
var tex = ImageTexture.create_from_image(img)
# Set sprite texture.
sprite.texture = tex

Ma usandolo in _ready() o dal primo frame dell'inizializzazione di Viewport's, si otterà una texture vuota perché non c'è nulla da ottenere come texture. Si può gestire con (ad esempio):

GDScriptC#

# Wait until the frame has finished before getting the texture.
await RenderingServer.frame_post_draw
# You can get the image after this.

Contenitore di Viewport

Se la SubViewport è figlia di un SubViewportContainer, diventerà attiva e visualizzerà tutto ciò che contiene. La disposizione appare così:

La SubViewport coprirà completamente l'area del suo SubViewportContainer padre se Stretch è impostato su true nel SubViewportContainer.

Nota

Le dimensione del SubViewportContainer non può essere inferiore alle dimensioni della SubViewport.

Renderer

Poiché una Viewport è un punto di accesso a un'altra superficie di rendering, espone alcune proprietà di rendering che possono essere diverse dalle impostazioni del progetto. È possibile scegliere di utilizzare un livello diverso di MSAA per ogni Viewport. Il comportamento predefinito è Disabilitato.

Se sai che la Viewport sarà utilizzata solo per il 2D, è possibile disabilitare il 3D. Godot limiterà quindi il modo in cui la Viewport è disegnata. Disabilitare il 3D è leggermente più veloce e utilizza meno memoria rispetto a mantenere il 3D abilitato. È una buona idea disabilitare il 3D se la tua viewport non renderizza nulla in 3D.

Nota

Se hai bisogno renderizzare ombre 3D nella viewport, assicurati di impostare la proprietà positional_shadow_atlas_size della viewport su un valore maggiore di 0. Altrimenti, le ombre non verranno renderizzate. Come predefinito, l'impostazione equivalente del progetto è impostata su 4096 sulle piattaforme desktop e su 2048 sulle piattaforme mobili.

Godot fornisce anche un modo per personalizzare il modo in cui tutto è disegnato all'interno di una Viewport tramite Debug Draw. Debug Draw consente di specificare una modalità che determina come la Viewport visualizzerà gli elementi disegnati al suo interno. Debug Draw è Disabled come predefinito. Altre opzioni sono Unshaded, Overdraw e Wireframe. Per un elenco completo, consultare la documentazione su Viewport.

• Debug Draw = Disabled (predefinito): la scena è disegnata normalmente.

• Debug Draw = Unshaded: unshaded disegna la scena senza utilizzare le informazioni di illuminazione, così che tutti gli oggetti appaiano colorati in modo piatto nel loro colore albedo.

• Debug Draw = Overdraw: Overdraw disegna le mesh in modo semitrasparente con una fusione additiva, così è possibile vedere come si sovrappongono le mesh.

• Debug Draw = Wireframe: Wireframe disegna la scena utilizzando solo i bordi dei triangoli nelle mesh.

Nota

Le modalità di disegno di debug non sono attualmente supportate quando si utilizza il metodo di rendering Compatibilità. Appariranno come normali modalità di disegno.

Obiettivo di rendering

Quando si renderizza su una SubViewport, il contenuto al suo interno non sarà visibile nell'editor di scene. Per visualizzarne il contenuto, è necessario disegnare la ViewportTexture della SubViewport da qualche parte. Ciò si può richiedere tramite codice, ad esempio:

GDScriptC#

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

Oppure si può assegnare nell'editor selezionando "Nuova ViewportTexture"

e poi selezionando la Viewport che vuoi usare.

A ogni frame, la texture della Viewport viene cancellata con un colore predefinito di cancellazione (o con un colore trasparente se Transparent BG è impostato su true). Ciò può essere cambiato impostando Clear Mode su Never o Next Frame. Come suggerisce il nome, Never significa che la texture non verrà mai cancellata, mentre next frame cancellerà la texture nel frame successivo e poi si imposterà su Never.

Per impostazione predefinita, il re-rendering della SubViewport avviene quando la sua ViewportTexture è stata disegnata in un frame. Se visibile, sarà renderizzata, altrimenti no. Questo comportamento si può cambiare impostando Update Mode su Never, Once, Always o When Parent Visible. Never e Always non renderizzeranno mai o sempre, rispettivamente. Once renderizerà il frame successivo e si cambierà in Never subito dopo. Questa opzione si può utilizzare per aggiornare manualmente la Viewport. Questa flessibilità consente agli utenti di renderizzare un'immagine una sola volta e poi utilizzare la texture senza dover sostenere l'impatto di rendering a ogni frame.

Nota

Assicurati di dare un'occhiata alle demo di Viewport. Sono disponibili nella cartella viewport dell'archivio demo o all'indirizzo https://github.com/godotengine/godot-demo-projects/tree/master/viewport.