TIFF256 Graphics Library Extensions For C Programmers Version 1.0 July 6, 1992 Copyright Spyro Gumas, 1992. All Rights Reserved TIFF256 Graphics Library Extensions July 6, 1992 Version 1.0 1.0 Introduction 3 1.1 Some TIFF Insight 3 2.0 The TIFF256 Extensions Environment 4 2.1 Using The TIFF256 Extensions 4 2.2 Support of TIFF 5.0 4 2.3 Global Graphics Parameters 7 3.0 TIFF256 Extensions Functionality 8 3.1 Function Descriptions 8 3.1.1 tf_open_file 8 3.1.2 tf_close_file 8 3.1.3 tf_get_file_info 9 3.1.4 tf_skip_ifd 9 3.1.5 tf_set_defaults 10 3.1.6 tf_read_ifd 11 3.1.7 tf_display_image 12 3.1.8 tf_set_prime_colors 12 3.2 Handling The Color Look Up Table 13 4.0 Nitty Gritties 14 4.1 Registration Information 14 4.2 Software License 14 4.3 Disclaimer 14 4.4 Technical Support 15 5.0 Coming Attractions 16 6.0 Appendix 17 6.1 TIFF.H Include File 17 Page: 2 TIFF256 Graphics Library Extensions July 6, 1992 Version 1.0 1.0 Introduction The TIFF256 Extensions is a library of C routines which enhance the VSA256 Graphics Library to provide a C programmer with the tools necessary to display Tagged Image File Format (TIFF) images using a video adapter running with the VESA BIOS Extensions, Version 2.0. 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. The distribution of the TIFF256 Extensions consists of the 8 files listed below. These files are archived in the self extracting file TIF256.EXE. To extract, just type TIF256 in the directory that you want the files extracted to. When distributing the TIFF256 Extensions, distribute TIF256.EXE instead of the individual files. 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.1 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 (ie. 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: 3 TIFF256 Graphics Library Extensions July 6, 1992 Version 1.0 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 an SVGA video adapter card capable of 256 colors. A math coprocessor chip is not required, however if it exists, this library will take advantage of it. 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 are used in conjunction with the VSA256 Graphics Library Version 1.1 (Version 1.0 Won't Work, Find V1.1 in same place you got TIFF256 Extensions). 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; 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 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. Page: 4 TIFF256 Graphics Library Extensions July 6, 1992 Version 1.0 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: 5 TIFF256 Graphics Library Extensions July 6, 1992 Version 1.0 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: 6 TIFF256 Graphics Library Extensions July 6, 1992 Version 1.0 2.3 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. TF_XResolution_int: Unsigned long, the integral number of pixels in the x dimension per TF_Resolution Unit TF_XResolution_frac: Unsigned long, the fractional number of pixels in the x dimension per TF_Resolution Unit TF_YResolution_int: Unsigned long, the integral number of pixels in the y dimension per TF_Resolution Unit TF_YResolution_frac: Unsigned long, the fractional number of pixels in the y dimension per TF_Resolution Unit 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. Page: 7 TIFF256 Graphics Library Extensions July 6, 1992 Version 1.0 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 librarys 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 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.1.1 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(). Comments: 3.1.2 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. Comments: Page: 8 TIFF256 Graphics Library Extensions July 6, 1992 Version 1.0 3.1.3 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(). If an error occurs, this routine returns a 1, otherwise it returns a 0. Comments: 3.1.4 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. Comments: Page: 9 TIFF256 Graphics Library Extensions July 6, 1992 Version 1.0 3.1.5 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 Comments: Page: 10 TIFF256 Graphics Library Extensions July 6, 1992 Version 1.0 3.1.6 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_image can be called to display the IFD's image. If an error occurs, or this routine is called with the TIFF file pointer set to a null value, fail_flag is returned set to '1', otherwise it is returned set to '0'. 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 TF_Black TF_Red TF_Orange TF_Yellow TF_Green TF_Aqua TF_Blue TF_Violet TF_White Comments: Page: 11 TIFF256 Graphics Library Extensions July 6, 1992 Version 1.0 3.1.7 tf_display_image(x0,y0) Inputs: Unsigned x0; Unsigned y0; Returns: Nothing 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 with its top left corner at screen coordinates 'x0,y0'. The Color Look Up Table (CLUT) is not modified until this routine is executed. When executed, this routine prepares the CLUT as defined by the IFD being displayed. Before calling this routine, 'tf_read_ifd()' must be called to initialize all of the required parameters. 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 (return value = 1). 3.1.8 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 CLUT and loading each parameter with the CLUT 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 CLUT (such as tf_display_image). 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 CLUT operations. However, the color must exist in the CLUT for this routine to find it. Comments: Page: 12 TIFF256 Graphics Library Extensions July 6, 1992 Version 1.0 3.2 Handling The Color Look Up Table The TIFF256 Extensions supports Bilevel and 8 bit or less Grayscale (TF_PhotometricInterpretation = 1), 24 bit True Color (TF_PhotometricInterpretation = 2) and 8 bit or less Palette Color (TF_PhotometricInterpretation = 3) image types. Since this library is specifically designed for 256 entry Color Look Up Tables (CLUTs), for True Color images, 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 table. 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_image is called, even though the IFD may have already been read by tf_read_ifd(). This means that the previously loaded CLUT (typically from previously displayed IFD) remains in force until tf_display_image() is called. Page: 13 TIFF256 Graphics Library Extensions July 6, 1992 Version 1.0 4.0 Nitty Gritties 4.1 Registration Information If you find the TIFF256 Extensions useful, a registration of $20 would be appreciated. If you register, you will receive a diskette and manual for the next upgrade of the software (see Section 5.0 Coming Attractions). Please state 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 4.2 Software License TIFF256 Extensions, Version 1.0 Copyright Spyro Gumas, 1992. All Rights Reserved. You are free to copy and distribute the TIFF256 Extensions if: 1) It is used strictly for non-commercial purposes. 2) No fee is charged for use, copying or distribution. 3) It is not modified in any way. Clubs and user groups may charge a nominal fee not to exceed ($10) for expenses and handling while distributing the TIFF256 Extensions. Site licenses and commercial licenses for the TIFF256 Extensions are available. Consult the file ORDER.TXT for more information, or contact me for more information. 4.3 Disclaimer This software is provided "as is". All warranties relating to this software are disclaimed, whether expressed or implied, including without limitation any implied warranties of merchantability or fitness for a particular purpose. Neither the author nor an agent of the author will be liable for any special, incidental, consequential, indirect or similar damages due to loss of data or any other reason, even if the author or an agent of the author has been advised of the possibility of such damages. In no event shall the author's or an agent of the author's liability for any damages ever exceed the price paid for the license to use software, regardless of the form of the claim. The person using the software bears all risk as to the quality and performance of the software. Page: 14 TIFF256 Graphics Library Extensions July 6, 1992 Version 1.0 4.4 Technical Support If you have any questions or comments about the TIFF256 Extensions, please write me at: Spyro Gumas 1668 Shady Brook Drive Fullerton, Ca. 92631 Page: 15 TIFF256 Graphics Library Extensions July 6, 1992 Version 1.0 5.0 Coming Attractions This stuff is shareware. In an attempt to actually make make money with shareware, I have to have something that you want (I'm an optimist). To this end, I offer TIFF256 Extensions Version 2.0. Version 2.0 of the TIFF256 Extensions incorporates TIFF FILE WRITING capabilities so that you can generate a TIFF file of any image you generate or modify using the VSA256 Graphics Library. Version 2.0 also supports some additional TIFF Tags while preserving compatibility with the previous version. With the $20 registration fee, you will automatically receive this upgrade. Some of the Version 2.0 new TIFF features are: TIFF File Writing Capability Basic Tags - ColorResponseCurves GrayResponseCurve GrayResponseUnit PlanarConfiguration = 2 Informational Tags - Artist DateTime HostComputer ImageDescription Make Model Software Document Storage and Retrieval Tags - DocumentName PageName PageNumber XPosition YPosition Page: 16 TIFF256 Graphics Library Extensions July 6, 1992 Version 1.0 6.0 Appendix 6.1 TIFF.H Include File /*................................. TIFF.H ................ 5-30-92 ........*/ /* This file declares the TIFFLB library functions and global parameters */ /* used throughout the graphics routines. */ /* */ /* Copyright Spyro Gumas, 1992. All Rights Reserved. */ /*..........................................................................*/ /*..........................................................................*/ /* Function Prototypes */ /*..........................................................................*/ int _far _cdecl tf_open_file(char _far *); void _far _cdecl tf_close_file(void); int _far _cdecl tf_get_file_info(void); int _far _cdecl tf_skip_ifd(unsigned); void _far _cdecl tf_set_defaults(void); int _far _cdecl tf_read_ifd(void); void _far _cdecl tf_display_image(unsigned,unsigned); void _far _cdecl tf_set_prime_colors(void); /*..........................................................................*/ /* Parameter Declarations */ /*..........................................................................*/ unsigned long TF_ImageWidth, TF_ImageLength; unsigned TF_BitsPerSample[3],TF_Num_Ifd; unsigned TF_ResolutionUnit,TF_SamplesPerPixel; unsigned TF_PhotometricInterpretation; unsigned long TF_XResolution_int,TF_XResolution_frac; unsigned long TF_YResolution_int,TF_YResolution_frac; unsigned TF_Black,TF_Red,TF_Orange,TF_Yellow,TF_Green; unsigned TF_Aqua,TF_Blue,TF_Violet,TF_White; Page: 17