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

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 ( int instance ) const

Color

get_instance_custom_data ( int instance ) const

Transform3D

get_instance_transform ( int instance ) const

Transform2D

get_instance_transform_2d ( int instance ) const

void

set_instance_color ( int instance, Color color )

void

set_instance_custom_data ( int instance, Color custom_data )

void

set_instance_transform ( int instance, Transform3D transform )

void

set_instance_transform_2d ( int instance, Transform2D transform )

枚举

enum TransformFormat:

TransformFormat TRANSFORM_2D = 0

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

TransformFormat TRANSFORM_3D = 1

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

属性说明

PackedFloat32Array buffer = PackedFloat32Array()

目前没有这个属性的描述。请帮我们贡献一个！

PackedColorArray color_array

见 set_instance_color。

PackedColorArray custom_data_array

见 set_instance_custom_data。

int instance_count = 0

  • void set_instance_count ( int value )

  • int get_instance_count ( )

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

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

Mesh mesh

  • void set_mesh ( Mesh value )

  • Mesh get_mesh ( )

要被实例化的 Mesh 资源。

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

PackedVector2Array transform_2d_array

见 set_instance_transform_2d。

PackedVector3Array transform_array

见 set_instance_transform。

TransformFormat transform_format = 0

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

bool use_colors = false

  • void set_use_colors ( bool value )

  • bool is_using_colors ( )

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

bool use_custom_data = false

  • void set_use_custom_data ( bool value )

  • 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 ( int value )

  • int get_visible_instance_count ( )

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

方法说明

AABB get_aabb ( ) const

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

Color get_instance_color ( int instance ) const

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

Color get_instance_custom_data ( int instance ) const

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

Transform3D get_instance_transform ( int instance ) const

返回指定实例的 Transform3D。

Transform2D get_instance_transform_2d ( int instance ) const

返回指定实例的 Transform2D。

void set_instance_color ( int instance, Color color )

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

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

void set_instance_custom_data ( int instance, Color custom_data )

为特定的实例设置自定义数据。虽然使用了 Color，但它只是一个容纳 4 个浮点数的容器。

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

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

void set_instance_transform ( int instance, Transform3D transform )

为指定实例设置 Transform3D。

void set_instance_transform_2d ( int instance, Transform2D transform )

为指定实例设置 Transform2D。