Path: isy!liuida!sunic!dkuug!diku!zonker
From: zonker@diku.dk (Claus Engdahl)
Newsgroups: comp.os.msdos.programmer
Subject: .GL composer/decomposer (src. + bin).
Summary: .gl composer/decomposer bin+src+ description of graspfiles format.
Keywords: gl grasp pic
Message-ID: <1991Jan29.124943.11440@odin.diku.dk>
Date: 29 Jan 91 12:49:43 GMT
Sender: news@odin.diku.dk (Netnews System)
Organization: Department of Computer Science, U of Copenhagen
Lines: 636

Hi.

This article contains:

 1. A description of the format of the grasp files. Posted by George
    Philips to comp.graphics (and then later reposted to
    alt.sex.pictures.d).

 2. A program to compose/decompose .GL files, originally posted by
    Stephen R. van den Berg in alt.sex.pictures .


PS I think the description of the .PIC file headers is missing a few
bytes (however I cannot remember where).


Claus (zonker@diku.dk)
=======================================================================

The formats of GRASP animation files.
By George Phillips <phillips@cs.ubc.ca>
Distribute this freely, but give credit where credit is due, eh?
Version: Jan. 19,1991

GRASP is an animation system particular to the IBM PC world.  It consists
of a program to create animations and a run-time environment for
displaying them.  The most common form these animations take is ".GL"
archives which may be displayed on an IBM-PC with a program called
GRASPRT.EXE.  This document describes what I have been able to
decipher about the format of ".GL" archives and the files contained
within.  It should be useful to those attempting to write ".GL"
animation players on other platforms.

A ".GL" file is simply an archive file which contains images, fonts
and a command file which tells GRASPRT what to do.  These various
files have standard extensions to denote their contents:

.txt - A command file; usually there is only one of these per archive.
.pic - An image.
.clp - An image but without a colour map.
.set or .fnt - A font containing character glyphs.

It should be noted that the GL archive is of no particular importance;
all the archived files could exist as ordinary files and the animation
should still work.  Any GL player should be able to operate both from
an archive or from ordinary files.


File Formats

Most of the data in GL files can be adequately described as a stream
of bytes which is practically universally understood.  Some fields
contain 2-byte and 4-byte integers.  I'll refer to these as "words"
and "long words" and they are all stored in little-endian format.
So if we have 4 consecutive bytes, b1, b2, b3 and b4, the word
at b1 is (b1 + b2 * 256) and the long word at b1 is
(b1 + b2 * 256 + b3 * 256 * 256 + b4 * 256 * 256 * 256).

Since this information was gathered by example, the purpose of some
header fields and commands may not be known.  I've marked unknown
fields with question marks and have tried to put question marks and
other warnings about descriptions which are guesses.


GL Archives (.gl)

A GL archive begins with a directory listing the files in the archive
which is followed by the data for each file.

+-- Directory Header
| dir length	(word)		number of bytes in the directory header
| +-- File Entry (17 bytes per, (dir length) / 17 of them)
| | offset	(long word)	Position of file data as an offset from
| |				the beginning of the archive
| | name	(13 bytes)	File name, null padded.
| +--
+--- File data area
| +-- File Data
| | length	(long word)	Size of the file
| | data	(bytes)		the file's data (surprise!)
| +--
+---

Font Files (.fnt or .set)

These are very simple; first a short header describing the size of the
characters in the font and what byte values correspond to each glyph
followed by the glyph data.

+-- Font Header
| length	(word)		length of the entire font file
| size		(byte)		number of glyphs in the font file
| first		(byte)		byte value represented by the first glyph
| width		(byte)		width of each glyph in pixels
| height	(byte)		height of each glyph in pixels
| glyphsize	(byte)		number of bytes to encode each glyph
+-- Glyph Data
| glyph first
| glyph first + 1
| ...
| glyph first + size - 2
| glyph first + size - 1
+--

Each glyph is stored almost exactly as you would expect a raw PBM file to
contain it except that a '0' bit means black and a '1' bit means white.
In other words, row major order, each line padded to end on a byte
boundary, most significant bit is leftmost.


Image Formats (.pic and .clp)

These consist of a header containing the usual image information followed
by blocked, run-length encoded image data.

+-- Image Header (17 or 19 bytes)
| magic?	(byte)		magic number?  Always is 0x34 or 0x12
| width		(word)		width of image in pixels
| height	(word)		heigh of image in pixels
| ????		(4 bytes)	unknown
| bpp		(byte)		bits per pixel (only seen 1 or 8)
| type		(byte)		image type, either 'L' or 'C'
| flags		(byte)		if (flags & 4) then image has colourmap
| ?		(byte)		unknown
| extend	(byte)		extended header byte (if != 0, header
|				has 2 more bytes) 1/2?
| ?		(byte)		unknown
| ??		(2 bytes)	header extension if extend != 0
+-- Colour Map ((1 << bpp) * 3 bytes, only if flags & 4 == 4)
| +-- Colour Map entries (as many as indicated by bpp)
| | R		(byte)		red intensity, 0 - 63   \
| | G		(byte)		green intensity, 0 - 63  + entry 0
| | B		(byte)		blue intensity, 0 - 63  /
| +--
| ...
+-- Image Data
| blocks	(word)		number of blocks of data
| +-- Data Block (blocks of them)
| | length	(word)		length of data block, including header
| | bufsize	(word)		buffer size needed to hold all the
| |				uncompressed data in this block
| | esc		(byte)		the escape code in this block
| | data	(length - 5 byte)	run-length encoded data
| +--
+--

The run-length encoding is byte oriented and follows these rules:

- characters other than "esc" (see data block header) are literal
- esc n c means repeat c n times (1 <= n <= 255)
- esc 0 len(word) c means repeat c len times

If bpp=1, then the resulting data stream is interpreted as it is
with font glyphs (i.e., msb is left, pad to bytes, row first, etc).
If bpp=8, then each byte in the data stream is an index into the
colour map.  If no colour map is available, the map to use can
only be discovered by running through the command file.

I've only seen images with bpp=1 and bpp=8 and they it always works
out that either bpp=1 and type=C or bpp=8 and type=L.  The type=C
corresponds to CGA graphics which are mostly monochrome and 640 x 200
(so the aspect ratio is funny).  Type=L is colour graphics, prob. VGA
and usually 320 x 200.  Notice that the colour maps have only 6
bits, the same as VGA's digital to analog converters.  ".pic" files
always have colour maps, ".clp" files never do.  It seems that
you can be lazy with your run-length decoding code; I've never seen
a full sequence appear across a data-block boundary (encoders should
probably not let that happen).  The amount of uncompressed data
in a block never seems to exceed 8192 bytes.

Much of the header information is mysterious.  Note that the header
extension field is a guess and that there are other consistent
possibilities (e.g., the extension field is a length byte or even
part of a length word).  Only type=C images seem to have the
extension.  Maybe the extra information is supposed to be used
in video mode operating system calls on the PC?

What made this part easier was the existence of a PC-based program which
converts ".pic" files into GIF files.  Its called "cvt2gif" and can
be found on wuarchive.wustl.edu:/mirrors/msdos/gif/cvt2gif.zip.  Those
wishing to enhance the format descriptions would do well to get a
copy.  I did notice that bpp=1 images are not necessarily black and white
but could be black and some other colour as selected from the CGA
pallette.  I doubt the distinction will make much difference to the
animation, but if you really want to do it right...


Command File (.txt)

The command file looks like a typical script file with the lines delimited
by carriage returns, line feeds or both.  Any text following ';' on a line
is a comment.  Text followed by a colon is used to indicate a label
(much like most assemblers).  Commands consist of a keyword followed by a
list of comma separated arguments.  The input is case-insensitive except
for arguments containing text to display (which are in double quotes).

The basis of the command language seems to be what I call picture and
clip registers, of which there are 16 of each.  A few commands will
load a picture (or clip) from a file into a register.  Other commands
then reference the register numbers to display the pictures or get
colour maps from them.  It seems that the colour map from a picture
(.pic) is installed into the hardware and this is where the
colour maps for the clips (.clp) come from.  I assume that I am missing
a lot of commands, but most notably I believe there should be
more primitive drawing commands.

Many of the commands seem to have a delay argument associated with
them.  This seems reasonable as control over time in an animation
is important.  I may have been over-zealous in looking for delays.
The actual time units of the delays is unknown.  They are typically
numbers < 100, so milliseconds are a likely candidate.  Hundredths
of a second are possible as well.

Here is a list of commands.  Optional arguments are enclosed in [].
Ranges are possible in arguments (I've only seem them in fly) and
take the form "n,-,m", (e.g., fly 0,0,10,10,1,1,1,-,16).

* box x1,y1,x2,y2,colour?
Draw a box with corners (x1, y1) and (x2, y2) in the colour given by
the colourmap entry number.

* cfade x,y,delay,img,[,?,?]
Display a clip image img at (x, y) and wait for delay time units before
proceeding.

* cfree n
Free up any memory associated with clip register n.

* clearscr
Clear the display (to the currently selected colour or black?).

* cload name,num[,?]
Load a clip image "name" into clip register num.  If name does not
have a .clp extension, it will be automatically appended.

* color n
Set the current colour to n.  This at least seems to affect the
text displaying commands.

* exit
Terminate the command file.

* fload name
Load the named font which becomes the font to be used when displaying
text.  ".fnt" is appended to name if necessary.

* float x1,y1,x2,y2,step?,delay?,num
Move the clip image (num) by displaying it at (x1,y1) and erasing it
and displaying it every step pixels until (x2,y2).  Delay delay time
units in between steps.  Or maybe something completely different,
but the x1,y1,x2,y2 and num arguments are probably coordinates and
a clip number.

* fly x1,y1,x2,y2,step?,delay?,clip list
Successively display the clip images from (x1,y1) to (x2,y2) with delay
time units in-between.  The clip list is just a bunch of clip numbers
separated by commas (i.e., fly is varags).  A range is likely to
appear in the clip list.  Often (x1,y1) == (x2,y2).

* fstyle ?[,?]
Presumably set up some parameters on how a font is displayed.

* goto label
Force flow of control to the given label.

* loop
Denotes the end of a mark loop.  Continues the loop at the most recent
mark if the loop hasn't finished.

* mark n
This pairs with the loop command and begins a for loop from 1 to n.
One assumes that the interaction of mark, loop and goto is the same
as for, next and goto in BASIC.  That is, loops are dynamically
scoped and you can jump in and out of them.  Mark simply pushes
a loop start onto the stack and loop examines whatever is on
the top of the loop stack.

* mode ?
Modify the current video mode in some way.  I haven't seen this often.

* note freq,delay?,duration

Play a musical note of the given frequency and duration and delay for
delay time units afterward.

* pallette n
Make the colour map from picture register n be the one to use.  This probably
installs it into the hardware so that when a clip is loaded there is
no colour map to change.

* pfade effect,pict[,delay?[,?,?]]
Display the picture numbered pict on the screen.  The effect number
indicates what sort of special effect is used to display it.  What
the numbers mean I have no idea, but I know some of the effects.
Each pixel loaded randomly, every even line then every odd line
and so on.  The delay parameter seems to make sense, but not always.
The extra parameters could be those needed for some effects.  Often
they are large numbers.

* pfree n
Free up any memory associated with picture register n.

* pload name,n
Load picture "name" into picture register n.  ".pic" is appended to
name if necessary.

* putup x,y,n
Display clip register n at (x,y).

* set retrace [on|off]
Set is probably a general internal control variable changing command.
What retrace is I have no idea, but it was set off then on around
a fly statement.

* spread ?,?
Who knows, but the numbers used are probably picture register numbers.
Maybe some kind of colourmap changing?

* text x,y,"text",[delay?]
Display the given text (enclosed in double quotes) at (x,y).  The
extra parameter is probably a display, but it could be the display
colour or the background colour.  Probably the display colour is
that given by the color statement.

* tran [on 0|off]
No idea.  Was used around some cload and float statements.

* video mode
Set the display mode to 'C' or 'L' (remember the image format types?).
Usually the first statement in a command file.  C almost certainly
refers to CGA which is 640 x 200 monochrome and L almost certainly
to VGA which (in their case) is 320 x 200 x 256.

* waitkey [[delay[,label]]
Wait up to delay units for the user to press a key (or forever if no
delay time is given).  If the user presses a key and the label
argument is present, transfer control to that label.

* window x1,y1,x2,y2,?
Some kind of display control.  Probably a clipping window with appropriate
coordinate translation (i.e., (0,0) becomes (x1,y1)).



This document was created by looking hard at a number of GL files,
using cvt2gif to help decipher the image file format and looking
at 1 or 2 animations on an RS-6000 running a PC emulator and using
grasprt.  cvt2gif was very useful; grasprt under the PC emulator
was painfully slow at times and didn't help my understanding
much.  I've never even gotten close to a copy of the program for
creating and editing GL files.

If you find out more about GL files, send me the changes so I can
extend this document.  Feel free to include this as supplementary
documentation if you write a GL player.  Finally, here are some
projects which could help find out more about GL files:

- Get cvt2gif and feed it small variations on .pic files to decipher
the meaning of the missing header fields.  I may do this.

- Alter control files on some animations and see what effects they
have.  Something easy would be to change the effect number on
pfade statements (if that's what it is).  I don't have the hardware
to do this.

- Look at the GRASP animation package and intuit what the commands
mean by what control you have over generating animations.  This is
probably the easiest way to get information.  I don't have GRASP,
I don't know where to get it and I don't has a PC good enough to
run it on.


================================================================
Path: freja.diku.dk!dkuug!sunic!mcsun!unido!rwthinf!cip-s03!berg
~From: berg@cip-s03.informatik.rwth-aachen.de (AKA Solitair)
~Newsgroups: alt.sex.pictures
~Subject: .gl file composer/decomposer source & executable
Message-ID: <3674@rwthinf.UUCP>
~Date: 8 Nov 90 11:45:01 GMT
~Sender: news@rwthinf.UUCP
~Reply-To: berg%cip-s01.informatik.rwth-aachen.de@unido.bitnet
~Lines: 246

This is one of those quick, dirty and portable programs :-).

To give those people who want to create .gl files on their own or write
an interpreter on a different machine than the pc a helping hand: here
is a .gl file composer/decomposer.  It extracts the separate files which
are in an .gl archive, or can create a new archive from the files you supply.

I have included the source and an executable (for the pc) in the posting.
Both are provided as is, no warranties or support from my side can be
expected.  Both are donated to the public domain.  So feel free to sell the
program :-)

As I'm not supporting this program anymore, there really is no need to contact
me (in case any problems arise, check with your local C guru :-).
Should you however have an uncontrollable urge to write me some mail,
then please use the mail address mentioned in the signature (*NOT* the address
in the From: line).

--
Sincerely,                 


       berg%cip-s01.informatik.rwth-aachen.de@unido.bitnet

           Stephen R. van den Berg.
"I code it in 5 min, optimize it in 90 min, because it's so well optimized:
it runs in only 5 min.  Actually, most of the time I optimize programs."
--------------------- cut here ---------------------------------------


--
Claus Engdahl (zonker@diku.dk, postmaster@diku.dk, staff@diku.dk,,,,,)
----------------------------------------------------------------------
My motto is: Honi soit qui pense  ;-)
