MultiMesh

继承： Resource < RefCounted < Object

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

描述

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

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

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

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

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

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

教程

• 使用 MultiMeshInstance

• 使用 MultiMesh 进行优化

• 使用 MultiMeshInstance 动画化数千条鱼

属性

方法

枚举

enum TransformFormat: 🔗

TransformFormat TRANSFORM_2D = 0

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

TransformFormat TRANSFORM_3D = 1

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

属性说明

PackedFloat32Array buffer = PackedFloat32Array() 🔗

• void set_buffer(value: PackedFloat32Array)

• PackedFloat32Array get_buffer()

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

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 🔗

• void set_transform_format(value: TransformFormat)

• TransformFormat get_transform_format()

用于变换网格的变换格式，可以是 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。