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...

Decal

Hérite de : VisualInstance3D < Node3D < Node < Object

Nœud qui projette une texture sur un MeshInstance3D.

Description

Decals are used to project a texture onto a Mesh in the scene. Use Decals to add detail to a scene without affecting the underlying Mesh. They are often used to add weathering to building, add dirt or mud to the ground, or add variety to props. Decals can be moved at any time, making them suitable for things like blob shadows or laser sight dots.

They are made of an AABB and a group of Texture2Ds specifying Color, normal, ORM (ambient occlusion, roughness, metallic), and emission. Decals are projected within their AABB so altering the orientation of the Decal affects the direction in which they are projected. By default, Decals are projected down (i.e. from positive Y to negative Y).

The Texture2Ds associated with the Decal are automatically stored in a texture atlas which is used for drawing the decals so all decals can be drawn at once. Godot uses clustered decals, meaning they are stored in cluster data and drawn when the mesh is drawn, they are not drawn as a post-processing effect after.

Note: Decals cannot affect an underlying material's transparency, regardless of its transparency mode (alpha blend, alpha scissor, alpha hash, opaque pre-pass). This means translucent or transparent areas of a material will remain translucent or transparent even if an opaque decal is applied on them.

Note: Decals are only supported in the Forward+ and Mobile rendering methods, not Compatibility. When using the Mobile rendering method, only 8 decals can be displayed on each mesh resource. Attempting to display more than 8 decals on a single mesh resource will result in decals flickering in and out as the camera moves.

Note: When using the Mobile rendering method, decals will only correctly affect meshes whose visibility AABB intersects with the decal's AABB. If using a shader to deform the mesh in a way that makes it go outside its AABB, GeometryInstance3D.extra_cull_margin must be increased on the mesh. Otherwise, the decal may not be visible on the mesh.

Propriétés

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

Méthodes

Texture2D

get_texture(type: DecalTexture) const

void

set_texture(type: DecalTexture, texture: Texture2D)

Énumérations

enum DecalTexture: 🔗

DecalTexture TEXTURE_ALBEDO = 0

Texture2D correspondant à texture_albedo.

DecalTexture TEXTURE_NORMAL = 1

Texture2D correspondant à texture_normal.

DecalTexture TEXTURE_ORM = 2

Texture2D correspondant à texture_orm.

DecalTexture TEXTURE_EMISSION = 3

Texture2D correspondant à texture_emission.

DecalTexture TEXTURE_MAX = 4

Taille maximale de l'énumération DecalTexture.

Descriptions des propriétés

float albedo_mix = 1.0 🔗

  • void set_albedo_mix(value: float)

  • float get_albedo_mix()

Blends the albedo Color of the decal with albedo Color of the underlying mesh. This can be set to 0.0 to create a decal that only affects normal or ORM. In this case, an albedo texture is still required as its alpha channel will determine where the normal and ORM will be overridden. See also modulate.

int cull_mask = 1048575 🔗

  • void set_cull_mask(value: int)

  • int get_cull_mask()

Spécifie sur quels VisualInstance3D.layers ce décalage se projettera. Par défaut, les Decals affectent toutes les couches. Ceci est utilisé pour que vous puissiez spécifier quels types d'objets reçoivent le Decal et lequels ne le reçoivent pas. Ceci est particulièrement utile pour vous assurer que des objets dynamiques ne reçoivent pas accidentellement un Decal destiné au terrain sous eux.

float distance_fade_begin = 40.0 🔗

  • void set_distance_fade_begin(value: float)

  • float get_distance_fade_begin()

La distance à la caméra à laquelle le Decal commence à disparaître (en unités 3D).

bool distance_fade_enabled = false 🔗

  • void set_enable_distance_fade(value: bool)

  • bool is_distance_fade_enabled()

Si true, les décalques vont disparaître en douceur lorsqu'ils sont loin de la Camera3D active à partir de distance_fade_begin. Le décalque disparaîtra sur distance_fade_begin + distance_fade_length, après quoi il sera coupé et ne sera pas envoyé au shader du tout. Utilisez cela pour réduire le nombre de décalques actifs dans une scène et ainsi améliorer les performances.

float distance_fade_length = 10.0 🔗

  • void set_distance_fade_length(value: float)

  • float get_distance_fade_length()

La distance sur laquelle le décalque disparaît (en unités 3D). Le décalque devient lentement plus transparent au cours de cette distance et est complètement invisible à la fin. Des valeurs plus élevées résultent en une transition plus fluide, plus adaptée lorsque la caméra se déplace rapidement.

float emission_energy = 1.0 🔗

  • void set_emission_energy(value: float)

  • float get_emission_energy()

Multiplicateur de l'énergie pour la texture d'émission. Cela fera que le décalque émet de la lumière à une intensité supérieure ou inférieure, indépendamment de l’albédo. Voir aussi modulate.

float lower_fade = 0.3 🔗

  • void set_lower_fade(value: float)

  • float get_lower_fade()

Définit la courbe sur laquelle le décalque va disparaître lorsque que la surface s'éloigne du centre de l'AABB. Seules les valeurs positives sont valides (les valeurs négatives seront bornées à 0.0). Voir aussi upper_fade.

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

  • void set_modulate(value: Color)

  • Color get_modulate()

Change la Color du Decal en multipliant la couleur de l'albédo et de l'émission avec cette valeur. La composante alpha est seulement prise en compte lors de la multiplication de la couleur de l'albédo, pas de la couleur de l'émission. Voir aussi emission_energy et albedo_mix pour changer l'intensité de l'émission et de l'albédo indépendamment l'une de l'autre.

float normal_fade = 0.0 🔗

  • void set_normal_fade(value: float)

  • float get_normal_fade()

Fait disparaître le Decal si l'angle entre l'AABB du Decal et la surface cible devient trop grand. Une valeur de 0 projette le Decal indépendamment de l'angle, une valeur de 1 limite le Decal aux surfaces presque perpendiculaires.

Note : Définir normal_fade à une valeur supérieure à 0.0 a un petit coût de performance en raison des calculs d'angle normaux ajoutés.

Vector3 size = Vector3(2, 2, 2) 🔗

Sets the size of the AABB used by the decal. All dimensions must be set to a value greater than zero (they will be clamped to 0.001 if this is not the case). The AABB goes from -size/2 to size/2.

Note: To improve culling efficiency of "hard surface" decals, set their upper_fade and lower_fade to 0.0 and set the Y component of the size as low as possible. This will reduce the decals' AABB size without affecting their appearance.

Texture2D texture_albedo 🔗

Texture2D avec la Color de base du Decal. Soit cela soit la texture_emission doit être définie pour que le Decal soit visible. Utilisez le canal alpha comme un masque pour mélanger en douceur les bords du décalque avec l'objet sous-jacent.

Note : Contrairement à BaseMaterial3D dont le mode de filtrage peut être ajusté selon le matériau, le mode de filtrage pour les textures de Decal est défini globalement avec ProjectSettings.rendering/textures/decals/filter.

Texture2D texture_emission 🔗

Texture2D avec la Color d'émission du Decal. Soit cela soit la texture_albedo doit être définie pour que le Decal soit visible. Utilisez le canal alpha comme un masque pour mélanger en douceur les bords du décalque avec l'objet sous-jacent.

Note : Contrairement à BaseMaterial3D dont le mode de filtrage peut être ajusté selon le matériau, le mode de filtrage pour les textures de Decal est défini globalement avec ProjectSettings.rendering/textures/decals/filter.

Texture2D texture_normal 🔗

Texture2D avec la normal map par pixel du Decal. Utilisez cela pour ajouter des détails supplémentaires aux décalques.

Note : Contrairement à BaseMaterial3D dont le mode de filtrage peut être ajusté selon le matériau, le mode de filtrage pour les textures de Decal est défini globalement avec ProjectSettings.rendering/textures/decals/filter.

Note : Définir seulement cette texture ne résultera pas en un décalque visible, car texture_albedo doit également être définie. Pour créer un décalque avec seulement des normales, chargez une texture d'albedo dans texture_albedo et définissez albedo_mix à 0.0. Le canal alpha de la texture de l'albédo sera utilisé pour déterminer où la normal map de la surface sous-jacente devrait être redéfinie (et son intensité).

Texture2D texture_orm 🔗

Texture2D storing ambient occlusion, roughness, and metallic for the decal. Use this to add extra detail to decals.

Note: Unlike BaseMaterial3D whose filter mode can be adjusted on a per-material basis, the filter mode for Decal textures is set globally with ProjectSettings.rendering/textures/decals/filter.

Note: Setting this texture alone will not result in a visible decal, as texture_albedo must also be set. To create an ORM-only decal, load an albedo texture into texture_albedo and set albedo_mix to 0.0. The albedo texture's alpha channel will be used to determine where the underlying surface's ORM map should be overridden (and its intensity).

Note: Due to technical limitations, modifying the underlying surface's roughness using texture_orm does not affect screen-space reflections (Environment.ssr_enabled), reflections from VoxelGI, and reflections from SDFGI (Environment.sdfgi_enabled). Only reflections from ReflectionProbes are affected.

float upper_fade = 0.3 🔗

  • void set_upper_fade(value: float)

  • float get_upper_fade()

Définit la courbe sur laquelle le décalque va disparaître lorsque que la surface s'éloigne du centre de l'AABB. Seules les valeurs positives sont valides (les valeurs négatives seront bornées à 0.0). Voir aussi lower_fade.

Descriptions des méthodes

Texture2D get_texture(type: DecalTexture) const 🔗

Renvoie la Texture2D associée au DecalTexture spécifié. Il s'agit d'une méthode de commodité, dans la plupart des cas, vous devriez accéder directement à la texture.

Par exemple, au lieu de albedo_tex = $Decal.get_texture(Decal.TEXTURE_ALBEDO), utilisez albedo_tex = $Decal.texture_albedo.

Un cas où cela vaut meilleur que d'accéder directement à la texture est quand vous voulez copier une texture d'un Decal vers un autre. Par exemple :

for i in Decal.TEXTURE_MAX:
    $NouveauDecal.set_texture(i, $AncienDecal.get_texture(i))

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

Définit la Texture2D associée au DecalTexture spécifié. Il s'agit d'une méthode de commodité, dans la plupart des cas, vous devriez accéder directement à la texture.

Par exemple, au lieu de $Decal.set_texture(Decal.TEXTURE_ALBEDO, albedo_tex), utiliser $Decal.texture_albedo = albedo_tex.

Un cas où cela est meilleur que d'accéder directement à la texture est quand vous voulez copier une texture d'un Decal à un autre. Par exemple :

for i in Decal.TEXTURE_MAX:
    $NouveauDecal.set_texture(i, $AncienDecal.get_texture(i))