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
     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 CODES
     STReadImageHeader 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.

     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 ALSO
     libstiff(3), STAddTag(3).