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
(Added info about CSM volumes (Black Mesa game feature). There were no documentation about this. I've spent many time and attempts to turn out what each thing does and how to use.)
(oops)
 
(46 intermediate revisions by 10 users not shown)
Line 1: Line 1:
{{langsp}}
{{LanguageBar}}
{{tabsBar|main=env_cascade_light}}
{{This is a|logical entity|name=env_cascade_light|since=Counter-Strike: Global Offensive|notext=1}}
{{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}} (Click if GIF is not playing)]]
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/[[skybox]]</code> texture, acting as a real-time variation of {{ent|light_environment}}. This form of lighting is known as [https://learn.microsoft.com/en-us/windows/win32/dxtecharts/cascaded-shadow-maps Cascaded Shadow Maps], or CSM, 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.


{{important|
{{important|
* {{Xe|4}}'s implementation requires <code>-CascadeShadows</code> and <code>-StaticPropLighting</code> parameters for [[VRAD]], this for CSM to work correctly.
* 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.
* Due to lighting changes in {{Xe|4}}, this entity has many additional parameters.}}
* If this entity is missing from your map, the CSM will still be created automatically!
 
:{{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.}} }}
{{bug|
}}
* Although you can toggle this entity, you can have only one {{ent|env_cascade_light}} in your level. Other will not work.
{{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.}}
* In {{insurgency}}, shadows will be very faint if the map hasn't been compiled with [[HDR]].
{{codenote|
* In {{insurgency}}, [[Naming Lights|Lightstyles]] will break when this entity exists.}}
* {{src13|4}} doesn't have this entity, but there is an [https://github.com/celisej567/Fake-CSM-Mapbase attempt] of simulating it.  
 
{{note|
* 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.
* {{src13|4}} doesn't have this entity, but there is an [https://github.com/celisej567/Fake-CSM-Source-2013 attempt] of porting 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.
}}
}}
 
{{bug|
 
* In {{insurgency}}, shadows will be very faint if the map hasn't been compiled with [[HDR]].
{{csgo}}{{xe}} Represented by class <code>CCascadeLight</code>.
* In {{insurgency}}, [[lightstyle]]s will break when this entity exists.|hidetested=1}}


==Keyvalues==
==Keyvalues==
{{KV|Light Color|intn=color|color255|This is the color of the sunlight. For {{csgo}}, the color is automatically copied from the light_environment.}}
{{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|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 quality and performance. In near future Auto mode will be removed from the game.|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 CSM Volumes' I/O.
{{KV EnableDisable}}
{{KV BaseEntity}}


==Inputs==
==Inputs==
{{IO|SetAngles|Sets the direction shadows cast in.|param=string}}
{{I|SetAngles|Sets the direction shadows cast in.|param=string}}
{{note|Effects nothing.}}
:{{bug|Affects nothing.}}
{{IO|LightColor|Changes color of the sunlight.|param=color255}}
{{I|LightColor|Changes color of the sunlight.|param=color255}}
{{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=
{{note|{{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=packed heights=250px>
<gallery mode=nolines widths=320px heights=250px>
File:beforeCSMLC.jpg| thumb | left |Before <code>ent_fire env_cascade_light lightcolor 255 0 0 255</code>.  
File:beforeCSMLC.jpg|Before <code>ent_fire env_cascade_light lightcolor 255 0 0 255</code>.  
File:afterCSMLC.jpg| thumb | left |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=packed heights=250px>
{{I|LightColorScale|Boosts the color of the sunlight. Non-functional, only resets the Light Color.|nofgd=1|deprecated=1}}
File:beforeBMS,jpg.jpg| thumb | left |Before <code>ent_fire env_cascade_light lightcolor 255 0 0 255</code>.
{{I EnableDisable}}
File:afterBMS.jpg| thumb | left |After <code>ent_fire env_cascade_light lightcolor 255 0 0 255</code>.
:{{bug|Doesnt work correctly in {{CSGO}}; cascade light must be [[kill]]ed instead. Fixed in {{jb3}}.}}
</gallery>
}}
}}
{{IO|LightColorScale|Boosts the color of the sunlight. Non-functional, only resets the Light Color.|nofgd=1|deprecated=1}}
{{bug|Effects nothing in {{Xe|4}}.}}
{{IO|SetCSMVolume|Set CSM Volume via trigger volume.|only={{Xe}}}}
{{IO|SetCSMVolumeToSceneBounds|Set CSM Volume to scene bounds.|only={{Xe}}}}
{{IO|SetCSMVolumeViaCSMVolumeEntity|param=targetname|Set CSM Volume to CSM Volume Entity.|only={{Xe}}}}
{{IO|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.}}
{{IO|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.}}
{{I BaseEntity}}
 
==Outputs==
{{O BaseEntity}}
 
==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 {{code|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
 
{{code|Max shadow distance}} property.
 


{{code|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 {{code|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 {{code|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 {{code|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:
{{entity-output-start}}
{{entity-output||OnStartTouch|NameOfEnvCascadeLight|SetCSMVolume||0.00|No|Instead of ''NameOfEnvCascadeLight'' use name of your env_cascade_light for which you want to set volume.}}
{{entity-output-end}}
<gallery mode=packed heights=700px>
File:csmvol1.jpg| thumb | left | 710px |An example.
</gallery>
In this way, static cascade shadows will not appear outside of min and max bounds.
<gallery mode=packed heights=400px>
File:csmvolg1.jpg| thumb | left | 710px |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| thumb | left | 710px |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 {{code|SetCSMVolumeToSceneBounds}}. It resets CSM volume to scene bounds. To use it, use the steps from the previous way, but replace {{code|SetCSMVolume}} input with {{code|SetCSMVolumeToSceneBounds}} input.
In this way, static cascade shadows never disappear, but dynamic still disappear.
<gallery mode=packed heights=600px>
File:csmvolgScene.jpg| thumb | left | 710px |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 {{code|SetCSMVolumeViaCSMVolumeEntity}}. It does the same thing that does {{code|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 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 {{code|RadiusX}}, {{code|RadiusY}} and {{code|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 is this they, this can be trigger or any other entity. {{code|SetCSMVolumeViaCSMVolumeEntity}} requires parameter to work, the parameter is the name of {{ent|env_cascade_volume}} which we set up early.
<gallery mode=packed heights=700px>
File:csmvolent.jpg| thumb | left | 710px |An example.
</gallery>
In this way, we get results that are identical to the result from {{code|SetCSMVolume}} input.
== See also ==
== See also ==
 
* {{ent|light_environment}} - baked static sunlight
* {{ent|light_environment}}
* {{ent|Shadow_control}} - dynamic shadows
* {{ent|Shadow_control}}
* {{ent|env_sun}} - glowing sun effect
* {{ent|env_sun}}
* [[Skybox Basics]]
* [[Skybox Basics]]
* [[Skybox lighting]]
* [[Skybox lighting]]
* [[Advanced Lighting]]
* [[Advanced Lighting]]
* [[Effect flags]] (dynamic light effects)
* [[Effect flags]] (dynamic light effects)
* {{ent|newLight_Dir}}
* {{ent|newLight_Point}}
* {{ent|newLight_Spot}}
* {{ent|NewLights_settings}}
* [[New_Specular]]
* {{ent|light_deferred}}
* {{ent|light_deferred_global}}


== External links ==
[[Category:Lighting]]
* [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]])

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"