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