document textconf.conf

Signed-off-by: Mattias Andrée <maandree@operamail.com>

1 files changed, 180 insertions, 39 deletions

diff --git a/examples/textconf.conf b/examples/textconf.conf
index a6baf77..8214ff9 100644
--- a/examples/textconf.conf
+++ b/examples/textconf.conf
@@ -12,55 +12,196 @@
 ; Both = (equal sign) and : (colon) are valid key–value delimiters.
 
 
-[blueshift]
+[blueshift] ; General settings and adjustments shared between monitors
+
+adjustment-method-x = randr ; (default) vidmode is also available
+; This is the method used to set and get colour curves for monitors
+; when running in X
+
+adjustment-method-tty = drm ; (default)
+; This is the method used to set and get colour curves for monitors
+; when running in TTY
+
+location = 59.3326 18.0652
+; Your geographical location as GPS coordinates in decimal form. If you
+; are on the south hemisphere the first value should be negative, if you
+; are on the west side of the prime meridian (the Greenwich meridian).
+; If you are not sure about your location you probably find it in your
+; online phone book or on Wikipedia.
+; ("Kristall, vertikal accent i glas och stål" (Crystal, vertical accent
+; in glass and steal) in this example. A glas obelisk, lit from the inside
+; with adjustable colours and a default colour of 5600 K, in the middle
+; of a hyperelliptic roundabout.)
+
+;location = 59.3326$(locateme | cut d ' ' -f 1) 18.0652$(locateme | cut d ' ' -f 2)
+; Just loke above, but use the values as fallback and use the output
+; of the command `locateme` primarily.
+
+
+points = solar 3 -6 ; (default)
+; Adjustment settings have up to two values, one for when the Sun's
+; elevation is above 3° (day) and one for when it is below −6° (night).
+
+;points = solar -18 -12 -6 0 6
+; Adjustment settings have up to five values that depend on the Sun's
+; elevation: at and below −18°, at −12°, at −6°, at 0° and at and above
+; 6°. Interpolation of values are used between these points to give nice
+; transitions.
+
+;points = solar -18 0 3 6 reduce
+; Adjustment settings have up to two values. When the Sun's elevation is
+; at or below −18° the first value is used, when it is at or above 6° the
+; second value is used. Between −18° and 6° interpolation is used to give
+; nice transitions: at 0° two thirds of the first value and one third of
+; the second value is used, and at 3° on third of the first value and two
+; thirds of the second value is used.
+
+;point = time 6:00 10:00 20:00
+; Adjustment settings have up to three values. At 6:00 the first value is
+; used, at 10:00 the second value is used and at 20:00 the third value is
+; used. Between 6:00 and 10:00 interpolation between first and second
+; value is used, between 10:00 and 20:00 interpolation between the second
+; and third valu is used, and between 20:00 and 4:00 interpolation between
+; the third and first value is used.
+
+;points = time 6:00 10:00 20:00 reduce
+; Adjustment settings have up to two values. At 6:00 the first value is
+; used, and at 20:00 the second setting is used. Interpolation is used
+; between between 20:00 and 6:00, but between 6:00 and 20:00 interpolation
+; is used with the adjustment that both the first and the second value
+; is used to 50 % each at 10:00.
+
+; TODO: the following should be possible
+;   points = solar -18 (0) 3 (6) 12 reduce
+;   points = time 6:00 (10:00) 20:00 reduce
+;   points = time 6:00 (10:00) 20:00 (2:00) reduce
+
+
+; For the following settings you can also add the word ‘linear’, just
+; as ‘cie’ can be used on some settings. ‘linear’ (which is supported
+; on all adjustments) performs the adjustments in linear RGB colour
+; space. ‘cie’ (which is only supported where used in this example)
+; performs the adjustments in CIE xyY colour space. ‘linear’ and ‘cie’
+; can be combined but should not be combined as it has no proper meaning.
+; Additional, while possible, ‘linear’ should not be used with ‘linear’,
+; as that too has no proper meaning.
+
+; All of this adjustments can have multiple values, but in this example
+; only ‘temperature’ uses this. We have set “points = solar 3 -6”, which
+; means that the first setting is used during the day and the second is
+; used between civil dusk and civil dawn (night). The other settings
+; only use one value (in this example) which means that those apply all
+; day long.
+
+; The order of adjustments are made in the order they are listed. which
+; means that putting gamma before temperature produces another result
+; than putting temperature before gamma. Monitor specific adjustments
+; are made after these adjustments.
+
+
 temperature = 6500 3600
-contrast = 1
-contrast = 1:1:1 cie
-brightness = 1
-brightness = 1:1:1 cie
-gamma = 1:1:1
-negative = 1:1:1
-negative = 1
-invert = 1:1:1
-invert = 1:1:1 cie
-sigmoid = 4.5
-sigmoid = 4.5:none:4.5
-limits = 0:0:0..1:1:1
-limits = 0:0:0..1:1:1 cie
-;icc = 
-;location = 
-points = time 0:00 10:00 20:00 reduce
-adjustment-method-x = randr
-adjustment-method-tty = drm
+; 6500 K (neutral) during the day, and 3600 during the night.
+
+;contrast = 0.5
+; Converge white and black both halfways to 50 % grey.
+
+;contrast = 1:1:0.5 cie
+; Converge white and black both halfways to 50 % grey,
+; but only on the blue channel.
+
+;brightness = 0.75
+; Reduce the brightness of the white colour to 75 % grey.
+
+;brightness = 1:0.75:1 cie
+; Reduce the brightness of the white colour to 75 % grey,
+; but only on the green channel.
+
+;negative = 1
+; Apply a negative image filter, this reverses the
+; encoding values.
+
+;negative = 1:0:0
+; Apply a negative image filter on the red channel.
+
+;invert = 0:1:1
+; Apply an image inversion filter, this inverts the
+; output values. But do not do it on the red channel.
+
+;invert = 1 cie
+; Apply an image inversion filter.
+
+;sigmoid = 4.5
+; Apply a sigmoid curve (S-curve) correction
+; (cancellation) with a multiplier level of 4,5.
+
+;sigmoid = 4.5:none:4.5
+; Apply a sigmoid curve correction with a multiplier
+; level of 4,5, but not on the green channel.
+
+;gamma = 1.1
+; Apply a gamma filter/correction of level 1,1.
+
+;gamma = 1.2:1.2:1
+; Apply a gamma filter/correction of level 1,2,
+; but not on the blue channel.
+
+;limits = 0.1..0.9
+; Apply a brightness–contrast correction of 90 % black
+; (black is 0; first parameter) and 90 % white (white
+; is 1; second parameter)
+
+;limits = 0:0.1:0.1..1:0.9:0.9 cie
+; Apply a brightness–contrast correction of 90 % black
+; and 90 % white, but not on the red channel.
+
+;icc = /home/user/.config/icc/filter
+; Apply an ICC profile with the pathname
+; /home/user/.config/icc/filter
+
 ; TODO it should be possible to control backlight
 
 
-[monitor 0]
-gamma=1.16:1.15:1.11 default
+; Here begins monitor identification and specific
+; specifc calibrations/filters for the primary monitor.
+
+
+[monitor 0] ; Adjustment method independent settings for monitor 0
+gamma = 1.16:1.15:1.11 default
+; Gamma correction of 1.16 on red, 1.15 on green and 1.11 on blue.
+; ‘default’ is used so that this correction is used when at the
+; beginning of a transition from a clean state to a state with
+; the adjustments in effect, at which time these adjustments will
+; still apply.
+
 ; TODO it should be possible to map to a backlight device
 
-[randr]
-monitor=0
-crtc=0
-screen=0
+[randr] ; RandR specific information for monitor 0
+monitor=0 ; Include [monitor 0]
+crtc=0    ; CRTC 0
+screen=0  ;   in screen 0
+
+[drm] ; DRM specific information for monitor 0
+monitor=0 ; Include [monitor 0]
+crtc=1    ; CRTC 1
+card=0    ;   on graphics card 0
+
 ; TODO it should be possible to use connector name and EDID
 
-[drm]
-monitor=0
-crtc=1
-card=0
+
+; Here begins monitor identification and specific
+; specifc calibrations/filters for the secondary monitor.
 
 
-[monitor 1]
-gamma=1.10:1.16:1.10 default
+[monitor 1] ; Adjustment method independent settings for monitor 1
+gamma = 1.10:1.16:1.10 default
 
-[randr]
-monitor=1
-crtc=1
-screen=0
+[randr] ; RandR specific information for monitor 1
+monitor=1 ; Include [monitor 1]
+crtc=1    ; CRTC 1
+screen=0  ;   in screen 0
 
-[drm]
-monitor=1
-crtc=0
-card=0
+[drm] ; DRM specific information for monitor 1
+monitor=1 ; Include [monitor 1]
+crtc=0    ; CRTC 0
+card=0    ;   on graphics card 0