image man page on Plan9

Man page or keyword search:  
man Server   549 pages
apropos Keyword Search (all sections)
Output format
Plan9 logo
[printable version]

IMAGE(6)							      IMAGE(6)

NAME
       image - external format for images

SYNOPSIS
       #include <draw.h>

DESCRIPTION
       Images are described in graphics(2), and the definition of pixel values
       is in color(6).	Fonts and images  are  stored  in  external  files  in
       machine-independent formats.

       Image  files  are  read and written using readimage and writeimage (see
       allocimage(2)),or readmemimage and writememimage (see memdraw(2)).   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(2) 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-
       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 multi‐
       ple of 8, so pixel values take up an integral number of bytes.

       The loadimage and unloadimage functions described in allocimage(2) 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 particu‐
       lar  'r8g8b8' pixels have byte ordering blue, green, and red within the
       file.  See color(6) 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
       form.

       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 48×48 face files as  used  by  seemail
       (see  faces(1) and face(6)) 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 for‐
       mats reflect history rather than design.

SEE ALSO
       jpg(1),	tweak(1),  graphics(2),	 draw(2),   allocimage(2),   color(6),
       face(6), font(6)

								      IMAGE(6)
[top]
                             _         _         _ 
                            | |       | |       | |     
                            | |       | |       | |     
                         __ | | __ __ | | __ __ | | __  
                         \ \| |/ / \ \| |/ / \ \| |/ /  
                          \ \ / /   \ \ / /   \ \ / /   
                           \   /     \   /     \   /    
                            \_/       \_/       \_/ 
More information is available in HTML format for server Plan9

List of man pages available for Plan9

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net