diff options
| -rw-r--r--[l---------] | README | 244 | ||||
| -rw-r--r-- | README.md | 147 | ||||
| -rw-r--r-- | TODO | 2 |
3 files changed, 245 insertions, 148 deletions
@@ -1 +1,243 @@ -README.md
\ No newline at end of file +PROLOGUE + redshift-ng is a fork Redshift. redshift-ng strives to keep backwards + compatibility with Redshift and be usable as a drop-in replacement. + Therefore, redshift-ng implements the command "redshift" just like the + original Redshift implementation. + +NAME + redshift - Automatically adjust display colour temperature according the Sun + +SYNOPSIS + redshift [-b day:night] [-c file] [-g r:g:b] [-m method[:options]] + [-l latitude:longitude | -l provider[:options]] + [-o | -O temperature | -t day:night | -x] [-hpPrvV] + +DESCRIPTION + 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. + + 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 higher temperature on an overcast day. + + In addition to the command-line tool redshift, the GUI redshift-gtk + provides an alternative interface that shows up as a notification icon + in the desktop environment. + +OPTIONS + The following options are supported: + + -b day:night + Screen brightness to apply at daytime and at nighttime. + (Default: 1:1) + + The value most be between 0.1 and 1.0. + + -c file + Load settings from specified configuration file. + + -g r:g:b + Additional gamma correction to apply. (Default: 1:1:1) + + -h + Display help message. + + -l 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. + + -l provider[:options] + Select provider for automatic location updates. + + Use "-l list" to see available providers. + + Use "-l provider:help" to see available options. + + -m method[:options] + Method to use to set colour temperature. + + Use "-m list" to see available methods. + + Use "-m method:help" to see available options. + + -o + One-shot mode (do not continuously adjust colour temperature). + + Use this with the -P option to clear the existing gamma ramps + before applying the new color temperature. + + -O temperature + One-shot manual mode (set colour temperature). + + Use this with the -P option to clear the existing gamma ramps + before applying the new color temperature. + + -p + Print parameter and exit. + + -P + Reset exiting gamma ramps before applying new scolour effects. + + -r + Disable fading between colour temperatures. + + -t day:night + Colour temperature to set at daytime and at nighttime. + + -v + Enable verbose output. + + -V + Show program implementation and verison. + + -x + Remove adjustments from screen. + +OPERANDS + None. + +STDIN + Not used. + +INPUT FILES + None. + +ASYNCHRONOUS EVENTS + redshift takes the standard action for all signals except: + + TODO + +STDOUT + TODO + +STDERR + Default. + +OUTPUT FILES + None. + +FILES + TODO + +EXTENDED DESCRIPTION + Gamma ramps + 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. + + redshift uses colour correction lookup tables (CLUTs), usually called + gamma ramps or gamma correction ramps, to apply this effect. + + Colour temperature + The redness effect applies 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 + 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. + + 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 redshift's defines this illuminant has having the + colour temperature 6500K. This means that 6500K is the neutral (no + effect) colour temperature. + + The current version 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. + +EXIT STATUS + TODO + +EXAMPLES + TODO + +KNOWN ISSUES + 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. + + D65-flashes + For some versions of some graphics drivers, there will be an occasional + flash where gamma ramps are not applied to the output. + + Limited hardware support + Low-end hardware, especially embedded devices, often lack colour + correction features redshift abuse to apply it's affect. 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 + 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 + applications like redshift. + + Backlight control + 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 + adjbacklight(1). + + Flickering and temporary suspension + 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, 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. + +RATIONALE + To prevent the user from accidental making the screen black, brightness + level below 0.1 are forbidden. + + To prevent colour distortion and making the screen too white, brightness + level above 1.0 are forbidden. + +NOTES + "Colour temperature", or just "temperature", is actually short for + "correlated colour temperature". (Your monitor is not a black-body + radiator.) And specifically the correlated colour temperature of the + monitor's whitepoint. + + 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. + +SEE ALSO + cg-tools(7), coopgammad(1), radharc(1) diff --git a/README.md b/README.md deleted file mode 100644 index cc226d8..0000000 --- a/README.md +++ /dev/null @@ -1,147 +0,0 @@ - -Redshift -======== - -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. - -README versions: [latest](https://github.com/jonls/redshift/blob/master/README.md) | [1.12](https://github.com/jonls/redshift/blob/v1.12/README.md) | [1.11](https://github.com/jonls/redshift/blob/v1.11/README.md) - - - -Run `redshift -h` for help on command line options. You can run the program -as `redshift-gtk` instead of `redshift` for a graphical status icon. - -* Project page: https://github.com/jonls/redshift - -Build status ------------- - -[](https://travis-ci.org/jonls/redshift) -[](https://ci.appveyor.com/project/jonls/redshift) - -Technical Details (Gamma Ramps) -------------------------------- - -Redshift applies a redness effect to the graphical display. The intensity of the redness can be customized and -scheduled to only be applied at night or to be applied with more intensity at night. - -Redshift uses the gamma correction ramps to apply this effect which has traditionally been the only -way of applying a color effect to the display. Note that this is really a hack to work around the absense of a -standardized way of applying color effects, and it is resulting in several issues some of which are explained in -the _FAQ_ section below. As long as Redshift is using gamma ramps, many of these issues are impossible to solve properly -in Redshift. - -Since Redshift was first created, many desktop environments have adopted similar functionality as an integrated -component: - -- GNOME: [Night Light](https://www.gnome.org/news/2017/03/gnome-3-24-released/attachment/night-light/) -- Plasma: Night Color -- Windows: [Night Light](https://support.microsoft.com/en-us/help/4027563/windows-10-set-your-display-for-night-time) -- macOS: Night Shift - -Using the features integrated into the desktop environments avoids many of the issues with gamma ramps which is why -these implementations should generally be favored over Redshift. On the other hand, Redshift may offer some additional -flexibility that is not available in the integrated features. - -FAQ ---- - -### How do I install Redshift? - -Use the packages provided by your distribution, e.g. for Ubuntu: -`apt-get install redshift` or `apt-get install redshift-gtk`. For developers, -please see _Building from source_ and _Latest builds from master branch_ below. - -### How do I setup a configuration file? - -A configuration file is not required but is useful for saving custom -configurations and manually defining the location in case of issues with the -automatic location provider. An example configuration can be found in -[redshift.conf.sample](redshift.conf.sample). - -The configuration file should be saved in the following location depending on -the platform: - -- Linux/macOS: `~/.config/redshift/redshift.conf` (if the environment variable `XDG_CONFIG_HOME` is undefined) or `${XDG_CONFIG_HOME}/redshift/redshift.conf` (if `XDG_CONFIG_HOME` is defined). -- Windows: Put `redshift.conf` in `%USERPROFILE%\AppData\Local\` - (aka `%localappdata%`). - -### Where can I find my coordinates to put in the configuration file? - -There are multiple web sites that provide coordinates for map locations, for -example clicking anywhere on Google Maps will bring up a box with the -coordinates. Remember that longitudes in the western hemisphere (e.g. the -Americas) must be provided to Redshift as negative numbers. - -### Why does GeoClue fail with access denied error? - -It is possible that the location services have been disabled completely. The -check for this case varies by desktop environment. For example, in GNOME the -location services can be toggled in Settings > Privacy > Location Services. - -If this is not the case, it is possible that Redshift has been improperly -installed or not been given the required permissions to obtain location -updates from a system administrator. See -https://github.com/jonls/redshift/issues/318 for further discussion on this -issue. - -### Why doesn't Redshift work on my Chromebook/Raspberry Pi? - -Certain video drivers do not support adjustable gamma ramps. In some cases -Redshift will fail with an error message, but other drivers silently ignore -adjustments to the gamma ramp. - -### Why doesn't Redshift change the backlight when I use the brightness option? - -Redshift has a brightness adjustment setting but it does not work the way most -people might expect. In fact it is a fake brightness adjustment obtained by -manipulating the gamma ramps which means that it does not reduce the backlight -of the screen. Preferably only use it if your normal backlight adjustment is -too coarse-grained. - -### When running as a systemd service, redshift fails to connect to the graphical environment - -You need to export your environment variables when your window manager or -compositor start up. Typically, you want to run this as part of its startup: - - systemctl --user import-environment; systemctl --user start graphical-session.target - -See your compositor's (or window manager's) documentation for further details -of setting up the systemd user session. - -Related issues: [#753](https://github.com/jonls/redshift/pull/753). - -### The redness effect is applied during the day instead of at night. Why? - -This usually happens to users in America when the longitude has been set in the -configuration file to a positive number. Longitudes in the western hemisphere -should be provided as negative numbers (e.g. New York City is at approximately -latitude/longitude 41, -74). - -### Why does the redness effect occasionally switch off for a few seconds? - -Redshift uses the gamma ramps of the graphics driver to apply the redness -effect but Redshift cannot block other applications from also changing the -gamma ramps. Some applications (particularly games and video players) will -reset the gamma ramps. After a few seconds Redshift will kick in again. There -is no way for Redshift to prevent this from happening. - -### Why does the redness effect continuously flicker? - -You may have multiple instances of Redshift running simultaneously. Make sure -that only one instance is running for the display where you are seeing the -flicker. - -### Why doesn't Redshift change the color of the mouse cursor? - -Mouse cursors are usually handled separately by the graphics hardware and is -not affected by gamma ramps. Some graphics drivers can be configured to use -software cursors instead. - -### I have an issue with Redshift but it was not mentioned in this FAQ. What do I do? - -Please go to [the issue tracker](https://github.com/jonls/redshift/issues) and -check if your issue has already been reported. If not, please open a new issue -describing you problem. @@ -196,3 +196,5 @@ po/sv.po: felaktig -> ogiltig (?) po/sv.po: NBSP before units (after ° which should also be added) Translate gamma-coopgamma.c Previously unmarked for NLS: redshift.c: "Unable to load config file." +Optionally use METAR data adjust day-time colour temperature according the cloudiness +read the monitores chromas to determine it's colour space and correct the RGB multipliers according |