This is a document describing how redshift works. It might be useful
if the normal docs don't answer a question, or when you want to hack
on the code.


Programs
========

redshift
--------

redshift is a program written in C that tries to figure out the user's
location during startup, and then goes into a loop setting the display
gamma according to the time of day every couple seconds or minutes
(details?).

On systems that support signals, it reacts to the SIGUSR1 signal by
switching to day/night immediately, and when receiving SIGINT or
SIGTERM, it restores the screen gamma (to 6500K).

Redshift knows short and long transitions, short transitions being
used at start and when reacting to signals. Short transitions take
about 10 seconds; long transitions about 50 minutes.

Once running, redshift currently doesn't check location providers
again.


redshift-gtk
------------

redshift-gtk is a small program written in Python that shows a status
icon (what is an appindicator versus a GTK status icon?) (does it
change the icon according to internal program state of redshift? 
doesn't seem so) and run an instance of the "redshift" program, and
will send it SIGUSR1 each time the user clicks the icon.


Alternative Features
====================

Redshift interacts with the rest of the system in two ways: reading
the location, and setting the gamma. Both can be done in different
ways, and so for both areas there are configure options to
enable/disable compilation of the various methods. ./configure --help
shows more about what parts of the program that can be conditionally
compiled.

The two groups of features shall be called: "location providers" and
"adjustment methods".

These are probably not the best names for these things but at least
I've been mostly consistent with the naming throughout the source code
(I hope).

First adjustment methods: There is "randr" which is the preferred
because it has support for multiple outputs per X screen which is lacking
in "vidmode". Both are APIs in the X server that allow for manipulation
of gamma ramps, which is what Redshift uses to change the screen color
temperature. There's also "drm" which allows manipulation of gamma ramps
in a TTY in Linux.

Then there are location providers: "manual" and "geoclue2".
Some time ago there was only one way to specify the
location which had to be done manually with the argument "-l LAT:LON".
Then later, automatic "location providers" were added and the syntax
had to be changed to "-l PROVIDER:OPTIONS" where OPTIONS are arguments
specific to the provider. But to make people less confused about the
change I decided to still support the "-l LAT:LON" syntax, so if the
PROVIDER is a number, the whole thing is parsed as LAT:LON. You could
run redshift with "-l manual:lat=55:lon=12" and get the same effect as
"-l 55:12".

There is currently one automatic location provider, "geoclue".

Lastly, there's the support for configuration files for which there's
no real documentation, but all the options that can be set on the
command line can also be set in the config file.
