docs/X_Color_Management.txt

   1
   2     X Color Management specification 0.4
   3    ====================
   4
   5 DRAFT 1
   6
   7    Revision History
   8   ------------------
   9 Revision 0.1            2008-07-21  Tomas Carnecky
  10                                       initial incomplete spec for
  11                                       Color Management near X
  12 Draft for Revision 0.2  2010-05-16  Kai-Uwe Behrmann
  13                                       clearify XcolorRegion, add references,
  14                                       history, date and headers,
  15                                       remove XRandR, _ICC_COLOR_MANAGEMENT and
  16                                       _ICC_COLOR_PROFILES from this version,
  17                                       add _ICC_COLOR_REGIONS and
  18                                       _ICC_COLOR_DESKTOP
  19 Draft 2  Revision 0.2   2010-08-14  Kai-Uwe Behrmann
  20                                       add _ICC_DEVICE_PROFILE(_xxx)
  21
  22 Draft 1  Revision 0.3   2011-09-11  Kai-Uwe Behrmann
  23                                       rename _NET prefix to _ICC
  24
  25 Draft 2  Revision 0.3   2011-10-30  Kai-Uwe Behrmann
  26                                       describe _ICC_COLOR_DISPLAY_ADVANCED,
  27                                       readd _ICC_COLOR_PROFILES
  28                                       add color server implementation note
  29
  30 Draft 1  Revision 0.4   2012-02-17  Kai-Uwe Behrmann
  31                                       add _ICC_COLOR_OUTPUTS
  32 Draft 2  Revision 0.4   2012-11-11  Kai-Uwe Behrmann
  33                                       clearify about opt out
  34 Draft 3  Revision 0.4   2012-12-20  Kai-Uwe Behrmann
  35                                       specify ICM _ICC_COLOR_DESKTOP capability
  36
  37    Introduction
  38   --------------
  39
  40 The X Color Management specification defines a protocol, which can be used by
  41 X11 clients to offload color correction and transformation into the
  42 compositing manager. The basic idea is to communicate client side informations
  43 to the X11 server. The regions or outputs can of this version have no ICC
  44 profile attached, which means a color server, typical in a compositing manager,
  45 shall not color manage these regions or windows. These regions or windows then
  46 are in the responsibility of the application. This allowes for calibration and
  47 early colour binding.
  48 Support for client side colour space ICC profiles is possible. This allowes
  49 applications to do late colour binding, which is very convenient to correct
  50 complex vector graphics or 3D scenes to multiple outputs, without the need
  51 to understand window transformations.
  52
  53
  54    Color Profile
  55   ---------------
  56
  57 A single ICC color profile is described by the following C structure.
  58
  59 typedef struct {
  60         uint8_t md5[16];  /* ICC MD5 hash of the associated ICC profile */
  61         uint32_t size;    /* number of bytes following, in network byte order */
  62 } XcolorProfile;
  63
  64 It defines a single ICC profile that can be uploaded to the compositing manager
  65 and later referenced in color regions. The actual profile data follows directly
  66 after the structure.
  67
  68
  69    Color Region
  70   --------------
  71
  72 A color region is described by the following C structure:
  73
  74 typedef struct {
  75         uint32_t region;  /* window centric XserverRegion               */
  76         uint8_t md5[16];  /* ICC MD5 hash of the associated ICC profile */
  77 } XcolorRegion;
  78
  79 It defines a region and the attached color profile. Color regions are attached
  80 to windows and used by the compositing manager to apply the proper color
  81 transformation. Windows can have an unlimited amount of regions attached, though
  82 only the first 2 * 2^32 can be referenced.
  83 As of this spec the md5 shall be set to zero to signal the region is already
  84 color managed by the application. That capability is called opt out.
  85
  86
  87    Color Output
  88   --------------
  89
  90 A windows profile reference is described by the following C structure:
  91
  92 typedef struct {
  93         unsigned char name[16]; /* output name                          */
  94         uint8_t md5[16];  /* ICC MD5 hash of the associated ICC profile */
  95         uint8_t dummy[16];/* reserved                                   */
  96 } XcolorOutput;
  97
  98 It defines a window profile describing the windows content colour space.
  99 A normal window profile is referenced by each window and is used by the
 100 compositing manager to apply per window colour transformations.
 101
 102 The name field can be zero if the referenced profile is a normal editing space
 103 profile.
 104
 105 It is allowed to reference a device link profile, which describes a
 106 colour transform of window content to one specified output. Then the name field
 107 must be filled.
 108
 109 Output names are normally deteced by the XRandR Xorg extension and literally be
 110 used for the name field, e.g. "DP-1" In case the XRandR extension detects only
 111 one output, but the Xinerama extension detects multiple outputs, then the
 112 Xinerama screens can be named in plain Xinerama order. Xinerama screen names
 113 are ascii encoded numbers like "0".
 114
 115 The md5 shall be set to zero to signal the window is already color managed
 116 by the application. That capability is called opt out.
 117
 118
 119    Atoms
 120   -------
 121
 122  _ICC_COLOR_PROFILES:
 123
 124 Is used to upload color profiles to the compositing manager. Clients attach a
 125 a list of one or more XColorProfile to the root window. Compositing manager then
 126 fetches the list and saves the profiles in an internal database and deletes the
 127 property.
 128 The type is XA_CARDINAL. The size value is stored in network byte order. The
 129 data represents a list of XcolorProfile. The memory layout is like:
 130 first profile
 131    16 byte      md5
 132     4 byte      size
 133  size bytes     profile data
 134 second profile
 135    16 byte      md5
 136     4 byte      size
 137  size bytes     profile data
 138 ...
 139
 140
 141  _ICC_COLOR_REGIONS:
 142
 143 The atom is attached to windows and lists the XcolorRegion's defined for that
 144 specific window. The application is responsible to update the contained
 145 informations, e.g. on region resize or move inside the window.
 146
 147 The type is XA_CARDINAL and values are stored in network byte order.
 148 _ICC_COLOR_OUTPUTS must not be intermixed with _ICC_COLOR_REGIONS on the same
 149 window. Intermixing shall cause the colour server to fall back to sRGB.
 150
 151
 152  _ICC_COLOR_OUTPUTS:
 153
 154 The atom is attached to windows and lists the XcolorOutput's defined for that
 155 specific window. The application is responsible to update that atom in case
 156 device link profiles are utilised and outputs change.
 157
 158 The type is XA_CARDINAL and values are stored in network byte order.
 159 _ICC_COLOR_OUTPUTS must not be intermixed with _ICC_COLOR_REGIONS on the same
 160 window. Intermixing shall cause the colour server to fall back to sRGB.
 161
 162
 163  _ICC_COLOR_TARGET:
 164
 165 Is attached to windows and specifies on which output the window should
 166 look correctly. The type is XA_STRING. Deprecated. Please look at the
 167 _ICC_COLOR_OUTPUTS atom.
 168
 169
 170  _ICC_COLOR_DISPLAY_ADVANCED:
 171
 172 The atom is optionaly attached to the root window. A value of "1" signals the
 173 colour server to use advanced CMS options like proofing. The type is XA_STRING.
 174
 175
 176  _ICC_COLOR_DESKTOP:
 177
 178 The atom is attached on the root window to inform about the color server.
 179 The content is of type XA_STRING and has four sections separated by a
 180 empty space char ' '.
 181 The _ICC_COLOR_DESKTOP atom is a string with following usages:
 182 - uniquely identify the colour server
 183 - tell the name of the colour server
 184 - tell the colour server is alive
 185 - list the colour server capabilities and spec compliance
 186 All sections are separated by one space char ' ' for easy parsing.
 187
 188 The first section contains the process id (pid_t) of the color server process,
 189 which has set the atom.
 190 The second section contains time since epoch GMT as returned by time(NULL).
 191 The thired section contains the bar '|' separated and surrounded
 192 capabilities:
 193   - ICP  _ICC_COLOR_PROFILES XcolorRegion::md5 is handled
 194   - ICT  _ICC_COLOR_TARGET - deprecated
 195   - ICM  _ICC_COLOR_MANAGEMENT color server is converting
 196   - ICR  _ICC_COLOR_REGIONS XcolorRegion is handled
 197   - ICO  _ICC_COLOR_OUTPUTS XcolorOutput is handled
 198   - ICA  _ICC_COLOR_DISPLAY_ADVANCED
 199   - V0.4 indicates version compliance to the _ICC_Profile in X spec
 200 The fourth section contains the servers name identifier.
 201
 202 As of this specification the third section must contain the supported
 203 _ICC_PROFILE in X version. The third section must contain at least the
 204 ICO capability specifier to show baseline support. All other capability
 205 specifiers are optional to the third section.
 206
 207 A example of a valid atom might look like:
 208 _ICC_COLOR_DESKTOP(STRING) = "4518 1274001512 |ICA|ICR|ICO|ICP|ICM|V0.4| compicc"
 209
 210
 211  _ICC_DEVICE_PROFILE(_xxx):
 212
 213 The atom will hold a native ICC profile with the exposed device
 214 characteristics at the compositing window manager level.
 215 The colour server shall if no _ICC_DEVICE_PROFILE(_xxx) is set, copy the
 216 _ICC_PROFILE(_xxx) profiles to each equivalent _ICC_DEVICE_PROFILE(_xxx) atom.
 217 The _ICC_PROFILE(_xxx) profiles shall be replaced by a sRGB ICC profile.
 218 The counting in the atoms (_xxx) name section follows the rules outlined in
 219 the ICC Profile in X recommendation. After finishing the session the the old
 220 state has to be recovered by copying any _ICC_DEVICE_PROFILE(_xxx) atoms
 221 content into the appropriate _ICC_PROFILE(_xxx) atoms and removing all
 222 _ICC_DEVICE_PROFILE(_xxx) atoms.
 223 The colour server must be aware about change property events indicating that
 224 a _ICC_PROFILE(_xxx) atom has changed by a external application and needs to
 225 move that profile to the appropriate _ICC_DEVICE_PROFILE(_xxx) atom and set
 226 the _ICC_PROFILE(_xxx) atom to sRGB as well.
 227 The modification of the _ICC_DEVICE_PROFILE(_xxx) atoms by external applications
 228 is undefined.
 229
 230
 231    Baseline Implementation
 232   -------------------------
 233
 234 _ICC_COLOR_OUTPUTS support must be implemented. That allowes applications and
 235 toolkits to rely on a common level of support from different colour server
 236 implementations.
 237
 238
 239    Discussion
 240   ------------
 241
 242 Elder desktop applications might not be aware of the capabilities exposed
 243 through a implementation of this recommendation. Thus a way is needed to enshure
 244 backward compatibility. The _ICC_DEVICE_PROFILE(_xxx) atom provides a means to
 245 expose capable clients the desired information about the monitor characteristics
 246 at the discussed level. The _ICC_PROFILE(_xxx) atom is maintained to enshure the
 247 desired backward compatibility.
 248
 249  Implementation Notes:
 250
 251 Color servers see in a X11 environment only asynchronous events. Therefore they
 252 shall control the setup of _ICC_PROFILE(_xxx) atoms. That way they will
 253 be able to handle XRandR output configuration and desktop geometry change events
 254 in the correct order.
 255
 256 _ICC_COLOR_OUTPUTS provides a very simple mechanism for compositors to do
 257 server side colour correction of otherwise non colour managed windows.
 258 Supporting _ICC_COLOR_PROFILES capabilities helps applications a lot to obtain
 259 proper multi monitor colour correction as they can render into a single
 260 intermediate colour space, which is then finally converted to each output by
 261 the colour server. Therefor _ICC_COLOR_PROFILES support is highly encouraged.
 262
 263
 264    References
 265   ------------
 266
 267 1. X window system (hhtp://www.x.org)
 268 2. International Color Consortium (http://www.color.org)
 269 3. _ICC_Profile in X (http://www.freedesktop.org/wiki/Specifications/icc_profiles_in_x_spec)
 270 4. Xcolor reference implementation (git clone git://www.oyranos.org/git/xcolor)
 271 5. CompIcc colour server for compiz (http://sourceforge.net/apps/mediawiki/compicc/index.php?title=Main_Page)
 272 6. xcmsevents monitor tool (git clone git://www.oyranos.org/git/oyranos)
 273 7. Key words for use in RFCs to Indicate Requirement Levels (http://www.ietf.org/rfc/rfc2119.txt)
 274
 275
 276 2008 (c) Tomas Carnecky, 2010-2012 (c) Kai-Uwe Behrmann
 277