.TH IMAGE 6.SH NAMEimage \- external format for images.SH SYNOPSIS.B #include <draw.h>.SH DESCRIPTIONImages are described in.IR graphics (2),and the definition of pixel values is in.IR color (6).Fonts and images are stored in external filesin machine-independent formats..PPImage files are read and written using.B readimageand.B writeimage(see.IR allocimage (2)), or.B readmemimageand.B writememimage(see.IR memdraw (2)).An uncompressed image file starts with 5strings:.BR chan ,.BR r.min.x ,.BR r.min.y ,.BR r.max.x ,and.BR r.max.y .Each is right-justified and blank padded in 11 characters, followed by a blank.The.B chanvalue is a textual string describing the pixel format(see .B strtochanin.IR graphics (2)and the discussion of channel descriptors below),and the rectangle coordinates are decimal strings.The rest of the file contains the.B r.max.y-r.min.yrows of pixel data.A.I rowconsists of the byte containing pixel.B r.min.xand all the bytes up to and including the byte containing pixel.BR r.max.x -1.For images with depth .I dless than eight, a pixel with x-coordinate =.I xwill appear as.I dcontiguous bits in a byte, with the pixel's high order bitstarting at the byte's bit number.if t \fIw\fP\(mu(\fIx\fP mod (8/\fIw\fP)),.if n w*(x mod (8/w)),where bits within a byte are numbered 0 to 7 from thehigh order to the low order bit.Rows contain integral number of bytes, so there may be some unusedpixels at either end of a row.If.I dis greater than 8, the definition of images requires that it will a multiple of 8, sopixel values take up an integral number of bytes..PPThe.B loadimageand.B unloadimagefunctions described in.IR allocimage (2)also deal with rows in this format, stored in user memory..PPThe channel format string is a sequence of two-character channel descriptions,each comprising a letter .RB ( rfor red,.B gfor green,.B bfor blue,.B afor alpha,.B mfor color-mapped,.B kfor greyscale,and.B xfor ``don't care'')followed by a number of bits per pixel.The sum of the channel bits per pixel is thedepth of the image, which must be either a divisor or a multiple of eight.It is an error to have more thanone of any channel but .BR 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..PPThe 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.B 'r8g8b8'pixels have byte ordering blue, green, and red within the file.See.IR color (6)for more details of the pixel format..PPA venerable yet deprecated format replaces the channel stringwith a decimal.IR ldepth ,which is the base two logarithm of the number of bits per pixel in the image.In this case,.IR ldepth s0, 1, 2, and 3correspond to channel descriptors.BR k1 ,.BR k2 ,.BR k4 ,and.BR m8 ,respectively..PPCompressed image files start with a line of text containing the word.BR compressed ,followed by a header as described above, followed by the image data.The data, when uncompressed, is laid out in the usual form..PPThe data is represented by a string of compression blocks, each encodinga number of rows of the image's pixel data.  Compression blocksare at most 6024 bytes long, so that they fit comfortably in asingle 9P message.  Since a compression block must encode awhole number of rows, there is a limit (about 5825 bytes) to the width of imagesthat 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..PPA compression block begins with two decimal strings of twelve bytes each.The first number is one more than the.B ycoordinate of the last row in the block.  The second is the numberof bytes of compressed data in the block, not including the two decimal strings.This number must not be larger than 6000..PPPixels 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..PPThe compression block is a string of variable-lengthcode words encoding substrings of the pixel data.  A code word either gives thesubstring directly or indicates that it is a copy of data occurringpreviously in the pixel stream..PPIn a code word whose first byte has the high-order bit set, the rest of thebyte 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..PPIf the high-order bit is zero, the next 5 bits encodethe length of a substring copied from previous pixels.  Values from 0 to 31encode lengths from 3 to 34 bytes.  The bottom two bits of the first byte andthe 8 bits of the next byte encode an offset backward from the currentposition in the pixel data at which the copy is to be found.  Values from0 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 datais identical to the data at the given offset, even though the two strings overlap..PPSome small images, in particular 48\(mu48 face filesas used by.I seemail(see.IR faces (1)and.IR face (6))and 16\(mu16cursors, can be stored textually, suitable for inclusion in C source.Each line of text represents one scan line as acomma-separated sequence of hexadecimalbytes, 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 separatelyto be processed by programs such as.IR 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 fromthe input; there is no header.These formats reflect history rather than design..SH "SEE ALSO".IR jpg (1),.IR tweak (1),.IR graphics (2),.IR draw (2),.IR allocimage (2),.IR color (6),.IR face (6),.IR font (6)