home *** CD-ROM | disk | FTP | other *** search
/ DP Tool Club 8 / CDASC08.ISO / NEWS / 439 / LOADGIF / LOADGIF.DOC < prev    next >
Text File  |  1993-10-07  |  8KB  |  182 lines
  1.  
  2.         Documentation for LOADGIF.OBJ & ERROR.OBJ v1.0
  3.  
  4.         By Rich Geldreich, August 20, 1993
  5.  
  6. DESCRIPTION
  7.  
  8.         LoadGIF  is a fast QB/PDS/VBDOS callable assembly function which
  9. loads GIF format images onto the screen.
  10.  
  11. FUNCTION LoadGIF
  12.  
  13.         Loads a GIF format image file onto a 16 color or 256 color video
  14.         screen. The following parameters are expected:
  15.  
  16.         MemPointer  -   Pointer to a block of memory for LoadGIF's use.
  17.                         Use the LoadGIFMem function to find the amount of
  18.                         memory required. (I've assembled LoadGIF to require
  19.                         about 16k of memory.)
  20.  
  21.         FileOfs     -   Offset and segment of zero terminated GIF filename.
  22.         FileSeg
  23.  
  24.         ScrType     -   Set to zero for 16 color modes.
  25.                         Set to one for mode 13.
  26.                         Set to two for the "mode x" video modes. (Meant
  27.                         to be used with Matt Pritchard's MODEX graphics
  28.                         library, but should work fine with any MODEX
  29.                         graphics lib.)
  30.  
  31.         ScrOffset   -   Offset to use when writing to screen memory.
  32.                         Normally  zero  unless  you  want  to  write  to
  33.                         another page of video memory. The table below
  34.                         gives formulas for calculating a page's offset
  35.                         for common video modes.
  36.  
  37.         ScrWidth    -   Bytes per line. See table below for screen widths of
  38.                         various video modes.
  39.  
  40.         XRes        -   Screen's boundries. A 320x200 screen would be
  41.         YRes            specified as 319x199, for instance. 640x480 =
  42.                         639x479, etc.
  43.  
  44.         X0          -   These coordinates specify a "viewing window" for
  45.         Y0              the GIF's image. Any points outside of this window
  46.         X1              will not be plotted. Useful for only displaying part
  47.         Y1              of the image. This window is clipped to the screen's
  48.                         boundries.
  49.  
  50.         XOrg        -   These coordinates specify where the image's upper
  51.         YOrg            left hand corner will go. Negative values are valid.
  52.  
  53.         AdapterType -   This parameter selects either an EGA or VGA palette.
  54.                         0  =  Call the EGA BIOS to set the palette.
  55.                               (Two bits per RGB component.)
  56.                         1  =  Call the VGA BIOS to set the palette.
  57.                               (Six bits per RGB component.)
  58.  
  59.                         An EGA palette can only be specified for 16 color
  60.                         modes.
  61.  
  62.         PalIgnore   -   If this parameter is not zero then the palette in
  63.                         the GIF file will not be set.
  64.  
  65.         PalSeg      -   Offset & segment of where the image's palette
  66.         PalOfs          is to be placed in memory. If you do not wish
  67.                         to retrieve the image's palette, set PalSeg
  68.                         to zero.
  69.  
  70.                         The area of memory  will  be  filled  with  3  *
  71.                         numcolors  bytes,  where numcolors is the number
  72.                         of colors stored in the  first image of the GIF.
  73.                         For instance, a 256 color GIF image requires 768
  74.                         bytes of memory for palette storage.  If you are
  75.                         unsure of how many colors a GIF image  contains,
  76.                         set  aside  the maximum amount (768 bytes) to be
  77.                         safe.
  78.  
  79.                         Each byte stored ranges from 0-255. The order
  80.                         of storage is red, green, then blue.
  81.  
  82.                         If no global palette existed in the GIF file, no
  83.                         information will be stored.
  84.  
  85.         PalColors    -  The LoadGIF function returns the number of colors
  86.                         the GIF image contained in this variable.
  87.  
  88.                         If  the  GIF  file  did  not  contain  a  global
  89.                         palette, then a negative value will be returned.
  90.                         For instance, if  the  GIF  image  contained  16
  91.                         colors,  but a global palette did not exist, the
  92.                         value returned  in  this  variable  will be -16.
  93.  
  94.         LoadGIF will  return  a  -1  if  any  error  occured.   Call the
  95. ErrorReport function to locate the source of the error.
  96.  
  97.         The following chart shows  the  parameters that should be passed
  98. for various video modes:
  99.  
  100.     SCREEN #    ScrType     ScrOffset   ScrWidth    XRes    YRes
  101.     --------    --------    ----------  ---------   -----   -----
  102.        7           0        Page*8192      40        319     199
  103.  
  104.        8           0        Page*16384     80        639     199
  105.  
  106.        9           0        Page*32768     80        639     349
  107.  
  108.        12          0           n/a         80        639     479
  109.  
  110.        13          1           n/a        320        319     199
  111.  
  112.   Mode-X 320x200   1        Page*16000     80        319     199
  113.  
  114.   Mode-X 320x240   1        Page*19200     80        319     239
  115.  
  116.   Mode-X 320x400   1        Page*32000     80        319     399
  117.  
  118.   Mode-X 320x480   1        Page*38400     80        319     479
  119.  
  120.   Mode-X 360x200   1        Page*18000     90        359     199
  121.  
  122.   Mode-X 360x240   1        Page*21600     90        359     239
  123.  
  124.   Mode-X 360x400   1           n/a         90        359     399
  125.  
  126.   Mode-X 360x480   1           n/a         90        359     479
  127.  
  128. FUNCTION ErrorReport
  129.  
  130.         If the ErrorReport function  returns  a  number  from  0-99,   a
  131. critical  disk error occured(drive not ready,  sector not found,  etc.).
  132. Error codes above 99 specify  a  DOS error(102=file not found,  103=path
  133. not found,  etc.   See a DOS reference for a list  of  error  codes  and
  134. meanings).  Negative error codes specify an internal error:
  135.  
  136.         -1          -   Encountered end of file before GIF terminator.
  137.         -2          -   Bad code in GIF file.
  138.         -3          -   Not a GIF file.
  139.         -4          -   Too many colors in GIF file for screen.
  140.         -5          -   Bad image descriptor or GIF too big.
  141.         -6          -   ScrType parameter is bad. Must be 0, 1 or 2.
  142.         -7          -   AdapterType parameter is bad or EGA palette
  143.                         specified for a 256 color VGA mode.
  144.  
  145.         The ErrorReport function  does  not  clear  the  internal  error
  146. variable, so this function may be called repeatedly.
  147.  
  148. FUNCTION LoadGIFMem
  149.  
  150.         Returns  the  number of pages of memory required by LoadGIF.  (A
  151. page of memory is 16 bytes long.)
  152.  
  153. The sample program TEST.BAS will load  a  GIF  image  specified  on  the
  154. command line onto the VGA's 320x200x256 video mode.
  155.  
  156. NOTES
  157.  
  158.         The  LoadGIF  function  was written for my own uses, and was not
  159. originally intented for public release.   The function is NOT a complete
  160. implementation of the GIF89a standard.  In other words, the function was
  161. not designed for general purpose use.  If you want a  full  fledged  GIF
  162. viewer, grab a copy of VPIC, GDS,  or CSHOW.  LoadGIF is best suited for
  163. displaying a set of tested, pre-chosen images.
  164.  
  165.         The LoadGIF function is public domain.  Use as you wish.  I have
  166. included the complete assembly source code to it, just in case you  wish
  167. to  study  or  modify it.  Please keep in mind that I did not intend for
  168. anybody to see this  code,  so  don't  puke  if  you see anything really
  169. stupid!   Also  beware  that  I  love using self modifying code.  (Don't
  170. worry, I didn't use any  "unsafe"  self modifying code that gets screwed
  171. up by the prefetch queue.)
  172.  
  173.         The file LOADGIF.QLB was linked for QuickBASIC 4.5.  You'll have
  174. to relink  this  file  for  PDS  or  VBDOS.   The  files LOADGIF.OBJ and
  175. ERROR.OBJ must be in the quick library.
  176.  
  177.         Finally,  for  those of you who try to make the LoadGIF function
  178. callable from a language  other  than  QuickBASIC,  beware that the code
  179. assumes that SS=DS on entry into the LoadGIF function.  Line #517  takes
  180. advantage of this.
  181.  
  182.