DecalActor

继承： VisualRender < Item3D < Item < Object

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

描述

DecalActor用于将纹理投射到场景中的Mesh上。使用贴花在不影响底层Mesh的情况下为场景添加细节。它们通常用于为建筑物添加风化，为地面添加泥土或泥浆，或为道具添加多样性。贴花可以随时移动，使其适用于斑点阴影或激光视点等事物。

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

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

注意：贴花不会影响底层材质的透明度，无论其透明度模式如何（alpha混合、alpha剪刀、alpha散列、不透明预通）。这意味着即使在材质上应用了不透明贴花，材质的半透明或透明区域仍将保持半透明或透明。

注意：仅在Forward+和Mobile渲染方法中支持贴花，不支持兼容性。使用Mobile渲染方法时，每个网格资源只能显示8个贴花。尝试在单个网格资源上显示超过8个贴花将导致贴花随着摄像机移动而闪烁进出。

注意：当使用移动渲染方法时，贴花只会正确影响可见性AABB与贴花的AABB相交的网格。如果使用着色器变形网格，使其超出AABB，则必须在网格上增加GeometryRender.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(type: DecalTexture) const

void

set_texture(type: DecalTexture, texture: Texture2D)

枚举

enum DecalTexture: 🔗

DecalTexture TEXTURE_ALBEDO = 0

Texture2D对应于texture_albedo。

DecalTexture TEXTURE_NORMAL = 1

Texture2D对应于texture_normal。

DecalTexture TEXTURE_ORM = 2

Texture2D对应于texture_orm。

DecalTexture TEXTURE_EMISSION = 3

Texture2D对应于texture_emission。

DecalTexture TEXTURE_MAX = 4

DecalTexture枚举的最大大小。

属性说明

float albedo_mix = 1.0 🔗

  • void set_albedo_mix(value: float)

  • float get_albedo_mix()

将贴花的反照率Color与底层网格的反照率Color混合。这可以设置为0.0以创建仅影响正常或ORM的贴花。在这种情况下，仍然需要反照率纹理，因为其Alpha通道将决定正常和ORM将被覆盖的位置。另请参阅modulate。

int cull_mask = 1048575 🔗

  • void set_cull_mask(value: int)

  • int get_cull_mask()

指定此贴花将投射到哪个VisualRender.layers。默认情况下，贴花会影响所有图层。使用此选项，您可以指定哪些类型的对象接收贴花，哪些不接收。这特别有用，因此您可以确保动态对象不会意外接收针对其下地形的贴花。

float distance_fade_begin = 40.0 🔗

  • void set_distance_fade_begin(value: float)

  • float get_distance_fade_begin()

贴花开始消失时与摄像机的距离（以3D为单位）。

bool distance_fade_enabled = false 🔗

  • void set_enable_distance_fade(value: bool)

  • bool is_distance_fade_enabled()

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

float distance_fade_length = 10.0 🔗

  • void set_distance_fade_length(value: float)

  • float get_distance_fade_length()

贴花褪色的距离（以3D为单位）。贴花在此距离上慢慢变得更加透明，最终完全不可见。更高的值会导致更平滑的淡出过渡，这更适合摄像机快速移动时。

float emission_energy = 1.0 🔗

  • void set_emission_energy(value: float)

  • float get_emission_energy()

发射纹理的能量倍增器。这将使贴花以更高或更低的强度发光，与反照率颜色无关。另见modulate。

float lower_fade = 0.3 🔗

  • void set_lower_fade(value: float)

  • float get_lower_fade()

设置当表面离AABB中心越来越远时贴花会褪色的曲线。只有正值有效（负值将被限制为0.0）。另请参见upper_fade。

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

  • void set_modulate(value: Color)

  • Color get_modulate()

通过将反照率和发射颜色与此值相乘来更改贴花的Color。Alpha分量仅在相乘反照率颜色时被考虑，而不是发射颜色。另请参阅emission_energy和albedo_mix以独立地更改发射和反照率强度。

float normal_fade = 0.0 🔗

  • void set_normal_fade(value: float)

  • 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。必须设置此选项或texture_emission才能使贴花可见。使用像蒙版一样的alpha通道将贴花的边缘与底层对象平滑混合。

注意：与BaseMaterial3D不同，DecalActor纹理的过滤模式可以在每个材质的基础上进行调整，DecalActor纹理的过滤模式是使用ProjectSettings.rendering/textures/decals/filter全局设置的。

Texture2D texture_emission 🔗

带有贴花的发射Color的Texture2D。必须设置此选项或texture_albedo才能使贴花可见。使用像蒙版一样的alpha通道将贴花的边缘与底层对象平滑混合。

注意：与BaseMaterial3D不同，DecalActor纹理的过滤模式可以在每个材质的基础上进行调整，DecalActor纹理的过滤模式是使用ProjectSettings.rendering/textures/decals/filter全局设置的。

Texture2D texture_normal 🔗

带有贴花的每像素法线贴图。使用它为贴花添加额外的细节。

注意：与BaseMaterial3D不同，DecalActor纹理的过滤模式可以在每个材质的基础上进行调整，DecalActor纹理的过滤模式是使用ProjectSettings.rendering/textures/decals/filter全局设置的。

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

Texture2D texture_orm 🔗

Texture2D为贴花存储环境遮挡、粗糙度和金属。使用它为贴花添加额外的细节。

注意：与BaseMaterial3D不同，DecalActor纹理的过滤模式可以在每个材质的基础上进行调整，DecalActor纹理的过滤模式是使用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(value: float)

  • float get_upper_fade()

设置当表面离AABB中心越来越远时贴花会褪色的曲线。只有正值有效（负值将被限制为0.0）。另请参见lower_fade。

方法说明

Texture2D get_texture(type: DecalTexture) const 🔗

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

例如，使用albedo_tex=$DecalActor.get_texture（DecalActor.TEXTURE_ALBEDO），而不是albedo_tex=$DecalActor.texture_albedo。

比直接访问纹理更好的一种情况是，当您想将一个Decal的纹理复制到另一个纹理时。例如：

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

void set_texture(type: DecalTexture, texture: Texture2D) 🔗

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

例如，使用$DecalActor.set_texture（DecalActor.TEXTURE_ALBEDO，albedo_tex），而不是$DecalActor.texture_albedo=albedo_tex。

比直接访问纹理更好的一种情况是当您想将一个Decal的纹理复制到另一个纹理时。例如：

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