View source for Decals

When the player shoots his or her weapon into a wall, the marks left by the bullet impacts are called "decals". These are most easily thought of as materials that are applied to a surface and remain there as an indelible mark on the world. Posters, scorch marks, and stenciled letters can all be created using this type of graphic. Decals will ''clip'' their extents to whatever surface they are placed on to. For example, a decal applied to a staircase would cascade down on to each stair surface instead of hanging out into space. You can also think of this as how a stencil would apply a mark to the world.

Creating decals is straightforward: they are simply materials generally having an ''alpha channel mask'' of some sort, and possible using the <code>[[DecalModulate]]</code> shader. Before reading this article, please read about the basics of [[Material Creation|material creation]].

== Standard decals ==
The most simple type of decal is one that simply acts like a true decal or stencil: source art is clipped and projected on to the world within some mask, specified via the material's alpha channel (centre):

<div style="text-align:center;">[[Image:decal04.jpg|128px|Source color channels]] [[Image:decal05.jpg|128px|Source alpha channel]] [[Image:Decal06.jpg|128px|Decal in the world]]</div>

===Material parameters===
A decal's [[material]] looks something like this:

 [[LightmappedGeneric]]
 {
 	[[$basetexture]]	decals\mydecal
 	$decal		1
 	$decalscale	0.1
 	[[$translucent]]	1
 
 	$modelmaterial decals\mydecal_model
 }

; <code>$decal <[[bool]]></code>
: Marks the material as a decal. Without it, the decal will not be clipped or projected onto the world properly.
; <code>$decalscale <[[float]]></code>
: Important because its default is one pixel to one inch. If the source texture for this decal is 128 pixels, a value of <code>0.1</code> will cause it to be 12.8 inches in size in the engine (about a foot).
:{{tip|A decal can't be drawn at a higher resolution that the texture it's applied to. [[Hammer Overlay Tool|Overlays]] can, but they are more [[expensive]].}}
; <code>$translucent <bool></code>
: See <code>[[$translucent]]</code>.
; <code>$modelmaterial <material></code>
: Separate <code>[[VertexLitGeneric]]</code> material to apply to models, if applicable.
; <code>$decalfadeduration <float></code>
: Amount of time to spend fading out. Requires <code>[[$vertexcolor]]</code>.
; <code>$decalfadetime <float></code>
: Delay before fadeout begins.
; <code>$decalsecondpass</code>
: {{TODO|??}}

== Application ==

{{note|Decals that are meant to be applied to [[model]]s (such as blood) must use the <code>[[VertexLitGeneric]]</code> or <code>[[DecalModulate]]</code> shaders. <code>[[LightmappedGeneric]]</code> only works on [[brush]]es.}}

=== Hammer ===

*Decals can be placed on [[brush]]es in Hammer with the '''[[Hammer Overlay Tool|Overlay]]''' or '''[[Hammer Decal Tool|Decal]]''' tools. These decals will exist when the map loads.
*The [[info_projecteddecal]] entity can be used to apply decals to both brushes and models at any time.

=== C++ ===

Decals can be created in on the client with <code>C_BaseEntity::AddDecal()</code>. Internally this calls <code>AddStudioDecal()</code> or <code>AddBrushModelDecal()</code> depending on whether the entity has a brush or model. Parameters for these functions:

<source lang=cpp>void C_BaseEntity::AddDecal( const Vector& rayStart, const Vector& rayEnd, const Vector& decalCenter,
				int hitbox, int decalIndex, bool doTrace, trace_t& tr, int maxLODToDecal );

void C_BaseEntity::AddBrushModelDecal( const Ray_t& ray, const Vector& decalCenter,
				int decalIndex, bool doTrace, trace_t& tr );

void C_BaseEntity::AddStudioDecal( const Ray_t& ray, int hitbox, int decalIndex,
				bool doTrace, trace_t& tr, int maxLODToDecal );</source>

This can be achieved on the server with <code>engine->StaticDecal</code>:

<source lang=cpp>void IVEngineServer::StaticDecal( const Vector &originInEntitySpace, int decalIndex, int entityIndex, int modelIndex, bool lowpriority );</source>

Decal indices can be obtained by calling <code>decalsystem->GetDecalIndexForName</code> or <code>UTIL_PrecacheDecal()</code>:

<source lang=cpp>int IDecalEmitterSystem::GetDecalIndexForName( char const *decalname ); // Valid decalnames are defined in scripts/decals_subrect.txt
int UTIL_PrecacheDecal( const char *filename, bool preload );</source>

== Using modulation ==
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 currently, the mask is necessary to prevent "bordering" from occurring around the decal.

{{Tip|You can avoid "bordering" without creating an alpha channel simply by using BGR888 format instead of DXT1 when you create your VTF. {{l4d2}} It has also been observed in [[Left 4 Dead 2]] that DXT1 compressed textures using DecalModulate shader (such as blood splatters and "graffiti wall writing") with background colors RGB 124 126 124 are considered alpha. L4D2's [[vtex]] will output a that specific color from the source image pixels are gray RGB 127 127 127. This solution may also apply to other engines (and other versions of vtex) that use RGB 124 126 124 as the color indicating alpha 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 alpha for DXT1 compression?}}

<div style="text-align:center;">[[Image:decal01.jpg|128px|Source color channels]] [[Image:decal02.jpg|128px|Source alpha channel]] [[Image:decal03.jpg|128px|Decal in the world]]</div>

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.

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

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