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

Utilisation de ImmediateMesh

The ImmediateMesh is a convenient tool to create dynamic geometry using an OpenGL 1.x-style API. Which makes it both approachable to use and efficient for meshes which need to be updated every frame.

Générer une géométrie complexe (plusieurs milliers de sommets) avec cet outil est inefficace, même si cela n'est fait qu'une seule fois. Il est plutôt conçu pour générer une géométrie simple qui change à chaque trame.

First, you need to create a MeshInstance3D and add an ImmediateMesh to it in the Inspector.

Next, add a script to the MeshInstance3D. The code for the ImmediateMesh should go in the _process() function if you want it to update each frame, or in the _ready() function if you want to create the mesh once and not update it. If you only generate a surface once, the ImmediateMesh is just as efficient as any other kind of mesh as the generated mesh is cached and reused.

Pour commencer à générer la géométrie, vous devez appeller surface_begin(). surface_begin() prend une PrimitiveType comme argument. PrimitiveType indique au GPU comment organiser la primitive en fonction des sommets, qu'il s'agisse de triangles, de droites, de points, etc. Une liste complète peut être trouvée sur la page de référence de la classe Mesh.

Une fois que vous avez appelé surface_begin(), vous êtes prêt à commencer à ajouter des sommets. Vous ajoutez les sommets un par un. Tout d'abord, vous ajoutez des attributs spécifiques aux sommets tels que les normales ou les UV en utilisant surface_set_****() (par exemple surface_set_normal()). Ensuite, vous appelez surface_add_vertex() pour ajouter un sommet avec ces attributs. Par exemple :

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

Seuls les attributs ajoutés avant l'appel de surface_add_vertex() seront inclus dans ce sommet. Si vous ajoutez un attribut deux fois avant d'appeler surface_add_vertex(), seul le second appel sera utilisé.

Enfin, une fois que vous avez ajouté tous vos sommets, appelez surface_end() pour signaler que vous avez fini de générer le maillage. Vous pouvez appeler surface_begin() et surface_end() plusieurs fois pour générer plusieurs surfaces pour le maillage.

Le code d'exemple ci-dessous dessine un triangle dans la fonction _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()

The ImmediateMesh can also be used across frames. Each time you call surface_begin() and surface_end(), you are adding a new surface to the ImmediateMesh. If you want to recreate the mesh from scratch each frame, call clear_surfaces() before calling 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()

The above code will dynamically create and draw a single surface each frame.