impReadRow(3)

NAME
     impReadRow, impReadRowB, impWriteRow, impWriteRowB - read/write SGI Image
     Format files

SYNOPSIS
     #include <imp.h>

     int impReadRow(IMPImage *image, short *buffer,
                    ushort_t row, ushort_t channel);

     int impReadRowB(IMPImage *image, uchar_t *buffer,
                     ushort_t row, ushort_t channel);

     int impWriteRow(IMPImage *image, short *buffer,
                     ushort_t row, ushort_t channel);

     int impWriteRowB(IMPImage *image, uchar_t *buffer,
                      ushort_t row, ushort_t channel);

DESCRIPTION
     impReadRow and impReadRowB each read a row of image data from the
     specified channel of an SGI Image Format file.  impReadRow stores the row
     data in an array of short integers and therefore can read image data that
     is either one or two bytes per pixel per channel in width. impReadRowB
     stores the data in a character array and can only handle image data that
     is one byte per pixel per channel wide.  If impReadRowB is called to read
     image data that is two bytes per pixel per channel, an error condition is
     reported.

     impWriteRow and impWriteRowB each write a row of image data to the
     specified channel of an SGI Image file. impWriteRow writes one or two
     byte per pixel per channel image row data. impWriteRowB writes only one
     byte per pixel data. It is an error to use impWriteRowB to write to
     images that expect two byte per pixel per channel data.

     The functions take the following parameters.

     image          Pointer to an IMPImage structure returned by a call to
                    impOpen or impOpenFd.

     buffer         Caller allocated buffer containing the data to write to or
                    to be filled with the data read from the image. The amount
                    of storage allocated for the buffer should be
                    impXSize(image) * sizeof(short) if impReadRow or
                    impWriteRow functions are used and impXSize(image) if
                    impReadRowB or impWriteRowB are used.

     row            The image row to read. Rows are numbered from 0 through
                    impYSize(image) - 1.
     channel        The image channel to read. Channels are numbered from 0
                    through impNumChannels(image) - 1.

RETURN VALUE
     If execution was successful, all functions return the number of pixels
     (not bytes) read or written. If an execution error occurred, -1 is
     returned and IMPerrno is set.

EXECUTION ERROR CODES
     In addition to the system error codes defined in errno.h, the following
     libimp specific error codes may be returned.

     impWriteRow and impWriteRowB will fail under the following circumstances.

     IMP_ERR_WRITEFLAG        Attempt to write to an image file not opened for
                              writing.

     IMP_ERR_BADBPP           Unsupported bytes per pixel value. Refer to
                              imp.h for supported BPP values.

     IMP_ERR_BADIMAGE         Unrecognized image type. Refer to imp.h for
                              supported image types.

     IMP_ERR_SHORTWRITE       A complete row of data could not be written.

     impReadRow and impReadRowB will fail under the following circumstances.

     IMP_ERR_READFLAG         Attempt to read from an image file not opened
                              for reading.

     IMP_ERR_BADBPP           Unsupported bytes per pixel value. Refer to
                              imp.h for supported BPP values.

     IMP_ERR_BADIMAGE         Unrecognized image type. Refer to imp.h for
                              supported image types.

     IMP_ERR_SHORTREAD        The amount of data read was less than the amount
                              expected based on the image size.

NOTE
     It is the caller's responsibility to allocate enough buffer storage for
     image row data.

SEE ALSO
     libimp(3), impOpen(3)