1 058b0118 2005-01-03 devnull .TH IMAGE 7
3 058b0118 2005-01-03 devnull image \- external format for images
4 058b0118 2005-01-03 devnull .SH SYNOPSIS
5 058b0118 2005-01-03 devnull .B #include <draw.h>
6 058b0118 2005-01-03 devnull .SH DESCRIPTION
7 058b0118 2005-01-03 devnull Images are described in
8 d32deab1 2020-08-16 rsc .MR graphics (3) ,
9 058b0118 2005-01-03 devnull and the definition of pixel values is in
10 d32deab1 2020-08-16 rsc .MR color (7) .
11 058b0118 2005-01-03 devnull Fonts and images are stored in external files
12 058b0118 2005-01-03 devnull in machine-independent formats.
14 058b0118 2005-01-03 devnull Image files are read and written using
15 058b0118 2005-01-03 devnull .B readimage
17 058b0118 2005-01-03 devnull .B writeimage
19 058b0118 2005-01-03 devnull .IR allocimage (3)), or
20 058b0118 2005-01-03 devnull .B readmemimage
22 058b0118 2005-01-03 devnull .B writememimage
24 d32deab1 2020-08-16 rsc .MR memdraw (3) ).
25 058b0118 2005-01-03 devnull An uncompressed image file starts with 5
27 058b0118 2005-01-03 devnull .BR chan ,
28 058b0118 2005-01-03 devnull .BR r.min.x ,
29 058b0118 2005-01-03 devnull .BR r.min.y ,
30 058b0118 2005-01-03 devnull .BR r.max.x ,
32 058b0118 2005-01-03 devnull .BR r.max.y .
33 058b0118 2005-01-03 devnull Each is right-justified and blank padded in 11 characters, followed by a blank.
36 058b0118 2005-01-03 devnull value is a textual string describing the pixel format
38 058b0118 2005-01-03 devnull .B strtochan
40 d32deab1 2020-08-16 rsc .MR graphics (3)
41 058b0118 2005-01-03 devnull and the discussion of channel descriptors below),
42 058b0118 2005-01-03 devnull and the rectangle coordinates are decimal strings.
43 058b0118 2005-01-03 devnull The rest of the file contains the
44 058b0118 2005-01-03 devnull .B r.max.y-r.min.y
45 058b0118 2005-01-03 devnull rows of pixel data.
48 058b0118 2005-01-03 devnull consists of the byte containing pixel
49 058b0118 2005-01-03 devnull .B r.min.x
50 058b0118 2005-01-03 devnull and all the bytes up to and including the byte containing pixel
51 058b0118 2005-01-03 devnull .BR r.max.x -1.
52 977b25a7 2020-08-14 rsc For images with depth
54 058b0118 2005-01-03 devnull less than eight, a pixel with x-coordinate =
56 058b0118 2005-01-03 devnull will appear as
58 058b0118 2005-01-03 devnull contiguous bits in a byte, with the pixel's high order bit
59 058b0118 2005-01-03 devnull starting at the byte's bit number
60 058b0118 2005-01-03 devnull .if t \fIw\fP\(mu(\fIx\fP mod (8/\fIw\fP)),
61 058b0118 2005-01-03 devnull .if n w*(x mod (8/w)),
62 058b0118 2005-01-03 devnull where bits within a byte are numbered 0 to 7 from the
63 058b0118 2005-01-03 devnull high order to the low order bit.
64 058b0118 2005-01-03 devnull Rows contain integral number of bytes, so there may be some unused
65 058b0118 2005-01-03 devnull pixels at either end of a row.
68 058b0118 2005-01-03 devnull is greater than 8, the definition of images requires that it will a multiple of 8, so
69 058b0118 2005-01-03 devnull pixel values take up an integral number of bytes.
72 058b0118 2005-01-03 devnull .B loadimage
74 058b0118 2005-01-03 devnull .B unloadimage
75 058b0118 2005-01-03 devnull functions described in
76 d32deab1 2020-08-16 rsc .MR allocimage (3)
77 058b0118 2005-01-03 devnull also deal with rows in this format, stored in user memory.
79 058b0118 2005-01-03 devnull The channel format string is a sequence of two-character channel descriptions,
80 977b25a7 2020-08-14 rsc each comprising a letter
84 058b0118 2005-01-03 devnull for green,
86 058b0118 2005-01-03 devnull for blue,
88 058b0118 2005-01-03 devnull for alpha,
90 058b0118 2005-01-03 devnull for color-mapped,
92 058b0118 2005-01-03 devnull for greyscale,
95 058b0118 2005-01-03 devnull for ``don't care'')
96 058b0118 2005-01-03 devnull followed by a number of bits per pixel.
97 058b0118 2005-01-03 devnull The sum of the channel bits per pixel is the
98 977b25a7 2020-08-14 rsc depth of the image, which must be either
99 058b0118 2005-01-03 devnull a divisor or a multiple of eight.
100 058b0118 2005-01-03 devnull It is an error to have more than
101 977b25a7 2020-08-14 rsc one of any channel but
103 058b0118 2005-01-03 devnull An image must have either a greyscale channel; a color mapped channel;
104 058b0118 2005-01-03 devnull or red, green, and blue channels.
105 058b0118 2005-01-03 devnull If the alpha channel is present, it must be at least as deep as any other channel.
107 058b0118 2005-01-03 devnull The channel string defines the format of the pixels in the file,
108 058b0118 2005-01-03 devnull and should not be confused with ordering of bytes in the file.
109 058b0118 2005-01-03 devnull In particular
110 058b0118 2005-01-03 devnull .B 'r8g8b8'
111 058b0118 2005-01-03 devnull pixels have byte ordering blue, green, and red within the file.
113 d32deab1 2020-08-16 rsc .MR color (7)
114 058b0118 2005-01-03 devnull for more details of the pixel format.
116 058b0118 2005-01-03 devnull A venerable yet deprecated format replaces the channel string
117 058b0118 2005-01-03 devnull with a decimal
118 058b0118 2005-01-03 devnull .IR ldepth ,
119 977b25a7 2020-08-14 rsc which is the base two logarithm of the number
120 058b0118 2005-01-03 devnull of bits per pixel in the image.
121 058b0118 2005-01-03 devnull In this case,
122 058b0118 2005-01-03 devnull .IR ldepth s
123 058b0118 2005-01-03 devnull 0, 1, 2, and 3
124 058b0118 2005-01-03 devnull correspond to channel descriptors
125 058b0118 2005-01-03 devnull .BR k1 ,
126 058b0118 2005-01-03 devnull .BR k2 ,
127 058b0118 2005-01-03 devnull .BR k4 ,
129 058b0118 2005-01-03 devnull .BR m8 ,
130 058b0118 2005-01-03 devnull respectively.
132 058b0118 2005-01-03 devnull Compressed image files start with a line of text containing the word
133 058b0118 2005-01-03 devnull .BR compressed ,
134 058b0118 2005-01-03 devnull followed by a header as described above, followed by the image data.
135 058b0118 2005-01-03 devnull The data, when uncompressed, is laid out in the usual form.
137 058b0118 2005-01-03 devnull The data is represented by a string of compression blocks, each encoding
138 058b0118 2005-01-03 devnull a number of rows of the image's pixel data. Compression blocks
139 058b0118 2005-01-03 devnull are at most 6024 bytes long, so that they fit comfortably in a
140 058b0118 2005-01-03 devnull single 9P message. Since a compression block must encode a
141 058b0118 2005-01-03 devnull whole number of rows, there is a limit (about 5825 bytes) to the width of images
142 058b0118 2005-01-03 devnull that may be encoded. Most wide images are in subfonts,
143 058b0118 2005-01-03 devnull which, at 1 bit per pixel (the usual case for fonts), can be 46600 pixels wide.
145 058b0118 2005-01-03 devnull A compression block begins with two decimal strings of twelve bytes each.
146 058b0118 2005-01-03 devnull The first number is one more than the
148 058b0118 2005-01-03 devnull coordinate of the last row in the block. The second is the number
149 058b0118 2005-01-03 devnull of bytes of compressed data in the block, not including the two decimal strings.
150 058b0118 2005-01-03 devnull This number must not be larger than 6000.
152 058b0118 2005-01-03 devnull Pixels are encoded using a version of Lempel & Ziv's sliding window scheme LZ77,
153 058b0118 2005-01-03 devnull best described in J A Storer & T G Szymanski
154 058b0118 2005-01-03 devnull `Data Compression via Textual Substitution',
155 058b0118 2005-01-03 devnull JACM 29#4, pp. 928-951.
157 058b0118 2005-01-03 devnull The compression block is a string of variable-length
158 058b0118 2005-01-03 devnull code words encoding substrings of the pixel data. A code word either gives the
159 058b0118 2005-01-03 devnull substring directly or indicates that it is a copy of data occurring
160 058b0118 2005-01-03 devnull previously in the pixel stream.
162 058b0118 2005-01-03 devnull In a code word whose first byte has the high-order bit set, the rest of the
163 058b0118 2005-01-03 devnull byte indicates the length of a substring encoded directly.
164 058b0118 2005-01-03 devnull Values from 0 to 127 encode lengths from 1 to 128 bytes.
165 058b0118 2005-01-03 devnull Subsequent bytes are the literal pixel data.
167 058b0118 2005-01-03 devnull If the high-order bit is zero, the next 5 bits encode
168 058b0118 2005-01-03 devnull the length of a substring copied from previous pixels. Values from 0 to 31
169 058b0118 2005-01-03 devnull encode lengths from 3 to 34 bytes. The bottom two bits of the first byte and
170 058b0118 2005-01-03 devnull the 8 bits of the next byte encode an offset backward from the current
171 058b0118 2005-01-03 devnull position in the pixel data at which the copy is to be found. Values from
172 058b0118 2005-01-03 devnull 0 to 1023 encode offsets from 1 to 1024. The encoding may be `prescient',
173 058b0118 2005-01-03 devnull with the length larger than the offset, which works just fine: the new data
174 058b0118 2005-01-03 devnull is identical to the data at the given offset, even though the two strings overlap.
176 058b0118 2005-01-03 devnull Some small images, in particular 48\(mu48 face files
177 058b0118 2005-01-03 devnull as used by
178 058b0118 2005-01-03 devnull .I seemail
179 058b0118 2005-01-03 devnull (see Plan 9's
180 977b25a7 2020-08-14 rsc .IR faces (1)
182 d32deab1 2020-08-16 rsc .MR face (7) )
183 058b0118 2005-01-03 devnull and 16\(mu16
184 058b0118 2005-01-03 devnull cursors, can be stored textually, suitable for inclusion in C source.
185 058b0118 2005-01-03 devnull Each line of text represents one scan line as a
186 058b0118 2005-01-03 devnull comma-separated sequence of hexadecimal
187 058b0118 2005-01-03 devnull bytes, shorts, or words in C format.
188 058b0118 2005-01-03 devnull For cursors, each line defines a pair of bytes.
189 058b0118 2005-01-03 devnull (It takes two images to define a cursor; each must be stored separately
190 058b0118 2005-01-03 devnull to be processed by programs such as
191 d32deab1 2020-08-16 rsc .MR tweak (1) .)
192 058b0118 2005-01-03 devnull Face files of one bit per pixel are stored as a sequence of shorts,
193 058b0118 2005-01-03 devnull those of larger pixel sizes as a sequence of longs.
194 058b0118 2005-01-03 devnull Software that reads these files must deduce the image size from
195 058b0118 2005-01-03 devnull the input; there is no header.
196 058b0118 2005-01-03 devnull These formats reflect history rather than design.
197 058b0118 2005-01-03 devnull .SH "SEE ALSO"
198 d32deab1 2020-08-16 rsc .MR jpg (1) ,
199 d32deab1 2020-08-16 rsc .MR tweak (1) ,
200 d32deab1 2020-08-16 rsc .MR graphics (3) ,
201 d32deab1 2020-08-16 rsc .MR draw (3) ,
202 d32deab1 2020-08-16 rsc .MR allocimage (3) ,
203 d32deab1 2020-08-16 rsc .MR color (7) ,
204 d32deab1 2020-08-16 rsc .MR face (7) ,
205 d32deab1 2020-08-16 rsc .MR font (7)
