ilConvert(3X)

NAME

ilConvert() − convert the image’s type, format or both

SYNOPSIS

ilBool
ilConvert (

ilPipe pipe,

ilImageDes *pDes,

ilImageFormat *pFormat,

int option,

void *pOptionData);

DESCRIPTION

ilConvert() adds zero or more filters as necessary to convert the image in the pipe to the given descriptor and/or format.

pipe is a pipe created by ilCreatePipe().

*pDes points to an ilImageDes structure that describes the converted image. If NULL, no type conversion occurs.

*pFormat if not NULL, points to an ilImageFormat structure that describes the format to which the image in the pipe should be converted. If NULL (recommended) and *pDes if not NULL, defaults to the most efficient format for an image of the type identified by *pDes.

option if zero (0), uses the default method of conversion; otherwise defines a type-specific method for conversion; see the following section of this man page.

*pOptionData if not NULL (0), points to a structure depending on the value of option.

ilConvert() allows the pipe image to be converted from any image type to any other image type by pointing pDes to a data structure that describes the new image type. If pDes is NULL, no conversion of the image data is performed. Not all conversions which can be described by pDes are supported. For example, you cannot convert the image to an IL_GRAY image with 209 levels per sample. An IL_ERROR_CANT_CONVERT error is returned if the requested conversion is not supported. For details on what conversions are supported, refer to the text on the predefined ilImageDes structures later in this man page.

If pFormat is NULL the optimal format for the image type described by pDes will result. It is recommended that pFormat be NULL because normally the caller does not care about the format of the pipe image. The exception is when an application-defined filter or consumer is being added using ilAddPipeElement(). If so, you can call ilConvert() with pFormat pointing to an ilImageFormat structure that describes the format needed by the pipe element, before calling ilAddPipeElement() to add the filter or consumer.

Assuming pFormat is NULL, conversions to the following pre-defined ilImageDes structures are fully supported:

IL_DES_BITONAL
is a bitonal image with zero (0) as white

IL_DES_GRAY
is a 256-level gray image, with zero (0) as black

IL_DES_RGB
is an R.C image, with R, G and B each 256 levels

IL_DES_PALETTE
is a palette image

IL_DES_YCBCR
is a YCbCr image with Y, Cb and Cr each having 256 levels

IL_DES_YCBCR_2
is a YCbCr image with Y, Cb and Cr each 256 levels, with Cb and Cr each subsampled by two (2).

option and pOptionData should be IL_CONVERT_NO_OPTION (0) and NULL (0) respectively to request the default conversion method. Their usage depends on the image type being converted to as follows:

IL_BITONAL
The default is to convert to bitonal using error diffusion; this approach works best for photographic images. If option is IL_CONVERT_THRESHOLD thresholding is used. The image is first converted to a 256-level gray image. Each gray pixel, with a value from 0 (black) to 255 (white) is then compared to a threshold value; if the pixel is greater than or equal to the threshold, a white pixel results; otherwise, a black pixel results.

Thresholding is recommended when converting textual images, such as screen dumps. The threshold value is specified by pointing pOptionData to a static unsigned long value. The threshold can be changed by changing this value without reforming the pipe; the threshold is not copied by ilConvert(). Smaller threshold values result in lighter images; larger values result in darker images. If pOptionData is NULL the default threshold of 128 is used, but a value of around 190 works better for many images.

If pDes->blackIsZero differs from that of the pipe image and option is IL_CONVERT_SOFT_INVERT, the pixels are not changed but blackIsZero is changed to the new value for the pipe image. If option is not IL_CONVERT_SOFT_INVERT the pixels are inverted (black becomes white). Note however in this case the value of blackIsZero also changes, so the pixels may be re-inverted when the image is displayed so the image will appear to have not been inverted. The IL_CONVERT_SOFT_CONVERT option results in an apparent inversion and is the recommended way to invert.

To force the pixels to be inverted while the image retains its value for blackIsZero, ilConvert() can be called twice as in the following example:

ilImageDes des;
ilQueryPipe (pipe, (long *)0, (long *)0, &des);
des.blackIsZero = (des.blackIsZero) ? 0 : 1;
ilConvert (pipe, &des, (ilImageFormat *)0,
IL_CONVERT_SOFT_INVERT, 0);
des.blackIsZero = (des.blackIsZero) ? 0 : 1;
/* invert pixels */
ilConvert (pipe, &des, (ilImageFormat *)0, 0, 0);

IL_GRAY pDes->blackIsZero and IL_CONVERT_SOFT_INVERT are as described for IL_BITONAL. If pDes->nLevelsPerSample[0] equals 256 and nLevelsPerSample[0] for the current pipe image equals 16, the image is converted from 16 to 256 levels. This supports conversion from 4 to 8 bit IL_GRAY; no other level conversions are supported.

IL_PALETTE
If option is IL_CONVERT_TO_PALETTE, pOptionData must point to a structure of type ilConvertToPaletteInfo, with the fields described below. If option is zero (0) then the conversion is done using the values listed as defaults below.

method
is either IL_CHOOSE_COLORS, IL_AREA_DITHER, IL_DIFFUSION, or IL_QUICK_DIFFUSION.

levels is the number of red (levels[0]), green (levels[1]) and blue (levels[2]) levels to dither/diffuse to.

kernelSize
is reserved for future use and must be equal to eight (8).

dstType
is the type of image to create and must be equal to IL_PALETTE.

mapImage
is an ilClientImage that defines how the pixels should be remapped. A value of NULL is recommended. Having a non NULL mapImage value is equivalent to specifying a NULL mapImage value followed by a call to ilMap() with the non NULL mapImage. This capability is used by ilWriteXDrawable() to remap the pixels to X pixel values for display.

If method is IL_CHOOSE_COLORS then levels[1], levels[2] and kernelSize are ignored. levels[0] is the number of palette colors, and must be in the range 1 to 256; dstType must be IL_PALETTE. An IL_ERROR_CONVERT_TO_PALETTE error is returned if mapImage is not NULL. The pipe image is converted to a palette image by choosing levels[0] palette colors to represent the image, and converting each pixel to one of those colors. The resulting palette image will have pixels in the range 0..levels[0] - 1. The unused entries in the palette will be zero (0). The rest of this section applies to values of method other than IL_CHOOSE_COLORS. Other values of method define ways of dithering.

When method is not IL_CHOOSE_COLORS, the output from ilConvert() is a byte-per-pixel image where each byte is equal to:

red * (levels[1]-1) * (levels[2]-1) + green *
(levels[2]-1) + blue

where red, green and blue are in the range 0..levels[] - 1. If method is IL_AREA_DITHER only the following expressions are supported: levels[0] == 4, levels[1] == 8 and levels[1] == 4. If method is IL_DIFFUSION or IL_QUICK_DIFFUSION the red, green and blue values can be any combination of powers of 2 from 2 to 64 whose product is 256 or less.

The IL_DITHERED_PALETTE bit is set in the flags field of the image descriptor ( ilImageDes ) for the resulting image and typeInfo.paletteInfo.levels is set to the given levels.

A method of IL_AREA_DITHER specifies an area dither; IL_DIFFUSION specifies full error diffusion and IL_QUICK_DIFFUSION specifies a quicker less exact error diffusion. IL_AREA_DITHER is the fastest method, followed by IL_QUICK_DIFFUSION and IL_DIFFUSION. The resulting image quality is usually the inverse of speed; IL_DIFFUSION is the slowest method but yields the best quality image.

IL_RGB
No options supported; option must be zero (0). If pDes->nLevelsPerSample[0..2] equals 256 and nLevelsPerSample[0..2] for the current pipe image equals 16, each sample of the image is converted from 16 to 256 levels. This supports conversion from 12 to 24 bit RGB; no other level conversions are supported.

IL_YCBCR
No options are supported; option must be zero (0). The pipe image is converted to YCbCr based on lumaRed, lumaGreen, lumaBlue and refBlack, refWhite in sample[0..2] in pDes->typeInfo.YCbCr. It is then subsampled as defined by subsampleHoriz and subsampleVert in pDes->typeInfo.YCbCr.sample[0..2], where one (1) indicates no subsampling. The recommended subsampling is defined by the ilImageDes IL_DES_YCBCR_2: no subsampling of the Y (0) sample; Cb and Cr subsampled by two (2).

RETURN VALUE

Upon successful completion, ilConvert() returns TRUE.

ERRORS

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

EXAMPLE

The following example adds a pipe filter to the given pipe that will convert an (RGB) image in the pipe to a YCbCr image, subsampled twice in Cr and Cb.

ilPipe pipe;
.
.
.

if (!ilConvert (pipe, IL_DES_YCBCR_2, IL_FORMAT_3BYTE_PLANE, 0, NULL))

return(context->error);

AUTHOR

ilConvert() was developed by HP.

Museum

Related Articles