205 lines
6.1 KiB
Text
205 lines
6.1 KiB
Text
.TH IMAGE 6
|
|
.SH NAME
|
|
image \- external format for images
|
|
.SH SYNOPSIS
|
|
.B #include <draw.h>
|
|
.SH DESCRIPTION
|
|
Images are described in
|
|
.IR graphics (2),
|
|
and the definition of pixel values is in
|
|
.IR color (6).
|
|
Fonts and images are stored in external files
|
|
in machine-independent formats.
|
|
.PP
|
|
Image files are read and written using
|
|
.B readimage
|
|
and
|
|
.B writeimage
|
|
(see
|
|
.IR allocimage (2)), or
|
|
.B readmemimage
|
|
and
|
|
.B writememimage
|
|
(see
|
|
.IR memdraw (2)).
|
|
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
|
|
.B strtochan
|
|
in
|
|
.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.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 \fId\fP\(mu(\fIx\fP mod (8/\fId\fP)),
|
|
.if n d*(x mod (8/d)),
|
|
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 loadimage
|
|
and
|
|
.B unloadimage
|
|
functions described in
|
|
.IR allocimage (2)
|
|
also deal with rows in this format, stored in user memory.
|
|
.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 color-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 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.
|
|
.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.
|
|
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.
|
|
.PP
|
|
A venerable yet deprecated 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.
|
|
.PP
|
|
Compressed 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.
|
|
.PP
|
|
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.
|
|
.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.
|
|
.PP
|
|
Some small images, in particular 48\(mu48 face files
|
|
as used by
|
|
.I seemail
|
|
(see
|
|
.IR faces (1)
|
|
and
|
|
.IR face (6))
|
|
and 16\(mu16
|
|
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
|
|
.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 from
|
|
the 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)
|