MultiMesh

继承： Resource < RefCounted < Object

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

描述

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

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

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

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

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

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

教程

• 使用 MultiMeshInstance

• 使用 MultiMesh 进行优化

• 使用 MultiMeshInstance 动画化数千条鱼

属性

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
PhysicsInterpolationQuality	physics_interpolation_quality	0
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	reset_instance_physics_interpolation(instance: int)
void	set_buffer_interpolated(buffer_curr: PackedFloat32Array, buffer_prev: PackedFloat32Array)
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 变换时使用此选项。

---

enum PhysicsInterpolationQuality: 🔗

PhysicsInterpolationQuality INTERP_QUALITY_FAST = 0

始终使用 Basis 线性插值，部分情况下可能产生扭曲问题。

PhysicsInterpolationQuality INTERP_QUALITY_HIGH = 1

尽可能使用 Basis 球面线性插值，否则回退至线性插值。

---

属性说明

PackedFloat32Array buffer = PackedFloat32Array() 🔗

• void set_buffer(value: PackedFloat32Array)

• PackedFloat32Array get_buffer()

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

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

---

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() 来修改。

---

PhysicsInterpolationQuality physics_interpolation_quality = 0 🔗

• void set_physics_interpolation_quality(value: PhysicsInterpolationQuality)

• PhysicsInterpolationQuality get_physics_interpolation_quality()

选择使用优先考虑速度还是优先考虑质量的插值方式。

如果使用的物理周期率较低（通常低于 20）或对象旋转率较高，则设为高质量的效果会更好。

注意：速度优先并不意味着质量较低。除了上述特殊情况之外，其质量应与选择高质量时类似。

---

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 reset_instance_physics_interpolation(instance: int) 🔗

使用物理插值时，该函数能够让你在当前物理周期中阻止对实例进行插值。

这样你就可以让实例瞬移，通常在初始放置子弹等实例时使用，防止出现图形问题。

---

void set_buffer_interpolated(buffer_curr: PackedFloat32Array, buffer_prev: PackedFloat32Array) 🔗

设置 buffer 属性的替代做法，可以用于物理插值。该方法接受两个数组，可以一次性设置当前周期和上一周期的数据。渲染器每一帧都会自动插值。

适用于实例顺序每个物理周期中都经常会改变的场合，例如粒子系统。

如果实例的顺序是连贯的，插值时还是可以用更简单的设置 buffer 来代替。

---

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

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

注意：各分量在 Forward+ 和 Mobile 渲染方法中都是使用 32 位存储的，而在 Compatibility 渲染方法中则为 16 位。

要使颜色生效，请确保该 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 个浮点数。

注意：各个数字在 Forward+ 和 Mobile 渲染方法中都是使用 32 位存储的，而在 Compatibility 渲染方法中则为 16 位。

对于要使用的自定义数据，请确保 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。