NAME

ilCrop() − extract a rectangular portion of a pipe image

SYNOPSIS

ilBool
ilCrop (

ilPipe pipe,

ilRect *pRect );

DESCRIPTION

ilCrop() adds a filter to the given pipe to extract a rectangular portion of the pipe image based on the value of *pRect. An equal-sized or smaller pipe image results. This call must be used while the pipe is forming (that is, ilQueryPipe(pipe, ...)  returns IL_PIPE_FORMING.) 

pipe identifies a pipe created by ilCreatePipe(). 

*pRect identifies an ilRect structure that defines the portion of the pipe image to extract. 

x is the left edge of the rectangle to be extracted. 

y is the top edge of the rectangle to be extracted. 

width is the width of the image from x. x + width is the right edge of the rectangle to be extracted. 

height is the height of the image from y.  y + height is the lower edge of the rectangle to be extracted. 

The actual rectangle extracted is defined as follows:

X = max(x,0)
Y = max(y,0),
WIDTH = min(w, x+width) - X
HEIGHT = min(h, y+height) - Y

where "w" and "h" are the width and height of the pipe image.  If the resulting width or height is less than or equal to zero (0), an error is declared and the pipe becomes invalid. 

RETURN VALUE

Upon successful completion, ilCrop() returns TRUE. 

ERRORS

If the call fails, context->error receives a non-zero error code.  If the pipe image after the crop has a width or height less than or equal to zero (0), an IL_ERROR_ZERO_SIZE_IMAGE error is returned. 

EXAMPLE

The following example adds a pipe filter to crop the image in the pipe.  The resultant image will be centered, and half the width and height of the current image. 

ilPipe pipe;

ilRect rect;

ilPipeInfo info;

ilImageDes des;

ilImageFormat format;
.
.
.

if (ilGetPipeInfo (pipe, FALSE, &info, &des, &format)

!= IL_PIPE_FORMING) {

if (!pipe->context->error)

return (ilDeclarePipeInvalid

(pipe, IL_ERROR_PIPE_STATE));

return (pipe->context->error);

}
rect.width = (info.width + 1) / 2;
rect.height= (info.height + 1) / 2;
rect.x     = (info.width / 4) + 1;
rect.y     = (info.height / 4) + 1;
if (!ilCrop (pipe, &rect)) return (pipe->context->error);

AUTHOR

ilCrop() was developed by HP. 

SEE ALSO

ilCreatePipe(3X). 

Using the Image Developer’s Kit.

Hewlett-Packard Company  —  Image Library: February, 1995