Version:

Icon of a magnifying glass.

IN THIS ARTICLE

Using CVARs to Configure Terrain and Cascade Shadow Maps

Using CVARs to Configure Terrain and Cascade Shadow Maps

You can use console variables (CVARs) in Amazon Lumberyard to configure terrain and cascade shadow maps (also known as gradient shadow maps, or GSMs). This topic provides a list of key shadow-related console variables and shows you how to save your changes to them. It also shows you how to learn about other related console variables.

Topics

The following table shows some of the console variables that configure shadows, gradient shadow maps, and related debug modes.

Console VariableTypeDescription
e_GsmCastFromTerrainintSpecifies that shadows are cast from terrain. Off by default.
e_GsmDepthBoundsDebugintShows bounding volumes related to gradient shadow maps.
e_GsmLodsNumintSpecifies the number of gradient shadow map levels of detail (LOD). Valid values: 0 to 7.
e_GsmRangefloatSize of the LOD 0 gradient shadow map area in meters. Default value: 3 meters
e_GsmRangeStepfloatSpecifies a step value to multiply the previous range by to determine the range of the next GSM LOD. To determine the step size, use the following guidelines: If e_GsmRange is 3, cascade 0 is 3m. If e_GsmRangeStep is 3, the following values result. [See the AWS documentation website for more details]
e_GsmStatsintWhen enabled, shows debug information about shadow cascades. 0 = Off (default) 1 = On
e_ObjShadowCastSpecintSpecifies that objects that have a shadow cast spec less than or equal to the specified value cast shadows. Default value: 4
e_ParticleShadowsNumGSMsintSpecifies the number of shadow GSMs that are used for particle shadows. Default value: 3
e_ParticlesShadowsintEnables shadows on particles. 0 = Off 1 = On (default) 2 = Force
e_ShadowsintActivates the drawing of shadows. 0 = Off 1 = On (default)
e_ShadowsBlendCascadesintSoftens the blend between shadow cascade regions. 0 = Off 1 = On (default)
e_ShadowsBlendCascadesValfloatSpecifies the width of the region across which two cascades blend. Default value: 0.75
e_ShadowsCascadesDebugintFor debugging purposes, draws each shadow cascade with a different color on screen. 0 = Off (default) 1 = On
e_ShadowsCastViewDistRatiofloatSpecifies the view distance ratio for shadow maps that cast from objects. Default value: 1
e_ShadowsCloudsintEnables shadows for clouds. 0 = Off 1 = On (default)
e_ShadowsConstBiasfloatSpecifies the shadow slope bias for shadow generation. The shadow bias is the distance from where the shadows are cast to where they can be received. Default value: 1
e_ShadowsConstBiasHQfloatSpecifies the shadow slope bias for shadow generation in high quality mode. When shadow mode is set to high quality, the value of e_ShadowsConstBiasHQ or e_ShadowsConstBias is used, whichever is smaller. Default value: 0.05
e_ShadowsDebugintDisplays a debug viewport for shadow maps. 0 = Off (default) 1 = On
e_ShadowsLodBiasFixedintSpecifies the number of LOD levels that simplify mesh for shadow map generation. Default value: 0
e_ShadowsMaxTexResintSets the maximum resolution of the shadow map. Typical values are 256 for faster performance, 512 for a balance of performance and quality, and 1024 for higher quality. Default value: 1024 Larger values can cause texture thrashing warnings. To compensate, increase the value of r_DynTexMaxSize.
e_ShadowsPoolSizeintUses the formula e_ShadowsPoolSize * e_ShadowsPoolSize to set the size of the shadow pool. The shadow pool is the texture atlas used for rendering shadows from individual light points. Depending on the quality required, each light uses a different sized portion of the shadow map.
e_ShadowsResScalefloatSpecifies the resolution scale for an individual shadow inside the shadow pool for use by point lights. Determines how much of the shadow pool atlas to use when rendering the shadows for a light entity. Default value: 4
e_ShadowsSlopeBiasfloatSpecifies the shadow slope bias. The shadow slope bias is the distance from where shadows are cast to where they can be received, scaled by the slope of the geometry. Default value: 1
e_ShadowsSlopeBiasHQfloatSpecifies the shadow slope bias in high quality mode. When shadow mode is set to high quality, the value of e_ShadowsSlopeBiasHQ or e_ShadowsSlopeBias is used, whichever is smaller. Default value: 0.25
e_ShadowsTessellateCascadesintSpecifies the maximum cascade number to render tessellated shadows. In cascades higher than the specified value, objects render shadows without tessellation. Default value: 1 Use this console variable to optimize performance.
e_ShadowsTessellateDLightsintEnables or disables tessellation for shadows cast by local lights. 0 = Off (default) 1 = On
e_ShadowsUpdateViewDistRatiointSpecifies the view distance ratio for shadow maps that update for the shadow pool. Default: 256
e-ShadowsOnAlphaBlendintEnables shadows on alpha blend. 0 = Off (default) 1 = On
r_DrawNearShadowsintEnables shadows for near objects. 0 = Off 1 = On (default)
r_DynTexMaxSizeintSpecifies the maximum dynamic texture size. Use in conjunction with e_ShadowsMaxTexRes. Default value: 80
r_FogShadowsintEnables deferred volumetric fog shadows. 0 = Off 1 = Standard resolution (default) 2 = Reduced resolution
r_fogShadowsWaterintEnables volumetric fog shadows for water volumes. 0 = Off 1 = On (default)
r_ShadowJitteringfloatSpecifies the shadow map jittering radius. Values set by this CVAR are overwritten by ToD animation as soon as the ToD changes. 0 = OffDefault value: 2.5
r_ShadowPoolMaxFramesintSpecifies the maximum number of frames during which a shadow can exist in the shadow pool. Default value: 0
r_ShadowPoolMaxTimeslicedUpdatesPerFrameintSpecifies the maximum number of time-sliced shadow pool updates that are allowed per frame. Default value: 0
r_ShadowsCacheintReplaces all sun cascades above the specfied value with a cached (static) shadow map. 0 = No cached shadows. 1 = Replace the first and following cascades. 2 = Replace the second and following cascades. […] Default value: 5
r_ShadowsCacheFormatintSpecifies the texture format for shadow cache. 0 = Use D32 texture format. 1 = Use D16 texture format. Default value: 1
r_ShadowsCacheResolutionsstringSpecifies the resolution of the shadow cache per cascade. Default value: 4214
r_ShadowsPCFilteringintSpecifies whether to use Percentage Closer Filtering (PCF) for shadows. 0 = Off 1 = On (default)
r_ShadowsScreenSpaceintSpecifies whether to include screen space tracing in shadow computations. Screen space tracing helps to reduce artifacts caused by limited shadow map resolution and biasing. Use in cutscenes for better shadows on character faces. 0 = Off (default) 1 = On This effect is applied only in the near range.
r_ShadowsUseClipVolume DUMPTODISKintSpecifies whether shadows use clip volume. 0 = Off 1 = On (default)
sys_spec_shadowsintA console variable group that applies settings to certain shadow variables to configure shadow quality. A higher value signifies higher quality. Valid values: 1 to 8 For information on the console variables included in this group and how their settings are affected, see sys_spec_shadows Console Variables.

sys_spec_shadows Console Variables

The following table shows the console variables in the sys_spec_shadows group. The columns show the value of each variable for the sys_spec_shadows settings of 1 through 8. The final column lists the default values.

sys_spec_shadows12345678Default
e_GsmLodsNum344445555
e_GsmRange333333333
e_ObjShadowCastSpec111112343
e_ParticlesShadows000001111
e_Shadows111111111
e_ShadowsBlendCascades000001111
e_ShadowsCastViewDistRatio0.80.80.80.80.81111
e_ShadowsClouds111111111
e_ShadowsLodBiasFixed111110000
e_ShadowsMaxTexRes5125125125125121024102410241024
e_ShadowsOnAlphaBlend000000000
e_ShadowsPoolSize102410241024102440964096409640964096
e_ShadowsResScale444444444
e_ShadowsTessellateCascades111111111
e_ShadowsTessellateDLights000000000
e_ShadowsUpdateViewDistRatio256256256256256256256256256
r_DrawNearShadows000011111
r_FogShadows000002212
r_FogShadowsWater000000010
r_ShadowJittering0000112.52.52.5
r_ShadowPoolMaxFrames30303030303030030
r_ShadowPoolMaxTimeslicedUpdatesPerFrame100100100100100100100100100
r_ShadowsCache444444454
r_ShadowsCacheFormat000011111
r_ShadowsCacheResolutions3162,21073162,21073162,21073162,21073162,21076324,42146324,421442146324,4214
r_ShadowsPCFiltering111111111
r_ShadowsUseClipVolume111111111

Saving Console Variable Changes

Changes that you make to CVARs within the console do not automatically save in your level or editing session. To save your changes, you can use configuration files or Lua script.

To save console variable changes

  • Do one of the following:

    • Edit and save one of the console variable configuration files. For more information, see Configuring Console Variables.

    • In a Lua script, use the following syntax to assign a value to the variable at startup:

      ConsoleRequestBus.Broadcast.ExecuteConsoleCommand('r_ConsoleVariable = Value')

You can use the Lumberyard Editor console window to search for additional shadow-related console variables.

To find additional shadow-related console variables

  1. In Lumberyard Editor, choose Tools, Console.

  2. In the console window, do one of the following to open the Console Variables search window.
    [Lumberyard Editor console window]

    1. Click the X icon next to the command entry area.

    2. Right-click the command entry area.

  3. In the Console Variables window, for Search, enter shadow or gsm.
    [Searching for console variables by keyword for shadow or gsm]

  4. To learn more about a console variable, pause your pointer on the variable name.

For more information about the using the Lumberyard Editor console, see Using the Console Window.