In this manual the entire TIFF file is referred to as an “image chain.” An image chain has properties that can be retrieved by the function GetTiffFileInfo. Properties of individual images (tag data) can be retrieved by using functions GetTiffImageInfoBuffer and GetTiffImageInfo.
When you open a TIFF file, only the image chain data is read into memory. You can refer to this structure by a handle of TIFFFILE type. This handle can be used to register an image from the file. Registering an image means that the TIFF Image Directory (TID) of the specified image is read into memory. Other images can be registered at any time, or existing ones can be compressed or decompressed. This ability allows you to keep only the information actually needed at any given time in memory.
Generally, you have a handle to an opened or created TIFF image chain, along with an image handle to the specified image in the chain. Functions manipulating on whole image chains require the image chain handle (of TIFFFILE type) as a parameter. Those functions manipulating a specific image in the chain requires both the image chain handle and the image handle.
The image handle is simply the zero-base index of the image when you are reading a TIFF file. The first image in the chain will have an index of zero and there is no maximum number of images that can be stored in a file. The basic functions for manipulating image chains and individual images are listed below:
TIFFFILE CALLBACK OpenTiffFile(LPSTR IpszFileName, int nMode);
BOOL CALLBACK CloseTiffFile(TIFFFILE hChain);
BOOL CALLBACK GetTiffImage(TIFFFILE hChain, int nImage);
int CALLBACK DefineTiffImage(TIFFFILE hChain);
BOOL CALLBACK DropTiffImage(TIFFFILE hChain, int nImage);
Using GetTiffImage(), you can reach the images in a TIFF file in any order. On the other hand, when you define a TIFF image using DefineTiffImage() you cannot specify the order of the images in the file. It depends only on the sequence you call EncodeTiffImage() to actually write the image data into the TIFF file.
OpenTiffFile() requires approximately 100 bytes. Each GetTiffImage() call reads a TID into the memory which may require additional memory (roughly 100 bytes). DefineTiffImage() allocates only an initial buffer for the new (empty) TID. That buffer will be reallocated and enlarged if you call DefineTiffImageInfoBuffer() or DefineTiffImageInfo() to explicitly define the tags. DropTiffImage() clears a TID from the memory, releasing its buffer. The image data itself (the pixels) are read into the memory only if you call the decode functions, and it is handled by the user through callback functions.
Below is a simplified structure of reading and writing a TIFF file:
TIFFFILE hChain;
int nImage;
nImage=0; //The first image.
hChain=OpenTiffFile(lpszFileName,T_READ)
if(hChain !=NULL
{
// The first image in the chain is 0 and NOT 1
if(GetTiffImage(hChain,nImage))
{
...calling information and
...decoding functions
DropTiffImage(hChain,nImage);
}
CloseTiffFile(hChain);
}
TIFFFILE hChain;
int nImage;
hChain = OpenTiffFile(lpszFileName,T_WRITE)
if(hChain != NULL)
{
nImage = DefineTiffFile(hChain)
if(nImage != -1)
{
...Calling information defining and
...encoding functions
DropTiffImage(hChain,nImage)
}
CloseTiffFile(hChain);
}
Calling OpenTiffFile() with the nMode parameter equals with T_APPEND. You can read the TID of an existing file into the memory in a form, which gives you the possibility of appending new images to the file.
Besides OpenTiffFile and CloseTiffFile, there are only three other functions that work on whole image chains and thus require only the image chain handle as parameter. These are:
BOOL CALLBACK GetTiffFileInfo(TIFFFILE hChain, TIFFHDR FAR *Info);
BOOL CALLBACK ModiTiffFileInfo(TIFFFILE hChain, LPSTR IpszFileName,
int nByteOrder);
int CALLBACK NumberOfTiffImages(TIFFFILE hChain, WORD wImageType);
GetTiffFileInfo() retrieves basic information on a TIFF file. The Info parameter has the following form as defined in BITIFF.H:
typedef struct tag_TIFFHDR {
char cFileName[MAXPATH]; TIFF file name
int nByteOrder; Byte order in the file
int iNImages; Number of images in the TIFF
DWORD dwFirstTID; Offset of first TID in the file
} TIFFHDR;
The nByteOrder is either LH_BYTE_ORDER or HL_BYTE_ORDER. The number of images in a TIFF file is given by iNImages.
ModiTiffFileInfo() can be used to modify the associated file name or the byte order.
NumberOfTiffImages() returns with the number of images that match the filter given in wImageType. See the description in the section named Using the Document Imaging SDK