diff --git a/docs/lighting/clustered/clustered_light_inspector.md b/docs/lighting/clustered/clustered_light_inspector.md new file mode 100644 index 000000000..bd1bea109 --- /dev/null +++ b/docs/lighting/clustered/clustered_light_inspector.md @@ -0,0 +1,33 @@ +--- +title: Clustered Light Inspector +weight: 30 +features: + - USE_CLUSTERED +--- +# Developer UI + +In P2CE, you can enable the developer UI using the `devui_toggle_menu` console command. Currently, it consists of 8 menus: Windows, Graphics, Profiler, Map, Scripting, Entity, Settings and Debug. + +Graphics menu is the one needed. Upon pressing, four more buttons appear: Fog Config, Clustered Light Inspector, CSM Config and Post Processing. You need to choose the **Clustered Light Inspector**. + +![Developer UI](images/devui3.png) + +## Clustered Light Inspector + +Clustered Light Inspector is a menu where you can control `light_rt` entities in real time in-game. There are various options that give almost a full control over the entity. You can control all the default light options, such as `Constant`, `Linear`, `Quadratic`, `0% Intencity Falloff`, `50% Intencity Falloff`, `Minimum Brightness Threshold`, `Override Radius` and `Light Scale`, as well as `Color` using the color palette, `Shadow Scale`, `Near Z`, light's `Pattern` and entity's position in the map. + +> [!TIP] +> Position bars are scrollable! + +There are additional debugging and finding options. "Show Light Bounds" is relevant for `light_rt` and shows bounds of the light as a sphere. "Show Light Cone" is relevant for `light_rt_spot` and shows bounds of the light spot. "Show Only in Radius" will only display clustered lights in a specified radius. + +* Top: Clustered Light Inspector +* Middle: Clustered Light Inspector with the selected light's properties tweaked +* Bottom: Clustered Light Inspector with the selected light's position edited using XYZ bars + +![Clustered Light Inspector](images/clustered_ui1.png) + +![Clustered Light Inspector](images/clustered_ui2.png) + +![Clustered Light Inspector](images/clustered_ui3.png) + diff --git a/docs/lighting/clustered/differences.md b/docs/lighting/clustered/differences.md deleted file mode 100644 index bce5256bf..000000000 --- a/docs/lighting/clustered/differences.md +++ /dev/null @@ -1,52 +0,0 @@ ---- -title: Real-time Light Entities -features: - - USE_CLUSTERED ---- -# _rt light entities -This page documents the new additions and differences between the new `light_rt` entites and the old `light` entities. For a more in-depth description of the different light types, visit the [Light Type Reference](light_type_reference) page. - -> [!TIP] -> You can adjust the Radius and 50% falloff keyvalues for the dynamic light types in-game in real time. Open the console and type `devui_toggle_menu`, then go to the Graphics tab and click "Clustered Light Inspector". - -## Light distance/falloff -Unlike the previous lights, which could have falloff defined by either Constant, Linear, Quadratic or 50% falloff and 0% falloff, clustered lights are instead defined by the "Radius" and "50 percent scale" values. The Radius Keyvalue defines the distance from the center of the entity that light is allowed to cast. At this distance, light will fade off to 1/256 brightness, essentially negligible. - -In the below and all following images, the white cube is set at 256 units away from the light, the orange cube is set 512 units away from the light, and the gray cube is set 768 units away from the light, while the white wall at the end is set 1024 units away from the light. Fully dynamic lights are used to demonstrate the affect these keyvalues have on direct lighting. -* Top: Radius is set to 256 -* Middle: Radius is set to 512 -* Bottom: Radius is set to 1024 - -![256 radius](images/point_256_50.jpg) - -![512 radius](images/point_512_50.jpg) - -![1024 radius](images/point_1024_50.jpg) - -The "50 percent scale" keyvalue defines where the light will fade to 50% brightness inside the radius. This KV will accept any decimal value between 0 and 1, but after about 0.53, it becomes nonfunctional. If set to 0, the light will default back to .50 -* Top: Light with a radius of 1024, 50% scale of 0.25 -* Middle: Light with a radius of 1024, 50% scale of 0.50 -* Bottom: Light with a radius of 1024, 50% scale of 0.75 - -![.25 scale](images/point_1024_25.jpg) - -![.50 scale](images/point_1024_50.jpg) - -![.75 scale](images/point_1024_75.jpg) - -### Hard Falloff -The Hard Falloff keyvalue defines the distance where light will fall to exactly 0%. This keyvalue only affects baked lights, and therefore only has an affect for Static and Specular light types, and the bounced lighting produced from Staic Bounce lights. -* Top: Specular light, Radius 786, Hard Falloff set to 0 -* Bottom: Specular light, Radius 786, Hard Falloff set to 825 - -![0 falloff](images/specular_falloff_1.jpg) - -![825 text](images/specular_falloff_2.jpg) - -This value can be used to control the intensity of bounced lighting created by Static Bounce lights as well, to a lesser degree. This does not affect the dynamic direct lighting, however. -* Top: Static Bounce light, Radius 786, Hard Falloff set to 0 -* Bottom: Static Bounce light, Radius 786, Hard Falloff set to 812 - -![0 falloff](images/staticb_falloff_1.jpg) - -![812 falloff](images/staticb_falloff_2.jpg) diff --git a/docs/lighting/clustered/images/basic_light1.png b/docs/lighting/clustered/images/basic_light1.png deleted file mode 100644 index e02437a68..000000000 Binary files a/docs/lighting/clustered/images/basic_light1.png and /dev/null differ diff --git a/docs/lighting/clustered/images/basic_light2.png b/docs/lighting/clustered/images/basic_light2.png deleted file mode 100644 index 1b0efd2e2..000000000 Binary files a/docs/lighting/clustered/images/basic_light2.png and /dev/null differ diff --git a/docs/lighting/clustered/images/clustered_ui1.png b/docs/lighting/clustered/images/clustered_ui1.png new file mode 100644 index 000000000..755b9afce Binary files /dev/null and b/docs/lighting/clustered/images/clustered_ui1.png differ diff --git a/docs/lighting/clustered/images/clustered_ui2.png b/docs/lighting/clustered/images/clustered_ui2.png new file mode 100644 index 000000000..7c7fb7429 Binary files /dev/null and b/docs/lighting/clustered/images/clustered_ui2.png differ diff --git a/docs/lighting/clustered/images/clustered_ui3.png b/docs/lighting/clustered/images/clustered_ui3.png new file mode 100644 index 000000000..3e6a64f8b Binary files /dev/null and b/docs/lighting/clustered/images/clustered_ui3.png differ diff --git a/docs/lighting/clustered/images/devui3.png b/docs/lighting/clustered/images/devui3.png new file mode 100644 index 000000000..6ef04ad07 Binary files /dev/null and b/docs/lighting/clustered/images/devui3.png differ diff --git a/docs/lighting/clustered/images/fancy_light1.png b/docs/lighting/clustered/images/fancy_light1.png deleted file mode 100644 index 4f07b5910..000000000 Binary files a/docs/lighting/clustered/images/fancy_light1.png and /dev/null differ diff --git a/docs/lighting/clustered/images/fancy_light2.png b/docs/lighting/clustered/images/fancy_light2.png deleted file mode 100644 index decd1acd0..000000000 Binary files a/docs/lighting/clustered/images/fancy_light2.png and /dev/null differ diff --git a/docs/lighting/clustered/images/light_dynamic.png b/docs/lighting/clustered/images/light_dynamic.png new file mode 100644 index 000000000..d026a3fe3 Binary files /dev/null and b/docs/lighting/clustered/images/light_dynamic.png differ diff --git a/docs/lighting/clustered/images/light_dynamicbounce.png b/docs/lighting/clustered/images/light_dynamicbounce.png new file mode 100644 index 000000000..958048a0e Binary files /dev/null and b/docs/lighting/clustered/images/light_dynamicbounce.png differ diff --git a/docs/lighting/clustered/images/light_indirect.png b/docs/lighting/clustered/images/light_indirect.png new file mode 100644 index 000000000..6e187c3b4 Binary files /dev/null and b/docs/lighting/clustered/images/light_indirect.png differ diff --git a/docs/lighting/clustered/images/light_spec.png b/docs/lighting/clustered/images/light_spec.png new file mode 100644 index 000000000..0a181044e Binary files /dev/null and b/docs/lighting/clustered/images/light_spec.png differ diff --git a/docs/lighting/clustered/images/light_static+.png b/docs/lighting/clustered/images/light_static+.png new file mode 100644 index 000000000..de6fde59e Binary files /dev/null and b/docs/lighting/clustered/images/light_static+.png differ diff --git a/docs/lighting/clustered/images/light_static.png b/docs/lighting/clustered/images/light_static.png new file mode 100644 index 000000000..2f2c74df6 Binary files /dev/null and b/docs/lighting/clustered/images/light_static.png differ diff --git a/docs/lighting/clustered/images/only_direct1.jpg b/docs/lighting/clustered/images/only_direct1.jpg deleted file mode 100644 index 34b2f4c44..000000000 Binary files a/docs/lighting/clustered/images/only_direct1.jpg and /dev/null differ diff --git a/docs/lighting/clustered/images/only_direct2.jpg b/docs/lighting/clustered/images/only_direct2.jpg deleted file mode 100644 index 5981a7e9e..000000000 Binary files a/docs/lighting/clustered/images/only_direct2.jpg and /dev/null differ diff --git a/docs/lighting/clustered/images/only_indirect.jpg b/docs/lighting/clustered/images/only_indirect.jpg deleted file mode 100644 index 5c1e8535b..000000000 Binary files a/docs/lighting/clustered/images/only_indirect.jpg and /dev/null differ diff --git a/docs/lighting/clustered/images/point_1024_25.jpg b/docs/lighting/clustered/images/point_1024_25.jpg deleted file mode 100644 index b6e02b481..000000000 Binary files a/docs/lighting/clustered/images/point_1024_25.jpg and /dev/null differ diff --git a/docs/lighting/clustered/images/point_1024_50.jpg b/docs/lighting/clustered/images/point_1024_50.jpg deleted file mode 100644 index 47d51cf04..000000000 Binary files a/docs/lighting/clustered/images/point_1024_50.jpg and /dev/null differ diff --git a/docs/lighting/clustered/images/point_1024_75.jpg b/docs/lighting/clustered/images/point_1024_75.jpg deleted file mode 100644 index a1fec9550..000000000 Binary files a/docs/lighting/clustered/images/point_1024_75.jpg and /dev/null differ diff --git a/docs/lighting/clustered/images/point_256_25.jpg b/docs/lighting/clustered/images/point_256_25.jpg deleted file mode 100644 index f9886ee61..000000000 Binary files a/docs/lighting/clustered/images/point_256_25.jpg and /dev/null differ diff --git a/docs/lighting/clustered/images/point_256_50.jpg b/docs/lighting/clustered/images/point_256_50.jpg deleted file mode 100644 index 0ccdc7818..000000000 Binary files a/docs/lighting/clustered/images/point_256_50.jpg and /dev/null differ diff --git a/docs/lighting/clustered/images/point_256_75.jpg b/docs/lighting/clustered/images/point_256_75.jpg deleted file mode 100644 index d58863754..000000000 Binary files a/docs/lighting/clustered/images/point_256_75.jpg and /dev/null differ diff --git a/docs/lighting/clustered/images/point_512_25.jpg b/docs/lighting/clustered/images/point_512_25.jpg deleted file mode 100644 index 775bea821..000000000 Binary files a/docs/lighting/clustered/images/point_512_25.jpg and /dev/null differ diff --git a/docs/lighting/clustered/images/point_512_50.jpg b/docs/lighting/clustered/images/point_512_50.jpg deleted file mode 100644 index b24ab1a00..000000000 Binary files a/docs/lighting/clustered/images/point_512_50.jpg and /dev/null differ diff --git a/docs/lighting/clustered/images/point_512_75.jpg b/docs/lighting/clustered/images/point_512_75.jpg deleted file mode 100644 index c9f8edf6f..000000000 Binary files a/docs/lighting/clustered/images/point_512_75.jpg and /dev/null differ diff --git a/docs/lighting/clustered/images/properties_dynamic.png b/docs/lighting/clustered/images/properties_dynamic.png new file mode 100644 index 000000000..2d90360f9 Binary files /dev/null and b/docs/lighting/clustered/images/properties_dynamic.png differ diff --git a/docs/lighting/clustered/images/properties_dynamic2.png b/docs/lighting/clustered/images/properties_dynamic2.png new file mode 100644 index 000000000..fbb667cdc Binary files /dev/null and b/docs/lighting/clustered/images/properties_dynamic2.png differ diff --git a/docs/lighting/clustered/images/properties_indirect.png b/docs/lighting/clustered/images/properties_indirect.png new file mode 100644 index 000000000..e5ba73dde Binary files /dev/null and b/docs/lighting/clustered/images/properties_indirect.png differ diff --git a/docs/lighting/clustered/images/properties_specular.png b/docs/lighting/clustered/images/properties_specular.png new file mode 100644 index 000000000..4873cd1e8 Binary files /dev/null and b/docs/lighting/clustered/images/properties_specular.png differ diff --git a/docs/lighting/clustered/images/properties_static.png b/docs/lighting/clustered/images/properties_static.png new file mode 100644 index 000000000..003580605 Binary files /dev/null and b/docs/lighting/clustered/images/properties_static.png differ diff --git a/docs/lighting/clustered/images/shadow_size3.jpg b/docs/lighting/clustered/images/shadow_size3.jpg deleted file mode 100644 index 0e5052fc6..000000000 Binary files a/docs/lighting/clustered/images/shadow_size3.jpg and /dev/null differ diff --git a/docs/lighting/clustered/images/shadow_size5.jpg b/docs/lighting/clustered/images/shadow_size5.jpg deleted file mode 100644 index b371fa661..000000000 Binary files a/docs/lighting/clustered/images/shadow_size5.jpg and /dev/null differ diff --git a/docs/lighting/clustered/images/shadow_size7.jpg b/docs/lighting/clustered/images/shadow_size7.jpg deleted file mode 100644 index 05a3d70a0..000000000 Binary files a/docs/lighting/clustered/images/shadow_size7.jpg and /dev/null differ diff --git a/docs/lighting/clustered/images/shadowed_dynamic.jpg b/docs/lighting/clustered/images/shadowed_dynamic.jpg deleted file mode 100644 index 660852933..000000000 Binary files a/docs/lighting/clustered/images/shadowed_dynamic.jpg and /dev/null differ diff --git a/docs/lighting/clustered/images/shadowed_specular.jpg b/docs/lighting/clustered/images/shadowed_specular.jpg deleted file mode 100644 index da36c2317..000000000 Binary files a/docs/lighting/clustered/images/shadowed_specular.jpg and /dev/null differ diff --git a/docs/lighting/clustered/images/shadowed_static.jpg b/docs/lighting/clustered/images/shadowed_static.jpg deleted file mode 100644 index ac6daaf25..000000000 Binary files a/docs/lighting/clustered/images/shadowed_static.jpg and /dev/null differ diff --git a/docs/lighting/clustered/images/shadowed_staticb.jpg b/docs/lighting/clustered/images/shadowed_staticb.jpg deleted file mode 100644 index 0d2d98f05..000000000 Binary files a/docs/lighting/clustered/images/shadowed_staticb.jpg and /dev/null differ diff --git a/docs/lighting/clustered/images/shadows1.jpg b/docs/lighting/clustered/images/shadows1.jpg deleted file mode 100644 index 6d92752f5..000000000 Binary files a/docs/lighting/clustered/images/shadows1.jpg and /dev/null differ diff --git a/docs/lighting/clustered/images/shadows1.png b/docs/lighting/clustered/images/shadows1.png new file mode 100644 index 000000000..1ad3db10f Binary files /dev/null and b/docs/lighting/clustered/images/shadows1.png differ diff --git a/docs/lighting/clustered/images/shadowsize3.png b/docs/lighting/clustered/images/shadowsize3.png new file mode 100644 index 000000000..2fe17025c Binary files /dev/null and b/docs/lighting/clustered/images/shadowsize3.png differ diff --git a/docs/lighting/clustered/images/shadowsize5.png b/docs/lighting/clustered/images/shadowsize5.png new file mode 100644 index 000000000..0837ae3e4 Binary files /dev/null and b/docs/lighting/clustered/images/shadowsize5.png differ diff --git a/docs/lighting/clustered/images/shadowsize7.png b/docs/lighting/clustered/images/shadowsize7.png new file mode 100644 index 000000000..4c350835d Binary files /dev/null and b/docs/lighting/clustered/images/shadowsize7.png differ diff --git a/docs/lighting/clustered/images/specular1.jpg b/docs/lighting/clustered/images/specular1.jpg deleted file mode 100644 index c439d4205..000000000 Binary files a/docs/lighting/clustered/images/specular1.jpg and /dev/null differ diff --git a/docs/lighting/clustered/images/specular2.jpg b/docs/lighting/clustered/images/specular2.jpg deleted file mode 100644 index 5127c8832..000000000 Binary files a/docs/lighting/clustered/images/specular2.jpg and /dev/null differ diff --git a/docs/lighting/clustered/images/specular3.jpg b/docs/lighting/clustered/images/specular3.jpg deleted file mode 100644 index ca87d746b..000000000 Binary files a/docs/lighting/clustered/images/specular3.jpg and /dev/null differ diff --git a/docs/lighting/clustered/images/specular_metal1.jpg b/docs/lighting/clustered/images/specular_metal1.jpg deleted file mode 100644 index 3fbf7b12c..000000000 Binary files a/docs/lighting/clustered/images/specular_metal1.jpg and /dev/null differ diff --git a/docs/lighting/clustered/images/specular_metal2.jpg b/docs/lighting/clustered/images/specular_metal2.jpg deleted file mode 100644 index a4ec0812e..000000000 Binary files a/docs/lighting/clustered/images/specular_metal2.jpg and /dev/null differ diff --git a/docs/lighting/clustered/images/specular_off.png b/docs/lighting/clustered/images/specular_off.png new file mode 100644 index 000000000..183ca4c73 Binary files /dev/null and b/docs/lighting/clustered/images/specular_off.png differ diff --git a/docs/lighting/clustered/images/specular_on.png b/docs/lighting/clustered/images/specular_on.png new file mode 100644 index 000000000..0e04050b5 Binary files /dev/null and b/docs/lighting/clustered/images/specular_on.png differ diff --git a/docs/lighting/clustered/images/specular_shadoff.png b/docs/lighting/clustered/images/specular_shadoff.png new file mode 100644 index 000000000..c92ee504f Binary files /dev/null and b/docs/lighting/clustered/images/specular_shadoff.png differ diff --git a/docs/lighting/clustered/images/specular_shadon.png b/docs/lighting/clustered/images/specular_shadon.png new file mode 100644 index 000000000..69e233719 Binary files /dev/null and b/docs/lighting/clustered/images/specular_shadon.png differ diff --git a/docs/lighting/clustered/images/staticb_falloff_1.jpg b/docs/lighting/clustered/images/staticb_falloff_1.jpg deleted file mode 100644 index c8979e472..000000000 Binary files a/docs/lighting/clustered/images/staticb_falloff_1.jpg and /dev/null differ diff --git a/docs/lighting/clustered/images/staticb_falloff_2.jpg b/docs/lighting/clustered/images/staticb_falloff_2.jpg deleted file mode 100644 index 357664482..000000000 Binary files a/docs/lighting/clustered/images/staticb_falloff_2.jpg and /dev/null differ diff --git a/docs/lighting/clustered/images/unshadowed_dynamic.jpg b/docs/lighting/clustered/images/unshadowed_dynamic.jpg deleted file mode 100644 index 7e1e96a61..000000000 Binary files a/docs/lighting/clustered/images/unshadowed_dynamic.jpg and /dev/null differ diff --git a/docs/lighting/clustered/images/unshadowed_specular.jpg b/docs/lighting/clustered/images/unshadowed_specular.jpg deleted file mode 100644 index 50f9e91eb..000000000 Binary files a/docs/lighting/clustered/images/unshadowed_specular.jpg and /dev/null differ diff --git a/docs/lighting/clustered/images/unshadowed_static.jpg b/docs/lighting/clustered/images/unshadowed_static.jpg deleted file mode 100644 index d7ee94744..000000000 Binary files a/docs/lighting/clustered/images/unshadowed_static.jpg and /dev/null differ diff --git a/docs/lighting/clustered/images/unshadowed_staticb.jpg b/docs/lighting/clustered/images/unshadowed_staticb.jpg deleted file mode 100644 index 0fde6aa78..000000000 Binary files a/docs/lighting/clustered/images/unshadowed_staticb.jpg and /dev/null differ diff --git a/docs/lighting/clustered/light_type_reference.md b/docs/lighting/clustered/light_type_reference.md deleted file mode 100644 index a9ad4c449..000000000 --- a/docs/lighting/clustered/light_type_reference.md +++ /dev/null @@ -1,81 +0,0 @@ ---- -title: "Light Type Reference" -features: - - USE_CLUSTERED ---- -# Light Type Reference - -This is a reference page for the 4 light types. - -## Static - -This light type is mainly used for lights that cast baked direct and indirect light, with no need for dynamic shadows nor any specular lighting. The Shadowed spawnflag is non-functional with this light type. - -These lights are the same as standard Source Engine lights. - -| Direct | Indirect | Specular | -| ------ | -------- | ------------ | -| baked | baked | *disabled* | - -* Top: 3 Static-type lights, shadowed flag unchecked -* Bottom: 3 Static-type lights, shadowed flag checked. Note the lack of shadows on the walls. - -![static unshadowed](images\unshadowed_static.jpg) - -![static shadowed](images\shadowed_static.jpg) - -For most use cases, Specular lights should be used, as the specular reflections properly use the metallic channel of PBR materials. - -## Specular - -This light type has baked direct and indirect lighting like the Static light type, except that it also includes dynamic Specular lighting. - -Shadows can be enabled on this light type using the "Shadowed" spawnflag, however the shadows will be fainter than those of Static Bounce or Fully Dynamic. - -> [!WARNING] -> Specular highlights will travel through walls if the Shadowed spawnflag is not checked. If this will cause issues with your map, use the Static light type instead. - -| Direct | Indirect | Specular | -| ------ | -------- | ----------------- | -| baked | baked | **dynamic** | - -* Top: 3 Specular-type lights, shadowed flag unchecked -* Bottom: 3 Specular-type lights, shadowed flag checked. - -![specular unshadowed](images\unshadowed_specular.jpg) - -![specular shadowed](images\shadowed_specular.jpg) - -## Static Bounce - -This light type casts static bounced lighting and dynamic direct lighting. Unlike the "Static" and "Specular" light types, direct lighting is dynamic and will shine through walls if the light is not shadowed. - -| Direct | Indirect | Specular | -| ----------------- | -------- | ----------------- | -| **dynamic** | baked | **dynamic** | - -* Top: 3 Static Boucne-type lights, shadowed flag unchecked -* Bottom: 3 Static Bounce-type lights, shadowed flag checked. - -![Static Bounce unshadowed](images\unshadowed_staticb.jpg) - -![Static Bounce shadowed](images\shadowed_staticb.jpg) - -This light is best used for static sources of light that need to cast dynamic shadows, such as observation rooms in Portal 2. - -## Fully Dynamic - -This light type casts dynamic direct lighting and specular highlights, without any indirect lighting. - -| Direct | Indirect | Specular | -| ----------------- | ------------ | ----------------- | -| **dynamic** | *disabled* | **dynamic** | - -* Top: 3 Dynamic-type lights, shadowed flag unchecked. Note how the light bleeds through the window frame on to the floor outside the room. -* Bottom: 3 Dynamic-type lights, shadowed flag checked. - -![specular unshadowed](images\unshadowed_dynamic.jpg) - -![specular shadowed](images\shadowed_dynamic.jpg) - -This light is best used for moving light sources, where prebaked bounce lighting will look out of place when the light source has moved, such as swinging ceiling lights or a movable desk lamp. diff --git a/docs/lighting/clustered/meta.json b/docs/lighting/clustered/meta.json index a430cae3a..c2fcf3759 100644 --- a/docs/lighting/clustered/meta.json +++ b/docs/lighting/clustered/meta.json @@ -1 +1 @@ -{ "title": "Clustered Shading" } +{ "title": "Clustered Lighting" } diff --git a/docs/lighting/clustered/quick_start.md b/docs/lighting/clustered/quick_start.md index 74ceccadc..2757ae587 100644 --- a/docs/lighting/clustered/quick_start.md +++ b/docs/lighting/clustered/quick_start.md @@ -1,31 +1,67 @@ --- title: Quick Start Guide +weight: 20 features: - USE_CLUSTERED --- # Quick Start Guide -"I want an unmoving normal Source engine light, but better, and not slow" +### "I want an expensive light that has fancy shadows and isn't supposed to move" 1. Add a light_rt or light_rt_spot entity -2. Set "Light mode" to "Specular" -3. Make sure the "Shadowed" spawnflag is UNCHECKED -4. Set "Radius" and "50 percent scale" KeyValues to adjust the look and feel -5. For best results, use PBR textures with appropriate MRAOs and normal maps +2. Set "Specular Light Mode" to "Dynamic Only" +3. Set "Direct Light Mode" to "Dynamic Only" +4. Set "Indirect Light Mode" to "Static Only +5. Set "Initial Shadow Size" to 6 or 7 +6. Make sure the "Shadowed" flag is **checked** +7. Set "50 percent falloff distance" and "0 percent falloff distance" KeyValues to adjust the look and feel +8. For best results, use PBR textures with appropriate MRAOs and normal maps -![Keyvalues](images/basic_light1.png) +![Keyvalues](images/properties_dynamic.png) -![Spawnflags](images/basic_light2.png) +### "I want a fully dynamic light that is supposed to move and interact with other dynamic lights" -"I want an expensive light that has fancy shadows or moves around" +1. Add a light_rt or light_rt_spot entity +2. Set "Specular Light Mode" to "Dynamic Only" +3. Set "Direct Light Mode" to "Dynamic Only" +4. Set "Indirect Light Mode" to "None" +5. Set "Initial Shadow Size" to something around 5 +6. Make sure the "Shadowed" flag is **checked** +7. Set "50 percent falloff distance" and "0 percent falloff distance" KeyValues to adjust the look and feel +8. For best results, use PBR textures with appropriate MRAOs and normal maps + +![Keyvalues](images/properties_dynamic2.png) + +### "I want a regular, cheap static light" 1. Add a light_rt or light_rt_spot entity -2. Set "Light mode" to "Static Bounce" (for mostly stationary) or "Fully Dynamic" (frequently moves) -3. Set "Initial Shadow Size" to somewhere around 5 to 7 -4. Make sure the "Shadowed" spawnflag is CHECKED -5. Set "Radius" and "50 percent scale" KeyValues to adjust the look and feel +2. Set "Specular Light Mode" to "None" +3. Set "Direct Light Mode" to "Static Only" +4. Set "Indirect Light Mode" to "Static Only" +5. Set "50 percent falloff distance" and "0 percent falloff distance" KeyValues to adjust the look and feel 6. For best results, use PBR textures with appropriate MRAOs and normal maps -![Keyvalues](images/fancy_light2.png) +![Keyvalues](images/properties_static.png) + +### "I only want indirect lighting" + +1. Add a light_rt or light_rt_spot entity +2. Set "Specular Light Mode" to "None" +3. Set "Direct Light Mode" to "None" +4. Set "Indirect Light Mode" to "Static Only" +5. Set "50 percent falloff distance" and "0 percent falloff distance" KeyValues to adjust the look and feel +6. For best results, use PBR textures with appropriate MRAOs and normal maps + +![Keyvalues](images/properties_indirect.png) + +### "I only want a specular reflection" + +1. Add a light_rt or light_rt_spot entity +2. Set "Specular Light Mode" to "None" +3. Set "Direct Light Mode" to "None" +4. Set "Indirect Light Mode" to "Static Only" +5. Make sure the "Shadowed" flag is **checked** +6. Set "50 percent falloff distance" and "0 percent falloff distance" KeyValues to adjust the look and feel +7. For best results, use PBR textures with appropriate MRAOs and normal maps -![Spawnflags](images/fancy_light1.png) +![Keyvalues](images/properties_specular.png) diff --git a/docs/lighting/clustered/troubleshooting.md b/docs/lighting/clustered/troubleshooting.md index 5c2249880..65b0e8302 100644 --- a/docs/lighting/clustered/troubleshooting.md +++ b/docs/lighting/clustered/troubleshooting.md @@ -1,5 +1,6 @@ --- -title: "Troubleshooting and Known Issues" +title: "Known Issues" +weight: 40 features: - USE_CLUSTERED --- @@ -7,33 +8,33 @@ features: This is a list of currently known issues and some troubleshooting tips for any issues with clustered lighting. -**"Everything is completely broken/corrupted"** +### "My lights don't have shadows" / "My lights are shining through walls" -* Certain GPU models may have trouble running the clustered renderer. **If you experience this, let us know what GPU brand/model, operating system and other hardware specs you're using.** Usually this issue has been observed when running the game on Linux under DXVK on AMD platforms. However, the circumstances in which this has been observed should not be possible in production. +* For cheap static shadows, make sure "Direct light mode" is set to "Static Only" for your light entity. With this option, specular lighting will still travel through walls. If that's an issue for your map, you may need to use dynamic shadows or turn off specular. +* For dynamic shadows, make sure the "Shadowed" spawn flag is enabled on the light that should be casting shadows. -**"My lights don't have shadows" / "My lights are shining through walls"** +### "I set the Shadowed spawn flag, but there are still no shadows/light leaks through walls" -* For cheap static shadows, make sure you are using baked direct lighting for static shadows, (Light mode "specular" or "static.") With this option, specular lighting will still travel through walls. If that's an issue for your map, you may need to use dynamic shadows or turn off specular. -* For dynamic shadows, make sure the "Shadowed" spawn flag is set on the light that should be casting shadows. +* You have too many dynamic shadows updating at once. Remember that **each shadow size level increases the shadow atlas size by a factor of 4**, and **the shadow atlas cannot have exceed a value of 7**, so if there are for example 2 `light_rt`s with shadow size of 6 close to each other, they will overlap and therefore will not produce any shadows. However, there is an unstable workaround, where by enabling `light_rt`s one by one they have a chance to keep their shadows. -**"I set the Shadowed spawn flag, but there are still no shadows/light leaks through walls"** +### "My dynamic shadows are blurry" -* You may have too many dynamic shadows updating at once. This is a known issue without a current workaround. Let us know if you find one! +* Set the "Initial Shadow Size" keyvalue of your light to something around 6. -**"My dynamic shadows are blurry"** +### "My dynamic shadows are 'frozen' or don't update" / "Some entities like rockets don't cast shadows" -* Set the "Initial Shadow Size" key on your light to something around 7, or higher if you really need it. +* Shadows are updated when entities move near the light source. Some entities aren't hooked up properly, this is a known issue. Most entities should be fixed (prop_dynamic, prop_physics), but if you find any entity that does not update shadows, make sure to let us know on the Strata issue tracker. -**"My dynamic shadows are 'frozen' or don't update" / "Some entities like rockets don't cast shadows"** +### "My dynamic shadows update in low fps" -* Shadows are updated when entities move near the light source. Some entities aren't hooked up properly, this is a known issue. Most entities should be fixed (prop_dynamic, prop_physics), but if you find any entity that does not update shadows, make sure to let us know on the [Strata issue tracker](https://github.com/StrataSource/Engine/issues). +* There is a cap on how many faces can get their shadows updated, and this cap is called the **shadow frame budget**. This is an optimisation technique that prevents the game from lagging on low-end devices. You can increase the budget by using the `r_clustered_shadowframebudget` console command. Note that this will significantly lower your fps when used carelessly. -**"Shadows glitch or flicker when a light is moving"** +### "Shadows glitch or flicker when a light is moving" -* This is a known issue without a current workaround. Let us know if you find one! +* Clustered shadows update less frequently than the game itself, so if a moving clustered light entity cannot keep up updating the shadowmap, the shadows from that entity will flicker. This often happens in heavy maps with a lot of clustered lights, and rarely if the light peaks from a corner, especially when lighting up a huge area. There is no workaround other than not moving clustered lights too fast and using dynamic shadows only where nesessary. -**"I see light coming from light sources that aren't in the current PVS"** +### "Everything is completely broken/corrupted and I can't fix it" -* This is a known issue without a current workaround. Let us know if you find one! +* Certain GPU models may have trouble running the clustered renderer. **If you experience this, let us know what GPU brand/model, operating system and other hardware specs you're using.** Clustered lights may act weird when running the game on Linux under DXVK on AMD platforms. However, the circumstances in which they break should not be possible in production. -If you have any issues that are not addressed in this article, make sure to report it to us on the [Strata issue tracker](https://github.com/StrataSource/Engine/issues). +## If you have any issues that are not addressed in this article, make sure to report it to us on the [Strata issue tracker](https://github.com/StrataSource/Engine/issues). diff --git a/docs/lighting/clustered/what_is.md b/docs/lighting/clustered/what_is.md index f33f9a042..a68bf41c9 100644 --- a/docs/lighting/clustered/what_is.md +++ b/docs/lighting/clustered/what_is.md @@ -1,5 +1,6 @@ --- -title: "Clustered Lighting: How Does It Work?" +title: "Introduction" +weight: 10 features: - USE_CLUSTERED --- @@ -8,83 +9,104 @@ features: Clustered Lighting adds a new dynamic lighting system to Strata, with the following major improvements: * Specular lighting now works on all surfaces, brush or prop, indoors or outdoors. -* light_rt entities can now cast light and shadows dynamically. +* `light_rt` entities can now cast light and shadows dynamically. * Lights can move and their light and shadows will move with them. * Entities can move under lights and have their lighting updated. This includes brush entities. -* Hammer can now preview lighting and shadows in real time. +* `light_rt` can be configured to use static shadows or no shadows at all, making the regular light entity obsolete. Currently, only Portal 2: Community Edition and Momentum Mod support Clustered Lighting. There are currently no plans to add Clustered Lighting to Portal: Revolution. > [!NOTE] -> Clustered currently works for the PBR, LMG, VLG, Water, Paint, Gel Blobs, and Eyes shaders +> Clustered currently works with the following shaders: PBR, LightMappedGeneric, VertexLitGeneric, Water, Paint, Gel Blobs and Eyes. -## How Does it Work? +## How Does It Work? Traditionally in Source, light sources light up the map in two ways: by directly shining light onto a surface, and indirectly, by having their light bounce onto other surfaces. Both direct and indirect lighting are calculated by VRAD when the map is compiled, and "baked" into the map's lightmap, which can generally be thought of as an unmoving texture that is painted onto all the "lit" surfaces of the map. * Top: Normal lighting. -* Middle: Direct lighting only. Notice how the backs of the cubes are now completely black, since no light is directly hitting them. -* Bottom: Indirect lighting only. The room is now only dimly lit by the reflected light, but the bright direct light is gone. +* Middle: Direct lighting only. Notice how the room became darker. +* Bottom: Indirect lighting only. The room is now dimly lit, with only NPC and cubes neing bright. -![Normal Lighting](images\only_direct1.jpg) +![Normal Lighting](images\light_static+.png) -![Direct lighting only](images\only_direct2.jpg) +![Direct lighting only](images\light_static.png) -![Indirect lighting only](images\only_indirect.jpg) +![Indirect lighting only](images\light_indirect.png) Two major limitations of this system are that it cannot easily support dynamic light and shadows, since both are baked into the lightmap which can only change in very limited ways at runtime, and that it does not support specular lighting. -Specular lighting is the light that's reflected off of smooth, shiny surfaces, usually forming a bright highlight. Specular lighting is unique in that it can change drastically depending on the player's view position relative to the surface and the light, so it can't easily be recorded into the lightmap. This is not true for direct and indirect lighting, as these are diffuse types of lighting, which means they don't depend on the player's view position. +## +#### Clustered lighting improves these limitations, +by adding efficient dynamic lighting for all light types, instead of just projected textures. +Clustered uses traditional shadow-mapping techniques and renders to a single shadow atlas instead of a separate depth texture like projected textures do. The shadow atlas contains the depth values for all lights in the scene. +Shadowmaps update only in certain scenarios: when the light source moves and when an object moves inside the light. -Clustered lighting improves these limitations by adding dynamic lighting that is calculated at runtime, and not exclusively baked into the lightmap. Now, we can change the following three properties: -* Direct lighting can be statically baked into the lightmap or dynamic -* Indirect lighting can be statically baked into the lightmap or disabled -* Specular lighting can be disabled or dynamic +Now, there are three properties of a clustered light entity: +* Direct lighting, that can be statically baked into the lightmap or dynamically use the clustered lighting +* Indirect lighting, that can be baked or disabled +* Specular lighting, which is a realistic reflection of the light, can be disabled as well -Which technique is used is controlled by the light's "Light mode": +There are three keyvalues that control these properties: **Direct light mode**, **Indirect light mode.** and **Specular light mode**. -| | Direct | Indirect | Specular | + +| | Direct | Indirect | Specular | | --------------- | ----------------- | ------------ | ----------------- | -| "Static" | baked | baked | *disabled* | -| "Specular" | baked | baked | **dynamic** | -| "Static Bounce" | **dynamic** | baked | **dynamic** | -| "Dynamic" | **dynamic** | *disabled* | **dynamic** | +| None | "None" | "Static Only"| "Dynamic Only" | +| Static | "None" | "Static Only"| - | +| Dynamic | "None" | - | "Dynamic Only" | -The "Static" light mode is identical to pre-clustered lighting, with no dynamic lighting at all. "Specular" enables dynamic specular lighting while keeping everything else baked into the lightmap. "Static bounce" also does direct lighting dynamically, and "Dynamic" removes indirect lighting, so it is 100% dynamic. ## Specular Lighting -All the new light modes except "Static" enable specular lighting, which can massively improve how materials look, especially PBR materials. +All the new light modes except "Static" enable specular lighting, which can massively improve how PBR materials look. + +Specular lighting is not an actual lighting, but rather a reflection off of smooth, shiny surfaces, usually forming a bright highlight. Specular lighting is unique in that it can change drastically depending on the player's view position relative to the surface and the light, so it can't be baked into the lightmap. This is not true for direct and indirect lighting, as these are diffuse types of lighting, which means they don't depend on the player's view position. + +> [!NOTE] +> Specular reflections are baked into cubemaps. Keep this in mind when making high-quality parallax reflections. * Top: No specular. -* Middle: Specular lighting enabled. Notice the highlight on the blue material, and the bright spots on the back wall. +* Middle: Specular lighting enabled. Notice a white circle appearing on the wall, as well as reflection on the grate. * Bottom: Specular lighting only. By removing the baked direct and indirect light, you can see exactly what specular lighting adds to the scene. -![No Specular](images/specular1.jpg) +![No Specular](images/light_dynamic.png) -![Specular lighting enabled](images/specular2.jpg) +![Specular lighting enabled](images/light_dynamicbounce.png) -![Specular lighting only](images/specular3.jpg) +![Specular lighting only](images/light_spec.png) The addition of specular lighting also make metallic PBR materials look much more correct. Previously, without another specular-enabled source like outdoors CSM, metallic materials would simply appear black. This is because metals really only reflect specular lighting, and have little to no diffuse lighting. * Top: No specular. The metal parts of the material are completely black. -* Bottom: Specular lighting enabled. The metal now reacts to the nearby light source correctly (some parts of the metal are still black because they aren't being lit by a dynamic light source.) +* Bottom: Specular lighting enabled. The metal now reacts to the nearby light source correctly (some parts of the metal are still black because they aren't being lit by a dynamic light source). + +![No specular](images/specular_off.png) + +![Specular lighting enabled](images/specular_on.png) + +> [!NOTE] +> Specular reflections are shadow dependant. So if the "Shadowed" flag is checked, the reflection will be displayed where the shadow from this light source would fall. + +![Specular](images/specular_shadoff.png) -![No specular](images/specular_metal1.jpg) +![Specular](images/specular_shadon.png) -![Specular lighting enabled](images/specular_metal2.jpg) ## Real Time Shadows With real time light and shadows, normal `light_rt` and `light_rt_spot` entities move, updating the light of their surroundings in real time. They can also be parented to other entities. -* A swinging point `light_rt`, casting shadows in all 6 directions, and a stationary directional `light_rt_spot`, casting shadows in one direction. +> [!NOTE] +> Clustered lights don't update their shadows when the object isn't moving (eg. when animation is played) unless a physics object updates its shadow around that object or if `Always Update` flag is set. + +There are 2 entities that can produce real time shadows. + +* `light_rt` on the top, casting shadows in all 6 directions, and a directional `light_rt_spot` on the bottom, casting shadows in one direction. -![lights in a scene](images/shadows1.jpg) +![lights in a scene](images/shadows1.png) > [!WARNING] -> Shadowed point `light_rt`s take up 6 times the shadow memory that shadowed `light_rt_spot` entities take, as they are casting in 6 different directions. Use these sparingly, and disable shadows if not needed! +> Shadowed point `light_rt`s take up 6 times the shadow memory that shadowed `light_rt_spot` entities take, as they are casting in 6 different directions. Use these sparingly, no need to make every light source dynamic! ## Shadow Map Size @@ -96,14 +118,31 @@ You can control the size of the shadow map by changing the "Initial Shadow Size" * Middle: "Initial Shadow Size" is 5 * Bottom: "Initial Shadow Size" is 7 -![Initial Shadow Size is 3](images/shadow_size3.jpg) +![Initial Shadow Size is 3](images/shadowsize3.png) -![Initial Shadow Size is 5](images/shadow_size5.jpg) +![Initial Shadow Size is 5](images/shadowsize5.png) -![Initial Shadow Size is 7](images/shadow_size7.jpg) +![Initial Shadow Size is 7](images/shadowsize7.png) > [!NOTE] -> In the clustered renderer, shadowmaps for all lights are stored in a single, larger texture, called the 'shadow atlas', which has space for a limited amount of shadow data. Each time you increase the 'size' of a shadow by 1, you increase its shadow size by a factor of 4. For example, a shadow of size 2 takes up only a quarter of the space that a shadow of size 3 takes up. If shadows in your map stop appearing suddenly, consider reducing the shadow size of a few less important shadows. +> In the clustered renderer, shadowmaps for all lights are stored in a single, larger texture, called the 'Shadow Atlas', which has space for a limited amount of shadow data. Each time you increase the size of a shadow by 1, you increase the atlas' shadow size by a factor of 4. For example, a shadow of size 2 takes up only a quarter of the space that a shadow of size 3 takes up. If shadows in your map stop appearing suddenly, consider reducing the shadow size of a few less important shadows. + +> [!WARNING] +> When increasing the outer angle of `light_rt_spot`, note that the edges of the spot will have sharper shadows than the center. This is importams since setting up a `light_rt_spot` with a high shadow size and a high outer angle will produce low-quality shadows in the center while still taking up a huge piece of shadow atlas. Consder using `env_projectedtexture` or `env_cascade_light` (when imitating sunlight) in scenarios like these. + +## Console commands + +There are some clustered-related console commands that give a more precise control over clustered shadows. + +| Command | Purpose | +|-------------------------------------------|-------------------| +|`r_clustered_lighting_enable` | Toggles clustered lights. Default is 1 | +|`r_clustered_shadowframebudget` | Determines how many shadow faces can be rendered per frame. Default is 6. High values (like 50) may impact perfomance.| +|`r_clustered_shadow_depthbias` | Controls shadow ance and peter panning. High values (like 0.1) break shadows completely, lower values make shadows appear on edges of shadowmaps. Default is 0.00005 | +|`r_clustered_shadow_slopescale` | Similar to depthbias, but applied depending on how glancing the angle to the surface being rendered in the shadowmap, since more glancing angles will need higher depth bias. High values make shadows leak through world. Default is 5 | +|`r_clustered_static_lightcull` | Experimental. Allows more lights to be rendered on AMD GPUs, but makes it way slower to render on NVidia GPUs. It is recommended not to touch if you don't use AMD GPU. | +|`r_clustered_static_shadow_exponent_scale` | Scales the atlas size of shadows so they take up more space, doesn't seem to be useful since increasing the atlas's size itself is almost always a better solution. Default is 1, higher values make some shadows appear sharper | + ## Other Clustered Changes diff --git a/docs/test/_meta.json b/docs/test/_meta.json index 0115a31ec..0c4d1b59b 100644 --- a/docs/test/_meta.json +++ b/docs/test/_meta.json @@ -1,3 +1,3 @@ { - "title": "Test suite" + "title": "Test Suite" } diff --git a/docs/test/weights/meta.json b/docs/test/weights/meta.json index de08c4bd7..eb7f3afb9 100644 --- a/docs/test/weights/meta.json +++ b/docs/test/weights/meta.json @@ -1,3 +1,3 @@ { - "title": "Weight tests" + "title": "Weight Tests" } diff --git a/docs/test/weights/weight-0.md b/docs/test/weights/weight-0.md index db3783cb9..c7aada33c 100644 --- a/docs/test/weights/weight-0.md +++ b/docs/test/weights/weight-0.md @@ -1,6 +1,8 @@ --- -title: B 0 weight +title: A 0 weight weight: 0 --- -This file has a weight of 0 +This file has a weight of 0. + +It appears on the top of other files. diff --git a/docs/test/weights/weight-10.md b/docs/test/weights/weight-10.md index 40c50b15c..9043d8a79 100644 --- a/docs/test/weights/weight-10.md +++ b/docs/test/weights/weight-10.md @@ -1,5 +1,5 @@ --- -title: c 10 weight +title: B 10 weight weight: 10 --- diff --git a/docs/test/weights/weight-no.md b/docs/test/weights/weight-no.md index 5782eb26a..3137c95de 100644 --- a/docs/test/weights/weight-no.md +++ b/docs/test/weights/weight-no.md @@ -1,5 +1,7 @@ --- -title: A no weight +title: C no weight --- -This file has no weight \ No newline at end of file +This file has no weight. + +It appears to be on the bottom of the pages list. \ No newline at end of file