20060303-partial

1 files changed, 178 insertions, 0 deletions

diff --git a/man/6/image b/man/6/image
new file mode 100644
index 00000000..93e668fa
--- /dev/null
+++ b/man/6/image
@@ -0,0 +1,178 @@
+.TH IMAGE 6
+.SH NAME
+image \- external format for images
+.SH DESCRIPTION
+Images are described in
+.IR draw-image (2),
+and the definition of pixel values is in
+.IR colour (6).
+Fonts and images are stored in external files
+in machine-independent formats.
+.PP
+Image files are read and written using
+.B Display.readimage
+and
+.B Display.writeimage
+(see
+.IR draw-display (2)).
+An image is a rectangular array of pixels,
+where each pixel is organised as one or more channels,
+as determined by the image.
+.PP
+An uncompressed image file starts with 5
+strings:
+.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 chan
+value is a textual string describing the pixel format
+(see below for a discussion of channel descriptors),
+and the rectangle coordinates are decimal strings.
+The rest of the file contains the
+.B r.max.y-r.min.y
+rows of pixel data.
+A
+.I row
+consists of the byte containing pixel
+.B r.min.x
+and all the bytes up to and including the byte containing pixel
+.BR r.max.x -1.
+For images with depth 
+.I d
+less than eight, a pixel with x-coordinate =
+.I x
+will appear as
+.I d
+contiguous bits in a byte, with the pixel's high order bit
+starting 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 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
+is greater than 8, the definition of images requires that it be a multiple of 8, so
+pixel values take up an integral number of bytes.
+.PP
+The
+.B Image.readpixels
+and
+.B Image.writepixel
+operations described in
+.IR draw-image (2)
+also deal with rows in this format, stored in Limbo arrays of bytes.
+.PP
+The channel format string is a sequence of two-character channel descriptions,
+each comprising a letter 
+.RB ( r
+for red,
+.B g
+for green,
+.B b
+for blue,
+.B a
+for alpha,
+.B m
+for colour-mapped,
+.B k
+for greyscale,
+and
+.B 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 
+.BR x .
+An image must have either a greyscale channel; a colour-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.
+.PP
+The channel string defines the format of the pixels in the file,
+and should not be confused with ordering of bytes in the file,
+which is little-endian.
+In particular
+.B 'r8g8b8'
+pixels have byte ordering blue, green, and red within the file.
+See
+.IR colour (6)
+for more details of the pixel format.
+.PP
+A previous Inferno image format replaces the channel string
+with 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 s
+0, 1, 2, and 3
+correspond to channel descriptors
+.BR k1 ,
+.BR k2 ,
+.BR k4 ,
+and
+.BR m8 ,
+respectively.
+Furthermore, the pixel values are inverted compared to the current colour maps;
+in particular, an all-zero pixel is white and all-ones is black.
+That format is still readable but cannot be written; older files should be converted to the
+newer one.
+The image file reading operations automatically invert the pixel values to produce correct results.
+.PP
+A compressed image file begins with the 11 bytes "compressed\en",
+immediately followed by a header as described above, followed by the
+image data.
+(The pixel data once uncompressed has the format described above.)
+The rest of the file is 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 Styx 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.
+.PP
+A compression block begins with two decimal strings of twelve bytes each.
+The first number is one more than the
+.B 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.
+.PP
+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.
+.PP
+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.
+.PP
+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.
+.PP
+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.
+.SH "SEE ALSO"
+.IR draw-intro (2),
+.IR draw-image (2),
+.IR draw (3),
+.IR colour (6),
+.IR font (6)