LIBSTIFF(3) Impressario LIBSTIFF(3)LIBRARY DESCRIPTIONlibstiff 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
Page 1
LIBSTIFF(3) Impressario LIBSTIFF(3)
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.
Page 2
LIBSTIFF(3) Impressario LIBSTIFF(3)
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.
Page 3
LIBSTIFF(3) Impressario LIBSTIFF(3)
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
Page 4
LIBSTIFF(3) Impressario LIBSTIFF(3)
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.
Page 5
LIBSTIFF(3) Impressario LIBSTIFF(3)
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
Page 6
LIBSTIFF(3) Impressario LIBSTIFF(3)
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 ALSOvstiff(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.
Page 7
