diff options
Diffstat (limited to 'README')
| -rw-r--r-- | README | 396 |
1 files changed, 368 insertions, 28 deletions
@@ -8,14 +8,10 @@ NAME redshift - Automatically adjust display colour temperature according the Sun SYNOPSIS - redshift [-b brightness] [-c file] [-D | +D] [-g gamma] + redshift [-b brightness] [-c config-file] [-D | +D] [-g gamma] [-l latitude:longitude | -l provider[:options]] [-m method[:options]] [-P | +P] [-r | +r] [-dv] - [-O temperature | -o | -p | -t temperature | -x] - - redshift -h - - redshift -V + [-O temperature | -o | -p | -t temperature | -x] | -h | -V DESCRIPTION redshift adjusts the colour temperature of your screen according to your @@ -34,7 +30,7 @@ DESCRIPTION outside. Typically around 5500K–6500K (default is 6500K). The light has a lower temperature on an overcast day. - In addition to the command-line tool redshift, the GUI redshift-gtk + In addition to the command-line tool redshift, the GUI redshift-gtk(1) provides an alternative interface that shows up as a notification icon in the desktop environment. @@ -45,17 +41,22 @@ OPTIONS Synonym for "-b brightness:brightness". -b day:night - Screen brightness to apply at daytime and at nighttime. - (Default: 1:1) + Monitor whitepoint brightness to apply at daytime and at + nighttime. (Default: 1:1) The values most be between 0.1 and 1.0. day or night may be omitted, to keep unmodified, however at least one must be specified. - -c file + -c config-file Load settings from specified configuration file. + /dev/null can be used to tell redshift not to load the + configuration file. + + If "-", the standard input will be used. + -D Start in enabled state. (Default) @@ -77,8 +78,12 @@ OPTIONS -g day:night Synonym for "-g day:day:day:night:night:night". - -g r:g:b - Synonym for "-g r:g:b:r:g:b". + However, if day is omitted, it is a synonym for + "-g :night:night:night", or if night is omitted, it is a + synonym for "-g day:day:day:". + + -g red:green:blue + Synonym for "-g red:green:blue:red:green:blue". -g day-r:day-g:day-b:night-r:night-g:night-b Additional gamma correction to apply at daytime and @@ -160,6 +165,12 @@ OPTIONS Values must be at least 1000 and integral. + The value 6500 is equivalent to no colour temperature + adjustment. + + Default mode, but default values may change between + versions. + -V Show program implementation and verison. @@ -201,6 +212,63 @@ ASYNCHRONOUS EVENTS Disable the effects of redshift, or if already disabled, reenable them. + SIGUSR2 with value 0 + Normally signals may be processed out of order, however + when this signal is received, SIGUSR2 will be blocked until + all pending SIGUSR2 signals has been processed, creating + signal processing order barrier. This is useful when mixing + SIGUSR2 value 3 (reloading configuration file) with other + configuration changing SIGUSR2 values. + + SIGUSR2 with value 1 + Disable the effects of redshift. + + SIGUSR2 with value 2 + Enable the effects of redshift. + + SIGUSR2 with value 3 + Reload the configuration file. + + Settings from the command line will be overriden. + + SIGUSR2 with value 4 + Execute into the currently installed version of the program. + + Only available on Linux. + + SIGUSR2 with value 5 + Set the "fade" setting to off. + + SIGUSR2 with value 6 + Set the "fade" setting to on. + + SIGUSR2 with value 7 + Set the "preserve-gamma" setting to off. + + SIGUSR2 with value 8 + Set the "preserve-gamma" setting to on. + + SIGUSR2 with value 9 + Exit the process without removing the its effects. + If the used adjustment method does not support leaving + the effects, they will be removed. + + SIGUSR2 with value 10 + Do not terminate redshift the standard output and + standard error are closed. + + SIGUSR2 with value 11 + Enable verbose mode. (The -v option will be treated as + specified.) + + SIGUSR2 with value 12 + Disable verbose mode. + + Ignore if started in verbose mode (-v option). + + SIGUSR2 with other values or no value + Ignored. + STDOUT The standard output is used to print state information and requested help information. The output is subject to localisation, and the @@ -210,7 +278,7 @@ STDOUT it may change between versions and applications should not expect any particular precision to be used. - When "-m list" is specified the available gamma ramp adjustment methods + When "-m list" is specified, the available gamma ramp adjustment methods are printed with the header "Available adjustment methods:\n" followed by the list in the format @@ -219,7 +287,7 @@ STDOUT The list is terminated by an empty line. Additional information for human users is printed after the empty line. - When "-l list" is specified the available location providers are + When "-l list" is specified, the available location providers are printed with the header "Available location providers:\n" followed by the list in the format @@ -250,6 +318,11 @@ STDOUT If "-v" is specified and the colour settings depend on the clock time, the time schedule is printed to the standard output, with the header + "Schedule:\n" and the footer "(End of schedule)\n", in the format + + "%s%f%% day at %02u:%02u:%02u\n", <arbitrary whitespace>, + <dayness level (0–100)>, <start hour (0–23)>, + <start minute (0–59)>, <start second (0–59)>. These lines may be printed, if "-v" is specified, if redshift is configured. @@ -289,7 +362,7 @@ STDOUT where <period> is "None", "Daytime", or "Night", or in the format - "Period: Transition (%f%% day)", <dayness level>. + "Period: Transition (%f%% day)\n", <dayness level> * 100. <dayness level> is exclusively between 0 (night) and 1 (daytime). @@ -303,15 +376,25 @@ STDOUT "Color temperature: %luK\n", <colour temperature>; - "Brightness: %f\n", <whitepoint brightness level (0-1)>; + "Brightness: %f\n", <whitepoint brightness level (0–1)>; "Gamma: %f, %f, %f\n", <red gamma>, <green gamma>, <blue gamma>. - If "-v" is specified, and if running and continual mode, the program + If "-v" is specified, and if running in continual mode, the program will print "Status: Enabled\n" if starting in or when entering enabled mode, and "Status: Disabled\n" if starting in or when entering disabled mode. + If "-v" is specified, and if running in continual mode, the program + will print "Fade: Enabled\n" or "Fade: Disabled\n" to indicate whether + the "fade" setting is enabled, when the program starts and when the + setting is modified. + + If "-v" is specified, and if running in continual mode, the program + will print "Preserve gamma: Enabled\n" or "Preserve gamma: Disabled\n" + to indicate whether the "preserve-gamma" setting is enabled, when the + program starts and when the setting is modified. + If the "dummy" gamma ramp adjustment method is used, any time a colour change is applied (including each fade step), the colour temperature is output, for debugging purposes (brightness and gamma are not printed), @@ -326,9 +409,239 @@ OUTPUT FILES None. FILES - TODO + Unless the -c option is used, redshift will look for its configuration + file, and if found, load it. When searching for the configuration file, + redshift will load the first found file. It will primary look for + "redshift-ng/redshift.conf", secondarily for "redshift/redshift.conf", + and tertiarily for "redshift.conf", in each directory it searches. It + will search the following directories in order: the directory set in + the environment variable XDG_CONFIG_HOME, the directory set in the + environment variable localappdata (Windows only), the ".config" + directory inside directory set in the environment variable HOME, and + the ".config" directory inside the user's home directory. For the two + latter, it will quaternarily look for the file ".redshift.conf". If not + found, it will also look for the file in each directory listed in the + environment variable XDG_CONFIG_DIRS (delimited by colon (:) on + Unix-like systems and by semicolon (;) on Windows), however it try each + directory before moving on to then next filename option. Lastly, on + Unix-like systems, it will look for the file in /etc. This means that + the preferred location for the configuration file is + ${XDG_CONFIG_HOME}/redshift-ng/redshift.conf. + + redshift will use the same pattern to find the hook directory, and the + tested subdirectories for each search directory are "/redshift-ng/hooks" + and secondarily "/redshift/hooks". All executable files, in the found + directory, that are neither prefixed with a period (.) or suffixed with + a tilde (~) will be used as hooks scripts, and will be executed in + arbitrary order. Subdirectories are not search for executable files. + This means that the preferred location for the hook scripts is (directly + inside) ${XDG_CONFIG_HOME}/redshift-ng/hooks/. EXTENDED DESCRIPTION + Configuration file + The configuration file uses the standard INI format. General program + options are placed under the redshift header ("[redshift]"), while + options for location providers are adjustment methods are placed under + a hader with the name of that proivder or method. + + General options are: + + temp = temperature + temperature = temperature + Set temperature for daytime and nighttime. The value shall be + format in the same way as with the -O and -t options. + + temp-day = integer + temperature-day = integer + Set temperature for daytime. That value shall be an integer no + less than 1000 (Kelvin). + + temp-night = integer + temperature-night = integer + Set temperature for nighttime. That value shall be an integer + no less than 1000 (Kelvin). + + brightness = brightness + Set whitepoint brightness for daytime and nighttime. The value + shall be format in the same way as with the -b option. + + brightness-day = 0.1–1.0 + Set whitepoint brightness for daytime. That value shall be an + within [0.1, 1.0]. + + brightness-night = 0.1–1.0 + Set whitepoint brightness for nighttime. That value shall be an + within [0.1, 1.0]. + + gamma = gamma + Set gamma correction for daytime and nighttime. The value shall + be format in the same way as with the -g option. + + gamma-day = 0.1–10.0 + gamma-day = red:green:blue + Set gamma correction for daytime. Values must be within [0.1, + 10.0], and are applied to each colour channel individually, + however if only one value is specified it is applied to all + each channels. + + gamma-night = 0.1–10.0 + gamma-night = red:green:blue + Set gamma correction for nighttime. Values must be within [0.1, + 10.0], and are applied to each colour channel individually, + however if only one value is specified it is applied to all + each channels. + + fade = 0 or 1 + Disable (if 0) or enable (if 1) fading between colour settings + with large differences. + + The -r and +r options can be used to override this setting. + + preserve-gamma = 0 or 1 + If 1, preapplied colour calibrations (all applied effects are + assumed to be colour calibrations) will be preserved, if 0, + colour calibrations will be reset while redshift is running. + + The -P and +P options can be used to override this setting. + + Note that if 0, colour calibrations will be reset even when + redshift is running but is disabled. This is necessary to + support the -o and -O options. + + This setting is ignored when coopgamma is used as coopgamma + allows multiple programs to modify the gamma ramps at the + same time. + + start-disabled = 0 or 1 + Start redshift in disabled (if 1) or enabled (if 0) state. + + The -D and +D options can be used to override this setting. + + elevation-high = decimal + The lowest solar elevation, in degrees, during daytime. + + elevation-low = decimal + The highest solar elevation, in degrees, during nighttime. + + dawn-time = HH:MM[:SS][-HH:MM[:SS]] + dusk-time = HH:MM[:SS][-HH:MM[:SS]] + Custom time interval for the transition from night to day + (dawn-time) and for the transition from day to night + (dusk-time). + + When specified, both settings must be specified and the + solar elevation will not be used to determine the current + daytime/nighttime period, nor will a location provider + used. + + The left-hand hour must be within [0, 23], but the right-hand + hour may be within [0, 47], the timespan must not be greater + than 24 hours. The minutes and seconds must be within [0, 59], + and the default value for the seconds is 0. + + adjustment-method = name + Select adjustment method. Options for the adjustment method can + be given under the configuration file heading of the same name. + + Not used if the -p option is specified. + + location-provider = name + Select location provider. Options for the location provider can + be given under the configuration file heading of the same name. + + Not used if dawn-time and dusk-time are used or if the colours + settings are specified to be the same during the day and the + night. + + Options for the location provider "manual" are: + + lat = decimal + The GPS latitude of the user's geographical location. + Shall be specified in degrees and formatted a single + real number, rather than split into integer degrees, + minutes and seconds. Positive values used for the + northern hemisphere and negative values are ued for + the southern hemisphere. + + lon = decimal + The GPS longitude of the user's geographical location. + Shall be specified in degrees and formatted a single + real number, rather than split into integer degrees, + minutes and seconds. Positive values used for the + eastern hemisphere and negative values are ued for + the western hemisphere. + + There are no options for the location providers "geoclue2" (may be + available on Unix-like systems) and "corelocation" (available on + Mac OS X). + + Options for the location provider "randr" (preferred method for X) are: + + screen = integer + X screen to apply adjustments to. Default is determined + by the environment variable DISPLAY. + + crtc = integer list or all + Comma-separated (,) list of CRTC indices for monitors to + apply adjustments to. All available CRTCs are used if the + list is empty or if the setting is omitted. + + "all" may be specified as a synonym for an empty list. + + The index of the first CRTC is 0. + + Options for the location provider "vidmode" (fallback method for X) are: + + screen = integer + X screen to apply adjustments to. Default is determined + by the environment variable DISPLAY. + + Options for the location provider "drm" (method for Linux without + display server) are: + + card = integer + Index of graphics card to apply adjustments to. + + crtc = integer or all + Index of CRTC for monitor to apply adjustments to. + + "all" may be specified to apply adjustments to each available + CRTC on the graphics card. + + The index of the first CRTC is 0. + + There are no options for the adjustment methods "wingdi" (available + on Windows), "quartz" (available on Mac OS X), and "dummy" (used for + debugging, does not apply any colour effects). + + Hooks + Executable files (that are not dotfiles or tilde files) in the hook + directory (see the FILES section), are executed on certain events. + The file inherit the redshift process standard input and standard + error, however the standard output is redirected to the standard error. + + Each file is executed with at least one argument. This first argument + indicate what event has taked place. Additional arguments may be + provided for additional event data. + + redshift will be the parent process of the executed script. + + Currently available events are: + + period-changed + This indicate that the period of the day has changed (and at + start of continual mode). The script will be provided two + additional arguments (the second argument and the third + argument). The second argument will the previous period, and + the third argument will be the new period. The argument values + will be either of "night", "daytime", "transition" (transition + in either direction between night and daytime), or "none" (not + previously or no longer calculated). "none" appears as the + previous period at start up and can also appear when the when + redshift is reconfigured if the colour settings no longer + depending on the period of the day or has started depending + on the period of the day. + Gamma ramps redshift applies a redness effect to the graphical display. The intensity of the redness can be customised and scheduled to only be @@ -338,7 +651,7 @@ EXTENDED DESCRIPTION gamma ramps or gamma correction ramps, to apply this effect. Colour temperature - The redness effect applies by redshift is modelled after black-body + The redness effect applied by redshift is modelled after black-body radiation, specifically with a 10 degree observer. Although black-body radiation starts at 0, redshift's model start at the conventional 1000K (1000 Kelvin). For this reason, no colour temperature below 1000K can be @@ -366,7 +679,30 @@ EXIT STATUS Default. EXAMPLES - TODO + Example for the superelliptical roundabout in Stockholm, Sweden: + + redshift -l 59.333:18.065 -t 5700:3600 -b 1:0.8 + + Example configuration file equivalent to above command: + + [redshift] + temperature-day=5700 + temperature-night=3600 + brightness-day=1 + brightness-night=0.8 + location-provider=manual + + [manual] + lat=59.333 + lon=18.065 + + Sample hook script: + + #!/bin/sh + case "$1" in + period-changed) + notify-send "redshift-ng" "Period changed from $2 to $3";; + esac KNOWN ISSUES No or incorrect effect on cursor @@ -381,11 +717,11 @@ KNOWN ISSUES Limited hardware support Low-end hardware, especially embedded devices, often lack colour - correction features redshift abuse to apply it's affect. redshift is not + correction features redshift abuse to apply its effect. redshift is not always able to tell if support is missing. Limited software support - redshift does not yet support Waylaid. If your environment contains the + redshift does not yet support Wayland. If your environment contains the variable WAYLAND_DISPLAY, you are using a Wayland compositor and cannot currently expect redshift to work. Even with Wayland support, it would be up to each individual Wayland compositor to opt in to support @@ -412,12 +748,13 @@ KNOWN ISSUES there is no standardised why have multiple applications applying different effects without overriding each other. This can cause continuous flicker if multiple instance are running or effects - temporarily disappearing. By default, redshift uses coopgammad, which is - a daemon applications can opt to use instead of directly setting the - gamma ramps themselves, coopgammad can then calculate the result of all - of the effects and apply them as one, allowing the user to use multiple - applications that apply different effects. However coopgammad still has - to compete with applications that does not use it. + temporarily disappearing. By default, redshift uses coopgammad(1), which + is a daemon applications can opt to use instead of directly setting the + gamma ramps themselves, coopgammad(1) can then calculate the result of + all of the effects and apply them as one, allowing the user to use + multiple applications that apply different effects. However + coopgammad(1) still has to compete with applications that does not use + it. DRM and display servers Using the DRM gamma ramp adjustment method can block starting or @@ -437,6 +774,9 @@ RATIONALE To prevent colour distortion and making the screen too white, brightness level above 1.0 are forbidden. + Gamma correction is preserved for backwards compatibility and is + deprecated (gamma parameters in particular). + NOTES "Colour temperature", or just "temperature", is actually short for "correlated colour temperature". (Your monitor is not a black-body |