




                               TIFF256
                          Graphics Library
                             Extensions
                                  
                          For C Programmers
                                  
                             Version 4.0
                            June 24, 1995
                                  
                                  
                 Copyright Spyro Gumas, 1992 - 1995.
                         All Rights Reserved
                                  
                                  
                                  
                                  
                                  
                                  
                 Look what You get for Registering!!

          -    Royalty Free Use of TIFF256 in Your Programs!
          -    3D Graphics Library!
          -    Graphics Mouse Library!
          -    Joystick Library & Source Code!
          -    Image Processing Library & Source Code!
          -    32 Bit WATCOM C Compiler compatible library!
          -    On line support through CompuServe!
          -    Printed Users Manual and Software Disk!
          -    Half Price upgrade to next version!

               (See Page 6 for Details)


















                                  
1.0 Introduction                                       3
  1.1 Revision History                                 4
  1.2 Benefits of Registering                          6
  1.3 Distribution Files                               7
  1.4 Some TIFF Insight                                7
2.0 The TIFF256 Extensions Environment                 8
  2.1 Using The TIFF256 Extensions                     8
  2.2 Global Graphics Parameters                       8
  2.3 Compiler Compatibility                           9
  2.4 Support of TIFF 5.0                              9
3.0 TIFF256 Extensions Functionality                   12
  3.1 Handling The Color Look Up Table                 12
  3.2 Function Descriptions                            13
     3.2.1 tf_set_true_color_mode                      13
     3.2.2 tf_get_true_color_mode                      14
     3.2.3 tf_open_file                                14
     3.2.4 tf_close_file                               15
     3.2.5 tf_get_file_info                            16
     3.2.6 tf_skip_ifd                                 16
     3.2.7 tf_set_defaults                             17
     3.2.8 tf_read_ifd                                 17
     3.2.9 tf_scan_file                                18
     3.2.10 tf_decode_scan_error                       19
     3.2.11 tf_display_ifd                             20
     3.2.12 tf_display_subimage                        21
     3.2.13 tf_set_compression                         22
     3.2.14 tf_get_compression                         22
     3.2.15 tf_save_file                               22
     3.2.16 tf_image_size                              23
     3.2.17 tf_load_image                              24
     3.2.18 tf_load_subimage                           25
     3.2.19 tf_save_image                              26
     3.2.20 tf_set_prime_colors                        28
4.0 Nitty Gritties                                     29
  4.1 Registration Information                         29
  4.2 Software License                                 30
  4.3 Disclaimer                                       31
  4.4 Technical Support                                31
5.0 Appendix                                           32
  5.1 TIFF.H Include File                              32













                                Page: 2
                                  
1.0 Introduction

      The  TIFF256  Graphics Library Extensions  Version  4.0  is  a
library  of  C routines which extend the capabilities of the  VSA256
Graphics  Library.   With  TIFF256 the C programmer  has  the  tools
necessary  to  read,  display, and write Tagged  Image  File  Format
(TIFF) images using a 256 color video adapter running with the  VESA
BIOS  Extensions.   Support is provided for  both  Microsoft  C  and
Borland C products.  The name "TIFF256" reflects the fact that  this
library  supports the 256 color video modes defined within the  VESA
standard.
      As  the preeminent graphics format, TIFF images have permeated
the fiber of  the computer world.  It is the single most common file
format  supported by virtually all hand held and flat bed  scanners.
While every major computer platform has evolved its own unique image
file  format,  TIFF  is the one standard format  which  crosses  the
boundaries between PC, MAC, Silicon Graphics, Sun, HP, DEC, and  all
the rest.
     The TIFF256 Graphics Library Extensions lets you take advantage
of  TIFF's popularity by letting you integrate TIFF capability  into
your  graphical application.  While powerful and robust, the TIFF256
library is simple to use.  Only a few lines of code are required  to
get  a  TIFF image up on the screen.  One more line of code and  the
image is saved.  (By the way, have you ever tried to write out a BMP
image  under Windows? ... Good night Eunice!)  A few more  lines  of
code  and  you can customize how the software displays 24  bit/pixel
images  on  your  256  color  display, selecting  between  332  RGB,
Dithered,  or  Adaptive  Palette displays.   The  VSA256  /  TIFF256
combination  gives  you a formidable tool for graphical  programming
while sparing you the nightmare of Windows programming.























                                Page: 3
                                  
1.1 Revision History

Version  4.0  adds  Compressed TIFF file handling capabilities  plus
subimage  capabilities so its easy to extract smaller portions  from
big  TIFF files.  The major changes between version 3.0 and 4.0  are
listed below:

  - Added TIFF File Compression:    Now you can  take  advantage  of
  Compressed  TIFF file technology for both reading in  and  writing
  out TIFF files.

  - Added TIFF File Sub Image Extraction capability:    You can read
  in  small  portions  of a larger TIFF image.  This  is  especially
  handy  for a single TIFF file which is a mosaic of ICONS (any  GUI
  writers out there?).

  - Added TRUE_COLOR_MODE 3:    If you need to get your hands on the
  24 bit pixel values of a true color TIFF, set true color mode =  3
  and call 'tf_load_image' or 'tf_load_subimage'.

  - New  routines:

  tf_set_compression   - Turns on compression for saving TIFFs.
  tf_get_compression   - Returns compression flag.
  tf_display_subimage  - Display a sub region of a TIFF file.
  tf_load_subimage     - Load a sub region of TIFF into image buffer
  tf_scan_file         - One command, replaces 5 calls to set up.
  tf_decode_scan_error - Error printer for 'tf_scan_file' status.

Version 3.0 is presented to the general public in the true spirit of
shareware.   This revision is the full-up version  of  the   TIFF256
Graphics  Library  Extensions.  I  no  longer  maintain  a  separate
registered  version  of this library.  Version 3.0  of  the  TIFF256
Graphics  Library  Extensions is presented as  Shareware  with  high
hopes that the programmers who use this library will feel good about
sending  in the registration fee of $29.  The major changes  between
version 2.0b and 3.0 are listed below:

  Added  Adaptive Palette    Now the programmer has  the  option  to
  turn  on Adaptive Palette during the 24 bits/pixel to 8 bits/pixel
  color  reduction.   The  Adaptive Palette feature  calculates  the
  optimum  color palette for each True Color image.  The  result  is
  that the most reduced images retain their True Color look.

  Added  Dithering     The  programmer has the  option  to  turn  on
  dithering   during  the  24  bits/pixel  to  8  bits/pixel   color
  reduction.   Dithering  approximates the  full  16  million  color
  spectrum on 256 color systems through a technique of jittering  or
  dithering  pixel  intensities.   This  technique  is  particularly
  useful when a good adaptive palette can not be generated.

  New  routine, tf_set_true_color_mode    Used to select 8 bit  RGB,
  Dithering,  or  Adaptive  Palette for True  Color  images  and  to
  define the Adaptive Palette configuration.
                                Page: 4
                                  
  New  routine,  tf_get_true_color_mode    Used to get current  True
  Color display mode and Adaptive Palette configuration parameters.
  
  New  routine, tf_image_size    Used to get the size  of  an  image
  for use with next two functions.

  New  routine,  tf_load_image    Now  you  can  read  a  TIFF  file
  directly into an memory buffer instead of having to display it  on
  the  screen first.  Use vsa_put_image to display it on the  screen
  when you are ready.

  New  routine, tf_save_image    With this function you can save  an
  image  already  in a memory buffer to a TIFF file.   You  can  use
  vsa_get_image to copy screen image into memory buffer.

  Clipping  when  TIFF  image displayed  on  screen     This  is  an
  outcome  of  the VSA256 Graphics Library 3.0 upgrade  which  added
  clipping.   You  no longer have to worry about your images  screen
  wrapping.

  Fixed "unresolved external _fstrlen" linker error with Turbo C.

  Made   all   functions  in  TIFF.H  external,  no  more  "Multiple
  Declaration" warnings.

  Changed  name  of  tf_display_image  to  tf_display_ifd      Since
  tf_load_image,  tf_save_image,  vsa_get_image,  and  vsa_put_image
  all  use  'image'  in the context of a memory buffer,  consistency
  demands  this  change.  tf_display_ifd doesn't  deal  with  memory
  buffers  but  goes straight from a TIFF file to the  screen.   For
  compatibility with older versions, tf_display_image  in  old  code
  automatically gets mapped to a call to tf_display_ifd.

  Turned  off  automatic  error message  screen  output     Now  the
  application  can decide whether or not it wants an  error  message
  actually  displayed  by  interpreting the  return  values  of  the
  relevant functions.

Version  2.0b  is  the  REGISTERED version of the  TIFF256  Graphics
Library Extensions.  Whereas the TIFF256 Graphics Library Extensions
Version 1.x is shareware, Version 2.0b IS NOT shareware and may only
be used in accordance with the terms of the purchase agreement.  The
major  change  between version 1.0 and 2.0b is the addition  of  the
routine  called   tf_save_file.  With  this  one  new  routine,  the
programmer may now create a TIFF file from any image generated using
the  VSA256  Graphics  Library  and  the  TIFF256  Graphics  Library
Extensions.

Version  1.0  is  the  original SHAREWARE  version  of  the  TIFF256
Graphics Library Extensions.


                                Page: 5
                                  
1.2 Benefits of Registering

      If  you  use this program beyond an initial evaluation period,
you must register your use with a $29 remittance to the author .. me
($15  if  ordering  VSA256  and  TIFF256  at  the  same  time,   see
ORDER.TXT).   In  addition  to the good feeling  that  you  get  for
sustaining  a  late night hacking obsession, you get  the  following
benefits for registering:

1)        Royalty Free Use of TIFF256 in Your Programs! Feel free to
          distribute your programs for profit with no royalty  fees.
          See section 4.2.

2)        3D  Graphics Library!   Don't live in a flat  world.   Add
          the missing 3rd dimension to your creations.  This library
          lets  you  create  3d objects, set your  view  point,  and
          perform  3d  transformations including scale, offset,  and
          rotation.   Supports wireframe, solid, and Gouraud  shaded
          objects.

3)        Graphics  Mouse Library!   Use this library  to  integrate
          Mouse  input with your graphics applications.  Get precise
          updates  of  mouse  position, update screen  cursor,  read
          mouse  buttons, and more.  Invent your own graphical  user
          interface,  give  your apps that professional  feel,  have
          tons of fun!

4)        Joystick  Library  with Source Code!   Integrate  Joystick
          input  with  your graphics applications.  Write  a  flight
          simulator,  boat driver, or your own unique  use  of  this
          agile input device.

5)        IMP256  Image  Processing Library and Source  Code!   With
          this  library  you  can learn all about image  sharpening,
          embossing, blurring, color balancing, and enhancement.

6)        32  Bit  WATCOM C Compiler compatible VSA256  and  TIFF256
          libraries!  Get the edge on performance.

7)        On line support through CompuServe.

8)        Printed Users Manual and Current Version Software on Disk.

9)        One Half Price Upgrade to the next version, as it  becomes
          available.

                              AND
10)       The following public domain full color TIFF image files to
          get you started:
                         VENUS.TIF
                         EARTH.TIF
                         MOON.TIF
                         MARS.TIF
                                Page: 6
                                  
                         SATURN.TIF
                         NEPTUNE.TIF
                         SHUTTLE.TIF
                         ASTRONTS.TIF
                         WEATHER.TIF
                         MANDRILL.TIF

1.3 Distribution Files

      The  distribution  of the TIFF256 Graphics Library  Extensions
Version  4.0 consists of the 8 files listed below.  These files  are
archived  in  the file TIF256.ZIP.  To extract, just  type  'PKUNZIP
TIF256' in the directory that you want the files extracted to.

TIF_DEMO.C     Demonstration program (Source Code).
TIF_DEMO.EXE   Demonstration program (Executable).
TIF_DATA.EXE   TIFF file analysis program (Executable).
TIFFMSL.LIB    TIFF256 Extensions, Large Memory Model (Microsoft C).
TIFFBCL.LIB    TIFF256 Extensions, Large Memory Model (Borland C).
TIFF.H         Include file required in your program.
TIFF256.TXT    This text document.
ORDER.TXT      A text file order form for upgrades and registration.

1.4 Some TIFF Insight

      A  TIFF  file can contain one or more images.  Each  of  these
images is stored in the file as an "Image File Directory" (an  IFD).
Each IFD consists of numerous fields or "tags".  Each tag defines  a
particular  aspect  of the image (i.e. color model,  width,  length,
resolution,  etc.).  With the TIFF256 Extensions, a  programmer  can
find out how many IFDs are contained within a TIFF file, jump to the
desired  IFD, read all of the tags within the IFD, and  display  the
IFD's image.




















                                Page: 7
                                  
2.0  The  TIFF256  Extensions Environment

2.1 Using The TIFF256 Extensions

      The TIFF256 Extensions work with any (any?) IBM PC, XT, AT  or
compatible  computer  equipped with a  VESA  compatible  SVGA  video
adapter  card capable of 256 colors.  Most  of the video cards  sold
today  are VESA compatible with the VESA BIOS built in to the  card.
For  older SVGA video cards which are not VESA compatible, the  VESA
BIOS  Extensions  must be loaded as a Terminate  and  Stay  Resident
(TSR)   program  before  using  the  TIFF256  Extensions.   A   math
coprocessor  chip  is  not  required.  The  TIFF256  Extensions  are
distributed  as a Large Memory Model library for either Microsoft  C
or Borland C.  If other memory models are required, contact me.
     The TIFF256 Extensions Version 4.0 are used in conjunction with
the  VSA256  Graphics Library Version 4.0.  The following discussion
assumes  that you are adding TIFF capability to an existing  program
which  already uses the VSA256 Graphics Library.  To use the TIFF256
Extensions,  add  the  file  TIFF.H to  your  C  compiler's  default
directory for INCLUDE files, add the statement:

                          #include<tiff.h>;

to  your program, and add the file TIFFBCL.LIB or TIFFMSL.LIB to the
list of files that your program is linked with.

2.2 Global Graphics Parameters

      The  file  TIFF.H  is used as an include file  during  program
development.   This  file includes all of the  extension's  function
prototypes  and it defines the global parameters that  describe  the
TIFF  File and individual IFDs.  The global graphics parameters  are
initialized by the tf_scan_file() function or the tf_get_file_info()
and tf_read_ifd() functions and they are described below:

TF_Num_Ifd:         Unsigned, the number of IFDs in the TIFF file.
TF_ImageWidth:      Unsigned long, the image width in pixels.
TF_ImageLength:     Unsigned long, the image length in pixels.
TF_BitsPerSample[3]:Unsigned,  the number of bits per  sample.
                    For  Bilevel, grayscale, or Palette Color, pixel
                    size  =  TF_BitsPerSample[0].  For  True  Color,
                    pixel Red Component = TF_BitsPerSample[0], pixel
                    Green  component  =  TF_BitsPerSample[1],  pixel
                    Blue component = TF_BitsPerSample[2].
TF_ResolutionUnit:  Unsigned,  1  = Not specified, 2  =  Inch,  3  =
                    Centimeter.
TF_SamplesPerPixel: Unsigned, the number of samples per pixel.
TF_Compression:     Unsigned,   1  =  No  Compression,   5   =   LZW
                    Compressed.
TF_PhotometricInterpretation:  Unsigned, 1 = Bilevel or Grayscale, 2
                    =  RGB  (True  Color) image, 3 =  Palette  Color
                    Image.

                                Page: 8
                                  
TF_XResolution_int: Unsigned long, the integral number of pixels  in
                    the x dimension per TF_ResolutionUnit.
TF_XResolution_frac:Unsigned  long, the fractional  number  of
                    pixels in the x dimension per TF_ResolutionUnit.
TF_YResolution_int: Unsigned long, the integral number of pixels  in
                    the y dimension per TF_ResolutionUnit.
TF_YResolution_frac:Unsigned  long, the fractional  number  of
                    pixels in the y dimension per TF_ResolutionUnit.
TF_Black:     Unsigned, index into CLUT for color nearest to Black.
TF_Red:       Unsigned, index into CLUT for color nearest to Red.
TF_Orange:    Unsigned, index into CLUT for color nearest to Orange.
TF_Yellow:    Unsigned, index into CLUT for color nearest to Yellow.
TF_Green:     Unsigned, index into CLUT for color nearest to Green.
TF_Aqua:      Unsigned, index into CLUT for color nearest to Aqua.
TF_Blue:      Unsigned, index into CLUT for color nearest to Blue.
TF_Violet:    Unsigned, index into CLUT for color nearest to Violet.
TF_White:     Unsigned, index into CLUT for color nearest to White.

2.3 Compiler Compatibility

      The TIFFMSL.LIB was compiled using Microsoft's Quick C 2.5 and
it  seems  to also work well with Microsoft C 6.0 and 7.0.   I  have
received reports of compatibility problems with Microsoft C 5.0.
      The TIFFBCL.LIB was compiled using Borland's C/C++ 3.1 and  it
seems  to  also work well with Borland C/C++ 3.0 and  4.0.   I  have
received   conflicting  reports  of  compatibility   problems   with
Borland's Turbo C 2.0 and 3.0.
      I appreciate any feedback that programmers send me along these
lines so that I can continue to improve this product.


                  Important Note for Borland Users:

      You Must set the -Fs compiler option.  This tells the compiler
to  assume that the Stack Segment equals the Data Segment.   In  the
Programmers IDE, you go to Options / Compiler / Code Generation  and
select "Always" under the option "Assume SS Equals DS".
      Why?   Because I compiled the TIFF256 Extensions with the  -Fs
option set for compatibility with VSA256 Graphics Library.  Why  did
I compile VSA256 with the -Fs option?  See the VSA256 documentation,
section 2.3 if you really must know.
                                
                                
                                
                                
                                
                                
                                
                                Page: 9
                                  
2.4 Support of TIFF 5.0

      For  the  programmer  familiar with  the  TIFF  5.0  Technical
Memorandum, the following list indicate which and to what degree the
defined  tags  are  supported by the TIFF256 Extensions.   The  tags
supported  provide functionality with most images.  When  in  doubt,
run  the  provided TIF_DATA program to determine the characteristics
of a given TIFF file.

TAGS SUPPORTED:

Basic Tags -
      BitsPerSample = 8,8,8 (for RGB or True Color Images)
      BitsPerSample <= 8 (for Bilevel, Grayscale, or Palette images) 
      ColorMap
      Compression = none
      Compression = LZW
      ImageLength
      ImageWidth
      NewSubFileType
      PhotometricInterpretation = Bilevel and Grayscale
      PhotometricInterpretation = RGB (True Color)
      PhotometricInterpretation = Palette Color
      PlanarConfiguration = 1
      ResolutionUnit
      RowsPerStrip
      SamplesPerPixel
      StripByteCounts
      StripOffsets
      XResolution
      YResolution
      Predictor = 1
          
TAGS NOT SUPPORTED (Maybe Next Revision):

Basic Tags -
          BitsPerSample != 8,8,8 (for RGB or True Color Images)
          BitsPerSample  >  8  (for Bilevel, Grayscale,  or  Palette
          images)
          ColorResponseCurves
          Compression = CCITT Group 3 1-Dimensional Modified Huffman
          RLE
          Compression = PackBits Compression
          GrayResponseCurve
          GrayResponseUnit
          PhotometricInterpretation = Transparency Mask
          PlanarConfiguration = 2
          Predictor != 1





                                Page: 10
                                  
TAGS NOT SUPPORTED (continued):

Informational Tags -
          Artist
          DateTime
          HostComputer
          ImageDescription
          Make
          Model
          Software
          
Facsimile Tags -
          Group3Options
          Group4Options
          
Document Storage and Retrieval Tags -
          DocumentName
          PageName
          PageNumber
          XPosition
          YPosition
          
Obsolete Tags -
          CellLength
          CellWidth
          FillOrder
          FreeByteCounts
          FreeOffsets
          MaxSampleValue
          MinSampleValue
          SubFileType
          Orientation
          Thresholding




















                                Page: 11
                                  
3.0   TIFF256   Extensions   Functionality

     This section describes the operation of the TIFF256 Extensions.
To use the functions in this library, compile your program using the
Large  Memory  Model  and  link your program  with  the  appropriate
libraries listed below depending on the compiler being used.

     Microsoft C or Quick C   -    VSA256MS.LIB and TIFFMSL.LIB
     Borland C++ or Turbo C   -    VSA256BC.LIB and TIFFBCL.LIB

3.1  Handling The Color Look Up Table

      The  TIFF256  Extensions supports Bilevel and 8  bit  or  less
Grayscale  images (TF_PhotometricInterpretation = 1),  24  bit  True
Color  images (TF_PhotometricInterpretation = 2) and 8 bit  or  less
Palette Color images (TF_PhotometricInterpretation = 3).
      Since this library is specifically designed for hardware  with
256 entry Color Look Up Tables (CLUTs), 24 bit True Color images are
reduced  to 8 bit images.  The method of reduction is selectable  as
either  332-RGB,  Dithered, or Adaptive Palette.  With  the  332-RGB
method, the Red, Green, and Blue color components are compressed  to
8  bit  pixels consisting of 3 bits Red, 3 bits Green,  and  2  bits
Blue,  and the CLUT is loaded with a compressed True Color  palette.
The  Dithered method also loads a compressed True Color Palette, but
the  pixels  intensities are modulated (or dithered) in a  technique
which approximates all of the 16 million possible colors.  With  the
Adaptive  Palette  method each 24 bit image is analyzed  separately.
The  optimal  color palette is determined for the image  and  loaded
into    the    Color    Look   Up   Table   (see    section    3.2.1
'tf_set_true_color_mode' function for details).
      For  Palette Color images, the IFD comes with its  own  values
which are directly loaded into the CLUT.
      Regardless  of  image  type, the  CLUT  is  not  loaded  until
'tf_display_ifd' (section 3.2.11) or 'tf_display_subimage'  (section
3.2.12) is called, even though the IFD may have already been read by
'tf_scan_file'  (section 3.2.9) or 'tf_read_ifd'  (section 3.2.8)  .
This   means  that  the  previously  loaded  CLUT  (typically   from
previously displayed IFD) remains in force until 'tf_display_ifd' is
called.    When   using,   'tf_load_image'   (section   3.2.17)   or
'tf_load_subimage' (section 3.2.18) instead of 'tf_display_ifd', the
CLUT  is not loaded until you, the programmer, deem appropriate with
a call to 'vsa_write_color_block'.











                                Page: 12
                                  
3.2 Function Descriptions

      In the following sections each function is listed along with a
definition  of  its  inputs  and return values.   A  description  is
provided followed by any relevant comments.

3.2.1 tf_set_true_color_mode(mode,num_colors,quality)

Inputs:   int mode, num_colors, quality;

Returns:  Nothing

Description:    This  routine configures the way that  24  bit/pixel
          True  Color images are displayed.  When reading  an  image
          from  an  IFD, the 'tf_display_ifd' 'tf_display_subimage',
          'tf_load_image'     and    'tf_load_subimage'     routines
          automatically  detect the number of  bits  per  pixel  and
          convert  the image to 8 bits per pixel.  If the  image  in
          the  IFD  is  a  24  bit per pixel image,  the  conversion
          process   is   defined   by  the  'tf_set_true_color_mode'
          routine.

          mode =    0 - 332 RGB
                    1 - Dithered
                    2 - Adaptive Palette
                    3 - Preserve 24 bit pixels info (tf_load_image &
                        tf_load_subimage only)

                For mode = 0 through 2, 24 bit True Color images are
          reduced   to  8  bit  images  using  either  the  332-RGB,
          Dithered,  or Adaptive Palette method.  With  the  332-RGB
          method,  the  Red,  Green, and Blue color  components  are
          compressed  to 8 bit pixels consisting of 3  bits  Red,  3
          bits  Green, and 2 bits Blue, and the Color Look Up  Table
          is  loaded with a compressed True Color palette.  With the
          Dithered method,  again a compressed True Color Palette is
          loaded,  but  the  pixels intensities  are  modulated  (or
          dithered) in a technique which approximates all of the  16
          million   possible  colors.   With  the  Adaptive  Palette
          method,  each  24  bit image is analyzed separately.   The
          optimal  color  palette is determined for  the  image  and
          loaded into the Color Look Up Table.
                    The  Adaptive  Palette  method  reduces  the  16
          million  possible  colors in the  24  bit  image  down  to
          'num_colors', where 'num_colors' can range from 2 to  256.
          The   'quality'  parameter  lets  the  user  optimize  the
          Adaptive  Palette algorithm for image quality.  The  valid
          range  is from 0 to 100.  When 'quality' is closer  to  0,
          the  algorithm is optimized for images with fewer  colors,
          but many shades per color (smooth shading is emphasized at
          the  expense of color variety).  When 'quality' is  closer
          to  100,  the  algorithm is optimized for  images  with  a
          broader  color distribution (many colors are  accommodated
                                Page: 13
                                  
          at  the  expense of smooth shading).  If 'mode' is not  2,
          the 'num_colors' and 'quality' parameters are ignored.
               When  true  color  mode  = 3 and  'tf_load_image'  or
          'tf_load_subimage' is used, the TIFF file's 24  bit  pixel
          data  is  preserved as it is loaded into the image buffer.
          The  image buffer contains the image width in the first  2
          bytes,  the image height in the second 2 bytes,  and  then
          the image pixel data in RGB triplets per pixel, where each
          of  R,  G, and B are a byte.  If true color mode =  3  and
          either "'tf_display_ifd' or 'tf_display_subimage' is used,
          the   image  is  displayed  with  true  color  mode  =   1
          (dithering).  True color mode = 3 is provided so that  the
          programmer can access the original 24 bit pixel  data  for
          image   processing   or   other   purposes.    Note   that
          'vsa_put_image' and 'tf_save_image' do not properly handle
          image buffers loaded with 24 bit pixel data.

Availability:  In TIFF256 Graphics Library Version 3.0 and up.

Comments: a)  If true color mode is set to 3 and tf_display_ifd or
              tf_display_subimage is called,   true color mode = 1
              (dithering) will be used to display the image.
          b)  'vsa_put_image' and 'tf_save_image' do not properly
              handle image buffers loaded with 24 bit pixel data.

3.2.2 tf_get_true_color_mode(pmode,pnum_colors,pquality)

Inputs:   int *pmode,*num_colors,*pquality;

Returns:  Nothing

Description:    This  routine returns the current True Color display
          mode  and  the  Adaptive Palette configuration  parameters
          which   were  set  by  tf_set_true_color_mode'.   '*pmode'
          returns    the   True   Color   display   'mode'    value,
          '*pnum_colors'  returns the Adaptive Palette  'num_colors'
          value,   and  '*pquality'  returns  the  Adaptive  Palette
          'quality' value.

Availability:  In TIFF256 Graphics Library Version 3.0 and up.

3.2.3 tf_open_file(filename)

Inputs:   char far *filename;

Returns:  int fail_flag;

Description:    This  routine opens the TIFF file specified  by  the
          character  string  'filename'  for  use  by  the   TIFF256
          Extensions.  Only one file can be opened at a  time.   The
          file   is   opened  as  'Read  Only'.   If  the  file   is
          successfully   opened,  this  routine   returns   a   '0'.
          Otherwise, it returns a '-1'.  This routine must be called
                                Page: 14
                                  
          before  calling tf_get_file_info().  Since only  one  TIFF
          file   can  be  opened  at  a  time,  make  sure  to  call
          'tf_close_file' before "opening" a new one.

Availability:  In TIFF256 Graphics Library Version 1.0 and up.

Comments: See 'tf_scan_file' and 'tf_decode_scan_error' for a simpler
          approach.

3.2.4 tf_close_file()

Inputs:   Nothing

Returns:  Nothing

Description:    This  routine closes the currently open  TIFF  file.
          This routine must be called before opening a new TIFF file
          with   tf_open_file()  or  tf_scan_file().   This  routine
          should be called before exiting your program.

Availability:  In TIFF256 Graphics Library Version 1.0 and up.

Comments: Remember,    each    'tf_scan_file'    also    needs     a
          'tf_close_file'.

3.2.5 tf_get_file_info()

Inputs:   Nothing

Returns:  int fail_flag;

Description:    This routine verifies  that the  selected  file is a 
          TIFF  format   file.   Then  it  initializes  the  TIFF256  
          environment   for  this   file.   The    global  parameter
          'TF_Num_Ifd'   is   set  to  the  number  of  Image   File
          Directories (IFDs) existing within the file.    An IFD  is
          one 'picture', and multiple IFDs can exist within one TIFF
          file.   The TIFF file pointer is set to point to the first
          IFD  in the file.  This routine is typically called  after
          'tf_open_file'.  The 'fail_flag' is returned with  one  of
          the following values:

                 0  No Errors
                 1  Error, Reading file failed
                 2  Error, File shorter than expected
                 3  Error, Bad TIFF File


Availability:  In TIFF256 Graphics Library Version 1.0 and up.

Comments: The  'fail_flag' return values 2 and 3 have been added  as
          of   Version   3.0.    Also,    see   'tf_scan_file'   and
          'tf_decode_scan_error' for a simpler approach.
                                Page: 15
                                  
3.2.6 tf_skip_ifd(count)

Inputs:   unsigned count;

Returns:  int reached_end;

Description:    This  routine  moves  the TIFF  file  pointer  ahead
          'count'  IFDs.  Typically, this routine  is  called  after
          tf_get_file_info() to index the TIFF file pointer  to  the
          desired  IFD.   For  example, if  tf_get_file_info()  sets
          TF_Num_Ifd  to  5, calling this routine immediately  after
          tf_get_file_info() with 'count' = 3, will cause  the  TIFF
          file  pointer to skip over the first 3 IFDs and  point  to
          the  4th IFD.  If 'count' equals or exceeds the number  of
          remaining  IFDs, this routine returns a 1,  and  the  TIFF
          file  pointer is set to point to the last IFD.   Otherwise
          it returns a 0.

Availability:  In TIFF256 Graphics Library Version 1.0 and up.

3.2.7 tf_set_defaults()

Inputs:   Nothing

Returns:  Nothing

Description:                                  This routine sets  the
          default values for all of the global parameters which  are
          modified by TIFF 'Tags'.  TIFF files may not include  data
          for all of the parameters used by the TIFF256 environment,
          and  therefore the defaults should be set.   This  routine
          should  be called at the beginning of each new IFD,  prior
          to  calling tf_read_ifd().  The default values are  listed
          below:

               TF_ImageWidth                 =    0
               TF_ImageLength                =    0
               TF_BitsPerSample[0]           =    1
               TF_BitsPerSample[1]           =    1
               TF_BitsPerSample[2]           =    1
               TF_ResolutionUnit             =    2
               TF_SamplesPerPixel            =    1
               TF_Compression                =    1
               TF_PhotometricInterpretation  =    1
               TF_XResolution_int            =    300
               TF_XResolution_frac           =    1
               TF_YResolution_int            =    300
               TF_YResolution_frac           =    1
               TF_Predictor                  =    1
               
Availability:  In TIFF256 Graphics Library Version 1.0 and up.

Comments: See 'tf_scan_file' and 'tf_decode_scan_error' for a simpler
          approach.
                                Page: 16
                                  
3.2.8 tf_read_ifd()

Inputs:   Nothing

Returns:  int fail_flag;

Description:                           This  routine reads the  data
          from  the  IFD  currently pointed  to  by  the  TIFF  file
          pointer.   The  TIFF file pointer must be  pointing  to  a
          valid  IFD prior to calling this routine (This routine  is
          typically  called  after 'tf_open_file'  or  'tf_skip_ifd'
          which  initialize  the pointer).  After reading  the  data
          from  the  current IFD, the TIFF file pointer  is  set  to
          point to the next IFD.  If the TIFF file pointer points to
          the  last  IFD  in  the  TIFF file  and  this  routine  is
          executed, the IFD is read, and then the TIFF file  pointer
          is  set  with  a null value.  After calling this  routine,
          'tf_display_ifd',  'tf_display_subimage',  'tf_load_image'
          or  'tf_load_subimage' can be called to display the  IFD's
          image.   The  'fail_flag'  is returned  with  one  of  the
          following values:

                 0  No Errors
                 1  Error, TIFF file pointer is a null value, end of file
                 2  Error, Seeking in File
                 3  Error, Reading file failed
                 4  Greater than 8 Bit Palette Pixels Not Supported
                 5  Samples Per Pixel > 3 Not Supported
                 6  Only 8x8x8 Bit True Color Pixels Supported
                 7  This TIFF Compression Format Not Supported
                 8  This Photometric Interpretation Not Supported
                 9  Currently Only Support up to 1024 Strips
                10  Samples Per Pixel > 3 Not Supported
                11  Currently Only Support up to 1024 Strips
                12  This Planar Configuration Not Supported
                13  This Predictor Not Supported
                14  Color Map Size > 256 Not Supported

          The following global parameters are set by this routine:

                    TF_ImageWidth
                    TF_ImageLength
                    TF_BitsPerSample[3]
                    TF_ResolutionUnit
                    TF_SamplesPerPixel
                    TF_Compression
                    TF_PhotometricInterpretation
                    TF_XResolution_int
                    TF_XResolution_frac
                    TF_YResolution_int
                    TF_YResolution_frac
                    TF_Predictor
                                Page: 17
                                  
Availability:  In TIFF256 Graphics Library Version 1.0 and up.

Comments: The 'fail_flag' return values 2 through 14 have been added
          as   of  Version  3.0.   Also,   see  'tf_scan_file'   and
          'tf_decode_scan_error' for a simpler approach.

3.2.9 tf_scan_file(filename)

Inputs:   char far *filename;

Returns:  int error;

Description:                            This   routine  provides   a
          simplified method of preparing to display a TIFF file.  To
          display a TIFF file, just call 'tf_scan_file' and then use
          'tf_display_ifd', 'tf_display_subimage',  'tf_load_image',
          or   'tf_load_subimage'   as  often   as   required.   The
          "filename" parameter is the full path and filename of  the
          TIFF  file  to be processed.  The return value  from  this
          routine  is '0' if no errors occur.  If non zero, see  the
          'tf_decode_scan_error' routine for individual errors,  and
          an  easy way to report them.  'tf_scan_file' combines  the
          functionality of the following routines:

            tf_set_prime_colors();
            tf_open_file(filename);
            tf_get_file_info();
            tf_set_defaults();
            tf_read_ifd();

          Don't  forget  to call 'tf_close_file' for  each  call  of
          'tf_scan_file', BEFORE calling 'tf_scan_file' again..

Availability:  In TIFF256 Graphics Library Version 4.0 and up.

Comments: In  most  cases,  you  can simplify  your  life  by  using
          'tf_scan_file'  and  'tf_decode_scan_error'   instead   of
          calling the older routines.
                                
                                










                                
                                
                                
                                Page: 18
                                  
3.2.10 tf_decode_scan_error(x,y,color,error)

Inputs:   int x, int y, int color, int error;

Returns:  Nothing

Description:    This  routine gives you a simple way  to  print  out
          screen  error  messages resulting from a  failed  call  to
          'tf_scan_file'.  Just call this routine,  passing  it  the
          returned  error value from 'tf_scan_file'.  The  following
          works just fine:

            tf_decode_scan_error(x,y,color,tf_scan_file(filename));

                         The  'x,y' parameters are pixel coordinates
          where  the  error  text  will be printed  on  the  screen.
          'color' defines the error text color, and 'error'  is  the
          error value returned from 'tf_scan_file'.  The error codes
          are enumerated below.  Note that no message is printed  if
          'error' = 0.

            0 -  No Error, No message Printed Out!
            1 -  Can't Find Specified File! ... Try Again.
            2 -  File Read Error!
            3 -  File Shorter Than Expected!
            4 -  Bad TIFF File!
            5 -  NULL TIFF file Pointer!
            6 -  Error Seeking in File!
            7 -  File Read error!
            8 -  Greater than 8 Bit Palette Pixels Not Supported!
            9 -  Samples Per Pixel > 3 Not Supported!
           10 -  Only 8x8x8 Bit True Color Pixels Supported!
           11 -  This TIFF Compression Format Not Supported!
           12 -  This Photometric Interpretation Not Supported!
           13 -  Currently Only Support up to 1024 Strips!
           14 -  Samples Per Pixel > 3 Not Supported!
           15 -  Currently Only Support up to 1024 Strips!
           16 -  This Planar Configuration Not Supported!
           17 -  This Predictor Not Supported!
           18 -  Color Map Size > 256 Not Supported!

Availability:  In TIFF256 Graphics Library Version 4.0 and up.

Comments: This  routine  should  only  be  used  with  error  values
          returned from 'tf_scan_file'.
                                
                                
                                
                                
                                
                                
                                
                                
                                Page: 19
                                  
3.2.11 tf_display_ifd(x0,y0)

Inputs:   unsigned x0;
          unsigned y0;

Returns:  int fail_flag;

Description:    This  routine displays the image that is defined  in
          the IFD read by the most recent call to 'tf_scan_file'  or
          'tf_read_ifd'.  The image is drawn directly to the  screen
          with  its  top left corner at screen coordinates  'x0,y0'.
          The Color Look Up Table is not modified until this routine
          is  executed.   When executed, this routine  prepares  the
          Color Look Up Table as defined by the IFD being displayed.
          Before    calling   this   routine,   'tf_scan_file'    or
          'tf_read_ifd'  must  be called to initialize  all  of  the
          required parameters.
               When  reading  the  image in the  IFD,  this  routine
          automatically  detects the number of bits  per  pixel  and
          converts  the image to 8 bits per pixel.  If the image  in
          the  IFD  is  a  24  bit per pixel image,  the  conversion
          process   is   defined   by  the  'tf_set_true_color_mode'
          routine.
                  If    Adaptive    Palette    is    enabled    (via
          'tf_set_true_color_mode'),   this   routine    temporarily
          allocates  32k  bytes of memory for the  Adaptive  Palette
          conversion process.  If the allocation fails, this routine
          returns  a  fail_flag = 1.  In this case, the program  can
          disable Adaptive Palette and call this routine again.
                Typically   this   routine  is   used   instead   of
          'tf_load_image' when you don't need to store the image  in
          a  buffer  for subsequent manipulation.  This  routine  is
          also useful when the run time environment has insufficient
          memory  for  allocating the huge image memory buffer  used
          with 'tf_load_image'.

          Return Values
                 0 = no error
                 1 = Can't allocate 32k array for adaptive palette
                -1 = not enough memory to do decompression
                -2 = Compressed Strip exceeds max size (12000 bytes max)
                -3 = error in compressed data
                -4 = Uncompressed Strip exceeds max size (12000 bytes max)
                -5 = Can't allocate misc. working memory

Availability:  In TIFF256 Graphics Library Version 1.0 and up.

Comments: This   routine   may  be  called  more   than   once   per
          'tf_scan_file' or 'tf_read_ifd' call.  Please DO NOT  call
          this routine if 'tf_scan_file' or 'tf_read_ifd' return  an
          error.


                                Page: 20
                                  
3.2.12 tf_display_subimage(x,y,x0,y0,x1,y1)

Inputs:   int x,y,x0,y0,x1,y1;

Returns:  int fail_flag;

Description:     This  routine  displays  the  rectangular  subimage
          bounded by 'x0,y0' and 'x1,y1' that is defined in the  IFD
          read  by  the  most  recent  call  to  'tf_scan_file'   or
          'tf_read_ifd'.   This  is useful when  you  only  want  to
          extract  a  small  portion of a  larger  TIFF  file.   The
          subimage is drawn directly to the screen with its top left
          corner  at  screen coordinates 'x,y'.  The Color  Look  Up
          Table  is  not  modified until this routine  is  executed.
          When  executed, this routine prepares the  Color  Look  Up
          Table  as  defined  by  the IFD being  displayed.   Before
          calling this routine, 'tf_scan_file' or 'tf_read_ifd' must
          be called to initialize all of the required parameters.
               When  reading the subimage in the IFD,  this  routine
          automatically  detects the number of bits  per  pixel  and
          converts  the image to 8 bits per pixel.  If the image  in
          the  IFD  is  a  24  bit per pixel image,  the  conversion
          process   is   defined   by  the  'tf_set_true_color_mode'
          routine.
                  If    Adaptive    Palette    is    enabled    (via
          'tf_set_true_color_mode'),   this   routine    temporarily
          allocates  32k  bytes of memory for the  Adaptive  Palette
          conversion process.  If the allocation fails, this routine
          returns  a  fail_flag = 1.  In this case, the program  can
          disable Adaptive Palette and call this routine again.
                Typically   this   routine  is   used   instead   of
          'tf_load_subimage' when you don't need to store the  image
          in  a buffer for subsequent manipulation.  This routine is
          also useful when the run time environment has insufficient
          memory  for  allocating the huge image memory buffer  used
          with 'tf_load_subimage'.

          Return Values
                 0 = no error
                 1 = Can't allocate 32k array for adaptive palette
                -1 = not enough memory to do decompression
                -2 = Compressed Strip exceeds max size (12000 bytes max)
                -3 = error in compressed data
                -4 = Uncompressed Strip exceeds max size (12000 bytes max)
                -5 = Can't allocate misc. working memory

Availability:  In TIFF256 Graphics Library Version 4.0 and up.

Comments: This   routine   may  be  called  more   than   once   per
          'tf_scan_file' or 'tf_read_ifd' call.  Please DO NOT  call
          this routine if 'tf_scan_file' or 'tf_read_ifd' return  an
          error.
                                
                                Page: 21
                                  
3.2.13 tf_set_compression(mode)

Inputs:   int mode;

Returns:  Nothing

Description:                             This   routine   sets   the
          compression  mode on or off for saving TIFF images.   When
          "mode"  =  0, compression is off.  When 'mode' =  1,  TIFF
          files  are  saved  as LZW compressed  images.   Note  that
          compression is off by default.

Availability:  In TIFF256 Graphics Library Version 4.0 and up.

3.2.14 tf_get_compression()

Inputs:   Nothing

Returns:  int

Description:                            This  routine  returns   the
          compression  mode for saving TIFF images.  a return  value
          of 0 indicates that compression is off.  A return value of
          1   indicates  that  TIFF  files  will  be  saved  as  LZW
          compressed  images.   Note  that  compression  is  off  by
          default.

Availability:  In TIFF256 Graphics Library Version 4.0 and up.

3.2.15 tf_save_file(x0,y0,x1,y1,filename)

Inputs:   unsigned x0,y0,x1,y1;
          char far *filename;

Returns:  int fail_flag;

Description:    This  routine saves the portion of the screen  image
          defined  by  (x0,y0) (x1,y1) to the TIFF file  "filename".
          The image is saved as an 8 bit Palette Color image (i.e. 8
          bits/pixel).  This routine may be called at anytime  after
          vsa_init  is called.  The TIFF file will be saved  as  LZW
          compressed   TIFF   if   compression   is   enabled,   see
          'tf_set_compression'.  If no error occurs in  writing  the
          file, a 0 is returned, otherwise see below.

          Return Values
                 0 = no error
                -1 = Can't open or create file
                -2 = Can't allocate temp working memory
                -3 = Can't allocate memory for compression
                -4 = Error while compressing data
                                
                                
                                Page: 22
                                  
               The TIFF image file saved as a result of this routine
          has  the following characteristics, as defined by the TIFF
          specification:

          - Intel Byte Ordering
          - SamplesPerPixel = 1
          - BitsPerSample = 8 (i.e. 8 bits per pixel)
          - ColorMap  (i.e. Color palette  stored  within TIFF file)
          - PhotometricInterpretation = Palette Color
          - PlanarConfiguration = 1
          - RowsPerStrip = Largest number to satisfy strip < 8000 bytes
          - ImageWidth = |x1-x0|+1 (pixels)
          - ImageLength = |y1-y0|+1 (pixels)
          - Resolution Unit = 2 (inches)
          - XResolution = 100 (Dots Per Inch)
          - YResolution = 100 (Dots Per Inch)
          - Compression = none or LZW (see 'tf_set_compression')
          - Predictor = 1 if compression, otherwise no predictor tag.

Availability:  In TIFF256 Graphics Library Version 2.0 and up.

3.2.16 tf_image_size()

Inputs:   Nothing

Returns:  long size;

Description:    This  routine  returns the size (in  bytes)  of  the
          memory  buffer required to store an image that is  defined
          in  the IFD read by the most recent call to 'tf_scan_file'
          or    'tf_read_ifd'.    Before   calling   this   routine,
          'tf_scan_file' or 'tf_read_ifd' must be called  to  define
          all  of  the  required global parameters.  If  true  color
          mode  <  3,  the  size  is based on  8  bit  pixels  since
          'tf_load_image' and 'tf_load_subimage' convert  to  8  bit
          pixels  as they read the TIFF file.  The size returned  is
          equal  to  the number of pixels in the image plus  4.   If
          true  color mode = 3, the size is based on 24 bit  pixels,
          and  the  size returned is equal to 3 times the number  of
          pixels in the image plus 4.
               Typically,  after  calling 'tf_image_size,  a  'huge'
          memory  buffer is allocated with 'size' bytes.   Then  the
          'tf_load_image'  function is used to load the  image  from
          the TIFF file into the memory buffer.

Availability:  In TIFF256 Graphics Library Version 3.0 and up.

Comments: You  can  use  this  routine for  'tf_load_subimage',  but
          you'll  be  wasting  memory.  For 'tf_load_subimage',  the
          required image array size  = (x1-x0+1)*(y1-y0+1)  +  4  if
          true  color mode < 3 and 3*(x1-x0+1)*(y1-y0+1) + 4 if true
          color mode = 3..
                                
                                Page: 23
                                  
3.2.17 tf_load_image(image,lut)

Inputs:   unsigned char huge *image;
          unsigned char far *lut;

Returns:  int status;

Description:   This routine loads the 'image' memory buffer with the
          image  that is defined in the IFD read by the most  recent
          call  to  'tf_scan_file'  or 'tf_read_ifd'.   The  image's
          color palette is loaded into the 'lut' memory buffer.  The
          'image'  memory buffer must be allocated the size returned
          by 'tf_image_size', and the 'lut' memory must be allocated
          768  bytes before calling this routine.  The return  value
          'status' indicates how many of the 256 colors in 'lut' are
          actually  used  (  <  2 indicates an  error,  see  below).
          Before    calling   this   routine,   'tf_scan_file'    or
          'tf_read_ifd'  must  be called to initialize  all  of  the
          required parameters.
               When  reading  the  image in the  IFD,  this  routine
          automatically  detects the number of bits  per  pixel  and
          converts  the image to 8 bits per pixel.  If the image  in
          the  IFD  is  a  24  bit per pixel image,  the  conversion
          process   is   defined   by  the  'tf_set_true_color_mode'
          routine.
                  If    Adaptive    Palette    is    enabled    (via
          'tf_set_true_color_mode'),   this   routine    temporarily
          allocates  32k  bytes of memory for the  Adaptive  Palette
          conversion process.  If the allocation fails, this routine
          returns  'status' = 1.  In the case where  the  allocation
          fails,  the program can disable Adaptive Palette and  call
          this routine again.
              If the 'image' buffer contains 8 bit pixels (i.e. true
          color mode < 3) it can be displayed on the screen with the
          'vsa_put_image' function, or saved to a TIFF file with the
          'tf_save_image' function.  The color palette in the  'lut'
          buffer  can  be loaded into the Color Look Up Table  using
          the 'vsa_write_color_block' routine.
              The 'image' buffer stores the image width in the first
          two  bytes, the  image height in the second two bytes, and
          then  the image pixels in raster order (row, then column).
          The  first pixel value following image height is  the  top
          left  corner pixel.  The 'lut' array stores the 256  color
          palette data in RGB triplets where each of R, G, and B  is
          a byte.  768 bytes are stored in 'lut'.
                Typically   this   routine  is   used   instead   of
          'tf_display_ifd' when you need to store  the  image  in  a
          buffer for subsequent manipulation.  With this routine,  a
          program  can bring in an image, manipulate its pixels  and
          or  color  palette, and then save it back to a  TIFF  file
          without  ever necessarily having to display the  image  on
          the screen.
                                
                                Page: 24
                                  
          Return Values
                 0 = no error
                 1 = Can't allocate 32k array for adaptive palette
                >1 = number of entries loaded in lut array
                -1 = not enough memory to do decompression
                -2 = Compressed Strip exceeds max size (12000 bytes max)
                -3 = error in compressed data
                -4 = Uncompressed Strip exceeds max size (12000 bytes max)
                -5 = Can't allocate misc. working memory

Availability:  In TIFF256 Graphics Library Version 3.0 and up.

Comments: This   routine   may  be  called  more   than   once   per
          'tf_scan_file' or 'tf_read_ifd' call.  Please DO NOT  call
          this routine if 'tf_scan_file' or 'tf_read_ifd' return  an
          error.

3.2.18 tf_load_subimage(x0,y0,x1,y1,image,lut)

Inputs:   int x0,y0,x1,y1;
          unsigned char huge *image;
          unsigned char far *lut;

Returns:  int status;

Description:   This routine loads the 'image' memory buffer with the
          rectangular  subimage bounded by 'x0,y0' and 'x1,y1'  that
          is  defined  in  the IFD read by the most recent  call  to
          'tf_scan_file' or 'tf_read_ifd'.  This is useful when  you
          only  want  to  extract a small portion of a  larger  TIFF
          file.   The  subimage's color palette is loaded  into  the
          'lut'  memory buffer.  The 'image' memory buffer  must  be
          allocated  with  the appropriate size  (see  Comments  for
          'tf_image_size'), and the 'lut' memory must  be  allocated
          768  bytes before calling this routine.  The return  value
          'status' indicates how many of the 256 colors in 'lut' are
          actually  used  (  <  2 indicates an  error,  see  below).
          Before    calling   this   routine,   'tf_scan_file'    or
          'tf_read_ifd'  must  be called to initialize  all  of  the
          required parameters.
               When  reading  the  image in the  IFD,  this  routine
          automatically  detects the number of bits  per  pixel  and
          converts  the image to 8 bits per pixel.  If the image  in
          the  IFD  is  a  24  bit per pixel image,  the  conversion
          process   is   defined   by  the  'tf_set_true_color_mode'
          routine.
                  If    Adaptive    Palette    is    enabled    (via
          'tf_set_true_color_mode'),   this   routine    temporarily
          allocates  32k  bytes of memory for the  Adaptive  Palette
          conversion process.  If the allocation fails, this routine
          returns  'status' = 1.  In the case where  the  allocation
          fails,  the program can disable Adaptive Palette and  call
          this routine again.
                                Page: 25
                                  
               If  true  color mode = 3, no conversion is performed.
          Instead,  for  24  bit  pixel images,  24  bits/pixel  are
          returned  in the  'image' array in RGB triplets per  pixel
          and the 'lut' array is loaded with 256 color gray scale.
              If the 'image' buffer contains 8 bit pixels (i.e. true
          color mode < 3) it can be displayed on the screen with the
          'vsa_put_image' function, or saved to a TIFF file with the
          'tf_save_image' function.  The color palette in the  'lut'
          buffer  can  be loaded into the Color Look Up Table  using
          the 'vsa_write_color_block' routine.
              The 'image' buffer stores the image width in the first
          two  bytes, the  image height in the second two bytes, and
          then  the image pixels in raster order (row, then column).
          The  first pixel value following image height is  the  top
          left  corner pixel.  The 'lut' array stores the 256  color
          palette data in RGB triplets where each of R, G, and B  is
          a byte.  768 bytes are stored in 'lut'.
                Typically   this   routine  is   used   instead   of
          'tf_display_subimage' when you need to store the image  in
          a  buffer for subsequent manipulation.  With this routine,
          a program can bring in an image, manipulate its pixels and
          or  color  palette, and then save it back to a  TIFF  file
          without  ever necessarily having to display the  image  on
          the screen.

          Return Values
                 0 = no error
                 1 = Can't allocate 32k array for adaptive palette
                >1 = number of entries loaded in lut array
                -1 = not enough memory to do decompression
                -2 = Compressed Strip exceeds max size (12000 bytes max)
                -3 = error in compressed data
                -4 = Uncompressed Strip exceeds max size (12000 bytes max)
                -5 = Can't allocate misc. working memory

Availability:  In TIFF256 Graphics Library Version 4.0 and up.

Comments: This   routine   may  be  called  more   than   once   per
          'tf_scan_file' or 'tf_read_ifd' call.  Please DO NOT  call
          this routine if 'tf_scan_file' or 'tf_read_ifd' return  an
          error.

3.2.19 tf_save_image(image,lut,filename)

Inputs:   unsigned char huge *image;
          unsigned char far *lut;
          char far *filename;

Returns:  int fail_flag;

Description:    This  routine saves the image defined in the 'image'
          buffer  along  with the 256 color palette defined  in  the
          'lut'  buffer  to the TIFF file "filename". The  image  is
                                Page: 26
                                  
          saved as an 8 bit Palette Color image (i.e. 8 bits/pixel).
          This  routine may be called at anytime after  vsa_init  is
          called,  assuming that both 'image' and  'lut'  have  been
          loaded with meaningful data.  The TIFF file will be  saved
          as  LZW  compressed TIFF if compression  is  enabled,  see
          'tf_set_compression'.  If no error occurs in  writing  the
          file, a 0 is returned, otherwise see below.
               The  'image'  buffer could have been  loaded  through
          either a 'tf_load_image' (which gets it from a TIFF  file)
          or  through  'vsa_get_image' (which gets it directly  from
          the  screen).  In the latter case, you would also need  to
          have loaded the 'lut' buffer using 'vsa_read_color_block'.
               The 'image' array stores the image width in the first
          two  bytes, the image height in the second two bytes,  and
          then  the image pixels in standard raster order (row, then
          column).  First  pixel is in top left corner.   The  'lut'
          array  stores  the 256 color palette data in RGB  triplets
          where  each  of R, G, and B is a byte.  256 triplets  (768
          bytes) are stored in 'lut'.

          Return Values
                 0 = no error
                -1 = Can't open or create file
                -2 = Can't allocate temp working memory
                -3 = Can't allocate memory for compression
                -4 = Error while compressing data

               The TIFF image file saved as a result of this routine
          has  the following characteristics, as defined by the TIFF
          specification:

                    - Intel Byte Ordering
                    - SamplesPerPixel = 1
                    - BitsPerSample = 8 (i.e. 8 bits per pixel)
                    - ColorMap  (i.e. Color palette  stored  within
                      TIFF file)
                    - PhotometricInterpretation = Palette Color
                    - PlanarConfiguration = 1
                    - RowsPerStrip = Largest number to satisfy strip
                      < 8000 bytes
                    - ImageWidth = first 16 bits of 'image' buffer
                    - ImageLength = second 16 bits of 'image' buffer
                    - Resolution Unit = 2 (inches)
                    - XResolution = 100 (Dots Per Inch)
                    - YResolution = 100 (Dots Per Inch)
                    - Compression   =   none    or    LZW    (see
                      'tf_set_compression')
                    - Predictor = 1 if compression on, otherwise no
                      predictor tag.

Availability:  In TIFF256 Graphics Library Version 3.0 and up.
                                
                                
                                Page: 27
                                  
3.2.20 tf_set_prime_colors()

Inputs:   Nothing

Returns:  Nothing

Description:     This   routine  updates  the  prime  color   global
          parameters:   TF_Black,   TF_Red,  TF_Orange,   TF_Yellow,
          TF_Green,  TF_Aqua, TF_Blue, TF_Violet, and TF_White.   It
          does  this by scanning the Color Look Up Table and loading
          each parameter with the Color Look Up Table index for  the
          brightest  color  nearest to the color  specified  by  the
          parameter  name.  This routine should be called  following
          any operation which modifies the Color Look Up Table (such
          as tf_display_ifd).
                The prime color global parameters are provided in an
          attempt  to  give  the user access to a  standard  set  of
          colors  (for  use with text, borders, etc.) regardless  of
          Color  Look Up Table operations.  However, the color  must
          exist in the Color Look Up Table for this routine to  find
          it.

Availability:  In TIFF256 Graphics Library Version 1.0 and up.






























                                Page: 28
                                  
4.0 Nitty Gritties

4.1 Registration Information

      If you find the TIFF256 Graphics Library Extensions useful,  a
registration of $29 would be appreciated ($15 if ordering VSA256 and
TIFF256 at the same time, see ORDER.TXT).  Registration brings  with
it  MAJOR  BENEFITS, as spelled out in section 1.2, so look  at  the
ORDER.TXT file and fill it out!

      Please  fill out the Information About You and  the  Wish List
sections, and  indicate the  version number of the software  you are
presently using.  Send check or money order to:

                             Spyro Gumas
                      7910 W. Brookridge Drive
                        Middletown, MD  21769


          ******  COMPUSERVE   -   SWREG  ID: 5418  ******
                                  
If  you are on CompuServe, you can register through SWREG.  Just "GO
SWREG",  then give them the registration ID: 5418.  They  will  bill
you  $44.00  and  I'll  send you both VSA256  and  TIFF256  graphics
Libraries (plus the goodies!).  Please do fill  out and send  me the
information  form  so  you  can  tell  me  what you want in the next 
revision.


























                                Page: 29
                                  
4.2 Software License

               TIFF256 Graphics Library, Version 4.0
      Copyright Spyro Gumas, 1992 - 1995.  All Rights Reserved.

      The  TIFF256  Graphics  Library  Extensions  is  a  "shareware
program"  and  is provided at no charge to the user for  evaluation.
The  essence  of  "user-supported" software is to  provide  personal
computer users with quality software without high prices, and yet to
provide  incentive  for  programmers  to  continue  to  develop  new
products.   If  you find this program useful and find that  you  are
using  The TIFF256 Graphics Library Extensions and continue  to  use
The  TIFF256  Graphics Library Extensions after a  reasonable  trial
period,  you must make a registration payment of $29 to Spyro  Gumas
($15  if  ordering  VSA256  and  TIFF256  at  the  same  time,   see
ORDER.TXT).  The registration fee will license one copy for  use  on
any one computer at any one time.  You must treat this software just
like  a  book.  An example is that this software may be used by  any
number  of people and may be freely moved from one computer location
to  another, so long as there is no possibility of it being used  at
one location while it's being used at another. Just as a book cannot
be read by two different persons at the same time.

You  are  free (and encouraged) to copy and distribute  The  TIFF256
Graphics Library Extensions if:

1)   It is not used as a component of another software library.
2)   No fee is charged for use, copying or distribution.
3)   It  is  distributed as is (preferably as TIF256.ZIP)  and  not
     modified in any way.

Furthermore,  you  are  granted royalty  free  use  of  The  TIFF256
Graphics  Library Extensions executable code in any of your programs
given that:

1)   You  have registered your use of The TIFF256 Graphics  Library
     Extensions and
     paid the registration fee.
2)   It is not used as a component of another software library.
3)   You visibly acknowledge the use of The TIFF256 Graphics Library
     Extensions in  your product  in both  the printed materials and 
     the executable software with the following statement:

     "This software uses the VSA256 and TIFF256 Graphics Libraries,
      Copyright Spyro Gumas, 1992 - 1995.  All Rights Reserved"


      Clubs  and user groups may charge a nominal fee (not to exceed
$10)  for  expenses  and  handling while  distributing  The  TIFF256
Graphics  Library  Extensions.   Anyone  distributing  The   TIFF256
Graphics Library Extensions for any kind of remuneration must  first
contact  Spyro  Gumas  at the address below for authorization.  This
authorization   will  be  automatically  granted   to   distributors
                                Page: 30
                                  
recognized by the (ASP) as adhering to its guidelines for  shareware
distributors, and such distributors may begin offering  The  TIFF256
Graphics  Library Extensions immediately (However Spyro  Gumas  must
still be advised so that the distributor can be kept up-to-date with
the latest version of The TIFF256 Graphics Library Extensions.).

      Commercial  users  of The TIFF256 Graphics Library  Extensions
must  register  and  pay for their copies of  The  TIFF256  Graphics
Library  Extensions within 30 days of first use or their license  is
withdrawn.   Consult  the  file ORDER.TXT for  more  information  or
contact Spyro Gumas.

4.3 Disclaimer

      Users  of The TIFF256 Graphics Library Extensions must  accept
this    disclaimer  of  warranty:   The  TIFF256  Graphics   Library
Extensions  is supplied as is.  The author disclaims all warranties,
expressed  or implied, including, without limitation, the warranties
of  merchantability  and  of fitness for  any  purpose.  The  author
assumes no liability for damages, direct or consequential, which may
result from the use of The TIFF256 Graphics Library Extensions.   In
no  event  shall the author's liability for any damages ever  exceed
the  price paid for the license to use The TIFF256 Graphics  Library
Extensions,  regardless of the form of the claim.  The person  using
The  TIFF256 Graphics Library Extensions bears all risk  as  to  the
quality and performance of this software.

4.4 Technical Support

      If  you  have  any  questions or comments  about  The  TIFF256
Graphics Library Extensions, please write me at:

                             Spyro Gumas
                      7910 W. Brookridge Drive
                        Middletown, MD  21769

Or, contact me via EMAIL!

            CompuServe:  71064,1571
            Internet:    71064.1571@compuserve.com













                                Page: 31
                                  
5.0 Appendix

5.1 TIFF.H Include File

/*............................ TIFF.H ................ 6-2-95 .........*/
/* This file declares the TIFFLB library functions and global          */
/* parameters used throughout the graphics routines.                   */
/*                                                                     */
/*                              Version 4.0                            */
/*        Copyright Spyro Gumas, 1992 - 1995.  All Rights Reserved.    */
/*.....................................................................*/

/*. The next line is for compatibility with older versions of TIFF256 .*/
#define tf_display_image tf_display_ifd

/*.....................................................................*/
/*                         Function Prototypes                         */
/*.....................................................................*/
extern void far cdecl tf_set_true_color_mode(int, int, int);
extern void far cdecl tf_get_true_color_mode(int far *, int far *,
                                             int far *);
extern void far cdecl tf_set_compression(int);
extern int  far cdecl tf_get_compression(void);
extern int  far cdecl tf_open_file(char far *);
extern void far cdecl tf_close_file(void);
extern int  far cdecl tf_get_file_info(void);
extern int  far cdecl tf_skip_ifd(unsigned);
extern void far cdecl tf_set_defaults(void);
extern int  far cdecl tf_read_ifd(void);
extern int  far cdecl tf_display_ifd(unsigned,unsigned);
extern int  far cdecl tf_display_subimage(int,int,int,int,int,int);
extern int  far cdecl tf_save_file(unsigned,unsigned,unsigned,unsigned,
                              char far *);
extern long far cdecl tf_image_size(void);
extern int  far cdecl tf_load_image(unsigned char huge *,
                                    unsigned char far *);
extern int  far cdecl tf_load_subimage(int,int,int,int,
                                       unsigned char huge*,
                                       unsigned char far *);
extern int  far cdecl tf_save_image(unsigned char huge *,
                                    unsigned char far *,
                                    char far *);
extern void far cdecl tf_set_prime_colors(void);
extern int  far cdecl tf_scan_file(char far *);
extern void far cdecl tf_decode_scan_error(int,int,int,int);
extern void far cdecl tf_about( void );







                                Page: 32
                                  
/*.....................................................................*/
/*                          Parameter Declarations                     */
/*.....................................................................*/

extern unsigned char far *TF_Byte_Buf;
extern unsigned long TF_ImageWidth, TF_ImageLength;
extern unsigned far TF_BitsPerSample[3],TF_Num_Ifd;
extern unsigned TF_ResolutionUnit,TF_SamplesPerPixel;
extern unsigned TF_Compression,TF_PhotometricInterpretation;
extern unsigned long TF_XResolution_int,TF_XResolution_frac;
extern unsigned long TF_YResolution_int,TF_YResolution_frac;
extern unsigned TF_Black,TF_Red,TF_Orange,TF_Yellow,TF_Green;
extern unsigned TF_Aqua,TF_Blue,TF_Violet,TF_White;








































                                Page: 33
