ReflectionProbe

继承： VisualInstance3D < Node3D < Node < Object

捕捉某个位置周围的环境，用于快速创建准确的反射。

描述

将其周围环境捕捉为立方体贴图，并存储不同版本，其模糊级别递增以模拟不同的材质粗糙度。

ReflectionProbe 用于以低性能成本（当 update_mode 为 UPDATE_ONCE 时），创建高质量反射。ReflectionProbe 可以与场景的其余部分，平滑地混合在一起。ReflectionProbe 还可以与 VoxelGI、SDFGI（Environment.sdfgi_enabled）和屏幕空间反射（Environment.ssr_enabled）结合使用，以在特定区域获得更准确的反射。ReflectionProbe 渲染其 cull_mask 内的所有对象，因此更新它们可能会非常昂贵。最好仅用重要的静态对象更新一次，然后保持原样。

注意：与 VoxelGI 和 SDFGI 不同，ReflectionProbe 仅从一个 WorldEnvironment 节点获取环境。如果你在一个 Camera3D 节点中指定了一个 Environment 资源，它将被该 ReflectionProbe 忽略。这可能会导致 ReflectionProbe 内的照明不正确。

注意：反射探针仅支持 Forward+ 和 Mobile 渲染方法，不支持 Compatibility。使用移动渲染方法时，每个网格资源上最多只能显示 8 个反射探针。尝试在单个网格资源上显示 8 个以上的反射探针，将导致反射探针随着相机移动而闪烁。

注意：当使用移动渲染方法时，反射探针只会正确地影响可见 AABB 与反射探针的 AABB 相交的网格。如果使用着色器以使网格超出其 AABB 的方式变形该网格，则必须在网格上增加 GeometryInstance3D.extra_cull_margin。否则，反射探针可能在网格上不可见。

教程

属性

Color

ambient_color

Color(0, 0, 0, 1)

float

ambient_color_energy

1.0

AmbientMode

ambient_mode

1

bool

box_projection

false

int

cull_mask

1048575

bool

enable_shadows

false

float

intensity

1.0

bool

interior

false

float

max_distance

0.0

float

mesh_lod_threshold

1.0

Vector3

origin_offset

Vector3(0, 0, 0)

int

reflection_mask

1048575

Vector3

size

Vector3(20, 20, 20)

UpdateMode

update_mode

0

枚举

enum UpdateMode: 🔗

UpdateMode UPDATE_ONCE = 0

在下一帧更新一次探针（建议大多数对象使用）。对应的辐照度贴图会在后续六帧中陆续生成。更新所花费的时间比 UPDATE_ALWAYS 多，但消耗的性能比它少、产生的反射质量也更高。ReflectionProbe 的变换发生变化时也会进行更新，但不会在周围几何体变化时更新。你可以通过将该 ReflectionProbe 在任意方向上进行小幅度移动来强制更新 ReflectionProbe。

UpdateMode UPDATE_ALWAYS = 1

每一帧都更新该探针。可以为快速移动的对象（如汽车）提供更好的结果。然而，带来的性能消耗也是显著的。因此，建议同一个场景中最多只使用一个 UPDATE_ALWAYS 的 ReflectionProbe。其他用途请使用 UPDATE_ONCE。

enum AmbientMode: 🔗

AmbientMode AMBIENT_DISABLED = 0

不在 ReflectionProbe 的大小为 size 的框内部应用环境光照。

AmbientMode AMBIENT_ENVIRONMENT = 1

在 ReflectionProbe 的大小为 size 的框内部应用自动来源的环境光照。

AmbientMode AMBIENT_COLOR = 2

在 ReflectionProbe 的大小为 size 的框内部应用自定义环境光照。见 ambient_color 和 ambient_color_energy。

属性说明

Color ambient_color = Color(0, 0, 0, 1) 🔗

  • void set_ambient_color(value: Color)

  • Color get_ambient_color()

ReflectionProbe 的大小为 size 的框中使用的自定义环境光颜色。仅在 ambient_mode 为 AMBIENT_COLOR 时有效。

float ambient_color_energy = 1.0 🔗

  • void set_ambient_color_energy(value: float)

  • float get_ambient_color_energy()

ReflectionProbe 的大小为 size 的框中使用的自定义环境光颜色能量。仅在 ambient_mode 为 AMBIENT_COLOR 时有效。

AmbientMode ambient_mode = 1 🔗

ReflectionProbe 的大小为 size 的框中使用的环境光颜色。环境光颜色会和其他 ReflectionProbe 和场景（ReflectionProbe 的大小为 size 的框之外）的其他部分进行平滑混合。

bool box_projection = false 🔗

  • void set_enable_box_projection(value: bool)

  • bool is_box_projection_enabled()

为 true 时将启用箱体投影。通过根据相机的位置偏移反射中心，这使得在矩形房间中的反射看起来更正确。

注意：为了更好地适应未与网格对齐的区域，你可以旋转 ReflectionProbe 节点。

int cull_mask = 1048575 🔗

  • void set_cull_mask(value: int)

  • int get_cull_mask()

设置剔除掩码，用来确定该探针绘制的对象。如果 VisualInstance3D 有一个层被包含在剔除掩码中，就会被该探针渲染。为了提高性能，最好只包含可能在反射中占用大量空间的大型对象。

也可以用来防止物体对自己进行反射（例如位于车辆中心的 ReflectionProbe）。

bool enable_shadows = false 🔗

  • void set_enable_shadows(value: bool)

  • bool are_shadows_enabled()

如果为 true，则在反射探测中计算阴影。这使得反射探针渲染更慢;如果想禁用它,可以使用 UPDATE_ALWAYS update_mode。

float intensity = 1.0 🔗

  • void set_intensity(value: float)

  • float get_intensity()

定义反射强度。

bool interior = false 🔗

  • void set_as_interior(value: bool)

  • bool is_set_as_interior()

如果为 true，则反射将忽略天空的贡献。

float max_distance = 0.0 🔗

  • void set_max_distance(value: float)

  • float get_max_distance()

对象在被剔除之前可以距该 ReflectionProbe 的最大距离。减少它可以提高性能，尤其是在使用 UPDATE_ALWAYS 作为 update_mode 时。

注意：最大反射距离始终至少等于探针的范围。这意味着减少 max_distance 并不总是会从反射中剔除对象，尤其是在反射探针由 size 定义的框已经很大的情况下。

float mesh_lod_threshold = 1.0 🔗

  • void set_mesh_lod_threshold(value: float)

  • float get_mesh_lod_threshold()

用于在 ReflectionProbe 内渲染网格的自动 LOD 偏置（这类似于 Viewport.mesh_lod_threshold）。较高的值将使用生成了 LOD 变化的不太详细的网格版本。如果设置为 0.0，则自动 LOD 将被禁用。增加 mesh_lod_threshold 以牺牲几何细节为代价提高性能，尤其是在使用 UPDATE_ALWAYS 的 update_mode 时。

注意：mesh_lod_threshold 不影响 GeometryInstance3D 可见性范围（也称为“手动”LOD 或分层 LOD）。

Vector3 origin_offset = Vector3(0, 0, 0) 🔗

设置当该 ReflectionProbe 处于 box_projection 模式时要使用的原点偏移量。这可以被设置为一个非零值，以确保反射适合矩形房间，同时减少“妨碍”反射的对象数量。

int reflection_mask = 1048575 🔗

  • void set_reflection_mask(value: int)

  • int get_reflection_mask()

设置反射掩码，该掩码确定哪些对象应用了来自该探针的反射。每个包含在该反射掩码中的层的 VisualInstance3D 都将由该探针应用反射。另请参阅 cull_mask，它可用于排除对象出现在反射中，同时仍使它们受到 ReflectionProbe 的影响。

Vector3 size = Vector3(20, 20, 20) 🔗

反射探针的大小。大小越大，探针覆盖的空间就越大，这将降低感知的分辨率。最好将大小保持在需要的大小。

注意：为了更好地适应未与网格对齐的区域，可以旋转 ReflectionProbe 节点。

UpdateMode update_mode = 0 🔗

设置该 ReflectionProbe 的更新频率。可以是 UPDATE_ONCE 或 UPDATE_ALWAYS。