Up to date

This page is up to date for Godot 4.2. If you still find outdated information, please open an issue.

ReflectionProbe

继承: VisualInstance3D < Node3D < Node < Object

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

描述

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

ReflectionProbe 用于以低性能成本(当 update_modeUPDATE_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)

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_colorambient_color_energy


属性说明

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

  • void set_ambient_color ( Color value )

  • Color get_ambient_color ( )

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


float ambient_color_energy = 1.0

  • void set_ambient_color_energy ( float value )

  • float get_ambient_color_energy ( )

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


AmbientMode ambient_mode = 1

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


bool box_projection = false

  • void set_enable_box_projection ( bool value )

  • bool is_box_projection_enabled ( )

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

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


int cull_mask = 1048575

  • void set_cull_mask ( int value )

  • int get_cull_mask ( )

设置剔除掩码,该掩码确定该探针绘制的对象。每个 VisualInstance3D,若它有一个层被包含在该剔除掩码中,则它将由该探针渲染。为了提高性能,最好只包含可能在反射中占用大量空间的大型对象。


bool enable_shadows = false

  • void set_enable_shadows ( bool value )

  • bool are_shadows_enabled ( )

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


float intensity = 1.0

  • void set_intensity ( float value )

  • float get_intensity ( )

定义反射强度。


bool interior = false

  • void set_as_interior ( bool value )

  • bool is_set_as_interior ( )

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


float max_distance = 0.0

  • void set_max_distance ( float value )

  • float get_max_distance ( )

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

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


float mesh_lod_threshold = 1.0

  • void set_mesh_lod_threshold ( float value )

  • float get_mesh_lod_threshold ( )

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

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


Vector3 origin_offset = Vector3(0, 0, 0)

  • void set_origin_offset ( Vector3 value )

  • Vector3 get_origin_offset ( )

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


Vector3 size = Vector3(20, 20, 20)

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

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


UpdateMode update_mode = 0

设置该 ReflectionProbe 的更新频率。可以是 UPDATE_ONCEUPDATE_ALWAYS