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