Decalery manual

From Bakery GPU Lightmapper: Wiki
Jump to navigation Jump to search

(Draft)

Installation

Simply import the package into Unity. If project uses URP, also unpack DecaleryURP.unitypackage; If project uses HDRP, unpack DecaleryHDRP.unitypackage.

Current limitations

Built-in (5.6) Built-in (2017.X) Built-in (2018.X) Built-in (>= 2019.1) URP 15.0.7 (tested on 2023.1.5) HDRP 15.0.6 (tested on 2023.1.5)
Editor and Runtime CPU decals Yes Yes Yes Yes Yes Yes
Runtime decals: GPU with readback No Yes (slower mesh API) Yes (slower mesh API) Yes Yes Yes
Runtime decals: Full GPU No It does something? Yes, but local lights only work correctly in Deferred Yes, but local lights only work correctly in Deferred No (can't copy per-object data to decals) Not tested yet


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.

Decal gets position, normals and lightmap UVs from the receiver, but retains its own texture UVs, tangents and vertex color. Decalery assumes that vertex color is used as a single opacity value (fade).

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:

Decalarch.jpg

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.

  • Dictionary<int, DecalUtils.Group> staticGroups
    A map of all static (that is, not having any parent transform) DecalUtils.Groups created by this spawner, indexed by their lightmap ID.

  • Dictionary<Transform, DecalUtils.Group> movableGroups
    A map of all movable DecalUtils.Groups created by this spawner, indexed by their parent transform.

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.
Bulbgraph.pngCurrently, 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 (bone) 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.

  • void AddDecalToQueue(Vector3 position, Quaternion rotation, GameObject hitObject, float decalSizeX, float decalSizeY, float distance, float opacity, float angleClip, Transform rootObject)
    Similar to AddDecal, but adds the decal to the queue instead (see next).

  • void UpdateQueue(int maxDecalsPerFrame)
    Takes maxDecalsPerFrame elements from the queue and executes them. This is useful to prevent too many decals spawning in one frame, thus affecting performance.

  • void Clear()
    Removes all visible decals, created with this spawner. Doesn't release memory.

  • void Release()
    Removes all visible decals, created with this spawner and releases all used memory.

Static properties:

  • static List<DecalSpawner> All
    A list of all spawners ever created.

DecalManager

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

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

DecalUtils

DecalUtils.Group is a lower-level object, representing a fixed-sized pool of decals, sharing a common material, lightmap index and parent transform. Most of the time there is no need to use it directly. DecalUtils class uses static methods to work with DecalUtils.Group. Underneath, most methods branch to either CPUDecalUtils or GPUDecalUtils.

CPUDecalUtils

CPUDecalUtils are used internally for both runtime CPU decals and in-editor DecalGroups.

GPUDecalUtils

GPUDecalUtils are used internally for runtime GPU decals. There are some GPU-specific methods that are useful for indirect drawing:

  • static CommandBuffer CreateDrawIndirectCommandBuffer(DecalUtils.Group group, int pass)
    Creates a CommandBuffer drawing the decals directly from generated data on the GPU, with the specified shader pass. Decal group must be created witn indirectDraw enabled.

  • static void UpdateDrawIndirectCommandBuffer(DecalUtils.Group group, Matrix4x4 mtx, int pass)
    Updates the command buffer using a new transformation matrix.


Examples of GPUDecalUtils usage can be found in DecalGlobalRuntimeSettings.cs.

Retrieved from "https://geom.io/bakery/wiki/index.php?title=Decalery_manual&oldid=1401"