
                                
                                
                                
                                
                                
                                
                                
                                
                                
                                
                               TIFF256
                          Graphics Library
                             Extensions
                                  
                          For C Programmers
                                  
                             Version 3.0
                            July 28, 1994
                                  
                                  
                 Copyright Spyro Gumas, 1992 - 1994.
                         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!
          -    Graphical User Interface 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)
                                
                                
                                
                                
                                
                                
                                
                                

                                
                                Page: 1
                                   
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                               14
     3.2.5 tf_get_file_info                            15
     3.2.6 tf_skip_ifd                                 15
     3.2.7 tf_set_defaults                             16
     3.2.8 tf_read_ifd                                 16
     3.2.9 tf_display_ifd                              17
     3.2.10 tf_save_file                               18
     3.2.11 tf_image_size                              19
     3.2.12 tf_load_image                              19
     3.2.13 tf_save_image                              20
     3.2.14 tf_set_prime_colors                        21
4.0 Nitty Gritties                                     22
  4.1 Registration Information                         22
  4.2 Software License                                 23
  4.3 Disclaimer                                       24
  4.4 Technical Support                                24
5.0 Appendix                                           25
  5.1 TIFF.H Include File                              25



















                                Page: 2
                                   
1.0 Introduction

     The TIFF256 Graphics Library Extensions Version 3.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 1.0 is the original SHAREWARE version of the TIFF256 Graphics
Library Extensions.

-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 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.

  **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.


                                Page: 4
                                   
  **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.























  




                                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
                         SATURN.TIF

                                Page: 6
                                   
                         NEPTUNE.TIF
                         SHUTTLE.TIF
                         ASTRONTS.TIF
                         WEATHER.TIF
                         MANDRILL.TIF

1.3 Distribution Files

     The distribution of the TIFF256 Graphics Library Extensions
Version 3.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 3.0 are used in conjunction with
the VSA256 Graphics Library Version 3.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_get_file_info() and tf_read_ifd() functions and
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_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.


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
                                
                                
                                
                                
                                
                                
                                Page: 9
                                   
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
          ImageLength
          ImageWidth
          NewSubFileType
          PhotometricInterpretation = Bilevel and Grayscale
          PhotometricInterpretation = RGB (True Color)
          PhotometricInterpretation = Palette Color
          PlanarConfiguration = 1
          ResolutionUnit
          RowsPerStrip
          SamplesPerPixel
          StripByteCounts
          StripOffsets
          XResolution
          YResolution
          
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 = LZW Compression
          Compression = PackBits Compression
          GrayResponseCurve
          GrayResponseUnit
          PhotometricInterpretation = Transparency Mask
          PlanarConfiguration = 2
          Predictor
                                
                                
                                
                                
                                
                                
                                
                                
                                
                                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 pixel 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.9) is called, even though the IFD may
have already been read by '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.12) instead of 'tf_display_ifd', the
CLUT is not loaded until the program deems 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' and 'tf_load_image' 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.
               24 bit True Color images are reduced to 8 bit images using 
          either the 332-RGB, Dithered, or Adaptive Palette method.  When 
          'mode' = 0, the 332-RGB method is used.  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.  When 
          'mode' = 1, the Dithered method is used.  Again a True Color 
          palette is loaded, but the pixel intensities are modulated (or 
          dithered) in a technique which approximates all of the 16 million 
          possible colors.  When 'mode' = 2, the Adaptive Palette method is 
          used.  In this case 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 at the expense of smooth shading).  If 
          'mode' is not 2, the 'num_colors' and 'quality' parameters are
          ignored.

Availability:  In TIFF256 Graphics Library Version 3.0 and up.

                                
                                
                                
                                
                                
                                
                                Page: 13
                                   
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 before calling
          tf_get_file_info().

Availability:  In TIFF256 Graphics Library Version 1.0 and up.

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().  This routine should be called before
          exiting your program.

Availability:  In TIFF256 Graphics Library Version 1.0 and up.










                                Page: 14
                                   
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.

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.






                                Page: 15
                                   
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_PhotometricInterpretation  =    1
               TF_XResolution_int            =    300
               TF_XResolution_frac           =    1
               TF_YResolution_int            =    300
               TF_YResolution_frac           =    1
               
Availability:  In TIFF256 Graphics Library Version 1.0 and up.

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' or 'tf_load_image' can be
          called to display the IFD's image.  The 'fail_flag' is
          returned with one of the following values:

                                
                                
                                
                                Page: 16
                                   
                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  Compressed TIFF data 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_PhotometricInterpretation
                    TF_XResolution_int
                    TF_XResolution_frac
                    TF_YResolution_int
                    TF_YResolution_frac

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.

3.2.9 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_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
                                
                                
                                
                                
                                
                                
                                Page: 17
                                   
          defined by the IFD being displayed.  Before calling this
          routine, '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, otherwise 0 is returned.  In the
          case where the allocation fails, 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 also
          useful when the run time environment has insufficient
          memory for allocating the huge image memory buffer used
          with 'tf_load_image'.

Availability:  In TIFF256 Graphics Library Version 1.0 and up.

Comments: This routine may be called more than once per 'tf_read_ifd'
          call.  Please DO NOT call this routine if 'tf_read_ifd'
          returns an error (fail_flag = 1).

3.2.10 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.  If an error occurs in writing the
          file, a -1 is returned, otherwise 0 is returned.
               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 = 1
                 - ImageWidth = |x1-x0|+1 (pixels)
                                Page: 18
                                   
                 - ImageLength = |y1-y0|+1 (pixels)
                 - Resolution Unit = 2 (inches)
                 - XResolution = 100 (Dots Per Inch)
                 - YResolution = 100 (Dots Per Inch)
                 - Compression = none

Availability:  In TIFF256 Graphics Library Version 2.0 and up.

3.2.11 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_read_ifd'.  Before
          calling this routine, 'tf_read_ifd' must be called to
          define all of the required global parameters.  The size is
          based on 8 bit pixels regardless of the image type since
          'tf_load_image' always converts to 8 bit pixels as it reads
          the TIFF file.  The size returned is equal to 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: This routine may be called more than once per 'tf_read_ifd'
          call.  Please DO NOT call this routine if 'tf_read_ifd'
          returns an error (fail_flag = 1).

3.2.12 tf_load_image(image,lut)

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

Returns:  int colors;

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_read_ifd'.  The images 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 'colors' indicates how many
          of the 256 colors in 'lut' are actually used (0 or 1
          indicates an error).  Before calling this routine,
          'tf_read_ifd' must be called to initialize all of the
          required parameters.
                                
                                Page: 19
                                   
              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 the case where the allocation
          fails, the program can disable Adaptive Palette and call
          this routine again.
              The 'image' buffer 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 triplets 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.

Availability:  In TIFF256 Graphics Library Version 3.0 and up.

Comments: This routine may be called more than once per 'tf_read_ifd'
          call.  Please DO NOT call this routine if 'tf_read_ifd'
          returns an error (fail_flag = 1).

3.2.13 tf_save_image(image,lut,filename)

Inputs:   unsigned char huge *image;
          unsigned char far *lut;
          char 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
          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..  If an error occurs in
          writing the file, a -1 is returned, otherwise 0 is returned.
                                Page: 20
                                   
              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'.
              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 = 1
                - 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

Availability:  In TIFF256 Graphics Library Version 3.0 and up.

3.2.14 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: 21
                                   
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
                       1668 Shady Brook Drive
                        Fullerton, Ca. 92631
                                  

                                
                                
                                
                                
                                
                                
                                
                                
                                
                                
                                
                                
                                
                                
                                
                                
                                
                                
                                
                                
                                
                                
                                
                                
                                
                                
                                
                                
                                
                                
                                
                                
                                
                                
                                Page: 22
                                   
4.2 Software License

                TIFF256 Graphics Library, Version 3.0
      Copyright Spyro Gumas, 1992 - 1994.  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 - 1994.  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
                                
                                
                                
                                Page: 23
                                   
contact  Spyro  Gumas  at the address below for  authorization.  This
authorization   will   be  automatically  granted   to   distributors
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
                       1668 Shady Brook Drive
                        Fullerton, Ca. 92631

Or, contact me on EMAIL!

            CompuServ  71064,1571
            Internet:  71064.1571@compuserve.com


                                
                                
                                
                                
                                
                                
                                
                                
                                
                                Page: 24
                                   
5.0 Appendix

5.1 TIFF.H Include File

/*................................. TIFF.H ................ 7-28-94 ........*/
/* This file declares the TIFFLB library functions and global parameters    */
/* used throughout the graphics routines (Version 3.0).                     */
/*                                                                          */
/*       Copyright Spyro Gumas, 1992 - 1994.  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 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_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_save_image(unsigned char huge*,unsigned char
                                    far*,char far *);
extern void far cdecl tf_set_prime_colors(void);

/*..........................................................................*/
/*                          Parameter Declarations                          */
/*..........................................................................*/

extern unsigned char far TF_Byte_Buf[4096];
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_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: 25

