$lightmap

From Valve Developer Community
Jump to navigation Jump to search

$lightmap is a material shader parameter for the VertexLitGeneric shader available in Source 2013 Multiplayer Source 2013 Multiplayer, Team Fortress 2 branch Team Fortress 2 branch, and Garry's Mod Garry's Mod.

It defines a lightmap to be used to light the MDL model's material, instead of the per-vertex lighting used by prop_static or point-based vertex lighting used by other models.

Icon-Important.pngImportant: In Source 2013 MultiplayerTeam Fortress 2 branch, $lightmap is automatically overridden by the engine, regardless of if a PPL lightmap is present.

$lightmap can still be used manually in other engine versions (requires custom shaders outside of Garry's Mod).

This parameter does not usually need to be added manually, as VRAD will generate model lightmaps automatically if generatelightmaps is enabled for the prop_static and -StaticPropLighting is enabled in VRAD. Nonetheless, it can still be added manually (not in Source 2013 MultiplayerTeam Fortress 2 branch), such as for using a lightmap on a prop_dynamic, or if a prop_static has multiple materials (as VRAD can only generate lightmaps for the first material and skin).

Tip.pngTip:
  • VRAD versions which support lightmapped props have a -dumppropmaps option, which will create external TGA versions of the generated static prop lightmaps which can be converted to VTF and manually defined as a $lightmap.
    Icon-Bug.pngBug:The resulting TGAs are written with the wrong color space; convert the resulting PPL files instead. This command can still be useful for indicating which model and at what location each prop is, which the PPL filenames lack. (fixed in Garry's Mod)
    Tip.pngTip: To pair static props in a map with their dumped lightmaps, use r_staticpropinfo 2 to show static prop IDs on screen.
  • For already-compiled maps, the lightmaps are stored as PPL files. These can be converted to VTF using Ficool2's proptexelvtf.exe (direct download).
  • If $lightmap is used to manually define lightmaps for a prop_static, disable vertex lighting for the prop (disablevertexlighting) to prevent VRAD from wasting time calculating lighting for the prop and generating a VHV file that will ultimately go unused and waste space.

{{Codenote}} is deprecated. Use {{code note}} instead.

VMT syntax

$lightmap <texture>
models/lightmapped/example.vmt
vmt
VertexLitGeneric { $basetexture "models/lightmapped/example_base" $lightmap "models/lightmapped/example_lightmap" }

Limitations and caveats

Warning.pngWarning: Models use the same UVs for lightmaps as $basetexture, and the model's lightmap is affected by $basetexturetransform; as such, lightmapping on models with overlapping or tiling UVs may not appear as intended!
VRAD cannot create lightmaps for UVs outside of the 0-1 UV space.
Additionally, shadows may appear on UV seams; this is more noticeable on lower-resolution lightmaps.
Icon-Bug.pngBug*:Lightmaps for models with multiple materials do not compile properly in VRAD! A lightmap will only be compiled for the first material on the model, that is a combined version of all the UV's used by all materials.
PlacementTip.pngWorkaround: Define a pre-baked $lightmap in the VMT of the VertexLitGeneric material (can be obtained using -dumppropmaps in VRAD).
Warning.pngWarning: Model lightmaps generated with VRAD are compiled as RGB888 (24-bit SDR) PPL files which can result in noticeable color banding when brightly lit in HDR mode.
PlacementTip.pngWorkaround:
  • Define a pre-baked RGBA16161616f $lightmap in the VMT of the VertexLitGeneric material. A custom-coded compiler would be required to this accurately (and could also create RGBA16161616f PPL files instead, although this may not work with vanilla shaders).
    • Garry's Mod Garry's Mod's VRAD now bakes RGBA16161616f PPL files in addition to the traditional 24-bit SDR RGB888 PPL files.[1] VRAD bakes and packs both PPLs in maps (during the -hdr and -ldr stages respectively) and will swap between them depending on the client's currently selected HDR mode. -dumppropmaps has also been updated to output PFM files in addition to the traditional TGAs, both being dumped to a new folder located at steamapps\common\GarrysMod\garrysmod\sp_lightmaps.
  • Increase lightmap resolution (results may vary).
  • Move light source further away from the lit surface.
Warning.pngWarning: Models using $bumpmap cannot receive lightmaps, they will fall back to vertex-lighting based upon the models' origin or $illumposition.{{Codenote}} is deprecated. Use {{code note}} instead.

See also

  • $detailblendmode 8 - Can be used on the UnlitGeneric shader to simulate lightmaps in all Source engine branches (will be darker; the lightmap VTF's gamma must be doubled linearly).
  • Modulate - A shader that can be used to fake lightmaps or vertex coloring in all Source engine branches. It can bypass some of the limitations of $lightmap, but requires additional setup to look convincing.
Note.pngNote: Simulated lightmaps using these methods will be darker in-game than native lightmaps; the lightmap VTF's gamma must be doubled.
Confirm.pngConfirm: Doubled in Linear or sRGB space?


1. These features were implemented following garrysmod-requests issue #2464.