Converting Image Color Space

Color space conversion is available for a separate raster as well as for an entire image. The simplest version may be used to convert an entire image. For these purposes, IG_image_colorspace_convert() routine must be used. It takes image, new color space identifier, and conversion options (optionally) as incoming parameters. It is necessary to note that the channels structure of the converted image may differ from the initial one. The most common changes are the quantity of channels and the depth of channels. The quantity of channels may be changed because of differences in color space and because of changes in extra channels (controlled by conversion options). Changes in depth usually occur if the source channels have different depths (e.g., if the source image has 5-6-5 bits per pixel, the converted image will have 6-6-6 channel depths).

The AT_COLORSPACE_CONVERSION_OPTIONS structure provides advanced control for color space conversion. Below is the explanation of each attribute:

IsRaw (BOOL) specifies whether to convert the image content or just change the value of the color space id. That is, if IsRaw is FALSE, conversion flows in the regular way with modification of pixels using color space conversion rules. If the parameter is set to TRUE, only the value of the attribute that stores the color space id is changed without applying conversion to the image data. It's necessary to note that raw conversion is not available for all cases (e.g., conversion from IG_COLOR_SPACE_ID_Gy to IG_COLOR_SPACE_ID_RGB with IsRaw = TRUE is not available because of the absence of a sufficient quantity of channels.
AlphaBlending is designed to control conversion in the presence of an alpha channel. If neither an alpha nor a pre-multiplied alpha channel is available in incoming image, this attribute is not used. But if the source image has any alpha and the new color space has no alpha bit (neither IG_COLOR_SPACE_ID_A nor IG_COLOR_SPACE_ID_P), AlphaBlending.Apply specifies whether or not the image should be blended with the AlphaBlending.Background color. That is, if the Apply attribute is equal to FALSE, the alpha channel will simply be cut. Otherwise, the image will be blended with the background according to the alpha channel values.
ExtraChannels provides additional control of how extra channels should be transferred. If its Range attribute is equal to FALSE, then all extra channels are transferred from the source to the converted image (if the new color space has IG_COLOR_SPACE_ID_Ex bit; otherwise all extra channels will be cut). Otherwise the StartChannel and ChannelCount attributes specify the range of extra channels to be transferred from the source to the result.
ColorConverter represents a custom converter for the pixel color part. For now, this is a reserved attribute and must be NULL.

Advanced color space conversion routines allow you to operate not only on images, but also on particular rasters. It's also possible to supply a custom channels structure to produce conversion data with the necessary channel depths.

To start operating conversion, a HIGCSCONVERTER instance must be created. Any of IG_colorspace_conversion_create(), IG_colorspace_conversion_create_from_image(), or IG_colorspace_conversion_create_from_dib_info() may be used for this purpose. The first variation has eight incoming parameters and one output:

sourceSpace (enumIGColorSpaceIDs) - identifier of color space from which conversion will occur.
sourceSpaceAttribs (const AT_RGBQUAD*) - represents palette entries. Must be specified if source color space is indexed. Otherwise may be NULL.
sourceChannelDepths(const AT_INT*) - array of channel depths in source image or raster.
sourceChannelCount (AT_INT) - quantity of channels in source image or raster.
resultSpace (enumIGColorSpaceIDs) - identifier of color space to which image or raster will be converted.
resultChannelDepths (const AT_INT*) - channel depths for resultant image (raster). May be NULL - in this case, resultChannelDepths will have same values as output of IG_colorspace_conversion_result_channels_build() routine.
resultChannelCount (AT_INT) - quantity of channels in resultant image or raster. Ignored if resultChannelDepths is NULL.
options (LPCAT_COLORSPACE_CONVERSION_OPTIONS) - conversion control parameters.

IG_colorspace_conversion_create_from_image() and IG_colorspace_conversion_create_from_dib_info() are designed for convenience and retrieve source attributes (space, palette, channels) from supplied image or DIB information.

Once a color space converter has been allocated, it may be used in any of IG_colorspace_conversion_apply_to_image() and IG_colorspace_conversion_apply_to_raster() routines.

To release conversion, IG_colorspace_conversion_destroy() routine must be used.

It's necessary to note that advanced conversion routines may be used not only for color space conversion, but for channel depth change, too (even if IsRaw attribute of conversion options is turned on). It's possible to provide the desired channels structure, and the converter will produce output according to the specified structure.

Auxiliary routines of advanced color space conversion are IG_colorspace_conversion_result_palette_get() and IG_colorspace_conversion_result_channels_build().

IG_colorspace_conversion_result_palette_get() is designed to produce a palette if the new color space is indexed. But note that conversion to IG_COLOR_SPACE_ID_I color space is possible only from IG_COLOR_SPACE_ID_I and IG_COLOR_SPACE_ID_Gy with a depth not greater than eight.

IG_colorspace_conversion_result_channels_build() may be used to get the default channels structure for converted data. The result of this routine is used by conversion routines if resultChannelDepths parameter has a NULL value.