                       MultiGIF  V1.0  28-Jun-96

                  (C) 1996 Andy Wardley <abw@peritas.com>  
                          All Rights Reserved.
 

INTRODUCTION

  MultiGIF is a cross-platform utilty for creating animated GIF images.
  Given an initial set of GIF images, you can use MultiGIF to combine 
  them into a single multi-image GIF file.  When viewed with a web browser 
  such as Netscape Navigator V2.0+, these images will appear sequentially
  as frames of an animation.  
  
  For further information on GIF animations, check out Royal Frazier's 
  excellent information and tutorial pages: http://members.aol.com/royalef


COPYRIGHT, LICENSE AND DISTRIBUTION TERMS

  MultiGIF is shareware for PERSONAL use.  Individuals may use MultiGIF 
  free of charge for an unlimited period.  If you find you are using it a 
  lot, enjoy it, find it useful or of any other value, you may wish 
  to make a donation to the author to show your appreciation.  If you 
  find yourself using MultiGIF in anything that makes you money (such as 
  web design), then you SHOULD make a donation if only to keep your 
  conscience in check.  An amount of 20 UK Pounds or equivalent (IN UK 
  REDEEMABLE FUNDS, PLEASE) is suggested, but any amount, large or small 
  would be appreciated.

  Commercial, government or institutional users MUST register MultiGIF for
  20 UK Pounds, or equivalent (IN UK FUNDS, PLEASE), per copy in use.   
  Site licenses are available for multiple users.  Contact the author for
  more information.

  Source code for MultiGIF is available and may be distributed freely for
  non-commerical purposes.  You may compile, and distribute freely,
  UNMODIFIED versions of MultiGIF.  You may not make any charge for 
  MultiGIF (except for a small copying fee) without the express consent 
  of the author.  

  You may modify MultiGIF for your own use but you may not distribute 
  modified versions of the source code, or modified binaries, without the 
  express permission of the author.  However, you may reuse source code 
  from MultiGIF into your own programs, providing this stays within the 
  realms of "reasonable use" with the following conditions:

    1) Copyright notices are retained in the source code. 
    2) Credit is given in the documentation and any on-screen credits.
    3) No charge is made for the resulting software without the express
       permission of the author.

  "Reasonable use" is admittedly a fuzzy term but you should be able to
  realise where the boundary is.  If you want to reuse the GIF input/output 
  routines or the command-line parser, for example, then that's fine as 
  long as the conditions above are followed.  If you find yourself doing 
  more cutting and pasting that actual coding, then perhaps it's time to 
  stop and have a little re-think.  

  In the spirit of sharing, I would like to see people get the most they 
  can from the source code and hopefully pass something on for others 
  to benefit from.  I don't want to see someone benefit (either 
  financially or by taking undue credit) for something that essentially 
  isn't their own work.  The little recognition we get for our work is 
  often all there is.

  If you have any questions or requests, just ask.  Details at the end.

  GIF Copyright Notice:

         ** The Graphics Interchange Format(c) is the Copyright **
         ** property of CompuServe Incorporated. GIF(sm) is a   **
         ** Service Mark property of CompuServe Incorporated.   **

USAGE

  MultiGIF is invoked as a command line utility.  You can specify options
  as command line parameters or create a command file and pass the option
  "@filename" to MultiGIF.  You can freely mix commmand line parameters
  and command files.

  For example, if you have a file called "prm" with the following contents:

      -b 0 -c "This is a comment"
      -g 4

  then running MultiGIF as follows:
   
      multigif @prm

  is exactly the same as if you had typed:

      multigif -b 0 -c "This is a comment" -g 4

  You can also add further options to the command line:

      multigif -o outfile.gif @prm -v foo.gif bar.gif baz.gif

  Command line options may, or may not, have spaces between the command 
  letter and value.  i.e. "-ooutfile.gif" is the same as "-o outfile.gif".  
  Options specified in a command file may appear on the same, or on 
  different lines.  Options may be stated in any order.  
  
  Be warned that some parameters will need to be quoted ("") to avoid 
  problems.  For example, a comment with spaces will need to be quoted to 
  prevent the parser from thinking that the seperate words are additional 
  paramaters:

      -c "This is a comment"   NOT   -c This is a comment

  Also note that parameters containing certain characters (e.g. '*' and '?')
  may need to be quoted to prevent the shell interpreting them.

  The basic usage of MultiGIF is as follows:

      multigif [options] files  (or multigif @paramfile)

  This will create a multi-image GIF from the files specified, using all
  default parameters.

  e.g.
      multigif foo.gif bar.gif baz.gif

  The following options are available.  This table can be reproduced by
  invoking MultiGIF with the help (-h) option:

    -b colour       Background colour index (default: 0)
    -c "comment"    Add comment to output GIF file
    -g frame        Use palette from <frame> as a global palette (default: 1)
    -n count        Add a Netscape loop of <count> iterations
    -o file         Output file name (default: multigif.gif)
    -d "n:n:n..."   Delays (1/100s) for each frame.  Frame repetions may be
                    specified as "d*r" - delay <d> for <r> frames
    -r "n:n:n..."   Replace modes for each frame, specified as above
                    0/1 - None, 2 - Background, 3 - Restore
    -x "n:n:n..."   X position of frame (default: 0), specified as above
    -y "n:n:n..."   Y position of frame (default: 0), specified as above
    -l "f,f,f..."   List of frames to have a local palette.  Range: "a-b"
    -u "f,f,f..."   List of frames to require user input 
    -v              Verbose mode
    -h              This help


  BACKGROUND COLOUR: -b colour

    A GIF image can have a colour specified as the background colour.  
    This is the index number of the colour in the global colour table.  
    By default, this is set to colour 0, the first colour (usually black) 
    in the colour table.  Legal values are in the range 0-255.  The 
    background colour is only valid if the GIF has a global colour table.  
    MultiGIF always adds a global colour table to the destination image.

    e.g. 
        multigif -b 5


  COMMENT: -c "comment"

    A GIF image can have any number of comment blocks added to it.  This 
    allows the creator or manipulator of an image to add information such 
    as copyright notice, name, date, etc.   MultiGIF currently only allows 
    one user-defined comment block to be added.

    e.g.
        multigif -c "Cool Fire (C) 1996 Andy Wardley"


  GLOBAL PALETTE: -g frame

    MultiGIF adds a global palette to the output file.  This is the colour 
    table which images will use if they don't specify their own local 
    palette.  By default, MultiGIF will use the palette from the first image
	(frame 1) as the global palette.  The -g option specifies the source 
	image number from which the palette should be taken.  Note that the 
	first image specified is image 1, not 0.

    e.g. 
        multigif -g 2 a.gif b.gif c.gif

    In this example, MultiGIF will use the global palette (or local palette
	if it has one) from image 2 (b.gif).


  NETSCAPE LOOP: -n count

    GIF images can contain "Application Extension Blocks" which allow
    the image creator or manipulator to add information specific to a 
    certain application.  Netscape have used this feature in their Navigator 
    v2.0+ browser to specify a "repeat loop" count.  
  
    MultiGIF, when invoked with the -n option will add a Netscape specific
    Application Extension Block to the output GIF file which tells Netscape 
	Navigator to repeat the animation a number of times.  Note that  
	Navigator version 2.0 ignores this value and loops indefinately but the 
    repetition count is supported in versions 3.0+.  A loop count of 0 
    indicates an indefinite loop, although this is not recommended.  
  
    Note also that Netscape Navigator only repeats the image if the cache 
    is enabled (Options|Network Preferences|Cache) to avoid reloading the 
    image across the network.

    e.g.
        multigif -n 25


  OUTPUT FILE: -o file

    By default, MultiGIF creates an output image named "multigif.gif".  
    Use the -o option to specify an alternate name.  This name should 
    conform to your platform specific file naming conventions.  No checks 
    are made by MultiGIF as to the suitability of the filename, due to the
    cross-platform nature of MultiGIF.

    e.g.
        multigif -o coolfire.gif


  DELAYS: -d "n:n:n..."

    Each image within a multi-GIF file can have a delay associated with 
    it.  This specifies the time, in hundredths of a second (1/100s), that 
    should elapse before the image is displayed.  This value effectively 
    controls the speed of the animation.  By default, a delay of 0 is used.

    Delays should be specified for each frame, seperated by colons (:).
    Empty values, or values for frames not specified will default to 0.
    To specify the same value for a number of frames, use the "delay*rep"
    syntax.  For example, to indicate a delay of 0.25s for 5 frames, you
    would specify "25*5".

    e.g. 
        multigif -d "100:25*3:200" a.gif b.gif c.gif d.gif e.gif

    The image a.gif (frame 1) will have a 1s delay, b.gif (2), c.gif (3) 
    and d.gif (4) will all have delays of 0.25s and e.gif (5) will have a 
    2s delay.
  

  REPLACE MODE: -r "n:n:n..."

    After the image has been displayed, the replace mode specifies how 
    it should be removed.  This is specified for each frame in a colon
    seperated list as per frame delays, described above.  Frame 
    repetitions (mode*rep) may be used.

    The replace modes are specified as a number in the range 0-3.  These 
    numbers indicate the following modes:

        0 - Not specified    No action (image is left on screen)
        1 - None             No action (image is left on screen)
        2 - Background       Image is replaced with background colour
                             or image.
        3 - Restore          Image is replaced with previous contents
                             of the image area.

    Note that option 3 (Restore) where the image is replaced with the 
    saved contents of whatever it was displayed over, is not yet
    supported on any known web browser.  Images with transparent colours 
    may have problems when displaying over previous images if the image 
    underneath can be seen through the transparent areas.  Until this 
    is supported in browsers, the only solution is to use Background mode, 
    or insert a frame restoring the previous screen contents.

    e.g.
        multigif -r "0:2*3:0" a.gif b.gif c.gif d.gif e.gif.

    In this example, images a.gif and e.gif (frames 1 and 5) will be left
    on screen and b.gif (2), c.gif (3) and d.gif (4) will be replaced with 
    the background colour or image.


  X-POSITION: -x "n:n:n..."
  Y-POSITION: -y "n:n:n..."

    Each image in a multi-GIF file can be positioned at an offset 
    relative to the top-left corner.  This allows small sub-sections of 
    the image to be added as frames, rather than repeating the entire 
    image for each frame.  X and Y positions are specified as colon 
    delimited lists, with optional repetition counts (pos*rep) as 
    described above.

    Note that the total image size will be as large as is required to 
    place all images in their entirety.  This avoids a bug in Netscape 
    which occurs when an image, or part of an image, is positioned 
    outside the "global" GIF area specified in the image header.

    e.g.
        multigif -x "0:48*3:50" -y "0:24*3:60" a.gif b.gif c.gif d.gif e.gif

    In this example, a.gif (frame 1) is positioned at XY 0,0, b.gif (2), 
	c.gif (3) and d.gif (4) are all positioned at XY 48,24, and e.gif (5) 
	is positioned at XY 50,60.


  LOCAL PALETTE FRAME: -l "f,f,f..."

    By default, images in a multi-GIF file created by MultiGIF will use
    the global palette.  You can specify that images should use their own
    local palette with the -l option.  The parameter should be s comma
    seperated list of frame numbers.  Frame numbers are identified by 
    the order the source filenames are presented on the command line, 
    starting at 1.  A range of frames may be specified using a hyphen.
    For example "3-5" indicates the frames 3, 4 and 5.
  
    e.g. 
        multigif -l "1,3-5" a.gif b.gif c.gif d.gif e.gif

    Local palettes would be used for the frames built from files a.gif 
    (frame 1), c.gif (3), d.gif (4) and e.gif (5).  The image b.gif (2) 
    would use the global palette which would, by default, be the palette
	taken from the first frame (a.gif).


  USER INPUT: -u "f,f,f..."

    The GIF standard specifies that a User Input Flag can be set for each 
    image.  This requires the user to intervene (say, by pressing a key) 
    before the image is displayed.  Although browsers do not currently 
    support this feature, it is supported by MultiGIF.  Frames requiring 
    user input should be specified as a comma-delimited list of frame 
    numbers, with optional ranges, as described about.

    e.g.
        multigif -u "1,3-5"


  VERBOSE MODE: -v

	MultiGIF running in verbose mode displays information about the 
	source and destination images as it processes them.


  HELP: -h

	Help mode displays a summary of command options as shown above.


OTHER INFORMATION

  MultiGIF maintains the transparency and interlace conditions of source
  files as is incorporates them.  The image size of the resulting GIF
  file will be as large as is necessary to fully incorporate all source
  images.  Options specified for frames that do not exist (e.g. specify
  delay values for 5 frames, but only provide 3 source GIF filenames)
  will be ignored.


COMPILING MULTIGIF

  MultiGIF is written in portable C and should compile without problem
  with any ANSI-compliant C compiler.  A Makefile is provided for your
  convenience.  Edit the Makefile to set any options (see the comments
  in the Makefile) and then run "make".

  If you experience any problems building MultiGIF, consult your local
  man pages first, C (or UNIX/PC/etc) guru next, and finally myself.
  If the problem is due to a bug in the code or an error on my part,
  please let me know.


GIFINFO

  The source archive for MultiGIF also contains a simple utility, Info,
  which reads and displays information about a GIF file, including 
  multiple images.  Simple run Info with the filename of the GIF file
  you wish to examine.

  e.g.
	  gifinfo coolfire.gif


CREDITS

  MultiGIF was written with reference to the "Encyclopedia of 
  Graphics File Formats" by James D. Murray and William vanRyper, 1994 
  O'Reilly and Associates, ISBN 1-56592-058-9.

  Thanks to Royal Frazier (http://members.aol.com/royalef) for his GIF 
  Animation tutorial pages, and to Samiel (http://www.fastlane.net/~samiel)
  for his utility GIFMAKE which inspired me to write MultiGIF.


AUTHOR INFORMATION

  MultiGIF was written by Andy Wardley.  
  
  Please contact me (preferably by email) if you have any comments, 
  criticisms, suggestions or even praise!

  Email: 

      abw@peritas.com

  On the Web:

      http://www.peritas.com/~abw                  (Home Page)
      http://www.peritas.com/~abw/multigif.html    (MultiGIF page)

  On the Planet (to send money, gifts, postcards, etc.):

      Andy Wardley
      c/o Peritas Multimedia
      Beaumont
      Burfield Road
      Old Windsor
      Berkshire.
      SL4 2JP
 
