View source for Decals

{{LanguageBar}}
{{tabs|Decals|goldsrc=1|source=1|main=source}}

[[File:Decal06.jpg|thumb|A decal placed by a level designer.]] [[File:Decal03.jpg|thumb|Bullet impacts generated by the game.]]

'''Decals''' are materials projected onto existing surfaces. They can be placed by the level designer, and are also generated by the engine for bullet impacts, blood, and other effects.

{{note|Each decal affects ''one entity only''. ([[The world]] is one big entity.)}}

Decals are "sprayed" from a location and mark every surface in their path. For instance, a decal applied downward onto a staircase would cascade down onto the top (but not front) of each step.

== Using ==

{{note|[[VertexLitGeneric]] decals won't show up on brushes, and [[LightmappedGeneric]] ones won't appear on models. Decals using <code>DecalModulate</code> or <code>$modelmaterial</code> work everywhere ([[#Creating|see below]]).}}

=== Hammer ===

; '''{{hammer decal}}'''
: Creates [[infodecal]] entities, which decal [[brush]]es and [[displacement]]s.
; '''[[info_projecteddecal]]'''
: An entity that decals [[model]]s or displacements (but ''not'' brushes). The angle of projection can be set, allowing for distortion.
; '''{{hammer overlay}}'''
: Overlays are more [[expensive]] decals that offer level designers more control.

[[infodecal]] and [[info_projecteddecal]] create [[edicts]] that last until the decal is sprayed (for unnamed decals, this is a split second after the map spawns). [[info_overlay]] only creates edicts if named.

{{tip|If a decal entity has a name it will appear when [[use]]d (i.e. blank input) or on receiving the <code>activate</code> input, instead of when the map starts. The entity then disappears.}}

{{note|Decals can also be made out of brushes or displacements using {{cmd|$decal}} materials, by having the decal be coplanar to the face that it is decaling. Due to [[VBSP]] performing a CGG pass on map geometry, however, decal brushes which aren't part of a separate [[bmodel]] (i.e. using [[func_illusionary]]) may not reliably appear in-game. Additionally, brush-based decals will use additional [[brushside]]s.
{{modernConfirm|[[func_detail]]-based decals will reliably show up on structural world brushes and brush entities, but what about on other func_details?}} }}

=== C++ ===

==== Standard ====

Created in response to impacts, blood, and so on. Limited in number by the value of [[r_decals]], [[CRecipientFilter#Reliable vs. Unreliable|unreliable]] when transmitted, and not transmitted to players who connect after creation.

{{note|Only materials registered in <code>scripts/decals_subrect.txt</code> can be used!}}

; <code>CBaseEntity::DecalTrace([[trace_t]]* pTrace, const char* decalName)</code>
: Shared code. The trace defines where the decal is projected from and its location. {{todo|How to avoid transmission being suppressed due to prediction?}}
; <code>C_BaseEntity::AddDecal( <lots of args> );</code>
: Client function where the decal is actually created. In most cases you are better off just calling <code>DecalTrace()</code>.

==== Static ====

Normally created by the level designer. These decals last forever and are always transmitted, including to players who connect later on. Any material can be used.

; <code>engine->StaticDecal( Vector localOrigin, int decalIndex, int entityIndex, int modelIndex, bool lowpriority )</code>
: Server only. This system does not appear use entities.
:; <code>Vector localOrigin</code>
:: Where the decal will be created, relative to the target's origin.
:; <code>int decalIndex</code>
:: A value received from <code>UTIL_PrecacheDecal()</code>. ''Don't'' use <code>GetDecalIndexForName()</code>.
:; <code>int entityIndex</code>
:; <code>int modelIndex</code>
:: Information about the target entity.
:; <code>bool lowpriority</code>
:: Low priority decals are not saved/restored, and can be "re-used on the client preferentially".
; <code>UTIL_PrecacheDecal(const char *filename, bool preload)</code>
: Returns a decal index for use with <code>StaticDecal()</code>. If this is in <code>[[precache()]]</code>, remember that it may be called statically; store the result in a global var.

== Creating ==

: ''This section assumes that you understand the basics of [[Material Creation|material creation]].''

Any material can be used as a decal. They generally have an [[alpha channel]] however, and can use some special parameters and/or the <code>[[#DecalModulate|DecalModulate]]</code> shader.

<gallery mode=nolines widths=128px style="text-align:center;">
decal04.jpg|Source RGB color channels
decal05.jpg|Source alpha channel
Decal06.jpg|Decal in the world
</gallery>

===Material parameters===
; <code>[[$decal]] <[[bool]]></code>
: Prevents decal texture clipping.
: {{note|This parameter is not exclusive to decal entities; any material can have $decal to modify how it is sorted when coplanar with another surface.}}
; <code>$decalscale <[[float]]></code>
: Same as a brush face's texture scale value: the number of [[unit]]s that each [[texel]] covers. Normally 0.25 or lower. {{note|This defines the size of the decal's geometry, and cannot be changed after its creation. Use [[$basetexturetransform]] if you want motion.}}
; <code>$modelmaterial <material></code>
: A separate <code>[[VertexLitGeneric]]</code> material to that will replace this one if the decal hits a [[model]].
; <code>$decalfadeduration <float></code>
: Amount of time to spend fading out. Requires <code>[[$vertexcolor]]</code>.
{{bug| This is broken in {{src13|4}}, decals will not fade out}}
; <code>$decalfadetime <float></code>
: Delay before fadeout begins.
{{bug| This is broken in {{src13|4}}, decals will not fade out}}
; <code>$decalsecondpass <[[bool]]></code>
: ALWAYS render this decal on top of decals ''without'' this parameter. If two decals with this parameter intersect, they will treat each other how two without the parameter would.
; <code>$fogscale <float></code>
: {{L4D2 add}} Scales the amount of fog affecting the decal. Useful for making important decals stand out in foggy levels.
; <code>$splatter <bool></code>
: {{CSGO add}} {{todo|What does this do?}}

Decals do not support [[normal maps]] in all engine branches prior to CS:GO. The underlying brushes/displacements ''must'' have bumped lightmaps for the decal's normal map to have any effect.
: {{confirm|Is CS:GO the first game to support this feature?}}

=== DecalModulate ===
{{split|[[DecalModulate]]}}
For decals intended to mimic the look of pock marks or dents in a surface, the '''<code>DecalModulate</code>''' (a.k.a. mod2x) shader is especially suitable: it lightens destination pixels for every source pixel that is over mid-range gray (128) and darkens any destination pixels for every source pixel that is below mid-range gray. This effect can be used to give the impression of depth when applied to a surface.

To begin, create a source image whose color channel will be used for the modulation's source values. Again, light values will lighten pixels they're drawn over, while dark values will darken the destination pixels. Mid-gray values will be treated as translucent.

Next, create an alpha channel that defines a mask for the decal. Because modulation cannot have an exact middle value with DXTn compression, the mask is necessary to prevent "bordering" from occurring around the decal. You can avoid "bordering" without creating an alpha channel simply by using BGR888 format instead of DXT1/DXT5 when you create your VTF, at the cost of being triple the file size.
{{modernConfirm|Does I8 (greyscale) work, like with {{cmd|$detailblendmode|0}}, or does the shader require RGB data? I8 is the same size as DXT5, and but accurately represent all 256 possible modulation values (albeit without color).}}
{{note|It has also been observed in {{l4d2|4}} that DXT1 compressed textures using DecalModulate shader (such as blood splatters and "graffiti wall writing") with background colors RGB 124 126 124 are considered unmodulated, alleviating "bordering". L4D2's [[Vtex (Source 1)|vtex]] will output that specific color from the source image pixels are gray RGB 127 127 127. This solution may also apply to other engine branches (and other versions of vtex) that use RGB 124 126 124 as the color indicating lack of modulation in-game, but needs further testing.}}
{{todo|Try converting source images with background colors RGB 127 127 127 with vtex found in other games other than L4D2 and see if it results in a background with RGB 124 126 124. Also, does RGB 124 126 124 apply to other versions of the Source engine as unmodulated for DXT1 compression? It is possible that the upgraded shader has a range of a few values before modulation occurs.}}

<gallery mode=nolines widths=128px style="text-align:center;">
decal01.jpg|Source RGB color channels
decal02.jpg|Source alpha channel
Decal03.jpg|Decal in the world
</gallery>

Finally, you must create a material that uses the <code>DecalModulate</code> shader. Neither <code>$translucent</code> nor <code>$decal</code> are needed this time.

{{tip|{{mono|DecalModulate}} is equivalent to the "Overlay" layer mode in image editors such as {{gimp|4}} or {{photoshop|4}}.}}

== See also ==
* [[Decals in Photoshop]]
* [[Decals in GIMP]]
* [[infodecal]]
* [[info_projecteddecal]]
* [[info_overlay]]
* [[$nodecal]]

[[Category:Material System]]
[[Category:Glossary]]