1 .TH COLOR 7
2 .SH NAME
3 color \- representation of pixels and colors
4 .SH DESCRIPTION
5 To address problems of consistency and portability among applications,
6 Plan 9 uses a fixed color map, called
7 .BR rgbv ,
8 on 8-bit-per-pixel displays.
9 Although this avoids problems caused by multiplexing color maps between
10 applications, it requires that the color map chosen be suitable for most purposes
11 and usable for all.
12 Other systems that use fixed color maps tend to sample the color cube
13 uniformly, which has advantages\(emmapping from a (red, green, blue) triple
14 to the color map and back again is easy\(embut ignores an important property
15 of the human visual system: eyes are
16 much more sensitive to small changes in intensity than
17 to changes in hue.
18 Sampling the color cube uniformly gives a color map with many different
19 hues, but only a few shades of each.
20 Continuous tone images converted into such maps demonstrate conspicuous
21 artifacts.
22 .PP
23 Rather than dice the color cube into subregions of
24 size 6\(mu6\(mu6 (as in Netscape Navigator) or 8\(mu8\(mu4
25 (as in previous releases of Plan 9), picking 1 color in each,
26 the
27 .B rgbv
28 color map uses a 4\(mu4\(mu4 subdivision, with
29 4 shades in each subcube.
30 The idea is to reduce the color resolution by dicing
31 the color cube into fewer cells, and to use the extra space to increase the intensity
32 resolution.
33 This results in 16 grey shades (4 grey subcubes with
34 4 samples in each), 13 shades of each primary and secondary color (3 subcubes
35 with 4 samples plus black) and a reasonable selection of colors covering the
36 rest of the color cube.
37 The advantage is better representation of
38 continuous tones.
39 .PP
40 The following function computes the 256 3-byte entries in the color map:
41 .IP
42 .EX
43 .ta 6n +6n +6n +6n
44 void
45 setmaprgbv(uchar cmap[256][3])
46 {
47     uchar *c;
48     int r, g, b, v;
49     int num, den;
50     int i, j;
51 
52     for(r=0,i=0; r!=4; r++)
53       for(v=0; v!=4; v++,i+=16)
54         for(g=0,j=v-r; g!=4; g++)
55           for(b=0; b!=4; b++,j++){
56             c = cmap[i+(j&15)];
57             den = r;
58             if(g > den)
59                 den = g;
60             if(b > den)
61                 den = b;
62             if(den == 0) /* would divide check; pick grey shades */
63                 c[0] = c[1] = c[2] = 17*v;
64             else{
65                 num = 17*(4*den+v);
66                 c[0] = r*num/den;
67                 c[1] = g*num/den;
68                 c[2] = b*num/den;
69             }
70           }
71 }
72 .EE
73 .PP
74 There are 4 nested loops to pick the (red,green,blue) coordinates of the subcube,
75 and the value (intensity) within the subcube, indexed by
76 .BR r ,
77 .BR g ,
78 .BR b ,
79 and
80 .BR v ,
81 whence
82 the name
83 .IR rgbv .
84 The peculiar order in which the color map is indexed is designed to distribute the
85 grey shades uniformly through the map\(emthe
86 .IR i 'th
87 grey shade,
88 .RI 0<= i <=15
89 has index
90 .IR i ×17,
91 with black going to 0 and white to 255.
92 Therefore, when a call to
93 .B draw
94 converts a 1, 2 or 4 bit-per-pixel picture to 8 bits per pixel (which it does
95 by replicating the pixels' bits), the converted pixel values are the appropriate
96 grey shades.
97 .PP
98 The
99 .B rgbv
100 map is not gamma-corrected, for two reasons.  First, photographic
101 film and television are both normally under-corrected, the former by an
102 accident of physics and the latter by NTSC's design.
103 Second, we require extra color resolution at low intensities because of the
104 non-linear response and adaptation of the human visual system.
105 Properly
106 gamma-corrected displays with adequate low-intensity resolution pack the
107 high-intensity parts of the color cube with colors whose differences are
108 almost imperceptible.
109 Either reason suggests concentrating
110 the available intensities at the low end of the range.
111 .PP
112 On `true-color' displays with separate values for the red, green, and blue
113 components of a pixel, the values are chosen so 0 represents no intensity (black) and the
114 maximum value (255 for an 8-bit-per-color display) represents full intensity (e.g., full red).
115 Common display depths are 24 bits per pixel, with 8 bits per color in order
116 red, green, blue, and 16 bits per pixel, with 5 bits of red, 6 bits of green, and 5 bits of blue.
117 .PP
118 Colors may also be created with an opacity factor called
119 .BR alpha ,
120 which is scaled so 0 represents fully transparent and 255 represents opaque color.
121 The alpha is
122 .I premultiplied
123 into the other channels, as described in the paper by Porter and Duff cited in
124 .MR draw (3) .
125 The function
126 .B setalpha
127 (see
128 .MR allocimage (3) )
129 aids the initialization of color values with non-trivial alpha.
130 .PP
131 The packing of pixels into bytes and words is odd.
132 For compatibility with VGA frame buffers, the bits within a
133 pixel byte are in big-endian order (leftmost pixel is most
134 significant bits in byte), while bytes within a pixel are packed in little-endian
135 order.  Pixels are stored in contiguous bytes.  This results
136 in unintuitive pixel formats. For example, for the RGB24 format,
137 the byte ordering is blue, green, red.
138 .PP
139 To maintain a constant external representation,
140 the
141 .MR draw (3)
142 interface
143 as well as the 
144 various graphics libraries represent colors 
145 by 32-bit numbers, as described in 
146 .MR color (3) .
147 .SH "SEE ALSO"
148 .MR color (3) ,
149 .MR graphics (3) ,
150 .MR draw (3)