libstiff(3)
As shipped in IRIX 6.5.22. Unchanged since IRIX 6.5.
This page could not be fully tidied (no-name); it is shown as printed.
LIBRARY DESCRIPTION libstiff provides a C Language application programming interface (API) for the reading and writing of Stream TIFF files. Stream TIFF (STIFF) is a subset of the Tag Image File Format (TIFF) originally developed by Aldus Corporation. The TIFF file format is an extremely flexible format well suited for monochrome and color bitmap images. The difference between TIFF and STIFF is that while a TIFF file may require file seeking during reading or writing a STIFF file does not. This means that a STIFF file can be read from and written to non-seekable streams such as pipes and sockets. It is important to note that a STIFF file may be read by any TIFF reader that conforms to the TIFF Revision 6.0 specification. However, the libstiff API should not be used to read standard TIFF files. The functions provided by libstiff greatly simplify the reading and writing of TIFF compatible files. Using the STIFF API, TIFF compatible files can be read and written without the need to understand the structure of a TIFF file and without the need to explicitly specify TIFF tags. LIBRARY ACCESS There are two sets of libstiff functions. One set comprises the generic libstiff API. These functions are designated by an ST prefix. These functions may be used to read and write generic STIFF files. To access these functions an application must include the header file stiff.h located in the /usr/include directory. The second set of libstiff functions are a subset of the generic functions and are tailored to reading and writing STIFF files that are to be passed between printing filters and drivers. These printing related functions are designated by the prefix PST and are accessed through the header file printstiff.h also located in /usr/include. If printstiff.h is used, the header stiff.h need not be specified. The generic and printing specific functions may be freely intermixed within an application. All libstiff functions require that the stdio.h file be included. Programs that call libstiff functions must link with the libstiff.a library located in the directory /usr/lib. FUNCTIONS Generic Functions Stream Handling STOpen STClose STSkipTo Reading and Writing STReadImageHeader STWriteImageHeader STRead STWrite TIFF Tag Support STAddTag STRemoveTag STGetTag STPrintTags Execution Error Handling STPerror STErrorString Printing Specific Functions Reading and Writing PSTReadImageHeader PSTWriteImageHeader USING THE LIBSTIFF FUNCTIONS Writing A STIFF File The typical sequence of operations for writing a STIFF file is as follows: 1. Obtain a writable file descriptor. Note that this descriptor can be associated with a non-seekable stream. 2. Call STOpen with the writable file descriptor and the flag ST_WRITE. 3. Fill in the STIFF image header (STImageHeader or PSTImageHeader). 4. Optionally, add any application specific TIFF tags to the file using STAddTag. 5. Call the image header write function STWriteImageHeader. 6. Write the image data using STWrite. 7. Repeat steps 3 through 6 for each page of image data. 8. Close the STIFF stream using STClose. 9. Close the file descriptor. Reading A STIFF File The typical sequence of operations for reading a STIFF file is as follows: 1. Obtain a readable file descriptor. Note that this descriptor can be associated with a non-seekable stream. 2. Call STOpen with the readable file descriptor and the flag ST_READ. 3. Call the image header read function STReadImageHeader or PSTReadImageHeader. 4. Access the fields of the image header structure to determine the amount of image data to be read for this page. 5. Optionally, obtain the values for any application specific TIFF tags from the file using STGetTag. 6. Read the image data using STRead. 7. Repeat steps 3 through 6 for each page of image data. The last page of image data will either have its last image header field set to one or will be an empty page (i.e. amount of data equals zero). 8. Close the STIFF stream using STClose. 9. Close the file descriptor. If an error condition is returned by a libstiff function, STPerror can be used to print a diagnostic error message to the standard error. GENERIC STIFF FILE STRUCTURE While it is not necessary to understand the STIFF file structure to use libstiff, this explanation is provided for those who need to know. A Stream TIFF file is first and foremost a valid TIFF file. STIFF is derived from the TIFF 6.0 Specification available from Aldus Corporation (see below). The terms used below to describe a STIFF file (e.g. IFD) are explained in the TIFF specification and will not be described here. The primary restriction STIFF places on the TIFF structure is that all data must be read from or written to the file without the need to seek within the file. Specifically, within a STIFF file: 1. The bitmap image data must be in page number order. 2. Data which does not fit in the value section of a tag must be located immediately after the IFD and must occur in the same order in which the tags are encountered. The exception to this is the image data itself, which must come last for each page. 3. Image data must immediately follow the IFD and any offset values associated with it. 4. A terminating, empty IFD will always be added to the end of the STIFF file. This IFD guarantees that an IFD with 0000 in its 'next IFD' field will appear in the IFD chain. Note that this empty IFD will not be encountered when following IFD pointers if the last 'real' IFD is written with the 'last' parameter set to 1. While the TIFF specification states that IFDs should not be empty, relaxing this restriction appears to have no impact on TIFF compatibility. A STIFF file can be represented diagrammatically as: _______________________________ TIFF header (8 bytes) _______________________________ Optional intervening space _______________________________ IFD for page 1 _______________________________ Data for long values in IFD 1 _______________________________ Image data for page 1 _______________________________ Optional intervening space _______________________________ IFD for page 2 _______________________________ Data for long values in IFD 2 _______________________________ Image data for page 2 _______________________________ ... _______________________________ Terminating empty IFD _______________________________ | | The libstiff functions support only the Motorola (MM) byte ordering. In addition to supporting TIFF class B, G and R data, libstiff supports the CMYK color image data type (PhotoMetricInterpretation = 5 and InkSet = 1) and four additional color image separation types: CMY, YMC, YMCK, and KCMY. For these additional types, PhotoMetricInterpretation = 5, InkSet = 2, NumberOfInks = 3 or 4, and the InkNames tag is used to indicate the inks contained in each channel. When reading an image header, libstiff parses the ink names for these additional types, and sets the type field of the STImageHeader structure to the appropriate value defined in <stiff.h>. When writing an image header, libstiff writes the appropriate PhotoMetricInterpretation, InkSet, NumberOfInks, and InkNames tags based on the value of the type field of the STImageHeader structure. The CMYK data class is a TIFF data format extension. Tag Possible Values _________________________________________________________ BitsPerSample (1,1,1,1) (4,4,4,4) (8,8,8,8) PhotoMetricInterpretation 5 SamplesPerPixel 4 PlanarConfiguration 1,2 NumberOfInks 4 The CMY data class is a subset of the CMYK class and differs from the CMYK class in a TIFF compliant manner. In the description of the SamplesPerPixel tag below, "1 bit planar" refers to the case where BitsPerSample has the value (1,1,1,1) and PlanarConfiguration has the value 2. Tag Possible Values _____________________________________________________________ BitsPerSample (1,1,1,1) (1,1,1) (4,4,4) (8,8,8) PhotoMetricInterpretation 5 SamplesPerPixel 3 (4 for 1 bit planar) PlanarConfiguration 1,2 NumberOfInks 3 The YMC data class is a class similar to the CMY class with the exception that data is organized as YMC instead of CMY. When using libstiff, YMC data corresponds to the data type ST_TYPE_YMC. Tag Possible Values _____________________________________________________________ BitsPerSample (1,1,1,1) (1,1,1) (4,4,4) (8,8,8) PhotoMetricInterpretation 5 SamplesPerPixel 3 (4 for 1 bit planar) PlanarConfiguration 1,2 NumberOfInks 3 InkSet 2 InkNames yellow,magenta,cyan The YMCK class is a class similar to the CMYK class with the exception that data is organized as YMCK instead of CMYK. When using libstiff, YMCK data corresponds to the data type ST_TYPE_YMCK. Tag Possible Values _________________________________________________________ BitsPerSample (1,1,1,1) (4,4,4,4) (8,8,8,8) PhotoMetricInterpretation 5 SamplesPerPixel 4 PlanarConfiguration 1,2 NumberOfInks 4 InkSet 2 InkNames yellow,magenta,cyan,black The KCMY class is a class similar to the CMYK class with the exception that the data is organized as KCMY instead of CMYK. When using libstiff, KCMY data corresponds to the data type ST_TYPE_KCMY. Tag Possible Values _________________________________________________________ BitsPerSample (1,1,1,1) (4,4,4,4) (8,8,8,8) PhotoMetricInterpretation 5 SamplesPerPixel 4 PlanarConfiguration 1,2 NumberOfInks 4 InkSet 2 InkNames black,cyan,magenta,yellow Note that for the RGB, CMY, and YMC classes with BitsPerSample values of (1,1,1) and a PlanarConfiguration value of 1, pixels are stored two to a byte, with the bits ordered from most to least significant. For example, CMY data is stored as: CMY0CMY0. Rows are padded to contain an integral number of bytes. Refer to the header file stiff.h for additional information regarding the STIFF file structure. PRINTING SPECIFIC STIFF The printing specific functions (PST) provided by libstiff to read and write STIFF files as described above. The printing specific aspect of these functions is found in the image header structure. The printing specific image header (PSTImageHeader) contains all fields of the (STImageHeader) plus printing specific information fields such as image resolution and halftoning method. If a STIFF stream is written using the generic functions and is read using the printing specific functions, default values will be used for the PSTImageHeader fields not found in the STIFF stream. Similarly, a STIFF stream written using the printing specific functions can be read by the generic functions. In this case, the additional information in the stream can be ignored or obtained using the STGetTag function. Refer to the header file printstiff.h for additional information regarding printing specific STIFF. SEE ALSO vstiff(1), zoomstiff(1). TIFF 6.0 Specification - Aldus Corporation, 1992. For a copy of the TIFF 6.0 specification contact Aldus Developers Desk, Aldus Corporation, 411 First Avenue South, Seattle, WA 98104-2871, (206) 628-6593.