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

MultiMesh

继承： Resource < RefCounted < Object

使用 GPU 实例提供单一网格的高性能多次绘制。

描述

MultiMesh 提供了低级别的网格实例化功能。绘制数以千计的 MeshInstance3D 节点可能会很慢，因为每个对象都要提交给 GPU 然后单独绘制。

MultiMesh 要快得多，因为它可以通过一次绘制调用来绘制成千上万的实例，从而减少 API 的开销。

缺点是，如果实例之间的距离太远，性能可能会降低，因为每一个实例总是会被渲染（对于整个对象，它们在空间上被索引为一个）。

由于实例可能具有任何行为，因此用于可见性的 AABB 必须由用户提供。

注意：MultiMesh 是单个对象，因此适用相同的对每个对象的最大灯光限制。这意味着，一旦最大灯光被一个或多个实例消耗了，其余的 MultiMesh 实例将不会接收任何光照。

注意：在 MultiMesh 中使用的 Blend Shape 将被忽略。

教程

属性

PackedFloat32Array

buffer

PackedFloat32Array()

PackedColorArray

color_array

AABB

custom_aabb

AABB(0, 0, 0, 0, 0, 0)

PackedColorArray

custom_data_array

int

instance_count

0

Mesh

mesh

PackedVector2Array

transform_2d_array

PackedVector3Array

transform_array

TransformFormat

transform_format

0

bool

use_colors

false

bool

use_custom_data

false

int

visible_instance_count

-1

方法

AABB

get_aabb() const

Color

get_instance_color(instance: int) const

Color

get_instance_custom_data(instance: int) const

Transform3D

get_instance_transform(instance: int) const

Transform2D

get_instance_transform_2d(instance: int) const

void

set_instance_color(instance: int, color: Color)

void

set_instance_custom_data(instance: int, custom_data: Color)

void

set_instance_transform(instance: int, transform: Transform3D)

void

set_instance_transform_2d(instance: int, transform: Transform2D)

枚举

enum TransformFormat: 🔗

TransformFormat TRANSFORM_2D = 0

使用 2D 变换时使用此选项。

TransformFormat TRANSFORM_3D = 1

使用 3D 变换时使用此选项。

属性说明

PackedFloat32Array buffer = PackedFloat32Array() 🔗

该属性目前没有描述，请帮我们贡献一个吧！

PackedColorArray color_array 🔗

已弃用： Accessing this property is very slow. Use set_instance_color and get_instance_color instead.

包含该网格所有实例使用的每种 Color 的数组。

Note: The returned array is copied and any changes to it will not update the original property value. See PackedColorArray for more details.

AABB custom_aabb = AABB(0, 0, 0, 0, 0, 0) 🔗

  • void set_custom_aabb(value: AABB)

  • AABB get_custom_aabb()

为该 MultiMesh 资源自定义 AABB。手动设置该项可以防止高昂的运行时 AABB 重新计算成本。

PackedColorArray custom_data_array 🔗

已弃用： Accessing this property is very slow. Use set_instance_custom_data and get_instance_custom_data instead.

包含该网格的所有实例所使用的每个自定义数据值的数组，作为 PackedColorArray。

Note: The returned array is copied and any changes to it will not update the original property value. See PackedColorArray for more details.

int instance_count = 0 🔗

  • void set_instance_count(value: int)

  • int get_instance_count()

将被绘制的实例数。这会清除缓冲区，并（重新）调整其大小。之后设置的数据格式或标志将无效。

默认情况下，所有实例都会被绘制，但可以使用 visible_instance_count 来限制它。

Mesh mesh 🔗

  • void set_mesh(value: Mesh)

  • Mesh get_mesh()

要被实例化的 Mesh 资源。

各个实例的外观可以通过 set_instance_color 和 set_instance_custom_data 来修改。

PackedVector2Array transform_2d_array 🔗

已弃用： Accessing this property is very slow. Use set_instance_transform_2d and get_instance_transform_2d instead.

包含该网格的所有实例所使用的每个 Transform2D 值的数组，作为 PackedVector2Array。每个变换被分为 3 个 Vector2 值，分别对应于变换的 x、y 和 origin。

Note: The returned array is copied and any changes to it will not update the original property value. See PackedVector2Array for more details.

PackedVector3Array transform_array 🔗

已弃用： Accessing this property is very slow. Use set_instance_transform and get_instance_transform instead.

包含该网格的所有实例所使用的每个 Transform3D 值的数组，作为 PackedVector3Array。每个变换被分为 4 个 Vector3 值，分别对应于变换的 x、y、z 和 origin。

Note: The returned array is copied and any changes to it will not update the original property value. See PackedVector3Array for more details.

TransformFormat transform_format = 0 🔗

用于变换网格的变换格式，可以是 2D 或 3D。

bool use_colors = false 🔗

  • void set_use_colors(value: bool)

  • bool is_using_colors()

如果为 true，则该 MultiMesh 将使用颜色数据（参见 set_instance_color）。只有在 instance_count 为 0 或更少时才能被设置。这意味着需要在设置实例计数之前调用该方法，或者暂时将实例计数重置为 0。

bool use_custom_data = false 🔗

  • void set_use_custom_data(value: bool)

  • bool is_using_custom_data()

如果为 true，则该 MultiMesh 将使用自定义数据（参见 set_instance_custom_data）。只有在 instance_count 为 0 或更少时才能被设置。这意味着需要在设置实例计数之前调用该方法，或者暂时将实例计数重置为 0。

int visible_instance_count = -1 🔗

  • void set_visible_instance_count(value: int)

  • int get_visible_instance_count()

限制绘制的实例数量，-1 会绘制所有的实例。改变这一点并不改变缓冲区的大小。

方法说明

AABB get_aabb() const 🔗

返回局部空间中的可见性轴对齐包围框。

Color get_instance_color(instance: int) const 🔗

获取特定实例的颜色倍数。

Color get_instance_custom_data(instance: int) const 🔗

返回已经为特定实例设置的自定义数据。

Transform3D get_instance_transform(instance: int) const 🔗

返回指定实例的 Transform3D。

Transform2D get_instance_transform_2d(instance: int) const 🔗

返回指定实例的 Transform2D。

void set_instance_color(instance: int, color: Color) 🔗

设置一个特定实例的颜色，通过乘以该网格的现有顶点颜色来设置。这允许每个实例使用不同的颜色。

要使颜色生效，请确保该 MultiMesh 上的 use_colors 为 true，并且材质上的 BaseMaterial3D.vertex_color_use_as_albedo 为 true。如果打算设置绝对颜色而不是着色，请确保材质的反照率颜色被设置为纯白色 (Color(1, 1, 1))。

void set_instance_custom_data(instance: int, custom_data: Color) 🔗

为特定的实例设置自定义数据。custom_data 是一个 Color 类型，仅为了包含 4 个浮点数。

对于要使用的自定义数据，请确保 use_custom_data 为 true。

必须使用 INSTANCE_CUSTOM 在自定义着色器中，手动访问该自定义实例数据。

void set_instance_transform(instance: int, transform: Transform3D) 🔗

为指定实例设置 Transform3D。

void set_instance_transform_2d(instance: int, transform: Transform2D) 🔗

为指定实例设置 Transform2D。