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...

Riproduzione di video

Godot supporta la riproduzione di video con il nodo VideoStreamPlayer.

Formati di riproduzione supportati

L'unico formato supportato nel core è Ogg Theora (da non confondere con l'audio Ogg Vorbis), con tracce audio Ogg Vorbis facoltative. Le estensioni sono in grado di implementare supporto di formati aggiuntivi.

H.264 e H.265 non sono supportati nel core di Godot, poiché sono entrambi protetti da brevetti software. AV1 è esente da royalty, ma la sua decodifica è lenta sulla CPU e il supporto per la decodifica su hardware non è ancora disponibile su tutte le GPU in uso.

WebM era supportato nel core di Godot 3.x, ma il supporto è stato rimosso nella versione 4.0 perché era troppo pieno di bug e difficile da mantenere.

Nota

Potresti trovare video con estensione .ogg o .ogx, che sono estensioni generiche per i dati dentro un contenitore Ogg.

Rinominare queste estensioni di file in .ogv potrebbe permettere ai video di essere importati in Godot. Tuttavia, non tutti i file con estensione .ogg o .ogx sono video: alcuni di essi potrebbero contenere solo audio.

Configurazione di VideoStreamPlayer

  1. Creare un nodo VideoStreamPlayer attraverso la finestra di dialogo Crea un nuovo nodo.

  2. Selezionare il nodo VideoStreamPlayer nel pannello dell'albero di scene, andare nell'Ispettore e caricare un file .ogv nella proprietà Stream.

  3. Se si desidera che il video venga riprodotto non appena la scena viene caricata, selezionare Riproduzione automatica nell'ispettore. Altrimenti, lascia Riproduzione automatica disabilitata e chiama play() sul nodo VideoStreamPlayer in uno script per avviare la riproduzione quando desiderato.

Gestire il ridimensionamento e i diverse rapporti di aspetto

By default, the VideoStreamPlayer will automatically be resized to match the video's resolution. You can make it follow usual Control sizing by enabling Expand on the VideoStreamPlayer node.

Per regolare come il nodo VideoStreamPlayer è ridimensionato in base alle dimensioni della finestra, è possibile regolare le ancore attraverso il menu Layout in alto la viewport dell'editor 2D. Tuttavia, questa configurazione potrebbe non essere potente abbastanza per gestire tutti i casi d'uso, come la riproduzione di video a schermo intero senza distorcere l'immagine (ma con spazio vuoto ai bordi). Per un maggiore controllo, è possibile utilizzare un nodo AspectRatioContainer, progettato per gestire questo tipo di caso d'uso:

Aggiungi un nodo AspectRatioContainer. Assicurati che non sia figlio di nessun altro nodo contenitore. Seleziona il nodo AspectRatioContainer, quindi imposta il suo Layout in alto l'editor 2D su Full Rect. Imposta il Ratio nel nodo AspectRatioContainer in modo che corrisponda al rapporto d'aspetto del video. Puoi utilizzare formule matematiche nell'ispettore per aiutarti. Ricorda di impostare uno degli operandi come float. Altrimenti, il risultato della divisione sarà sempre un numero intero.

La proprietà Ratio di AspectRatioContainer in fase di modifica nell'ispettore dell'editor

Questo valore sarà (approssimativamente) 1.777778

Dopo aver configurato l'AspectRatioContainer, riassegna il nodo VideoStreamPlayer al nodo figlio dell'AspectRatioContainer. Assicurati che l'opzione Expand sia abilitata sul VideoStreamPlayer. Il video dovrebbe ora ridimensionarsi automaticamente per adattarsi all'intero schermo, evitando distorsioni.

Vedi anche

Consulta Molteplici risoluzioni per ulteriori suggerimenti su come supportare più rapporti di aspetto nel tuo progetto.

Visualizzare un video su una superficie 3D

Attraverso un nodo VideoStreamPlayer come figlio di un nodo SubViewport, è possibile visualizzare qualsiasi nodo 2D su una superficie 3D. Ad esempio, questo può servire per visualizzare billboard animati quando un'animazione fotogramma per fotogramma richiederebbe troppa memoria.

Ciò si può fare seguendo i seguenti passaggi:

  1. Crea un nodo SubViewport. Imposta le sue dimensioni in modo che corrispondano alle dimensioni del video in pixel.

  2. Crea un nodo VideoStreamPlayer come figlio del nodo SubViewport e specifica al suo interno il percorso del video. Assicurati che Expand sia disabilitato e abilita Autoplay se necessario.

  3. Crea un nodo MeshInstance3D con una risorsa PlaneMesh o QuadMesh nella sua proprietà Mesh. Ridimensiona la mesh in modo che corrisponda al rapporto d'aspetto del video (altrimenti, apparirà distorta).

  4. Crea una nuova risorsa StandardMaterial3D nella proprietà Material Override nella sezione GeometryInstance3D.

  5. Abilita Local To Scene nella sezione Resource di StandardMaterial3D (in basso). Questo è necessario affinché sia possibile utilizzare una ViewportTexture nella sua proprietà Albedo Texture.

  6. Nello StandardMaterial3D, imposta la proprietà Albedo > Texture su Nuovo ViewportTexture. Modifica la nuova risorsa cliccando su di essa, poi specifica il percorso del nodo SubViewport nella proprietà Viewport Path.

  7. Abilita Albedo Texture Force sRGB nello StandardMaterial3D per evitare che i colori risultino sbiaditi.

  8. If the billboard is supposed to emit its own light, set Shading Mode to Unshaded to improve rendering performance.

Consultare Utilizzo delle Viewport e la demo GUI in 3D per ulteriori informazioni sulla configurazione.

Far ripetere un video

Per ripetere un video, è possibile abilitare la proprietà Loop. Questa proprietà riavvia il video senza interruzioni al termine della riproduzione.

Note that setting the project setting Video Delay Compensation to a non-zero value might cause your loop to not be seamless, because the synchronization of audio and video takes place at the start of each loop causing occasional missed frames. Set Video Delay Compensation in your project settings to 0 to avoid frame drop issues.

Limitazioni della riproduzione

There are some limitations with the current implementation of video playback in Godot:

  • La trasmissione di video da un URL non è supportata.

  • È supportata solo l'uscita audio mono e stereo. I video con 4, 5.1 e 7.1 canali audio sono supportati, ma sono convertiti in stereo.

Video con chroma key

Il chroma key, comunemente noto come effetto "green screen" o "blue screen", permette di rimuovere un colore specifico da un'immagine o un video e sostituirlo con un altro sfondo. Questo effetto è ampiamente utilizzato nella produzione video per comporre diversi elementi senza intoppi.

../../_images/chroma_key_video.webp

Realizzeremo l'effetto chroma key scrivendo uno shader personalizzato in GDScript e utilizzando un nodo VideoStreamPlayer per visualizzare il contenuto video.

Configurazione della scena

Assicurati che la scena contenga un nodo VideoStreamPlayer per riprodurre il video e un nodo Control per contenere gli elementi dell'interfaccia utente per controllare l'effetto chroma key.

../../_images/chroma_key_scene.webp

Scrivere lo shader personalizzato

Per implementare l'effetto chroma key, segui questi passaggi:

  1. Seleziona il nodo VideoStreamPlayer nella scena e vai alle sue proprietà. In CanvasItem > Material, crea un nuovo shader chiamato "ChromaKeyShader.gdshader".

  2. Nel file "ChromaKeyShader.gdshader", scrivi il codice dello shader personalizzato come mostrato di seguito:

shader_type canvas_item;

// Uniform variables for chroma key effect
uniform vec3 chroma_key_color : source_color = vec3(0.0, 1.0, 0.0);
uniform float pickup_range : hint_range(0.0, 1.0) = 0.1;
uniform float fade_amount : hint_range(0.0, 1.0) = 0.1;

void fragment() {
    // Get the color from the texture at the given UV coordinates
    vec4 color = texture(TEXTURE, UV);

    // Calculate the distance between the current color and the chroma key color
    float distance = length(color.rgb - chroma_key_color);

    // If the distance is within the pickup range, discard the pixel
    // the lesser the distance more likely the colors are
    if (distance <= pickup_range) {
        discard;
    }

    // Calculate the fade factor based on the pickup range and fade amount
    float fade_factor = smoothstep(pickup_range, pickup_range + fade_amount, distance);

    // Set the output color with the original RGB values and the calculated fade factor
    COLOR = vec4(color.rgb, fade_factor);
}

Lo shader utilizza il calcolo della distanza per identificare i pixel vicini al colore di chroma key e li scarta, effettivamente rimuovendo il colore selezionato. I pixel leggermente più distanti dal colore di chroma key sono sfumati in base a fade_factor, fondendoli gradualmente con i colori circostanti. Questo processo crea l'effetto chroma key desiderato, dando l'impressione che lo sfondo sia stato sostituito con un'altra immagine o un altro video.

Il codice qui sopra rappresenta una semplice dimostrazione dello shader Chroma Key, e gli utenti lo possono personalizzare in base alle proprie esigenze specifiche.

Control dell'UI

Per consentire agli utenti di manipolare l'effetto chroma key in tempo reale, abbiamo creato degli slider nel nodo Control. Lo script del nodo Control contiene le seguenti funzioni:

 extends Control

 func _on_color_picker_button_color_changed(color):
     # Update the "chroma_key_color" shader parameter of the VideoStreamPlayer's material.
     $VideoStreamPlayer.material.set("shader_parameter/chroma_key_color", color)

 func _on_h_slider_value_changed(value):
     # Update the "pickup_range" shader parameter of the VideoStreamPlayer's material.
     $VideoStreamPlayer.material.set("shader_parameter/pickup_range", value)

 func _on_h_slider_2_value_changed(value):
     # Update the "fade_amount" shader parameter of the VideoStreamPlayer's material.
     $VideoStreamPlayer.material.set("shader_parameter/fade_amount", value)

func _on_video_stream_player_finished():
     # Restart the video playback when it's finished.
     $VideoStreamPlayer.play()

assicurati anche che l'intervallo degli slider sia appropriato, le nostre impostazioni sono:

../../_images/slider_range.webp

Gestione dei segnali

Connetti il segnale appropriato dagli elementi dell'interfaccia utente allo script del nodo Control creato nello script del nodo Control per controllare l'effetto chroma key. Questi gestori di segnale aggiorneranno le variabili uniformi dello shader in risposta all'input dell'utente.

Save and run the scene to see the chroma key effect in action! With the provided UI controls, you can now adjust the chroma key color, pickup range, and fade amount in real-time, achieving the desired chroma key functionality for your video content.