openicc / xcalib

Load 'vcgt'-tag of ICC profiles to X-server and MS-Windows. Works on calibration stage, which can be a precondition for display ICC color conversions.

xcalib 0.11

WWW - codeberg.org/OpenICC/xcalib

(c) 2004-2007 Stefan Döhla This program is GPL-licensed postcardware! More infos at end of README. This program comes with ABSOLUTELY NO WARRANTY! Use on your own risk.

purpose

load 'vcgt'-tag of ICC profiles to X-server like MS-Windows or MacOS do it to calibrate your display. Versions 0.5 and higher are also usable with Microsoft Windows. They can be used as a free alternative to other calibration loaders.

usage

xcalib Tool Syntax de

last parameter MUST be an ICC profile containing a vcgt or mLUT tag or empty if the "-a" or "-alter" paramter is used or the LUT is to be cleared.

use profiles gamma_1_0.icc and gamma_2_2.icc for testing. Profiles with vcg-tables can be created with most profile creation suites. An example profile with a vcg-table is inclued, named bluish.icc, which simulates a very high whitepoint (without further intentions).

!Special note for Win32 users: If there is a default profile set for the primary display, running xcalib.exe without any arguments will use the Windows default profile.

If the profile contains gamma values, these values may be related to a special global gamma value. The default internal correction value is 1.0, as Apple does (the creator of these calibration tags in ICC profiles). To resemble the behaviour of the Windows XP Color Control Panel, pass "-gammacor 2.2" if you think, the screen is way to bright.

The values that shouldn't alter the screen for gamma, brightness and contrast are gamma=1.0 brightness=0.0 and contrast=100.0 .

requirements

LINUX/UNIXes

This program is intended for X11-Servers like XFree86 that come with XVidModeExtension (e.g. XFree86 4.x.x) and XRandR. Make sure that the extension is available. Other X-servers like OpenWin do not contain XVidMode stuff - so please don't ask me for support if XVidMode isn't supported. If you are experiencing problems with the X.org server because of missing XVidMode header files, search for the additional packages that are available for most distributions. Debian provides the headers by the package libxxf86vm-dev package.

As of version 0.6, a special treatment for the close-source ATI FGLRX X11 driver was added. The libs and header files are provided but may need to be updated for the most current video cards. The X11 and XVidMode headers are still required. Thanks to bleader who sent me a patch for multi-monitor support

Microsoft Windows

Since version 0.5, Win32-support was added. The program will work with most video cards, that have correctly implemented drivers. You need a working C compiler with the right windows headers to rebuild xcalib. Thanks to gl.tter multi-monitor support for Win32 is now available.

testing

You need a profile which contains the 'vcgt' tag to achieve monitor calibration. You can create it with some commercial windows profile creation programs or use the bundled ones from Bruce Lindbloom (only Gamma 1.0 and 2.2).

If you prefer using free (as the free in open-source) profile creation programs, have a look at current versions of ArgyllCMS. It was mentioned that LProf is now also capable of creating monitor profiles with vcgt tags included.

install

The bundled Makefile should work on most systems. It is very simple and doesn't use automake/autoconf stuff. Therefore you and I (the author) save time writing fancy autoconf/automake tests. One of the following commands should lead you to a working version of xcalib:

$ make xcalib
$ make win\_xcalib
$ make fglrx\_xcalib

For most UNIX-based systems the default version of xcalib should work. It only uses the XVidMode-Extension. The following command creates the executable:

$ make xcalib

The Win32 version was made with and tested for MinGW. Since most users do not have a running MinGW environment, a binary executable is provided. To compile it on your own, the following command creates a working Win32-build (tested with MSys):

$ make win\_xcalib

For ATI's proprietary FGLRX driver for X11, a special version can be built. Issue the command

$ make fglrx\_xcalib

motivation

ICC profiles created and used with MS-Windows can now also be used with Linux and other unixes with LCMS, Marti's ICC library. Some applications can already apply profiles (even display profiles) but they often use standard monitor profiles or custom profiles created for a calibrated monitor.

Calibration is the motivation for xcalib. Calibration brings your monitor to a defined state. Color spaces of profiles are often only valid for this defined state, which was created by a calibration.

Whenever you use a display profile, created with Gretag's ProfileMaker, AdobeGamma (not that good but better than nothing) or most other ICC profile creation packages, 'vcgt'-tags are included. These profiles are only valid with calibration applied!

You get the point?

Once again, a profile contains mainly the characterization of a device. This characterization should be constant over time for as long as possible. Therefore, you need a defined state, you can return to - this is the calibrated state.

Calibration linearizes your device, helps to set characteristics and can be easily repeated. Repeating calibration can help you to keep your profile constant (users don't need to change it).

The current way of embedding calibration data in a profile is against the theory of separating calibration from profiling - but we have to live with it since it's common. They use a tag called Video Card Gamma Tag (or vcgt) in ICC-profiles that contains calibration values. The calibration is applied before profile creation, where the vcgt

will be saved in your profile for convenience reasons: All color settings for the display device are stored in a common file.

So, let's repeat: We have calibration and profile creation - which are not the same. But calibration helps the user in the profile creation by having a linear (or linear with respect to a fixed gamma value) display device.

Linux was missing a tool like 'AdobeGammaLoader' or 'Logo Calibration Loader' which applied the vcgt-tag to the video-LUT (a matrix which assigns one color value to another). Under Linux we can not set the video-LUT itself but a X-server gamma ramp (which does practically the same).

Applying gamma ramps in the video-LUT has one big advantage: If used with proper values, all applications benefit from a monitor in a defined/calibrated state - although not using color management!

But keep the drawback in mind: you will lose some resolution by using a tool like AdobeGamma over xcalib. This may lead to posterization artifacts on your display (but doesn't affect printouts). You should tweak your monitor for perfect linearization as much as possible - the remaining tweaks might be part of a profile (, the "vcgt" tag).

If you want to come around that drawback: bug your video card vendor and ask for >8bit LUTs (plus LUTs for every output connector).

limitations

Not all XFree video card drivers do allow changing the gamma ramps. And video cards are often having only one LUT for all outputs - although they are dual-head models.

Known not-working drivers:

• vesa (generic driver without any calibration knobs)
• fglrx (but you can build fglrx_xcalib)
• savage with other depths than 24 (known bug in savage driver) => solution: change DefaultDepth to 24 in xorg.conf if you have enough video memory (may not work together with 3D).

If you see both/only one/no display changing it's behaviour, test if it's a bug of xcalib by cross-checking with the 'xgamma' tool that comes with every XFree86/X.org distribution.

Custom curves created with AdobeGamma do not contain these in the vcgt. The vcgt contains 2.2 in all cases, whereas the real LUT-values that are downloaded to the X-server are located somewhere else in the system - but nobody know's where. Please tell me where they are - if you find them. A newer version of AdobeGamma (from 2003) writes a vcgt tag with useful data. Nevertheless, the size field is wrong. As of version 0.6, a work-around for wrong AdobeGamma profiles (created with the 2003 version) was added to the internal parser.

On Win32-systems, some drivers are not correctly implemented. E.g. the NVidia Riva driver for Windows2000 and WindowsXP wrote nonsense values to the video cards RAMDAC (resulting in a gray display). I used for these cards an old NT-driver from a video card vendor.

The source code became messy in the last time because of numerous workarounds and a bad mixture of Win32, X11, ATI code and code for the different parsers used to get the gamma ramps from the profile. This makes it hard to find the important code sections for others than me and might have lead to bugs or leaks. A following version may be written in C++ to ease modularization of the code and allow utilization by other software.

history

0.10: 2018-01-10

• Fix incorrect use of X11 screen and output; rename -s to -o option

0.9: 2014-11-09

• fix rounding errors from upsampling of gamma ramps
• fix -printramps uses integers
• support XRandR

0.8: 2007-08-27

• applied gl.tter's patch for Win32 multi-monitor support
• applied bleader's patch for FGLRX multi-monitor support
• added support for LUTs bigger than in the profile linear interpolation is used for creating the values in between
• changed -n parameter: now the size of the simulated LUT must be given after -n/-noaction paramter

0.7: 2007-06-23

• major code-cleanup
• fixed gamma limits for vcg-formulae thanks to Graeme Gill, who pointed out the mistake
• implemented user-changeable gamma correction
• added alteration of existing LUTs
• added parameters for addiditional brightness, contrast, gamma either globally or per color
• removed icclib for parsing ICC profiles
• removed the LCMS patch since it doesn't work with newer versions
• check string sizes before strcpy now
• fixed Win32 ICM profile fetching
• added inversion of all values: not related to color-management but funny feature for the weekends
• updated this README

0.6: 2005-09-30

• added 0-interpolated upscaling if LUT>vcgt
• added reading of mLUT instead of vcgt (not memory-safe for now) this is used for profiles, created by ProfileMechanic Monitor
• added parsing of obviously wrong profiles made by AdobeGamma
• added fglrx version for ATI's proprietary driver
• added loss calculation (option "-loss" or "-l") which shows how many steps are lost by calibrating the device
• added limits of VideoCardGammaFormula to internal parser

0.5: 2005-03-03

• Win32 version added (compilable with MinGW)
  • support for command line options as usual
  • support for loading the default display profile
• fixed bug with 8bit vcg-tables in internal and icclib version this applied to Pantone ColorVision Spyder profiles only thanks to John Ackerman who found this really grave bug
• fixed bug in lcms patch regarding gamma table endpoints use a unpatched version of lcms for patching
• introduced macro for little-endian parsing in internal parser
• got rid of some compiler warnings because of multi-byte constants
• introduced variables in Makefile so that the user can set locations for X11 and patched lcms libs and headers
• beautified code for better readability
• added sample profile which contains a vcg-table

0.4: 2005-01-30

• own implementation for parsing the vcgt tags added.
• switch to lcms-1.13 (patched) instead of icclib use different make target to activate it
• LUTs and vcgt-content may now have different size. LCMS does scaling for xcalib this only works with a LCMS build for now
• much icc- and vcgt-stuff was exported to LCMS, to give every user the ability to use it and to make xcalib's code less confuscating apply the bundled patch to LCMS
• minor README changes to ease readability

0.3:

• raise error if no vcg-tag available
• profile no more a necessary parameter after -c and -h option
• some code cleanup

0.2: public pre-release

• added option to reset gamma table to system default (gamma 1.0)
• screen and display can be selected now
• as system gamma for Linux, 1/0.45 = 2.222 is assumed
• bugfixes

0.1:

• initial version with vcg-table and vcg-formula working

todo

• integrate the _ICC_PROFILE atom
• interpolated upscaling
• use ATI's API when using the closed-source X11 ATI driver
• further code review for memory leaks
• use platform independent types for better portability
• use lcms instead of icclib: worse vcgt-parsing but functions for gamma ramp building and smoothing
• add multi-monitor support to Win32 version
• apply bleader's patch for multiple FGLRX cards

bugs

if not already mentioned in this README, contact the author if you find bugs in this software.

author

Stefan Döhla

thanks

• Graeme Gill for his icclib which I used to parse ICC profiles in versions prior 0.4 and which contained vcgt-parsing source code. Note that he has a similar tool now, called dispwin. Because both tools are similar, he found some ambiguity in the case of gamma values and limits in vcgt tags. Thanks, Graeme, keep up the good work!

• Kai-Uwe Behrmann for his ideas and alpha-testing Note that Kai-Uwe uses xcalib in his Oyranos package

• RRZE (Regionales Rechenzentrum Erlangen) which employed me to ensure constant color quality for their large-format-printers and led me to color-management using ICC profiles

• My current employer for giving me the bucks I need to buy everyday-stuff and bringing happiness to my life

• The X11-team for implementing the gamma ramps (but they weren't used!?)

• Gretag/Logosoft for their ProfileMaker software which my former employer bought - and MonitorCalibrationTester, to debug vcgt-stuff on Win32

• Marti Maria and his lcms-community which led me to the vision of having xcalib Marti especially for LCMS: his lib for color-management

• Bruce Lindbloom for his ICC-profiles using vcg-formulae

• gl.tter for his work on multi-monitor support for Win32 see his website at http://gl.tter.org

• bleader for his work on multi-monitor support for ATI's FGLRX

links

The following links might lead you to other Linux color management ressources:

• Little CMS
• ArgyllCMS
• coloraid
• Oyranos
• LProf

license

You should have received a copy of the GPL together with this software. Furthermore, it is postcardware. So if you like this program, send me a picture postcard from your country/area to:

Stefan Doehla
Steinselb 7
95100 Selb
GERMANY

Please write on it your name and email-address and that you use xcalib-0.11 .

EOF

xcalib's Issues

xcalib -invert -alter doesn't work, but increases gamma

On Arch-Linux with AMD APU (amd-xorg drivers), xcalib v. 0.10, the inversion via "xcalib -i -a" but only increases the gamma heavily.

This bug was also reported by others:
https://bugzilla.redhat.com/show_bug.cgi?id=1662620
https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=913849
zoltanp/xrandr-invert-colors#20

Driver-Info:

lspci -k | grep -EA3 'VGA|3D|Display'
05:00.0 VGA compatible controller: Advanced Micro Devices, Inc. [AMD/ATI] Picasso (rev c1)
	Subsystem: Lenovo Picasso
	Kernel driver in use: amdgpu
	Kernel modules: amdgpu

Use case examples for xcalib

I have one. I have a laptop that rides around in my car with me, and I like to use a high gamma to help deal with impinging skylight. At night, I use an inverted display to minimize total light output so my eyes can remain dark-adapted. I have a panel button that triggers a script to make the changes:

#!/bin/bash
if test -f ~/.altered-display; then
    xcalib -c;
    if test -f ~/.inverted-display; then              #normal display
        rm ~/.altered-display ~/.inverted-display;
    else                                  #nighttime inverted display
        xcalib -red 0.7 0 100 -green 0.7 0 80 -blue 0.7 0 59 -i -a;
        mv ~/.altered-display ~/.inverted-display;
    fi
else
    if test -f ~/.inverted-display; then
        xcalib -co 60 -a;             #nighttime away from city lights
    else
        xcalib -gc 2.2 -a;            #high gamma for incident sunlight
    fi;
    touch ~/.altered-display;
fi;

I also like to see the gamma ramps on occasion. This works-for-me:

xcalib -p -a | grep ^[0-9] | graph -a -T X -x 0 3071 -y 0 65535 -m 0 -X "$(xcalib -l -a | tail -n 1)"

Update ubuntu repo

The Ubuntu repo is too old. Please update it, the old version didn't work on my computer.

invert colors results in extremely bright, white unreadable screen

See video attached, the inversion appears to do something but the result is an extremely bright, mostly white display.

output.mp4

█[phantom][~][0]$ xcalib -i -a -v
Red Brightness: 0.000000   Contrast: 100.000000  Max: 1.000000  Min: 0.000000
Green Brightness: 0.000000   Contrast: 100.000000  Max: 1.000000  Min: 0.000000
Blue Brightness: 0.000000   Contrast: 100.000000  Max: 1.000000  Min: 0.000000
X-LUT size:             1024
█[phantom][~][0]$ xcalib -i -a -v
Red Brightness: 100.000000   Contrast: -inf  Max: 0.000000  Min: 1.000000
Green Brightness: 100.000000   Contrast: -inf  Max: 0.000000  Min: 1.000000
Blue Brightness: 100.000000   Contrast: -inf  Max: 0.000000  Min: 1.000000
X-LUT size:             1024
█[phantom][~][0]$ 

graphics card:

█[phantom][~][130]$ inxi -G
Graphics:
  Device-1: AMD Ellesmere [Radeon RX 470/480/570/570X/580/580X/590]
    driver: amdgpu v: kernel
  Display: server: X.Org v: 1.21.1.7 driver: X: loaded: amdgpu
    unloaded: fbdev,modesetting,vesa dri: radeonsi gpu: amdgpu
    resolution: 3840x2160~30Hz
  API: OpenGL v: 4.6 Mesa 22.3.6 renderer: AMD Radeon RX 580 Series
    (polaris10 LLVM 15.0.6 DRM 3.49 6.1.0-16-amd64)

This is on debian bookworm and xcalib 0.8

█[phantom][~][0]$ lsb_release -a
No LSB modules are available.
Distributor ID: Debian
Description:    Debian GNU/Linux 12 (bookworm)
Release:        12
Codename:       bookworm
█[phantom][~][0]$ xcalib -version
xcalib 0.8
█[phantom][~][0]$ 

Color inversion works normally from a different machine using the same monitor, same OS, same xcalib version but different graphics card:

+ inxi -G
Graphics:
  Device-1: Intel WhiskeyLake-U GT2 [UHD Graphics 620] driver: i915 v: kernel
  Device-2: Chicony Integrated Camera type: USB driver: uvcvideo
  Display: x11 server: X.Org v: 1.21.1.7 driver: X: loaded: modesetting
    unloaded: fbdev,vesa dri: iris gpu: i915 resolution: 1920x1080~60Hz
  API: OpenGL v: 4.6 Mesa 22.3.6 renderer: Mesa Intel UHD Graphics 620 (WHL
    GT2)
+ lsb_release -a
No LSB modules are available.
Distributor ID: Debian
Description:    Debian GNU/Linux 12 (bookworm)
Release:        12
Codename:       bookworm
+ xcalib -version
xcalib 0.8
█[debian-x1-7th][~][0]$

Feature request: smart invert where black and white are reversed but colors stay mostly the same.

Hello, first thanks for your work developing and maintaining xcalib.

When I have to use Windows I use NegativeScreen to invert the colors. One feature that I really enjoy is smart invert which they describe as such:

Different inversion modes are provided, including “smart” modes, allowing blacks and whites inversion, while keeping colors (about) the sames.

The feature really shines when browsing the web. It looks closer towards a true universal dark theme than anything else I've seen. For example here is the duckduckgo homepage:

From a linux system if you look at the the same page after applying xcalib -invert -alter the logo appears to be more bluish and has a less native feel to it. This effect, of course, carries over to the rest of the web and whatever UI is in use.

I was wondering how difficult would it be to create either a smart invert function and/or an icc profile for xcalib?

The inversion matrices can be found here.

I'd appreciate hearing any thoughts you have on this subject.

Thanks again!

Update man after including -o flag

This pull request #3 is fantastic and solved an old and, I think, important problem on xcalib

However, it added a new "-o" flag which isn't in the man page. It don't understand much about xcalib, but it would be really great if the man page could be updated including the new flag. Thanks!

Remove the 1..100 contrast limitation to avoid flicker

I am a long time user of xcalib and for years I have been using the hack to first run xcalib -c and then xcalib -a -v | ... and then xcalib -a -co ... to simulate behavior of "percent points independent of the current state" instead of the current "percentage relative to the current state".

Now though I became too old to withstand the flickering due to xcalib -c.

Either of these solutions would do IMHO:

1. Treat percentage as "percent points" instead of the current percentage of the current ICC/LUT state. Percent points would thus be an absolute scale all the time (not relative as they are now).
2. Remove the 1..100 interval limitation and allow negative numbers on input (i.e. change the interval to -100..100).
3. Allow deferred application of the resulting computation (i.e. "transactionally" without flickering) from a chain of operations in one xcalib invocation like e.g. gstreamer does. Imagine writing xcalib -a -c ! -a -co 50 would dry-run consecutively xcalib -a -c and then xcalib -a -co 50 internally but thanks to the "deferred" behavior it would apply to the screen only the resulting numbers effectively avoiding the flicker.

WDYT?

Not able to invert colors | xcalib -a -i stopped working

I used the command xcalib to invert the colors on my screen and it was working fine for a long time till suddenly somehow it stopped working.I am unable to diagnose as to what has caused this.

Now when I run the command it has no effect on the screen and I get the following message :

xcalib -i -a
Warning - Unable to get display calibration

What could have gone wrong? Could this be a bug?

Following is the output of "xcalib -i -a -v" command -

XRandR output:      	HDMI-2
Warning - Unable to get display calibration
Red Brightness: 99.902344   Contrast: -102300.000000  Max: 0.000000  Min: 0.999023
Green Brightness: 99.902344   Contrast: -102300.000000  Max: 0.000000  Min: 0.999023
Blue Brightness: 99.902344   Contrast: -102300.000000  Max: 0.000000  Min: 0.999023
X-LUT size:      	1024

System Specs -

Linux harsh 5.15.37-1-lts #1 SMP Sun, 01 May 2022 15:44:53 +0000 x86_64 GNU/Linux

00:00.0 Host bridge: Intel Corporation Atom/Celeron/Pentium Processor x5-E8000/J3xxx/N3xxx Series SoC Transaction Register (rev 21)
	Subsystem: Intel Corporation Device 2060
	Flags: bus master, fast devsel, latency 0
	Kernel driver in use: iosf_mbi_pci

00:02.0 VGA compatible controller: Intel Corporation Atom/Celeron/Pentium Processor x5-E8000/J3xxx/N3xxx Integrated Graphics Controller (rev 21) (prog-if 00 [VGA controller])
	DeviceName:  CPU
	Subsystem: Intel Corporation Device 2060
	Flags: bus master, fast devsel, latency 0, IRQ 123
	Memory at 80000000 (64-bit, non-prefetchable) [size=16M]
	Memory at 88000000 (64-bit, prefetchable) [size=128M]
	I/O ports at f000 [size=64]
	Expansion ROM at 000c0000 [virtual] [disabled] [size=128K]
	Capabilities: <access denied>
	Kernel driver in use: i915
	Kernel modules: i915

This works only temporary on my X230

Hello,

When I run this command xcalib -i -a screen gets inverted for second and then it gets fixed.

I have no idea how to debug this since I have no ideas how it works.

Any suggestions?

---

Edit:

This is output I get:

Warning - Unable to get display calibration

---

Edit 2:

I do not see anything under Xorg log related to this.

---

Edit 3:

Laptop: Thinkpad X230

Graphics: HD 4000

OS: Arch

WM: i3wm

Composer: Compton

---

Edit 4:

Just to note that I do not have any problems on T430 with same CPU and almost the same software setup.

Pure RGB Black Not Inverting

Vision-impaired (blind) user here trying to get inversion to work correctly. "xcalib -i -a" will invert everything on the screen except for anything that is black, which stays black instead of turning white. Any help resolving this would be greatly appreciated, I need inversion to see my computer!
System specs:

• xcalib v0.11.0
• AMD Ryzen 9 7900X-3D using on-chip graphics for display
• Linux Mint 21.3 Cinnamon
• Kernel 6.5.0-25-generic

Due to changed conditions (2FA) house move

My favorite is gitlab.com. https://gitlab.com/openicc

BadRRCrtc (invalid Crtc parameter)

OS - ubuntu 24.04

I installed new version of xcalib this way:

sudo apt-get install libx11-dev libxrandr-dev  libxss-dev libxxf86vm-dev libxkbfile-dev libxv-dev 
git clone https://github.com/OpenICC/xcalib.git
cd xcalib
cmake CMakeLists.txt
sudo make install

and this is what I have:

pavel@notebook:~$ xcalib --version
xcalib v0.11.0 - Tiny monitor calibration loader for Xorg and Windows.


Author: 	Stefan Dohla <stefan AT doehla DOT de>

For more information read the man page:
	man xcalib

pavel@notebook:~$ xcalib -co 70 -a
X Error of failed request:  BadRRCrtc (invalid Crtc parameter)
  Major opcode of failed request:  139 (RANDR)
  Minor opcode of failed request:  24 (RRSetCrtcGamma)
  Crtc id in failed request: 0x0
  Serial number of failed request:  13
  Current serial number in output stream:  15

Could anyone help me?

Unable calibrate colors in new versions of Windows 10

I would know if, is possible use the command

xcalib -i -a

in the new versions of Windows 10.

My question is because when i try call this command, i recept this response

unable to calibrate screen