diff options
Diffstat (limited to 'redshift/redshift.1')
| -rw-r--r-- | redshift/redshift.1 | 1379 |
1 files changed, 1379 insertions, 0 deletions
diff --git a/redshift/redshift.1 b/redshift/redshift.1 new file mode 100644 index 0000000..33706fc --- /dev/null +++ b/redshift/redshift.1 @@ -0,0 +1,1379 @@ +.TH REDSHIFT 1 REDSHIFT-NG +.SH NAME +redshift \- Automatically adjust display colour temperature according the Sun + +.SH SYNOPSIS +.B redshift +[-b +.IR brightness ] +[-c +.IR config-file ] +[-D | +D] [-E | +E | -e +.IR elevations ] +[-g +.IR gamma ] +[-H +.IR hook-file ] +[-l +.IB latitude : longitude +| -l +.IR provider [\fB:\fP options ]] +[-m +.IR method [\fB:\fP options ] +[-P | +P] [-r | +r] [-dv] +[-O +.I temperature +| -o | -p | -t +.I temperature +| -x] | -h | -V + +.SH DESCRIPTION +.B redshift +adjusts the colour temperature of your screen according to your +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. +.PP +The colour temperature is set according the the position of the Sun. +A different colour temperature is set during the night and during the +day. During dawn and early morning, the colour temperature transitions +smoothly from night- to day-time temperature to allow your eyes to +slowly adapt over a period of about an hour. At night, the colour +temperature should be set to match the maps in your room. This is +typically a low temperature at around 3000K-4000K (default is 4500K). +During the day, the colour temperature should match the light from +outside. Typically around 5500K-6500K (default is 6500K). The light has +a lower temperature on an overcast day. +.PP +In addition to the command-line tool +.BR redshift , +the GUI +.BR redshift-gtk (1) +provides an alternative interface that shows up as a notification icon +in the desktop environment. + +.SH OPTIONS +The following options are supported: +.TP +.BI -b\fR\ brightness +Synonym for +.B -b +.IB brightness : brightness\fR. +.TP +.BI -b\fR\ day : night +Monitor whitepoint brightness to apply at daytime and at +nighttime. (Default: 1:1) + +The values most be between 0.1 and 1.0. + +.I day +or +.I night +may be omitted, to keep unmodified, however +at least one must be specified. +.TP +.BI -c\fR\ config-file +Load settings from specified configuration file. + +.B /dev/null +can be used to tell +.B redshift +not to load the configuration file. + +If +.RB \(dq - \(dq, +the standard input will be used. +.TP +.B -D +Start in enabled state. (Default) +.TP +.B +D +Start in disabled state. + +Ignored in one-shot mode. +.TP +.B -d +Keep the process alive and remove the colour effects +when killed. + +Ignored for +.B -p +and +.BR -x ; +always active for +.B -t +and the +.B quartz +adjustment method. +.TP +.B -E +Use wall-clock based schedule. +.TP +.B +E +Use solar elevation based schedule. +.TP +.BI -e\fR\ elevations +Synonym for +.B -e +.IB elevations : elevations\fR. +.TP +.BI -e\fR\ elevation-high : elevation-low +Sets the lowest solar elevation during daytime to +.I elevation-high +and the higest solar elevation during nighttime to +.IR elevation-low . + +The value should be formatted as real, decimal +values measured in degrees. Each value shall be +formatted as one complete value, without unit +suffix, and not split into degrees, minutes, and +seconds. Positive values are above the horizon +and negative values are below the horizon. + +.I elevation-high +or +.I elevation-low +may be omitted, to keep unmodified, however at least +one must be specified. + +Implies +.BR +E . +.TP +.BI -g\fR\ gamma +Synonym for +.B -g +.IB gamma : gamma\fR. +.TP +.BI -g\fR\ day : night +Synonym for +.B -g +.IB day : day : day : night : night : night\fR. + +However, if +.I day +is omitted, it is a synonym for +.B -g +.BI : night : night : night\fR, +or if +.I night +is omitted, it is a synonym for +.B -g +.IB day : day : day :\fR. +.TP +.BI -g\fR\ red : green : blue +Synonym for +.B -g +.IB red : green : blue : red : green : blue\fR. +.TP +.BI -g\fR\ day-r : day-g : day-b : night-r : night-g : night-b +Additional gamma correction to apply at daytime and +at nighttime. (Default: 1:1:1:1:1:1) + +The values most be between 0.1 and 10.0. + +.IB day-r : day-g : day-b +or +.IB night-r : night-g : night-b +may be omitted, +to keep unmodified, however at least one set must be specified. +Individual components of one set cannot be omitted, either +nothing is omitted or an entire set, including its two colons +.RB ( : ) +are omitted. +.TP +.BI -H\fR\ hook-file +Select hook file or directory. + +.B /dev/null +or +.B /var/empty +can be used to tell redshift not to run hook files. +.TP +.B -h +Display help message. +.TP +.BI -l\fR\ latitude : longitude +Your current location, in degrees. Shall be formatted a single +real number, rather than split into integer degrees, minutes +and seconds. The location should be specified using the GPS +coordinate system. +.TP +.BI -l\fR\ provider\fR[ : options\fR] +Select provider for automatic location updates. + +.I options +is a colon- +.RB ( : ) +and semicolon-separated +.RB ( ; ) +list. Each option an option name and value +separated by an equals sign +.RB ( = ). + +Use +.B -l list +to see available providers. + +Use +.BI -l\ provider :help +to see available options, +or refer to the +.B EXTENDED DESCRIPTION +section. +.TP +.BI -m\fR\ method\fR[ : options\fR] +Method to use to set colour temperature. + +.I options +is a colon- +.RB ( : ) +and semicolon-separated +.RB ( ; ) +list. Each option an option name and value +separated by an equals sign +.RB ( = ). + +Use +.B -m list +to see available methods. + +Use +.BI -m\ method :help +to see available options, +or refer to the +.B EXTENDED DESCRIPTION +section. +.TP +.BI -O\ temperature +This is a synonym for +.B -O +.IB temperature : temperature\fR. +.TP +.BI -O\ day : night +One-shot manual mode (set colour temperature). The colour set +is interpolated between day and night depending on the Sun's +elevation or the clock time (depending on which +.B redshift +is configured to use). + +Values must be at least 1000 and integral. + +Use this with the +.B -P +option to clear the existing gamma ramps +before applying the new color temperature. + +This is a synonym for +.B -t +.IB day : night +.BR -o . +.TP +.B -o +One-shot mode (do not continuously adjust colour temperature). + +Use this with the +.B -P +option to clear the existing gamma ramps +before applying the new color temperature. +.TP +.B -P +Reset exiting gamma ramps before applying new colour effects. +.TP +.B +P +Preserve preexisting gamma adjustments. (Default) +.TP +.B -p +Print parameters and exit. +.TP +.B -r +Disable fading between colour temperatures. +.TP +.B +r +Enable fading between colour temperatures. (Default) +.TP +.BI -t\fR\ temperature +This is a synonym for +.B -t +.IB temperature : temperature\fR. +.TP +.BI -t\fR\ day : night +Colour temperature to set at daytime and at nighttime. + +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. +.TP +.B -V +Show program implementation and version. +.TP +.B -v +Enable verbose output. +.TP +.B -x +Remove adjustments from screen. +.PP +For mutually exclusive options or options specified multiple times, +the last specified takes effect, except the first specified option +that outputs text (except +.BR -p ) +is used. However, if the daytime +alue or nighttime value is omitted for an option, the last previously +pecified value will be used; that is, for example, +.B -t 5000: +and +.B -t :3000 +do not override each other, but +.B -t 5000: +overrides, if specified later, +.B 6000 +but not +.B 3000 +in +.BR "-t 6000:3000" . +.PP +Options in the command line override settings from the configuration +file. + +.SH OPERANDS +None. + +.SH STDIN +Not used. + +.SH INPUT FILES +None. + +.SH ASYNCHRONOUS EVENTS +.B redshift +takes the standard action for all signals except: +.TP +.B SIGINT +.TQ +.B SIGTERM +.TQ +.B SIGQUIT +Smoothly disable the effects of +.B redshift +and terminate the +process. If already sent, immediately disable the effects +and terminate the process. +.TP +.B SIGUSR1 +Disable the effects of +.BR redshift , +or if already disabled, reenable them. +.TP +.BR SIGUSR2 \ with\ value\ \fI0\fR +Normally signals may be processed out of order, however +when this signal is received, +.B SIGUSR2 +will be blocked until all pending +.B SIGUSR2 +signals has been processed, creating signal processing +order barrier. This is useful when mixing +.B SIGUSR2 +value +.I 3 +(reloading configuration file) with other configuration changing +.I SIGUSR2 +values. +.TP +.BR SIGUSR2 \ with\ value\ \fI1\fR +Disable the effects of +.BR redshift . +.TP +.BR SIGUSR2 \ with\ value\ \fI2\fR +Enable the effects of +.BR redshift . +.TP +.BR SIGUSR2 \ with\ value\ \fI3\fR +Reload the configuration file. + +Settings from the command line will be overriden. +.TP +.BR SIGUSR2 \ with\ value\ \fI4\fR +Execute into the currently installed version of +.BR redshift . + +Only available on Linux. +.TP +.BR SIGUSR2 \ with\ value\ \fI5\fR +Set the +.B fade +setting to off. +.TP +.BR SIGUSR2 \ with\ value\ \fI6\fR +Set the +.B fade +setting to on. +.TP +.BR SIGUSR2 \ with\ value\ \fI7\fR +Set the +.B preserve-gamma +setting to off. +.TP +.BR SIGUSR2 \ with\ value\ \fI8\fR +Set the +.B preserve-gamma +setting to on. +.TP +.BR SIGUSR2 \ with\ value\ \fI9\fR +Exit the process without removing the its effects. +If the used adjustment method does not support leaving +the effects, they will be removed. +.TP +.BR SIGUSR2 \ with\ value\ \fI10\fR +Do not terminate +.B redshift +the standard output and standard error are closed. +.TP +.BR SIGUSR2 \ with\ value\ \fI11\fR +Enable verbose mode. (The +.B -v +option will be treated as specified.) +.TP +.BR SIGUSR2 \ with\ value\ \fI12\fR +Disable verbose mode. + +Ignore if started in verbose mode +.RB ( -v +option). +.TP +.BR SIGUSR2 " with other values or no value" +Ignored. + +.SH STDOUT +The standard output is used to print state information and requested +help information. The output is subject to localisation, and the +following formats apply for the +.RB \(dq C \(dq +locale. Applications taking use of this information must make sure +to set the message locale to +.RB \(dq C \(dq. +For floating-point values +.RB (\(dq %f \(dq) +the precision is not documented as it may change between versions and +applications should not expect any particular precision to be used. +.PP +When +.B -m list +is specified, the available gamma ramp adjustment methods +are printed with the header +.B \(dqAvailable adjustment methods:\en\(dq +followed by the list in the format +.RS +.nf + +\fB\(dq%s%s\en\(dq, \fI<arbitrary whitespace>\fP, \fP<method name>\fR. + +.fi +.RE +.PP +The list is terminated by an empty line. Additional information for +human users is printed after the empty line. +.PP +When +.B -l list +is specified, the available location providers are +printed with the header +.B \(dqAvailable location providers:\en\(dq +followed by the list in the format +.RS +.nf + +\fB\(dq%s%s\en\(dq, \fI<arbitrary whitespace>\fP, \fP<provider name>\fR. + +.fi +.RE +.PP +The list is terminated by an empty line. Additional information for +human users is printed after the empty line. +.PP +When +.B list +is specified for the +.B edid +suboption to +.BR -m , +a list of available monitors will be printed to the standard output, +with the header +.BR "\(dqAvailable outputs:\en\(dq" , +in the format +.RS +.nf + +\fB\(dq%s%s\en\(dq, \fI<arbitrary whitespace>\fP, \fP<monitor identifier>\fR. + +.fi +.RE +.PP +When +.BR "-m method:help" , +.BR "-l provider:help" , +or +.B -h +is specified help information is printed on in unspecified format, +intended only for human users. +.PP +When +.B -V +is specified, the used version of the program is printed to +the standard output in the format +.RS +.nf + +\fB\(dq%s %s\en\(dq, \fI<implementation name>\fP, \fP<version number>\fR. + +.fi +.RE +.PP +If +.B -v +is specified and the colour settings depend on the Sun's +elevation, the elevation thresholds are printed to the standard +output in the format +.RS +.nf + +\fB\(dqSolar elevations: day above %f, night below %f\en\(dq,\fR +\fI<minimum solar elevation at daytime>\fB,\fR +\fI<maximum solar elevation at nighttime>\fR. + +.fi +.RE +This line may be printed, if +.B -v +is specified, if +.B redshift +is configured. +.PP +If +.B -v +is specified and the colour settings depend on the clock time, +the time schedule is printed to the standard output, with the header +.B \(dqSchedule:\en\(dq +and the footer +.BR "\(dq(End of schedule)\e\n\(dq" , +in the format +.RS +.nf + +\fB\(dq%s%f%% day at %02u:%02u:%02u\en\(dq, \fI<arbitrary whitespace>\fP,\fR +\fI<dayness level (0-100)>\fB, \fP<start hour (0-23)>\fP,\fR +\fI<start minute (0-59)>\fB, \fP<start second (0-59)>\fR. + +.fi +.RE +These lines may be printed, if +.B -v +is specified, if +.B redshift +is configured. +.PP +If +.B -v +is specified, the colour settings is printed to the standard +output in the format +.RS +.nf + +\fB\(dqTemperatures: %luK at day, %luK at night\en\(dq\fR +\fB\(dqBrightness: %f:%f\en\(dq\fR +\fB\(dqGamma (Daytime): %f, %f, %f\en\(dq\fR +\fB\(dqGamma (Night): %f, %f, %f\en\(dq,\fR +\fI<daytime colour temperature>\fB, \fP<nighttime temperature>\fP,\fR +\fI<daytime whitepoint brightness>\fB, \fP<nighttime brightness>\fP,\fR +\fI<daytime red gamma>\fB, \fP<daytime green gamma>\fP,\fR +\fI<daytime blue gamma>\fB, \fP<nighttime red gamma>\fP,\fR +\fI<nighttime green gamma>\fB, \fP<nighttime blue gamma>\fR. + +.fi +.RE +Each line may be printed, if +.B -v +is specified, if +.B redshift +is configured. +.PP +If the colour effects depend on the Sun's elevation, the user's +geographical location will printed to the standard output in the +format +.RS +.nf + +\fB\(dqLocation: %f %c, %f %c\en\(dq,\fR +\fIfabs(<GPS latitude>)\fB, \fPsignbit(<GPS latitude>) ? 'S' : 'N'\fP,\fR +\fIfabs(<GPS longitude>)\fB, \fPsignbit(<GPS longitude>) ? 'W' : 'E'\fR. + +.fi +.RE +This message is printed when the program starts and any time the +location is updated. +.PP +If the colour effects are non-static, the current period of the day +(which determine the colour effects) is printed to standard output, if +.B -v +or +.B -p +is specified, in the format +.RS +.nf + +\fB\(dqPeriod: %s\en\(dq, \fI<period>\fR + +.fi +.RE +where +.I <period> +is +.BR None , +.BR Daytime , +or +.BR Night , +or in the format +.RS +.nf + +\fB\(dqPeriod: Transition (%f%% day)\en\(dq, \fI<dayness level> * 100\fR. + +.fi +.RE +.I <dayness level> +is exclusively between 0 (night) and 1 (daytime). +.PP +This message is printed when the program starts and any time it +changes (if +.B -v +is specified). +.PP +If +.B -v +or +.B -p +is specified, the colour settings are printed to the +standard output when the program standard and any time it changes +(fade effect is ignored). These are printed in three different +messages and, on chagne, only the settings that changed are printed: +.RS +.nf + +\fB\(dqColor temperature: %luK\en\(dq, \fI<colour temperature>\fR; + +\fB\(dqBrightness: %f\en\(dq, \fI<whitepoint brightness level (0-1)>\fR; + +\fB\(dqGamma: %f, %f, %f\en\(dq, \fI<red gamma>\fP, \fP<green gamma>\fP, \fP<blue gamma>\fR. + +.fi +.RE +.PP +If +.B -v +is specified, and if running in continual mode, the program will print +.B \(dqStatus: Enabled\en\(dq +if starting in or when entering enabled mode, and +.B \(dqStatus: Disabled\en\(dq +if starting in or when entering disabled mode. +.PP +If +.B -v +is specified, and if running in continual mode, the program will print +.B \(dqFade: Enabled\en\(dq +or +.B \(dqFade: Disabled\en\(dq +to indicate whether the +.B fade +setting is enabled, when the program starts and when the +setting is modified. +.PP +If +.B -v +is specified, and if running in continual mode, the program will print +.B \(dqPreserve gamma: Enabled\en\(dq +or +.B \(dqPreserve gamma: Disabled\en\(dq +to indicate whether the +.B preserve-gamma +setting is enabled, when the +program starts and when the setting is modified. +.PP +If the +.B 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), +to the standard output in the format +.RS +.nf + +\fB\(dqTemperature: %lu\en\(dq, \fI<colour temperature>\fR. +.fi +.RE + +.SH STDERR +Default. + +.SH OUTPUT FILES +None. + +.SH FILES +Unless the +.B -c +option is used, +.B redshift +will look for its configuration +file, and if found, load it. When searching for the configuration file, +.B redshift +will load the first found file. It will primary look for +.IR redshift-ng/redshift.conf , +secondarily for +.IR redshift/redshift.conf , +and tertiarily for +.IR redshift.conf , +in each directory it searches. It +will search the following directories in order: the directory set in +the environment variable +.IR XDG_CONFIG_HOME , +the directory set in the +environment variable +.I localappdata +(Windows only), the +.I .config +directory inside directory set in the environment variable +.IR HOME , +and the +.I .config +directory inside the user's home directory. For the two +latter, it will quaternarily look for the file +.IR .redshift.conf . +If not found, it will also look for the file in each directory listed in the +environment variable +.I XDG_CONFIG_DIRS +(delimited by colon +.RB ( : ) +on Unix-like systems and by semicolon +.RB ( ; ) +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 +.IR /etc . +This means that the preferred location for the configuration file is +.IB ${XDG_CONFIG_HOME} /redshift-ng/redshift.conf\fR. +.PP +.B redshift +will use the same pattern to find the hook directory, and the +tested subdirectories for each search directory are +.I /redshift-ng/hooks +and secondarily +.IR /redshift/hooks . +All executable files, in the found +directory, that are neither prefixed with a period +.BR ( . ) +or suffixed with a tilde +.RB ( ~ ) +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) +.IB ${XDG_CONFIG_HOME} /redshift-ng/hooks/\fR. + +.SH EXTENDED DESCRIPTION +.SS Configuration file +The configuration file uses the standard INI format. General program +options are placed under the +.B redshift +header +.RB ( [redshift] ), +while options for location providers are adjustment methods are +placed under a hader with the name of that proivder or method. +.PP +General options are: +.TP +.BI temp\fR\ =\ temperature +.TQ +.BI temperature\fR\ =\ temperature +Set temperature for daytime and nighttime. The value shall be +format in the same way as with the +.B -O +and +.B -t +options. +.TP +.BI temp-day\fR\ =\ integer +.TQ +.BI temperature-day\fR\ =\ integer +Set temperature for daytime. That value shall be an integer no +less than 1000 (Kelvin). +.TP +.BI temp-night\fR\ =\ integer +.TQ +.BI temperature-night\fR\ =\ integer +Set temperature for nighttime. That value shall be an integer +no less than 1000 (Kelvin). +.TP +.BI brightness\fR\ =\ brightness +Set whitepoint brightness for daytime and nighttime. The value +shall be format in the same way as with the +.B -b +option. +.TP +.BI brightness-day\fR\ =\ 0.1-1.0 +Set whitepoint brightness for daytime. That value shall be an +within [0.1, 1.0]. +.TP +.BI brightness-night\fR\ =\ 0.1-1.0 +Set whitepoint brightness for nighttime. That value shall be an +within [0.1, 1.0]. +.TP +.BI gamma\fR\ =\ gamma +Set gamma correction for daytime and nighttime. The value shall +be format in the same way as with the +.B -g +option. +.TP +.BI gamma-day\fR\ =\ 0.1-10.0 +.TQ +.BI gamma-day\fR\ =\ 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. +.TP +.BI gamma-night\fR\ =\ 0.1-10.0 +.TQ +.BI gamma-night\fR\ =\ 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. +.TP +.BI hook\fR\ =\ "file or directory" +Set hook file or directory. If not specified, the default +paths are searched. + +.B /dev/null +and +.B /var/empty +can be used to prevent redshift from executing hooks. +.TP +.BI fade\fR\ =\ \fP0 " or " 1 +Disable (if +.BR 0 ) +or enable (if +.BR 1 ) +fading between colour settings with large differences. + +The +.B -r +and +.B +r +options can be used to override this setting. +.TP +.BI preserve-gamma\fR\ =\ \fP0 " or " 1 +If +.BR 1 , +preapplied colour calibrations (all applied effects are +assumed to be colour calibrations) will be preserved, if +.BR 0 , +colour calibrations will be reset while +.B redshift +is running. + +The +.B -P +and +.B +P +options can be used to override this setting. + +Note that if +.BR 0 , +colour calibrations will be reset even when +.B redshift +is running but is disabled. This is necessary to +support the +.B -o +and +.B -O +options. + +This setting is ignored when +.B coopgamma +is used as +.B coopgamma +allows multiple programs to modify the gamma ramps +at the same time. +.TP +.BI start-disabled\fR\ =\ \fP0 " or " 1 +Start +.B redshift +in disabled (if +.BR 1 ) +or enabled (if +.BR 0 ) +state. + +The +.B -D +and +.B +D +options can be used to override this setting. +.TP +.BI elevation-high\fR\ =\ decimal +The lowest solar elevation, in degrees, during daytime. +.TP +.BI elevation-low\fR\ =\ decimal +The highest solar elevation, in degrees, during nighttime. +.TP +.BI dawn-time\fR\ =\ HH : MM\fR[ : SS\fR][ - HH : MM\fR[ : SS\fR]] +.TQ +.BI dusk-time\fR\ =\ HH : MM\fR[ : SS\fR][ - HH : MM\fR[ : SS\fR]] +Custom time interval for the transition from night to day +.RB ( dawn-time ) +and for the transition from day to night +.BR ( 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. +.TP +.BI adjustment-method\fR\ =\ 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 +.B -p +option is specified. +.TP +.BI location-provider\fR\ =\ name +Select location provider. Options for the location provider can +be given under the configuration file heading of the same name. + +Not used if +.B dawn-time +and +.B dusk-time +are used or if the colours +settings are specified to be the same during the day and the +night. +.PP +Options for the location provider +.B manual +are: +.TP +.BI lat\fR\ =\ 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. +.TP +.BI lon\fR\ =\ 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. +.PP +There are no options for the location providers +.B geoclue2 +(may be available on Unix-like systems) and +.B corelocation +(available on Mac OS X). +.PP +Options for the adjustment method +.B randr +(preferred method for X) are: +.TP +.BI display\fR\ =\ name +X display to apply adjustments to. Default is determined +by the environment variable +.IR DISPLAY . + +The value is expected to contain a colon +.RB ( : ) +and can only be terminated with a semicolon +.RB ( ; ). +.TP +.BI screen\fR\ =\ "ordinal list or " all +Comma-separated +.RB ( , ) +list of X screens to apply adjustments to. +All available X screens are used if the list is empty or +if the setting is omitted. + +.B all +may be specified as a synonym for an empty list. +.TP +.BI crtc\fR\ =\ "number list or " all +Comma-separated +.RB ( , ) +list of CRTC numbers for monitors to +apply adjustments to. All available CRTCs are used if the +list is empty or if the setting is omitted. + +A CRTC number may either be specified as an overall +ordinal for all selected X screens, or the index of +the X screen followed by a dot +.RB ( . ) +and the index of the CRTC within the specified X screen. +The specified X screen is automatically included in the +.B screen +selection. + +.B all +may be specified as a synonym for an empty list. + +The index of the first CRTC is 0. +.TP +.BI edid\fR\ =\ "name list or " list +Comma-separated +.RB ( , ) +list of EDIDs of monitors to apply adjustments to. + +If +.B list +is specified, all available EDIDs will be +printed to the standard output and the program exits. + +This list must not be empty; to select all monitors, +instead specify +.BR crtc=all . +.PP +Options for the adjustment method +.B vidmode +(fallback method for X) are: +.TP +.BI display\fR\ =\ name +X display to apply adjustments to. Default is determined +by the environment variable +.IR DISPLAY . + +The value is expected to contain a colon +.RB ( : ) +and can only be terminated with a semicolon +.RB ( ; ). +.TP +.BI screen\fR\ =\ "ordinal list or " all +Comma-separated +.RB ( , ) +list of X screens to apply adjustments to. +All available X screens are used if the list is empty or +if the setting is omitted. + +.B all +may be specified as a synonym for an empty list. +.PP +Options for the adjustment method +.B drm +(method for Linux without display server) are: +.TP +.BI card\fR\ =\ "ordinal list or " all +Comma-separated +.RB ( , ) +list of indices of graphics card screens to apply +adjustments to. All available graphics cards +are used if the list is empty or +if the setting is omitted. + +.B all +may be specified as a synonym for an empty list. +.TP +.BI crtc\fR\ =\ "number list or " all +Comma-separated +.RB ( , ) +list of CRTC numbers for monitors to +apply adjustments to. All available CRTCs are used if the +list is empty or if the setting is omitted. + +A CRTC number may either be specified as an overall +ordinal for all selected graphics card, or the index of +the graphics card followed by a dot +.RB ( . ) +and the index of +the CRTC within the specified graphics card. The specified +graphics card is automatically included in the +.B card +selection. + +.B all +may be specified as a synonym for an empty list. + +The index of the first CRTC is 0. +.TP +.BI edid\fR\ =\ "name list or " list +Comma-separated +.RB ( , ) +list of EDIDs of monitors to apply adjustments to. + +If +.B list +is specified, all available EDIDs will be +printed to the standard output and the program exits. + +This list must not be empty; to select all monitors, +instead specify +.BR crtc=all . +.PP +There are no options for the adjustment methods +.B wingdi +(available on Windows), +.B quartz +(available on Mac OS X), and +.B dummy +(used for debugging, does not apply any colour effects). + +.SS Hooks +Executable files (that are not dotfiles or tilde files) in the hook +directory (see the +.B FILES +section), are executed on certain events. +The file inherit the +.B redshift +process standard input and standard +error, however the standard output is redirected to the standard error. +.PP +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. +.PP +.B redshift +will be the parent process of the executed script. +.PP +Currently available events are: +.TP +.B 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 +.BR night , +.BR daytime , +.BR transition +(transition in either direction between night and daytime), or +.B none +(not previously or no longer calculated). +.B none +appears as the +previous period at start up and can also appear when the when +.B 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. + +.SS Gamma ramps +.B redshift +applies a redness effect to the graphical display. The +intensity of the redness can be customised and scheduled to only be +applied at night or to be applied with more intensity at night. +.PP +.B redshift +uses colour correction lookup tables (CLUTs), usually called +gamma ramps or gamma correction ramps, to apply this effect. + +.SS Colour temperature +The redness effect applied by +.B redshift is modelled after black-body +radiation, specifically with a 10 degree observer. Although black-body +radiation starts at 0, +.BR redshift 's +model start at the conventional 1000K +(1000 Kelvin). For this reason, no colour temperature below 1000K can be +specified. However, as there is a limit can be determined for the colour +when the colour temperature appreciates infinity, the upper limit for +allow colour temperature is instead determined by the data type it is +stored in. However, it also means that it is meaningless to use colour +temperatures above 40000K. +.PP +The sRGB colour space, and modern monitors, use the standard illuminant +D65 as the reference for pure white, modelling ideal day light. The +correlated colour temperature of D65 is called 6500K, however it's +actually 6504K, but +.BR redshift 's +defines this illuminant has having the colour temperature 6500K. +This means that 6500K is the neutral (no effect) colour temperature. +.PP +The current version +.B redshift +assumes the monitor uses sRGB. However +this is usually only true for CRT monitors. HDR-capable monitors +particular diverges significant for sRGB. This means that the display +colour does not perfectly correlated to the specified colour temperate. +Lower (more red) colour temperatures, about 1900K and below, are out of +gamut, and thus incorrect even on sRGB monitors. + +.SH EXIT STATUS +Default. + +.SH EXAMPLES +Example for the superelliptical roundabout in Stockholm, Sweden: +.RS +.nf + +redshift -l 59.333:18.065 -t 5700:3600 -b 1:0.8 +.fi +.RE +.PP +Example configuration file equivalent to above command: +.RS +.nf + +[redshift] +temperature-day=5700 +temperature-night=3600 +brightness-day=1 +brightness-night=0.8 +location-provider=manual + +[manual] +lat=59.333 +lon=18.065 +.fi +.RE +.PP +Sample hook script: +.RS +.nf + +#!/bin/sh +case "$1" in + period-changed) + notify-send "redshift-ng" "Period changed from $2 to $3";; +esac +.fi +.RE + +.SH KNOWN ISSUES +.SS No or incorrect effect on cursor +Some graphics drivers apply the effect (colour corrects) twice or not at +all on hardware cursors. It is often possible to reconfigure the display +server to use software cursors, to avoid this problem, however at mouse +pointer performance cost that may be noticeable on very low-end computer. + +.SS D65-flashes +For some versions of some graphics drivers, there will be an occasional +flash where gamma ramps are not applied to the output. + +.SS Limited hardware support +Low-end hardware, especially embedded devices, often lack colour +correction features +.B redshift +abuse to apply its effect. +.B redshift +is not always able to tell if support is missing. + +.SS Limited software support +.B redshift +does not yet support Wayland. If your environment contains the +variable +.IR WAYLAND_DISPLAY , +you are using a Wayland compositor and cannot +currently expect +.B redshift +to work. Even with Wayland support, it would be up to each individual +Wayland compositor to opt in to support applications like +.BR redshift . + +.SS Backlight control +.B redshift +uses gamma ramps rather than backlight control to adjust +brightness. This actually intentional and for your best. Most +contemporary monitors require Pulse-Width Modulation, which causes +flicker than can cause eye-strain and headaches, to adjust backlight. +Using gamma ramps is a safe option, it's also considerably less work +basically no extra code and posses no additional limitations. It's often +not possible to adjust backlight on desktop monitors from software, for +devices for which it is possible (mostly telephones and laptops, however +not all have fine-grained enough configurability to be usable) it's not +possible from software to determine well enough how changing the +backlight settings changes the backlight physically. If you still want +backlight to be controlled, you can hook in a tool such as +.BR adjbacklight (1). + +.SS Flickering and temporary suspension +.B redshift +uses the gamma ramps for the monitor to apply it's effect. The +gamma ramps where originally intended for colour correction. Therefore +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, +.B redshift +uses +.BR coopgammad (1), +which is a daemon applications can opt to use instead of directly +setting the gamma ramps themselves, +.BR 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 +.BR coopgammad (1) +still has to compete with applications that does not use it. + +.SS DRM and display servers +Using the DRM gamma ramp adjustment method can block starting or +switching to and already started display server (like X). Users may +also find that trying to switch to and an already started display cases +the computer hang, or more precisely appear to hang, as the display +server is not beign presented, the screen freezes, and the keyboard +doesn't do anything. (Once upon a time, this wasn't as catastrophic, +and it probably depend on display server implementation details.) The +only solution, abort from restarting the computer, is to remote into +it and kill the display server. + +.SH RATIONALE +To prevent the user from accidental making the screen black, brightness +level below 0.1 are forbidden. +.PP +To prevent colour distortion and making the screen too white, brightness +level above 1.0 are forbidden. +.PP +Gamma correction is preserved for backwards compatibility and is +deprecated (gamma parameters in particular). +.PP +.RB \(dq : \(dq +was used as the option delimited for +.B -l +and +.B -m +in the original +.BR redshift , +this is preserved for backwards compatbility. However because +some new options are expected to have +.RB \(dq : \(dq +in their value, +.RB \(dq ; \(dq +has added as an additional delimiter. Despite this +.RB \(dq : \(dq +is still the preferred delimiter as it is more user-friendly +and use of options that require delimiting with +.RB \(dq ; \(dq +is uncommon. + +.SH NOTES +\(dqColour temperature\(dq, or just \(dqtemperature\(dq, is actually short for +\(dqcorrelated colour temperature\(dq. (Your monitor is not a black-body +radiator.) And specifically the correlated colour temperature of the +monitor's whitepoint. +.PP +It's common for users to miss to specify a coordinate as negative, +which, if missed on the longitude can swap day and night. The latitude +is negative on the southern hemisphere and the longitude is negative on +the western hemisphere. + +.SH SEE ALSO +.BR cg-tools (7), +.BR coopgammad (1), +.BR radharc (1) |