Table of Contents

Class Decal

Namespace
Godot
Assembly
GodotSharp.dll

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, ExtraCullMargin must be increased on the mesh. Otherwise, the decal may not be visible on the mesh.

public class Decal : VisualInstance3D, IDisposable
Inheritance
Decal
Implements
Inherited Members

Constructors

Decal() 

public Decal()

Properties

AlbedoMix

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.

public float AlbedoMix { get; set; }

Property Value

float

CullMask

Specifies which Layers this decal will project on. By default, Decals affect all layers. This is used so you can specify which types of objects receive the Decal and which do not. This is especially useful so you can ensure that dynamic objects don't accidentally receive a Decal intended for the terrain under them.

public uint CullMask { get; set; }

Property Value

uint

DistanceFadeBegin

The distance from the camera at which the Decal begins to fade away (in 3D units).

public float DistanceFadeBegin { get; set; }

Property Value

float

DistanceFadeEnabled

If true, decals will smoothly fade away when far from the active Camera3D starting at DistanceFadeBegin. The Decal will fade out over DistanceFadeBegin + DistanceFadeLength, after which it will be culled and not sent to the shader at all. Use this to reduce the number of active Decals in a scene and thus improve performance.

public bool DistanceFadeEnabled { get; set; }

Property Value

bool

DistanceFadeLength

The distance over which the Decal fades (in 3D units). The Decal becomes slowly more transparent over this distance and is completely invisible at the end. Higher values result in a smoother fade-out transition, which is more suited when the camera moves fast.

public float DistanceFadeLength { get; set; }

Property Value

float

EmissionEnergy

Energy multiplier for the emission texture. This will make the decal emit light at a higher or lower intensity, independently of the albedo color. See also Modulate.

public float EmissionEnergy { get; set; }

Property Value

float

LowerFade

Sets the curve over which the decal will fade as the surface gets further from the center of the Aabb. Only positive values are valid (negative values will be clamped to 0.0). See also UpperFade.

public float LowerFade { get; set; }

Property Value

float

Modulate

Changes the Color of the Decal by multiplying the albedo and emission colors with this value. The alpha component is only taken into account when multiplying the albedo color, not the emission color. See also EmissionEnergy and AlbedoMix to change the emission and albedo intensity independently of each other.

public Color Modulate { get; set; }

Property Value

Color

NormalFade

Fades the Decal if the angle between the Decal's Aabb and the target surface becomes too large. A value of 0 projects the Decal regardless of angle, a value of 1 limits the Decal to surfaces that are nearly perpendicular.

Note: Setting NormalFade to a value greater than 0.0 has a small performance cost due to the added normal angle computations.

public float NormalFade { get; set; }

Property Value

float

Size

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 UpperFade and LowerFade 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.

public Vector3 Size { get; set; }

Property Value

Vector3

TextureAlbedo

Texture2D with the base Color of the Decal. Either this or the TextureEmission must be set for the Decal to be visible. Use the alpha channel like a mask to smoothly blend the edges of the decal with the underlying object.

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.

public Texture2D TextureAlbedo { get; set; }

Property Value

Texture2D

TextureEmission

Texture2D with the emission Color of the Decal. Either this or the TextureAlbedo must be set for the Decal to be visible. Use the alpha channel like a mask to smoothly blend the edges of the decal with the underlying object.

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.

public Texture2D TextureEmission { get; set; }

Property Value

Texture2D

TextureNormal

Texture2D with the per-pixel normal map 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 TextureAlbedo must also be set. To create a normal-only decal, load an albedo texture into TextureAlbedo and set AlbedoMix to 0.0. The albedo texture's alpha channel will be used to determine where the underlying surface's normal map should be overridden (and its intensity).

public Texture2D TextureNormal { get; set; }

Property Value

Texture2D

TextureOrm

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 TextureAlbedo must also be set. To create an ORM-only decal, load an albedo texture into TextureAlbedo and set AlbedoMix 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).

public Texture2D TextureOrm { get; set; }

Property Value

Texture2D

UpperFade

Sets the curve over which the decal will fade as the surface gets further from the center of the Aabb. Only positive values are valid (negative values will be clamped to 0.0). See also LowerFade.

public float UpperFade { get; set; }

Property Value

float

Methods

HasGodotClassMethod(in godot_string_name)

Check if the type contains a method with the given name. This method is used by Godot to check if a method exists before invoking it. Do not call or override this method.

protected override bool HasGodotClassMethod(in godot_string_name method)

Parameters

method godot_string_name

Name of the method to check for.

Returns

bool

HasGodotClassSignal(in godot_string_name)

Check if the type contains a signal with the given name. This method is used by Godot to check if a signal exists before raising it. Do not call or override this method.

protected override bool HasGodotClassSignal(in godot_string_name signal)

Parameters

signal godot_string_name

Name of the signal to check for.

Returns

bool

InvokeGodotClassMethod(in godot_string_name, NativeVariantPtrArgs, out godot_variant)

Invokes the method with the given name, using the given arguments. This method is used by Godot to invoke methods from the engine side. Do not call or override this method.

protected override bool InvokeGodotClassMethod(in godot_string_name method, NativeVariantPtrArgs args, out godot_variant ret)

Parameters

method godot_string_name

Name of the method to invoke.

args NativeVariantPtrArgs

Arguments to use with the invoked method.

ret godot_variant

Value returned by the invoked method.

Returns

bool
Edit this page