
search for ++-- to get to the start of each doc...

++---------------------------------------------------------------------

                                     G R A S P

                         GRAphical System for Presentation

                           Another USEware product from:

                             Microtex Industries, Inc.
                            2091 Business Center Drive
                                Irvine, Ca.  92715
                                  (714) 476-0777

                    (714) 545-8100 - PCPaint Picture Swap Line

        Current release number: 1.10*           Current release date :05/86


                             GRASP - Table of Contents
                             =========================

         Overview of Product . . . . . . . . . . . . . . . . . . . . .    1

              What is GRASP? . . . . . . . . . . . . . . . . . . . . .    3
              What is on the GRASP disk? . . . . . . . . . . . . . . .    4
              Making a working copy of the GRASP disk  . . . . . . . .    6
              Installing GRASP . . . . . . . . . . . . . . . . . . . .    7
              GRASP Installation Diagram . . . . . . . . . . . . . . .    8
              How do I use GRASP?  . . . . . . . . . . . . . . . . . .    9
              Running GRASP  . . . . . . . . . . . . . . . . . . . . .   10
              The Grasp Editor . . . . . . . . . . . . . . . . . . . .   12
              Simple GRASP Tutorial  . . . . . . . . . . . . . . . . .   15
              Running the library file version - GRASPRT . . . . . . .   18
              Using the GRASP Graphics Librarian - GLIB  . . . . . . .   19

         The commands of GRASP - Detailed  . . . . . . . . . . . . . .   21

              BOX  . . . . . . . . . . . . . . . . . . . . . . . . . .   23
              CFADE  . . . . . . . . . . . . . . . . . . . . . . . . .   24
              CFREE  . . . . . . . . . . . . . . . . . . . . . . . . .   25
              CHGCOLOR . . . . . . . . . . . . . . . . . . . . . . . .   26
              CIRCLE . . . . . . . . . . . . . . . . . . . . . . . . .   27
              CLEARSCR . . . . . . . . . . . . . . . . . . . . . . . .   28
              CLOAD  . . . . . . . . . . . . . . . . . . . . . . . . .   29
              COLOR  . . . . . . . . . . . . . . . . . . . . . . . . .   30
              EXEC . . . . . . . . . . . . . . . . . . . . . . . . . .   31
              EXIT . . . . . . . . . . . . . . . . . . . . . . . . . .   32
              FFREE  . . . . . . . . . . . . . . . . . . . . . . . . .   33
              FGAPS  . . . . . . . . . . . . . . . . . . . . . . . . .   34
              FLOAD  . . . . . . . . . . . . . . . . . . . . . . . . .   35
              FLOAT  . . . . . . . . . . . . . . . . . . . . . . . . .   36
              FLY  . . . . . . . . . . . . . . . . . . . . . . . . . .   37
              FSTYLE . . . . . . . . . . . . . . . . . . . . . . . . .   38
              GOSUB  . . . . . . . . . . . . . . . . . . . . . . . . .   39
              GOTO . . . . . . . . . . . . . . . . . . . . . . . . . .   40
              IFKEY  . . . . . . . . . . . . . . . . . . . . . . . . .   41
              LINE   . . . . . . . . . . . . . . . . . . . . . . . . .   42
              LINK . . . . . . . . . . . . . . . . . . . . . . . . . .   43
              LOOP . . . . . . . . . . . . . . . . . . . . . . . . . .   44
              MARK . . . . . . . . . . . . . . . . . . . . . . . . . .   45
              MODE . . . . . . . . . . . . . . . . . . . . . . . . . .   46
              NOISE  . . . . . . . . . . . . . . . . . . . . . . . . .   48
              OFFSET . . . . . . . . . . . . . . . . . . . . . . . . .   49
              PALETTE  . . . . . . . . . . . . . . . . . . . . . . . .   50
              PAN  . . . . . . . . . . . . . . . . . . . . . . . . . .   51
              PFADE  . . . . . . . . . . . . . . . . . . . . . . . . .   52
              PFREE  . . . . . . . . . . . . . . . . . . . . . . . . .   53
              PLOAD  . . . . . . . . . . . . . . . . . . . . . . . . .   54
              POINT  . . . . . . . . . . . . . . . . . . . . . . . . .   55
              PUTUP  . . . . . . . . . . . . . . . . . . . . . . . . .   56
              RESETSCR . . . . . . . . . . . . . . . . . . . . . . . .   57
              RETURN . . . . . . . . . . . . . . . . . . . . . . . . .   58
              SETCOLOR . . . . . . . . . . . . . . . . . . . . . . . .   59
              TEXT . . . . . . . . . . . . . . . . . . . . . . . . . .   60
              TRAN . . . . . . . . . . . . . . . . . . . . . . . . . .   61
              VIDEO  . . . . . . . . . . . . . . . . . . . . . . . . .   62
              WAITKEY  . . . . . . . . . . . . . . . . . . . . . . . .   64
              WINDOW . . . . . . . . . . . . . . . . . . . . . . . . .   65

         Tips, Hints, Examples and Demo Programs . . . . . . . . . . .   67

              Example Program #1 - Slide Show  . . . . . . . . . . . .   69
              Example Program #2 - How to animate using FLY  . . . . .   70

         APPENDIX A - Command Summary  . . . . . . . . . . . . . . . .   71

         APPENDIX B - Fade Table . . . . . . . . . . . . . . . . . . .   73

         APPENDIX C - Error Messages . . . . . . . . . . . . . . . . .   75

         APPENDIX D - Picture Swap Line  . . . . . . . . . . . . . . .   79

         APPENDIX E - GRASP Order Form . . . . . . . . . . . . . . . .   81


                                Overview of Product

                                  What is GRASP?

        GRASP is a simple graphics programming pseudo-language which can be
        used to create and run animated graphics demonstrations, tutorials,
        and  presentations  on  an  IBM  PC/XT/AT or respective compatible.
        GRASP requires that the user make use of  some other  tool, such as
        Mouse Systems'  PCPAINT PLUS, to create PCPAINT PLUS packed page or
        BSAVE format pictures, or 'capture' screens from any other graphics
        software with  the provided  capture utility  program. This product
        was developed by the folks at  Microtex Industries,  the authors of
        PCPAINT PLUS, so it is patterned to take advantage of the pictures,
        clippings and fonts  created  with  PCPAINT  PLUS  and  its related
        utilities, like FONTASIA and ARTOOLS.


        Features:

        * Supports IBM CGA, IBM EGA, HERCULES, AST ColorGraphPlus,
          Plantronics, AST Preview, 3 text modes.

        * 16 Picture Buffers

        * 128 Clipping Buffers

        * Single command to control animation sequences

        * 25 different fades with limitless combinations

        * Simple ASCII file format

        * FONTRIX(tm) font compatible

        * Fully PCPAINT PLUS from MOUSE SYSTEMS(tm) compatible

        * Run Custom Programs from within GRASP program


                           What is on the GRASP disk?


        The following files are on the GRASP disk

        GRASP.EXE -

        This is  the main  GRASP program.   This  version of GRASP gets the
        pictures, character sets, clippings  and text  files it  needs from
        the current  directory on your current disk drive, unless otherwise
        specified in  the text  files. This  program allows  you to create,
        edit and execute your GRASP programs.

        GRASPRT.EXE - 

        This is  the run-time  version of GRASP. This version of GRASP gets
        the pictures, character sets,  clippings, and text it needs  from a
        graphics library  created with  the GRASP  graphics librarian GLIB.
        This version only allows you to execute completed programs that are
        in library  form. No  editing of  the files  is possible. This .EXE
        file, along with your .GL file, may be  distributed without license
        fees or other compensation.

        GLIB.COM - 

        Library    manager  for  version  GRASPRT  of GRASP product. Allows
        management of all necessary files in  a library  environment rather
        than as files in a subdirectory on a disk. 

        WHATPIC.EXE - 

        Utility program to determine size and color combinations of PCPAINT
        PLUS pictures.

        WHATCLP.EXE - 

        Utility program to determine size and color combinations of PCPAINT
        PLUS clippings.

        CAP.COM -

        Capture Program  for capturing  screens and clippings from all your
        favorite software.

        STENCIL.SET -
        OLDTIME.SET -
        ROMAN.SET   -
        PIGFONT.SET -
        DOTTIE.SET  -

        Some fonts for you to use in your demo.  

        ED1.HLP     -
        CM1.HLP     -
        CM2.HLP     -
        CM3.HLP     -
        FD1.HLP     -
        FD2.HLP     -
        RP1.HLP     -

        Various help files.

                      Making a working copy of the GRASP disk


        The GRASP disk is not copy protected in any way. You should back up
        the disk  using the DOS diskcopy command, or you may perform a file
        by file backup to a hard disk using the DOS copy command. There are
        several different  ways to  copy disks under DOS, but the following
        will  work  on  almost  any  hardware  configuration  since  all it
        requires is access to the DOS master disk and 1 floppy disk drive.

        For PCs with 1 or 2 floppys, or an XT or AT with 1 floppy:

        Put your  DOS master  disk in  drive A  and turn  on the machine or
        press CTRL-ALT-DEL to re-boot the system.  Enter the  Date and Time
        when prompted and you should see the system prompt:

        A>_

        Type:

        A>DISKCOPY A: A:

        and press  the return  key. You  will be prompted to put the SOURCE
        disk in drive A. Remove the DOS master disk from  drive A,  put the
        GRASP distribution  disk in,  close the  door and  press the return
        key. After it reads some information, DOS will  ask you  to put the
        TARGET disk in drive A. Put a blank disk (formatted or unformatted)
        into drive A, close the door and press return. If  your machine has
        less than  512K of memory, you may be prompted to perform this disk
        exchange several times. When the process is complete, put the GRASP
        disk away in a safe place and use the backup copy for your work.


                                 Installing GRASP


        Simple Set-Up
        -------------

        To  develop  demos  under  the  grasp  system, you need to have the
        following GRASP files and programs accessible:

        GRASP.EXE
        CM1.HLP
        CM2.HLP
        ED1.HLP
        FD1.HLP
        FD2.HLP
        RP1.HLP

        as well as your pictures, clippings and fonts.

        With all of these files in  one subdirectory,  you will  be able to
        create and  edit your  demo program and have access to the help. If
        you do not need the help files, you may omit them. If you are going
        to be  creating a  library version of your demo, you will also need
        access to the librarian utility, GLIB.EXE. 



        Advanced Set-Up
        ---------------

        The following is an example of a well set-up system on a hard disk,
        including PCPAINT,  so that you can edit pictures and clippings and
        create your demo with a minimum of effort.

        From the root directory, create a sub-directory called PAINTLIB and
        put all  the PCPAINT  files in  it. (This is the recommended method
        for installing PCPAINT). In addition, be  sure your  PATH statement
        points to  PAINTLIB and  set up an environment variable to point to
        PAINTLIB as well with the command:

        SET PAINTLIB=C:\PAINTLIB

        Also make a sub-directory off the root called GRASP. Copy the GRASP
        disk contents  to the  sub-directory GRASP. Add the GRASP directory
        to your PATH command. Then create a DEMO  directory, change  to it,
        and run  GRASP by  typing GRASP at the command prompt. When you are
        in the GRASP editor, you can  run PCPAINT  by pressing  ALT-F10 and
        your previous  PATH and  SET statements will help DOS know where to
        find it. The following diagram is an example:

                            GRASP Installation Diagram


        This diagram  shows the  proper structure  for your sub-directories
        for GRASP  to perform  in the  above stated  manner. This  is not a
        requirement, just an example.
                                       
                                   ___________
                                  |           |
                                  |  C:\Root  |
                                  |___________|
                ________________________|________________________ . . . .
         ______|_______    ______|______    __________|__________    
        |              |  |             |  |                     |
        |   PAINTLIB   |  |    GRASP    |  |    DOS or OTHER     |
        |______________|  |_____________|  |_____________________|   
            :                  :      |          : 
        PCPAINT.EXE        GRASP.EXE  |      DOS files
        PxPAINT.OVR        ED1.HLP    |      Various batch files 
        CAP.COM            CM1.HLP    |
                           CM2.HLP    | 
                           CM3.HLP    |
                           FD1.HLP    |
                           FD2.HLP    |
                           RP1.HLP    |
                                      |
                           ___________|_ 
                          |             | 
                          |    Demos    |
                          |_____________|

        Then these statements would be in your AUTOEXEC.BAT file:

        SET PAINTLIB=C:\PAINTLIB
        PATH C:\PAINTLIB;C:\GRASP;C:\whateverelseyouwant...

        With this  set-up, you  can be  in any  directory and  run GRASP by
        typing GRASP and PCPAINT by typing PCPAINT. You have full access to
        all help files and the  PCPAINT  system.  The  auto-run  feature in
        GRASP (ALT-F10)  allows you to run PCPAINT while in GRASP. It looks
        for PCPAINT in the \PAINTLIB directory.  The  GRASP help  files are
        only accessible if they are in one of three places:

        1) In the current directory
        2) In the directory pointed to by the environment string 'PAINTLIB'
        3) In a sub-directory off the root called 'GRASP'

        GRASP performs  a search  for the help files in this order. If they
        are not found, a message  will  appear  when  you  first  run grasp
        telling you so. You may run GRASP without access to the help files,
        but you will get a beep if you try to access them.

                                How do I use GRASP?


        To use GRASP you need to do 3 things.


        1) Create the pictures and clippings you want  to use  with PCPAINT
        PLUS, or capture them the the CAP utility.

        2) Use the built-in GRASP editor to create an GRASP 'program' which
        is nothing more than a list of GRASP commands and some comments.

        3) Run your demonstration  by pressing  F10 from  the editor  or by
        selecting EXECUTE FILE from the main GRASP menu.


        It's that  simple. If you want to give your demo away, you must put
        the .PIC, .CLP, .SET and .TXT  files into  a library  with the GLIB
        utility, and distribute the library file with GRASPRT.EXE.


                                   Running GRASP

        To run the GRASP, enter at the command prompt:

        A:>GRASP

        You will be presented with a screen that looks something like this:

                                     G R A S P
                         GRAphical System for Presentation
                             Version 1.10* - May, 1986
                  Copyright (C) 1986 - Microtex Industries, Inc.

                                    Edit File      
                                    Execute File   
                                    Load File      
                                    Save File      
                                    Quit GRASP     

                               Current File: TMPFILE

        To select  an option from this menu, use the up and down arrow keys
        until the option you want to select is highlighted. Then just press
        return  and  the  option  is  selected. Each of these options has a
        special meaning to GRASP.

        Edit File: The Edit File option tells GRASP that you want to  go to
        the editor and create or modify your GRASP program file.

        Execute File:  The Execute  File option  tells GRASP to execute the
        currently loaded GRASP program file.

        Load File: The Load File option allows you to tell GRASP to load in
        an existing  file, or  to create  a new one. Notice that just below
        the menu there is an area  with the  current filename  listed. When
        you  first  run  GRASP,  the  system  will  default to a file named
        TMPFILE. This is the name that GRASP will use unless  you specify a
        new one.  To specify  a new one, just type in the name you want. DO
        NOT specify  the filename  extension. GRASP  will automatically use
        the extension  .TXT for you. To create a new file, just perform the
        load as though the  file you  want already  exists. GRASP  is smart
        enough to  understand and  create a  new file for you. If a file is
        already loaded, and changes have been  made, GRASP  will prompt you
        for saving before allowing you to load another. This keeps you from
        trashing your current file.

        Save File: The Save File option tells GRASP that you want to save
        the current working GRASP program file. It works  much the  same as
        the load  command. Just  specify the name you want to save the file
        under and press return. The  system  will  default  to  the current
        working name.

        Quit GRASP: The Quit GRASP option tells the system that you want to
        exit GRASP. If a file is loaded and has been changed since the last
        save, GRASP will prompt you for saving before allowing you to quit.

        Be sure to save your file before quitting!


        Of these  options, the only one that requires special consideration
        is the first one, Edit File. Select that  option and  let's explore
        the world of the GRASP editor...
                                 The Grasp Editor


        If you  have selected  the Edit File option from the main menu, you
        will now be in the GRASP editor. The screen should have a blue line
        across the top that looks like the following:


        TMPFILE         COL:1     LINE:1     POS:0     LEN:0      INSERT ON

        These are  just information  items about  the current  file you are
        working on and the mode you are operating in. Starting  at the left
        is the  name of  the current  file, which defaults to TMPFILE. Next
        comes the current cursor column  number,  the  current  cursor line
        number,  the  current  cursor's  character position relative to the
        entire file, and the total  number  of  characters  in  the current
        file.  At  the  far  right  is  the  status  of the INS key on your
        keyboard. If INSERT mode is ON,  then characters  you type  will be
        inserted before  the character  just to the right of the cursor. If
        INSERT mode is OFF, then characters to the right of the cursor will
        be overwritten.  This second  mode, INSERT  OFF, is commonly called
        OVERSTRIKE mode. This information is just there for  reference, and
        with the  exception of  the INSERT  mode signal, you probably won't
        need to refer to it too often.

        The first three function keys are the most important keys  to learn
        in  the  GRASP  editor.  GRASP  provides  'Quick  Help'  for  three
        different areas and is accessable by pressing F1, F2 or F3. 

        NOTE: If you press one of these function keys and  hear a  low tone
        from  your  computer  and  no  help  appears,  it  means that GRASP
        couldn't find the .HLP files that  were on  your distribution disk.
        If you  want to use the help. the .HLP files must be on the current
        drive and directory, in a directory called 'GRASP' directly off the
        root directory,  or in  a directory  pointed to  by the environment
        string 'PAINTLIB'. See INSTALLING GRASP for more details.

        F1 - Provides help in using the GRASP Editor. This  includes a list
        of the  most commonly  used editing  keys and a description of what
        each function key is used for.

        F2 - Provides  a  quick  summary  listing  of  all  available GRASP
        commands.  This  information  is  not  a  complete reference on the
        commands of GRASP, but  rather a  command syntax  reference so that
        you  can   insure  proper  useage  of  the  commands  and  a  brief
        description of what the command is used for. 

        F3 - Provides a  summary listing  of the  25 GRASP  fades and their
        respective  numbers.  Remember  that  all  fades  can  be  used for
        graphics  pictures,  text  pictures,  pictures  in   a  window  and
        clippings.

        If this  is your  first time  running GRASP and you are too lazy or
        too bored  to  read  the  entire  manual,  you  should  find enough
        information in these help keys to get you started.

        If you want to learn a little more about the editor, here is a full
        description of all the keys available in the GRASP editor.

        F1  - Quick help with the editor.
        F2  - Quick help with the commands.
        F3  - Quick help with the fades and video modes.
        F4  - Start/End highlighting a block.
        F5  - Copy a highlighted block.
        F6  - Move a highlighted block.
        F7  - Read a block in from disk.
        F8  - Write a highlighted block to disk.
        F9  - Save current file and run from current line.
        F10 - Save current file and run from the top.

        ALT/F1   - Quick exit to DOS. Typing EXIT at the DOS propmt returns
                   you to the GRASP editor.

        ALT/F10  - Run  PCPAINT  from  within the GRASP editor. PCPAINT.EXE
                   and  its  overlays  must  be  in  a  subdirectory called
                   PAINTLIB off the root directory on the current drive.

        CTRL-K-X or
        ESC      - Quit the  editor. Do  not save file. Leave flag set that
                   indicates changes if they have been made. 

        CTRL-K-Q - Quit  the  editor.  Do  not  save  file.  Reset  flag to
                   indicate no changes have been made.

        CTRL-K-D or
        ALT/X    - Quit the editor, save file if changes have been made.

        CTRL-K-S or
        ALT/S or
        ALT/W    - Save the current file and continue editing.

        ALT/L or
        ALT/R    - Reload   the   current   file   and   continue  editing,
                   overwriting any changes made.

        CTRL-Y or
        ALT/D    - Delete current line.

        CTRL-N   - Insert a carriage return  and  leave  cursor  at current
                   line.

        CTRL-K-B - Mark block beginnng. Same as the first time you hit F4.

        CTRL-K-K - Mark block end. Same as the second time you hit F4.

        CTRL-Q-B - Go to block beginning.

        CTRL-Q-K - Go to block end.

        CTRL-K-C - Copy a block. Same as F5.

        CTRL-K-V - Move a block. Same as F6.

        CTRL-K-R - Read block at cursor position. Same as F7.

        CTRL-K-W - Write block. Same as F8.

        CTRL-K-Y - Delete highlighted block. 

        CTRL-HOME or
        CTRL-Q-R - Go to top of file.

        CTRL-END or
        CTRL-Q-C - Go to end of file.

        CTRL-RIGHT ARROW or
        CTRL-F   - Skip word right.

        CTRL-LEFT ARROW or
        CTRL-A   - Skip word left.

        CTRL-Q-S or
        HOME     - Go to beginning of line.

        CTRL-Q-D or
        END      - Go to end of line.

        INS      - Turns insert mode on and off.

        DEL      - Deletes character under cursor and adjusts text.

        ARROW  KEYS  /  PGUP  / PGDN and Wordstar(tm) 'Diamond' equivalents
        move cursor around document.

        Now that you know how to use the editor, let's  see exactly  how to
        make a demo...

                               Simple GRASP Tutorial

        Loading and displaying a picture:

        It  is  important  to  understand  that  GRASP  is very much a LINE
        oriented programming pseudo-language.  It  is  called  this because
        inter-line  dependencies  have  been  kept to a minimum. In simpler
        terms, GRASP interprets one line at a time, executes it,  then goes
        and  gets  the  next  line.  Except  for  a few special cases, what
        happens on each line is relatively independent of the previous line
        or the next line. This is important because if you understand this,
        then creating a GRASP  program  will  be  easier  to  understand in
        concept.

        Each line can start with only one of three things:

        1) A GRASP command. (PRESS F2 to see all the GRASP commands)

        2) A semicolon - ';'. This indicates the beginning of a comment.

        3) A  label. This  can be any continuous string of ASCII characters
        with the exception of space, and must be followed by a colon - ':'.

        This keeps  the GRASP  interpreter's job  simple. It  either sees a
        command,  and  immediately  looks  for  possible  parameters,  or a
        semicolon, in which case  it ignores  the rest  of that  line, or a
        label, which it puts into a list so it can find it later if needed.
        Any  variation  from  these  three  options  will  result  in GRASP
        thinking that what you typed was  a GRASP  command which  it cannot
        understand, and results in an 'INVALID COMMAND IN LINE XXX' message
        when you try to execute the program.

        Usually, you will want to start you GRASP  program with  a comment,
        like a title of your program or your name, etc. Type:

        ; DEMO Program for GRASP

        and press return. You now have written a 1-line GRASP program. 

        Exciting huh? I'll bet you can't wait for more.

        The very  first command  in every  GRASP program  should be a VIDEO
        command which tells GRASP which video mode you want to  use. If you
        select a  video mode  that is not available on your computer, GRASP
        will try to understand and tell you so.  If you  get wierd results,
        or  the  screen  seems  to  go  crazy,  don't worry, just check the
        reference section of this manual to be sure  you are  using a valid
        video mode.  For this  tutorial, we  will assume that your computer
        has an IBM Color Graphics Adapter  or compatible,  and we  will use
        the standard 4 color 320x200 mode, which GRASP understands as video
        mode A. Type the  following (exactly  as spelled  below, with upper
        case):


        ; DEMO Program for GRASP
        ;
        video Q

        Now press F10 to execute the program. (By the way, all this does is
        set the video mode and come  back to  the editor.  Not too exciting
        yet, but we're getting there...)

        You should get a message that says

                           Illegal argument(s) at line 3
                                 File TMPFILE.TXT
                             Press any Key to Continue

        Any time you see the message, it means that the command you entered
        was correct, but one of the arguments you entered was incorrect.
        Press a key and you will  be returned  back to  the editor,  to the
        line where  the error  occured. The  problem here  is that  Q is an
        invalid video mode. Change it to A (which stands for  CGA 320x200 4
        color mode)  and press  F10 again. Your screen should blink and the
        you will be put back in the editor.  

        Now we have named the program and set up a video mode, so it's time
        to try  out some  graphics commands.  On the distribution disk is a
        picture named  GRASP.PIC.  This  is  a  4  color  picture  from the
        CGADEMO.GL file.  Let's load  it into  GRASP and display it using a
        variety of fades.

        ; DEMO Program for GRASP
        ;
        video A
        ;
        pload grasp,1                    ; load picture into buffer #1
        pfade 0,1,0,0                    ; fade it to the screen using fade
                                         ;  #0
        waitkey                           ; wait for a keypress before     
                                         ;  returning to the editor.

        now, press F10 and you should see the GRASP.PIC picture  loaded and
        displayed. 

        Change  the  first  parameter  of  the  pfade command to any number
        between 0 and 25 and watch all the different special  effects. Then
        to slow  things down, try a number like 50 for the third parameter,
        which is the speed of the fade. Speed  seems to  have no  effect on
        some fades,  while on others, it makes a lot of difference. This is
        because of the nature of  each  individual  fade.  To  optimize the
        performance of GRASP, it was decided that speed would be a relative
        number, that is, relative to the actual fade.  This way,  each fade
        may be accurately controlled from its fastest speed to its slowest.

        Let's do one more command, the  WINDOW command.  Window means don't
        allow  any  part  of  the  picture  that lies outside of a specific
        rectangle to be faded to the screen. Add the window command to your
        demo program as follows:

        ; DEMO Program for GRASP
        ;
        video A
        ;
        pload grasp,1                    ; load picture into buffer #1
        window 0,0,100,100               ; set fade clip window
        pfade 0,1,0,0                    ; fade it to the screen using fade
                                         ;  #0
        waitkey                          ; wait for a keypress before
                                         ;  returning to the editor.

        now press F10 and watch the  difference. You  should see  that only
        the lower  left part  of your picture was actually dissolved to the
        screen. Change the coordinates of the window command  and watch the
        results.

        One  other  note:  The  window  command  can  only  operate on byte
        boundaries. For most video modes, this means every 8 pixels  in the
        x  direction.   You  don't   have  to  worry  because  WINDOW  will
        automatically adjust itself to a byte boundary.
          
        This concludes this lesson.  Other  commands  in  GRASP  work  in a
        similar fashion.  Experiment with them. Just remember to keep track
        of your video modes and buffers.  You may  also want  to take apart
        the demo program, CGADEMO.GL using the GLIB.EXE utility and look at
        the code for more examples.


                    Running the library file version - GRASPRT


        The Library file, or runtime version of the program is identical to
        the  text  file  version  except  that  the  interpreter  gets  its
        information from  a library  file instead  of the  current disk and
        directory. The  GLIB utility  will put all of your .PIC, .CLP, .SET
        and .TXT files into a library  with the  extension GL.  To run your
        demo execute the command:

        GRASPRT <libfile> <textfile>

        If  the  textfile  is  omitted  from  the  command line, GRASP will
        execute the first text file it finds in the library.

        To run the demo that comes with GRASP, type:

        GRASPRT CGADEMO

                     Using the GRASP Graphics Librarian - GLIB

        The Graphics LIBrarian, GLIB.EXE, is used in the following manner:

        GLIB [-dstuea] libname [files...]  

        where the following commands are supported:

         -d   delete file from library
         -s   extended file list
         -t   quick file list
         -u   update (add) file to library
         -e   extract file from library
         -a   extract all files from library

        For example, if you  wanted to  put all  of the  .PIC files  in the
        current directory into a library file named MYFILE, you would type:

        GLIB -u MYFILE *.PIC

        Or if you wanted to extract GRASP.PIC from the library CGADEMO, you
        would type:

        GLIB -e CGADEMO GRASP.PIC

        Be  sure that all files  needed for  your demo  are in  the library
        file  before  you  try  to  run  it.  Otherwise,  you may get error
        messages.

        NOTE:
        You cannot use  wild  cards  for  extracting  or  deleting  in this
        version (1.0)  of GLIB.  However, you may use wild cards for adding
        to or updating the library.

        More Examples:

        GLIB -d DEMO FRED.TXT

        will delete the file 'fred.txt' from library file DEMO.GL

        GLIB -e DEMO LOGO.CLP

        will extract the clipping 'logo.clp' from library file DEMO.GL

        GLIB -u DEMO MTX.CLP

        will add/replace the picture 'mtx.pic' to library file DEMO.GL




                         The commands of GRASP - Detailed


BOX                                                            BOX


        Summary:
        -------

        BOX allows you to draw a box on the screen  in the  current drawing
        color.


        Syntax:
        ------

        BOX startx, starty, endx, endy, <width>

        where 'startx'  and 'starty'  is the point of one corner of the box
        and 'endx' and endy'  is the  point of  the opposite  corner of the
        box. Width  is the  number of  pixels wide  you want the box to be.
        Width is drawn 'inward' from the original box. 


        Example:
        -------

        BOX 0,0,100,100

        will draw a box in the  current  drawing  color  from  x=0,  y=0 to
        x=100, y=100.


        Comments:
        --------

        Transparent mode  does not affect this command. Default width is 1.
        BOX is not available in text modes.

CFADE                                                        CFADE


        Summary:
        -------

        CFADE allows you to dissolve or fade a clipping to  the screen. You
        may specify  one of several dissolves, the speed for that dissolve,
        and a delay after the dissolve. This command  is similar  to PFADE,
        but applies  to clippings. The same 25 fades that apply to pictures
        also apply to clippings.


        Syntax:
        ------

        CFADE fade number, x, y, <buffer number>, <speed>, <delay>

        where 'fade  number' is  the number  of the  fade you  want to use,
        'buffer number'  is the  clipping buffer  number where the clipping
        you want to fade has been loaded, 'x' and 'y' are the  location for
        the clipping  to be  faded, 'speed'  is the  speed of  the fade and
        'delay' is the time to wait after the  delay. Speed  can be  in the
        range 0-10000. Check Appendix B for a list of fades.


        Example:
        -------

        CFADE 2,20,40,5,500,1000

        will fade  the clipping  in buffer 5 using fade 2 at location x=24,
        y=40 at speed 500, and then  wait 10  seconds. The  delay works the
        same as using the WAITKEY command. 


        Comments:
        --------

        Note: CFADE only fades byte-width clippings and puts them up at the
        nearest byte boundary to the x  and  y  specified  in  the command.
        Deviations may cause unpredictable results. Use the utility WHATCLP
        to obtain the needed  information  about  your  clippings.  If your
        clipping  is  not  byte-width,  it  will  fill  the  right  edge to
        byte-width with white (highest  color available).  Transparent mode
        does NOT apply to CFADE. 

        Default values for optional parameters:

        buffer number: 1
        speed:         0
        delay:         0


CFREE                                                        CFREE


        Summary:
        -------

        CFREE is  used to free-up a clipping buffer. Sometimes, you may run
        out of memory and need to clear up  some buffers  you have  full of
        clippings you have already used.


        Syntax:
        ------

        CFREE buf1, <buf2>, <buf3>...

        where 'buf1' and other buffers are buffers you want to free-up.


        Example:
        -------

        CFREE 1,4,12

        will free-up clipping buffers 1, 4 and 12.

        CFREE 1,-,16

        will free-up buffers 1 through 16. You MUST use commas or spaces to
        separate these parameters.


        Comments:
        --------

        This is especially useful in  EGA  16  color  mode  where  space is
        critical.


CHGCOLOR                                                  CHGCOLOR


        Summary:
        -------

        Chgcolor is  used to  set the color palette registers in IBM EGA 16
        color mode. On the  EGA, there  are 16  possible colors,  called an
        'index', and  each of  these color  indices may  be one of 64 color
        'values'.


        Syntax:
        ------

        CHGCOLOR color index, color value,...

        where 'color index' refers to the color number  you want  to change
        in the range 0-15 and 'color value' lies in the range 0-63.


        Example:
        -------

        CHGCOLOR 3,32

        will change color index 3 to color value 32.


        Comments:
        --------

        Remember, this only works in EGA 16 color modes.


CIRCLE                                                      CIRCLE


        Summary:
        -------

        CIRCLE allows  you to draw a circle or ellipse on the screen in the
        current drawing color. The  color parameters  must be  specified in
        pairs, as in the example.


        Syntax:
        ------

        CIRCLE centerx, centery, xradius, <yradius>

        where 'centerx'  and 'centery' is the center point of the circle or
        ellipse, xradius' is the radius in the x-direction and 'yradius' is
        the radius in the y direction.


        Example:
        -------

        CIRCLE 100,100,100,20

        will draw a circle centered at x=100, y=100 with x radius=100 and y
        radius=20.


        Comments:
        --------

        Transparent mode does not affect this command. Failure to specify a
        yradius assumes yradius=xradius and a circle is produced. Note also
        that circle  here implies  xradius=yradius which,  depending on the
        aspect  ratio  of  your  current  video  mode, may not be a circle.
        CIRCLE is not available in text modes.


CLEARSCR                                                  CLEARSCR


        Summary:
        -------

        Clearscr is used to clear the screen to the current drawing color.


        Syntax:
        ------

        CLEARSCR


        Example:
        -------

        CLEARSCR

        will clear the screen to the current drawing  color (the  color set
        with the last COLOR command).


        Comments:
        --------


CLOAD                                                        CLOAD


        Summary:
        -------

        This command  is used  to load  a clipping into a buffer. There are
        128 buffers available for  clippings in  GRASP. It  is advised, for
        memory  reasons,  that  the  user  try  to  manage  using as few as
        possible. A clipping must be loaded into a buffer before  it can be
        dissolved or put up onto the screen.


        Syntax:
        ------

        CLOAD clipping, buffer number, <shiftparm>

        where 'clipping'  is the name of the clipping you want to load (the
        file name extension is optional) and 'buffer number'  is the number
        of the  buffer you  want to  load in to. Valid buffer numbers are 1
        through 128. Buffer 0 is non-existent  for clippings,  and thus, no
        clipping may  be loaded  into it.  'Shiftparm' indicates whether or
        not to create the  shifted copies  necessary to  place clippings at
        non-byte boundaries. Default for shiftparm is 0 or YES. Placing a 1
        here will cause GRASP  not to  create the  shifted copies  and thus
        saving memory.  This is useful if you know that you are going to be
        using CFADE on this clipping and therefore couldn't use the shifted
        copies anyway.


        Example:
        -------

        CLOAD myclip,5

        will load the clipping myclip.clp into clipping buffer number 5.


        Comments:
        --------

        If you  do not understand the concept of shifted copies, it is best
        not to fool around with the shiftparm parameter.  Note also  that a
        file extension  is not  necessary in  your GRASP file. Drive letter
        and path may be specified.


COLOR                                                        COLOR


        Summary:
        -------

        COLOR allows you to choose a drawing color.  Drawing color  is used
        for  drawing  primitives  (such  as  line,  box, circle, or point),
        transparent mode selection, text  strings and  clearing the screen.
        Secondary color is used for background color in text mode or shadow
        color for font styles in graphics modes.


        Syntax:
        ------

        COLOR n1,<n2>

        where 'n1' is the drawing color and 'n2' is the secondary color.


        Example:
        -------

        COLOR 3,0

        will set the current  drawing color  to color  3 and  the secondary
        color to 0.


        Comments:
        --------

        Related  commands  are  LINE,  BOX,  CIRCLE, POINT, TRAN, CLEARSCR,
        PALETTE, MODE and PFADE. The secondary color is used for the bottom
        character in  shadow text strings and the background color for text
        screens. Secondary color defaults to color 0 if not specified.


EXEC                                                          EXEC


        Summary:
        -------
        This command allows you to execute another program from within your
        GRASP program.  Useful for utility programs, or custom programs you
        write that provide a function that GRASP does not.


        Syntax:
        ------

        EXEC program, <parameters>

        where 'program' is the name of the program you wish to execute. You
        MUST include  path if  it is  in a  different path, and all program
        names must include the extension. 'Parameters' are any command line
        parameters you would normally pass to the program.


        Example:
        -------

        EXEC \PAINTLIB\PCPAINT.EXE, /O

        will execute  pcpaint from  the \paintlib  directory on the current
        drive passing the /O parameter.


        Comments:
        --------

        You MUST include full path and file extension.


EXIT                                                          EXIT


        Summary:
        --------

        Exit will  cause the  currently running  GRASP program  to quit and
        return to DOS or the GRASP editor.


        Syntax:
        ------

        EXIT


        Example:
        -------

        EXIT

        will  cause  the  currently  running GRASP program to terminate and
        return to DOS or the GRASP editor.


        Comments:
        --------

        If you are running  GRASPRT, EXIT  returns you  to DOS.  If you are
        running GRASP,  EXIT returns  you to  the editor  or the main menu,
        depending on how you ran the program.



FFREE                                                        FFREE


        Summary:
        -------

        This command will free up the font buffer  so that  more memory may
        be available for pictures and clippings.


        Syntax:
        ------

        FFREE


        Example:
        -------

        FFREE

        will free up the font buffer.


        Comments:
        --------


FGAPS                                                        FGAPS


        Summary:
        -------

        This command  allows you  to set the gaps between characters in the
        text command and also the width of the space character.


        Syntax:
        ------

        FGAPS <char gap, space gap>

        where 'char gap is the  number  of  pixels  between  characters and
        'space gap' is the number of pixels wide for the space character.


        Example:
        -------

        FGAPS 3,9

        will  set  the  inter-character  gap  to  3  pixels  and  the space
        character to a width of 9 pixels.


        Comments:
        --------

        Note that this has no effect on the TEXT command if you are in TEXT
        mode. FGAPS  with no parameters resets the gaps to the default gaps
        for the currently loaded font.


FLOAD                                                        FLOAD


        Summary:
        -------

        This command is used to load in a  character set.  The GRASP system
        only allows  1 character set in memory at a time. After a character
        set has been loaded,  TEXT  commands  (see  command  TEXT)  will be
        performed using the currently loaded font. Applies only to graphics
        modes.


        Syntax:
        ------

        FLOAD fontname

        where 'fontname'  is the  name of  the FONTRIX(tm)  or PCPAINT font
        file you wish to load. File name extensions are optional.


        Example:
        -------

        FLOAD bocklin

        will load  the FONTRIX(tm)  font bocklin.set into memory for use by
        the TEXT command.


        Comments:
        --------

        When a font is loaded with FLOAD, the gaps are reset to the default
        gaps  for  that  font.  So  be  sure  to reset gaps using the FGAPS
        command if the default gaps aren't adequate. 


FLOAT                                                        FLOAT


        Summary:
        -------

        FLOAT allows you to  animate  a  clipping  or  series  of clippings
        between any two points on the screen with one command. It
        is similar  to FLY  except that it performs an exchange with screen
        data so that the background may be preserved. 

        Syntax:
        ------

        FLOAT startx, starty, endx,  endy, increment,  delay, clip1, clip2,
        ...clipn

        where 'startx' and 'starty' indicate the starting point, 'endx' and
        'endy' indicate  the  ending  point,  'increment'  is  the distance
        between each  put along  the line, 'delay' is the wait time between
        each put and 'clip1-clipn' is the list of clippings. 


        Example:
        -------

        FLOAT 0,0,200,200,2,10,1,2,3

        will 'FLOAT' the clippings 1,2 and  3   in that  order from  0,0 to
        200,200, skipping  2 pixels between each put, waiting a count of 10
        between each put. For example, clip 1 will  be put  at 0,0,  clip 2
        will be  put at  clip 2,2, clip 3 will be put a 4,4, clip 1 will be
        put at 6,6, clip2 will be put at 8,8, etc.


        Comments:
        --------

        This command differs from FLY in that it  preserves the background.
        Also note  that the  last operation  it performs  is the swap-back,
        which restores screen data. This means that if  you want  to have a
        clipping on  the screen after the FLOAT command, you have to follow
        the FLOAT with a  PUTUP command.  Selective use  of transparent can
        yield very interesting results.



FLY                                                            FLY


        Summary:
        -------

        FLY allows you to animate a clipping or series of clippings between
        any two points on the screen with one command.


        Syntax:
        ------

        FLY startx, starty, endx,  endy,  increment,  delay,  clip1, clip2,
        ...clipn

        where 'startx' and 'starty' indicate the starting point, 'endx' and
        'endy' indicate  the  ending  point,  'increment'  is  the distance
        between each  put along  the line, 'delay' is the wait time between
        each put and  'clip1-clipn'  is  the  list  of  clippings.  You may
        animate up to 10 clippings.


        Example:
        -------

        FLY 0,0,200,200,2,10,1,2,3

        will  'fly'  the  clippings  1,2  and  3  in that order from 0,0 to
        200,200, skipping 2 pixels between each put, waiting a count  of 10
        between each  put. For  example, clip  1 will be put at 0,0, clip 2
        will be put at clip 2,2, clip 3 will be put a  4,4, clip  1 will be
        put at 6,6, clip2 will be put at 8,8, etc.


        Comments:
        --------
         
        Selective use  of slightly larger than necessary clippings (to wipe
        out  the    previous  put)  and  transparent  mode  can  yield very
        interesting results.


FSTYLE                                                       FSTYLE


        Summary:
        -------

        This command allows you to choose a style for the characters in the
        TEXT command. Styles are as follows:

        style #    style
        -------    -----
           0       Default, normal letters
           1       Bold up.
           2       Bold right.
           3       Shadow up right.
           4       Shadow up left.
           5       Shadow up right 2 pixels.
           6       Shadow up left 2 pixels.


        Syntax:
        ------

        FSTYLE fstyle

        where fstyle is the number of the desired style.


        Example:
        -------

        FSTYLE 4

        will set the text style to shadow up left.


        Comments:
        --------
        Use of the command with no parameters will default to style 0.


GOSUB                                                        GOSUB


        Summary:
        -------

        This command allows the transfer of  control during  execution of a
        GRASP program  to a  sub-program defined  elsewhere in the program.
        This is similar to a BASIC gosub command. The subprogram is defined
        by a  label at the beginning, and a RETURN command at the end. When
        the  RETURN  is  encountered,  control  is  returned  to  the  line
        following the line where the GOSUB ocurred.


        Syntax:
        ------

        GOSUB subroutine

        where 'subroutine'  is a sub-program defined elsewhere in the GRASP
        program.


        Example:
        -------

        GOSUB myprog

        will transfer control to  the  sub-program  'myprog'.  Control will
        return when the statement RETURN in encountered in the sub-program.


        Comments:
        --------

        Also see command RETURN.


GOTO                                                          GOTO


        Summary:
        -------

        This command  allows you  to transfer control of a GRASP program to
        another portion of the program,  similar  to  the  same  command in
        BASIC. You  must first  define a  label at the point you want to go
        to. Labels are defined  as any  string of  less than  16 characters
        terminated by a colon (:).


        Syntax:
        ------

        GOTO label

        where 'label' is defined somewhere else in the program.


        Example:
        -------

        GOTO here

        will  transfer  control  to  the  line which begins with the string
        'here:'. There may only be one  label of  a particular  name in one
        GRASP program. 


        Comments:
        --------

        You may have up to 512 labels in a GRASP program.  


IFKEY                                                        IFKEY


        Summary:
        -------

        IFKEY allows  conditional branching by means of an implied goto. If
        the key indicated in  the  command  matches  the  last  key pressed
        during a waitkey command, branching occurs.


        Syntax:
        ------

        IFKEY key label

        where  key  is  the  key  code  to  compare to and label is a label
        defined elsewhere in the program.


        Example:
        -------

        IFKEY 1 part1

        means that if, during  the last  waitkey command,  the '1'  key was
        pressed, goto label "PART1".


        Comments:
        --------

        LINE                                                          LINE


        Summary:
        -------

        LINE allows  you to draw a single pixel width line on the screen in
        the current drawing color.


        Syntax:
        ------

        LINE startx, starty, endx, endy

        where 'startx' and 'starty' is the location for the first  point in
        the line  and 'endx'  and 'endy' is the location for the last point
        in the line.


        Example:
        -------

        LINE 0,0,100,100

        will draw a line in the  current drawing  color from   x=0,  y=0 to
        x=100, y=100.


        Comments:
        --------

        Transparent  mode  does  not  affect  this  command.  LINE  is  not
        available in text modes.


LINK                                                          LINK


        Summary:
        -------

        This command is used to link to another  text command  file. IF you
        wish  to  have  several  special effects, and for editing purposes,
        keep them is separate ASCII files, you may  link them  during GRASP
        run time with this command.


        Syntax:
        ------

        LINK txtfile

        where  'txtfile'  is  the  name  of  the  command  file you wish to
        execute. File  name  extensions  are  not  required,  but  all text
        command files must have an extension of txt.


        Example:
        -------

        LINK race

        will  link  to  the  text  command  file  'race.txt'  and  continue
        executing.


        Comments:
        --------

        Since this command requires  interpretation of  the command itself,
        the loading  of a  new file,  and the  interpretation of the second
        file, it has a tendency to slow things down. It is recommended that
        all  commands  be  put  into  one file before giving a presentation
        using GRASP. This command is useful  during development,  or if you
        have stored  several effects  from previous demonstrations and want
        to link them together.


LOOP                                                          LOOP


        Summary:
        -------

        This command causes the  GRASP  interpreter  to  loop  back  to the
        previous mark.  This will  happen n number of times, where n is the
        number specified in the previous MARK command.


        Syntax:
        ------

        LOOP


        Example:
        -------

        LOOP

        will loop to previous mark.


        Comments:
        --------

        MARK/LOOP pairs may be nested up to 16 levels deep.


MARK                                                         MARK


        Summary:
        -------

        This command is used to mark a position which will be the  top of a
        loop. Coupled  with the LOOP command, MARK allows you to repeat the
        same steps in your GRASP command file a specified number of times.


        Syntax:
        ------

        MARK xxx

        where 'xxx' is the number of times you  wish to  loop back  to this
        mark.


        Example:
        -------

        MARK 10

        will  place  a  mark  at  this  point  so that the next time a LOOP
        command is encountered, the program will  loop back  to this point.
        This process will occur ten times.


        Comments:
        --------

        MARK/LOOP pairs  may be  nested up  to 16  levels deep. The maximum
        number of times you can loop is 65535.


MODE                                                          MODE


        Summary:
        -------

        Mode is used in IBM CGA 4 color mode and IBM CGA 2 color mode only.
        It is used to set the palette and border color in these modes. 


        Syntax:
        ------

        MODE border color, palette

        where 'border  color' refers  to the  background color in IBM CGA 4
        color mode and foreground color in  IBM CGA  2 color  mode. 'Border
        color' can  be in  the range  0-15. Palette  affects only IBM CGA 4
        color mode and is in the range 0-5.  Refer to  the following tables
        for specifics.


        Border                                 Color Table
        Color    Color       Palette   1            2              3
        -----    -----       ------- -----------------------------------
          0      Black          0    Green        Red             Brown
          1      Blue           1    Cyan         Magenta         White
          2      Green          2    Cyan         Red             White
          3      Cyan           3    Bright Green Bright Red      Yellow
          4      Red            4    Bright Cyan  Bright Magenta  White
          5      Magenta        5    Bright Cyan  Bright Red      White
          6      Brown       -------------------------------------------
          7      Grey 
          8      Dark Grey (Bright Black)
          9      Bright Blue
         10      Bright Green
         11      Bright Cyan
         12      Bright Red
         13      Bright Magenta
         14      Yellow (Bright Brown)
         15      White (Bright Grey)


        In  the  above  Palette  table,  color  0 is the currently selected
        Border Color.
          

        Example:
        -------

        Mode 1,4

        will yield the following: (Assuming  we  are  in  IBM  CGA  4 color
        mode), border color is blue (Drawing Color 0), and the palette will
        be bright cyan, bright magenta, and white. (Drawing  colors 1,2 and
        3, respectively)  in IBM CGA 4 color mode. In IBM CGA 2 color mode,
        The foreground color will be blue.


        Comments:
        --------

        This command was intended for use only in IBM CGA  4 color  and IBM
        CGA 2  color modes.  Use in  any other  mode may result in an error
        message. 



NOISE                                                        NOISE


        Summary:
        -------

        NOISE allows you to make music in GRASP. By specifying starting and
        ending  frequencies,  as  well  as  a duration, you can make single
        notes, or complex sounds.


        Syntax:
        ------

        NOISE startfreq, endfreq, duration

        where 'startfreq' and 'startfreq' are the  starting frequencies for
        the noise and 'duration' is the overall length of the noise.


        Example:
        -------

        NOISE 440,440,100

        will play the note with a frequency 440 for duration 100.


        Comments:
        --------



OFFSET                                                      OFFSET


        Summary:
        -------

        The  OFFSET  command  allows  you  to  treat  coordinates  in other
        commands  (like  putup,  line,  box,  cfade,  etc...)  as  relative
        coordinates rather than absolute. If the OFFSET is set to 0,0, then
        the coordinates you enter in the other commands are relative to the
        screen as  a whole  which appears  to be  absolute. This command is
        used when you want to repeat a series of operations  but don't want
        to have  to alter  all the  coordinates in order to use a different
        region of the screen.


        Syntax:
        ------

        OFFSET x,y

        where 'x' and 'y' are the x and y offset values.


        Example:
        -------

        OFFSET 40,32

        will set the offset to x=40, y=32. This  means that  if you specify
        that you want a line drawn from 0,0 to 10,10, it will actually draw
        it from 40,32 to 50,42. In other words, the offset values are added
        to the coordinate data you type in the command.


        Comments:
        --------

PALETTE                                                    PALETTE


        Summary:
        -------

        Palette is used to set the current palette to that of the specified
        picture which has been loaded  into  a  buffer.  This  sets  the 16
        colors  out  of  64  on  EGA  16 color modes and the border-palette
        combination of CGA 4 color mode.


        Syntax:
        ------

        PALETTE buffer number

        Where 'buffer number' is the number  of  the  buffer  in  which the
        picture resides.


        Example:
        -------

        PALETTE 2

        will set  the current  palette to  the palette used for the picture
        which was loaded into buffer 2 with the PLOAD command.


        Comments:
        --------

        This command was intended for use in EGA  16 color  mode and  CGA 4
        color  mode  only.  Use  in  other  modes  may  cause unpredictable
        results. Use with caution.

PAN                                                           PAN


        Summary:
        -------

        This command allows you  to  perform  a  hardware  pan  if  you are
        operating in  one of  the EGA modes. If the picture you want to pan
        around on is larger than a screen then  the following  rules apply:
        1) You  MUST use  PFADE number 0 to put up the picture, 2) when you
        are finished panning and scrolling,  you  MUST  PFREE  the picture,
        clear the screen with CLEARSCR, then do a RESETSCR before using any
        other pictures. This is so that the EGA will be able to  keep track
        of which  picture you  are using  and how to best display it. Also,
        sequences  of  PAN  commands  should  always  return  you   to  the
        coordinate 0,0  when you  are done. Think of the picture as being a
        very large screen with the upper left corner  being coordinate 0,0.
        Pan  then  allows  you  to  change  upper  left  corner  to  be any
        coordinate in the valid coordinate space.


        Syntax:
        ------

        PAN x0,y0,x1,y1,buffer

        where 'x0', 'y0' is the starting  coordinate for  panning and 'x1',
        'y1' is  the ending coordinate. 'Buffer' is the picture buffer that
        the command will look into to get real picture coordinates  and set
        the EGA display modes to coincide to.


        Example:
        -------

        PAN 0,0,100,100,1
        PAN 100,100,0,0,1

        will smoothly  pan the screen diagonally from the upper left corner
        to 100,100 and back again.


        Comments:
        --------

        This is a complicated command  and  requires  some  thought  to use
        effectively. Be careful.

        CAUTION: It is imperative that you free the oversize picture buffer
        BEFORE you perform the CLEARSCR and RESETSCR functions! 


PFADE                                                        PFADE

        Summary:
        -------

        Pfade is the heart of GRASP. It allows you to dissolve a picture to
        the screen. You may specify one of several dissolves, the speed for
        that dissolve, and a delay after the dissolve.


        Syntax:
        ------

        PFADE fade number, buffer number, speed, delay

        where 'fade  number' is  the number  of the  fade you  want to use,
        'buffer number'  is the picture buffer number where the picture you
        want to fade has been loaded, 'speed' is the speed of the  fade and
        'delay' is  the time  to wait  after the delay. Speed can be in the
        range 0-10000. Check Appendix B for a list of fades.


        Example:
        -------

        PFADE 12,1,500,1000

        will fade the picture in buffer 1 using  fade 12  at speed  500 and
        then  wait  1000.  The  delay  works  the same as using the WAITKEY
        command. 


        Comments:
        --------

        The first 25 fades in GRASP are the same in all video  modes. Fades
        beyond  25  may  be  mode  specific  and must be used with caution.
        Specifying buffer 0 will  cause a  blank screen  of current drawing
        color to  be generated  and faded  to the  screen. Transparent mode
        does NOT apply to PFADE.


PFREE                                                        PFREE


        Summary:
        -------

        PFREE is used to free-up a picture buffer.  Sometimes, you  may run
        out of  memory and  need to  clear up some buffers you have full of
        pictures you have already used.


        Syntax:
        ------

        PFREE buf1, buf2, buf3...

        where 'buf1' and other buffers are buffers you want to free-up.


        Example:
        -------

        PFREE 1,2

        will free-up picture buffers 1 and 2.


        Comments:
        --------

        This is especially useful in  EGA  16  color  mode  where  space is
        critical.


PLOAD                                                        PLOAD

        Summary:
        -------

        This command is used to load a picture into a buffer. There are  16
        buffers available for pictures in GRASP. It is  advised, for memory
        reasons,  that  the  user  try  to  manage using only one buffer. A
        picture must be loaded  into a  buffer before  it can  be dissolved
        onto the screen.


        Syntax:
        ------

        PLOAD picture,buffer number

        where 'picture'  is the  name of  the picture you want to load (the
        file name extension is optional) and 'buffer number'  is the number
        of the  buffer you  want to  load in to. Valid buffer numbers are 1
        through 16. Buffer 0 is a dummy buffer  used for  solid color wipes
        and changes, and thus, no picture may be loaded into it.


        Example:
        -------

        PLOAD mypic,1

        will load the picture myfile.pic into picture buffer number 1.


        Comments:
        --------


POINT                                                        POINT


        Summary:
        -------

        POINT  allows  you  to  draw  a  single  pixel on the screen in the
        current drawing  color. If  a second  point is  indicated, a random
        point  is  drawn  in  the  rectangular  region  defined  by  the  4
        coordinates.


        Syntax:
        ------

        POINT startx, starty, <endx, endy>

        where 'startx' and 'starty'  is  the  location  for  the  point and
        'endx' and 'endy' define the region for randomization.


        Example:
        -------

        POINT 50,50

        will draw a point in the current drawing color at x=50, y=50.

        POINT 100,100,150,150

        will draw a random point in the region defined by 100,100,150,150.


        Comments:
        --------
         
        Transparent mode does not affect this command.


PUTUP                                                        PUTUP


        Summary:
        -------

        PUTUP  allows  you  to  place  a  clipping  on the screen. PUTUP is
        similar to CFADE 0, but allows  placement at  any x  and y location
        and supports transparent mode.


        Syntax:
        ------

        PUTUP x ,y, <buffer number>, <delay>

        where 'x'  and 'y'  are the location where the lower left corner of
        the clipping will be placed, 'buffer number' is the clipping buffer
        number where  the clipping  you want to put up resides and delay is
        the time to wait after the putup in hundredths of a second.


        Example:
        -------

        PUTUP 25,50,1,1000

        will put the clipping in buffer 1 up  on the  screen at  x=25, y=50
        and then wait for time 1000 (10 seconds). Remember that the x and y
        coordinates correspond to the  current video  mode. Exceeding these
        coordinates may result in an error message.


        Comments:
        --------

        Also see CFREE.


RESETSCR                                                   RESETSCR


        Summary:
        -------

        This command  is used  to reset  the virtual screen back to display
        screen size after a PAN command with a larger-than-screen picture.


        Syntax:
        ------

        RESETSCR


        Example:
        -------

        RESETSCR 

        will reset the virtual screen image.


        Comments:
        --------

        Works only with EGA modes and PAN command.


RETURN                                                       RETURN


        Summary:
        -------

        This command causes execution  of the  current sub-program  to halt
        and return control to the calling program.


        Syntax:
        ------

        RETURN


        Example:
        -------

        RETURN

        will return control to calling program.


        Comments:
        --------

        Also see command GOSUB.



SETCOLOR                                                  SETCOLOR


        Summary:
        -------

        Setcolor is  used to  set the color palette registers in IBM EGA 16
        color modes. On the EGA, there  are 16  possible colors,  called an
        'index', and  each of  these color  indices may  be one of 64 color
        'values'. SETCOLOR differs from CHGCOLOR in that SETCOLOR  sets all
        16  color  indices  at  once.  This  is  faster  and  is useful for
        animation effects.


        Syntax:
        ------

        SETCOLOR color value 1, color value 2, ... color value 16

        where 'color value n' lies in the range 0-63.


        Example:
        -------

        SETCOLOR 3,32,23,53,12,11,10,21,35,2,4,8,30,40,61,63

        will set the current  palette  registers  to  the  16  color values
        specified.


        Comments:
        --------

        Remember, this  only works  in EGA  16 color  modes and requires an
        Enhanced Color Display (ECD).


TEXT                                                          TEXT


        Summary:
        -------

        TEXT allows you to put-up a string of text in the font  loaded with
        FLOAD in the current drawing color.


        Syntax:
        ------

        TEXT x, y, string, <delay>

        where 'x'  and 'y'  is the location of the lower left corner of the
        first character in the string, 'string' is the string to put up and
        'delay' is  the time  to wait  after the  put-up in hundredths of a
        second.


        Example:
        -------

        TEXT 4,4,"This is a text string..."

        will put the string indicated between  the quotes  up at  x=4, y=4,
        using the current drawing color.


        Comments:
        --------

        The string to be put must be in double quotes.


TRAN                                                          TRAN


        Summary:
        -------

        TRAN allows  you to  set transparent mode on or off, and to specify
        which colors to  make  transparent.  This  is  used  for overlaying
        objects or floating objects across complex backgrounds.


        Syntax:
        ------

        TRAN on/off, color1, color2,...colorn

        where 'on/off'  specifies whether  you want transparent mode turned
        on or off and color1-colorn indicate which colors you want  to make
        transparent. Color1-colorn  may have the values 0 to maxcolor where
        maxcolor is the highest  color  number  available  in  your current
        video mode.


        Example:
        -------

        TRAN on 2,14

        will  turn  transparent  mode  on  and  make  the  colors  2 and 14
        transparent.

        TRAN off

        will turn transparent mode off.


        Comments:
        --------

        If you turn transparent mode on and off, the next time you  turn it
        on, you  must re-specify  which colors  you want to be transparent.
        Transparent does not work in EGA 16 color modes.


VIDEO                                                        VIDEO


        Summary:
        -------

        Video is used to set the video mode. Video should  be used   at the
        beginning  of  the  GRASP  text  file.  Video  modes may be changed
        during  the  demo, but caution is advised. Damage may be  done to a
        monitor if  the wrong  video mode is requested for your system. The
        default video mode is A, (see table below).


        Syntax:
        ------

        VIDEO vidmode

        where 'vidmode' is one of the following...

                    Maximum       Picture         Memory
        Vidmode    Resolution   # of Colors     Requirement
        --------------------------------------------------------
           0         40x25          16         2K (IBM 40 column text)
           1         80x25          16         4K (IBM 80 column text)
           2         80x25          2          4K (IBM 80 column text)
           A        320x200         4         16K (IBM CGA)
           B        320x200         16        32K (IBM PCjr/STB)
           C        640x200         2         16K (IBM CGA)
           D        640x200       16/64       64K (IBM EGA)
           E        640x350         2         32K (IBM EGA monochrome)
           F        640x350         4         64K (IBM EGA)
           G        640x350       16/64      128K (IBM EGA)
           H        720x348         2         32K (Hercules monochrome)
           I        320x200         16        32K (Plantronics/AST CGP)
           J        320x200         16        32K (IBM EGA)

        These modes, (with the exception of  the text  modes) correspond to
        PCPAINT video modes.


        Example:
        -------

        VIDEO G

        Will  set  up  GRASP  to  use  the  high resolution mode of the EGA
        adapter in 16 out of 64 colors.


        Comments:
        --------

        Memory requirement in the table above is the approximate amount  of
        memory required for the buffer to hold EACH picture you load in for
        use. Also, pay attention to the  size of  the screen  in each video
        mode. Attempting  to FADE  pictures other  that this size may yield
        unpredictable results. The exception to this is when  using the PAN
        command on an EGA.



WAITKEY                                                    WAITKEY


        Summary:
        -------

        This command  instructs the  demonstration or presentation to pause
        until a key is pressed, or  until timeout  value, if  specified. If
        timeout occurs, conditional branching is allowed.


        Syntax:
        ------

        WAITKEY <timeout>, <label>

        where 'timeout'  is the  time to wait before timeout in 100ths of a
        second and 'label' is the label to go to if timeout occurs.


        Example:
        -------

        WAITKEY 600,myline

        will wait until a key is pressed, or until delay  of 6  seconds. If
        delay of 6 seconds is reached, goto label 'myline'.


        Comments:
        --------

        If no  timeout is  specified, WAITKEY will wait forever until a key
        is pressed. The key that is pressed to abort the wait is  saved and
        may be tested by IFKEY.


WINDOW                                                       WINDOW


        Summary:
        -------

        This command  is used  to restrict  a picture  fade to a particular
        portion of the screen. The coordinates you pass are in  pixels, but
        they are rounded to the nearest byte, or usually 8 pixels.


        Syntax:
        ------

        WINDOW x,y,x1,y1

        where 'x',  'y', 'x1'  and 'y1'  are the lower left and upper right
        corner of the window to set for clipping.


        Example:
        -------

        WINDOW 40,40,100,160

        will set the fade window to  40,40,100,160. The  PFADE command will
        only fade that portion of the screen that lies in this region.


        Comments:
        --------

        WINDOW has no effect on the CFADE command.



----------------------------------------------------------------------

                      Tips, Hints, Examples and Demo Programs



        Example Program #1 - Slide Show
        -------------------------------

        A simple  slideshow can  be constructed by creating a grasp command
        file as follows:


        ; Slideshow demo for GRASP
        ;
        ; This program will load and display 4 pictures, alternating
        ; between fade #1 and fade #2, waiting for a count of 500 between
        ; each fade.
        ;
         video a             ; set medium res 4 color CGA mode (this can
                             ; be whatever mode you want to use)
        ;
         load pic1           ; load pic1 into buffer 1
         fade 1              ; fade using fade number 1
         waitkey 500         ; wait for a count of 500
        ;
         load pic2           ; load pic2 into buffer 1
         fade 2              ; but use fade #2 this time.
         waitkey 500         ; etc...
        ;
         load pic3
         fade 1
         waitkey 500
        ;
         load pic4
         fade 2
         waitkey 500
        ;
         exit                ; quit the program





        Example Program #2 - How to animate using FLY
        ---------------------------------------------

        Let's say  you have  2 clippings  which are  a flock  of birds with
        wings up and wings down. To fly them across the screen, (from 0,160
        to 300,160 issue the following sequence:


         tran on 3      ; turn transparent mode on
                        ; (this assumes the background is color 3.)
        ;
         cload birds1,1                ; load in first clip
         cload birds2,2                ; load in second clip
         fly 0,160,300,160,3,4,1,2     ; fly 'em!
        ;
         tran off       ; turn off transparent mode

        The parameters  in the  fly command  are x1,y1,x2,y2,step(number of
        pixels between each putup),delay(time of delay between each putup),
        and list of clippings, in this case, 1 and 2.


----------------------------------------------------------------------

        APPENDIX A - Command Summary


        Notes:
        -----

        Each  command's  arguments  (if  any) are  separated by  commas  or
        spaces, whichever is preferable.

        Comments  begin  at  a  semicolon  and continue for the rest of the
        line.

        Line  labels  are  up  to  16  characters  long  and  end   with  a
        colon,i.e.,<label>:.

        Subroutines can be nested up to 16 levels deep.

        There can be up to 16 levels of nesting in MARK,LOOP constructions.

        CAPITAL letters are the command name. It must be spelled correctly,
        but capitals are not required.

        LOWERCASE letters and numbers are parameters. You must  specify all
        required parameters, (those not enclosed in <>), or you will get an
        error message indicating too few parameters.


        Command Summary:
        ---------------
        BOX x,y,x2,y2,<width>                 - draw a box
        CFADE #,x,y,<buffer>,<speed>,<delay>  - fade a clipping to screen
        CFREE buffer,<buffer>,...             - free up clipping buffer(s)
        CHGCOLOR from,to,<from,to>,...        - EGA, change color index
        CIRCLE x,y,rx,<ry>                    - draw an ellipse
        CLEARSCR                              - clear screen
        CLOAD clipping filename,<buffer>      - load a clipping
        COLOR color1,<color2>                 - set color 1 & color 2
        EXEC program,<parameters>             - execute program from GRASP
        EXIT                                  - quit program
        FFREE                                 - free the font buffer
        FGAPS <char_gap, space_gap>           - set text gaps
        FLOAD character set filename          - load a font
        FLOAT xs,ys,xe,ye,step,delay,clp1...  - float clip across screen
        FLY xs,ys,xe,ye,step,delay,clp1...    - fly clip across screen
        FSTYLE style                          - set text style
        GOSUB label                           - execute subroutine
        GOTO label                            - goto label
        IFKEY key,label                       - if key match, goto label
        LINE x,y,x2,y2                        - draw line
        LINK textfile filename                - link to another text file
        LOOP                                  - loop to previous mark
        MARK loop count                       - mark for looping
        MODE border color,<palette>           - CGA border & palette set
        NOISE freq1,freq2,duration            - make some noise
        OFFSET x,y                            - set x and y offsets
        PALETTE buffer                        - EGA mode set palette
        PAN x0,y0,x1,y1,<buffer>              - EGA pan from x0,y0 to x1,y1
        PFADE #,<buffer>,<speed>,<delay>      - fade a picture to screen
        PFREE buffer,<buffer>,...             - free up picture buffer(s)
        PLOAD picture filename,<buffer>       - load a picture
        POINT x,y,<x2,y2>                     - draw a point
        PUTUP x,y,<buffer>,<delay>            - put a clip to screen @ x,y
        RESETSCR                              - reset screen to default
        RETURN                                - return from subroutine
        SETCOLOR c1,c2,c3...c16               - EGA mode set 16 colors
        TEXT x,y,"some text",<delay>          - put up text @ x,y
        TRAN on/off, color                    - transparent mode on/off
        VIDEO vidmode                         - set video mode
        WAITKEY <timeout>, <label>            - wait for a keypress
        WINDOW x0,y0,x1,y1                    - set clip window



        APPENDIX B - Fade Table

        There are 25 fades  in GRASP  which must  be called  by number. All
        fades  work  on  graphics  screens,  graphics  screens in a window,
        clippings  and  text  screens.  This  list  is  also  accessable by
        pressing F3 while in the GRASP editor.

        Fade # Description
        ------ -------------------------------------------------------
          0    Quick snap wipe
          1    Horizontal left to right wipe
          2    Horizontal right to left wipe
          3    Horizontal edge to center wipe
          4    Horizontal center to edge wipe
          5    Horizontal 1 pass filter wipe - both sides simultaneously
          6    Horizontal 2 pass filter wipe - from left, then from right
          7    Horizontal halves wipe - left to right, then right to left
          8    Horizontal halves wipe - left and right simultaneously
          9    Vertical top to bottom wipe
         10    Vertical bottom to top wipe
         11    Vertical edge to center wipe
         12    Vertical center to egde wipe
         13    Vertical filter wipe, top and bottom simultaneously
         14    Vertical halves wipe, top and bottom simultaneously
         15    Vertical halves wipe, left down, right up
         16    Vertical quarters wipe
         17    Vertical fingers wipe
         18    Vertcial fingers/filter combination wipe
         19    Slither from top to bottom
         20    Sparkle fade (random)
         21    Diagonal wipe
         22    Aperature dissolve - edge to center
         23    Aperature dissolve - center to edge
         24    Clockwise clock dissolve
         25    Double slant dissolve



        APPENDIX C - Error Messages

        The following  is a  list of  messages you  may get while executing
        GRASP and some of their causes and solutions.


        MOST COMMON ERRORS:


        I.    The most common error is not  a  grasp  program  error  but a
              system  error.  The  screen  will  clear, and you will get an
              error like

         External Memory allocation overflow, xxxxk requested, yyyyk free.

              This means that you have tried to load a picture  or clipping
              that is  too large  for the  memory you  have left. There are
              several fixes for this problem.
              1) Buy more memory. EGA 16 color demos usually take most of a
              640K machine
              2) Check your code and use PFREE, CFREE and FFREE to clean up
              memory  when  you  are  through  using  particular  pictures,
              clippings and  fonts. See  the section of the manual on these
              commands.
              3) Use the special parameter,  ',1'  on  clipping  loads that
              don't make the shifted copies. In order to be able to PUTUP a
              clipping at any single-pixel coordinate, GRASP  needs to make
              up to  8 shifted  copies of the clipping. If you are going to
              be using CFADE or putting it up at a byte  boundary, then the
              shifted copies aren't necessary. You can keep them from being
              generated by typing:

              CLOAD clip,1,1 ;note the extra ',1'

              If you do specify the extra parameter, and you try  to put up
              the  clipping  at  a  non-byte boundary, no putup will occur.
              Remember, FLY, FLOAT  and  PUTUP  can  put  clippings  at any
              coordinate. CFADE can only putup at a byte boundary.

              If  none  of  the  above  three work, then call the GRASP and
              PCPAINT BBS for more advice.




        II. System Errors

         The following is a list of  the GRASP  system errors  that you may
        encounter. These will appear on the top of the screen while running
        your demo along with a line number where  the error  occurred. When
        you press a key, you will be returned to that line in your program.
        If you get the error while running under  the runtime  version, the
        program will stop.



        DUPLICATE LABEL 

        - You have used the same label name more than once in your demo and
        GRASP is confused.


        ERROR IN LOOP COUNT

         - Loop count must be  a positive  number. This  error occurs  if a
        negative number was specified.


        ERROR IN NAME

         - You have  used an  invalid character  in a filename, or the file
        GRASP was trying to load was not found.


        ERROR IN PACKED CLIPPING

         - sometimes, clippings may be trashed  or  someone  tries  to load
        some other  file with a .CLP extension. If GRASP does not recognize
        a clipping as being  a  valid  clipping  file,  you  will  get this
        message.


        ERROR IN XCOORD

         - The Y-coordinate  lies off  the screen.  This may occur after an
        OFFSET command. If you specify 0 for the Y coordinate, but Y offset
        is set to -5, you will get this error.


        ERROR IN YCOORD

         - The Y-coordinate  lies off  the screen.  This may occur after an
        OFFSET command. If you specify 0 for the Y coordinate, but Y offset
        is set to -5, you will get this error.


        ERROR LOADING FONT

         - GRASP doesn't  recognize the  font you  are trying to load. Also
        could be too large for memory or hardware error during load.


        ERROR LOADING PICTURE

         - GRASP doesn't recognize the picture you are trying to load. Also
        could be hardware error during load.


        ERROR LOADING TEXT

         - GRASP doesn't recognize the text file you are trying to link to.
        Also could be hardware during load.


        ILLEGAL ARGUMENT(S)

         - One  of  the  arguments  for  the  current  command  is invalid.
        Examples are invalid video mode, etc.


        ILLEGAL BUFFER

         - You  have  specified  a  buffer  number that is outside of valid
        range. Buffers are 1-16 for pictures and 1-128  for clippings. Also
        may get  this when  an error occurs trying to allocate a new buffer
        during load.


        ILLEGAL COLOR

         - You have specified an invalid color number for this video mode.


        ILLEGAL FADE

         - You have specified an invalid fade number. Valid fades are 0-25.


        ILLEGAL PALETTE

         - You have  specified an  invalid palette  number for  CGA 4 color
        mode. Valid palettes are 0-5.


        ILLEGAL SPEED

         - You have specified an invalid speed for a fade. Valid speeds are
        0-10000.


        INVALID FONT STYLE

         - You have specified an  invalid font  style number.  Valid styles
        are 0-6.


        INVALID GAP VALUE

         - You have specified an invalid GAP value. Range is 0-255.


        LABEL NOT FOUND

         - You have  tried to  reference a  label which  was not previously
        defined.


        MEMORY ERROR

         - When trying to allocate the memory for your  GRASP command file,
        an error  was encountered. Usually only happens when a command file
        is too large.


        NOT ENOUGH ARGUMENTS

         - Certain commands require a minimum number of arguments. You need
        to specify some more.


        THIS COMMAND REQUIRES AN EGA

         - Just like  it says, this particular command requires an EGA card
        and EGA video mode to operate.


        TOO MANY LOOPS

         - You have nested your loops deeper than the maximum, which is 16,
        or you have more loop commands that mark commands.


        TOO MANY MARKS

         - You have nested your loops deeper than the maximum, which is 16,
        or you have more mark commands than loop commands.


        UNKNOWN COMMAND

         - GRASP found something that was not  a comment,  not a  label and
        couldn't recognize as a valid command. Check your spelling.



        APPENDIX D - Picture Swap Line


        There is  a public  domain electronic bulletin board which operates
        24 hours a day with the sole purpose of providing a method by which
        users of PCPAINT and GRASP may exchange pictures, clippings, fonts,
        effects and ideas. This help eliminate the extra  cost of providing
        artwork for  many of  the GRASP  demos you  may want to create. The
        most current version of GRASP will be avaliable this system.

        All uploads and downloads are free  and may  be used  by anyone. We
        encourage you  to contribute  any artwork you feel could be used by
        someone else. Of  course  there  will  be  proprietary  artwork you
        either pay  to have  developed, or  need to  keep confidential. But
        your discards may be another's joy...

        The BBS is located in Costa Mesa, California, and the number is

                           ***    (714) 545-8100    ***

        You will be limited to 1 hour of use per  day. We  suggest that you
        use 1200  or 2400 baud modems set at 8 bits, 1 stop bit, no parity.
        You will be transferring binary files so the 8 bit mode is  a must.
        There are  several utility programs you will want to download first
        which allow you to squeeze and unsqueeze the pic files so that they
        will not  take as  much time  to upload and download. You will find
        them in the UTILITY file area.


        Thanks in advance for your support and contributions to the board.





        APPENDIX E - GRASP Order Form

        GRASP is distributed in the USEware format. If you are going to USE
        it, please  check the  appropriate box below and enclose a check or
        purchase order. If you find the program unUSEable, please drop us a
        line telling  us why. If you pay for the program by sending in this
        registration form with a check or money order, you will be added to
        our  mailing  list  and  be  kept  notified of new releases and new
        utilities.

        ------------------------------------------------------------------
        Single-User Order Form
        ======================
        If you are going to pay for less than 50 copies, use this form. The
        single  user  price  is  $50.00. California residents please add 6%
        sales tax. You must pay for EACH copy you plan to use.

        Full Name:__________________________  ___ Copies @ $50.00=_________

        Address  :__________________________      6% Sales Tax   =_________

                 :__________________________      Total Enclosed =_________

        City, St.:_________________    _____  Zip:_________________

        ------------------------------------------------------------------
        Corporate Site License Order Form
        =================================
        If you are going to be using in excess of 50 copies of GRASP within
        your company at one site, (5 mile radius from licensing party), you
        need only pay for the  first  50  copies.  You  may  then  make and
        distribute to  your employees  an unlimited number of copies of the
        software and manual. We have 45 day billing  if you  include a P.O.
        number instead of a check or money order.

        Primary Corporate Contact for updates, etc.:

        Full Name :_________________________  50 Copies @ $50.00 = $2500.00

        Address   :_________________________        6% Sales Tax =_________

                  :_________________________      Total Enclosed =_________

        Department:_________________________   P.O. Number:________________

        City, St. :_________________    _____     Zip:_________________

        Authorized Signature:______________________________  Date:_________

        ------------------------------------------------------------------


++---------------------------------------------------------------------


Things fixed or changed since 3.1a
----------------------------------

  1) PCX support should be completed. Included 256 color. Files should be
     identical to PCX output.
 
  2) PFADE should work like PFADE 0 if a window is used.

  3) Default mode (text) should clear screen in GRASPRT.

 *4) DLOAD, DFREE and PUTDFF should be added to GRASP.

     DLOAD defaults to buffer 1 like CLOAD and PLOAD and FLOAD	

     PUTDFF BUFNUM DELAY BEGIN END XPOS YPOS

     BUFNUM defaults to 1
     DELAY defaults to 0
     BEGIN defaults to 0
     END defaults to BEGIN is BEGIN is given, else defaults to last frame
     XPOS defaults to 0
     YPOS defaults to 0

 *5) STB VGA/EM card isn't being reset to text mode after quit of Pictor.

 *6) Pictor needs to allow CUT, COPY, PASTE, INVERT while in Change Colors box.
     This applies to the colors that lie between left and right button color.

 *7) Bug in MOVE command in GRASP where it doesn't hide the mouse cursor.

 *8) 80386 bug in moving large regions in Pictor, GRASP. 

  9) For PFADEs and CFADEs (ALL of them!) the lower left corner of the buffer
     should align with the lower left corner of the window unless altered
     with the position command. This means we should have some sort of
     position for CFADE. Perhaps OFFSET?

*10) ERRORLEVEL is asigned to a key after an EXEC so IFKEY can test for it.

*11) SPREAD 1,2 used to set palette 1 then spread to palette 2. Now, it works
     properly where it just figures the differences and does the spread. This
     allows very nice complicated operations previously impossible.




++---------------------------------------------------------------------

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.


++---------------------------------------------------------------------


                   PCPAINT/Pictor Page Format Description

                          Format by John Bridges.

                   Document by Microtex Industries, Inc.





Revision Date: 2/9/88



Global Notes:
------------

PCPAINT 1.0 - Revision 1.0 was developed for Mosue Systems in 1984 supported
only BSAVE files in CGA 4 color mode. In the space between the scan buffers
was a string that read PCPAINT 1.0 followed by 2 bytes which were the pallete
and border information for that picture.

PCPAINT 1.5 - Revision 1.5 was the same as 1.0 except that it contained larger
than screen images and also had a primative packing format. This was sold for
so short a time that it won't be covered here.

PCPAINT 2.0 thru Pictor 3.1 - This document describes these formats. The file
description is identical for all revisions in this range. However, in
PCPAINT 2.0, the bit-planes were packed together so that the pictures
resembled a PCjr picture, or 4 bits per pixel, 1 bit plane. Starting with
Pictor 3.0, the files were saved with the bitplanes separated. This takes a
little more memory in some cases, but the speed in loading and saving was a
desireable consideration.

NOTE TO PROGRAMMERS: A good PCPAINT/Pictor file decoder will use the variables
                     in the header to decode the image and thus be compatible
                     with all formats since the October, 1985 release of
                     PCPAINT 2.0.

Also please note that PCPAINT/Pictor are stored from the bottom up. This is
opposite that of most of the screen adapters it supports. This really causes
no problem, but be aware that you should use a Y table to look up scan lines.
In all PCPAINT/Pictor pictures, the scan lines are continuous. If a picture 
is to be displayed on a particular adapter, the programmer is responsible for
using a y-table to properly interleave the lines if necessary.

Also note that Pictor was designed for speed, so no inter-mode loading is
possible. If you are writing applications that create Pictor images that you
want to load into Pictor, you must remain mode dependent. 

Header - A full description of the file header information.

offset	type	name	description
-------	-------	-------	----------------------------------------------------- 
  0	word	marker	marker that is always 01234h

  2	word	xsize	x size of page in pixels 

  4	word	ysize	y size of page in pixels

  6	word	xoff	x offset into page where lower left hand corner of
			viewport is located (default of 0 is ok)

  8	word	yoff	y offset into page where lower left hand corner of
			viewport is located (default of 0 is ok)

 10	byte	bitsinf	bits 0-3 is the number of bits per pixel per bit
			plane and bits 4-7 is the number of bit planes (so
			4 color cga mode would be 02h and 16 color ega would
			be 31h and plantronics 16 color would be 12h)

 11	byte	emark	marker that is always a 0ffh

 12	byte	evideo	single uppercase letter indicating which video mode
			this picture was created in, can default to 0.

			0 - 40 col text
			1 - 80 col text
			2 - mono text
			3 - 43 line text

			A=320x200x4 cga
			B=320x200x16 pcjr, stbplus, tandy 1000
			C=640x200x2 cga
			D=640x200x16 ega
			E=640x350x2 ega
			F=640x350x4 ega
			G=640x350x16 ega
			H=720x348x2 hercules
			I=320x200x16 plantronics
			J=320x200x16 ega
			K=640x400x2 AT&T or Toshiba 3100
			L=320x200x256 vga
			M=640x480x16 ega plus(video 7, tseng, paradise), vga
			N=720x348x16 Hercules InColor
			O=640x480x2 vga

 13	word	edesc	extra information descriptor defines what is in
			the extra information that follows this header,
			0=nothing
			1=pallet (single byte) border (single byte)[CGA]
			2=pcjr or non ECD 16 color registers (0-15), 1 byte each
			3=EGA with ECD 16 color registers (0-63) 1 byte each
			4=VGA 256 color info - 256 colors, 1 byte each rgb gun.

 15	word	esize	size of extra information in bytes

 17	byte	edata[]	the actual extra data the size which is defined
			by esize (at offset 15).
 17+
 esize	word	numblks	the number of packed blocks in this file. if this is
			a zero, then data is unpacked. 


Structures - These C structures describe the header information.

If the file is packed then what follows is a multi block packed file,
otherwise (if the file is not packed, numblks=0) the actual data follows.

Bit planes follow each other in the file and when packed each bit plane
must start in a new packed block.


Packed Block Description


Packed block header

0PBSIZE	dw		;Packed block size. The size of this block
BSIZE	dw		;Unpacked block size
MBYTE	db		;Unique marker byte. This is a byte that does not
			; exist in the current unpacked block. If no unique
			; byte exists, then pick one that is used rarely
			; to avoid too much redundancy.

Packed block data - variable size depending on whether 16 bit run is needed.

MARKER	db		;mark a run (this is where MBYTE goes) 
LENGTH	db		;length of run. if 0, then look at BIGLEN

BIGLEN	dw		;16 bit run count (only exists if LENGTH==0)
DATA	db		;byte to fill run with


Example 1 - a 320x200, 4 color, packed page file, of a white screen. 

	dw	0x1234		;marker
	dw	320		;x size
	dw	200		;y size
	dw	0		;x offset
	dw	0		;y offset
	db	02h		;2 bits per pixel and 1 bit plane

	db	0xff		;extra info flag
	db	'A'		;vidmode
	dw	1		;extra area descriptor (pal and bord)
	dw	2		;bytes in extra area
	db	2,0		;pallet and border (extra information)

	dw	2		;number of packed blocks

;first block
	dw	5+5		;packed block size
	dw	8192		;unpacked block size
	db	0		;marker byte
	db	0		;mark a run
	db	0		;a 16 bit run count follows
	dw	8192		;16 bit run count
	db	0xff		;byte to fill run with
;second block
	dw	5+5		;packed block size
	dw	7808		;unpacked block size
	db	0		;marker byte
	db	0		;mark a run
	db	0		;a 16 bit run count follows
	dw	7808		;16 bit run count
	db	0xff		;byte to fill run with




Example 2 - a 640x350, 16 color, packed page file, of a red screen (color 4).

	dw	0x1234		;marker
	dw	640		;x size
	dw	350		;y size
	dw	0		;x offset
	dw	0		;y offset
	db	31h		;bits per pixel and 1 bit plane

	db	0xff		;new extra info flag
	db	'G'		;vidmode
	dw	3		;extra area descriptor (pal and bord)
	dw	16		;bytes in extra area
	db	0,1,2,3,4,5,14h,7
	db	38h,39h,3ah,3bh,3ch,3dh,3eh,3fh

	dw	16		;number of packed blocks
;block 1 of first bit plane
	dw	5+5		;packed block size
	dw	8192		;unpacked block size
	db	0		;marker byte
	db	0		;mark a run
	db	0		;a 16 bit run count follows
	dw	8192		;16 bit run count
	db	0		;byte to fill run with
;block 2 of first bit plane
	dw	5+5		;packed block size
	dw	8192		;unpacked block size
	db	0		;marker byte
	db	0		;mark a run
	db	0		;a 16 bit run count follows
	dw	8192		;16 bit run count
	db	0		;byte to fill run with
;block 3 of first bit plane
	dw	5+5		;packed block size
	dw	8192		;unpacked block size
	db	0		;marker byte
	db	0		;mark a run
	db	0		;a 16 bit run count follows
	dw	8192		;16 bit run count
	db	0		;byte to fill run with
;block 4 of first bit plane
	dw	5+5		;packed block size
	dw	3424		;unpacked block size
	db	0		;marker byte
	db	0		;mark a run
	db	0		;a 16 bit run count follows
	dw	3424		;16 bit run count
	db	0		;byte to fill run with
;block 1 of second bit plane
	dw	5+5		;packed block size
	dw	8192		;unpacked block size
	db	0		;marker byte
	db	0		;mark a run
	db	0		;a 16 bit run count follows
	dw	8192		;16 bit run count
	db	0		;byte to fill run with
;block 2 of second bit plane
	dw	5+5		;packed block size
	dw	8192		;unpacked block size
	db	0		;marker byte
	db	0		;mark a run
	db	0		;a 16 bit run count follows
	dw	8192		;16 bit run count
	db	0		;byte to fill run with
;block 3 of second bit plane
	dw	5+5		;packed block size
	dw	8192		;unpacked block size
	db	0		;marker byte
	db	0		;mark a run
	db	0		;a 16 bit run count follows
	dw	8192		;16 bit run count
	db	0		;byte to fill run with
;block 4 of second bit plane
	dw	5+5		;packed block size
	dw	3424		;unpacked block size
	db	0		;marker byte
	db	0		;mark a run
	db	0		;a 16 bit run count follows
	dw	3424		;16 bit run count
	db	0		;byte to fill run with
;block 1 of third bit plane
	dw	5+5		;packed block size
	dw	8192		;unpacked block size
	db	0		;marker byte
	db	0		;mark a run
	db	0		;a 16 bit run count follows
	dw	8192		;16 bit run count
	db	0xff		;byte to fill run with
;block 2 of third bit plane
	dw	5+5		;packed block size
	dw	8192		;unpacked block size
	db	0		;marker byte
	db	0		;mark a run
	db	0		;a 16 bit run count follows
	dw	8192		;16 bit run count
	db	0xff		;byte to fill run with
;block 3 of third bit plane
	dw	5+5		;packed block size
	dw	8192		;unpacked block size
	db	0		;marker byte
	db	0		;mark a run
	db	0		;a 16 bit run count follows
	dw	8192		;16 bit run count
	db	0xff		;byte to fill run with
;block 4 of third bit plane
	dw	5+5		;packed block size
	dw	3424		;unpacked block size
	db	0		;marker byte
	db	0		;mark a run
	db	0		;a 16 bit run count follows
	dw	3424		;16 bit run count
	db	0xff		;byte to fill run with
;block 1 of fourth bit plane
	dw	5+5		;packed block size
	dw	8192		;unpacked block size
	db	0		;marker byte
	db	0		;mark a run
	db	0		;a 16 bit run count follows
	dw	8192		;16 bit run count
	db	0		;byte to fill run with
;block 2 of fourth bit plane
	dw	5+5		;packed block size
	dw	8192		;unpacked block size
	db	0		;marker byte
	db	0		;mark a run
	db	0		;a 16 bit run count follows
	dw	8192		;16 bit run count
	db	0		;byte to fill run with
;block 3 of fourth bit plane
	dw	5+5		;packed block size
	dw	8192		;unpacked block size
	db	0		;marker byte
	db	0		;mark a run
	db	0		;a 16 bit run count follows
	dw	8192		;16 bit run count
	db	0		;byte to fill run with
;block 4 of fourth bit plane
	dw	5+5		;packed block size
	dw	3424		;unpacked block size
	db	0		;marker byte
	db	0		;mark a run
	db	0		;a 16 bit run count follows
	dw	3424		;16 bit run count
	db	0		;byte to fill run with



Example 3 - For more detail lets consider a block that isn't all the same.
Say the data consists of 30 2's, and 8, a 4, and 300 1's.

; the block would look like this 

	dw	5+10		;packed block size
	dw	332		;30 + 1 + 1 + 300 bytes as above
	db	ff		;what to mark a run with,
                                ; because there are no ff's in our example.

	db	ff		;mark a run 
	db	30		;8 bit run count
	db	2		;byte to fill run with - 2

	db	8		;not a run marker, so must be data

	db	4		;not a run marker, so must be data

	db	ff		;mark a run
	db	0		;means 16 bit run count follows
	dw	300		;run count	
	db	1		;byte to fill run with - 1


The actual unpacked data that resides in memory consists 2 seperate
sections.

1. The control structure: contains x size, y size, x offset, y offset,
   segment of bit mapped data, number of bits per pixel and number of
   additional bit planes. this information is kept in pcpaint's data segment.

2. The actual bit mapped data: contains the actual page image, mapped from
   bottom left (so bottom scan line is first). The data is contiguous within
   each bit plane, so scan line 1 follows scan line 0 directly. the page
   can and does cross segment boundires (a bit plane can be larger than
   64k). each bit plane follows the previous but starts on a paragraph
   boundary, the printer driver will be passed the offset in paragraphs
   between bit planes and the number of additional planes.
   The bit planes start with bit 0, each additional plane is the next bit.


++---------------------------------------------------------------------


                     THE DATA TRANSFORMS FONT FORMAT


                         Data Transforms, Inc.
                           616 Washington St.
                         Denver, Colorado 80203
                            (303) 832-1501


                       Technical Support Contacts:
                            Bob Van Arsdale
                            Glenn Searfoss
                             Steven Boker

A Brief Background.

	Data Transforms' font library of over 200 different font styles
	(Fontpak Volumes 1 - 15, and Laser Fontpak volumes 1 & 2) was
	created by our IBM Fontrix graphics package.  The font creation
	limits of the Fontrix Font Editor are 1 x 1 to 96 x 96 pixels and
	may be any alphanumeric, language, or symbol.  Fontrix, written in
	C and Assembler, creates/saves images and fonts in a bit-mapped
	raster format.

The Fontrix Font Format Definition.

	"Font1 Structure Definition" describes the standard font header of
	a Data Transform non-compressed font.

	Each font has a header that defines the font and points to the
	character bitmaps.  Immediately following the font header is the
	character bitmap data.  Character bitmaps are stored as scanrects
	in scanline order from top to bottom.  Each scanline is stored
	bytewise left to right, left justified and rounded to byte length. 
	Each byte is stored 8 bits per byte where MSB is the leftmost
	pixel.

	"Font2 Structure Definition" details the header information for a
	font compressed using a "bounding box~ data compression method. 
	This method (see Figure 2) involves outlining a cell's "bit-on~
	character data with the smallest box possible.  Coordinates that
	position the "box~ relative to the original character cell are
	saved in the font header.  This compression method is automatic
	within the Data Transforms Font Editor when a font over 32 x 32
	pixels in size is saved.

	The bounding box routine can run at up to 90% of the over-all
	compression efficiency of more computationally expensive
	compression algorithms.  The actual character bits-on data is never
	compressed.  Information regarding the bounding box (size, [x,y]
	position within the original cell, etc...) is kept for each
	character in a lookup table in the font header.

	Using this compression method on the character cell in Figure 1
	(lower case "i~), the net gain in savings is 94% of the original
	character cell size.  For Figure 3 (upper case "W~), the net
	savings is 31% of the original character cell size.  The percentage
	in savings correlates to the discarded zero (bit off) data outside
	of the bounding box.

	The character data is never compressed; rather, the empty space
	outside of the bounding box is discarded.  The analogy of a
	shrink-wrap bag can be used to illustrate.

	Imagine a character cell placed within a shrink-to-fit bag.  The
	non-compressed cell is the unshrunk bag.  Now shrink the bag until
	all edges contact the outer limits of bit-on data, forming a
	rectangular bounding box.  For some characters, as in a lower case
	"i", this correlates to a major amount of shrinkage and the
	shrinkage correlates to saved data space, hence compression.  An
	upper case "W" may fill the majority of a cell.  In this instance
	minimal shrinkage will occur, with little or no saved data space. 
	However, the overall net savings in data space for an entire font
	set will be great since few characters fill an entire cell. 


/* FONT1 STRUCTURE DEFINITIONS */

struct font1head {          /* standard character font header */
	unsigned char fnttype;  /* font structure type: */
                            /* non-compressed type = 0x10 or compressed type = 0x14 */
	char fntname[13];       /* font name -always followed with a ".set" extension */
	unsigned char fntcheck; /* check digit - verifies a Data Transforms font */
                            /* non-compressed font = 0xba, compressed font = 0xdc */
	unsigned char fntbase;	/* baseline count (in pixels) from top to bottom, top = 0 */
	unsigned char fnttotal;	/* total characters in font:*/
              		        /* limited to the lower 94 ASCII characters: 0x21 - 0x7E */
	unsigned char fntstart;	/* starting character */
	unsigned char fntstatus;/* proportional or non-proportional: 0 = non-proportional */
	unsigned char fnthsize;	/* horizontal cell size in pixels */
	unsigned char fntvsize;	/* vertical cell size in pixels */
	unsigned char fntbytes;	/* number of horizontal bytes in the current cell */
	unsigned char fntspaceh;	/* space bar horizontal size in pixels */
	unsigned char fntchargap;	/* pixels between characters default */
	unsigned char fntlfgap;	/* pixels between linefeeds default */
	int fntlength;	/* total length of file */
	unsigned char fntpitch;	/* italics pitch (0 = none) */
		/* bits 0 - 6 ... number of scanlines to skip */
		/* bit  7 ... 0 = decrement xpos, 1 = increment xpos */
	unsigned char fntinvert;	/* 0 = dont invert, 1 = invert */
	unsigned char fnthbold;	/* number of overlapping bits horizontal */
	unsigned char fntvbold;	/* number of overlapping bits vertical */
	unsigned char fnthmag;	/* integral horizontal bit magnification */
	unsigned char fntvmag;	/* integral vertical bit magnification */
	unsigned char fnthfract;	/* fractional horizontal bit magnification */
	unsigned char fntvfract;	/* fractional vertical bit magnification */
	unsigned char fntdirection;	/* Print direction 0 = left to right, 1...3 = counterclock 1...3 */
	unsigned char fntrot90;	/* rotation 0 = up, 1...3 = counterclock 1...3 */
	unsigned char fnthflip;	/* horizontal flip 0 = no, 1 = yes */
	unsigned char fntvflip;	/* vertical flip 0 = no, 1 = yes */
	unsigned char fntcolor;	/* color of font */
		/* bits 0 - 3 ... foreground color */
			/* bit 0 ... strike black ribbon */
			/* bit 1 ... strike blue ribbon */
			/* bit 2 ... strike red ribbon */
			/* bit 3 ... strike yellow ribbon */
		/* bits 4 - 7 ... background color */
			/* bit 4 ... strike black ribbon */
			/* bit 5 ... strike blue ribbon */
			/* bit 6 ... strike red ribbon */
			/* bit 7 ... strike yellow ribbon */
	unsigned char fntsubtype;	/* subcategory type of this font */
			/* 0 = normal font subtype */
			/* 1 = equation roman font subtype */
			/* 2 = equation symbol font subtype */
	unsigned char fntunused[18];	/* unused bytes */
};

struct font1 {	/* standard character font (type = 0x10) */
	struct font1head fhd;	/* font header */
	char *fntcellptr[FONT1TOTAL + 1];		/* offsets from beginning of file to character bitmaps */
	char fntcellwidth[FONT1TOTAL + 1];	/* cell widths if proportional */
};


/* FONT2 STRUCTURE DEFINITIONS */

struct font2 {
	struct font1head fhd2;			/* font header */
	unsigned int fnt2cellseg[FONT2TOTAL + 1];	/* array of segment pointers to characters */
	int fnt2cellhsize[FONT2TOTAL + 1];		/* array of cell horizontal sizes in bits */
	int fnt2cellhoffset[FONT2TOTAL + 1];	/* array of cell horizontal offsets in bits */
	int fnt2cellhbytes[FONT2TOTAL + 1];	/* array of cell horizontal size in bytes */
	int fnt2cellvsize[FONT2TOTAL + 1];		/* array of cell vertical sizes in bits */
	int fnt2cellvoffset[FONT2TOTAL + 1];	/* array of cell vertical offsets in bits */
};

	The data listed in the "struct font2~ portion of the (Font2) font
	structure above is defined as follows:

	* The font header is the same as described in the "struct
	font1head~ of the non-compressed font data format.

	* Font cell segments are an array of segment pointers to characters
	kept as offsets from the beginning of the font file.  For example,
	if an array value for a character = 10, then the starting address
	of a character's "bounding box~ data = (the start of file address +
	sizeof (struct font2)) + (10 x 16), where 1 segment = 16 bytes.

	* The Horizontal size is the actual width in bits of the bounding
	box.

	* The Horizontal offset is the distance in bits from the left edge
	of the cell to the upper lefthand corner of the bounding box.

	* Horizontal bytes refers to the actual size in bytes of the
	interior of the bounding box.

	* The Vertical size is the actual height in bits of the bounding
	box.

	* The Vertical offset is the distance in bits from the top edge of
	the cell to the upper edge of the bounding box.



++---------------------------------------------------------------------


Technical Reference Manual

Including Information For:
Publisher's Paintbrush
PC Paintbrush Plus
PC Paintbrush

ZSoft Corporation
450 Franklin Rd. Suite 100
Marietta, GA  30067
(404) 428-0008

IMAGE FILE (.PCX) FORMAT

The information in this section will be useful if you want to write a
program to read or write PCX files (images).  If you want to write a
special case program for one particular image format you should be able to
produce something that runs twice as fast as "Load from..."  in PC
Paintbrush.

Image files used by PC Paintbrush product family and FRIEZE (those with a
.PCX extension) begin with a 128 byte header.  Usually you can ignore this
header, since your images will all have the same resolution.  If you want
to process different resolutions or colors, you will need to interpret the
header correctly.  The remainder of the image file consists of encoded
graphic data.  The encoding method is a simple byte oriented run-length
technique.  We reserve the right to change this method to improve
efficiency.  When more than one color plane is stored in the file, each
line of the image is stored by color plane (generally ordered red, green,
blue, intensity), As shown below.

Scan line 0: 	RRR...
		GGG...
		BBB...
		III...
Scan line 1: 	RRR...
		GGG...
		BBB...
		III...
(etc.)
The encoding method is:
FOR  each  byte,  X,  read from the file
	IF the top two bits of X are  1's then
		count = 6 lowest bits of X
		data = next byte following X
	ELSE
		count = 1
		data = X

Since the overhead this technique requires is, on average, 25% of the
non-repeating data and is at least offset whenever bytes are repeated, the
file storage savings are usually considerable.

The format of the file header is shown below.

ZSoft .PCX FILE HEADER FORMAT

Byte	Item	        Size	Description/Comments

0	Manufacturer	1	Constant Flag  10 = ZSoft .PCX
1	Version 	1	Version information:
				0 = Version 2.5
				2 = Version 2.8 w/palette information
				3 = Version 2.8 w/o palette information
				5 = Version 3.0
2	Encoding	1	1 = .PCX run length encoding
3	Bits per pixel	1	Number of bits/pixel per plane
4	Window  	8	Picture Dimensions 
				(Xmin, Ymin) - (Xmax - Ymax)
				in pixels, inclusive
12	HRes    	2	Horizontal Resolution of creating device
14	VRes    	2	Vertical Resolution of creating device
16	Colormap	48	Color palette setting, see text
64	Reserved	1
65	NPlanes	        1	Number of color planes
66	Bytes per Line	2	Number of bytes per scan line per 
				color plane (always even for .PCX files)
68	Palette Info	2	How to interpret palette - 1 = color/BW,
				2 = grayscale
70	Filler  	58	blank to fill out 128 byte header

All variables of size 2 are integers.


Decoding .PCX Files First, find the pixel dimensions of the image by
calculating [XSIZE = Xmax - Xmin + 1] and [YSIZE = Ymax - Ymin + 1].

Then calculate how many bytes are required to hold one complete
uncompressed scan line:  TotalBytes = NPlanes * BytesPerLine
Note that since there are always an integral number of bytes, there will
probably be unused data at the end of each scan line.  TotalBytes shows
how much storage must be available to decode each scan line, including any
blank area on the right side of the image.

You can now begin decoding the first scan line - read the first byte of
data from the file.  If the top two bits are set, the remaining six bits
in the byte show how many times to duplicate the next byte in the file.
If the top bits are not set, the first byte is the data itself, with a
count of one.  Continue decoding the rest of the line.  Keep a running
subtotal of how many bytes are moved and duplicated into the output
buffer.  When the subtotal equals TotalBytes, the scan line is complete.

There will always be a decoding break at the end of each scan line.  But
there will not be a decoding break at the end of each plane within each
scan line.  When the scan line is completed, there may be extra blank data
at the end of each plane within the scan line.  Use the XSIZE and YSIZE
values to find where the valid image data is.  If the data is multi-plane
BytesPerLine shows where each plane ends within the scan line.  Continue
decoding the remainder of the scan lines.  There may be extra scan lines
at the bottom of the image, to round to 8 or 16 scan lines.

Palette Information Description

EGA/VGA 16 Color Palette Information

The palette information is stored in one of two different formats.  In
standard RGB format (IBM EGA, IBM VGA) the data is stored as 16 triples.
Each triple is a 3 byte quantity of Red, Green, Blue values.  The values
can range from 0-255 so some interpretation into the base card format is
necessary.  On an IBM EGA, for example, there are 4 possible levels of RGB
for each color.  Since 256/4 = 64, the following is a list of the settings
and levels:

Setting		Level
0-63		0
64-127		1
128-192		2
193-254		3

VGA 256 Color Palette Information

ZSoft has recently added the capability to store palettes containing more
than 16 colors in the .PCX image file.  The 256 color palette is formatted
and treated the same as the 16 color palette, except that it is
substantially longer.

The palette (number of colors x 3 bytes in length) is appended to the end
of the .PCX file, and is preceded by a 12 decimal.  To determine the VGA
BIOS palette you need only divide the values read in the palette by 4.

To access a 256 color palette:

First, check the version number in the header, if it contains a 5 there is
a palette.

Second, read to the end of the file and count back 769 bytes.  The value
you find should be a 12 decimal, showing the presence of a 256 color
palette.

CGA Color Palette Information

For a standard IBM CGA board, the palette settings are a bit more complex.
Only the first byte of the triple is used.  The first triple has a valid
first byte which represents the background color.  To find the background,
take the (unsigned) byte value and divide by 16.  This will give a result
between 0-15, hence the background color.  The second triple has a valid
first byte, which represents the foreground palette.  PC Paintbrush
supports 8 possible CGA palettes, so when the foreground setting isbetween
0 and 255, there are 8 ranges of numbers and the divisor is 32.


CGA Color Map
Header Byte #16
Background color is determined in the upper four bits.
Header Byte #19

Only upper 3 bits are used, lower 5 bits are ignored.  The first three
bits that are used are ordered C, P, I.  These bits are interpreted as
follows:

c: color burst enable - 0 = color; 1 = monochrome
p: palette - 0 = yellow; 1 = white
i: intensity - 0 = dim; 1 = bright

PC Paintbrush Bitmap Character Format

The bitmap character fonts are stored in a particularly simple format.
The format of these characters is as follows:

Header (2 bytes)
font width	db	0a0h + character width (in dots)
font height	db	character height (in dots)
Character Widths (256 bytes)
char widths	db	256 dup(each char's width +1)
Character Images
(remainder of the file)

The characters are stored in ASCII order and as many as 256 may be
provided.  Each character is left justified in the character block, all
characters take up the same number of bytes.

Bytes are organized as N strings, where each string is one scan line of
the character.  See figure 2.

For example, each character in a 5x7 font requires 7 bytes.  A 9x14 font
uses 28 bytes per character (stored two bytes per scan line in 14 sets of
2 byte packets).  Custom fonts may be any size up to the current maximum
of 10K bytes allowed for a font fil e.

Sample "C" Routines

The following is a simple set of C subroutines to read data from a .PCX
file.

/*
 * This procedure reads one encoded block from the image file and stores
 * a count and data byte.
 * Result:
 * 0 = valid data stored
 * EOF = out of data in file
 */

encget(pbyt, pcnt, fid)
int *pbyt;     /* where to place data */
int *pcnt;     /* where to place count */
FILE *fid;     /* image file handle */
{
    int i;

    *pcnt = 1;     /* safety play */
    if (EOF == (i = getc(fid)))
	return(EOF);
    if (0xc0 == (0xc0 & i)) {
	*pcnt = 0x3f&i;
	if (EOF == (i = getc(fid)))
	    return(EOF);
    }
    *pbyt = i;
    return(0);
}

/*
 * Here's a program fragment using encget.  This reads an entire file and
 * stores it in a (large) buffer, pointed to by the variable "bufr".
 * "fp" is the file pointer for the image
 */

    while (EOF != encget(&chr, &cnt, fp))
	for (i = 0; i ~	*bufr++ = chr;


The following is a set of C subroutines to write data to a .PCX file.

 /* This subroutine encodes one scanline and writes it to a file */

encLine(inBuff, inLen, fp)
unsigned char *inBuff;  /* pointer to scanline data */
int inLen;			/* length of raw scanline in bytes */
FILE *fp;			/* file to be written to */
{  /* returns number of bytes written into outBuff, 0 if failed */
	unsigned char this, last;
int srcIndex, i;
register int total;
register unsigned char runCount; /* max single runlength is 63 */
total = 0;
last = *(inBuff);		runCount = 1;

for (srcIndex = 1; srcIndex  inLen; srcIndex++) {
	this = *(++inBuff);
	if (this == last)	{
		 runCount++;	/* it encodes */
		if (runCount == 63)	{
			if (!(i=encput(last, runCount, fp)))
				return(0);
			total += i;
			runCount = 0;
			}
		}
	else	{   /* this != last */
		if (runCount)	{
			if (!(i=encput(last, runCount, fp)))
				return(0);
			total += i;
			}
		last = this;
		runCount = 1;
		}
	}	/* endloop */
if (runCount)	{		/* finish up */
	if (!(i=encput(last, runCount, fp)))
		return(0);
	return(total + i);
	}
return(total);
}

/* subroutine for writing an encoded byte pair 
(or single byte  if it doesn't encode) to a file */
encput(byt, cnt, fid) /* returns count of bytes written, 0 if err */
unsigned char byt, cnt;
FILE *fid;
{
if(cnt) {
	if( (cnt==1) && (0xc0 != (0xc0&byt)) )	{
		if(EOF == putc((int)byt, fid))
			return(0); /* disk write error (probably full) */
		return(1);
		}
	else		{
		if(EOF == putc((int)0xC0 | cnt, fid))
			return(0); 	/* disk write error */
		if(EOF == putc((int)byt, fid))
			return(0); 	/* disk write error */
		return(2);
		}
	}
return(0);
}
