STReadImageHeader(3) Impressario STReadImageHeader(3)NAME
STReadImageHeader, STWriteImageHeader - read/write STIFF image header
SYNOPSIS
#include <stdio.h>
#include <stiff.h>
int STReadImageHeader(STStream *st, STImageHeader *hd);
int STWriteImageHeader(STStream *st, STImageHeader *hd,
int last);
DESCRIPTION
Before an image is read from a STIFF stream an image header must be
obtained from the stream. Similarly, before an image is written to a
STIFF stream an image header structure must be filled in and written to
the stream. The functions STReadImageHeader and STWriteImageHeader assist
with these image header tasks.
STReadImageHeader reads the image header information from the stream
specified by st and places the information in the image header structure
specified by hd. st must point to a STIFF stream open for reading.
Following a successful call to STReadImageHeader, the function STRead can
be called to read the actual image data. The amount of image data
available can be found in the STImageHeader structure. In addition,
following a successful call to STReadImageHeader the TIFF tag list read
from the STIFF stream can be queried using the STGetTag function.
After the last image has been read from a STIFF stream, the next call to
STReadImageHeader will return -1, and STerrno will be set to STEEOF (see
below).
STWriteImageHeader writes the image header to the STIFF stream specified
by st. Before a call to STWriteImageHeader any caller specific TIFF tags
should be added to the output tag list using the STAddTag function.
Make sure that all fields of the STImageHeader structure passed to
STWriteImageHeader contain reasonable values; otherwise, garbage will be
written into the STIFF stream.
Following a successful call to STWriteImageHeader the actual image data
can be written to the stream using STWrite. The amount of image data that
must be written to the stream is specified in the STImageHeader
structure. Note that following a successful call to STWriteImageHeader
the output TIFF tag list is cleared.
The last parameter to STWriteImageHeader should be set to 1 if this is to
be the last image written to this stream. In this case,
STWriteImageHeader will store a value in the stream to indicate to
readers that this is the last image. last should be set to 0 if more
images are to be written after this one, in which case STWriteImageHeader
calculates the offset of where the next image will start and stores that
Page 1
STReadImageHeader(3) Impressario STReadImageHeader(3)
location in the stream.
The STImageHeader structure is defined as follows.
typedef struct tag_imghdr {
unsigned long width, height; /* Dimensions in pixels */
unsigned short bitsPerSample; /* Bits per channel */
unsigned short samplesPerPixel; /* # of color channels */
unsigned long imgbytes; /* Bytes of image data */
STType type; /* Image data type */
STPlane plane; /* Planar configuration */
} STImageHeader;
TIFF TAGS USED
The STWriteImageHeader function will write the TIFF tags listed below
into the STIFF stream. Caller specific tags would be output in addition
to the tags listed. The tags are expressed in terms of their names in the
header file stiff.h
STBitsPerSample
STImageLength
STImageWidth
STPhotometricInterpretation
STPlanarConfiguration
STSamplesPerPixel
STStripByteCounts
STStripOffsets
RETURN VALUE
Both STReadImageHeader and STWriteImageHeader return 0 if execution was
successful. -1 is returned and STerrno is set if an execution error has
occurred.
EXECUTION ERROR CODESSTReadImageHeader will fail under the following circumstances.
STEBADTAG Invalid TIFF tag.
STENOMEM Out of memory.
STEREADFROMWRITE Attempt to read from a write stream.
STESYSCALL System call failed.
STENEEDSEEK Operation requires seeking on a stream.
STEEOF End of stream.
STWriteImageHeader will fail under the following circumstances.
Page 2
STReadImageHeader(3) Impressario STReadImageHeader(3)
STEBADTAG Invalid TIFF tag.
STENOMEM Out of memory.
STEWRITETOREAD Attempt to write to a read only stream.
STESYSCALL System call failed.
STENEEDSEEK Operation requires seeking on a stream.
SEE ALSOlibstiff(3), STAddTag(3).
Page 3
