This article's documentation is for anything that uses the Source engine. Click here for more information.

Env cascade light: Difference between revisions

From Valve Developer Community
Jump to navigation Jump to search
(oops)
 
(8 intermediate revisions by the same user not shown)
Line 1: Line 1:
{{LanguageBar}}
{{LanguageBar}}
{{This is a|logical entity|name=env_cascade_light|since=Counter-Strike: Global Offensive|notext=1}}{{also|{{Xe}}}}
{{tabsBar|main=env_cascade_light}}
{{This is a|logical entity|name=env_cascade_light|since=Counter-Strike: Global Offensive|notext=1}}
{{CD|CCascadeLight}}
{{CD|CCascadeLight}}
[[File:CSM Example.jpg|thumb|CSM in {{csgo|4.1}}]]
[[File:CSM Example.jpg|thumb|CSM in {{csgo|4.1}}]]
[[File:Env_cascade_light_-_BMS_CSM_comparison.gif|thumb|Comparison of CSM and without CSM in {{bms|3.1}} ([https://developer.valvesoftware.com/w/images/archive/5/58/20240908185746%21Env_cascade_light_-_BMS_CSM_comparison.gif Click here for full-res version])]]
It casts an extremely accurate shadow map via the <code>tools/tools[[skybox]]</code> texture, augmenting the lighting cast by {{ent|light_environment}} with real-time shadows. This form of shadow mapping is known as '''[https://learn.microsoft.com/en-us/windows/win32/dxtecharts/cascaded-shadow-maps Cascaded Shadow Maps]''', or '''CSM''' for short, which works by rendering very detailed shadow maps which becomes a lower and lower resolution depending on the distance the viewer is from the surface, similar to [[mipmaps]]. Some games automatically add this entity to the map, but it can be placed manually as well.
It casts an extremely accurate shadow map via the <code>tools/tools[[skybox]]</code> texture, augmenting the lighting cast by {{ent|light_environment}} with real-time shadows. This form of shadow mapping is known as '''[https://learn.microsoft.com/en-us/windows/win32/dxtecharts/cascaded-shadow-maps Cascaded Shadow Maps]''', or '''CSM''' for short, which works by rendering very detailed shadow maps which becomes a lower and lower resolution depending on the distance the viewer is from the surface, similar to [[mipmaps]]. Some games automatically add this entity to the map, but it can be placed manually as well.


{{Note|Although you can toggle this entity, you can have only one {{ent|env_cascade_light}} present in your level. Any others will not work.}}
{{important|
{{bug|
* You still need to have a {{ent|light_environment}} in your map as well to create [[lightmap]] based lighting, which is not done by this entity. CSM relies upon a fifth channel <!--first 4 channels are RGB and exponent, even in non-HDR mode--> in the lightmap to mask dark and light areas.
* In {{insurgency}}, shadows will be very faint if the map hasn't been compiled with [[HDR]].
* If this entity is missing from your map, the CSM will still be created automatically!
* In {{insurgency}}, [[Naming Lights|Lightstyles]] will break when this entity exists.|hidetested=1}}
:{{note|In {{jb3}}, this will only occur if both {{ent|env_cascade_light}} and {{ent|shadow_control}} are missing, and the BSP contains lightmap alpha. {{confirm|{{strata}} probably works similarly.}} }}
 
}}
{{note|
{{note|Although you can toggle this entity, you can have only one {{ent|env_cascade_light}} present in your level. Any others will not work.}}
* You still need to have a {{ent|light_environment}} in your map as well to create [[lightmap]] based lighting, which is not done by this entity.
{{codenote|
* {{src13|4}} doesn't have this entity, but there is an [https://github.com/celisej567/Fake-CSM-Mapbase attempt] of porting it.
* {{src13|4}} doesn't have this entity, but there is an [https://github.com/celisej567/Fake-CSM-Mapbase attempt] of simulating it.  
* {{asd|4}}'s counterpart to this entity is {{ent|Light_deferred_global}}{{also|{{lw}}}}
* {{asd|4}}'s counterpart to this entity is {{ent|Light_deferred_global}}{{also|{{lw}}}}
* You alternatively can [[Implementing_Deferred_lighting_into_Source_2013|implement]] {{lw|4}}'s Deferred lighting as it is the most robust implementation currently being available to the public.
* You alternatively can [[Implementing_Deferred_lighting_into_Source_2013|implement]] {{lw|4}}'s Deferred lighting as it is the most robust implementation currently being available to the public.
}}
}}
{{important|
{{bug|
* {{Xe|4}}'s implementation requires the <code>-CascadeShadows</code> and <code>-StaticPropLighting3</code> parameters in [[VRAD]] for CSM to work correctly.
* In {{insurgency}}, shadows will be very faint if the map hasn't been compiled with [[HDR]].
* Due to lighting changes in {{Xe|4}}, this entity has many additional parameters.}}
* In {{insurgency}}, [[lightstyle]]s will break when this entity exists.|hidetested=1}}


==Keyvalues==
==Keyvalues==
{{KV Targetname}}
{{KV Targetname}}
{{KV|Light Color|intn=color|color255|This is the color of the sunlight. For {{csgo|4}}, the color is automatically copied from the {{ent|light_environment}}.
{{KV|Light Color|intn=color|color255|This is the color of the sunlight. For {{csgo|4}}, the color is automatically copied from the {{ent|light_environment}}.}}
{{bug|In {{bms|4}}, do not use a color value that differs from what is written in ''light_environment'' entity, otherwise the cascade light will not work properly.|hidetested=1
}}
}}
{{KV|Max shadow distance|intn=maxshadowdistance|float|Maximum dynamic shadow distance. Higher values are slower, default on PC is 400 units.}}
{{KV|Max shadow distance|intn=maxshadowdistance|float|Maximum dynamic shadow distance. Higher values are slower, default on PC is 400 units.}}
{{KV|Use light_environment's angles|intn=uselightenvangles|bool|If true, the CSM shadow angles are automatically taken from a {{ent|light_environment}}'s angles. If false, this entity's '''Pitch Yaw Roll''' is used.}}
{{KV|Use light_environment's angles|intn=uselightenvangles|bool|If true, the CSM shadow angles are automatically taken from a {{ent|light_environment}}'s angles. If false, this entity's angles is used.}}
{{KV|LightRadius1|to=LightRadius3|intn=LightRadius1|float|Used for controlling shadow softness in cascades 1, 2, and 3.|only={{Xe}}}}
{{KV Angles}}
{{KV|Depthbias1|to=Depthbias3|intn=Depthbias1|float|DepthBias for cascades 1, 2, and 3.|only={{Xe}}}}
{{KV StartDisabled}}
{{KV|Slopescaledepthbias1|to=Slopescaledepthbias3|intn=Slopescaledepthbias1|float|Slope DepthBias for cascades 1, 2, and 3.|only={{Xe}}}}
:{{bug|hidetested=1|Non-functional in {{csgo}}. Fixed in {{jb3}}.}}
{{KV|ViewModelDepthbias|intn=ViewModelDepthbias|float|DepthBias for viewmodel cascade.|only={{Xe}}}}
{{KV|ViewModelSlopescaledepthbias|intn=ViewModelSlopescaledepthbias|float|DepthBias for viewmodel cascade.|only={{Xe}}}}
{{KV|CSM_Volume_Mode|intn=CSMVolumeMode|choices|Use Manual mode for better performance.|only={{Xe}}|}}
:*0: Auto: Static cache will update once every 10 frames (approx) covering max shadow distance or whole map around player.
:*1: Manual : Static cache area coverage and updates are managed via Cascade Shadow Mapping Volumes.
{{KV EnableDisable}}


==Inputs==
==Inputs==
{{I|SetAngles|Sets the direction shadows cast in.|param=string}}
{{I|SetAngles|Sets the direction shadows cast in.|param=string}}
:{{note|Affects nothing.}}
:{{bug|Affects nothing.}}
{{I|LightColor|Changes color of the sunlight.|param=color255}}
{{I|LightColor|Changes color of the sunlight.|param=color255}}
<dd>{{bug|Doesn't work as expected. With {{csgo|4}}'s implementation, the color only changes on static props, not on world geometry or dynamic objects. It only changes the shadow color (only in world geometry, not in models), with no change upon reloading the game. With {{Xe|4}}'s implementation, the only thing you can do is change shadows color to turquoise and change the intensity of these shadows, however this doesn't effects shadows on the [[viewmodel]].
<dd>{{bug|Doesn't work as expected. The color only changes on static props, not on world geometry or dynamic objects. It only changes the shadow color (only in world geometry, not in models), with no change upon reloading the game.  
{{expand|title=Examples|noborder=1|1=
{{expand|title=Examples|noborder=1|1=
{{p2ce|4.1}} uses {{csgo|4.1}}'s implementation of CSM
{{p2ce|4.1}} uses {{csgo|4.1}}'s implementation of CSM
{{csgo|2}} ({{p2ce|2}}):
<br>
<br>
<gallery mode=nolines widths=320px heights=250px>
<gallery mode=nolines widths=320px heights=250px>
Line 52: Line 42:
File:afterCSMLC.jpg|After <code>ent_fire env_cascade_light lightcolor 255 0 0 255</code>.  
File:afterCSMLC.jpg|After <code>ent_fire env_cascade_light lightcolor 255 0 0 255</code>.  
</gallery>
</gallery>
{{Xe|2}}:
}}|tested={{p2ce}}}}</dd>
<gallery mode=nolines widths=320px heights=250px>
File:beforeBMS,jpg.jpg|Before <code>ent_fire env_cascade_light lightcolor 255 0 0 255</code>.
File:afterBMS.jpg|After <code>ent_fire env_cascade_light lightcolor 255 0 0 255</code>.
</gallery>
}}|tested={{p2ce}}{{bms}}}}</dd>
{{I|LightColorScale|Boosts the color of the sunlight. Non-functional, only resets the Light Color.|nofgd=1|deprecated=1}}
{{I|LightColorScale|Boosts the color of the sunlight. Non-functional, only resets the Light Color.|nofgd=1|deprecated=1}}
:{{bug|Affects nothing in {{Xe|4}}.|hidetested=1}}
{{I EnableDisable}}
{{I|SetCSMVolume|Set CSM Volume via trigger volume.|only={{Xe}}}}
:{{bug|Doesnt work correctly in {{CSGO}}; cascade light must be [[kill]]ed instead. Fixed in {{jb3}}.}}
{{I|SetCSMVolumeToSceneBounds|Set CSM Volume to scene bounds.|only={{Xe}}}}
{{I|SetCSMVolumeViaCSMVolumeEntity|param=targetname|Set CSM Volume to CSM Volume Entity.|only={{Xe}}}}
{{I|Disable|param=void|Disable this entity.}}
:{{note|Only in {{Xe|4}} work as expected. {{csgo|4}}'s implementation only disable blobby shadows and lighting in [[viewmodel]], also cause freeze for some seconds.}}
{{I|Enable|param=void|Enable this entity.}}
:{{note|Only in {{Xe|4}} work as expected. {{csgo|4}}'s implementation only enable blobby shadows and lighting in [[viewmodel]], also cause freeze for some seconds.}}
 
==Cascade Shadow Mapping Volumes==
{{bms|2}} provides very powerful optimization feature, called Cascade Shadow Mapping Volumes (CSM volumes for short). Initially, there were 2 different modes for rendering shadow maps for static cascade, which type to use - determines the value from the property, the property is '''CSM_Volume_Mode'''. CSM volumes allow you to automatically limit rendering of cascade shadows, swap areas there you want to have static cascade shadows (this is cascade shadows from static props with world geometry (brush entities as well) and also change value for '''Max shadow distance''' property.
 
'''CSM_Volume_Mode''' property can have 2 different values:
 
*Auto - you will not be able to swap areas there you want to have static cascade shadows, value from '''Max shadow distance''' property never changes, static cascade shadows will also disappear with dynamic cascade shadows. Good enough if map isn't very open space or if it's not too big.
 
*Manual - static cascade shadows rendering areas depends on values from the inputs, value from '''Max shadow distance''' property also depends on values from the inputs. This allows you to save many FPS for maps with big open space areas (especially for [[Xen]] levels).
 
There are 3 different inputs for this feature, which create 3 different ways to use CSM volumes.
 
The first input is '''SetCSMVolume'''. This input changes CSM volume and sets min and max bounds via {{ent|trigger_csm_volume}} entity. The size of {{ent|trigger_csm_volume}} entity decides the size of the world or level to be rendered into CSM shadow maps. To use it, specify the area in which you want to set CSM volume via {{ent|trigger_csm_volume}} entity (also works with {{ent|trigger_multiple}} and other triggers for some reason). In {{ent|trigger_csm_volume}} make the following output:
 
<gallery mode=nolines widths=320px heights=250px>
File:csmvol1.jpg|An example (instead of <code>cascade</code> there should be your {{ent|env_cascade_light}} name).
</gallery>
 
In this way, static cascade shadows will not appear outside of min and max bounds.
 
<gallery mode=nolines widths=320px heights=250px>
File:csmvolg1.jpg|Example with console message about min and max bounds (this appear when you touch such CSM volume). Note that we have static cascade shadows in this area.
File:csmvolg2.jpg|Example in room that is outside of the bounds. Note that we don't have have static cascade shadows in this area.
</gallery>
 
The second input is '''SetCSMVolumeToSceneBounds'''. It resets CSM volume to scene bounds. To use it, use the steps from the previous way, but replace '''SetCSMVolume''' input with '''SetCSMVolumeToSceneBounds''' input.
 
In this way, static cascade shadows never disappear, but dynamic still disappear.
<gallery mode=nolines widths=320px heights=250px>
File:csmvolgScene.jpg|Example with console message about CSM volume reset (this appear when you touch such CSM volume). Note that we have static cascade shadows (from the tree and world geometry in this case), but we don't have dynamic cascade shadows (from the crate and the ropes in this case).
</gallery>
 
 
The third input and the last way is '''SetCSMVolumeViaCSMVolumeEntity'''. It does the same thing that does '''SetCSMVolume''', but instead of {{ent|trigger_csm_volume}} you are using {{ent|env_cascade_volume}} entity. This way is deprecated, but still can be used in some very rare cases. {{ent|env_cascade_volume}} is disabled in original [[FGD]], you need to open <code>base.cfg</code>, find line <code>3169</code> and uncomment the code (or just use [https://github.com/MyGamepedia/Enhanced-Black-Mesa-FGD Enhanced Black Mesa FGD]). The next step is to place the entity, give a name and set values for '''RadiusX''', '''RadiusY''' and '''RadiusZ''' properties. What values to set to have required results ? Image that the entity position is brush center, and the values for the properties is the values what you see in 2D {{hammer|4}} window while some brush entity is selected. The last step is to add output for entity that will set CSM volume in this way, this can be trigger or any other entity. '''SetCSMVolumeViaCSMVolumeEntity''' requires parameter to work, the parameter is the name of {{ent|env_cascade_volume}} which we set up early.
<gallery mode=nolines widths=320px heights=250px>
File:csmvolent.jpg|An example.
</gallery>
In this way, we get results that are identical to the result from '''SetCSMVolume''' input.
 
 
{{important|All these features are fully disabled with ridiculous value for setting '''Sun Shadow Quality''' ({{command|cl_csm_qualitymode|4}}).}}
{{bug|All these features doesn't work properly in multiplayer.|hidetested=1}}


== See also ==
== See also ==
* {{ent|trigger_csm_volume}} - cascade volume brush entity
* {{ent|env_cascade_volume}} - cascade volume point entity
* {{ent|light_environment}} - baked static sunlight
* {{ent|light_environment}} - baked static sunlight
* {{ent|Shadow_control}} - dynamic shadows
* {{ent|Shadow_control}} - dynamic shadows
Line 120: Line 55:
* [[Advanced Lighting]]
* [[Advanced Lighting]]
* [[Effect flags]] (dynamic light effects)
* [[Effect flags]] (dynamic light effects)
* {{ent|newLight_Dir}} - directional sun light with godrays only
* {{ent|newLight_Point}} - point deferred light entity
* {{ent|newLight_Spot}} - spot deferred light entity
* {{ent|NewLights_settings}} - entity that changes deferred light settings
* [[New Specular]] - specular shader for new lights
* {{ent|light_deferred}} - deferred light
* {{ent|light_deferred_global}} - deferred global light
== External links ==
* [https://drive.google.com/file/d/1BEEXsHwpL6iHuzZvbYEeOuRuuSqpEHHh/view?usp=drive_link Example of CSM volumes (all 3 ways) in test map]
* [https://chetanjags.wordpress.com/2023/07/17/blackmesa-xenengine-part3-csm-2-0/ BlackMesa XenEngine: Part3 – CSM 2.0] (page from Black Mesa developer about their own CSM implementation)
* [https://chetanjags.wordpress.com/2023/07/11/blackmesa-xenengine-part2-how-a-frame-is-rendered/ BlackMesa XenEngine: Part2 – How a Frame is Rendered] (page from Black Mesa developer about new graphics features)
* [https://chetanjags.wordpress.com/2022/06/01/blackmesa-xenengine-part1-a-heavily-modified-source-engine/ BlackMesa XenEngine: Part1 – Heavily Modified Source Engine] (page from Black Mesa developer about Black Mesa engine, better known as [[Xengine]])


[[Category:Lighting]]
[[Category:Lighting]]

Latest revision as of 17:24, 3 December 2025

English (en)Translate (Translate)
Edit Tabs

env_cascade_light is a logical entity available in all Source Source games since Counter-Strike: Global Offensive Counter-Strike: Global Offensive.

C++ Class hierarchy
CCascadeLight
↳CBaseEntity
CSM in Counter-Strike: Global Offensive Counter-Strike: Global Offensive

It casts an extremely accurate shadow map via the tools/toolsskybox texture, augmenting the lighting cast by light_environment with real-time shadows. This form of shadow mapping is known as Cascaded Shadow Maps, or CSM for short, which works by rendering very detailed shadow maps which becomes a lower and lower resolution depending on the distance the viewer is from the surface, similar to mipmaps. Some games automatically add this entity to the map, but it can be placed manually as well.

Icon-Important.pngImportant:
  • You still need to have a light_environment in your map as well to create lightmap based lighting, which is not done by this entity. CSM relies upon a fifth channel in the lightmap to mask dark and light areas.
  • If this entity is missing from your map, the CSM will still be created automatically!
Note.pngNote:In Jabroni Brawl: Episode 3, this will only occur if both env_cascade_light and shadow_control are missing, and the BSP contains lightmap alpha.
Confirm:Strata Source probably works similarly.
Note.pngNote:Although you can toggle this entity, you can have only one env_cascade_light present in your level. Any others will not work.
Cpp.pngCode:
Icon-Bug.pngBug:
  • In Insurgency, shadows will be very faint if the map hasn't been compiled with HDR.
  • In Insurgency, lightstyles will break when this entity exists.

Keyvalues

Name (targetname) <string>
The name that other entities refer to this entity by, via Inputs/Outputs or other keyvalues (e.g. parentname or target).
Also displayed in Hammer's 2D views and Entity Report.
See also: Generic Keyvalues, Inputs and Outputs available to all entities
Light Color (color) <color255>
This is the color of the sunlight. For Counter-Strike: Global Offensive Counter-Strike: Global Offensive, the color is automatically copied from the light_environment.
Max shadow distance (maxshadowdistance) <float>
Maximum dynamic shadow distance. Higher values are slower, default on PC is 400 units.
Use light_environment's angles (uselightenvangles) <boolean>
If true, the CSM shadow angles are automatically taken from a light_environment's angles. If false, this entity's angles is used.
Pitch Yaw Roll (Y Z X) (angles) <QAngle>
This entity's orientation in the world. Pitch is rotation around the Y axis, yaw is the rotation around the Z axis, roll is the rotation around the X axis.
Start Disabled (StartDisabled) <boolean>
Stay dormant until activated (with theEnableinput).
Icon-Bug.pngBug:Non-functional in Counter-Strike: Global Offensive. Fixed in Jabroni Brawl: Episode 3.

Inputs

SetAngles <stringRedirectInput/string>
Sets the direction shadows cast in.
Icon-Bug.pngBug:Affects nothing.  [todo tested in ?]
LightColor <color255RedirectInput/color32>
Changes color of the sunlight.
Icon-Bug.pngBug:Doesn't work as expected. The color only changes on static props, not on world geometry or dynamic objects. It only changes the shadow color (only in world geometry, not in models), with no change upon reloading the game.
Examples
Portal 2: Community Edition Portal 2: Community Edition uses Counter-Strike: Global Offensive Counter-Strike: Global Offensive's implementation of CSM


  • Before ent_fire env_cascade_light lightcolor 255 0 0 255.

    Before ent_fire env_cascade_light lightcolor 255 0 0 255.

  • After ent_fire env_cascade_light lightcolor 255 0 0 255.

    After ent_fire env_cascade_light lightcolor 255 0 0 255.

  (tested in: Portal 2: Community Edition)
LightColorScale  !FGD Obsolete
Deprecated.
Boosts the color of the sunlight. Non-functional, only resets the Light Color.

EnableDisable:

Enable / Disable
Enable/disable this entity from performing its task. It might also disappear from view.
Icon-Bug.pngBug:Doesnt work correctly in Counter-Strike: Global Offensive; cascade light must be killed instead. Fixed in Jabroni Brawl: Episode 3.  [todo tested in ?]

See also

Retrieved from "https://developer.valvesoftware.com/w/index.php?title=Env_cascade_light&oldid=493813"