6.1 Color Structures

typedef struct {
	unsigned long pixel;			/* pixel value */
	unsigned short red, green, blue;	/* rgb values */
	char flags;				/* DoRed, DoGreen, DoBlue */
	char pad;
} XColor;

The red, green, and blue values are always in the range 0 to 65535 inclusive, independent of the number of bits actually used in the display hardware. The server scales these values down to the range used by the hardware. Black is represented by (0,0,0), and white is represented by (65535,65535,65535). In some functions, the flags member controls which of the red, green, and blue members is used and can be the inclusive OR of zero or more of DoRed , DoGreen , and DoBlue .

Functions that operate on all color space values use an XcmsColor structure. This structure contains a union of substructures, each supporting color specification encoding for a particular color space. Like the XColor structure, the XcmsColor structure contains pixel and color specification information (the spec member in the XcmsColor structure).

typedef unsigned long XcmsColorFormat;		/* Color Specification Format */

typedef struct {
	union {
		XcmsRGB RGB;
		XcmsRGBi RGBi;
		XcmsCIEXYZ CIEXYZ;
		XcmsCIEuvY CIEuvY;
		XcmsCIExyY CIExyY;
		XcmsCIELab CIELab;
		XcmsCIELuv CIELuv;
		XcmsTekHVC TekHVC;
		XcmsPad Pad;
	} spec;
	unsigned long pixel;
	XcmsColorFormat format;
} XcmsColor;					/* Xcms Color Structure */

Because the color specification can be encoded for the various color spaces, encoding for the spec member is identified by the format member, which is of type XcmsColorFormat. The following macros define standard formats.

#define XcmsUndefinedFormat	0x00000000
#define XcmsCIEXYZFormat	0x00000001	/* CIE XYZ */
#define XcmsCIEuvYFormat	0x00000002	/* CIE u'v'Y */
#define XcmsCIExyYFormat	0x00000003	/* CIE xyY */
#define XcmsCIELabFormat	0x00000004	/* CIE L*a*b* */
#define XcmsCIELuvFormat	0x00000005	/* CIE L*u*v* */
#define XcmsTekHVCFormat	0x00000006	/* TekHVC */
#define XcmsRGBFormat		0x80000000	/* RGB Device */
#define XcmsRGBiFormat		0x80000001	/* RGB Intensity */

Formats for device-independent color spaces are distinguishable from those for device-dependent spaces by the 32nd bit. If this bit is set, it indicates that the color specification is in a device-dependent form; otherwise, it is in a device-independent form. If the 31st bit is set, this indicates that the color space has been added to Xlib at run time (see "Creating Additional Color Spaces"). The format value for a color space added at run time may be different each time the program is executed. If references to such a color space must be made outside the client (for example, storing a color specification in a file), then reference should be made by color space string prefix (see XcmsFormatOfPrefix() and XcmsPrefixOfFormat()).

Data types that describe the color specification encoding for the various color spaces are defined as follows:

typedef double XcmsFloat;



typedef struct {
	unsigned short red;	/* 0x0000 to 0xffff */
	unsigned short green;	/* 0x0000 to 0xffff */
	unsigned short blue;	/* 0x0000 to 0xffff */
} XcmsRGB;			/* RGB Device */



typedef struct {
	XcmsFloat red;		/* 0.0 to 1.0 */
	XcmsFloat green;	/* 0.0 to 1.0 */
	XcmsFloat blue;		/* 0.0 to 1.0 */
} XcmsRGBi;			/* RGB Intensity */



typedef struct {
	XcmsFloat X;
	XcmsFloat Y;		/* 0.0 to 1.0 */
	XcmsFloat Z;
} XcmsCIEXYZ;			/* CIE XYZ */



typedef struct {
	XcmsFloat u_prime;	/* 0.0 to ~0.6 */
	XcmsFloat v_prime;	/* 0.0 to ~0.6 */
	XcmsFloat Y; 		/* 0.0 to 1.0 */
} XcmsCIEuvY;			/* CIE u'v'Y */



typedef struct {
	XcmsFloat x; 		/* 0.0 to ~.75 */
	XcmsFloat y; 		/* 0.0 to ~.85 */
	XcmsFloat Y; 		/* 0.0 to 1.0 */
} XcmsCIExyY;			/* CIE xyY */



typedef struct {
	XcmsFloat L_star; 	/* 0.0 to 100.0 */
	XcmsFloat a_star;
	XcmsFloat b_star;
} XcmsCIELab;			/* CIE L*a*b* */



typedef struct {
	XcmsFloat L_star; 	/* 0.0 to 100.0 */
	XcmsFloat u_star;
	XcmsFloat v_star;
} XcmsCIELuv;			/* CIE L*u*v* */



typedef struct {
	XcmsFloat H; 		/* 0.0 to 360.0 */
	XcmsFloat V; 		/* 0.0 to 100.0 */
	XcmsFloat C; 		/* 0.0 to 100.0 */
} XcmsTekHVC;			/* TekHVC */



typedef struct {
	XcmsFloat pad0;
	XcmsFloat pad1;
	XcmsFloat pad2;
	XcmsFloat pad3;
} XcmsPad;			/* four doubles */

The device-dependent formats provided allow color specification in:

• RGB Intensity (XcmsRGBi)

  Red, green, and blue linear intensity values, floating-point values from 0.0 to 1.0, where 1.0 indicates full intensity, 0.5 half intensity, and so on.

• RGB Device (XcmsRGB)

  Red, green, and blue values appropriate for the specified output device. XcmsRGB values are of type unsigned short, scaled from 0 to 65535 inclusive, and are interchangeable with the red, green, and blue values in an XColor structure.

It is important to note that RGB Intensity values are not gamma corrected values. In contrast, RGB Device values generated as a result of converting color specifications are always gamma corrected, and RGB Device values acquired as a result of querying a colormap or passed in by the client are assumed by Xlib to be gamma corrected. The term RGB value in this manual always refers to an RGB Device value.

Next: Color Strings