Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
IMAGE(7)	       Miscellaneous Information Manual		      IMAGE(7)

       image - external	format for images

       #include	<draw.h>

       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  ma-
       chine-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  dis-
       cussion	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-co-
       ordinate	= 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  or-
       der  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	multi-
       ple 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 de-
       scriptions, 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 particu-
       lar  '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	corre-
       spond 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

       The data	is represented by a string of compression blocks, each	encod-
       ing 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 Com-
       pression	via Textual Substitution', JACM	29#4, pp. 928-951.

       The compression block is	a string of variable-length code words	encod-
       ing  substrings	of  the	pixel data.  A code word either	gives the sub-
       string directly or indicates that it is a copy of data occurring	previ-
       ously 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	48x48 face files as  used  by  seemail
       (see  Plan  9's	faces(1) and face(7)) and 16x16	cursors, can be	stored
       textually, suitable for inclusion in C source.  Each line of text  rep-
       resents	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.

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



Want to link to this manual page? Use this URL:

home | help