image(7) - Plan 9 from User Space

From 78e51a8c6678b6e3dff3d619aa786669f531f4bc Mon Sep 17 00:00:00 2001 From: rsc Date: Fri, 14 Jan 2005 03:45:44 +0000 Subject: checkpoint --- man/man7/image.html | 175 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 175 insertions(+) create mode 100644 man/man7/image.html (limited to 'man/man7/image.html') 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 @@ + +image(7) - Plan 9 from User Space + + + + +

IMAGE(7) IMAGE(7) +

+
+

NAME
+ +
+ + image – external format for images
+ +
+

SYNOPSIS
+ +
+ + #include <draw.h> + +
+

DESCRIPTION
+ +
+ + Images are described in graphics(3), and the definition of pixel + values is in color(7). Fonts and images are stored in external + files in machine-independent formats. +
+ + Image files are read and written using readimage and writeimage + (see allocimage(3)),or readmemimage and writememimage (see memdraw(3)). + An uncompressed image file starts with 5 strings: chan, r.min.x, + r.min.y, r.max.x, and r.max.y. Each is right-justified and blank + padded in 11 + characters, followed by a blank. The chan value is a textual string + describing the pixel format (see strtochan in graphics(3) and + the discussion of channel descriptors below), and the rectangle + coordinates are decimal strings. The rest of the file contains + the r.max.y−r.min.y rows of pixel data. A row consists + of the byte containing pixel r.min.x and all the bytes up to and + including the byte containing pixel r.max.x-1. For images with + depth d less than eight, a pixel with x-coordinate = x will appear + as d contiguous bits in a byte, with the pixel’s high order bit + starting at the byte’s bit number w×(x mod (8/w)), 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 d 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. +
+ + The loadimage and unloadimage functions described in allocimage(3) + also deal with rows in this format, stored in user memory. +
+ + The channel format string is a sequence of two-character channel + descriptions, each comprising a letter (r for red, g for green, + b for blue, a for alpha, m for color-mapped, k for greyscale, + and x 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 x. 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. +
+ + 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 'r8g8b8' pixels have byte ordering blue, green, + and red within the file. See color(7) for more details of the + pixel format. +
+ + A venerable yet deprecated format replaces the channel string + with a decimal ldepth, which is the base two logarithm of the + number of bits per pixel in the image. In this case, ldepths 0, + 1, 2, and 3 correspond to channel descriptors k1, k2, k4, and + m8, respectively. +
+ + Compressed image files start with a line of text containing the + word compressed, followed by a header as described above, followed + by the image data. The data, when uncompressed, is laid out in + the usual form. +
+ + 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. +
+ + A compression block begins with two decimal strings of twelve + bytes each. The first number is one more than the y 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. +
+ + 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. + +
+ + 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. +
+ + 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. +
+ + 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. + +
+ + Some small images, in particular 48×48 face files as used by seemail + (see Plan 9’s faces(1) and face(7)) 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 tweak(1).) 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.
+ +
+

SEE ALSO
+ +
+ + jpg(1), tweak(1), graphics(3), draw(3), allocimage(3), color(7), + face(7), font(7)
+ +
+ +

+ + +

		+
	+ + + +

+ + -- cgit v1.2.3