Decalery manual

(Draft)

Components

Decal Group

Represents a decal projector, defined by the MeshFilter/MeshRenderer on the same object. Decal shape can be anything from a simple quad, to a complex shape, such as e.g. a corner, a ring around another object, etc. MeshRenderer should be normally disabled after the decal is projected.

Settings:

• Receiver selection mode: defines how the decal-receiving objects are selected. Possible options:
  • Manual: receivers are selected by hand. This is the most precise and predictable method. Objects can be chosen via both the standard Unity selector or by pressing the "Pick in Scene" button and directly clicking receivers in the scene. To the side of every added object there are X and M buttons:
    • Pressing X will remove the receiver from the list.
    • Pressing M will show a material field which will be used instead of the decal's own material only for the selected receiver. This is useful when, for example, the same decal is applied to a dry and a wet surface, where different shaders might be desirable.
  • Box Intersection: receivers are chosen by overlapping a box with nearby colliders.
    • Box scale: scales the selection box. Final box size is affected both by decal mesh bounds, Forward/Backward distance and Box scale.
  • Raycast from vertices: receivers are chosen by performing a physics raycast from every vertex of the decal's mesh, in the inverse normal direction. As with the previous option, it only picks up objects having colliders.

• Forward distance: decal projection distance (inside).
• Backward distance: decal projection distance (outside).
• Angle clip: maximum allowed angle between each decal triangle and projector triangle. The value is from -1 (-180) to 1 (180). This is to prevent texture stretching on surfaces parallel to the projection.
• Angle fade: fades vertex color/alpha to 0 as the projection approaches Angle clip value.
• Layer mask: a simple layer mask to filter out receiving objects.
• Generate tangents: does decal geometry need per-vertex tangents generated? Tangents are required for normal-mapping, parallax and other effects.
• Link to parent: if enabled, decal meshes will be parented to their receivers.
• Optimize: performs vertex welding and vertex order optimization.

Buttons:

• Live Preview: when enabled, decal will be rebuilt interactively, as it is transformed, or its settings are tweaked.
• Update: (re)builds the decal geometry once.
• Remove: removes previously generated decal geometry.

Runtime API

Decals can be created at runtime. While it is possible to directly use the DecalGroup component, it is not recommended for performance reasons. Decalery has a special fast mode of generating and rendering simple quad-like and trail-like decals at runtime. The architecture is as follows:

---

DecalSpawner

DecalSpawner class is the main building block that manages pools of decals using identical settings and materials. For example, in a shooter, a single DecalSpawner for bullet holes can be used by all guns of all characters. Internally DecalSpawner will create lower-level DecalUtils.Group objects for every combination of shader variant / lightmap index / parent transform.

Properties:

• InitData initData
  Main spawner settings. InitData class contains following members:
  
  
  • Material material
    Base material used by all spawned decals. Use shaders made specifically for decals (offsetting position to camera to prevent Z-fighting).
    
    
  • bool isTrail
    Is this decal a trail (e.g. a tire track)? Trails connect edge-to-edge instead of being separated quads. Trails also have a unique continuous UV generation style.
    
    
  • float trailInterval
    If isTrail is enabled, controls interval between trail edges (smaller interval = rounder trails).
    
    
  • float trailVScale
    If isTrail is enabled, controls vertical texture coordinate tiling.
    
    
  • bool tangents
    Should decals have tangents (do they need normal mapping)?
    
    
  • bool inheritMaterialPropertyBlocks
    Should these decals inherit MaterialPropertyBlocks from receivers?
    
    
  • bool useShaderReplacement
    Use shader replacement feature? (see next)
    
    
  • ShaderReplacement[] shaderReplacement
    Allows optionally overriding decal shader based on the receiver's shader. Can be used when applying decals to e.g. special surfaces with vertex deformation. ShaderReplacement structure contains following members
    
    • Shader src
    • Shader dest
      If receiver has shader src, decal will use shader dest.
      

Methods:

• void Init(int maxTrisTotal, int maxTrisInDecal, DecalUtils.Mode preferredMode, bool preferDrawIndirect, int preferredShaderPass)
  Initializes the spawner using its properties. Must be called only once.
  
  • int maxTrisTotal
    Maximum amount of triangles used in a single DecalUtils.Group spawned. Decal triangle count depends on receiver geometry detail and decal size. Older decals will disappear when new decals are added above the limit.
    
  • int maxTrisInDecal
    Maximum allowed triangle count for one decal. Similarly, it depends on receiver geometry detail and decal size. While this number can be set to maxTrisTotal for safety, using a lower realistic value will reduce processing time.
    
  • DecalUtils.Mode preferredMode
    Preferred decal generation mode. Possible values are:
    
    • DecalUtils.Mode.CPU
      Generation is done on the CPU, similar to how the DecalGroup component works. This is the slowest, but also the most platform-compatible option. Requires receiver meshes to have Read/Write Enabled.
      
    • DecalUtils.Mode.GPU
      Generation is done on the GPU. This option requires hardware support for Unordered Access Views and Geometry Shaders (i.e. sm5_0). Receivers do not need to have Read/Write Enabled.
  • bool preferDrawIndirect
    Are these decals supposed to be rendered with DrawProceduralIndirect? Such decals do not require costly VRAM->RAM->VRAM memory transfers, as the generated buffer is used directly by the drawing shader. Shader must be aware of this method.
    
  • int preferredShaderPass
    Shader pass used by indirect-drawing shaders. If the pass is not present in the shader, it will be clamped to the highest available value.
    

Currently, skinned meshes only support CPU generation mode. DecalSpawner will automatically fallback to CPU when used on skinned meshes.

• void AddDecal(Vector3 position, Quaternion rotation, GameObject hitObject, float decalSizeX, float decalSizeY, float distance, float opacity, float angleClip, Transform rootObject)
  Spawns a decal on hitObject from a projector placed at position in the direction of rotation.
  
  • Vector3 position
    Projection origin.
    
  • Quaternion rotation
    Projection rotation. Decals are projected along the positive Z axis.
    
  • GameObject hitObject
    Object receiving the decal. Must have either a MeshRenderer, a SkinnedMeshRenderer or a DecalMeshRef (containing a list of renderers). When the decal is applied to a SkinnedMeshRenderer, hitObject matrix will be used to transform into bind pose correctly.
    
  • float decalSizeX
    Decal width.
    
  • float decalSizeY
    Decal height.
    
  • float distance
    Decal projection distance (same as Forward distance in DecalGroup).
    
  • float opacity
    Opacity multiplier.
    
  • float angleClip
    Same as Angle clip in DecalGroup.
    
  • Transform rootObject
    Optional transform used as a parent for this decal. Assign movable objects' transforms here.
    

---

DecalManager

DecalManager manages the creation and reuse of DecalSpawners. Its main purpose is to let different scripts to access the same shared spawners.

Methods:

• static void SetPreferredMode(DecalUtils.Mode mode, bool drawIndirect, int pass)
  Sets preferred generation/rendering settings for all newly created spawners (see Init).
  
  
• static DecalSpawner GetSpawner(DecalSpawner.InitData initData, int maxTrisTotal, int maxTrisInDecal)
  Gets an existing spawner or creates a new one using provided settings.
  
  
• static DecalSpawner GetSpawner(string name, int maxTrisTotal, int maxTrisInDecal)
  Same, but will attempt to load initData from Resources/DecalTypes/name.asset. This data can be stored in DecalType assets, as seen in the included example scenes.
  
  
• static DecalSpawner CreateUniqueSpawner(DecalSpawner.InitData initData, int maxTrisTotal, int maxTrisInDecal)
  Similar to GetSpawner, but always creates a new spawner. Normally. this is only useful for trail decals, as they connect to each other within one DecalUtils.Group.