home *** CD-ROM | disk | FTP | other *** search
/ Simtel MSDOS 1992 December / simtel1292_SIMTEL_1292_Walnut_Creek.iso / msdos / gif / gifdoc.arc / ENGIF.DOC < prev    next >
Text File  |  1988-04-13  |  18KB  |  482 lines
  1. .PL
  2.                   ENGIF TURBO PASCAL UNIT DOCUMENTATION
  3.  
  4.  
  5.  
  6. 1.0 INTRODUCTION
  7.  
  8.      ENGIF is a Turbo Pascal Unit to encode graphic images stored in 
  9. CompuServe's Graphic Interchange Format (GIF).  With this unit you can write 
  10. your own GIF encoder or add GIF to any application.  With its companion unit 
  11. DEGIF you can write GIF utilities to re-encode existing images.  "GIF" and 
  12. "Graphic Interchange Format" are trademarks of H & R Block, Inc.  The GIF 
  13. standard itself is in the public domain.
  14.  
  15.      This unit is fully documented but we will not release the source code 
  16. at this time.  This is a shareware product with a registration fee of $25 
  17. payable to Cyborg Software Systems, Inc.  3119 Cossell Drive, Indianapolis, 
  18. IN 46224.  If you are already registered for DEGIF, you need not register 
  19. ENGIF.   In future releases the two units will be distributed as a single 
  20. package.  This unit, the documentation and the source and executable code 
  21. for RELACE are all Copyright 1988 by Cyborg Software Systems, Inc.
  22.  
  23.      You may use this material for personal non-commercial use.  If you like 
  24. it we ask you to register it.  If you distribute it for free you must 
  25. distribute it in its original ARC form with all files intact.  If you 
  26. distribute it for a fee or if you wish to use ENGIF in any commercial 
  27. application or custom programming written for fee or under contract, you 
  28. must register it.  Violation of the above terms infringes our copyright.  
  29. Registered users will receive the next update free of charge.  Further 
  30. updates will cost registered users $5.
  31.  
  32.      Parts of this code are very loosely based on ENCODE.INC by Bob Berry 
  33. which was a Turbo Pascal 3.0 translation of routines written in C by Steve 
  34. Wilhite.  Sincere thanks and credit to them.
  35.  
  36.      If all you are interested in is the RELACE utility then it is used by 
  37. simply typing....
  38.  
  39. C:\>RELACE IN.GIF OUT.GIF
  40.  
  41.      .....where IN.GIF is a GIF file to be laced or un-laced and OUT.GIF is 
  42. the output file.  WARNING: DO NOT SPECIFY THE SAME FILE!  OUT.GIF is 
  43. overwritten and can be destroyed.  This is just a simple demo.  Its not a 
  44. foolproof professional program.
  45.  
  46. 2.0  GIF ENCODING
  47.  
  48.      The best way we know to document the ENGIF unit is to give an example 
  49. program called RELACE.  RELACE is a utility which will run on any IBM PC 
  50. compatible regardless of graphic cards.  It uses the DEGIF unit to decode an 
  51. image to memory and then uses ENGIF to re-encode it.  You are given the 
  52. option to interlace non-interlaced images or un-lace interlaced images -- 
  53. hence the name RELACE.  If you do not already have a copy of the DEGIF unit 
  54. and documentation, we suggest you obtain them from the same source as you 
  55. obtained ENGIF.
  56.  
  57.      You should print out a copy of RELACE.PAS and follow it along its main 
  58. routine as we go.
  59.  
  60.  
  61. Copyright (c) 1988 Cyborg Software Systems, Inc.             page 1.
  62.                   ENGIF TURBO PASCAL UNIT DOCUMENTATION
  63.  
  64.  
  65.  
  66. 2.1 Initialization
  67.  
  68.      The ENGIF unit requires that you establish a pointer to your procedure 
  69. WrtByte.  WrtByte must be a far-call procedure to write one byte to the 
  70. output file.   We will discuss this routine in section 3.0 below.  
  71. AddrWrtByte is a global pointer declared in the ENGIF unit but you must 
  72. initialize it.  AddrGetByte and AddrPutByte are required by the DEGIF unit.
  73.  
  74.      The next few lines of RELACE's main routine engage the CRT unit and 
  75. prints the copyright notice.  A file name is retrieved from the command line 
  76. or the user is prompted for one.  Names for the source and destination files 
  77. are retrieved from the command line or you are prompted for them.  The files 
  78. are opened.
  79.      
  80.      Because ENGIF "uses" DEGIF, many of DEGIF's types, variables and 
  81. routines are needed by ENGIF too.  The DEGIF unit defines the following....
  82.  
  83.           Type MapType=(Global,Local);
  84.  
  85.      GIF files may or may not have a global color map and or a local color 
  86. map for multiple image files.  DEGIF and ENGIF need the variable 
  87. CurMap:MapType to be initialized before you begin.
  88.  
  89. 2.2 Procedure PutGIFSig
  90.  
  91.      All valid GIF files begin with a 6 byte signature.  The DEGIF unit 
  92. provides a procedure GetGIFSig to retrieve it.  After calling GetGIFSig the 
  93. global string GIFSig should contain the string.  As of this writing (March 
  94. 1988) the only valid string is 'GIF87a'.  Similarly ENGIF provides PutGIFSig 
  95. to write the signature to the output file.  If you are not using GetGIFSig, 
  96. you should use the following....
  97.    
  98.      Gifsig:='GIF87a';
  99.      PutGIFSig;
  100.  
  101. 2.3 Procedure PutScrDes
  102.  
  103.      Following the GIF signature in a GIF file is the screen description.  
  104. The DEGIF unit provides a procedure GetScrDes to retrieve it and initialize 
  105. several global variables.  PutScrDes in the ENGIF unit is used to write a 
  106. screen description.  Unlike PutGIFSig, PutScrDes does not simply write back 
  107. the variables which GetScrDes read because you may wish to write different 
  108. values with ENGIF while maintaining the DEGIF variables.  The PutScrDes 
  109. routine is passed the following parameters.
  110.  
  111.      procedure PutScrDes(SW,SH,BC,CR,PR:word;ME:boolean);
  112.  
  113.      ScreenWidth and ScreenHeight (or SW and SH) are type Word and contain 
  114. the screen width and height in pixels.  All images in this file will fit in 
  115. this virtual screen space.  Its up to you to scale or clip the image if it 
  116. doesn't fit the global screen size you specify.
  117.  
  118.      Some GIF files are composed of multiple small images that may overlap 
  119.  
  120.  
  121. Copyright (c) 1988 Cyborg Software Systems, Inc.             page 2.
  122.                   ENGIF TURBO PASCAL UNIT DOCUMENTATION
  123.  
  124.  
  125. or may not fill the screen.  The standard says you should first fill in a 
  126. background before plotting the images.  Some decoders don't bother.  They 
  127. leave the background black.  DEGIF gives you BackgrColorIndex which tells 
  128. you what color to paint the background.  You should use BC to pass the index 
  129. of the background color you want.
  130.  
  131.      BitsOfColorPerPrimary (or CR meaning "Color Resolution") is a Word but 
  132. the only valid values are [1..8].  I was just too lazy to declare it as a 
  133. byte or sub-range type <heheh>.  It is the topic of much debate among GIF 
  134. developers as to what should be put there and how useful it is.  It isn't 
  135. necessary for most decoding and my experience is it is unreliable.  As an 
  136. example, for EGA created images its value should be 2 because each primary 
  137. color (red, green and blue) is designated by 2 bits.  
  138.  
  139.      BitsPerPixel[Global] (or PR meaning "Pixel Resolution") is a Word that 
  140. does tells you the number of colors in the color map.  It is also necessary 
  141. for ENGIF's compression routine to establish a minimum code size.  The only 
  142. valid values are [1..8].  The number of colors in the global color map is 
  143. computed by...
  144.  
  145.      NumberOfColors[Global]:= (1 shl BitsPerPixel[Global]);
  146.  
  147.      This means GIF color maps always contain 2, 4, 8, 16, 32, 64, 128 or 
  148. 256 entries.  The image may not actually contain that many colors.  It may 
  149. use fewer.  I have no problem with 16 color images that contain only 10 or 
  150. 12 colors.  It really raises my dandruff when I download 256 color images 
  151. with 31 colors!!!  Editorial over.
  152.  
  153.      MapExists[Global] (or ME) is a boolean that tells you if there is a 
  154. global color map for this file.
  155.  
  156.      Next, RELACE builds a virtual screen on the heap and initializes it to 
  157. the background color.  It then calls DisplayScrDes.  This is its own routine 
  158. which simply tells the user the information from the screen descriptor.  If 
  159. you intend to modify any of the screen description, this is where you would 
  160. do it.  Finally we call PutScrDes.  RELACE does simply pass on the values 
  161. obtained by DEGIF but many other applications of ENGIF might make changes.
  162.  
  163. 2.4 Procedure PutColorMap
  164.  
  165.      The GIF standard provides for an optional global color map.  Most GIF 
  166. files contain one.  GetScrDes sets the boolean MapExists[Global] to true if 
  167. there is a global map.  If you passed ME=true to PutScrDes then you must 
  168. have one too.  The map is put in the following arrays....
  169.  
  170.      RedValue,GreenValue,BlueValue: array [0..255] of byte;
  171.  
  172.      These global arrays are declared in DEGIF and if you change them you 
  173. lose the old values.  This probably will not be a problem.  Only index 
  174. values in the range [0..NumberOfColors[Global]-1] are defined.  They are 
  175. intensity values from [0..255] for the red, blue and green components of the 
  176. color.
  177.  
  178.      See the DEGIF documentation for more details on the color maps. 
  179.  
  180.  
  181. Copyright (c) 1988 Cyborg Software Systems, Inc.             page 3.
  182.                   ENGIF TURBO PASCAL UNIT DOCUMENTATION
  183.  
  184.  
  185.  
  186.      The PutColorMap routine in ENGIF writes the values from those arrays.  
  187. It requires that CurMap and NumberOfColors[CurMap] have the proper values.
  188.  
  189. 2.5 Writing blocks
  190.  
  191.      Its time now to get down to actual encoding!   The next thing to appear 
  192. in a GIF file is a block.  There are currently only two types.  Image blocks 
  193. are preceded by a comma.  Extension blocks are preceded by an exclamation 
  194. point.  GIF files are terminated by a semi-colon.  Any characters other than 
  195. a ';' or a ',' or '!' may be ignored.  ENGIF currently has no facility for 
  196. writing extension blocks so RELACE uses DEGIF's SkipExtendBlock routine.  
  197. Currently no extension blocks are defined.  
  198.  
  199. 2.6 Procedure PutImageDescription
  200.  
  201.      After finding an image block which begins with a comma, RELACE does...
  202.  
  203.      WrtByte(ord(','));
  204.  
  205.      ... and reads the image description using GetImageDescription.  The 
  206. image description is output with...
  207.  
  208.      procedure PutImageDescription(IL,IT,IW,IH,PR:word;ME,ITL:boolean);
  209.  
  210.      ImageLeft and ImageTop (or IL and IT) define the coordinates of this 
  211. image relative to the screen description.  A value of 0,0 is the upper left 
  212. corner of the screen.
  213.  
  214.      ImageWidth and ImageHeight (or IW and IH) give the dimensions of this 
  215. image.  The image may overlap previous images.  It may or may not fill the 
  216. screen.  It should never exceed the screen description.
  217.  
  218.      BitsPerPixel[Local] (or PR for Pixel Resolution) and 
  219. NumberOfColors[Local] tell you the same things about the local map that 
  220. their global brothers tell you about the global map.
  221.  
  222.      MapExists[Local] (or ME) is a boolean that tells you if a local color 
  223. map exists for this image.  
  224.  
  225.      Our AdjustImage routine prompts you to determine whether or not the 
  226. output file should be interlaced.  It sets the variable LaceIt.  Note that 
  227. the variable Interlaced tells whether or not the input image is laced and 
  228. LaceIt (passed as ITL) controls the output image.  See section 3.2 for a 
  229. discussion of interlaced images.
  230.  
  231.      If you have a local color map then you must call GetColorMap and 
  232. PutColorMap with CurMap:=Local.
  233.  
  234. 2.7 Procedures CompressGIF(Pix) and EndCompress
  235.  
  236.      The data blocks which follow are the image data index values compressed 
  237. in a variable length 12 bit-maximum modified LZW compression scheme.
  238.  
  239.  
  240.  
  241. Copyright (c) 1988 Cyborg Software Systems, Inc.             page 4.
  242.                   ENGIF TURBO PASCAL UNIT DOCUMENTATION
  243.  
  244.  
  245.      HUH?
  246.  
  247.      That's what I said when I first became a GIF developer.  They just 
  248. handed me a bunch of code written in "C" by Steve Wilhite.  They said just 
  249. use this code and everything will be ok.  There was one problem.  I don't 
  250. know "C"!  Enter Bob Berry who sees C and Pascal.  My first GIF decoder used 
  251. his Turbo Pascal 3.0 translation from Wilhite's "C".  I plugged.  It 
  252. chugged.  Out came GIF!  Presto!  
  253.  
  254.      Since then I've rewritten DEGIF's ExpandGIF several times on my own and 
  255. I understand "image data index values compressed in a variable length 12 bit 
  256. maximum modified LZW compression scheme."
  257.  
  258.      But you don't need to.
  259.  
  260.      DEGIF's ExpandGIF calls your GetByte routine to get compressed data one 
  261. byte at a time.  It does all the magic by calling your PutByte routine to 
  262. put the dots on the screen.
  263.  
  264.      When the entire image is done ExpandGIF returns an integer.  Anything 
  265. other than a 0 is an error.
  266.  
  267.      To compress the GIF image we simply call CompressGIF repeatedly passing 
  268. the image bytes to it.  When we are done we call EndCompress which clears 
  269. the compression buffer and terminates the image block.   See section 3.2 for 
  270. RELACE's method of outputing interlaced images.
  271.  
  272. 2.8 Terminator
  273.  
  274.      When you've output all the images, you should write a GIF terminator 
  275. by...
  276.  
  277.      WrtByte(ord(';'));
  278.  
  279.      ...and close the output file.
  280.  
  281. 3.0 ROUTINES YOU PROVIDE
  282.  
  283.      Routines like DisplayScreenDescription and AdjustImage are so totally 
  284. your responsibility that we really can't say much more about them because 
  285. you may want to do them differently.  The WrtByte, GetByte and PutByte need 
  286. more explanation.
  287.  
  288.      DO NOT FORGET TO INCLUDE THESE LINES!
  289.  
  290.            AddrWrtByte:=@WrtByte;
  291.            AddrGetByte:=@GetByte;
  292.            AddrPutByte:=@PutByte;
  293.  
  294. 3.1 Procedure WrtByte(I:integer);
  295.  
  296.      You must provide a procedure WrtByte which outputs bytes to the output 
  297. file.  This function must be a far function and is compiled with the {$F+} 
  298. directive.  The simplest WrtByte is..
  299.  
  300.  
  301. Copyright (c) 1988 Cyborg Software Systems, Inc.             page 5.
  302.                   ENGIF TURBO PASCAL UNIT DOCUMENTATION
  303.  
  304.  
  305.  
  306. {$F+}
  307. procedure WrtByte(I: integer);
  308.  var B:byte;
  309.  begin
  310.   B:=lo(I);  write(OutFile,B)
  311.  end;
  312. {$F-}
  313.  
  314. 3.2 Interlacing images
  315.  
  316.      If you want your images interlaced, you must pass bytes to CompressGIF 
  317. in the proper order.  You pass a byte that is the index to the color array.  
  318. That color will eventually be plotted at location x,y.  The catch is what 
  319. are x and y?
  320.  
  321.      On non-interlaced images you just start at XCord:=ImageLeft and 
  322. YCord:=ImageTop.  You pass points along Y and increment X until you've 
  323. plotted ImageWidth of them.  That is until XCord=ImageLeft+ImageWidth.  Then 
  324. you reset X to ImageLeft, increment Y and plot the next line.
  325.  
  326.      Interlaced images start with YCord:=ImageTop but they make 4 interlaced 
  327. passes.  Pass 1 begins at ImageTop+0 and plots every 8th line.  Pass 2 
  328. starts at ImageTop+4 and also plots every 8th line.  Pass 3 starts at 
  329. ImageTop+2 and plots every 4th line.  Pass 4 starts at ImageTop+1 and plots 
  330. every other line.  These 4 passes fill the screen.
  331.  
  332.      In RELACE the PutByte routine and the "repeat until" structure in the 
  333. main routine both deal with interlacing.  For non-interlaced images I 
  334. invented a Pass 5 which starts at ImageTop+0 and plots every line.  I simply 
  335. say ... 
  336.  
  337.      if Interlaced then Pass:=1 else Pass:=5;
  338.  
  339.      This fully implements interlaced images.
  340.  
  341. 4.0 INTERFACE
  342.  
  343.      Because ENGIF uses DEGIF you will have access to both ENGIF's variables 
  344. and routines as well as ENGIF's.
  345.  
  346. 4.1 DEGIF interface
  347.  
  348.      Here is the interface section of the DEGIF unit.
  349.  
  350. unit degif;
  351. interface
  352.  
  353. type MapType=(Global,Local);
  354.  
  355. var  GIFSig:String[6];        {GIF ID string usually = 'GIF87a'}
  356.      CurMap:MapType;          {Current Map in use}
  357.      BitsPerPixel,            {in this image}
  358.      NumberOfColors           {in this image}
  359.  
  360.  
  361. Copyright (c) 1988 Cyborg Software Systems, Inc.             page 6.
  362.                   ENGIF TURBO PASCAL UNIT DOCUMENTATION
  363.  
  364.  
  365.        :array [Global..Local] of word;
  366.      BackgrColorIndex,        {Background Color index}
  367.      BitsOfColorPerPrimary,   {For example on EGA=2}
  368.      ImageLeft,             {Left edge of image relative to virtual screen}
  369.      ImageTop,              {Top edge of image relative to virtual screen}
  370.      ImageWidth,              {in pixels}
  371.      ImageHeight,             {in pixels}
  372.      ScreenHeight,            {in pixels}
  373.      ScreenWidth:word;        {in pixels}
  374.      MapExists:array [Global..Local] of boolean;
  375.      Interlaced:boolean;
  376.      AddrGetByte,             {Pointer to user supplied GetByte}
  377.      AddrPutByte:pointer;     {Pointer to user supplied PutByte}
  378.      RedValue,GreenValue,BlueValue: array [0..255] of byte;
  379.      Color:    array [Global..Local,0..255] of byte;
  380.  
  381. function ExpandGif: integer;
  382.  
  383. procedure GetColorMap;
  384.  
  385. procedure GetGIFSig;
  386.  
  387. procedure GetImageDescription;
  388.  
  389. procedure GetScrDes;
  390.  
  391. procedure SkipExtendBlock;
  392.  
  393. 4.2 ENGIF interface
  394.  
  395.      Here is ENGIF's interface....
  396.  
  397. unit engif;
  398.  interface
  399.   uses degif;
  400.   var
  401.    AddrWrtByte:pointer;    {Pointer to user supplied WrtByte}
  402.  
  403.    procedure CompressGIF(Pix: byte);
  404.  
  405.    procedure EndCompress;
  406.  
  407.    procedure PutColorMap;
  408.  
  409.    procedure PutGIFSig;
  410.  
  411.    procedure PutImageDescription(IL,IT,IW,IH,PR:word;ME,ITL:boolean);
  412.  
  413.    procedure PutScrDes(SW,SH,BC,CR,PR:word;ME:boolean);
  414.  
  415. 5.0 FINAL WORDS
  416.  
  417.      This unit is written entirely in Turbo Pascal 4.0 and contains no 
  418. assembler or Inline code.  My #1 goal was to get this available as soon as 
  419.  
  420.  
  421. Copyright (c) 1988 Cyborg Software Systems, Inc.             page 7.
  422.                   ENGIF TURBO PASCAL UNIT DOCUMENTATION
  423.  
  424.  
  425. possible.  My #2 goal will be to make it fast.  After that I'll add 
  426. extension block support and any new extensions to the GIF87a standard.
  427.  
  428.      To make it worth my trouble I need your support.  Please show your 
  429. appreciation and register this product.
  430.  
  431.  
  432.  
  433.  
  434.  
  435.  
  436.  
  437.  
  438.  
  439.  
  440.  
  441.  
  442.  
  443.  
  444.  
  445.  
  446.  
  447.  
  448.  
  449.  
  450.  
  451.  
  452.  
  453.  
  454.  
  455.  
  456.  
  457.  
  458.  
  459.  
  460.  
  461.  
  462.  
  463.  
  464.  
  465.  
  466.  
  467.  
  468.  
  469.  
  470.  
  471.  
  472.  
  473.  
  474.  
  475.  
  476.  
  477.  
  478.  
  479.  
  480.  
  481. Copyright (c) 1988 Cyborg Software Systems, Inc.             page 8.
  482.