diff options
| -rw-r--r-- | DESIGN | 95 | ||||
| -rw-r--r-- | HACKING | 3 | ||||
| -rw-r--r-- | redshift.1 | 87 | ||||
| -rw-r--r-- | src/location-geoclue.c | 4 | ||||
| -rw-r--r-- | src/location-gnome-clock.c | 4 | ||||
| -rw-r--r-- | src/location-manual.c | 3 | ||||
| -rw-r--r-- | src/redshift.c | 7 |
7 files changed, 187 insertions, 16 deletions
@@ -0,0 +1,95 @@ +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. + + +gtk-redshift +------------ + +gtk-redshift 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. + +NOTE: some features have to be disabled explicitely, like +--disable-gnome-clock to prevent the gnome-clock code from being built +in. + +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 some features that are lacking in "vidmode" (IIRC it +has to do with multiple monitors). 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 "wingdi" which is +for the Windows version. + +Then there are location providers: "manual", "gnome-clock" and +"geoclue". 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". + +So there are currently two automatic location providers "gnome-clock" +and "geoclue". From the beginning I was looking for a way to get the +location automatically (from e.g. GPS) and Geoclue seemed like a good +idea, but upon closer investigation it turned out to be horribly +unstable. At this time GNOME had a clock applet which was present by +default (at least in Ubuntu) that allowed the user to set a home town. +This setting was registered in the gconf key +/apps/panel/applets/clock_screen*/prefs/cities. +The idea was to use this information until Geoclue had become more +stable. To me, it always was a hack. Now that the Clock applet has +gone (at least in Ubuntu) the "gnome-clock" makes little sense and +causes a lot of trouble, so I really want to get rid of it as soon as +possible. The problem is that Geoclue is still problematic for some +people. + +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. @@ -0,0 +1,3 @@ +- verbose flag is (currently) only held in redshift.c; thus, write all + verbose messages there + @@ -1,20 +1,26 @@ -.TH REDSHIFT: "1" "August 2010" "redshift" "User Commands" +.TH REDSHIFT: "1" "October 2011" "redshift" "User Commands" .SH NAME redshift \- Set color temperature of display according to time of day. .SH SYNOPSIS .B redshift -\fI-l LAT:LON -t DAY:NIGHT \fR[\fIOPTIONS\fR...] +\fI[-l LAT:LON | -l PROVIDER:OPTIONS] [-t DAY:NIGHT] \fR[\fIOPTIONS\fR...] .SH DESCRIPTION .B redshift adjusts the color temperature of your screen according to your -surroundings. This may help your eyes hurt less if you are working in -front of the screen at night. +surroundings. This may help your eyes hurt less or reduce the risk for +delayed sleep phase syndrome if you are working in front of the screen +at night. The color temperature is set according to the position of the sun. A different color temperature is set during night and daytime. During twilight and early morning, the color temperature transitions smoothly from night to daytime temperature to allow your eyes to slowly -adapt. +adapt over a period of about an hour. At night the color temperature +should be set to match the lamps in your room. This is typically a low +temperature at around 3000K\-4000K (default is 3700K). During the day, +the color temperature should match the light from outside, typically +around 5500K\-6500K (default is 5500K). The light has a higher +temperature on an overcast day. .SH OPTIONS .TP \fB\-h\fR @@ -26,8 +32,8 @@ Verbose output \fB\-V\fR Show program version .TP -\fB\-b\fR N -Screen brightness to apply (max is 1.0) +\fB\-b\fR DAY:NIGHT +Screen brightness to apply (between 0.1 and 1.0) .TP \fB\-c\fR FILE Load settings from specified configuration file @@ -36,9 +42,11 @@ Load settings from specified configuration file Additional gamma correction to apply .TP \fB\-l\fR LAT:LON -Your current location +Your current location, in degrees, given as floating point numbers, +towards north and east, with negative numbers representing south and +west, respectively. .TP -\fB\-l\fR PROVIDER +\fB\-l\fR PROVIDER[:OPTIONS] Select provider for automatic location updates (Type `list' to see available providers) .TP @@ -48,6 +56,7 @@ Method to use to set color temperature .TP \fB\-o\fR One shot mode (do not continously adjust color temperature) +.TP \fB\-O\fR TEMP One shot manual mode (set color temperature) .TP @@ -66,14 +75,64 @@ color temperature to a value higher than this results in more blue light, and setting a lower value will result in more red light. -Default values: +Default temperature values: .IP -Daytime temperature: 5500K -Night temperature: 3700K +Daytime: 5500K, night: 3700K +.SH CONFIGURATION FILE +A configuration file with the name `redshift.conf' can optionally be +placed in `~/.config/'. The file has standard INI format. General +program options are placed under the `redshift' header, while options +for location providers and adjustment methods are placed under a +header with the name of that provider or method. General options are: +.TP +\fBtemp-day\fR = integer +Daytime temperature +.TP +\fBtemp-night\fR = integer +Night temperature +.TP +\fBtransition\fR = 0 or 1 +Disable or enable transitions +.TP +\fBbrightness-day\fR = 0.1\-1.0 +Screen brightness at daytime +.TP +\fBbrightness-night\fR = 0.1\-1.0 +Screen brightness at night +.TP +\fBgamma\fR = R:G:B +Gamma adjustment to apply +.TP +\fBadjustment-method\fR = name +Select adjustment method. Options for the adjustment method can be +given under the configuration file heading of the same name. +.TP +\fBlocation-provider\fR = name +Select location provider. Options for the location provider can be +given under the configuration file heading of the same name. +.PP +Options for location providers and adjustment methods can be found in +the help output of the providers and methods. .SH EXAMPLE Example for Copenhagen, Denmark: .IP -$ redshift -l 55.7:12.6 -t 5700:3600 -g 0.8 -m vidmode -v +\fB$\fR redshift -l 55.7:12.6 -t 5700:3600 -g 0.8 -m vidmode -v +.PP +An example configuration file with the same effect as the above +command line: +.IP +.nf +[\fBredshift\fR] +temp-day=5700 +temp-night=3600 +gamma=0.8 +adjustment-method=vidmode +location-provider=manual + +[\fBmanual\fR] +lat=55.7 +lon=12.6 +.fi .SH AUTHOR .B redshift was written by Jon Lund Steffensen <jonlst@gmail.com>. @@ -85,6 +144,6 @@ License, version 3. .SH BUGS Please report bugs to <https://bugs.launchpad.net/redshift> .SH KNOWN ISSUES -Redshift won’t affect the color of your cursor when your graphics driver +Redshift won't affect the color of your cursor when your graphics driver is configured to use hardware cursors. Some graphics drivers have an option to disable hardware cursors in xorg.conf. diff --git a/src/location-geoclue.c b/src/location-geoclue.c index 4050f41..6aedfcd 100644 --- a/src/location-geoclue.c +++ b/src/location-geoclue.c @@ -117,6 +117,10 @@ location_geoclue_print_help(FILE *f) fputs(_(" name=N\tName of Geoclue provider (or `default')\n" " path=N\tPath of Geoclue provider (or `default')\n"), f); fputs("\n", f); + fputs(_("NOTE: currently redshift doesn't recheck geoclue once started,\n" + "which means it has to be restarted to take notice after travel.\n"), + f); + fputs("\n", f); } int diff --git a/src/location-gnome-clock.c b/src/location-gnome-clock.c index 2bb1949..f68af2f 100644 --- a/src/location-gnome-clock.c +++ b/src/location-gnome-clock.c @@ -156,7 +156,9 @@ location_gnome_clock_init(location_gnome_clock_state_t *state) char *lat_str = strstr(current_city, "latitude=\""); char *lon_str = strstr(current_city, "longitude=\""); if (lat_str == NULL || lon_str == NULL) { - fputs(_("Location not specified for city.\n"), stderr); + fprintf(stderr, + _("Location not specified for city `%s'.\n"), + current_city); g_free(current_city); return -1; } diff --git a/src/location-manual.c b/src/location-manual.c index 1f68b6c..11586bb 100644 --- a/src/location-manual.c +++ b/src/location-manual.c @@ -70,6 +70,9 @@ location_manual_print_help(FILE *f) fputs(_(" lat=N\t\tLatitude\n" " lon=N\t\tLongitude\n"), f); fputs("\n", f); + fputs(_("Both values are expected to be floating point numbers,\n" + "negative values representing west / south, respectively.\n"), f); + fputs("\n", f); } int diff --git a/src/redshift.c b/src/redshift.c index 08f3e1d..9cd1e36 100644 --- a/src/redshift.c +++ b/src/redshift.c @@ -930,6 +930,9 @@ main(int argc, char *argv[]) location_providers[i].name != NULL; i++) { const location_provider_t *p = &location_providers[i]; + fprintf(stderr, + _("Trying location provider `%s'...\n"), + p->name); r = provider_try_start(p, &location_state, &config_state, NULL); if (r < 0) { @@ -966,6 +969,8 @@ main(int argc, char *argv[]) if (verbose) { /* TRANSLATORS: Append degree symbols if possible. */ printf(_("Location: %f, %f\n"), lat, lon); + printf(_("Temperatures: %dK at day, %dK at night\n"), + temp_day, temp_night); } /* Latitude */ @@ -1314,7 +1319,7 @@ main(int argc, char *argv[]) } } - /* Sleep for a while */ + /* Sleep for 5 seconds or 0.1 second. */ #ifndef _WIN32 if (short_trans) usleep(100000); else usleep(5000000); |