
   PGC Portfolio Graphics Compressed File Specification
   ----------------------------------------------------
   by Don Messerli, Software Vineyard
   Revision 01      1/4/91

   Introduction
   ------------

   The PGC spec allows graphic files on the Portfolio (formerly called
   PGF files) to be compressed to save disk (RAM Card) space. We
   all know how much RAM cards cost!

   A little background
   -------------------

   The Portfolio's screen is 240 x 64 pixels when in graphics mode.
   Being monochome, it only takes 1 bit to represent a single pixel.
   Therefore, 8 pixels per byte.  A PGF ends up being 64 rows of
   30 bytes each for a total of 1920 bytes.  PGF files could simply
   be copied from video ram to disk and vice-versa.

   This was pretty simple.  All PGF files were 1920 bytes no matter
   how complex the picture.  A real space waster in most cases.
   Compression became a logical next step.

   What will compression do?
   -------------------------

   Compression can save quite a bit of space.  Typically from 20
   to 80% depending on the file.  However, because of the compression
   algorithm I have chosen, it is also possible for a file to become
   larger.  This happens with files that have a lot of random dots
   on the screen with little repetition.  Digitized photos are the
   culprits.  Fortunately, because of the small size of the Portfolio
   screen, we probably won't be seeing too many of them.

   PGC File Format
   ---------------

   Header -   The first 3 bytes of the file are the PGC header.  This
            is the only way to tell if the file is a PGC file or
            not.  This should always be checked when reading PGC
            files.  Your decoder routines could take a quick trip
            into never-never land if you try to decode a spreadsheet
            file.

            The three bytes that make up the header are the ASCII
            codes for 'P' and 'G' followed by the revision number
            in hex.  These three bytes should be:

                     "\x50\x47\x01" 
                        P    G   01

   Data -   The picture data is made up of repeating sets of single
            index bytes followed by data bytes.  The index byte
            tells the decoder how to handle the data that follows.
            The key is whether the high bit (\x80) is set or not.
            The maximum number of data bytes following an index
            byte is 127.

            High Bit Set
            ------------
            If the high bit is set, it indicates that the data is
            a string of identical bytes.  The low 7 bits indicate
            how many times to repeat the following byte (maximum is
            127).

            Example:  86     FF
                      index  data byte

               High bit of index byte is set, low 7 bits = 6.
               Repeat data byte (FF) 6 times.
                     
            High Bit Not Set
            ----------------
            If the high bit is NOT set, it indicates that the data
            following is a string of unique bytes and should be copied
            as is.  The low 7 bits indicate how many bytes to copy (max
            is 127).

            Example:  0A     FF 01 10 09 1A BB CE D0 FF 1A
                      index  data bytes

               High bit of index byte is NOT set, low 7 bits = 10.
               Copy next 10 bytes as is.

   
   Where do we go from here?
   -------------------------

   Writing a decoder is fairly straightforward.  The following is
   the general algorithm:

   do {
      get a byte from PGC image
      if high bit is set
         index = byte - 128
         get data byte
         write data byte, index times
      else
         index = byte
         copy next index # of bytes
   } while less than 1920 bytes written
   
   Writing an efficient compressor is a little more difficult.  I
   plan to upload a library of functions in the near future.  If
   you encounter difficulty writing a compressor, please contact
   me via electronic mail.


   What are these other files?
   ---------------------------         
   I have included a few PGF files to give your compressors and
   decoders a real workout.  

   BEST.PGF - This is a pure black image.  It should compress down
               to 35 bytes.

   WORST.PGF - This image is made up of runs of 2 identical bytes
               alternated with single unique bytes.  It should end
               up being larger as a PGC file (2524 bytes) than as
               a PGF file (1920 bytes). All decoders should be able
               to handle this file.
               
            
   In Closing
   ----------

   I hope this information is helpful for those writing graphics
   applications for the Portfolio.  It is my sincere wish that the
   PGC format is widely supported in the Portfolio arena and that
   it promotes compatibility between graphics applications on the
   Portfolio.  My sincere thanks to BJ Gleason for including PGC
   support in PBASIC.  That is a major step in making my wish come
   true.

   Please support the PGC format whenever possible.  If your application
   must output PGF files, because you're trying to write the world's
   smallest TSR (or something) and you can't commit to the overhead
   required by a compressor, that is unavoidable.  The PGF files can
   later be compressed with PGCOMP (my compressor).  It is still preferable
   to store files that end up larger as PGC files as PGC files anyway.
   This means software only has to worry about reading the PGC
   format.

   Versions of PGEDIT greater than 1.10 will read either PGF or PGC files.
   However, they will only save in PGC format.  BJ Gleason has indicated
   that PBASIC 3.1 will only read and write PGC files.

   If you have any questions, comments, or kind words, please send
   me electronic mail:

   Don Messerli
   Compuserve    72500,1671
   GEnie         DMESS


   

            
               

   