dispwin
Author: Graeme Gill

## spectro/dispwin

### Summary

This tool has several different but related functions. When given as a file argument an ICC profile containing vcgt "gamma" curves, or an Argyll video calibration .cal file, it will load that calibration into the chosen display. It can also install or uninstall a profile in the system for the chosen display, or set the display calibration to that in the currently installed system profile. By default it displays a test window the same as that used by dispcal and dispread, to test this functionality. It can also be used to test the ability to load video card LUT curves to each display, and to test how the console Bell will sound when used with some instruments (ie. Eye-One Pro).
[Note that in OS X 10.7 Lion, changes to the default system profile permissions mean that you can't set a calibration persistently when the default system profile is being used, unless you run as root (ie. use sudo). Note that you do not need to run as root to install a user profile (-Su, the default install type.)]

### Usage

dispwin [options] [calfile]
-v Verbose mode
-display displayname [X11 only] Choose X11 display name
-d n[,m] [X11 only] Choose the display from the following list (default 1),
and optionally choose a different display m for Video LUT access.
-d n [Not X11] Choose the display from the following list (default 1)
-d web[:port] Display via a web server at port (default 8080)
`` `-d cc[:n]` `Display via n'th ChromeCast (default 1, ? for list)
` -d madvr [MSWin] Display via MadVR Video Renderer
`-d dummy Display via dummy (non-existant, invisible) display
` -P ho,vo,ss[,vs] Position test window and scale it
ho,vi: 0.0 = left/top, 0.5 = center, 1.0 = right/bottom etc.
ss: 0.5 = half, 1.0 = normal, 2.0 = double etc.
ss,vs: = optional horizontal, vertical scale.
-F Fill whole screen with black background
-E Video encode output as (16-235)/255 "TV" levels
-i Run forever with random values
-G filename Display RGB colors from CGATS file
-m Manually step through colors
-Y msec patch delay in msec (default 2000)
-r Test just video LUT loading & Beeps
-n Test native display values (rather than through Video LUT and C.M.)
-s filename.cal Save the currently loaded Video LUT to 'filename'
-c Load a linear display calibration (clear calibration)
-V Verify that calfile/profile cal. is currently loaded in LUT
-I Install profile for display and use its calibration
-U Un-install profile for display
-S d Specify the install/uninstall scope for OS X [nlu] or Vista [lu]
d is one of: n = network, l = local system, u = user (default)
-L Load installed profiles cal. into Video LUT
-x [X11 only] Load all profiles for given X11 server
-X [X11 only] Run in daemon loader mode for given X11 server
-D [level] Print debug diagnostics to stderr
calfile Load display calibration (.cal or .icm) into LUT, and exit.

### Comments

The -v flag makes the program more verbose..
display: When running on a UNIX based system that used the X11 Windowing System, dispwin will by default use the $DISPLAY environment variable to determine which display and screen to read from. This can be overridden by supplying an X11 display name to the -display option. Note that if Xinerama is active, you can't select the screen using $DISPLAY or -display, you have to select it using the -d parameter.
-d: By default the location of the test window will be the main display. If the system has more than one display or screen, an alternate display/screen can be selected with the -d parameter. If you invoke dispwin so as to display the usage information (i.e. "dispcal -?" or "dispcal --"), then the discovered displays/screens will be listed. Multiple displays may not be listed if they appear as a single display to the operating system (ie. the multi-display support is hidden in the video card driver). On UNIX based system that used the X11 Windowing System, the -d parameter will override the screen specified by the $DISPLAY or -display parameter.
Note that if VideoLUTs for a display are not accessible (i.e. no hardware calibration capability), dispwin will will issue a warning or fail when it attempts to access them.
On X11 the inability to access VideoLUTs could be because you are trying to access a remote display, and the remote display doesn't support the XF86VidMode extension, or perhaps you are running multiple monitors using NVidia TwinView, or MergedFB, and trying to access anything other than the primary monitor. TwinView and MergedFB don't properly support the XF86VidMode extension for multiple displays. You can use dispwin -r to test whether the VideoLUTs are accessible for a particular display. See also below, on how to select a different display for VideoLUT access. Also note that dispcal will fail if the Visual depth doesn't match the VideoLUT depth. Typically the VideoLUTs have 256 entries per color component, so the Visual generally needs to be 24 bits, 8 bits per color component.
More modern X11 systems support the XRANDR extension, which handles multiple displays much more gracefully, but note that there are limitations in profiling and calibrating Mirrored or Cloned Displays. Mirrored displays share the same frame buffer space (Separate CRTC's with overlapping pixel locations) but can have different calibration curves, while Cloned displays share both frame buffer space and calibration curves (A single CRTC feeding multiple Outputs). dispwin will show different display selections for each output, but calibration or application of color management may only be correct for the last set display (i.e. if frame buffer space overlaps, or there is only a single CRTC to hold calibration curves, and a single _ICC_PROFILE_xxx root atom holding the profile, if the application is using the Xinerama convention for obtaining a profile, rather than the Xrandr per Output property _ICC_PROFILE convention.)
-d n[,m]Because of the difficulty cause by TwinView and MergedFB in X11 based systems, you can optionally specify a separate display number after the display that is going to be used to present test patches, for accessing the VideoLUT hardware. This must be specified as a single string, e.g. -d 1,2 . Some experimentation may be needed on such systems, to discover what screen has access to the VideoLUT hardware, and which screens the test patches appear on. You may be able to calibrate one screen, and then share the calibration with another screen. Profiling can be done independently to calibration.
-dweb or -dweb:port starts a standalone web server on your machine, which then allows a local or remote web browser to display the the color test patches. By default port 8080 is used, but this can be overridden by appending a : and the port number i.e. -dweb:8001. The URL will be http:// then name of the machine or its I.P. address followed by a colon and the port number - e.g something like http://192.168.0.1:8080. If you use the verbose option (-v) then a likely URL will be printed once the server is started, or you could run ipconfig (MSWin) or /sbin/ifconfig (Linux or OS X) and identify an internet address for your machine that way. JavaScript needs to be enabled in your web browser for this to work. You may have to modify any firewall to permit port 8080 to be accessed on your machine.
Note that if you use this method of accessing a display, that there is no access to the display Video Lookup tables, and that any operation that depends on accessing the VideoLUTs will either generate a warning or fail.
-dcc or -dcc:no causes test patches to be displayed using and available ChromeCast to your TV. Use -dcc:? to display a list of ChromeCasts on your local network. Note that the ChromeCast as a test patch source is probably the least accurate of your choices, since it up-samples the test patch and transforms from RGB to YCC and back, but should be accurate within ± 1 bit. You may have to modify any firewall to permit port 8081 to be accessed on your machine if it falls back to the Default receiver (see installation instructions for your platform).
-dmadvr [MSWin only] causes test patches to be displayed using the MadVR video renderer. Note that will have to start MadTPG before running dispread, and that while you can adjust the "Test Pattern Configuration" controls, you should not normally alter the "Existing Calibration" controls, as dispread will set these appropriately. See -n flag.
-ddummy causes test patches not to be displayed at all.
The -P parameter allows you to position and size the test patch window. By default it is places in the center of the screen, and sized appropriately for the type of instrument, or 10% of the width of the display if the display size is unknown.. The ho and vo values govern the horizontal and vertical offset respectively. A value of 0.0 positions the window to the far left or top of the screen, a value of 0.5 positions it in the center of the screen (the default), and 1.0 positions it to the far right or bottom of the screen. If three parameters are provided, then the ss parameter is a scale factor for the test window size. A value of 0.5 for instance, would produce a half sized window. A value of 2.0 will produce a double size window. If four parameters are provided, then the last two set independent horizontal and vertical scaling factors. Note that the ho,vo,ss or ho,vo,hs,vs numbers must be specified as a single string (no space between the numbers and the comma). For example, to create a double sized test window at the top right of the screen, use -P 1,0,2 . To create a window twice as wide as high: -P 1,0,2,1.
The -F flag causes the while screen behind the test window to be masked with black. This can aid black accuracy when measuring CRT displays or projectors.
The -E flag causes the test values to be scaled to the Video RGB encoding range of 16/255 to 235/255. Note that this is not applicable if the MadVR render is being used to display patches, as MadVR should be configured for Video encoding instead.
By default dispwin will put a test window on the selected display, and display some test colors, before darkening then brightening the screen by loading video LUT values, test the bell sounds, then restore the original values and exit.
If the -i flag is set, then dispwin will display the preset sequence, then random test colors forever.
If the -G parameter is set, then dispwin will display the sequence of RGB color in the supplied CGATS file, e.g. a .ti1 file. Typically this might the used with the -m option to manually measure a set of test patches.
If the -m flag is set, then dispwin will display the preset sequence then exits, but advances manually after each return key.
If the -Y parameter is set, then the default automatic patch delay of 2000 msec can be overridden.
If the -r flag is set, then dispwin will test just the loading of video LUT values by first darkening, then lightening the screen, before exiting.
If the -n flag is set, then dispwin will display the colors directly on the display, rather than having the color values translated through the currently loaded Video LUTs. In the case of using the MadVR renderer to display the patches, any 3dLut will also be disabled.
If a -s filename.cal option is used, then rather than displaying a test window, dispwin will save the currently loaded calibration curves to the given calibration file. Note that other functions such as clearing or loading a calibration can be performed after this action.
If a -c flag is used, then rather than displaying a test window, dispwin will load the selected display with a linear set of Video LUT curves, effectively clearing the calibration, and will then exit. Note that other functions such as loading a calibration can be performed after this action.
If a -V flag is used, then rather than loading the calibration specified as the final argument, the currently loaded calibration will be verified as being the same as the given calibration file. If this is combined with the -L flag, the currently loaded calibration will be verified as being the same as the installed system profile for the display.
-I: The ICC profile specified as the final argument will be installed as the default operating system profile for the chosen display, and the display calibration will be set to the calibration tag ('vcgt' tag, if any) in that profile. On MSWindows and OS X this means that the profile will be copied to the appropriate color profile directory and registered with the operating system.
(Note that on older MSWindows systems you may have to manually check that the installed profile is the default by looking in display->properties->settings->advanced->Color Management.)
For Linux X11 systems, the profile will be installed using using the ucmm convention by default, and this associates the display hardware identification (EDID) of the selected display, with the profile. The X11 _ICC_PROFILE property will be set in the root window, and also the the XrandR 1.2 X11 _ICC_PROFILE output property on systems that are running XrandR 1.2 or later. The use of atoms is following this convention for allowing applications to locate the display profile for a particular X11 display, and expands it to accomodate XrandR 1.2. Note that for X11 systems, the properties are not persistent, and will need to be loaded each time the X11 server is started (see the -L flag).
If the ARGYLL_USE_COLORD environment variable is set (ie. set it to "yes"), then on Gnome systems running colord, dispwin will attempt to store and retrieve display ICC profiles using
colord.
To make sure that the profile calbration 'vcgt' tag gets loaded into the Graphics Card at system start, please read the guide here.
-U: The ICC profile specified as the final argument will be un-installed as the default operating system profile for the chosen display. The display calibration will remain unchanged.
-S d: Some systems have more than one profile scope that an installed profile will apply to, and this parameter allows overriding the default user scope. On OS X, there is a choice of three scopes: n: for network scope, if people are sharing profiles over a network, l: local system scope, which installs the profile for all users of a system, and the default u, which covers just the user installing the profile. On Linux or Microsoft Vista, just the local system l and user u scope are available. Note that you may need to run dispwin with elevated privileges(sudo) to be able to successfully use network or local system scope. This option also applies to uninstalling a profile. Note that to install a user profile for the root account, you will have to login as root (sudo will not achieve this).
-L: This option fetches the current installed system profile for the chosen display, and sets the display to the calibration tag ('vcgt' tag, if any) in the profile. This is a convenient way of initializing the display on system startup from the installed display profile, if the system doesn't not do this automatically .
-x: When running on a UNIX based system that used the X11 Windowing System, it will load the installed profiles of all the screens of the given X11 server. This may be useful on startup, or when called from a udev script triggered by attachment of a display.
-X: Daemon mode (experimental). When running on a UNIX based system that used the X11 Windowing System, this option runs dispwin in a "daemon" mode where it monitors the given X11 server, waiting for any changes in monitors that may require loading a matching ICC profile (ie. such as re-configuring, plugging in a different monitor etc.) This only works if XRandR 1.2 is available on the server. By default dispwin runs silently, and will not terminate. If the -v option is given, it will emit messages to stdout to show what it is doing. When it is first invoked, it will load the installed profiles of all the screens of the given X11 server.
The -D flag causes diagnostics to be printed to stdout. A level can be set between 1 .. 9, that may give progressively more verbose information. This can be useful in tracking down why an operation fails.
The final optional parameter on the command line is the name of an ICC profile that contains a Video LUT vcgt tag, or an Argyll .cal format display calibration. If this parameter is provided, then the selected display will be loaded with the given calibration. If the -V flag was given, then it is verified that this calibration is the currently loaded one. This may be useful in initializing a system to the current calibration on system startup, although a better way may be to install the profile (-I option), and then just use -L. Note that the vcgt tag interpretation within Argyll is consistent with that of the originators of the tag. Other ICC profile vcgt implementations may not be so consistent.
NOTE that on an X11 system, if the environment variable ARGYLL_IGNORE_XRANDR1_2 is set (ie. set it to "yes"), then the presence of the XRandR 1.2 extension will be ignored, and other extensions such as Xinerama and XF86VidMode extension will be used. This may be a way to work around buggy XRandR 1.2 implementations.
NOTE on MSWin systems that you will have to disable any other calibration installer program if you want to be able to control calibration using dispwin. Note also that there are other programs that will interfere with calibration loading, such as igfxpers.exe that gets installed with nVidia "Optimus" technology.