1
0

image 6.1 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205
  1. .TH IMAGE 6
  2. .SH NAME
  3. image \- external format for images
  4. .SH SYNOPSIS
  5. .B #include <draw.h>
  6. .SH DESCRIPTION
  7. Images are described in
  8. .IR graphics (2),
  9. and the definition of pixel values is in
  10. .IR color (6).
  11. Fonts and images are stored in external files
  12. in machine-independent formats.
  13. .PP
  14. Image files are read and written using
  15. .B readimage
  16. and
  17. .B writeimage
  18. (see
  19. .IR allocimage (2)), or
  20. .B readmemimage
  21. and
  22. .B writememimage
  23. (see
  24. .IR memdraw (2)).
  25. An uncompressed image file starts with 5
  26. strings:
  27. .BR chan ,
  28. .BR r.min.x ,
  29. .BR r.min.y ,
  30. .BR r.max.x ,
  31. and
  32. .BR r.max.y .
  33. Each is right-justified and blank padded in 11 characters, followed by a blank.
  34. The
  35. .B chan
  36. value is a textual string describing the pixel format
  37. (see
  38. .B strtochan
  39. in
  40. .IR graphics (2)
  41. and the discussion of channel descriptors below),
  42. and the rectangle coordinates are decimal strings.
  43. The rest of the file contains the
  44. .B r.max.y-r.min.y
  45. rows of pixel data.
  46. A
  47. .I row
  48. consists of the byte containing pixel
  49. .B r.min.x
  50. and all the bytes up to and including the byte containing pixel
  51. .BR r.max.x -1.
  52. For images with depth
  53. .I d
  54. less than eight, a pixel with x-coordinate =
  55. .I x
  56. will appear as
  57. .I d
  58. contiguous bits in a byte, with the pixel's high order bit
  59. starting at the byte's bit number
  60. .if t \fIw\fP\(mu(\fIx\fP mod (8/\fIw\fP)),
  61. .if n w*(x mod (8/w)),
  62. where bits within a byte are numbered 0 to 7 from the
  63. high order to the low order bit.
  64. Rows contain integral number of bytes, so there may be some unused
  65. pixels at either end of a row.
  66. If
  67. .I d
  68. is greater than 8, the definition of images requires that it will a multiple of 8, so
  69. pixel values take up an integral number of bytes.
  70. .PP
  71. The
  72. .B loadimage
  73. and
  74. .B unloadimage
  75. functions described in
  76. .IR allocimage (2)
  77. also deal with rows in this format, stored in user memory.
  78. .PP
  79. The channel format string is a sequence of two-character channel descriptions,
  80. each comprising a letter
  81. .RB ( r
  82. for red,
  83. .B g
  84. for green,
  85. .B b
  86. for blue,
  87. .B a
  88. for alpha,
  89. .B m
  90. for color-mapped,
  91. .B k
  92. for greyscale,
  93. and
  94. .B x
  95. for ``don't care'')
  96. followed by a number of bits per pixel.
  97. The sum of the channel bits per pixel is the
  98. depth of the image, which must be either
  99. a divisor or a multiple of eight.
  100. It is an error to have more than
  101. one of any channel but
  102. .BR x .
  103. An image must have either a greyscale channel; a color mapped channel;
  104. or red, green, and blue channels.
  105. If the alpha channel is present, it must be at least as deep as any other channel.
  106. .PP
  107. The channel string defines the format of the pixels in the file,
  108. and should not be confused with ordering of bytes in the file.
  109. In particular
  110. .B 'r8g8b8'
  111. pixels have byte ordering blue, green, and red within the file.
  112. See
  113. .IR color (6)
  114. for more details of the pixel format.
  115. .PP
  116. A venerable yet deprecated format replaces the channel string
  117. with a decimal
  118. .IR ldepth ,
  119. which is the base two logarithm of the number
  120. of bits per pixel in the image.
  121. In this case,
  122. .IR ldepth s
  123. 0, 1, 2, and 3
  124. correspond to channel descriptors
  125. .BR k1 ,
  126. .BR k2 ,
  127. .BR k4 ,
  128. and
  129. .BR m8 ,
  130. respectively.
  131. .PP
  132. Compressed image files start with a line of text containing the word
  133. .BR compressed ,
  134. followed by a header as described above, followed by the image data.
  135. The data, when uncompressed, is laid out in the usual form.
  136. .PP
  137. The data is represented by a string of compression blocks, each encoding
  138. a number of rows of the image's pixel data. Compression blocks
  139. are at most 6024 bytes long, so that they fit comfortably in a
  140. single 9P message. Since a compression block must encode a
  141. whole number of rows, there is a limit (about 5825 bytes) to the width of images
  142. that may be encoded. Most wide images are in subfonts,
  143. which, at 1 bit per pixel (the usual case for fonts), can be 46600 pixels wide.
  144. .PP
  145. A compression block begins with two decimal strings of twelve bytes each.
  146. The first number is one more than the
  147. .B y
  148. coordinate of the last row in the block. The second is the number
  149. of bytes of compressed data in the block, not including the two decimal strings.
  150. This number must not be larger than 6000.
  151. .PP
  152. Pixels are encoded using a version of Lempel & Ziv's sliding window scheme LZ77,
  153. best described in J A Storer & T G Szymanski
  154. `Data Compression via Textual Substitution',
  155. JACM 29#4, pp. 928-951.
  156. .PP
  157. The compression block is a string of variable-length
  158. code words encoding substrings of the pixel data. A code word either gives the
  159. substring directly or indicates that it is a copy of data occurring
  160. previously in the pixel stream.
  161. .PP
  162. In a code word whose first byte has the high-order bit set, the rest of the
  163. byte indicates the length of a substring encoded directly.
  164. Values from 0 to 127 encode lengths from 1 to 128 bytes.
  165. Subsequent bytes are the literal pixel data.
  166. .PP
  167. If the high-order bit is zero, the next 5 bits encode
  168. the length of a substring copied from previous pixels. Values from 0 to 31
  169. encode lengths from 3 to 34 bytes. The bottom two bits of the first byte and
  170. the 8 bits of the next byte encode an offset backward from the current
  171. position in the pixel data at which the copy is to be found. Values from
  172. 0 to 1023 encode offsets from 1 to 1024. The encoding may be `prescient',
  173. with the length larger than the offset, which works just fine: the new data
  174. is identical to the data at the given offset, even though the two strings overlap.
  175. .PP
  176. Some small images, in particular 48\(mu48 face files
  177. as used by
  178. .I seemail
  179. (see
  180. .IR faces (1)
  181. and
  182. .IR face (6))
  183. and 16\(mu16
  184. cursors, can be stored textually, suitable for inclusion in C source.
  185. Each line of text represents one scan line as a
  186. comma-separated sequence of hexadecimal
  187. bytes, shorts, or words in C format.
  188. For cursors, each line defines a pair of bytes.
  189. (It takes two images to define a cursor; each must be stored separately
  190. to be processed by programs such as
  191. .IR tweak (1).)
  192. Face files of one bit per pixel are stored as a sequence of shorts,
  193. those of larger pixel sizes as a sequence of longs.
  194. Software that reads these files must deduce the image size from
  195. the input; there is no header.
  196. These formats reflect history rather than design.
  197. .SH "SEE ALSO"
  198. .IR jpg (1),
  199. .IR tweak (1),
  200. .IR graphics (2),
  201. .IR draw (2),
  202. .IR allocimage (2),
  203. .IR color (6),
  204. .IR face (6),
  205. .IR font (6)