ilGetPipeInfo(3X)

NAME

ilGetPipeInfo() − return information about an Image Library pipe prior to using ilAddPipeElement()

SYNOPSIS

unsigned int
ilGetPipeInfo (

ilPipe pipe,

ilBool forceDecompress,

ilPipeInfo *pInfo,

ilImageDes *pDes

ilImageFormat *pFormat);

DESCRIPTION

ilGetPipeInfo() returns the current state of a pipe, which can be IL_PIPE_FORMING, IL_PIPE_INVALID, IL_PIPE_EMPTY, IL_PIPE_COMPLETE, or IL_PIPE_EXECUTING. ilGetPipeInfo() is usually used before using ilAddPipeElement() to add an application-defined element to the pipe. Other code should use ilQueryPipe() to obtain the pipe state.

If the pipe state is IL_PIPE_FORMING, ilGetPipeInfo() optionally decompresses the image, if compressed, and returns the currently defined image information, such as image format and description. The caller can check this information to determine if ilConvert() must be used on the image before the pipe element can handle it.

If the pipe state is IL_PIPE_EMPTY, only a producer can be added to the pipe; if the state is IL_PIPE_FORMING, either a filter or a consumer can be added. For other states, no elements can be added and the pipe state should be set to IL_PIPE_INVALID. Take care not to overwrite the error code in the pipe; IL_PIPE_INVALID is returned if an error occurs.

pipe identifies an ilPipe structure created by ilCreatePipe().

forceDecompress if TRUE and the returned pipe state is IL_PIPE_FORMING, adds a pipe element to decompress the image, if it is compressed.

*pInfo receives the contents of the currently defined ilPipeInfo structure if the returned pipe state is IL_PIPE_FORMING and pInfo is not NULL. *pInfo contains the following fields:

producerObject set by ilAddPipeElement() for the producer of this pipe; for use by internal Image Library elements only.

tempImage if FALSE, indicates the previous element in the pipe was added by ilReadImage(); in other words, the source image for the next element to be added is a permanent image. If TRUE, the source image is a temporary image created by ilExecutePipe(). This field can be ignored in most cases.

width identifies the width of the current pipe image.

height identifies the height of the current pipe image.

constantstrip if TRUE, the previous pipe element outputs strips that are uniformally of the size defined by stripHeight, except for the last strip, which can be smaller. If FALSE, the strip height may vary.

stripHeight identifies the height of the strips output by the previous pipe element.

recommendedStripHeight
identifies the strip height used by ilAddPipeElement() if either the ilAddPipeElement() parameter pSrcData is NULL or pSrcData->stripHeight is zero (0).

*pPalette if the pipe image is a palette image (pDes->type is equal to IL_PALETTE), must point to the palette for the pipe image. Palettes are an array of shorts in the following order: 256 red values, 256 green values, 256 blue values.

pCompData identifies a field that is for use by internal Image Library elements only.

filler identifies a field that is reserved for future use.

*pDes receives the contents of the currently defined ilImageDes structure if the returned pipe state is IL_PIPE_FORMING and pDes is not NULL.

*pFormat receives the contents of the currently defined ilImageFormat structure if the returned pipe state is IL_PIPE_FORMING and pFormat is not NULL.

RETURN VALUE

Upon successful completion, ilGetPipeInfo() returns the current state of the pipe and, if the state is IL_PIPE_FORMING, returns the currently defined image information.

ERRORS

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

EXAMPLE

The following example gets pipeinfo, descriptor and format of the current image in the pipe pipe. If the pipe state is not IL_PIPE_FORMING then an error is returned.

ilPipe pipe;

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

}

AUTHOR

ilGetPipeInfo() was developed by HP.

Museum

Related Articles