chore(obs): update documentation following changes

Author: MrLixm

obs/README.md

@@ -16,7 +16,7 @@ many benefits applied on desktop capture.
 # Requirements
 
 - This has been developed on OBS `28.1.2` for Windows but should work for lower 
-versions, and other operating systems.
+and upper versions, and other operating systems.
 
 - Nothing more than the content of this directory.
 
@@ -36,50 +36,54 @@ The script is now active. A new filter has been created :
 
 1. Go to your Scene/Source where you want to add the AgX filter and select it (the source)
 2. Click on the `Filters` button that should be a bit above the source.
-3. In the **Effect Filters** section, click the `+` button and choose AgX
+3. In the **Effect Filters** section, click the `+` button and choose `AgX`
 
 All done ! You can now configure it.
 
 # Configuration
 
 ![screenshot of OBS interface while in the Filters section](doc/img/obs-filter-options.png)
 
-> ![NOTE]
+> [!IMPORTANT]
 > Reminder that AgX being a display transform it should be placed at
 > **the very end** of the image processing chain (= at the bottom in OBS).
 
 The camera/video-source and your lighting setup will affect how much you need
 to tweak the parameters. There is no setup that work for all cases, but once
 configured for your camera/usual lighting, you should not need to touch it anymore.
 
-## Recommended Options
+## Guidelines
 
-I recommend to always start by :
-
-- boosting the `Grading Exposure` by +1.0 stop.
-- boosting `Highligh Gain` by 2.0
+I recommend to :
+- `Pre-Grading`
+  - boosting the `Grading Exposure` by +1.0 stop if you are in a dim environment.
+  - boosting `Highligh Gain` by 2.0 (always better)
+  - `White Balance`: `intensity` at 1.0 and use `tint` ~10.0 if your camera tend to
+  have to produce pinkish tones (noticable on skin).
 
 ## Available Options
 
 ### Input Colorspace
 
 Pick in which colorspace your source is encoded. 
 
-Passthrough means no decoding is applied.
+`Passthrough` means no decoding is applied.
 
 ### Output Colorspace
 
 Target colorspace encoding. Must correspond to your monitor calibration.
 
-> ![NOTE]
+> [!TIP]
 > You can request adding new colorspace by opening an issue on GitHub !
 
 ### DRT
 
 Pick the DRT to use. Technically here we could include other DRT than AgX.
-But for now only None and AgX are available.
+But for now only None and AgX (with 2 variants) are available.
 
-`None` will not apply AgX but still allow you to use the grading options. 
+- `None` will not apply AgX but still allow you to use the grading options.
+- `AgX w/Outset` is AgX but with an additional transform to restore chroma. This
+can reintroduce shift and skews but might be acceptable.
 
 
 ### Pre-Grading/...
@@ -96,7 +100,7 @@ Power function. 1.0 = neutral.
 
 ### Grading/Saturation
 
-Saturation based on BT.709 coeff. 1.0 = neutral.
+Saturation with coefficient based on the working color-space. 1.0 = neutral.
 
 ### Grading/Highlight Gain
 
@@ -109,32 +113,38 @@ via `Highlight Gain Threshold`.
 
 See above.
 
-### Post-Grading/...
+### Grading/White-Balance
 
-Grading modifications applied after AgX on display encoded data. This will
-introduce skews, clipping and other artefacts.
+Shift white tones, applied before all operations.
+
+- `Temperature`: in Kelvin. Lower=warmer, higher=colder.
+- `Tint`: shift the temperature: >0=greener, <0=pinker
+- `Intensity`: global multiplier for the effect. 0=disabled.
 
-Not recommended to use or with very small values.
+The most "neutral values" when `Intensity` is 1.0 are `Temperature`=`~5600` and
+`Tint`=`~-15.5` which try to match the Illuminant E (those neutral values are not 
+ideal and perhaps the white-balance implementation could be improved)
 
-### Debug/Use OCIO Log Transform
+![Close up diagram of the CIE 1960 UCS with the planckian locus iso lines visble](https://upload.wikimedia.org/wikipedia/commons/d/d7/Planckian-locus.png)
 
-Switch to use the HLSL transform being an exact match to the OCIO `log2Transform`.
 
-Does not create any change visually.
+### Post-Grading/...
 
-### Debug/Apply Outset
+Grading modifications applied after AgX on display encoded data. This will
+introduce skews, clipping and other artefacts.
 
-Not originally included in the first AgX version but should be in the future.
-Restore chroma and avoid having to use Punchy saturation.
-Might bring back some hue skews so better left off. 
+Not recommended to use or with very small values, but can help achieve a stronger
+artistic look.
+
+All parameters are described the same as for the Pre-Grading section.
 
 ### Debug/CAT Method
 
-Chromatic Adaptation Transform method to chose for whitepoint conversion.
+Chromatic Adaptation Transform method to chose for whitepoint conversion (when
+there is a whitepoint conversion between input and output colorspace.)
 
 Default is Bradford and doesn't need to be changed.
 
-
 # Developer
 
 Developer documentation can be found in [doc/DEV.md](doc/DEV.md).

obs/doc/DEV.md

@@ -3,13 +3,13 @@
 # Introduction.
 
 - `AgX.lua` : direct interface with OBS used for building the GUI
-- `AgX.hlsl` : GPU shader with the actual AgX code.
-- `colorspace.hlsl` : side-library imported in `AgX.hlsl`
-  - this is actually the public interface of the `colorscience/` "package".
-- `colorscience/` library of hlsl modules for color manipulation. some of the modules
-are code-generated and not intended to be edited directly. Directly editable modules are :
-  - `math.hlsl`
-  - `cctf.hlsl`
+- `AgX.hlsl` : top-level GPU shader used in the lua script.
+
+With that you will find additional hlsl modules that are all imported in `AgX.hlsl` :
+
+- `lib_colorscience.hlsl`: library of hlsl modules for color manipulation
+  - `_lib_colorscience/`: some of the modules are procedurally-generated and not 
+   intended to be edited directly (see header comment).
 
 The "procedurally" generated code can be found in the [../src/](../src) directory.