NAME

ilAddPipeElement() − add an application-defined element to an Image Library pipe

SYNOPSIS

ilPtr
ilAddPipeElement (

ilPipe pipe,

int elementType,

unsigned int nBytesPrivate,

unsigned long flags,

ilSrcElementData *pSrcData,

ilDstElementData *pDstData,

ilError (*Init)(),

ilError (*Cleanup)(),

ilError (*Destroy)(),

ilError (*Execute)(),

unsigned long mustBeZero);

DESCRIPTION

ilAddPipeElement() adds an application-defined element to an Image Library pipe and returns an ilPtr, which is a pointer to a client private block.  The returned ilPtr is passed as the parameter pPrivate to all functions associated with this pipe element.  The private block is available for use by the caller. However, the caller must not free the private block; it is freed by the Image Library when this pipe element is destroyed. 

If an error occurs, ilAddPipeElement() returns NULL (0) and sets the pipe state of the pipe identified to IL_PIPE_INVALID. 

Before using ilAddPipeElement(), the application can use ilGetPipeInfo() to obtain the current state of the pipe. 

pipe identifies an ilPipe structure created by ilCreatePipe(). 

elementType can be one of the following:

IL_PRODUCER identifies the element as a producer and changes the pipe state from IL_PIPE_EMPTY to IL_PIPE_FORMING. 

IL_FILTER identifies the element as a filter and makes no change to the pipe state, which must be IL_PIPE_FORMING. 

IL_CONSUMER identifies the element as a consumer and changes the pipe state from IL_PIPE_FORMING to IL_PIPE_COMPLETE. 

IL_HOOK uses the *Init(), *Cleanup(), or *Destroy() functions, which are called with the parameters described subsequently in this man page.  However, an element is not actually added to the pipe.  The pipe state must be IL_PIPE_EMPTY, IL_PIPE_FORMING, or IL_PIPE_COMPLETE, and it is not changed by this call.  flags, *pSrcData, *pDstData, and *Execute() are ignored. 

If *Init() is not NULL, it is called before all of the *Init() functions for standard pipe elements.  The pSrcImage and pDstImage parameters of *Init() always have the value NULL.  If *Cleanup() is not NULL, it is called after all of the *Cleanup() functions for standard pipe elements. If *Destroy() is not NULL, it is called after all of the *Cleanup() functions for standard pipe elements. 

nBytesPrivate determines the length, in bytes, of the client private block pointed to by the returned ilPtr.  The size of the private block is only what is needed by the client filter; no data is required for the Image Library. 

flags identifies a bit  field of options.  The following mask values set options; all other bits must be set to zero (0). 

IL_ADD_PIPE_NO_DST
used internally by the Image Library;  not to be used by client.

IL_ADD_PIPE_HOLD_SRC
used internally by the Image Library; not to be used by client.

IL_ADD_PIPE_HOLD_DST
set this option if the pipe element  requires the output destination image buffer to retain its contents between invocations of the Execute() function.  If this option is not set the contents of the output buffer are undefined before each time Execute() is called. 

*pSrcData if not NULL, and the pipe element is not a producer, identifies an input data structure that is used by the caller.  If elementType is set to IL_PRODUCER.  *pSrcData is ignored.  If NULL, *pSrcData uses the default values shown with the field definitions that follow:

consumerImage
identifies a value that must be NULL.  This field is used internally by the Image Library. 

The default value is NULL. 

stripHeight identifies the required height of all source strips presented to this pipe element.  If stripHeight is not zero, but constantStrip is TRUE, all but the last strip are stripHeight lines high. If stripHeight is zero, the default values for stripHeight and constantStrip are used. 

The default value is ilPipeInfo.recommendedStripHeight for filters and ilPipeInfo.stripHeight for consumers. 

constantStrip
if TRUE, all but the last source strip presented to this pipe element will be stripHeight lines high; the last strip can be less.  If FALSE, strips can be less than stripHeight lines high. 

The default value is FALSE. 

minBufferHeight
identifies a value that must be zero (0). This field is used internally by the Image Library.

The default value is NULL. 

*pDstData if not NULL, describes the output image buffer.  *pDstData must be not be NULL if elementType is IL_PRODUCER, but is ignored if elementType is IL_CONSUMER.  If NULL, *pDstData uses the default values shown with the field definitions that follow:

producerObject
used internally by the Image Library; must be NULL. 

The default value is NULL. 

pDes points to a descriptor ( ilImageDes ) of the image to be output by this pipe element; must be not be NULL if elementType is IL_PRODUCER.  Set to NULL if the pipe element does not change the image attributes the descriptors for the input and output image match. 

The default value is NULL. 

pFormat points to the format ( ilImageFormat ) of the image to be output by this pipe element; it must not be NULL if elementType is set to IL_PRODUCER.  Set to NULL if the pipe element does not change the image format the input and output image formats match).  For more details on format, see ilImageFormat(5). 

The default value is NULL. 

width indicates the width in pixels of the output image.  For filters and consumers, set width to the value supplied for ilPipeInfo.width unless the pipe element scales the image. 

The default value is ilPipeInfo.width. 

height indicates the height in pixels of the output image.  For filters and consumers, set height to the value supplied for ilPipeInfo.height unless the pipe element scales the image. 

The default value is ilPipeInfo.height. 

stripHeight identifies the maximum height of a strip output by this pipe element; must be non-zero if elementType is set to IL_PRODUCER.  Zero (0) dictates that the output strips from this element will be the same size as the input strips. 

The default value is zero (0). 

constantStrip
if TRUE, all but the last strip written by this pipe element will be stripHeight lines high.  If FALSE, strips written can be less than stripHeight lines high. 

ilPipeInfo.constantStrip or pSrcData->constantStrip is the default value, if one of them is defined; otherwise, the default value is FALSE. 

pPalette is a pointer to the palette for the pipe image, which is needed if elementType is set to IL_PRODUCER and pDstData->pDes->type is set to IL_PALETTE.  Otherwise, set pPalette to NULL.  The palette must exist until freed by the producer’s Cleanup() function.  The values in the palette must already be filled in, unless they will be filled in by either Init() or the first execution of the Execute() function for this pipe element.  If not NULL, pPalette points to an array of 256*3 unsigned shorts. The array contains three sections of 256 values of red, green and blue. Each image pixel indexes into each section to determine an R.C value. 

The default value is NULL. 

*Init() identifies a function that is called each time pipe execution begins; if set to IL_NPF, no function is called.  *Init() is called as follows:

ilError
*Init()

ilPtr pPrivate,

ilImageInfo *pSrcImage,

ilImageInfo *pDstImage);

pPrivate receives the ilPtr returned by ilAddPipeElement(). 

*pSrcImage
points to the source image for this element; set to NULL if the elementType for the element being called is IL_PRODUCER.  If the image is compressed, the values for pSrcImage->plane must be loaded on each call to Execute(). Note that the palette entries in pSrcImage->pPalette may be undefined at this time and may not be available until Execute() is later called. 

*pDstImage
identifies the destination image for this element; set to NULL if the elementType for the element being called is IL_CONSUMER.  If the image is compressed, the values for pSrcImage->plane must be loaded on each call to *Execute ().

*Cleanup() identifies a function that is called each time pipe execution completes or is aborted; if set to IL_NPF, no function is called.  If *Cleanup() and *Init() are both non-null (IL_NPF), they are called the same number of times.  *Cleanup() is called as follows:

ilError
*(Cleanup) (

ilPtr pPrivate,

ilBool aborting);

pPrivate receives the ilPtr returned by ilAddPipeElement(). 

aborting if TRUE, indicates pipe execution is aborting.  If FALSE, indicates pipe execution is complete. 

*Destroy() identifies a function that is called when the pipe is emptied; if set to IL_NPF, no function is called.  A pipe is emptied by either a call to ilEmptyPipe(), a call to ilDestroyObject() that is used on the pipe, or by a call to ilDestroyContext() that is used on the context to which the pipe belongs. 

Note that the *Destroy() function must not free the client private block pointed to by pPrivate.  The client private block will be freed by the Image Library.  *Destroy() is called as follows:

ilError
*(Destroy) (

ilPtr pPrivate );

pPrivate receives the ilPtr returned by ilAddPipeElement(). 

*Execute() identifies the routine called to execute the pipe element for each pass of the image pipeline. This routine is required for all pipe elements; it must not be NULL unless the object type is IL_HOOK.  *Execute() is called as follows:

ilError
*(Execute) (

ilExecuteData *pData,

long dstLine,

long *pNLines );

*pData points to an ilExecuteData data structure with the following fields:

pPrivate
points to the pipe element private data, as returned from ilAddPipeElement(). 

pSrcImage set to NULL if the element is an IL_PRODUCER; otherwise, points to a structure that describes the source image of this pipe element.  *pSrcImage must not be modified. 

pDstImage set to NULL if the element is an IL_CONSUMER; otherwise, points to a structure that describes the destination image for this pipe element *pDstImage must not be modified. 

srcLine identifies the first line of source image to read where zero (0) is the top line. 

pNextSrcLine
a field for internal use by the Image Library; clients must not use this field.

compressed a field used by compression and decompression filters only.  Clients must not use this field. 

filler identifies a field that is reserved for future use; should be ignored. 

dstLine identifies the number of the first line to write in the destination image, where zero (0) is the top or first line in the image.  dstLine should be ignored if the element is an IL_CONSUMER. 

*pNLines points to a long which on entry contains the number of lines for this element to process.  That is, *pNLines is the number of lines to read, starting at pData->scrLine.  On exit, *pNLines must contain the number of lines written.  For most filters, this number matches the number of lines read.  On entry, *pNLines is always  greater than zero (0).  If *pNLines is set to zero (0) before exiting, no other Execute() functions downstream in the pipe are called.  Note that the pipe image width and height are both greater than zero (0), because zero-sized pipe images are not allowed. 

mustBeZero is a value that must be zero; this parameter is reserved for future use. 

RETURN VALUE

Upon successful completion, ilAddPipeElement() returns an ilPtr data structure that points to a client private block. 

If an error occurs, the call returns a NULL and sets the pipe state to IL_PIPE_INVALID. 

ERRORS

If ilAddPipeElement() fails, it returns IL_ERROR_USER_PIPE_ELEMENT in context->error and context->errorInfo receives a negative error code. 

EXAMPLE

The following example adds a pipe element for an application created filter.  ConverterExecute is the name of the routine that filters the image data. 

ilContext context;

ilPipe pipe;

ilSrcElementData *pSrcData;

ilDstElementData *pDstData;
.
.
.

/∗  Add a pipe element.  The 3 IL_NPF’s below are the Init(),

Cleanup() and Destroy() functions for this element; in this

case none of them are needed.         ∗/

if (!(pPriv = (convertPrivPtr)ilAddPipeElement (pipe, IL_FILTER,
sizeof (convertPrivRec), 0, pSrcData, pDstData,

IL_NPF, IL_NPF, IL_NPF, ConverterExecute, (0))
return (context->error);

AUTHOR

ilAddPipeElement() was developed by HP. 

SEE ALSO

ilGetPipeInfo3X), ilDeclarePipeInvalid3X), ilCreatePipe3X). 

Using the Image Developer’s Kit.

Hewlett-Packard Company  —  Image Library: February, 1995