Up to date

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

Decal

继承： VisualInstance3D < Node3D < Node < Object

将纹理投影到 MeshInstance3D 上的节点。

描述

Decal 用于将纹理投射到场景中的 Mesh 上。使用贴花可在不影响底层 Mesh 的情况下向场景中添加细节。它们通常用于为建筑物添加风化效果，为地面添加污垢或泥土，或为道具添加多样性。贴花可以随时移动，使其适用于斑点阴影或激光瞄准点之类的东西。

贴花由一个 AABB 和一组用于指定 Color、法线、ORM（环境光遮蔽、粗糙度、金属度）和自发光的 Texture2D 组成。贴花在其 AABB 内投影，因此改变贴花的朝向会影响它们投影的方向。默认情况下，贴花向下投影（即从正 Y 到负 Y）。

与贴花关联的 Texture2D 会自动存储在用于绘制贴花的纹理图集中，因此可以一次绘制所有贴花。Godot 使用集群贴花，这意味着贴花是存储在集群数据中的，会在绘制网格时绘制，而不是作为后期处理效果在此之后进行绘制。

注意：贴花不会影响底层材质的透明度，无论其透明度模式如何（Alpha 混合、Alpha 剪切、Alpha 哈希、不透明预通）。这意味着材质的半透明或透明区域将保持半透明或透明，即使在其上应用不透明贴花也是如此。

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

注意：当使用 Mobile 渲染方式时，贴花只会正确影响其可视 AABB 与该贴花的 AABB 相交的网格。如果使用着色器变形网格，使其超出网格自身的 AABB，则必须增大网格上的 GeometryInstance3D.extra_cull_margin。否则，贴花可能在该网格上不可见。

属性

float

albedo_mix

1.0

int

cull_mask

1048575

float

distance_fade_begin

40.0

bool

distance_fade_enabled

false

float

distance_fade_length

10.0

float

emission_energy

1.0

float

lower_fade

0.3

Color

modulate

Color(1, 1, 1, 1)

float

normal_fade

0.0

Vector3

size

Vector3(2, 2, 2)

Texture2D

texture_albedo

Texture2D

texture_emission

Texture2D

texture_normal

Texture2D

texture_orm

float

upper_fade

0.3

方法

Texture2D

get_texture ( DecalTexture type ) const

void

set_texture ( DecalTexture type, Texture2D texture )

枚举

enum DecalTexture:

DecalTexture TEXTURE_ALBEDO = 0

与 texture_albedo 对应的 Texture2D。

DecalTexture TEXTURE_NORMAL = 1

与 texture_normal 对应的 Texture2D。

DecalTexture TEXTURE_ORM = 2

与 texture_orm 对应的 Texture2D。

DecalTexture TEXTURE_EMISSION = 3

与 texture_emission 对应的 Texture2D。

DecalTexture TEXTURE_MAX = 4

DecalTexture 枚举的最大大小。

属性说明

float albedo_mix = 1.0

  • void set_albedo_mix ( float value )

  • float get_albedo_mix ( )

将该贴花的反照率 Color 与底层网格的反照率 Color 混合。可以将其设置为 0.0，从而创建仅影响法线或 ORM 的贴花。这种情况下仍然需要反照率纹理，因为它的 Alpha 通道将决定覆盖法线和 ORM 的位置。另见 modulate。

int cull_mask = 1048575

  • void set_cull_mask ( int value )

  • int get_cull_mask ( )

指定此贴花将投射到哪些 VisualInstance3D.layers 上。默认情况下，贴花会影响所有图层。可用于指定哪些类型的对象接收该贴花、哪些不接收。这一点特别有用，你可以确保动态对象不会意外收到用于其下方地形的贴花。

float distance_fade_begin = 40.0

  • void set_distance_fade_begin ( float value )

  • float get_distance_fade_begin ( )

与相机的距离，贴花从该处开始淡出（以 3D 单位表示）。

bool distance_fade_enabled = false

  • void set_enable_distance_fade ( bool value )

  • bool is_distance_fade_enabled ( )

如果为 true，贴花会在远离活动的 Camera3D 时平滑地淡出，从 distance_fade_begin 开始。该贴花将在 distance_fade_begin + distance_fade_length 处消失，之后就会被剔除，根本不会发送到着色器。请使用这个选项来减少场景中激活贴花的数量，从而提高性能。

float distance_fade_length = 10.0

  • void set_distance_fade_length ( float value )

  • float get_distance_fade_length ( )

该贴花淡出的距离（以 3D 单位表示）。这段距离内，该贴花会慢慢变得透明，直至完全不可见。值越大，淡出过渡更平滑，更适合于相机快速移动的情况。

float emission_energy = 1.0

  • void set_emission_energy ( float value )

  • float get_emission_energy ( )

自发光纹理的能量倍数。会使贴花以更高或更低的强度发光，与反照率颜色无关。另见 modulate。

float lower_fade = 0.3

  • void set_lower_fade ( float value )

  • float get_lower_fade ( )

设置该贴花的淡出曲线，表示随着表面远离 AABB 中心而逐渐淡出。仅正值有效（负值将被限制到 0.0）。另见 upper_fade。

Color modulate = Color(1, 1, 1, 1)

  • void set_modulate ( Color value )

  • Color get_modulate ( )

更改贴花的 Color，将其反照率和自发光颜色乘以这个值。仅在与反照率颜色相乘时才会考虑 Alpha 分量，与自发光颜色相乘时则不会。如果要独立更改自发光和反照率强度，请参阅 emission_energy 和 albedo_mix。

float normal_fade = 0.0

  • void set_normal_fade ( float value )

  • float get_normal_fade ( )

如果贴花的 AABB 与目标表面之间的角度变得过大，则淡出贴花。值为 0 时在投影贴花会忽略角度，值为 1 时会将贴花限制到几乎垂直的表面。

注意：将 normal_fade 设置为大于 0.0 的值会有较小的性能成本，因为增加了法线角度计算。

Vector3 size = Vector3(2, 2, 2)

设置贴花使用的 AABB 的大小。所有大小都必须设置为大于零的值（如果不是这种情况，它们将被钳制为 0.001）。该 AABB 从 -size/2 到 size/2。

注意：为了提高“硬表面”贴花的剔除效率，将它们的 upper_fade 和 lower_fade 设置为 0.0，并将 size 的 Y 分量设置的越低越好。这将减少贴花的 AABB 大小而不影响它们的外观。

Texture2D texture_albedo

带有贴花的基础 Color 的 Texture2D。必须设置这个属性或者 texture_emission 贴花才可见。要将贴花的边缘与底层对象平滑地混合，请像遮罩一样使用 Alpha 通道。

注意：BaseMaterial3D 的过滤模式可以对每个材质进行调整，而 Decal 纹理的过滤模式是通过 ProjectSettings.rendering/textures/decals/filter 全局设置的。

Texture2D texture_emission

带有贴花的自发光 Color 的 Texture2D。必须设置这个属性或者 texture_albedo 贴花才可见。要将贴花的边缘与底层对象平滑地混合，请像遮罩一样使用 Alpha 通道。

注意：BaseMaterial3D 的过滤模式可以对每个材质进行调整，而 Decal 纹理的过滤模式是通过 ProjectSettings.rendering/textures/decals/filter 全局设置的。

Texture2D texture_normal

带有贴花的逐像素法线贴图的 Texture2D。可用于为贴花添加额外的细节。

注意：BaseMaterial3D 的过滤模式可以对每个材质进行调整，而 Decal 纹理的过滤模式是通过 ProjectSettings.rendering/textures/decals/filter 全局设置的。

注意：单独设置此纹理时贴花不可见，因为还必须设置 texture_albedo。要创建仅包含法线的贴花，请将反照率纹理加载到 texture_albedo，并将 albedo_mix 设置为 0.0。反照率纹理的 Alpha 通道将用于确定应在何处覆盖底层表面的法线贴图（及其强度）。

Texture2D texture_orm

存有贴花的环境光遮蔽、粗糙度、金属性的 Texture2D。可用于为贴花添加额外的细节。

注意：BaseMaterial3D 的过滤模式可以对每个材质进行调整，而 Decal 纹理的过滤模式是通过 ProjectSettings.rendering/textures/decals/filter 全局设置的。

注意：单独设置此纹理时贴花不可见，因为还必须设置 texture_albedo。要创建仅包含 ORM 的贴花，请将反照率纹理加载到 texture_albedo，并将 albedo_mix 设置为 0.0。反照率纹理的 Alpha 通道将用于确定应在何处覆盖底层表面的 ORM 贴图（及其强度）。

float upper_fade = 0.3

  • void set_upper_fade ( float value )

  • float get_upper_fade ( )

设置该贴花的淡出曲线，表示随着表面远离 AABB 中心而逐渐淡出。仅正值有效（负值将被限制到 0.0）。另见 upper_fade。

方法说明

Texture2D get_texture ( DecalTexture type ) const

返回与指定的 DecalTexture 关联的 Texture2D。这是一个便捷方法，在大多数情况下，你应该直接访问纹理。

例如，相比于 albedo_tex = $Decal.get_texture(Decal.TEXTURE_ALBEDO)，请使用 albedo_tex = $Decal.texture_albedo。

有一种情况下这种写法比直接访问纹理更好，那就是当想要将贴花的纹理复制到另一个贴花是。例如：

for i in Decal.TEXTURE_MAX:
    $NewDecal.set_texture(i, $OldDecal.get_texture(i))

void set_texture ( DecalTexture type, Texture2D texture )

设置与指定的 DecalTexture 关联的 Texture2D。这是一个便捷方法，在大多数情况下，你应该直接访问纹理。

例如，相比于 albedo_tex = $Decal.set_texture(Decal.TEXTURE_ALBEDO, albedo_tex)，请使用 $Decal.texture_albedo = albedo_tex。

有一种情况下这种写法比直接访问纹理更好，那就是当想要将贴花的纹理复制到另一个贴花是。例如：

for i in Decal.TEXTURE_MAX:
    $NewDecal.set_texture(i, $OldDecal.get_texture(i))