Appendix B. Silicon Graphics Image File Format API
Prev |  | Next

## Appendix B. Silicon Graphics Image File Format API

This appendix describes `libimp`, the C application program interface (API) for reading and writing Silicon Graphics image format files.

The following major topics are discussed:

- “Library Description”

- “Library Access”

- “Library Functions”

- “IMPImage Structure”

## Library Description

`libimp` provides a C application program interface (API) for reading and writing Silicon Graphics image format files and for performing a number of format-independent image processing operations. These operations include color space conversion and filtered image zooming.

`libimp` provides all functionality of the `libimage` library. (See the `rgb(4)` reference page for a description of `libimage`.) In addition, `libimp` provides function prototypes, a documented interface, reliable error reporting, and a number of other enhancements.

## Library Access

A program that calls `libimp` functions must include the header file `imp.h` located in the directory `/usr/include`. In addition, the program must link with the `libimp.a` library located in `/usr/lib`. The link line would look like this:

    ... -limp ...

## Library Functions

The `libimp` library, which is based heavily on the `libimage` and `libgutil` libraries, consists of two main sets of functions. The functions shown in Table B-1 perform operations on Silicon Graphics image format files.

Table B-1. Silicon Graphics Image Format File Functions

Task | Function | Description
--- | --- | ---
Image Access | impOpen() | Opens a Silicon Graphics image format file for reading or writing
| impOpenFd() | Opens a Silicon Graphics image format file for reading or writing
| impClose() | Closes a Silicon Graphics image format file
| impCloseFd() | Closes a Silicon Graphics image format file
Image I/O | impReadRow() | Reads image row
| impReadRowB() | Reads byte image row
| impWriteRow() | Writes image row
| impWriteRowB() | Writes byte image row

The functions shown in Table B-2 perform operations on image data in a format-independent manner.

Table B-2. Format-Independent File Functions

Task | Function | Description
--- | --- | ---
Zooming | impCreateZoom() | Creates zoom operator
| impDestroyZoom() | Destroys zoom operator
| impResetZoom() | Resets zoom row cache
| impZoomRow() | Zooms an image row
Data Packing | impPackRow() | Packs two-byte data into one byte
| impUnpackRow() | Unpacks one-byte data into two bytes
Math Operations | impZeroRow() | Sets row to zero
| impInitRow() | Initializes a row to a value
| impCopyRow() | Copies a row
| impSAddRow() | Adds a value to a row
| impVAddRow() | Adds two rows
| impSSubRow() | Subtracts a value from a row
| impVSubRow() | Subtracts two rows
| impSMulRow() | Multiplies a row by a value
| impSDivRow() | Divides a row by a value
| impClampRow() | Clamps row values
Color Space Conversion | impRGBtoW() | Converts an array from RGB to W format
| impWtoRGB() | Converts an array from W to RGB format
| impRGBtoK() | Converts an array from RGB to K format
| impKtoRGB() | Converts an array from K to RGB format
| impRGBtoCMY() | Converts an array from RGB to CMY format
| impCMYtoRGB() | Converts an array from CMY to RGB format
| impRGBtoYIQ() | Converts an array from RGB to YIQ format
| impYIQtoRGB() | Converts an array fromYIQ to RGB format
| impRGBtoYUV() | Converts an array from RGB to YUV format
| impYUVtoRGB() | Converts an array from YUV to RGB format
| impRGBtoYCbCr() | Converts array from RGB to YCbCr format
| impYCbCrtoRGB() | Converts array from YCbCr to RGB format
| impRGBtoCMYK() | Converts array from RGB to CMYK format
| impCMYKtoRGB() | Converts array from CMYK to RGB format
| impRGBtoDevCMYK() | Converts array from RGB to device CMYK format
| impRGBtoHSV() | Converts an array from RGB to HSV format
| impHSVtoRGB() | Converts an array from HSV to RGB format
| impRGBtoHLS() | Converts an array from RGB to HLS format
| impHLStoRGB() | Converts an array from HLS to RGB format
Error Handling | impPerror() | Prints `libimp` execution error messages to standard error
| impErrorString() | Obtains `libimp` execution error messages

## IMPImage Structure

The IMPImage structure contains public and private information about a Silicon Graphics image file. This structure is identical both in size and field naming to the IMAGE structure defined in the header file `image.h`, included by applications that use the `libimage` library. While it has been common practice to directly modify the public fields of the image structure, this is not recommended. Macros are defined in `imp.h` for manipulating the structure fields. It is strongly recommended that these macros be used to set and get values from the image structure. The IMPImage structure is defined as follows:

    typedef struct _impImage {
        /******* Public image header information (archived) */
        ushort_t imagic;  /* Silicon Graphics image file magic number */
        ushort_t type;    /* Raster type (e.g. verbatim, rle) */
        ushort_t dim;     /* Image dimension */
        ushort_t xsize;   /* X size (pixels) */
        ushort_t ysize;   /* Y size (pixels) */
        ushort_t zsize;   /* Number of channels (e.g. rgb = 3) */
        long     min;     /* Minimum intensity in image */
        long     max;     /* Maximum intensity in image */
        ulong_t  wastebytes;            /* Padding */
        char     name[IMP_NAME_MAX+1];  /* Image name */
        ulong_t  colormap;              /* Image type (e.g. colormap, normal) */

        /******* Private image header information (core use only) */
        long     file;
        ushort_t flags;
        short    dorev;
        short    x;
        short    y;
        short    z;
        short    cnt;
        short    *ptr;
        short    *base;
        short    *tmpbuf;
        ulong_t  offset;
        ulong_t  rleend;
        ulong_t  *rowstart;
        long     *rowsize;
    } IMPImage;

| Note: ushort_t and ulong_t are unsigned short and unsigned long, respectively.

Fields:

magic |  | Magic number identifying file as a Silicon Graphics image format file.
type |  | Bitwise-OR combined code indicating the raster encoding method and the number of bytes per pixel per channel. Currently, Silicon Graphics image files support either a verbatim, uncompressed raster encoding or a run-length, compressed encoding. Both of these encodings are available at one or two bytes per pixel per channel. The header file `imp.h` defines codes for all supported combinations of encoding methods and pixel widths.
dim |  | Number of dimensions to the image. A colormap file has dimension one (length), a black and white image has dimension two (height and width), and an RGB image has dimension three (height, width, and depth).
xsize, ysize |  | Image size in pixels.
zsize |  | Number of color channels or depth. A black and white image has one channel and an RGB image has three channels.
min, max |  | The minimum and maximum intensity values in the image. These values are the minimum and maximum for all channels combined.
name |  | A descriptive name string for the image.
colormap |  | The image type. Refer to `imp.h` for the supported image type codes. The field is named colormap for compatibility with the IMAGE structure used by the `libimage` library.

## Image Access Functions

### impOpen() Function

This function opens the image file specified by fname. If mode is r, the file is opened for reading. If mode is w, the file is opened for writing and created if it does not exist, or truncated to zero length if it does exist.

`impOpenFd()` opens the image file pointed to by the file descriptor fd. The descriptor's permissions must permit the operations specified by mode. That is, if mode is w, the descriptor must have write permission. In addition, it must be possible to seek on the specified descriptor. At this time, read/write mode is not supported for Silicon Graphics image files. Upon successful execution, both functions return a pointer to a Silicon Graphics image file structure.

Synopsis:

    #include <imp.h>

    IMPImage* impOpen(const char *fname, const char *mode, ...);
    IMPImage* impOpenFd(int fd, const char *mode, ...);

In write mode, `impOpen()` and `impOpenFd()` require that these additional parameters be specified:

    uint_t rasterType,dimension, xSize, ySize, numChannels, imageType;
    char *name;

| Note: uint_t stands for unsigned int.

Arguments:

rasterType |  | Specifies the raster encoding method and the number of bytes per pixel per channel. Silicon Graphics image format files can be written either uncompressed or with run-length encoding compression, and with one or two bytes per pixel per channel. Refer to `imp.h` for the supported raster types.
dimension |  | Specifies the number of dimensions in the image. A colormap file has dimension one, a black and white image has dimension two, and an RGB image has dimension three.
xSize, ySize |  | Specifies the image size in pixels.
numChannels |  | Specifies the number of image color channels. A black and white image has one channel and an RGB image has three channels.
imageType |  | Specifies how the image data is to be interpreted. Image data is either actual color values (normal), screen colormap indices (screen), or a colormap (colormap). Refer to imp.h for the supported image types.
name |  | Specifies a descriptive string for the image. Strings longer than IMP_NAME_MAX characters are truncated. Refer to `imp.h` for the value of IMP_NAME_MAX. If this parameter is specified as NULL, the string “no name” is written into the file. Use the empty string "" to write an empty name string into the image.

### impOpen(), impOpenFd(), impClose(), and impCloseFd() Functions

`impClose()` closes a Silicon Graphics image format file previously opened by `impOpen()` or `impOpenFd()`. Among other tasks, `impClose()` closes the file descriptor associated with an image file. If the image was opened using `impOpenFd()`, the file descriptor specified in that function call is closed by `impClose()`.

`impCloseFd()` performs the same function as `impClose()`, but it leaves open the file descriptor associated with the image and returns it in the parameter fdp. It then becomes the responsibility of the caller to close the file descriptor when it is no longer needed. It is essential that either `impClose()` or `impCloseFd()` be called at the completion of writing a Silicon Graphics image file so that all buffered data can be written and the image header can be updated.

Synopsis:

    #include <imp.h>

    int impClose(IMPImage *image);
    int impCloseFd(IMPImage *image, int *fdp);

Return Value:

`impOpen()` and `impOpenFd()` return a pointer to an image structure if execution was successful. NULL is returned and IMPerrno is set if an execution error has occurred.

`impClose()` and `impCloseFd()` return 0 if execution was successful; a -1 is returned and IMPerrno is set if an execution error has occurred.

Execution Error Codes:

`impOpen()` and `impOpenFd()` fail with the following errors:

- IMP_ERR_READWRITE

- IMP_ERR_MEMALLOC

- IMP_ERR_BADMAGIC

- IMP_ERR_BADRASTER

- IMP_ERR_BADIMAGE

In addition, `impOpenFd()` fails with the following errors:

- IMP_ERR_BADFD

- IMP_ERR_SEEK

`impClose()` and `impCloseFd()` fail with the following errors:

- IMP_ERR_WRITEFLAG

- IMP_ERR_BADBPP

- IMP_ERR_BADIMAGE

| Note: The storage for the IMPImage structure is allocated by the image open function. This storage is deallocated by the `impClose()` and `impCloseFd()` functions. The caller should not explicitly reallocate or deallocate any storage related to the image structure.

See also:

`libimp(3`), `impReadRow(3)`, `impReadRowB(3)`

### Data Packing Functions

#### impPackRow() and impUnpackRow() Functions

Synopsis:

    #include <imp.h>

    void impPackRow(uchar_t *dptr, short *sptr, int n);
    void impUnpackRow(short *dptr, uchar_t *sptr, int n);

`impPackRow()` converts the array of short integers pointed to by sptr into the array of unsigned char values pointed to by dptr. Source data that is too large to fit in a character is truncated. For example, the source value 0x0B56 is converted into 0x56 in the destination array. `impUnpackRow()` converts the array of unsigned char values pointed to by sptr into the array of short integers pointed to by dptr. For example, the source value 0x56 is converted into 0x0056 in the destination array. The parameter n specifies the number of elements in the source and destination arrays.

| Note: The allocation of storage for the source and destination arrays is the responsibility of the caller.

See also:

`libimp(3)`

### Error Handling Functions

#### impPerror() and impErrorString() Functions

Synopsis:

    #include <imp.h>

    void impPerror(const char *str);
    char* impErrorString(int errCode);
    extern int IMPerrno;

`impPerror()` prints error messages to standard error in a format similar to the standard C library function `perror(3C)`. If an error occurs during a `libimp` function call, the global error variable IMPerrno is set with an error code. The error code is either a system error code (errno) or a `libimp`-specific code. The symbolic names for the `libimp` error codes are defined in `imp.h`. The value of IMPerrno is used by `impPerror()` as an index to a table of error messages.

`impPerror()` prints user-supplied string str followed by a colon (:), a space, and the error message corresponding to the current value of IMPerrno.

If the string str is the NULL string (""), no colon or space is printed, only the error message. The error message is either a system error message or a `libimp`-specific message. To be of most use, a call to impPerror should be made immediately following the `libimp` function call where an error has been detected.`impErrorString()` is similar to the `strerror(3C)` function and returns the error message corresponding to the error code specified by errCode.

If errCode is less than IMP_ERR_BASE, the message returned is a system error message generated by `strerror`. If errCode is one of the error codes specified in `imp.h`, the returned string is a `libimp`-specific error message.

See also:

`libimp(3)`, `perror(3C)`, `strerror(3C)`

### Image I/O Functions

#### impReadRow(), impReadRowB(), impWriteRow(), and impWriteRowB() Functions

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);

`impReadRow()` and `impReadRowB()` each read a row of image data from the specified channel of a Silicon Graphics image format file.

`impReadRow()` stores the row data in an array of short integers and can read image data that is one or two bytes per pixel per channel in width. `impReadRowB()` stores the data in a character array and can handle only 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 a Silicon Graphics image file. `impWriteRow()` writes one or two bytes 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 bytes per pixel per channel data.

| Note: The functions make use of the following macros:

`impXSize` |  | Returns the number of pixels in an image file in the X direction.
`impYSize` |  | Returns the number of pixels in an image file in the Y direction.
`impNumChannels` |  | Returns the number of color channels in an image. It returns 3 if the image is RGB, 4 if it is CMYK, and 1 if it is monochrome

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`)` x `sizeof(`short`)` if `impReadRow()` or `impWriteRow()` is used, and `impXSize(`image`)` if `impReadRowB()` or `impWriteRowB()` is used.
row |  | The image row to read. Rows are numbered from 0 through `impYSize(`image) minus 1.
channel |  | The image channel to read. Channels are numbered from 0 through `impNumChannels`(image) minus 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:

`impWriteRow()` and `impWriteRowB()` fail with the following errors:

- IMP_ERR_WRITEFLAG

- IMP_ERR_BADBPP

- IMP_ERR_BADIMAGE

- IMP_ERR_SHORTWRITE

`impReadRow()` and `impReadRowB()` fail with the following errors:

- IMP_ERR_READFLAG

- IMP_ERR_BADBPP

- IMP_ERR_BADIMAGE

- IMP_ERR_SHORTREAD

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

See also:

`libimp(3)`, `impOpen(3)`

### Color Space Conversion Functions

These functions perform color space conversion between a given color space and RGB. The actual transformations performed are described below. Certain functions specify the parameter unity. unity should be set to the value of maximum possible intensity for the arrays specified. For example, if 8-bit data is being converted, unity would be specified as 255. If the data makes use of the full 16 bits available in each array element, unity would be specified as 65535. Note that the parameter n specifies the number of elements in the arrays and not the number of bytes.

#### impRGBtoW(), impWtoRGB() Functions

Figure B-1 shows the equation for W conversions.

Figure B-1. W Conversions

Synopsis:

    #include <imp.h>

    void impRGBtoW(short *rbuf, short *gbuf, short *bbuf,
       short *wbuf, int n);

    void impWtoRGB(short *wbuf, short *rbuf, short *gbuf,
        short *bbuf, int n);

#### impRGBtoK(), impKtoRGB() Functions

Figure B-2 shows the equation for K conversions.

Figure B-2. K Conversions

Synopsis:

    #include <imp.h>

    void impRGBtoK(short *rbuf, short *gbuf, short *bbuf,
       short *kbuf, short unity, int n);

    void impKtoRGB(short *kbuf, short *rbuf, short *gbuf,
        short *bbuf, short unity, int n);

#### impRGBtoCMY(), impCMYtoRGB() Functions

Figure B-3 shows the equation for CMY conversions.

Figure B-3. CMY Conversions

Synopsis:

    #include <imp.h>

    void impRGBtoCMY(short *rbuf, short *gbuf, short *bbuf,
       short *cbuf, short *mbuf, short *ybuf,
       short unity, int n);

    void impCMYtoRGB(short *cbuf, short *mbuf, short *ybuf,
       short *rbuf, short *gbuf, short *bbuf,
       short unity, int n);

#### impRGBtoYIQ(), impYIQtoRGB() Functions

Figure B-4 shows the equation for YIQ conversions.

Figure B-4. YIQ Conversions

Synopsis:

    #include <imp.h>

    void impRGBtoYIQ(short *rbuf, short *gbuf, short *bbuf,
       short *ybuf, short *ibuf, short *qbuf,
       int n);

    void impYIQtoRGB(short *ybuf, short *ibuf, short *qbuf,
       short *rbuf, short *gbuf, short *bbuf,
       int n);

#### impRGBtoYUV(), impYUVtoRGB() Functions

Figure B-5 shows the equation for YUV conversions.

Figure B-5. YUV Conversions

Synopsis:

    #include <imp.h>

    void impRGBtoYUV(short *rbuf, short *gbuf, short *bbuf,
       short *ybuf, short *ubuf, short *vbuf,
       int n);

    void impYUVtoRGB(short *ybuf, short *ubuf, short *vbuf,
       short *rbuf, short *gbuf, short *bbuf,
       int n);

#### impRGBtoYCbCr(), impYCbCrtoRGB() Functions

Figure B-6 shows the equation for YCbCr conversions.

Figure B-6. YCbCr Conversions

Synopsis:

    #include <imp.h>

    void impRGBtoYCbCr(short *rbuf, short *gbuf, short *bbuf,
       short *ybuf, short *cbbuf, short *crbuf, int n);

    void impYCbCrtoRGB(short *ybuf, short *cbbuf, short *crbuf,
       short *rbuf, short *gbuf, short *bbuf, int n);

#### impRGBtoCMYK(), impRGBtoDevCMYK(), impCMYKtoRGB() Functions

Figure B-7 shows the equation for CMYK conversions.

Figure B-7. CMYK Conversions

Synopsis:

    #include <imp.h>

    void impRGBtoCMYK(short *rbuf, short *gbuf, short *bbuf,
       short *cbuf, short *mbuf, short *ybug,
       short *kbuf, short unity, int n);

    void impRGBtoDevCMYK(short *rbuf, short *gbuf, short *bbuf,
       short *cbuf, short *mbuf, short *ybug,
       short *kbuf, IMPUCRFunc ucr, IMPBGFunc bg,
       short unity, int n);

    short (*IMPBGFunc)(short k);
    short (*IMPUCRFunc)(short k);

    void impCMYKtoRGB(short *cbuf, short *mbuf, short *ybuf,
       short *kbuf, short *rbuf, short *gbug,
       short *bbuf, short unity, int n);

#### impRGBtoHSV(), impHSVtoRGB() Functions

Synopsis:

    #include <imp.h>

    void impRGBtoHSV(short *rbuf, short *gbuf, short *bbuf,
       float *hbuf, float *sbuf, float *vbuf, int n);

    void impHSVtoRGB(float *hbuf, float *sbuf, float *vbuf,
       short *rbuf, short *gbuf, short *bbuf, int n);

#### impRGBtoHLS(), impHLStoRGB() Functions

For HSV conversions, refer to Computer Graphics, Principals and Practice, Foley and Van Dam, 2nd Edition, pages 590-592. For HLS conversions, refer to pages 592-595.

Synopsis:

    #include <imp.h>

    void impRGBtoHLS(short *rbuf, short *gbuf, short *bbuf,
       float *hbuf, float *lbuf, float *sbuf,
       short unity, int n);

    void impHLStoRGB(float *hbuf, float *lbuf, float *sbuf,
       short *rbuf, short *gbuf, short *bbuf,
       short unity, int n);

| Note: It is the caller's responsibility to allocate all buffer storage.

See also:

`libimp(3)`

### Math Operation Functions

#### impZeroRow(), impInitRow(), impCopyRow(), impSAddRow(), impVAddRow(), impSSubRow(), impVSubRow(), impSMulRow(), impSDivRow(), impClampRow() Functions

Synopsis:

    #include <imp.h>

    void impZeroRow(short *dptr, int n);

    void impInitRow(short *dptr, int val, int n);

    void impCopyRow(short *dptr, short *sptr, int n);

    void impSAddRow(short *dptr, short *sptr, int val, int n);

    void impVAddRow(short *dptr, short *sptr1, short *sptr2, int n);

    void impSSubRow(short *dptr, short *sptr, int val, int n);

    void impVSubRow(short *dptr, short *sptr1, short *sptr2, int n);

    void impSMulRow(short *dptr, short *sptr, int val, int n);

    void impSDivRow(short *dptr, short *sptr, int val, int n);

    void impClampRow(short *dptr, short *sptr, int lov, int hiv, int n);

In the following descriptions, the parameter n specifies the number of elements in an array and not the number of bytes in the array. In addition, functions that take a source array pointer and a destination array pointer can specify the same array as both a source and destination.

impZeroRow |  | Initializes to zero the array pointed to by dptr.
impInitRow |  | Initializes the array dptr to the value val.
impCopyRow |  | Copies the array sptr to the array dptr.
impSAddRow |  | Adds the value val to each element of the array sptr and stores the result in the array dptr.
impVAddRow |  | Adds the corresponding elements of sptr1 and sptr2 and stores the result in the array dptr.
impSSubRow |  | Subtracts the value val from each element of the array sptr and stores the result in the array dptr.
impVSubRow |  | Subtracts the corresponding elements of sptr2 from those of sptr1 and stores the result in the array dptr.
impSMulRow |  | Multiplies each element of the array sptr by val and stores the result in dptr.
impSDivRow |  | Divides each element of the array sptr by val and stores the result in dptr.
impClampRow |  | Clamps the values of the array sptr between the values lov and hiv inclusive. The result is stored in the array dptr.

| Note: It is the caller's responsibility to allocate all buffer storage. Also, because the arrays referenced by these functions are short integer arrays, the caller should be aware of overflow/wraparound conditions.

See also:

`libimp(3)`

### Zooming Functions

#### impCreateZoom(), impDestroyZoom(), impResetZoom(), impZoomRow() Functions

Synopsis:

    #include <imp.h>

    IMPZoom* impCreateZoom(ushort_t srcXSize, ushort_t srcYSize,
       ushort_t dstXSize, ushort_t dstYSize,
       IMPReadRowFunc readRowFunc,
       int numChannels,
       IMPFilterType filterType,
       float blurFactor);

    void impDestroyZoom(IMPZoom *zoom);

    void impResetZoom(IMPZoom *zoom);

    int impZoomRow(IMPZoom *zoom, short *buffer,
       ushort_t row, void *clientData);

The `libimp` library provides an API for performing image resizing or zooming. Images can be zoomed up or down using any of a number of resampling methods. The resampling methods divide into two categories. The first resampling category is non-filtered zooming (also known as replicative zoom, decimation). The second resampling category is filtered zooming where a filter of a given shape is applied to the data. The image zooming is performed on a row-by-row basis using a one-pass, two-dimensional convolution.

To zoom one or more rows of an image, first create a zoom operator by calling `impCreateZoom()`. One of the parameters to `impCreateZoom()` is a pointer to a function that is called during the zoom to read rows of the source image. To obtain zoomed rows, call `impZoomRow()`. When all desired zoomed rows have been obtained, call `impDestroyZoom()` to deallocate storage held by the zoom operator. When filtered zooming is performed, a number of contiguous rows of image data are cached. Often all rows of a given image channel are zoomed, followed by all rows of the next channel. Since rows are cached, the cache should be flushed when switching between image channels. The `impResetZoom()` function performs this row cache flushing operation.

The `impCreateZoom()` function has the following parameters:

srcXSize, srcYSize |  | Width and height of the source image in pixels.
dstXSize, dstYSize |  | Width and height of the destination (that is, zoomed) image in pixels.
readRowFunc |  | Pointer to a function that is called to read a row from the source image. The prototype for this function is
    int (*IMPReadRowFunc)(short *buffer,
       ushort_t row,
       void *clientData);

The function should read the image row indicated by row and place the data in buffer. The storage for buffer is allocated and deallocated by the zoom operator and should not be manipulated by the read row function. clientData is a pointer to caller-specific information. The caller may specify a pointer to client data when calling the `impZoomRow()` function. That pointer is passed to the read row function.

At the caller's discretion, this pointer may be set to NULL. A common use of the client data is to pass a pointer to a structure containing the image structure pointer and the channel number. The read row function must return -1 if it encounters an error while obtaining the row data and must return a value of 0 or greater if the function succeeds.

numChannels |  | Specifies the number of channels of image data that are packed on a single row. For example, if each row contains data for only a single channel, then numChannels should be specified as one. However, if each row contains RGB data packed together as RGBRGBRGB..., numChannels should be specified as three.
filterType |  | Specifies the type of filter to be used for resampling the image during zooming.
|  | The filter types available are
Filter Type | Category
IMPImpulse | Replicative
IMPBox | Filtered
IMPTriangle | Filtered
IMPQuadratic | Filtered
IMPMitchell | Filtered
IMPGaussian | Filtered
Refer to “Filter Functions” for detailed information on the available filters.
blurFactor |  | Specifies a multiplier for the width of the filter. The default blur factor is 1.0. Higher factors increase the amount of blur present in the image.

The `impZoomRow()` function has the following parameters:

zoom |  | Pointer to a zoom operator structure obtained from a call to `impCreateZoom()`.
buffer |  | Caller-allocated buffer that is filled with the zoomed image row data. The buffer should be allocated to accommodated dstXSize * numChannels * `sizeof`(short) bytes.
row |  | The desired zoomed row. Rows are numbered from 0 through dstYSize minus 1. clientData is a pointer to client data. This pointer is passed to the readRowFunc. A typical use of this is for passing a pointer to a structure containing the IMPImage pointer and the channel number.

#### Filter Functions

The resampling filters available for zooming are summarized below. Note that the span of the filter (x range) is expressed in terms of the original image, not the zoomed image. Table B-3 lists the available filter functions.

Table B-3. Filter Functions

Filter Type | Function | Span
--- | --- | ---
IMPImpulse | Not Applicable |
IMPBox | f(x) = 0.0 | x < -0.5
| f(x) = 1.0 | -0.5 <= x < 0.5
| f(x) = 0.0 | x >= 0.5
IMPTriangle | f(x) = 0.0 | x < -1.0
| f(x) = 1.0+x | -1.0 <= x < 0.0
| f(x) = 1.0-x | 0.0 <= x < 1.0
| f(x) = 0.0 | x >= 1.0
IMPQuadratic | f(x) = 0.0 | x < -1.5
| f(x) = 0.5*(x+1.5)^2 | -1.5 <= x < -0.5
| f(x) = 0.75-x^2 | -0.5 <= x < 0.5
| f(x) = 0.5*(x-1.5)^2 | 0.5 <= x < 1.5
| f(x) = 0.0 | x >= 1.5
IMPMitchell | b = 1.0/3.0 |
| c = 1.0/3.0 |
| p0 = (6.0-2.0*b)/6.0 |
| p2 = (-18.0+12.0*b+6.0*c)/6.0 |
| p3 = (12.0-9.0*b-6.0*c)/6.0 |
| q0 = (8.0*b+24.0*c)/6.0 |
| q1 = (-12.0*b-48.0*c)/6.0 |
| q2 = (6.0*b+30.0*c)/6.0 |
| q3 = (-b-6.0*c)/6.0 |
| f(x) = 0.0 | x < -2.0
| f(x) = q0-x*(q1-x*(q2-x*q3)) | -2.0 <= x < -1.0
| f(x) = p0+x*x*(p2-x*p3) | -1.0 <= x < 0.0
| f(x) = p0+x*x*(p2+x*p3) | 0.0 <= x < 1.0
| f(x) = q0+x*(q1+x*(q2+x*q3)) | 1.0 <= x < 2.0
| f(x) = 0.0 | x >= 2.0
IMPGaussian | a(x) = 1.0/exp((1.5*x)^2) |
| b(x) = 1.0/exp(1.5^4) |
| f(x) = a(x)-b(x) |

Return Value:

The `impCreateZoom()` function returns a pointer to a zoom operator structure if execution was successful. NULL is returned and IMPerrno is set if an execution error has occurred.

The `impZoomRow()` function returns 0 if execution was successful. -1 is returned and IMPerrno is set if an execution error occurred.

Execution Error Codes:

The `impCreateZoom()` function fails with the following error:

- IMP_ERR_MEMALLOC

The `impZoomRow()` function fails with the following error:

- IMP_ERR_READROW

| Note: The storage for the IMPZoom structure is allocated by the zoom operator creation function. This storage is deallocated by the `impDestroyZoom()` function. The caller should not explicitly reallocate or deallocate any storage related to the image structure. Furthermore, the fields of the IMPZoom structure are private and should not be modified by the caller.

See also:

`libimp(3)`

Prev | Table of Contents | Next
Appendix A. Stream TIFF Data Format |  | Appendix C. Printer Object Database (POD) File Formats