MultiMesh

继承： Resource < RefCounted < Object

使用GPU实例化多次提供网格的高性能绘图。

描述

MultiMesh提供低级网格实例化。绘制数千个MeshRender节点可能会很慢，因为每个对象都提交到GPU，然后单独绘制。

MultiMesh速度更快，因为它可以通过一次绘制调用绘制数千个实例，从而减少API开销。

作为一个缺点，如果实例彼此相距太远，性能可能会降低，因为每个实例都将始终呈现（对于整个对象，它们在空间上被索引为一个）。

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

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

注意：如果在MultiMesh中使用，混合形状将被忽略。

属性

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

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

始终使用基础lerping进行插值，这在某些情况下会产生翘曲伪影。

PhysicsInterpolationQuality INTERP_QUALITY_HIGH = 1

在可能的情况下尝试使用基础slerping（球面线性插值）进行插值，否则回退到lerping。

属性说明

PackedFloat32Array buffer = PackedFloat32Array() 🔗

注意： 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 🔗

已弃用： 访问该属性非常慢。请改用 set_instance_color() 和 get_instance_color()。

包含此网格的所有实例使用的每个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 🔗

已弃用： 访问该属性非常慢。请改用 set_instance_custom_data() 和 get_instance_custom_data()。

包含此网格的所有实例使用的每个自定义数据值的数组，作为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 🔗

选择是否使用有利于速度或质量的插值方法。

当使用低物理刻度率（通常低于20）或高对象旋转率时，您可能会从高质量设置中获得更好的结果。

注：质量快不等于质量低，除上述特殊情况外，质量应与高质量相当。

PackedVector2Array transform_2d_array 🔗

已弃用： 访问该属性非常慢。请改用 set_instance_transform_2d() 和 get_instance_transform_2d()。

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

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 🔗

已弃用： 访问该属性非常慢。请改用 set_instance_transform() 和 get_instance_transform()。

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

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 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位存储，但在兼容性渲染方法中打包为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位存储，但在Compatiity渲染方法中被打包为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。