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 di ImmediateMesh

La classe ImmediateMesh è uno strumento comodo per creare geometrie dinamiche utilizzando un'API in stile OpenGL 1.x. Questo la rende accessibile ed efficiente per le mesh che si devono aggiornare a ogni frame.

Generare geometrie complesse (diverse migliaia di vertici) con questo strumento è inefficiente, anche se fatto una sola volta. È invece progettato per generare geometrie semplici che cambiano a ogni frame.

Innanzitutto, bisogna creare un MeshInstance3D e aggiungergli un ImmediateMesh nell'Ispettore.

Successivamente, aggiungi uno script a MeshInstance3D. Il codice per l'ImmediateMesh si dovrebbe inserire nella funzione _process() se vuoi aggiornarla a ogni frame, oppure nella funzione _ready() se vuoi creare la mesh una sola volta e non aggiornarla. Se generi una superficie una sola volta, ImmediateMesh è efficiente quanto qualsiasi altro tipo di mesh, poiché la mesh generata è memorizzata nella cache e riutilizzata.

Per iniziare a generare la geometria è necessario chiamare surface_begin(). surface_begin() accetta un PrimitiveType come argomento. PrimitiveType indica alla GPU come disporre la primitiva in base ai vertici forniti, specificando se sono triangoli, linee, punti, ecc. Un elenco completo è disponibile nella pagina di Mesh nel riferimento classi.

Una volta chiamata la funzione surface_begin(), sei pronto per cominciare ad aggiungere i vertici. I vertici si aggiungono uno alla volta. Per prima cosa aggiungi gli attributi specifici del vertice, come le normali o le coordinate UV, attraverso la funzione surface_set_****() (ad esempio, surface_set_normal()). Poi chiami la funzione surface_add_vertex() per aggiungere un vertice con tali attributi. Ad esempio:

GDScript

# Add a vertex with normal and uv.
surface_set_normal(Vector3(0, 1, 0))
surface_set_uv(Vector2(1, 1))
surface_add_vertex(Vector3(0, 0, 1))

Solo gli attributi aggiunti prima di chiamare surface_add_vertex() saranno inclusi in quel vertice. Se aggiungi un attributo due volte prima di chiamare surface_add_vertex(), verrà utilizzata solo la seconda chiamata.

Infine, dopo aver aggiunto tutti i vertici, chiama surface_end() per segnalare che hai finito di generare la superficie. Puoi chiamare surface_begin() e surface_end() più volte per generare più superfici per la mesh.

Il codice di esempio riportato di seguito disegna un singolo triangolo nella funzione _ready().

GDScript

extends MeshInstance3D

func _ready():
    # Begin draw.
    mesh.surface_begin(Mesh.PRIMITIVE_TRIANGLES)

    # Prepare attributes for add_vertex.
    mesh.surface_set_normal(Vector3(0, 0, 1))
    mesh.surface_set_uv(Vector2(0, 0))
    # Call last for each vertex, adds the above attributes.
    mesh.surface_add_vertex(Vector3(-1, -1, 0))

    mesh.surface_set_normal(Vector3(0, 0, 1))
    mesh.surface_set_uv(Vector2(0, 1))
    mesh.surface_add_vertex(Vector3(-1, 1, 0))

    mesh.surface_set_normal(Vector3(0, 0, 1))
    mesh.surface_set_uv(Vector2(1, 1))
    mesh.surface_add_vertex(Vector3(1, 1, 0))

    # End drawing.
    mesh.surface_end()

L'ImmediateMesh si può utilizzare anche attraverso più frame. Ogni volta che chiami surface_begin() e surface_end(), stai aggiungendo una nuova superficie a ImmediateMesh. Se vuoi ricreare la mesh da zero a ogni frame, chiama clear_surfaces() prima di chiamare surface_begin().

GDScript

extends MeshInstance3D

func _process(delta):

    # Clean up before drawing.
    mesh.clear_surfaces()

    # Begin draw.
    mesh.surface_begin(Mesh.PRIMITIVE_TRIANGLES)

    # Draw mesh.

    # End drawing.
    mesh.surface_end()

Il codice sopra riportato creerà e disegnerà dinamicamente una singola superficie per ogni frame.