home *** CD-ROM | disk | FTP | other *** search
/ Collection of Hack-Phreak Scene Programs / cleanhpvac.zip / cleanhpvac / FAQSYS18.ZIP / FAQS.DAT / GLFORMAT.TXT < prev    next >
Text File  |  1996-01-04  |  30KB  |  817 lines
  1. Note that some of this information is incomplete.  Check the Grasp
  2. manual for clarification on e.g. the script-file commands.  If 
  3. anybody would like to merge all relevant documents together, that
  4. would be nice.
  5.  
  6. These documents were passed to me by Martin Fong, fong@erg.sri.com
  7.  
  8. Eli Brandt   eli@smectos.gang.umass.edu  32@4351 WWIV
  9. ========================================================================
  10.  
  11. The formats of GRASP animation files.
  12. By George Phillips <phillips@cs.ubc.ca>
  13. Distribute this freely, but give credit where credit is due, eh?
  14. Version: Jan. 19,1991
  15.  
  16. GRASP is an animation system particular to the IBM PC world.  It consists
  17. of a program to create animations and a run-time environment for
  18. displaying them.  The most common form these animations take is ".GL"
  19. archives which may be displayed on an IBM-PC with a program called
  20. GRASPRT.EXE.  This document describes what I have been able to
  21. decipher about the format of ".GL" archives and the files contained
  22. within.  It should be useful to those attempting to write ".GL"
  23. animation players on other platforms.
  24.  
  25. A ".GL" file is simply an archive file which contains images, fonts
  26. and a command file which tells GRASPRT what to do.  These various
  27. files have standard extensions to denote their contents:
  28.  
  29. .txt - A command file; usually there is only one of these per archive.
  30. .pic - An image.
  31. .clp - An image but without a colour map.
  32. .set or .fnt - A font containing character glyphs.
  33.  
  34. It should be noted that the GL archive is of no particular importance;
  35. all the archived files could exist as ordinary files and the animation
  36. should still work.  Any GL player should be able to operate both from
  37. an archive or from ordinary files.
  38.  
  39.  
  40. File Formats
  41.  
  42. Most of the data in GL files can be adequately described as a stream
  43. of bytes which is practically universally understood.  Some fields
  44. contain 2-byte and 4-byte integers.  I'll refer to these as "words"
  45. and "long words" and they are all stored in little-endian format.
  46. So if we have 4 consecutive bytes, b1, b2, b3 and b4, the word
  47. at b1 is (b1 + b2 * 256) and the long word at b1 is
  48. (b1 + b2 * 256 + b3 * 256 * 256 + b4 * 256 * 256 * 256).
  49.  
  50. Since this information was gathered by example, the purpose of some
  51. header fields and commands may not be known.  I've marked unknown
  52. fields with question marks and have tried to put question marks and
  53. other warnings about descriptions which are guesses.
  54.  
  55.  
  56. GL Archives (.gl)
  57.  
  58. A GL archive begins with a directory listing the files in the archive
  59. which is followed by the data for each file.
  60.  
  61. +-- Directory Header
  62. | dir length    (word)        number of bytes in the directory header
  63. | +-- File Entry (17 bytes per, (dir length) / 17 of them)
  64. | | offset    (long word)    Position of file data as an offset from
  65. | |                the beginning of the archive
  66. | | name    (13 bytes)    File name, null padded.
  67. | +--
  68. +--- File data area
  69. | +-- File Data
  70. | | length    (long word)    Size of the file
  71. | | data    (bytes)        the file's data (surprise!)
  72. | +--
  73. +---
  74.  
  75. Font Files (.fnt or .set)
  76.  
  77. These are very simple; first a short header describing the size of the
  78. characters in the font and what byte values correspond to each glyph
  79. followed by the glyph data.
  80.  
  81. +-- Font Header
  82. | length    (word)        length of the entire font file
  83. | size        (byte)        number of glyphs in the font file
  84. | first        (byte)        byte value represented by the first glyph
  85. | width        (byte)        width of each glyph in pixels
  86. | height    (byte)        height of each glyph in pixels
  87. | glyphsize    (byte)        number of bytes to encode each glyph
  88. +-- Glyph Data
  89. | glyph first
  90. | glyph first + 1
  91. | ...
  92. | glyph first + size - 2
  93. | glyph first + size - 1
  94. +--
  95.  
  96. Each glyph is stored almost exactly as you would expect a raw PBM file to
  97. contain it except that a '0' bit means black and a '1' bit means white.
  98. In other words, row major order, each line padded to end on a byte
  99. boundary, most significant bit is leftmost.
  100.  
  101.  
  102. Image Formats (.pic and .clp)
  103.  
  104. These consist of a header containing the usual image information followed
  105. by blocked, run-length encoded image data.
  106.  
  107. +-- Image Header (17 or 19 bytes)
  108. | magic?    (byte)        magic number?  Always is 0x34 or 0x12
  109. | width        (word)        width of image in pixels
  110. | height    (word)        heigh of image in pixels
  111. | ????        (4 bytes)    unknown
  112. | bpp        (byte)        bits per pixel (only seen 1 or 8)
  113. | type        (byte)        image type, either 'L' or 'C'
  114. | flags        (byte)        if (flags & 4) then image has colourmap
  115. | ?        (byte)        unknown
  116. | extend    (byte)        extended header byte (if != 0, header
  117. |                has 2 more bytes) 1/2?
  118. | ?        (byte)        unknown
  119. | ??        (2 bytes)    header extension if extend != 0
  120. +-- Colour Map ((1 << bpp) * 3 bytes, only if flags & 4 == 4)
  121. | +-- Colour Map entries (as many as indicated by bpp)
  122. | | R        (byte)        red intensity, 0 - 63   \
  123. | | G        (byte)        green intensity, 0 - 63  + entry 0
  124. | | B        (byte)        blue intensity, 0 - 63  /
  125. | +--
  126. | ...
  127. +-- Image Data
  128. | blocks    (word)        number of blocks of data
  129. | +-- Data Block (blocks of them)
  130. | | length    (word)        length of data block, including header
  131. | | bufsize    (word)        buffer size needed to hold all the
  132. | |                uncompressed data in this block
  133. | | esc        (byte)        the escape code in this block
  134. | | data    (length - 5 byte)    run-length encoded data
  135. | +--
  136. +--
  137.  
  138. The run-length encoding is byte oriented and follows these rules:
  139.  
  140. - characters other than "esc" (see data block header) are literal
  141. - esc n c means repeat c n times (1 <= n <= 255)
  142. - esc 0 len(word) c means repeat c len times
  143.  
  144. If bpp=1, then the resulting data stream is interpreted as it is
  145. with font glyphs (i.e., msb is left, pad to bytes, row first, etc).
  146. If bpp=8, then each byte in the data stream is an index into the
  147. colour map.  If no colour map is available, the map to use can
  148. only be discovered by running through the command file.
  149.  
  150. I've only seen images with bpp=1 and bpp=8 and they it always works
  151. out that either bpp=1 and type=C or bpp=8 and type=L.  The type=C
  152. corresponds to CGA graphics which are mostly monochrome and 640 x 200
  153. (so the aspect ratio is funny).  Type=L is colour graphics, prob. VGA
  154. and usually 320 x 200.  Notice that the colour maps have only 6
  155. bits, the same as VGA's digital to analog converters.  ".pic" files
  156. always have colour maps, ".clp" files never do.  It seems that
  157. you can be lazy with your run-length decoding code; I've never seen
  158. a full sequence appear across a data-block boundary (encoders should
  159. probably not let that happen).  The amount of uncompressed data
  160. in a block never seems to exceed 8192 bytes.
  161.  
  162. Much of the header information is mysterious.  Note that the header
  163. extension field is a guess and that there are other consistent
  164. possibilities (e.g., the extension field is a length byte or even
  165. part of a length word).  Only type=C images seem to have the
  166. extension.  Maybe the extra information is supposed to be used
  167. in video mode operating system calls on the PC?
  168.  
  169. What made this part easier was the existence of a PC-based program which
  170. converts ".pic" files into GIF files.  Its called "cvt2gif" and can
  171. be found on wuarchive.wustl.edu:/mirrors/msdos/gif/cvt2gif.zip.  Those
  172. wishing to enhance the format descriptions would do well to get a
  173. copy.  I did notice that bpp=1 images are not necessarily black and white
  174. but could be black and some other colour as selected from the CGA
  175. pallette.  I doubt the distinction will make much difference to the
  176. animation, but if you really want to do it right...
  177.  
  178.  
  179. Command File (.txt)
  180.  
  181. The command file looks like a typical script file with the lines delimited
  182. by carriage returns, line feeds or both.  Any text following ';' on a line
  183. is a comment.  Text followed by a colon is used to indicate a label
  184. (much like most assemblers).  Commands consist of a keyword followed by a
  185. list of comma separated arguments.  The input is case-insensitive except
  186. for arguments containing text to display (which are in double quotes).
  187.  
  188. The basis of the command language seems to be what I call picture and
  189. clip registers, of which there are 16 of each.  A few commands will
  190. load a picture (or clip) from a file into a register.  Other commands
  191. then reference the register numbers to display the pictures or get
  192. colour maps from them.  It seems that the colour map from a picture
  193. (.pic) is installed into the hardware and this is where the
  194. colour maps for the clips (.clp) come from.  I assume that I am missing
  195. a lot of commands, but most notably I believe there should be
  196. more primitive drawing commands.
  197.  
  198. Many of the commands seem to have a delay argument associated with
  199. them.  This seems reasonable as control over time in an animation
  200. is important.  I may have been over-zealous in looking for delays.
  201. The actual time units of the delays is unknown.  They are typically
  202. numbers < 100, so milliseconds are a likely candidate.  Hundredths
  203. of a second are possible as well.
  204.  
  205. Here is a list of commands.  Optional arguments are enclosed in [].
  206. Ranges are possible in arguments (I've only seem them in fly) and
  207. take the form "n,-,m", (e.g., fly 0,0,10,10,1,1,1,-,16).
  208.  
  209. * box x1,y1,x2,y2,colour?
  210. Draw a box with corners (x1, y1) and (x2, y2) in the colour given by
  211. the colourmap entry number.
  212.  
  213. * cfade x,y,delay,img,[,?,?]
  214. Display a clip image img at (x, y) and wait for delay time units before
  215. proceeding.
  216.  
  217. * cfree n
  218. Free up any memory associated with clip register n.
  219.  
  220. * clearscr
  221. Clear the display (to the currently selected colour or black?).
  222.  
  223. * cload name,num[,?]
  224. Load a clip image "name" into clip register num.  If name does not
  225. have a .clp extension, it will be automatically appended.
  226.  
  227. * color n
  228. Set the current colour to n.  This at least seems to affect the
  229. text displaying commands.
  230.  
  231. * exit
  232. Terminate the command file.
  233.  
  234. * fload name
  235. Load the named font which becomes the font to be used when displaying
  236. text.  ".fnt" is appended to name if necessary.
  237.  
  238. * float x1,y1,x2,y2,step?,delay?,num
  239. Move the clip image (num) by displaying it at (x1,y1) and erasing it
  240. and displaying it every step pixels until (x2,y2).  Delay delay time
  241. units in between steps.  Or maybe something completely different,
  242. but the x1,y1,x2,y2 and num arguments are probably coordinates and
  243. a clip number.
  244.  
  245. * fly x1,y1,x2,y2,step?,delay?,clip list
  246. Successively display the clip images from (x1,y1) to (x2,y2) with delay
  247. time units in-between.  The clip list is just a bunch of clip numbers
  248. separated by commas (i.e., fly is varags).  A range is likely to
  249. appear in the clip list.  Often (x1,y1) == (x2,y2).
  250.  
  251. * fstyle ?[,?]
  252. Presumably set up some parameters on how a font is displayed.
  253.  
  254. * goto label
  255. Force flow of control to the given label.
  256.  
  257. * loop
  258. Denotes the end of a mark loop.  Continues the loop at the most recent
  259. mark if the loop hasn't finished.  
  260.  
  261. * mark n
  262. This pairs with the loop command and begins a for loop from 1 to n.
  263. One assumes that the interaction of mark, loop and goto is the same
  264. as for, next and goto in BASIC.  That is, loops are dynamically
  265. scoped and you can jump in and out of them.  Mark simply pushes
  266. a loop start onto the stack and loop examines whatever is on
  267. the top of the loop stack.
  268.  
  269. * mode ?
  270. Modify the current video mode in some way.  I haven't seen this often.
  271.  
  272. * note freq,delay?,duration
  273.  
  274. Play a musical note of the given frequency and duration and delay for
  275. delay time units afterward.
  276.  
  277. * pallette n
  278. Make the colour map from picture register n be the one to use.  This probably
  279. installs it into the hardware so that when a clip is loaded there is
  280. no colour map to change.
  281.  
  282. * pfade effect,pict[,delay?[,?,?]]
  283. Display the picture numbered pict on the screen.  The effect number
  284. indicates what sort of special effect is used to display it.  What
  285. the numbers mean I have no idea, but I know some of the effects.
  286. Each pixel loaded randomly, every even line then every odd line
  287. and so on.  The delay parameter seems to make sense, but not always.
  288. The extra parameters could be those needed for some effects.  Often
  289. they are large numbers.
  290.  
  291. * pfree n
  292. Free up any memory associated with picture register n.
  293.  
  294. * pload name,n
  295. Load picture "name" into picture register n.  ".pic" is appended to
  296. name if necessary.
  297.  
  298. * putup x,y,n
  299. Display clip register n at (x,y).
  300.  
  301. * set retrace [on|off]
  302. Set is probably a general internal control variable changing command.
  303. What retrace is I have no idea, but it was set off then on around
  304. a fly statement.
  305.  
  306. * spread ?,?
  307. Who knows, but the numbers used are probably picture register numbers.
  308. Maybe some kind of colourmap changing?
  309.  
  310. * text x,y,"text",[delay?]
  311. Display the given text (enclosed in double quotes) at (x,y).  The
  312. extra parameter is probably a display, but it could be the display
  313. colour or the background colour.  Probably the display colour is
  314. that given by the color statement.
  315.  
  316. * tran [on 0|off]
  317. No idea.  Was used around some cload and float statements.
  318.  
  319. * video mode
  320. Set the display mode to 'C' or 'L' (remember the image format types?).
  321. Usually the first statement in a command file.  C almost certainly
  322. refers to CGA which is 640 x 200 monochrome and L almost certainly
  323. to VGA which (in their case) is 320 x 200 x 256.
  324.  
  325. * waitkey [[delay[,label]]
  326. Wait up to delay units for the user to press a key (or forever if no
  327. delay time is given).  If the user presses a key and the label
  328. argument is present, transfer control to that label.
  329.  
  330. * window x1,y1,x2,y2,?
  331. Some kind of display control.  Probably a clipping window with appropriate
  332. coordinate translation (i.e., (0,0) becomes (x1,y1)).
  333.  
  334.  
  335.  
  336. This document was created by looking hard at a number of GL files,
  337. using cvt2gif to help decipher the image file format and looking
  338. at 1 or 2 animations on an RS-6000 running a PC emulator and using
  339. grasprt.  cvt2gif was very useful; grasprt under the PC emulator
  340. was painfully slow at times and didn't help my understanding
  341. much.  I've never even gotten close to a copy of the program for
  342. creating and editing GL files.
  343.  
  344. If you find out more about GL files, send me the changes so I can
  345. extend this document.  Feel free to include this as supplementary 
  346. documentation if you write a GL player.  Finally, here are some
  347. projects which could help find out more about GL files:
  348.  
  349. - Get cvt2gif and feed it small variations on .pic files to decipher
  350. the meaning of the missing header fields.  I may do this.
  351.  
  352. - Alter control files on some animations and see what effects they
  353. have.  Something easy would be to change the effect number on
  354. pfade statements (if that's what it is).  I don't have the hardware
  355. to do this.
  356.  
  357. - Look at the GRASP animation package and intuit what the commands
  358. mean by what control you have over generating animations.  This is
  359. probably the easiest way to get information.  I don't have GRASP,
  360. I don't know where to get it and I don't has a PC good enough to
  361. run it on.
  362.  
  363. ========================================================================
  364.  
  365. GRASP/Pictor Font format description                                  09/06/87
  366. ------------------------------------                                  --------
  367.  
  368. For convenience, we have chosen to adopt the IBM ROM font format for data, but
  369. to keep things manageable, we have added a 7 byte header which describes the
  370. font.
  371.  
  372. The seven byte header is defined as follows:
  373.  
  374. WORD    number of bytes in character data, plus this 7 byte header.
  375. BYTE    number of characters in set. 1-255 or 0 if 256.
  376. BYTE    ascii value of first character.
  377. BYTE    x size of character in pixels.
  378. BYTE    y size of character in pixels.
  379. BYTE    number of bytes in a single character.
  380.  
  381. As you can see from this header data, these limits apply:
  382.  
  383. 1) Maximum number of characters in set is 256.
  384. 2) Maximum character size is limited as: xsize/8 * ysize <256.
  385. 3) All character data plus 7 byte header must be <64K in size
  386.  
  387.  
  388. We use the following structure when writing programs that use fonts. Note the
  389. additional words at the end of the structure which allow you to keep the actual
  390. character data in a far segment.
  391.  
  392. struct chs {        /* character set structure */
  393.     unsigned int numchbyts;
  394.     unsigned char numchars;
  395.     unsigned char ascoff;
  396.     unsigned char chxsize;
  397.     unsigned char chysize;
  398.     unsigned char chbytes;
  399.     unsigned int chsseg;    /* segment of character data */
  400.     unsigned int chsofs;    /* offset in segment of character data */
  401. };
  402.  
  403.  
  404. So....A 256 character 8x16 font's header would look like:
  405.  
  406. numchbyts   = 4103         256 chars X 16 bytes/char + 7 bytes for header
  407. numchars    =    0         0 to represent 256
  408. ascoff      =    0         start with 0 character
  409. chxsize     =    8         8 dots wide
  410. chysize     =   16         16 dots high
  411. chbytes     =   16         1 byte wide x 16 dots high
  412.  
  413.  
  414. and a 96 character 11 X 18 font whose first character is SPACE's header would
  415. look like:
  416.  
  417. numchbyts   = 3456         96 chars X 36 bytes/char + 7 bytes for header
  418. numchars    =    0         0 to represent 256
  419. ascoff      =   32         start with 'SPACE' character
  420. chxsize     =   11         8 dots wide (this takes 2 bytes!)
  421. chysize     =   18         16 dots high
  422. chbytes     =   36         2 byte wide x 18 dots high
  423.  
  424. ========================================================================
  425.  
  426.  
  427.  
  428.                    PCPAINT/Pictor Page Format Description
  429.  
  430.                           Format by John Bridges.
  431.  
  432.                    Document by Microtex Industries, Inc.
  433.  
  434.  
  435.  
  436.  
  437.  
  438. Revision Date: 2/9/88
  439.  
  440.  
  441.  
  442. Global Notes:
  443. ------------
  444.  
  445. PCPAINT 1.0 - Revision 1.0 was developed for Mosue Systems in 1984 supported
  446. only BSAVE files in CGA 4 color mode. In the space between the scan buffers
  447. was a string that read PCPAINT 1.0 followed by 2 bytes which were the pallete
  448. and border information for that picture.
  449.  
  450. PCPAINT 1.5 - Revision 1.5 was the same as 1.0 except that it contained larger
  451. than screen images and also had a primative packing format. This was sold for
  452. so short a time that it won't be covered here.
  453.  
  454. PCPAINT 2.0 thru Pictor 3.1 - This document describes these formats. The file
  455. description is identical for all revisions in this range. However, in
  456. PCPAINT 2.0, the bit-planes were packed together so that the pictures
  457. resembled a PCjr picture, or 4 bits per pixel, 1 bit plane. Starting with
  458. Pictor 3.0, the files were saved with the bitplanes separated. This takes a
  459. little more memory in some cases, but the speed in loading and saving was a
  460. desireable consideration.
  461.  
  462. NOTE TO PROGRAMMERS: A good PCPAINT/Pictor file decoder will use the variables
  463.                      in the header to decode the image and thus be compatible
  464.                      with all formats since the October, 1985 release of
  465.                      PCPAINT 2.0.
  466.  
  467. Also please note that PCPAINT/Pictor are stored from the bottom up. This is
  468. opposite that of most of the screen adapters it supports. This really causes
  469. no problem, but be aware that you should use a Y table to look up scan lines.
  470. In all PCPAINT/Pictor pictures, the scan lines are continuous. If a picture 
  471. is to be displayed on a particular adapter, the programmer is responsible for
  472. using a y-table to properly interleave the lines if necessary.
  473.  
  474. Also note that Pictor was designed for speed, so no inter-mode loading is
  475. possible. If you are writing applications that create Pictor images that you
  476. want to load into Pictor, you must remain mode dependent. 
  477.  
  478. Header - A full description of the file header information.
  479.  
  480. offset    type    name    description
  481. -------    -------    -------    ----------------------------------------------------- 
  482.   0    word    marker    marker that is always 01234h
  483.  
  484.   2    word    xsize    x size of page in pixels 
  485.  
  486.   4    word    ysize    y size of page in pixels
  487.  
  488.   6    word    xoff    x offset into page where lower left hand corner of
  489.             viewport is located (default of 0 is ok)
  490.  
  491.   8    word    yoff    y offset into page where lower left hand corner of
  492.             viewport is located (default of 0 is ok)
  493.  
  494.  10    byte    bitsinf    bits 0-3 is the number of bits per pixel per bit
  495.             plane and bits 4-7 is the number of bit planes (so
  496.             4 color cga mode would be 02h and 16 color ega would
  497.             be 31h and plantronics 16 color would be 12h)
  498.  
  499.  11    byte    emark    marker that is always a 0ffh
  500.  
  501.  12    byte    evideo    single uppercase letter indicating which video mode
  502.             this picture was created in, can default to 0.
  503.  
  504.             0 - 40 col text
  505.             1 - 80 col text
  506.             2 - mono text
  507.             3 - 43 line text
  508.  
  509.             A=320x200x4 cga
  510.             B=320x200x16 pcjr, stbplus, tandy 1000
  511.             C=640x200x2 cga
  512.             D=640x200x16 ega
  513.             E=640x350x2 ega
  514.             F=640x350x4 ega
  515.             G=640x350x16 ega
  516.             H=720x348x2 hercules
  517.             I=320x200x16 plantronics
  518.             J=320x200x16 ega
  519.             K=640x400x2 AT&T or Toshiba 3100
  520.             L=320x200x256 vga
  521.             M=640x480x16 ega plus(video 7, tseng, paradise), vga
  522.             N=720x348x16 Hercules InColor
  523.             O=640x480x2 vga
  524.  
  525.  13    word    edesc    extra information descriptor defines what is in
  526.             the extra information that follows this header,
  527.             0=nothing
  528.             1=pallet (single byte) border (single byte)[CGA]
  529.             2=pcjr or non ECD 16 color registers (0-15), 1 byte each
  530.             3=EGA with ECD 16 color registers (0-63) 1 byte each
  531.             4=VGA 256 color info - 256 colors, 1 byte each rgb gun.  
  532.  
  533.  15    word    esize    size of extra information in bytes
  534.  
  535.  17    byte    edata[]    the actual extra data the size which is defined
  536.             by esize (at offset 15).
  537.  17+
  538.  esize    word    numblks    the number of packed blocks in this file. if this is
  539.             a zero, then data is unpacked. 
  540.  
  541.  
  542. Structures - These C structures describe the header information.
  543.  
  544. struct head {
  545.     unsigned int mark=0x1234;    /* marks begining of a page file */
  546.     unsigned int xsize;        /* x size of page */
  547.     unsigned int ysize;        /* y size of page */
  548.     unsigned int xoff;        /* current x offset into picture of viewport */
  549.     unsigned int yoff;        /* current y offset into picture of viewport */
  550.     unsigned char bitsinf;
  551. }
  552.  
  553. struct extra {
  554.     unsigned char emark=0xff;
  555.     unsigned char evideo;
  556.     unsigned int edesc;
  557.     unsigned int esize;
  558. }
  559.  
  560. int edata[esize];
  561. unsigned int numblks;
  562.  
  563. If the file is packed then what follows is a multi block packed file,
  564. otherwise (if the file is not packed, numblks=0) the actual data follows.
  565.  
  566. Bit planes follow each other in the file and when packed each bit plane
  567. must start in a new packed block.
  568.  
  569.  
  570. Packed Block Description
  571.  
  572.  
  573. Packed block header
  574.  
  575. PBSIZE    dw        ;Packed block size. The size of this block
  576. BSIZE    dw        ;Unpacked block size
  577. MBYTE    db        ;Unique marker byte. This is a byte that does not
  578.             ; exist in the current unpacked block. If no unique
  579.             ; byte exists, then pick one that is used rarely
  580.             ; to avoid too much redundancy.
  581.  
  582. Packed block data - variable size depending on whether 16 bit run is needed.
  583.  
  584. MARKER    db        ;mark a run (this is where MBYTE goes) 
  585. LENGTH    db        ;length of run. if 0, then look at BIGLEN
  586.  
  587. BIGLEN    dw        ;16 bit run count (only exists if LENGTH==0)
  588. DATA    db        ;byte to fill run with
  589.  
  590.  
  591. Example 1 - a 320x200, 4 color, packed page file, of a white screen. 
  592.  
  593.     dw    0x1234        ;marker
  594.     dw    320        ;x size
  595.     dw    200        ;y size
  596.     dw    0        ;x offset
  597.     dw    0        ;y offset
  598.     db    02h        ;2 bits per pixel and 1 bit plane
  599.  
  600.     db    0xff        ;extra info flag
  601.     db    'A'        ;vidmode
  602.     dw    1        ;extra area descriptor (pal and bord)
  603.     dw    2        ;bytes in extra area
  604.     db    2,0        ;pallet and border (extra information)
  605.  
  606.     dw    2        ;number of packed blocks
  607.  
  608. ;first block
  609.     dw    5+5        ;packed block size
  610.     dw    8192        ;unpacked block size
  611.     db    0        ;marker byte
  612.     db    0        ;mark a run
  613.     db    0        ;a 16 bit run count follows
  614.     dw    8192        ;16 bit run count
  615.     db    0xff        ;byte to fill run with
  616. ;second block
  617.     dw    5+5        ;packed block size
  618.     dw    7808        ;unpacked block size
  619.     db    0        ;marker byte
  620.     db    0        ;mark a run
  621.     db    0        ;a 16 bit run count follows
  622.     dw    7808        ;16 bit run count
  623.     db    0xff        ;byte to fill run with
  624.  
  625.  
  626.  
  627.  
  628. Example 2 - a 640x350, 16 color, packed page file, of a red screen (color 4).
  629.  
  630.     dw    0x1234        ;marker
  631.     dw    640        ;x size
  632.     dw    350        ;y size
  633.     dw    0        ;x offset
  634.     dw    0        ;y offset
  635.     db    31h        ;bits per pixel and 1 bit plane
  636.  
  637.     db    0xff        ;new extra info flag
  638.     db    'G'        ;vidmode
  639.     dw    3        ;extra area descriptor (pal and bord)
  640.     dw    16        ;bytes in extra area
  641.     db    0,1,2,3,4,5,14h,7
  642.     db    38h,39h,3ah,3bh,3ch,3dh,3eh,3fh
  643.  
  644.     dw    16        ;number of packed blocks
  645. ;block 1 of first bit plane
  646.     dw    5+5        ;packed block size
  647.     dw    8192        ;unpacked block size
  648.     db    0        ;marker byte
  649.     db    0        ;mark a run
  650.     db    0        ;a 16 bit run count follows
  651.     dw    8192        ;16 bit run count
  652.     db    0        ;byte to fill run with
  653. ;block 2 of first bit plane
  654.     dw    5+5        ;packed block size
  655.     dw    8192        ;unpacked block size
  656.     db    0        ;marker byte
  657.     db    0        ;mark a run
  658.     db    0        ;a 16 bit run count follows
  659.     dw    8192        ;16 bit run count
  660.     db    0        ;byte to fill run with
  661. ;block 3 of first bit plane
  662.     dw    5+5        ;packed block size
  663.     dw    8192        ;unpacked block size
  664.     db    0        ;marker byte
  665.     db    0        ;mark a run
  666.     db    0        ;a 16 bit run count follows
  667.     dw    8192        ;16 bit run count
  668.     db    0        ;byte to fill run with
  669. ;block 4 of first bit plane
  670.     dw    5+5        ;packed block size
  671.     dw    3424        ;unpacked block size
  672.     db    0        ;marker byte
  673.     db    0        ;mark a run
  674.     db    0        ;a 16 bit run count follows
  675.     dw    3424        ;16 bit run count
  676.     db    0        ;byte to fill run with
  677. ;block 1 of second bit plane
  678.     dw    5+5        ;packed block size
  679.     dw    8192        ;unpacked block size
  680.     db    0        ;marker byte
  681.     db    0        ;mark a run
  682.     db    0        ;a 16 bit run count follows
  683.     dw    8192        ;16 bit run count
  684.     db    0        ;byte to fill run with
  685. ;block 2 of second bit plane
  686.     dw    5+5        ;packed block size
  687.     dw    8192        ;unpacked block size
  688.     db    0        ;marker byte
  689.     db    0        ;mark a run
  690.     db    0        ;a 16 bit run count follows
  691.     dw    8192        ;16 bit run count
  692.     db    0        ;byte to fill run with
  693. ;block 3 of second bit plane
  694.     dw    5+5        ;packed block size
  695.     dw    8192        ;unpacked block size
  696.     db    0        ;marker byte
  697.     db    0        ;mark a run
  698.     db    0        ;a 16 bit run count follows
  699.     dw    8192        ;16 bit run count
  700.     db    0        ;byte to fill run with
  701. ;block 4 of second bit plane
  702.     dw    5+5        ;packed block size
  703.     dw    3424        ;unpacked block size
  704.     db    0        ;marker byte
  705.     db    0        ;mark a run
  706.     db    0        ;a 16 bit run count follows
  707.     dw    3424        ;16 bit run count
  708.     db    0        ;byte to fill run with
  709. ;block 1 of third bit plane
  710.     dw    5+5        ;packed block size
  711.     dw    8192        ;unpacked block size
  712.     db    0        ;marker byte
  713.     db    0        ;mark a run
  714.     db    0        ;a 16 bit run count follows
  715.     dw    8192        ;16 bit run count
  716.     db    0xff        ;byte to fill run with
  717. ;block 2 of third bit plane
  718.     dw    5+5        ;packed block size
  719.     dw    8192        ;unpacked block size
  720.     db    0        ;marker byte
  721.     db    0        ;mark a run
  722.     db    0        ;a 16 bit run count follows
  723.     dw    8192        ;16 bit run count
  724.     db    0xff        ;byte to fill run with
  725. ;block 3 of third bit plane
  726.     dw    5+5        ;packed block size
  727.     dw    8192        ;unpacked block size
  728.     db    0        ;marker byte
  729.     db    0        ;mark a run
  730.     db    0        ;a 16 bit run count follows
  731.     dw    8192        ;16 bit run count
  732.     db    0xff        ;byte to fill run with
  733. ;block 4 of third bit plane
  734.     dw    5+5        ;packed block size
  735.     dw    3424        ;unpacked block size
  736.     db    0        ;marker byte
  737.     db    0        ;mark a run
  738.     db    0        ;a 16 bit run count follows
  739.     dw    3424        ;16 bit run count
  740.     db    0xff        ;byte to fill run with
  741. ;block 1 of fourth bit plane
  742.     dw    5+5        ;packed block size
  743.     dw    8192        ;unpacked block size
  744.     db    0        ;marker byte
  745.     db    0        ;mark a run
  746.     db    0        ;a 16 bit run count follows
  747.     dw    8192        ;16 bit run count
  748.     db    0        ;byte to fill run with
  749. ;block 2 of fourth bit plane
  750.     dw    5+5        ;packed block size
  751.     dw    8192        ;unpacked block size
  752.     db    0        ;marker byte
  753.     db    0        ;mark a run
  754.     db    0        ;a 16 bit run count follows
  755.     dw    8192        ;16 bit run count
  756.     db    0        ;byte to fill run with
  757. ;block 3 of fourth bit plane
  758.     dw    5+5        ;packed block size
  759.     dw    8192        ;unpacked block size
  760.     db    0        ;marker byte
  761.     db    0        ;mark a run
  762.     db    0        ;a 16 bit run count follows
  763.     dw    8192        ;16 bit run count
  764.     db    0        ;byte to fill run with
  765. ;block 4 of fourth bit plane
  766.     dw    5+5        ;packed block size
  767.     dw    3424        ;unpacked block size
  768.     db    0        ;marker byte
  769.     db    0        ;mark a run
  770.     db    0        ;a 16 bit run count follows
  771.     dw    3424        ;16 bit run count
  772.     db    0        ;byte to fill run with
  773.  
  774.  
  775.  
  776. Example 3 - For more detail lets consider a block that isn't all the same.
  777. Say the data consists of 30 2's, and 8, a 4, and 300 1's.
  778.  
  779. ; the block would look like this 
  780.  
  781.     dw    5+10        ;packed block size
  782.     dw    332        ;30 + 1 + 1 + 300 bytes as above
  783.     db    ff        ;what to mark a run with,
  784.                                 ; because there are no ff's in our example.
  785.  
  786.     db    ff        ;mark a run 
  787.     db    30        ;8 bit run count
  788.     db    2        ;byte to fill run with - 2
  789.  
  790.     db    8        ;not a run marker, so must be data
  791.  
  792.     db    4        ;not a run marker, so must be data
  793.  
  794.     db    ff        ;mark a run
  795.     db    0        ;means 16 bit run count follows
  796.     dw    300        ;run count    
  797.     db    1        ;byte to fill run with - 1
  798.  
  799.  
  800. The actual unpacked data that resides in memory consists 2 seperate
  801. sections.
  802.  
  803. 1. The control structure: contains x size, y size, x offset, y offset,
  804.    segment of bit mapped data, number of bits per pixel and number of
  805.    additional bit planes. this information is kept in pcpaint's data segment.
  806.  
  807. 2. The actual bit mapped data: contains the actual page image, mapped from
  808.    bottom left (so bottom scan line is first). The data is contiguous within
  809.    each bit plane, so scan line 1 follows scan line 0 directly. the page
  810.    can and does cross segment boundires (a bit plane can be larger than
  811.    64k). each bit plane follows the previous but starts on a paragraph
  812.    boundary, the printer driver will be passed the offset in paragraphs
  813.    between bit planes and the number of additional planes.
  814.    The bit planes start with bit 0, each additional plane is the next bit.
  815.  
  816.  
  817.