True Volumetric Light 0.2 beta
==============================

Volumetric sunlight for The Witcher 3: Wild Hunt next-gen (DirectX 12): shafts of light and shadow in the
game's own fog, worked out from the sun's shadow map, following the game's weather and time of day.


Requirements
------------
- The Witcher 3 next-gen update, DirectX 12 (bin\x64_dx12). DirectX 11 is not supported.
- ReShade 6.x WITH FULL ADD-ON SUPPORT (the "add-on" version from reshade.me), installed for witcher3.exe in
  bin\x64_dx12. Tested with ReShade 6.8.0.


Installing
----------
1. Install ReShade with add-on support for bin\x64_dx12\witcher3.exe, DirectX 10/11/12.
2. Extract the archive into the game's folder (The Witcher 3\), or install it with a mod manager, so that you have:
     bin\x64_dx12\TrueVolumetricLight.addon64
     bin\x64_dx12\TrueVolumetricLight\TrueVolumetricLight.hlsl
3. Start the game. Open the ReShade overlay (Home by default): the settings are in the "True Volumetric Light" tab.

Uninstalling: delete TrueVolumetricLight.addon64 and the TrueVolumetricLight folder. The settings are kept in
ReShade.ini under [TrueVolumetricLight]; that section can be deleted too.


Settings
--------
Volumetric sunlight      On/off. "Toggle key" picks a key to switch it while playing (none by default).
Follow the game's weather  The air the light goes through is the game's own fog (its density, height and
                         colours, which are dark in rain). Off: a clear day's fog, always.
Density                  Multiplies the game's fog. Fog mods that change the game's fog (e.g. Fog Remastered's
                         Density) change it here too, so with a denser fog mod a lower value may look better.
Height                   How high the dense air reaches.
Shadows in the game's haze  How much of the game's haze is taken out where the air is in shadow: the shafts,
                         without the picture getting brighter. Indoors (rooms, caves) this fades out by itself,
                         so the room is not darkened; Details shows it. Indoors is told by the game itself with
                         the optional Companion (see below); without it, it is guessed from the shadows: by the
                         air in view and around the camera, every place counting as outdoors at dusk, and by
                         moonlight for the fire glow. The guess can be wrong (shady streets, rooms with big
                         sunny windows): the Companion is recommended. From 0.2 a place the game calls outdoors
                         where no light reaches the air around (a tavern in Novigrad) counts as indoors too.
Shadows: most of a pixel  A limit on how dark those shadows can make a pixel.
Extra sunlit haze        Haze in the fog's colour added where the sun reaches: brighter shafts.
Extra sunlit haze indoors  The same indoors (0.1.12). 0.05 by default: a little light through windows without
                         hazing the room; 0 takes it out (and any light shining into a dark cave).
Fire glow in the haze    Fires, torches and lamps light the haze around them in their own colour (0.1.8). The
                         lights come from the game's own list, so a torch in Geralt's hand glows too. 0 turns it
                         off; 0.5 by default. 0.1.9 evens out how bright the fires glow and no longer counts a
                         light twice (a torch could glow two or three times too bright): with settings kept from
                         0.1.8, "Reset to defaults" or 0.5 gives the new look.
Fire glow indoors        The same indoors: rooms, cellars, caves (0.1.10). 0.25 by default: several braziers in a
                         small room made it very hazy.
                         The two are blended as you go in and out; Details shows how much of each is used.
Fire shadows in the haze (experimental)  The fires' glow in their own shadows, read from the game's shadow maps of
                         its lights: shafts of firelight through fences and between people (0.1.10). Off by
                         default. Experimental: the game keeps the shadows of some fires only from some angles,
                         and there the shafts can flicker; behind a moving torch the glow can leave a short
                         trail. Costs about 0.3 to 0.6 ms more near many fires.
Dust in the light        Motes of dust floating near you that catch the light (0.2): in shafts through windows and
                         doorways, in barns and ruins, and in the glow of fires and lamps; fainter by moonlight,
                         fewer in the open. 0.5 by default, 0 turns it off.
Quality                  Low / Medium / High / Ultra (light resolution, steps, distance). Measured cost at
                         3440x1440 on an RTX 5080: 0.20 / 0.38 / 0.45 / 0.63 ms per rendered frame.

Dim the scene behind the medium  Off by default; best left off with fog mods (the game's fog dims the distance
                         already).
Reset to defaults        Look and quality back to how the mod comes. The toggle key stays.

The GPU time of the effect is shown at the top of the tab. "Details" shows what the add-on reads from the game and,
from 0.2, how much CPU time it takes per frame; "Developer tools" are for bug reports.


Companion (optional, recommended)
---------------------------------
A separate download: TrueVolumetricLight.asi (bin\x64_dx12) and a tiny script mod (mods\modTrueVolumetricLight). The
game knows when Geralt is indoors; the Companion hands that to the add-on, so the indoor settings switch exactly at
the door instead of being guessed from the shadows. It needs Witcher Native Bridge and an ASI loader (Native Bridge
comes with one). Without Native Bridge the script does not compile: do not install the Companion then. Details shows
"Indoors: told by the game" when it works. The add-on works without it. The Companion also stops a crash at the game's
start from other add-ons (Dynamic Fog, Fog Remastered, The Living Continent) by keeping all add-ons in memory.


Compatibility
-------------
Tested with: W3 Clouds (W3Atmos), Fog Remastered, Dynamic Fog, The Living Continent (W3 Living Sky); path tracing, ray
tracing and raster lighting; DLSS (with frame generation), FSR, no upscaler.
Other ReShade effects work as usual.
OptiScaler (0.1.9): OptiScaler makes a DirectX 11 device next to the game's DirectX 12 one; the add-on now leaves the
DirectX 11 one alone.
RenoDX (from 0.1.4): RenoDX replaces the game's tone mapper and draws it itself; the add-on finds the tone mapper by
the images it reads, whatever its shader, and with RenoDX puts the light in before RenoDX draws it. 0.1.5 fixes a crash
on the first frame with the light alongside RenoDX-based add-ons (e.g. Darker Nights). If Details ever
shows "Post-processing draw ... not seen", ReShade.log lists candidates, and one of them can be set as
PostShader=<hex> under [TrueVolumetricLight] in ReShade.ini.


Known limits of this beta
-------------------------
- Tested on one PC (NVIDIA). On AMD, versions before 0.1.4 could crash when a save finished loading (especially with
  FSR); 0.1.4 reads the game's depth and shadow map in their own formats, the likely cause. Reports from other GPUs,
  AMD especially, are very welcome. Some AMD setups with FSR (Native) report a far too bright picture; that is still
  being looked into. 0.1.11 and 0.1.12 could crash on AMD after fast travel or loading a save (the add-on could keep
  using a buffer the game had freed while loading); 0.2 fixes the likely cause.
- Fire glow: before 0.1.11 it worked with ray or path tracing only. It now finds the game's lighting pass by what it
  reads, so it works in raster too, and should with other lighting add-ons and on other cards.
- The shafts come from the sun's (or the moon's) shadow map and, from 0.1.11, the game's shadows of its terrain, so
  mountains block the sun. No shadows of clouds in the air yet.
- Fires glow in the haze; their shadows in it are experimental (see Settings). Without them, within a few metres of
  a fire the glow shows through thin walls.
- Next to a character moving with a torch the glow can leave a faint trail.
- Cutscenes: from 0.1.12 the light is not blended across a cut from one shot to the next (Details counts the cuts).
- Frame generation: before 0.2 the light could flicker at x3 and over, and at times in cutscenes (the generated frames
  were counted as the game's own, and the light's smoothing over frames dropped out). Fixed in 0.2.
- CPU: 0.2 takes about half the CPU time per frame it did (measured in a busy market: about 10 ms down to 6 ms, spread
  over the game's threads).
- Rooms and caves: the shadows in the haze fade out where little sunlight is in view (0.1.6). In a big hall seen
  from far across, a little light can still show through thin walls: the game's coarser shadow cascades leave
  them out.


Reporting a problem
-------------------
Open "Details" in the add-on's tab and press "Copy report for a bug report" (0.1.12): it copies the version, your
GPU, the settings, the details, your other add-ons and the problems in ReShade.log (before 0.2 it often could not
open ReShade.log while the game ran). Paste it into your comment and
add your lighting mode (raster / ray tracing / path tracing), upscaler and frame generation. If the game crashes
before you get there, post ReShade.log (bin\x64_dx12) instead.
