| <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> |
