$envmap

From Valve Developer Community
Jump to: navigation, search
English (en)中文 (zh)
Edit
Specular reflections at full intensity.
For the set of material parameters used to mask specular reflections via textures, see $envmapmask.

$envmap is a material shader parameter available in all Source Source games. It most commonly used to approximate the specular reflections seen on smooth surfaces, such as metals and plastics. This is achieved by mapping the vertex normals of a model to positions on a cubemap - specified by $envmap - and adding the sampled color from the cubemap to the model's surface. Typically, the cubemap is a simple, static "environment map" which has been pre-rendered (although a custom cubemap can be animated).

When $envmap is set to env_cubemap and buildcubemaps has been run on the map, the engine will automatically select the environment map contained in the BSP which is nearest to the model as it moves through the world, providing a very rough approximation of dynamic reflections.

The other form of specularity supported by Source is the Phong type, which provides simpler reflections on both static and dynamic models.

Availability

$envmap was introduced in Source Source with Half-Life 2 and Counter-Strike: Source. It is available in all subsequent games.

Icon-Bug.pngBug:Half-Life: Source The latest Source engine version (v24) of Half-Life: Source does support $envmap if it uses an env_cubemap, but the buildcubemaps command does not work properly. If the cubemaps are built in another game and then the BSP is added into HL:S, they will work fine. Is not clear if in older versions there were more issues; but, due such problems, Valve used static reflective images for every reflective texture in the game.

Syntax

$envmap env_cubemap

"env_cubemap" is typically used, which tells VBSP to swap in the name of the nearest env_cubemap when the map compiles. However, it is also possible to use a static cubemap image that has been manually created.

Note.pngNote:If $envmap is used without specifying $basetexture, the specular reflections will be force drawn regardless of anything.
Note.pngNote:Most Cubemap textures will have no reflectivity when used as overlays or decals. It is unclear why this is so[Clarify].
Note.pngNote:Cubemap transparency is affected by the $basetexture alpha/transparency map even when using $envmapmask. This causes conflicting problems.

Creating a custom static cubemap texture

Creating a custom cubemap texture might be required for some circumstances and is used occasionally in some Valve models.

Icon-Bug.pngBug:(this works in LUX) Cubemaps flagged as sRGB will only properly load as sRGB when HDR is disabled. Either include an HDR .hdr.vtf equivalent for an sRGB-encoded SDR .vtf cubemap, or encode the SDR cubemap in regular RGB.
Confirm.pngConfirm: What games can actually load SDR cubemaps in HDR mode? Counter-Strike: Source handles such fine (printing warnings about missing a proper HDR cubemap in the console), but Day of Defeat: Source seems not be able to load SDR cubemaps in HDR mode (regardless of sRGB-ness), resulting in the surface glowing white.

In VTFEdit

For this to work you will need to have the 6 sides of the cubemap saved as individual textures in the correct orientation for it to appear correctly in the Source Engine. So some faces might need to be rotated either clockwise or counter clockwise. Each face will need to be mirrored horizontally before orientation.

Note.pngNote:Pre-Alien Swarm Alien Swarm games require 7 faces for the cubemap to work. The seventh in this case is a round texture, used as a sphere map for the (broken) $envmapsphere parameter. VTFEdit can generate this face automatically, via the "Advanced" tab when importing.

To the right hand side of this page you will find two guide images to aid in properly rotating each side of your environment render.
Save one or both of those guides on your computer and then import your environment render onto it or recreate it in a smaller scale, then rotate your sides as instructed by the images.
Save every side as a separate image file, their names should be the number found on that specific square. This will ensure that the environment texture will be built correctly, as the numbers also represent the import order in VTFEdit.

Orientation guide for T-assembled environments. Click to enlarge
Orientation guide for Blender render results. Click to enlarge

Once you have all the image sides ready you can just import them all into VTFEdit and select "Environment Map". Texture format is up to you, generally DXT1 will do.

Cubemap tut1 cra0.png

Enable the "Clamp S" and "Clamp T" texture flags.

Then just save it all as a .vtf file and use it in your VMT like so:

"$Envmap" "effects/my_cubemap"

"effects" is the usual folder for environments/cubemaps You may put yours anywhere you like

In VTEX

VTEX will automatically mirror and orient your faces, you need only to provide correctly named textures. Name each file something like envmap001a*.tga, where * is put BK, FT, LF, RT, UP, or DN. If you took a cubemap screenshot in-game, this step will already by done, but to make them work properly with Vtex.exe you must use HDRShop (but before you need to change textures format to BMP, because HDRShop can only work with that kind of format) and then covert them to PFM files format.

Blank image.pngTodo: What axis does each direction relate to?

Cubemap axis reference 1.jpg

Create a text file the same name as your textures (e.g. envmap001a.txt). If building for HDR write in the following, otherwise leave it blank:

pfm 1 // read .pfm file instead of .tga
pfmscale 1 // higher values will result in a brighter sky
nocompress 1 // disable compression (HDR compression is only supported by skyboxes)

Put these files into materialsrc and then just drag-n-drop .txt file into vtex.exe and you should end up with a working cubemap! HDR envmaps will be named like envmap001a.hdr.vtf, and only need to exist to work.

Parameters and Effects

See $envmapmask. A texture file that determines per-texel reflection intensity.

Controls the intensity of the reflection's red, green and blue color channels. Any positive number can be used. Default is "[1 1 1]", which means 100% intensity.
Icon-Important.pngImportant: On VertexLitGeneric this parameter is being converted from gamma to linear. The input will turn into X^2.2f. For Example, 0.25 is not 25% reflectivity, it's actually ~5%!
Note.pngNote:You must use quotemarks, as there are space characters within the value.
Note.pngNote:You can also define the value as a single float, in which case it should equally apply to all three channels (e. g. $envmaptint 0.5 will equate to $envmaptint "[0.5 0.5 0.5]"). In this case you won't need the quotemarks. However, this method appears to not be 100% reliable.[confirm]
Tip.pngTip:This command is often used to dim the brightness of a specular reflection without the overhead of an $envmapmask.

Controls the contrast of the reflection. 0 is natural contrast, while 1 is the full squaring of the color (i.e. color*color).
Note.pngNote:Will not work when Phong is enabled.
Tip.pngTip:Use higher contrasts to diminish relatively darker areas and increase "hot spots".

Controls the color saturation of the reflection. 0 is greyscale, while 1 is natural saturation. R, G and B can be de/oversaturated respectively using "[r g b]"
Note.pngNote:In the Shadercode for Source 2013 Source 2013 and Alien Swarm Alien Swarm the parameter is defined as a float parameter. However it will be used as a vec3 and the Shader expects and uses it as such.
Note.pngNote:Will not work when Phong is enabled on models.
Icon-Bug.pngBug:Counter-Strike: Source Works only on models.
Confirm.pngConfirm: Does this bug exist in other Source 2013 Multiplayer games using stock shaders? (ex: Half-Life 2: Deathmatch Half-Life Deathmatch: Source Day of Defeat: Source Team Fortress 2)

The frame to start an animated cubemap on.

Depreciated MATERIAL_VAR_ENVMAPMODE = (1 << 25), // OBSOLETE

$basetexturenoenvmap and $basetexture2noenvmap <boolean> (DX9+) (removed since Counter-Strike: Global Offensive)
Shader(s): WorldVertexTransition
Used for materials with two albedos, to make one or the other matte. See also $basetexture and $basetexture2.
Note.pngNote:Superseded in Counter-Strike: Global Offensive by $envmapmask2.

$envmapoptional <choices> (removed since Left 4 Dead)
Sets the oldest DirectX version that should draw the reflection. Choose from:
  • 80 (DirectX 8)
  • 81 (DirectX 8.1)
  • 90 (DirectX 9)
  • 95 (DirectX 9 with Shader Model 3)

$envmapsphere <boolean> Obsolete (also in Garry's Mod) (removed since Alien Swarm)
Determines whether the material's envmap should be a spheremap (using matcap shading like GoldSrc "chrome" textures) instead of a cubemap. Set this to 1 to use a spheremap.
Icon-Bug.pngBug:In DirectX 9 mode, this will instead act like a regular cubemap with all 6 faces being identical.

$noenvmapmip <boolean> (only in Counter-Strike: Global Offensive)
Shader(s): LightmappedGeneric
Only use the top-level mipmap of the cubemap.
A vent without and with reflection tinting. The bottom image lists the material parameters used to create the effect.

$fresnelreflection <float> (in all games since Source 2006)
Shader(s): LightmappedGeneric, Lightmapped_4WayBlend, WorldVertexTransition
Adds a Fresnel effect to the reflection. 0 is none, while 1 applies the full effect, similar to Water. The effect becomes multiplied with values higher than 1.
Icon-Bug.pngBug:Value behaves inverted in Black Mesa, 0 applies the full effect, while 1 is none.

$envmapfresnel <float> (DX9+) (in all games since Source 2007)
Shader(s): VertexLitGeneric
The same as $fresnelreflection, but for VertexLitGeneric. By default, this will use the fresnel ranges set by $phongfresnelranges.
Note.pngNote:Only works with Phong enabled before Left 4 Dead.
An in-game example of anisotropic reflections, with $envmapanisotropyscale set to 1.

$envmapfresnelminmaxexp <vector> (in all games since Left 4 Dead)
Shader(s): VertexLitGeneric
Sets fresnel ranges for VertexLitGeneric materials using $envmapfresnel without phong. By default "[0 1 2]", making surfaces facing the viewer less reflective than surfaces facing sideways.
Note.pngNote:The fresnel values for this parameter are not the same as those for $phongfresnelranges.Instead, the first value is the minimum amount of fresnel, the second value is the maximum, and the final value is exponent.
Icon-Bug.pngBug:Cannot be used with $bumpmap. $phongfresnelranges must be used instead.

$envmaplightscale <float> (in all games since Alien Swarm) (also in Garry's Mod)
Shader(s): LightmappedGeneric, Lightmapped_4WayBlend Counter-Strike: Global Offensive, VertexLitGeneric Counter-Strike: Global Offensive, WorldVertexTransition Counter-Strike: Global Offensive
Tint the surface's specular reflection with its lightmap. This matches a surface's reflection with its diffuse lighting and acts as rudimentary reflection occlusion. With a value of 1, a surface will have no reflection if it isn't lit at all. For models in Counter-Strike: Global Offensive, vertex lighting is used for the tinting instead of a lightmap.
Note.pngNote:Values above 1 for this parameter are technically permitted, but start inverting the effect.

$envmaplightscaleminmax <vector2> (only in Counter-Strike: Global Offensive) (also in Garry's Mod)
Shader(s): LightmappedGeneric, Lightmapped_4WayBlend, VertexLitGeneric, WorldVertexTransition
Thresholds for the lightmap reflection tinting effect. Setting the minimum value higher increases the minimum light amount at which the reflection gets nerfed to nothing.

$envmapanisotropy <boolean> (only in Counter-Strike: Global Offensive)
Shader(s): LightmappedGeneric, Lightmapped_4WayBlend, WorldVertexTransition
Enables anisotropic reflection emulation by warping the reflection downwards.

For this it uses the alpha channel of the $bumpmap.
It linearly interpolates between a normal reflection vector and an anisotropic one.

This means that values of 0 in the alpha will result in normal reflections, and a value of 1 will result in anisotropic reflections.
Icon-Bug.pngBug:Does not work with $normalmapalphaenvmapmask
Icon-Bug.pngBug:Does not work with $basealphaenvmapmask except Lightmapped_4WayBlend
Note.pngNote:Requires a $bumpmap to be present.

Shader(s): LightmappedGeneric, Lightmapped_4WayBlend, WorldVertexTransition
Multiplier for how much the reflection should be warped.

Console commands

buildcubemaps
Generates cubemaps for use in materials. If this isn't run, objects will reflect the skybox (OB) or have an invalid reflection, white in Ep1 and pink checkerboards in MP.
envmap
Generates an environment map at the player's position and dumps it in cubemap_screenshots/, in six separate PFM files (or, if running without HDR, TGA files).
Tip.pngTip:Cubemaps created this way will capture dynamic entities and models in them, which are normally hidden when using buildcubemaps.
mat_envmaptgasize <integer>
Sets the resolution for the files created with envmap. Default value: 32
mat_fastspecular <boolean>
Quickly disable or enable specular rendering without reloading materials. This does not affect performance, only appearance. mat_specular must be used for proper performance testing.
Icon-Bug.pngBug:Doesn't work in some games.
Note.pngNote:Despite common misconception, setting this to 0 does not enable a "fancy specular" mode, it simply disables specular rendering entirely.
mat_specular <boolean>
Disable or enable specular reflections, unloading or loading the specular materials from memory. Default 1.
r_showenvcubemap <boolean>
Debug command to display cubemaps on all dynamic objects at full intensity. It was used to create the image at the start of this article.

See also