This repository has been archived by the owner on Jan 7, 2023. It is now read-only.
-
Notifications
You must be signed in to change notification settings - Fork 9
/
blueshift.texinfo
2160 lines (1774 loc) · 69.8 KB
/
blueshift.texinfo
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
\input texinfo @c -*-texinfo-*-
@c %**start of header
@setfilename blueshift.info
@settitle blueshift
@afourpaper
@documentencoding UTF-8
@documentlanguage en
@finalout
@c %**end of header
@c --- start of do not touch ---
@set DOCDIR /usr/share/doc
@set PKGNAME blueshift
@c --- end of do not touch ---
@dircategory Ergonomy
@direntry
@c * blueshift: (blueshift). Automatically adjust the colour temperature
* blueshift: (blueshift). The grand unified dynamic colour adjustment framework
@end direntry
@copying
Copyright @copyright{} 2014, 2015, 2016, 2017 Mattias Andrée
@quotation
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with no
Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
Texts. A copy of the license is included in the section entitled
``GNU Free Documentation License''.
@end quotation
@end copying
@ifnottex
@node Top
@c @top blueshift -- Automatically adjust the colour temperature
@top blueshift -- The grand unified dynamic colour adjustment framework
@insertcopying
@end ifnottex
@titlepage
@title blueshift
@c @subtitle Automatically adjust the colour temperature
@subtitle The grand unified dynamic colour adjustment framework
@author by Mattias Andrée (maandree)
@page
@center `The possibilities are... like endless.' -- Scootaloo
@vskip 0pt plus 1filll
@insertcopying
@end titlepage
@contents
@menu
* Overview:: Brief overview of @command{blueshift}.
* Invoking:: Invocation of @command{blueshift}.
* Signals:: Signals handled by @command{blueshift}.
* Configuration API:: How to write configuration files.
* Configuration examples:: Example configuration files.
* Related software:: Software related to @command{blueshift}.
* Terminology:: Related terminology.
* GNU Free Documentation License:: Copying and sharing this manual.
@end menu
@node Overview
@chapter Overview
Inspired by Redshift, Blueshift adjusts the colour
temperature of your monitor according to brightness
outside to reduce eye strain and make it easier to
fall asleep when going to bed. It can also be used
to increase the colour temperature and make the
monitor bluer, this helps you focus on your work.
Blueshift is not user friendly and it is not
meant to be. Blueshift does offer limited
use of command line options to apply settings,
but it is really meant for you to have configuration
files (written in Python 3) where all the policies
are implemented, Blueshift is only meant to provide
the mechanism for modifying the colour curves.
Blueshift neither provides any means of automatically
getting your geographical position; the intention is
that you should implement that in the policy yourself
using library which can do that. Additionally
Blueshift provides not safe guards from making your
screen unreadable or otherwise miscoloured; and
Blueshift will never, officially, add support
specifically for any proprietary operating system.
Blueshift is fully extensible so it is possible to
make extensions that make it usable under unsupported
systems, the base code is written in Python 3 without
calls to any system dependent functions.
If Blueshift does not work for you for any of these
reasons, you should take a look at Redshift.
@node Invoking
@chapter Invoking
Blueshift uses argparser to read options from the
commnad line. It inherits a few properaties from this:
abbreviations are supported, you only need to type the
beginning of the long options so that the rest can
be filled in unambiguously by the program; @option{--}
can be used, as usual, to make all following options
being parsed as just arguments; and @option{++} works
like @option{--}, except it only allied to the next
option. Any argument that is not parsed as an option
for Blueshift is passed onto the configuration script.
Blueshift recognises the following options:
@table @option
@item -c
@itemx --configurations FILE
Select configuration script. This defaults to the
first file of the following the exists:
@itemize @bullet
@item @file{$XDG_CONFIG_HOME/blueshift/blueshiftrc}
@item @file{$HOME/.config/blueshift/blueshiftrc}
@item @file{$HOME/.blueshiftrc}
@item @file{/etc/blueshiftrc}
@end itemize
Blueshift does not check the user home, rather it
checks @env{HOME} which should be the user home, unless
you change it yourself.
You update the configuration file you can send a
SIGUSR1 signal to reload it.
@item -p @c the long name of option is inspired from openntpd
@itemx --panic-gate
@itemx --panicgate
Applies the settings directly instead of transitioning
into the initial settings. There is not option for doing
this when the program exists. But you press @kbd{Control+c}
twice, or send SIGTERM twice, to skip transition into
default settings.
@item -h
@itemx -?
@itemx --help
Prints help information.
@item -C
@itemx --copying
@itemx --copyright
Prints copyright information.
@item -W
@itemx --warranty
Prints non-warranty information,
included in the copyright information.
@item -v
@itemx --version
Prints the name of the program and the
installed version of the program
@end table
Blueshift also supports a few options
for ad-hoc settings. These are ignored
(unless fetched by the configuration file)
if @option{-c} (@option{--configurations})
is used.
@table @option
@item -g
@itemx --gamma RGB
Apply gamma correction to the colour curves.
All values in the three colour curves are raised
to the power of 1 divided by @code{RGB}. Assuming
no values in the curves are larger than 1 (100 %)
the curves are bent upwards if @code{RGB} is larger
than 1.
@item -g
@itemx --gamma R:G:B
This works as @option{--gamma RGB}, except the
gamma is applied separately for the three colour
curves. If we want to apply the 0,9 gamma to the
red colour component, and 1,1 and 1,2 for the
green and blue colour components, respectively use
@option{-g 0.9:1.1:1.2} or @option{-gamma 0.9:1.1:1.2}.
@item -b
@itemx --brightness RGB
This multiplies all values in the colour curves
with @env{RGB}, effectively making the display
@env{RGB} times as bright. Values larger than 1,
will be clipped to 1. This is indented to be used
to make the screen slightly darker during the night.
@item -b
@itemx --brightness R:G:B
This option is to @option{--brightness RGB} as
@option{--gamma R:G:B} is to @option{--gamma RGB}.
@item +b
@itemx ++brightness Y
This option works as @option{--brightness RGB},
except the CIE xyY colour spaces is used instead
of sRGB and will probably make the colour curves
look better.
@item -t
@itemx --temperature TEMP
Changes the colour tempurature to @code{TEMP}
Kelvin. The standard colour tempurature is
6500 K@footnote{Or actually 6504 K using revised
constants in Planck's law}. If not specified,
the colour temperature will be 3700 K during
high night and 6500 K during the high day.
@item -l
@itemx --location LAT:LON
Specify your geographical coordinates. This
is used to determine how dark it is outside.
@env{LAT} is the latitude, floating point
measured in degrees celestial northwards from
the equator. It is negative if you are on the
southern hemisphere. @env{LON} is the
longitude, floating point measured in degrees
eastwards from Greenwich. Negative if you
are on the west side of the Earth.
@item -r
@itemx --reset
Transition from the specified settings to
normal, clean, settings.
@item -o
@itemx --output
@itemx --crtc CRTC
Select CRTC to apply changes to. This is
comma separated list, and multiple options
may be used. It is best to start one
instance per monitor with colour calibration.
Be aware than under X — using the Resize and
Rotate (RandR) extension@footnote{Don't be
fooled by the name, it can actually do anything
that has to do with monitor control.} — the
primary monitor is reported to have the zeroth
CRTC. But under TTY — using DRM — this is no
concept of primary monitors, and thus the CRTC
indices can slightly different.
@end table
@option{-g}, @option{-b}, @option{+b}, and
@option{-t} can be use twice, each, to use
different settings during the night and during
the day. While this is possible for gamma,
it is not recommended. The purpose of gamma
is to adjust the same error that are present
in minors and make all colours look correct
in relation to each other.
@node Signals
@chapter Signals
@command{blueshift}, by default in continuous
mode, implements special support for three
signals:
@table @asis
@item SIGTERM
Fades out the settings and exits the first
time SIGTERM is received. If SIGTERM is
received again, Blueshift immediately
resets effects and exits.
@kbd{Control+c} is treated as SIGTERM.
@item SIGTSTP
@itemx SIGCONT
Blueshift does implement special handling
of the termporary stop signal (SIGTSTP),
or continue signal (SIGCONT). So if you send
SIGTSTP to Blueshift it pause until you send
SIGCONT.
With usual TTY settings, the terminal sends
SIGTSTP when @kbd{Control+z} is processed.
Shells can send SIGCONT if you type either
of @code{%}, @code{fg}, @code{%blueshift} or
@code{fg blueshift}. @code{bg} or
@code{bg blueshift} can be used to continue
in the background instead of in the foreground.
@item SIGUSR1
Reloads the configuration script.
@item SIGUSR2
Disables or enables Blueshift.
@end table
@node Configuration API
@chapter Configuration API
@menu
* Configuration variables:: Configuration variables.
* Colour curve manipulators:: Configuration functions colour adjustments.
* Custom colour curve manipulators:: Creating custom colour adjustment functions.
* Preexisting adjustments:: Using preexisting adjustment, in use and ICC.
* Applying colour curves:: Appying colour adjustments to the video drivers.
* Hardware detection:: Detecting connected monitors.
* Backlight:: Adjusting monitor backlight.
* Continuous mode:: Creating continuous mode configurations.
* Solar time:: Solar functions, such as elevation calcuation.
* Weather:: Making weather dependent settings.
* Running without X:: Configuration options for running without X.
* Optimising:: Functions that can be used to optimise performance.
* Interpolation:: Interpolation functionised curves.
* Temperature constants:: Predefined colour temperature values.
@end menu
@node Configuration variables
@section Configuration variables
Blueshift has three colour curves:
@table @code
@item r_curve
The curve for the red colour component.
@item g_curve
The curve for the green colour component.
@item b_curve
The curve for the blue colour component.
@end table
These are @code{i_size} sized floating point
lists, where 0 is the darkest colour and 1
is the brightest colour. Values outside this
range are clipped unless @code{clip_result}
is set to @code{False}. By calling @code{clip}
this clipping is done independently of the value
of @code{clip_result}. @code{clip} optionally
takes one or three arguments, if one, nothing
will happen if it is @code{False}, if three,
nothing will happen for the red, green and
blue colour curves if the first, second and
third arguments, respectively, is @code{False}.
When applied these values are automatically
translated to appropriate integer values:
[0, @code{o_size} - 1].
Additionally if the variable @code{panicgate}
is @code{True}, there is no fading when the program
starts. And @code{conf_opts} is a list of command line
arguments passed onto the configuration script; and
@code{conf_storage} is a dictionary can be used to
store information is required to survive a
configuration reload, such as replaced functions.
If you want to use the settings intended for ad-hoc
mode, set @code{uses_adhoc_opts} to @code{True}. This
lets you use @code{parser}, which is an instance of
@code{ArgParser} (from the argparser library) which
@code{parser} and @code{support_alternatives} already
invoked, without a warning being printed. If you do
not do this, @code{parser} will be @code{None} at the
time @code{periodically} is first invoked by Blueshift.
@node Colour curve manipulators
@section Colour curve manipulators
Blueshift provides a set of functions to
manipulate these curves:
@table @code
@item rgb_contrast(rgb)
Adjusts the contrast to @code{rgb}. This
function assumes the black is 0, and white
is 1, so you should apply this before brightness.
Note: This does not correspond to the contrast
on monitors control panels used to calibrate
the white point.
@item rgb_contrast(r, g, b)
Adjusts the contrast to @code{r}, @code{g}
and @code{b} on the red, green and blue colour
curves, respectively. This function assumes the
black is 0, and white is 1, so you should apply
this before brightness.
Note: This does not correspond to the contrast
on monitors control panels used to calibrate
the white point.
@item cie_contrast(rgb)
Adjusts the contrast to @code{rgb}.
The function calculate the values by using
the CIE xyY colour space instead of the sRGB
colour space. This function assumes the black
is 0, and white is 1, so you should apply
this before brightness.
Note: This does not correspond to the contrast
on monitors control panels used to calibrate
the white point.
@item cie_contrast(r, g, b)
Adjusts the contrast to @code{r}, @code{g}
and @code{b} on the red, green and blue
colour curves, respectively.
The function calculate the values by using
the CIE xyY colour space instead of the sRGB
colour space. This function assumes the black
is 0, and white is 1, so you should apply
this before brightness.
Note: This does not correspond to the contrast
on monitors control panels used to calibrate
the white point.
@item rgb_brightness(rgb)
Adjusts the brightness to @code{rgb}.
Note: This does not correspond to the contrast
on monitors control panels used to calibrate
the white point.
Note: This does not correspond to the brightness
on monitors control panels used to calibrate
the black point point, rather it corresponds
to the contrast on monitors control panels
used to calibrate white point.
@item rgb_brightness(r, g, b)
Adjusts the brightness to @code{r}, @code{g}
and @code{b} on the red, green and blue colour
curves, respectively.
Note: This does not correspond to the brightness
on monitors control panels used to calibrate
the black point point, rather it corresponds
to the contrast on monitors control panels
used to calibrate white point.
@item cie_brightness(rgb)
Adjusts the brightness to @code{rgb}.
The function calculate the values by using
the CIE xyY colour space instead of the sRGB
colour space.
Note: This does not correspond to the brightness
on monitors control panels used to calibrate
the black point point, rather it corresponds
to the contrast on monitors control panels
used to calibrate white point.
@item cie_brightness(r, g, b)
Adjusts the brightness to @code{r}, @code{g}
and @code{b} on the red, green and blue
colour curves, respectively.
The function calculate the values by using
the CIE xyY colour space instead of the sRGB
colour space.
Note: This does not correspond to the brightness
on monitors control panels used to calibrate
the black point point, rather it corresponds
to the contrast on monitors control panels
used to calibrate white point.
@item linearise()
Converts the colour curves from sRGB to
linear RGB. sRGB is the default colour space.
@item linearise(rgb)
Converts the colour curves from sRGB to
linear RGB if @code{rgb} is @code{True}.
sRGB is the default colour space.
@item linearise(r, g, b)
Converts the colour curves from sRGB to
linear RGB, but only for the red, green
and blue colour curves if @code{red},
@code{green}, @code{blue} is @code{True},
respectively. sRGB is the default colour
space.
@item standardise()
Converts the colour curves from linear RGB to
sRGB, the default colour space.
@item standardise(rgb)
Converts the colour curves from linear RGB to
sRGB, the default colour space, if @code{rgb}
is @code{True}.
@item standardise(r, g, b)
Converts the colour curves from linear RGB to
sRGB, the default colour space, but only for
the red, green and blue colour curves if
@code{red}, @code{green}, @code{blue} is
@code{True}, respectively.
@item gamma(rgb)
Adjusts the gamma to @code{rgb}.
@item gamma(r, g, b)
Adjusts the gamma to @code{r}, @code{g} and
@code{b} on the red, green and blue colour
curves, respectively.
@item negative()
Reverse the colour curves on the encoding axis.
This creates a negative image with preserved gamma.
@item negative(rgb)
Reverse the colour curves on the encoding axis
if @code{rgb} is @code{True}.
@item negative(r, g, b)
Reverse the red, green and blue colour curves
on the encoding axis if @code{r}, @code{g} and
@code{b} are @code{True}, respectively.
@item rgb_invert()
Inverts the all values on the colour curves.
This creates a negative image with inverted gamma.
@item rgb_invert(rgb)
Inverts the all values on the colour curves
if @code{rgb} is @code{True}.
@item rgb_invert(r, g, b)
Inverts the all values on the red, green and
blue colour curves if @code{r}, @code{g} and
@code{b} are @code{True}, respectively.
@item cie_invert()
Inverts the all values on the colour curves
using the CIE xyY colour space instead of sRGB.
@item cie_invert(rgb)
Inverts the all values on the colour curves
using the CIE xyY colour space instead of sRGB,
if @code{rgb} is @code{true}.
@item cie_invert(r, g, b)
Inverts the all values on the red, green and
blue colour curves using the CIE xyY colour
space instead of sRGB if @code{r}, @code{g} and
@code{b} are @code{True}, respectively.
@item sigmoid(rgb)
An inverted sigmoid curve function is applied
to the values of in colour curves if @code{rgb}
is not @code{None}, @code{rgb} is the sigmoid
curve multiplier.
@item sigmoid(r, g, b)
An inverted sigmoid curve function is applied
to the values of in the red, green and blue
colour curves if @code{r}, @code{g} and @code{b}
are not @code{None}, respectively. @code{r},
@code{g} and @code{b} are the sigmoid curve
multipliers for the red, green and blue colour
curves, respectively.
@item rgb_limits(rgb_min, rgb_max)
Changes the black point to @code{rgb_min}, and
the white point to @code{rgb_max}.
@code{rgb_min} corresponds to the brightness
on monitor control panels used to calibrate the
black point. @code{rgb_max} corresponds to the
contrast on monitor control panels used to
calibrate the white point.
@item rgb_limits(r_min, r_max, g_min, g_max, b_min, b_max)
Changes the black point to (@code{r_min},
@code{g_min}, @code{b_min}), and the white
point to (@code{r_max}, @code{g_max}, @code{b_max}).
@item cie_limits(rgb_min, rgb_max)
Changes the black point to @code{rgb_min}, and
the white point to @code{rgb_max}, using the
CIE xyY colour space instead of sRGB.
@item cie_limits(r_min, r_max, g_min, g_max, b_min, b_max)
Changes the black point to (@code{r_min},
@code{g_min}, @code{b_min}), and the white
point to (@code{r_max}, @code{g_max},
@code{b_max}), using the CIE xyY colour space
instead of sRGB.
@item manipulate(rgb)
Applies the function @code{rgb} : float
@click{} float to the colour curves.
Nothing is done if @code{rgb} is @code{None}.
@item manipulate(r, g, b)
Applies the functions @code{r}, @code{g} and
@code{b} : float @click{} float to the red, green
and blue colour curves, respectively.
Nothing is done for the red, green and blue
colour curves if @code{red}, @code{green} and
@code{blue} are @code{None}, respectively.
@item cie_manipulate(rgb)
Applies the function @code{rgb} : float @click{}
float to Y component (illumination) of the colour
curves when converted to CIE xyY.
Nothing is done if @code{rgb} is @code{None}.
@item cie_manipulate(r, g, b)
Applies the function @code{r}, @code{g} and
@code{b} : float @click{} float to Y component
(illumination) of the red, green and blue colour
curves, respectively, when converted to CIE xyY.
Nothing is done for the red, green and blue
colour curves if @code{red}, @code{green} and
@code{blue} are @code{None}, respectively.
@item temperature(temperature, algorithm)
Applies the a blackbody colour temperature of
@code{temperature}@footnote{Actually multiplied
by 1,000556328, due to revisions of natural
constants.} Kelvin. Where the white point
for that temperature is calculates by
the function @code{algorithm} : @code{temperature}
@click{} (red, green, blue). When the white
point has been calculates, its components
are used as parameters in a componentwise
brightness adjustment.
There are a few algorithm for calculating the
white point included:
@table @code
@item series_d(temperature)
Can only calculate the white point correctly for
temperatures inside [4000, 25000]. The CIE illuminant
series D is used to calculate the white point.
@item simple_whitepoint(temperature)
Can only calculate the white point accurately for
temperatures inside [1000, 40000]. A mathematical
model of the @code{cmf_10deg} function is used.
@item cmf_2deg(temperature)
Uses a lookup table with linear interpolation to
calculate temperatures inside [1000, 40000].
CIE 1931 2 degree CMF is used.
@item cmf_10deg(temperature)
Uses a lookup table with linear interpolation to
calculate temperatures inside [1000, 40000].
CIE 1964 10 degree CMF is used. This is the
preferred algorithm.
@item redshift(temperature, old_version, linear_interpolation = False)
Uses the lookup table from Redshift with linear
interpolation. If @code{old_version} is @code{True}
the table Redshift<=1.8 is used, which is limited
to [1000, 10000], and is not that accurate. Otherwise
(the default) the table from Redshift>1.8 is used,
which is limited to [1000, 25100], and is accurate.
If @code{linear_interpolation} is @code{False}
(the default) the sRGB colour space is used for
interpolation, otherwise linear RGB is used.
@end table
Some of these algorithms (including @code{cmf_10deg})
are not very good by themself and should be wrapped
with @code{divide_by_maximum} or @code{clip_whitepoint}
((red, green, blue) @click{} (red, green, blue) functions.)
For example, instead of using @code{cmf_10deg}, you can use
@code{lambda t : clip_whitepoint(divide_by_maximum(cmf_10deg(t)))}.
@item rgb_temperature(temperature, algorithm)
This function is a synonym for @code{temperature}.
@item cie_temperature(temperature, algorithm)
This works the same way as @code{temperature},
except that subpixel brightness adjustment is
done in CIE xyY colour space rather than sRGB.
You probability do not want to use this variant
of @code{temperature}.
@item lower_resolution(x, y)
Emulate low resolution. @code{x} is the number of
colours to emulate that each subpixel can have.
@code{y} does the same thing as @code{x}, except
on the output axis rather than the encoding axis.
For arguments taht are set to @code{None}, the
default value will be used.
@item lower_resolution(rx, ry, gx, gy, bx, by)
This works the same way as @code{lower_resolution(x, y)},
except the subpixels are controlled individually.
@code{rx} and @code{ry} are @code{x} and @code{y}
for the red subpixel, and analogously for @code{gx}
and @code{gy} for green, and @code{bx} and @code{by}
for blue. For arguments taht are set to @code{None},
the default value will be used.
@end table
Keep in mind that the order your call the
function matters. For example, adjusting
the gamma before the brightness does not
yeild the same result as in the reverse
order, the latter is the correct way to
apply gamma correction.
Before performing adjusts you must (not required
the very first time) reset the curves by invoking
@code{start_over} (no parameters.) Otherwise the
adjustments will accumulate.
@node Custom colour curve manipulators
@section Custom colour curve manipulators
If you want to write your own functions
@code{curves(r, g, b)} returns a tuple
containing the tuples @code{(r_curve, r)},
@code{(g_curve, g)} and @code{(b_curve, b)}.
To make this easier Blueshift provies a set
of functions used to convert colour space:
@table @code
@item linear_to_standard(r, g, b)
Convert [0, 1] linear RGB to [0, 1] sRGB
@item standard_to_linear(r, g, b)
Convert [0, 1] sRGB to [0, 1] linear RGB
@item ciexyy_to_ciexyz(x, y, Y)
Convert CIE xyY to CIE XYZ
@item ciexyz_to_ciexyy(X, Y, Z)
Convert CIE XYZ to CIE xyY
@item ciexyz_to_linear(X, Y, Z)
Convert CIE XYZ to [0, 1] linear RGB
@item linear_to_ciexyz(r, g, b)
Convert [0, 1] linear RGB to CIE XYZ
@item srgb_to_ciexyy(r, g, b)
Convert [0, 1] sRGB to CIE xyY
@item ciexyy_to_srgb(x, y, Y)
Convert CIE xyY to [0, 1] sRGB
@item ciexyz_to_cielab(x, y, z)
Convert CIE XYZ to CIE L*a*b*
@item cielab_to_xiexyz(l, a, b)
Convert CIE L*a*b* to CIE XYZ
@end table
All these functions return lists with
the three colour components, not tuples.
Input and output is one colour instance.
If you want to calculated the distance (difference)
between two colours, you can use @code{delta_e}. It
has two parameters, each is red–green–blue-tuple of
an sRGB colour. The just notice difference is circa
2,3.
@node Preexisting adjustments
@section Preexisting adjustments
If you have an ICC profile for calibration (applied last)
or want to use one for as a video filter (applied first),
the function @code{load_icc} can be used to load an ICC
profile file. @code{load_icc} takes one argument, the
pathname of the ICC profile file; the function returns
a fuction that can be invoked to apply the profile.
Alternatively, you can use either of the functions:
@table @code
@item parse_icc(data)
Parse raw (series of bytes) ICC profile data into a function
that applies the profile when invoked.
@item get_current_icc_raw()
@itemx get_current_icc_raw(display)
Load the raw data for the currently applied ICC profiles,
stored on the X server. This function returns a list of
3-tuples, each tuple contains the index of a screen,
the index of a monitor and the raw data (series of bytes)
of the ICC profile for indicated monitor on the indicated
screen. Monitors without profiles are not listed.
Associated ICC profile is mapped as properties of the
root window of X screens. The ICC profile of a primary
monitor in a screen is saved as a property named
@var{_ICC_PROFILE}, the secondary monitor is stored as
@var{_ICC_PROFILE_1}, the tertiary monitor is stored as
@var{_ICC_PROFILE_2}, and so on.
If @code{display} is not specified or is @code{None},
the current X display will be used. Otherwise, the
display indicated by @code{display} will be used.
@item get_current_icc()
@itemx get_current_icc(display)
This function works like @code{get_current_icc_raw}, except
rather than returning raw profile data it returns functions
that apply the profiles when invoked.
If @code{display} is not specified or is @code{None},
the current X display will be used. Otherwise, the
display indicated by @code{display} will be used.
@end table
If you have multiple profiles you want to interpolate
or want to, possible with an interpolation, apply a
profile partially, that is, interpolate between it an
an identity profile, you can use the function
@code{make_icc_interpolation}. It takes your profiles
as one argument, as a list, and outputs a function
that applies an interpolation of the profiles,
it takes to arguments: the timepoint and the filter
alpha. The timepoint is normally a [0, 1] floating point
of the dayness level, this means that you only have two
ICC profiles, but you have multiple profiles, in such
case profile the floor of the timepoint value is takes
as the index of the first profile to use in the
interpolation as well as the following profile (first
profile if the last profile was select). They are
interpolated linearly. The filter alpha is a [0, 1]
floating point of the degree to which the profile should
be applied.
If you want to apply your adjustments on top of the
current colour adjustments, you can use the functions
@code{randr_get} or @code{vidmode_get}. @code{randr_get}
and @code{vidmode_get} have three optional parameters:
@code{crtc}, @code{screen} and @code{display}, which are
the CRTC of the monitor to read from, the screen to which
the monitor belongs and the X display to use, respectively.
The functions return a parameterless function that applies
adjustsments that were applied at the time of invocation
of @code{randr_get} or @code{vidmode_get} to the current
working curves. If not specified, the zeroth (primary) CRTC,
the zeroth screen and the current X display is used, for
@code{crtc}, @code{screen} and @code{display} respectively.
The current X display is also used if @code{display} is
@code{None}.
@node Applying colour curves
@section Applying colour curves
To apply a colour curve to the display
server, invoke the @code{randr} function, or
@code{vidmode}@footnote{@code{vidmode} has
the same API as @code{randr}, but it only
supports using the zeroth CRTC.};
@code{print_curves} can be used to print
the curves to stdout instead (for debugging).
These functions apply the curves to all
monitors in the default screen (screen 0),
but you can also use select monitors by
specifying each monitor in as separate
arguments. The monitors are indexed from
zero. The screen by can be selected by
adding the argument @code{screen = X},
where @code{X} is the index of the screen,
also indexed from zero. Additionally,
you can add the argument @code{display = X},
where @code{X} is the X display to use,
or @code{None} (default) for the current
X display. @code{print_curves} has a fourth
optional parameter: @code{compact}, if it
is set to @code{True}, the curves will be
printed with run-length encoding.
If you want to write your own curve flushing
fucntion @code{translate_to_integers} can be
used, it returned the colour curves converted
from floating point lists to integer lists in
a tuple of three (red, green and blue.) Replace
the parameterless function @code{close_c_bindings}
to make it free all used resource, this is
invoked when Blueshift exits.
When Blueshift exists, it invoked the
parameterless function @code{reset} which
you should replace. By default it resets
the colour curves and flushes it to all
monitors. To restrict which monitors it
applies the changes to replace
@code{monitor_controller} with a parameterless
function that sends the colour curves to
the desired monitors to the display server.
This is only done if Blueshift runs in
continuous mode.
@node Hardware detection
@section Hardware detection
To support multiple monitors in a dynamic way,
the function @code{list_screens} can be used.
@code{list_screens} has two optional parameters
and returns the an instance of the class
@code{Screens}. Instances of @code{Screens} have
one variable: @code{screens}, a list of instances
of the class @code{Screen}. The index of each
screens is their index in @code{screens}.
@code{list_screens}'s first parameter,
@code{method}, selects the method and defaults
to `randr', it also supports the method `drm'.
Its second parameters, @code{display}, is no
effect if `drm' is used for @code{method}, but
otherwise selects the X display to use. If
@code{display} is @code{None}, or is not
specified, the current X display will be used.
Instances of the class @code{Screen} have two
variables: @code{crtc_count}, the number of CRT
controllers used within the screen, and
@code{outputs}, a list of all output ports as
instances of the class @code{Output}. Instances
of @code{Output} have six variables:
@table @code
@item name
The name of the output port.
@item connected
Whether the output is known to be connected
to a monitor.
@item widthmm
The physical width of the monitor, measured
in millimetres. @code{None} if unknown, not
defined or if not connected.
@item heightmm
The physical height of the monitor, measured
in millimetres. @code{None} if unknown, not
defined or if not connected.
@item crtc
The CRT controller index. @code{None} if not
connected.
@item screen
The screen index. @code{None} if not used.
@item edid
The extended display identification data of
the monitor in lower case hexadecimal representations.
@code{None} if not used or not found. If the monitor
is used it is probably found because it is needed
for plug and play support of the monitor.
@end table
The width and height are unknown if the monitor
does not specify them in the EDID if using DRM.
They are not defined the output is a projector.
If using RandR this values are probably not
correct, but the EDID can be parsed, which is
want is done by DRM. The EDID can only specify
whole centrimeters up to 255 cm.
@code{Screens} and @code{Screen} provide a set
of functions for finding the output, and traversal
the CRTC and screen, a monitor is connected to:
@table @code
@item find_by_crtc(index)
Matches outputs by CRTC index. If @code{index}
is @code{None}, it will find unused outputs.
@item find_by_name(name)
Matches outputs by output name.