ilScale(3X)

NAME

ilScale() − scale a pipe image and optionally convert the image type

SYNOPSIS

ilBool
ilScale (

ilPipe pipe,

long dstWidth,

long dstHeight,

int option,

void *pOptionData);

DESCRIPTION

ilScale() scales a pipe image to the given dimensions and optionally converts the image type.

pipe identifies a pipe created by ilCreatePipe().

dstWidth identifies the desired width; must be greater than zero (0).

dstHeight identifies the desired height; must be greater than zero (0).

option indicates the type of scaling to perform. Use one of the following values:

IL_SCALE_SIMPLE is the scaling method that gives the fastest scaling performance but the lowest image quality. This method uses pixel replication if the image is enlarged and pixel decimation if the image is being reduced. No image conversion is performed. pOptionData must be NULL.

IL_SCALE_SAMPLE is the scaling method that gives highest quality scaling results. This method only applies to scaling an image down, but future releases of the Image Developer’s Kit might add scaling up support to this option. In scaling the image down, IL_SCALE_SAMPLE uses area sampling techniques. If the pipe image is a color palette image, it is first converted to an IL_RGB image before it is scaled by area sampling.

To scale down bitonal images, this method scales by temporarily converting the image to an averaged grayscale type; it then sets the pixels as either on or off, based on a threshold value that can be set by *pOptionData. High threshold values darken the image; low thresholds lighten it. For text-oriented images, such as FAX images, the default threshold of 192 is recommended. For pictorial images, a threshold value of 128 is recommended.

For all image types, if the image is being enlarged, this option scales by replication and performs no image conversion.

IL_SCALE_BITONAL_TO_GRAY is a scaling method that applies only when scaling down bitonal images. It converts bitonal images to grayscale and uses area sampling techniques to scale the image down. An error results if dstWidth is not smaller than or equal to the pipe image width and dstHeight is not smaller than or equal to the pipe image height.

*pOptionData if option is set to IL_SCALE_SIMPLE, set *pOptionData to NULL.

if option is set to IL_SCALE_SAMPLE and the current pipe image is IL_BITONAL, *pOptionData must point to an unsigned long threshold that has a value between 0 and 255. The image is converted to IL_GRAY; it is then scaled and converted back to IL_BITONAL using the threshold value pointed to by pOptionData.

if option is set to IL_SCALE_BITONAL_TO_GRAY, *pOptionData must point to the unsigned long containing the number of grays in the resulting image; if this pointer is NULL, the default (recommended) value of 256 is used. The number of grays must be between 2 and 256.

RETURN VALUE

Upon successful completion, ilScale() returns TRUE.

ERRORS

If the call fails, context->error receives a non-zero error code.

EXAMPLE

The following example adds to the pipe a filter that scales the pipe image by a factor of 2.

ilContext context;

ilPipe pipe;

long width;

long height;
.
.
.

if (ilQueryPipe(pipe, &width, &height, NULL) != IL_PIPE_FORMING)

return(IL_ERROR_PIPE_STATE);

if (!(ilScale(pipe, width * 2, height * 2, IL_SCALE_SIMPLE, NULL)))

return (context->error);

AUTHOR

ilScale() was developed by HP.

Museum

Related Articles