Decal System Technical Guide

Overview

This page provides technical details for programmers on the decal system and using decals.

DecalComponent member variables

What follows is a brief description of the DecalComponent member variables...

Material

The DecalMaterial property represents the material to use on this decal. A MaterialInstance chain that must eventually lead to a DecalMaterial

Size

The size of the decal on the surface (tangent/binormal directions):

• Width/Height

Planes

The size of the decal:

• NearPlane/FarPlane

Tiling

Tiling multipliers and offsets for the decal UVs:

• TileX/TileY
• OffsetX/OffsetY

Hit Information

Information about the decal frustum location and orientation, used during render data computation and also for decal debug rendering:

• HitLocation
• HitNormal
• HitTangent
• HitBinormal

Clipping

The bNoClip property defaults to FALSE. If TRUE, use the "NoClip" codepath when computing decal geometry. This codepath does not perform a software clip of potential receiver triangles against the decal frustum, at the expense of extra fill during decal rendering. In addition, textures used in "NoClip" decal materials must have their address mode set to TA_Clamp and have a transparent border around their outer edge wide enough to survive mipmapping.

Note that bNoClip is implied for lit decals on vertex-lit static meshes.

Static

The bStaticDecal property is TRUE only for decals placed in the level through the editor. bStaticDecal is set to TRUE by ADecalActor's defaultproperties block.

Receivers

HitComponent defaults to NULL. If non-NULL, only this component will be considered as a potential receiver when computing decal geometry. Setting this property precludes having to intersect against all potential receivers, but may lead to undesirable results, as the decal will project only onto the specified component (which is bad for eg. rocket blasts).

Components

The list of components that generated geometry for this decal and their associated render data. The Receiver and RenderData arrays are always of the same length, and the i'th entry of RenderData is the data for Receiver i. This layout allows for receivers to be attached/detached to the decal independantly of others.

Bias

When two or more decals overlap, the DepthBias and SlopeScaleDepthBias parameters can be used to bias the decal's depth to control whether it is rendered below or above other decals.

Filtering

As described above, Filter contains a list of actors to filter and FilterMode describes whether or not the actors in the Filter (FM_Ignore) list should be ignored or should be the only actors affected (FM_Affect) by this decal. The default value is FM_None, meaning that the Filter is not consulted

Projection Flags

These flags control whether the decal projects onto:

• bProjectonBackfaces - triangle backfaces
• bProjectOnBSP - BSP
• bProjectOnStaticMeshes - static meshes
• bProjectOnSkeletalMeshes - skeletal meshes
• bProjectOnTerrain - terrain

Creating decals from script

Decals are typically created by calling DecalManager's >SpawnDecal member function. The basic process is to simply call SpawnDecal with arguments describing the decal's size, orientation, material, and hints about how the decal should be computed.

Imagine a weapon class containing a SpawnHitDecal member function that gets called in response to a weapon hitting something in the game.

Code for this function might look like the following:

// A class containing state/behaviour shared by all weapons in your game.
class BaseWeaponClassForYourGame extends Weapon

// ...

// Generates a decal based on a weapon hit; called by functions like eg. SpawnExplosionEffects.
simulated function SpawnHitDecal(ImpactInfo Impact)
{
    local DecalComponent         DecalTemplate;

    // Consult eg. the physical material system stored in the impact info
    // to get decal parameters appropriate for this surface/weapon pairing.
    DecalTemplate = Impact.GetDecalTemplate( this );

    // Create a decal based on the decal template.
    WorldInfo.MyDecalManager.SpawnDecal( DecalTemplate.DecalMaterial,                // UMaterialInstance used for this decal.
                              Impact.HitLocation,                         // Decal spawned at the hit location.
                              rotator(-Impact.HitNormal),                 // Orient decal into the surface.
                              DecalTemplate.Width, DecalTemplate.Height,  // Decal size in tangent/binormal directions.
                              DecalTemplate.Thickness,                    // Decal size in normal direction.
                              DecalTemplate.bNoClip,                      // If TRUE, use "NoClip" codepath.
                              FRand() * 360,                              // random rotation
                              Impact.HitInfo.HitComponent );               // If non-NULL, consider this component only.
}

Decal Lifetime Management

The singleton DecalManager Actor, accessed through WorldInfo->MyDecalManager, manages temporary decals. It keeps a list of all such decals currently in the world. The base implementation simply ticks down a configurable lifetime for each decal and detaches it when the time expires, but this class can easily be overridden (through the configurable DecalManagerClassPath in WorldInfo) to implement different behavior.

The DecalManager also pools DecalComponents it creates. When a decal's lifetime runs out, it is returned to the pool and that component will be used again for a future SpawnDecal() call. This minimizes object overhead and garbage collection times by having only as many DecalComponents around as are needed in a worst case instead of constantly creating and throwing away objects.

Performance Monitoring

Relevant Stats

The Engine stats group (visualized by entering stat engine on the in-game console) contains two entries relevant to decals: DecalDrawCalls, the total number of decal draw calls; and DecalTriangles, the total number of decal triangles passed to the renderer. Also, the Game stats group (stat game) contains DecalTime, the amount of time spent ticking the decal manager and decal lifetime policies.

Relevant ShowFlags

Their are two showflags governing decal rendering. SHOW DECALINFO enables the rendering of decal debug information, including decal frustums and their tangent bases. SHOW DECALS globally toggles whether or not decals are drawn to a viewport, including any decal debug rendering enabled with DECALINFO.

Globally enabling/disabling decals

The bStaticDecalsEnabled and bDynamicDecalsEnabled config member variables of Engine can be used to enable/disable all aspects (geometry computation, scene attachment and rendering, etc.) of static and dynamic decals. Both variables default to TRUE, meaning decals are fully enabled.

Using Decals

For information on placing and manipulating decals in levels using the editor tools, please see the Using Decals page.