diff options
Diffstat (limited to 'man/man7/image.html')
| -rw-r--r-- | man/man7/image.html | 175 |
1 files changed, 175 insertions, 0 deletions
diff --git a/man/man7/image.html b/man/man7/image.html new file mode 100644 index 00000000..f81c023b --- /dev/null +++ b/man/man7/image.html @@ -0,0 +1,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> |