mirror of
https://github.com/9fans/plan9port.git
synced 2025-01-30 11:54:57 +00:00
175 lines
10 KiB
HTML
175 lines
10 KiB
HTML
<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>
|