gcgIMAGE Class Reference

Class for handling images with up to 32 bits per pixel and up to 4 channels. More...

#include <gcg.h>

Inheritance diagram for gcgIMAGE:

Public Member Functions
	gcgIMAGE ()
	Constructs a valid but empty image. The image can be used as destiny image in any gcgIMAGE method or GCGlib function. More...
virtual	~gcgIMAGE ()
	Releases all image resources by calling destroyImage(). More...
bool	createImage (unsigned int width, unsigned int height, unsigned int bpp, bool usealpha=false)
	Image creation. Alocates all necessary space for the image indicated by the parameters. Sets all indices (if bpp < 16) or colors (if bpp >= 16) with zero values. If bpp < 16, it creates and sets a gray scale palette. More...
bool	createSimilar (gcgIMAGE *source)
	Creates an image with the same dimensions, bits per pixel, color masks and palette of a source image. Only palette data, if used, is copied to the current image. This is useful for creating temporary images compatible with the source. More...
bool	destroyImage ()
	Releases all resources used by the image. After destroyed, the image becomes invalid and must be recreated. More...
bool	isCompatibleWith (gcgIMAGE *source)
	Checks if both images are compatible: same dimensions, same bits per pixel, same masks, same palette. But not necessarily the same pixel data. More...
bool	isValid ()
	Checks if the current image is valid: dimensions are non-zero, pixel data is allocated and bits per pixel is 1, 2, 4, 8, 16, 24 or 32. If the image has a palette, checks if it is allocated. More...
bool	duplicateImage (gcgIMAGE *source)
	Makes an independent copy of the source image. Creates an image similar to the source image and copies all of its contents. The duplicata is stored in this image, whose previous data is destroyed. The destination (this) and the source can be the same object. More...
bool	duplicateSubimage (gcgIMAGE *source, int left, int top, unsigned int width, unsigned int height)
	Makes an independent copy of a subregion of the source image. Creates an image to the source image but with different size and copies the pixel data of its subregion. The result is stored in this image, whose previous data is destroyed. The destination (this) and the source can be the same object. More...
bool	copyImage (gcgIMAGE *source)
	Copies the pixel and palette data if the source image is equivalent to this image: same dimensions, same bits per pixel, same masks, same number of colors in the palette. If they are not compatible this image is leaved unchanged. The destination (this) and the source can be the same object. More...
bool	loadImage (const char *filename)
	Loads a file image based on its extension. If the file extension does not match .tga, .bmp, .pcx, .jpg or .jpeg, an error is issued. More...
bool	loadJPG (const char *filename)
	Loads a file image in JPEG format. This function uses the Independent JPEG Group Library. More...
bool	loadBMP (const char *filename)
	Loads a file image in BMP format. More...
bool	loadPCX (const char *filename)
	Loads a file image in PCX format, paletted with 256 colors. More...
bool	loadTGA (const char *filename)
	Loads a file image in TGA format. More...
bool	saveBMP (const char *filename)
	Saves the image in BMP format. If the image has 8 bits per pixel, a RLE compressed version is computed and, if it is smaller than the uncompressed version, it is saved. All other versions are saved uncompressed. More...
bool	saveJPG (const char *filename, int quality)
	Saves the image in JPG format. This method uses the Independent JPEG Group library. Only 24 bits RGB and gray scaled images are supported. Jpeg format does not include alpha/exponent channel. If this image has not these formats, the function automatically computes a compatible image for saving. More...
bool	getPixelColor (unsigned int i, unsigned int j, VECTOR4 color)
	Retrieves the color of the pixel with coordinates (i, j). This method is not recommended for high performance processes since it always computes the pixel address and normalizes the color values. Access gcgIMAGE::data directly whenever possible. If the image has a palette, it calls getPixelIndex() and getPaletteColor() to retrieve the color, which is much slower. Note that gcgIMAGE currently supports up to 8 bits per channel. More...
bool	setPixelColor (unsigned int i, unsigned int j, VECTOR4 color)
	Sets the color of the pixel with coordinates (i, j). This method is not recommended for high performance processes since it always computes the pixel address and converts the color values. Access gcgIMAGE::data directly whenever possible. If the image has a palette, it finds the color in the palette closest (squared euclidian distance) to color and then calls setPixelIndex() to set the color, which is considerably slow. Note that gcgIMAGE currently supports up to 8 bits per channel. More...
int	getPixelIndex (unsigned int i, unsigned int j)
	Gets the palette index of the pixel with coordinates (i, j), in the range [0, palettecolors - 1]. Generally, palettecolors = (2 powered to bpp) - 1. This method is valid only for paletted images, i.e. bits per pixel <= 8. More...
bool	setPixelIndex (unsigned int i, unsigned int j, int newindex)
	Sets the palette index of the pixel with coordinates (i, j), in the range [0, palettecolors - 1]. This method is valid only for paletted images, i.e. bits per pixel <= 8. More...
bool	getPaletteColor (int index, VECTOR4 color)
	Gets the RGBA color stored in the position index of the palette, in the range [0, palettecolors - 1]. Generally, palettecolors = (2 powered to bpp) - 1. This method is valid only for paletted images, i.e. bits per pixel <= 8. Note that gcgIMAGE currently allocates 8 bits for each channel in the palette. More...
bool	setPaletteColor (int index, VECTOR4 color)
	Sets the RGBA color in the position index of the palette, in the range [0, palettecolors - 1]. Generally, palettecolors = (2 powered to bpp) - 1. This method is valid only for paletted images, i.e. bits per pixel <= 8. Note that gcgIMAGE currently allocates 8 bits for each channel in the palette. More...
bool	convolutionX (gcgIMAGE *source, gcgDISCRETE1D< float > *mask, float addthis=0)
	Computes the convolution product of an unidimensional floating point mask mask with each row (left to right) of source image source. The result is stored in this image, whose previous data is destroyed. The destination (this) and the source can be the same object. Generally, the mask elements are given in the interval [0.0, 1.0]. Each convolved value, one per pixel, is clamped to be between 0.0 (minimum intensity) and 1.0 (maximum intensity). Use the addthis parameter to displace convolutions that might result in negative values (high pass for example) or values greater than one. All image channels are convolved with mask. If the source image is gray scaled, forceLinearPalette() is called for it, and the convolution is computed with the indices stored in the bitmap. If the source image is paletted but is not gray scaled (i.e. RGBA), the convolutions results in a 32 bits image, since it is not possible to directly filter paletted color images. More...
bool	convolutionY (gcgIMAGE *source, gcgDISCRETE1D< float > *mask, float addthis=0)
	Computes the convolution product of an undimensional floating point mask mask with each column (bottom to top) of source image source. The result is stored in this image, whose previous data is destroyed. The destination (this) and the source can be the same object. Generally, the mask elements are given in the interval [0.0, 1.0]. Each convolved value, one per pixel, is clamped to be between 0.0 (minimum intensity) and 1.0 (maximum intensity). Use the addthis parameter to displace convolutions that might result in negative values (high pass for example) or values greater than one. All image channels are convolved with mask. If the source image is gray scaled, forceLinearPalette() is called for it, and the convolution is computed with the indices stored in the bitmap. If the source image is paletted but is not gray scaled (i.e. RGBA), the convolution results in a 32 bits image, since it is not possible to directly filter paletted color images. More...
bool	convolutionXY (gcgIMAGE *source, gcgDISCRETE2D< float > *mask, float addthis=0)
	Computes the convolution product of a bidimensional floating point mask mask with the source image source. The result is stored in this image, whose previous data is destroyed. The destination (this) and the source can be the same object. Generally, the mask elements are given in the interval [0.0, 1.0]. Each convolved value, one per pixel, is clamped to be between 0.0 (minimum intensity) and 1.0 (maximum intensity). Use the addthis parameter to displace convolutions that might result in negative values (high pass for example) or values greater than one. All image channels are convolved with mask. If the source image is gray scaled, forceLinearPalette() is called for it, and the convolution is computed with the indices stored in the bitmap. If the source image is paletted but is not gray scaled (i.e. RGBA), the convolution results in a 32 bits image, since it is not possible to directly filter paletted color images. This function is highly computation expensive. Use it ONLY when the 2D filter is not separable. In that case, the use an application of convolutionX() followed by convolutionY() is preferable and much faster. More...
bool	templateMatching (unsigned int imgleft, unsigned int imgbottom, unsigned int imgwidth, unsigned int imgheight, gcgDISCRETE2D< float > *mask, VECTOR2 position)
	Finds the pixel coordinates (x, y) that gives the greatest Sum of Absolute Differences (SAD) with the alignment of the bidimensional mask and the image's pixels. The mask is called the template which has to be discovered in the current image. It is represented by an gcgDISCRETE2D<float> object normaly having points with values between 0.0 and 1.0. Each color of the image is a RGB triple with channel values normalized between 0.0 and 1.0. The origin of mask is aligned with all points inside the region defined starting at (imgleft, imgbottom), with imgwidth by imgheight pixels, and the sum of absolute differences are computed for all color channels. The total sum of absolute differences is the sum of the result of all channels. The pixel coordinate with greatest total sum is returned in position. If the source image is paletted and gray scaled, forceLinearPalette() is called for it, and the sum of absolute differences is computed with the indices stored in the bitmap. In all other configurations the actual RGB values of the pixels are used in the computation. This function is highly computation expensive. Try to reduce the search space by setting properly the imgleft, imgbottom, imgwidth and imgheight parameters. More...
bool	transformColorSpace (gcgIMAGE *source, MATRIX4 matrix)
	Applies the linear tranformation defined by a 4 x 4 matrix in all image colors. It is called a color space transform. Each image pixel has a color vector [R G B A] composed by the red, green, blue and alpha values, normalized between 0.0 (darker) and 1.0 (brigher). This method computes the matrix-vector multiplication [R' G' B' A'] = matrix * [R G B A]. The resulting color components [R' G' B' A'] are clamped between 0.0 and 1.0 and stored in the image bits. If the image has no alpha/exponent channel defined, the last column and the last row of the matrix must be 0 to avoid errors. If this is not the case, the resulting color is undefined. For 24 bits images, the last column is ignored (alpha component is set to zero: A = 0) and the last row is ignored (A' is not computed). The result is stored in this image, whose previous data is destroyed. The destination (this) and the source can be the same object. It is useful in color calibration processes. More...
bool	convertBits (gcgIMAGE *source, unsigned int newbpp)
	Computes an equivalent image of source but with a different number of bits per pixel. The result is stored in this image, whose previous data is destroyed. The destination (this) and the source can be the same object. Currently, the following conversions are supported: [1, 2 or 4 bits] to [8 bits]: paletted images to a palette with 256 colors; [1, 2, 4 or 8 bits] to [24 bits]: paletted images to 24 bits with 8 bits per channel, where the alpha values in palette colors are discarded; [16 bits] to [24 bits]: 16 bits with arbitrary masks to 24 bits with 8 bits per channel, where the alpha values (if its mask is non zero) are discarded; [16 bits] to [32 bits]: 16 bits with arbitrary masks to 32 bits with 8 bits per channel, where the alpha values (if its mask is non zero) are copied to the corresponding 8 bit channel; [32 bits] to [24 bits]: 32 bits with 8 bits per channel to 24 bits with 8 bits per channel, where the alpha value is discarded. More...
bool	convertGrayScale (gcgIMAGE *source)
	Computes a gray scaled version of source, keeping its number of bits per pixel. The result is stored in this image, whose previous data is destroyed. The destination (this) and the source can be the same object. If the source has 1, 2, 4 or 8 bits per pixel, the palette RGB colors are converted to gray scale and the indices of the bitmap are forced to be linear through a call to forceLinearPalette(). In any other bpp, the actual RGB color bits are forced to be gray by a simple arithmetic average between their original values. In all cases, the alpha/exponent values (if present) are just copied. More...
bool	convertGrayScale8bits (gcgIMAGE *source)
	Computes a gray scaled version of source, but with 8 bits per pixel. The result is stored in this image, whose previous data is destroyed. The destination (this) and the source can be the same object. The resulting image has a linear palette varying uniformly from index 0 (black) to index 255 (white). In all cases, the alpha/exponent values are ignored in the computation and discarded since they generally cannot be mapped to the palette. More...
bool	isGrayScale ()
	Checks if the image has only gray scaled colors. If the image is paletted, the palette colors are first checked. If the palette has colors which are not gray, then all indices and corresponding colors are checked. This means that a gray scaled image might have a palette with non gray colors. If the image is not paletted, all bitmap values are verified. A color is a gray tone if R = G = B. The alpha/exponent channel, if present, is ignored. More...
bool	forceLinearPalette ()
	Classify the palette colors in ascending order of the sum R+G+B. The bitmap indices are adjusted accordingly. The resulting image has indices that correspond directly to the average intensity of the palette color. As a result, the bitmap indices can be used directly in several image processing tasks, notably if the image is gray scaled. The original alpha/exponent values are preserved. This function does not check if palette colors are duplicated. More...
bool	scale (float weight, gcgIMAGE *source, float addthis=0.0)
	Scales a source image source and stores the result in the current object, whose previous data is destroyed. The destination (this) and the source can be the same object. Each pixel component of the source, in the [0, 1] range, is multiplied by weight and then summed to addthis (weight * value + addthis). The result, one per RGBA component, is clamped to be between 0.0 (minimum intensity) and 1.0 (maximum intensity) and stored in this image. Use the addthis parameter to displace scalings that might result in negative values or values greater than one. All image channels are scaled. If the source image is gray scaled, forceLinearPalette() is called for it, and the scaling is computed with the indices stored in the bitmap. If the source image is paletted but is not gray scaled, the convolution results in a 32 bits image. More...
bool	combineAdd (gcgIMAGE *source1, gcgIMAGE *source2, float weight1=1.0, float weight2=1.0, float addthis=0.0)
	Combines two source images source1 and source2 by addition. Stores the result in the current object, whose previous data is destroyed. The destination (this) and any source image (source1 and source2) can be the same object. source1 and source2 must be compatible (see gcgIMAGE::isCompatibleWith()). For a given image position, each RGBA component of source1, in the [0, 1] range, is multiplied by weight1 and its corresponding component in source2, also in the [0, 1] range, is multiplied by weight2, and the two results are summed. It is then added to addthis (weight1 * value1 + weight2 * value2 + addthis). The result, one per RGBA component, is clamped to be between 0.0 (minimum intensity) and 1.0 (maximum intensity) and stored in this image. Use the addthis parameter to displace combinations that might result in negative values or values greater than one. All image channels are combined. If the source image is gray scaled, forceLinearPalette() is called for it, and the combination is computed with the indices stored in the bitmap. If the source image is paletted but is not gray scaled, the convolution results in a 32 bits image, since it is not possible to directly combine paletted color images. More...
bool	combineMult (gcgIMAGE *source1, gcgIMAGE *source2, float add1=0.0, float add2=0.0, float addthis=0.0)
	Combines two source images source1 and source2 by multiplication. Stores the result in the current object, whose previous data is destroyed. The destination (this) and any source image (source1 and source2) can be the same object. source1 and source2 must be compatible (see gcgIMAGE::isCompatibleWith()). For a given image position, each RGBA component of source1, in the [0, 1] range, is added to add1 and its corresponding component in source2, also in the [0, 1] range, is added to add2, and the two results are multiplied. It is then added to addthis ((add1 + value1) * (add2 * value2) + addthis). The result, one per RGBA component, is clamped to be between 0.0 (minimum intensity) and 1.0 (maximum intensity) and stored in this image. Use the addthis parameter to displace combinations that might result in negative values or values greater than one. All image channels are combined. If the source image is gray scaled, forceLinearPalette() is called for it, and the combination is computed with the indices stored in the bitmap. If the source image is paletted but is not gray scaled, the convolution results in a 32 bits image, since it is not possible to directly combine paletted color images. More...
bool	splitChannels (gcgIMAGE *red, gcgIMAGE *green, gcgIMAGE *blue, gcgIMAGE *alpha=NULL)
	Copies the color channels of the current image into distinct gray scaled images. The destination images (red, green, blue, alpha) must not be the source (this). Any destination can be NULL, indicating that a channel is not to be copied. The output are 8 bits per pixel, gray scaled images, with the same dimensions of the source. The original component values of the current image are converted and scaled to the [0, 255] range. All output images have linear palettes which means that the original channel value match their indices. More...
bool	mergeChannels (gcgIMAGE *red, gcgIMAGE *green, gcgIMAGE *blue, gcgIMAGE *alpha=NULL)
	Merges the distinct gray scaled images into the channels of the current image. The source images (red, green, blue, alpha) must not be the source (this). All sources must be mutually compatible (see gcgIMAGE::isCompatibleWith()). Any source can be NULL, indicating that the corresponding channel will have only zeros. The destination image can have 16 or 32 bits per pixel, if the alpha channel is provided. If it is not the case, the current image is adjusted to 32 bits per pixel. The destination image can have 16, 24 or 32 bits per pixel, if the alpha channel is not provided. If this is not the case, the current image is adjusted to 24 bits per pixel. In any case, the dimensions of the current image is adjusted to the sources. The source images MUST have 8 bits per pixel and be gray scaled. Their indices are assumed to be in the [0, 255] range with a linear palette (see gcgIMAGE::forceLinearPalette()), which means that their indices values match the gray level. More...
bool	exportChannels (gcgDISCRETE2D< float > *red, gcgDISCRETE2D< float > *green, gcgDISCRETE2D< float > *blue, gcgDISCRETE2D< float > *alpha)
	Copies the color channels of the current image into distinct gcgDISCRETE2D<float> objects. The destination objects (red, green, blue, alpha) can be NULL, indicating that a channel is not to be copied. The output have the same dimensions of the current object and are composed by float values . The original component values of the current image are converted and scaled to the [0.0, 1.0] range. More...
bool	exportChannels (gcgDISCRETE2D< double > *red, gcgDISCRETE2D< double > *green, gcgDISCRETE2D< double > *blue, gcgDISCRETE2D< double > *alpha)
	Copies the color channels of the current image into distinct gcgDISCRETE2D<double> objects. The destination objects (red, green, blue, alpha) can be NULL, indicating that a channel is not to be copied. The output have the same dimensions of the current object and are composed by double values . The original component values of the current image are converted and scaled to the [0.0, 1.0] range. More...
bool	exportChannels (gcgDISCRETE2D< short > *red, gcgDISCRETE2D< short > *green, gcgDISCRETE2D< short > *blue, gcgDISCRETE2D< short > *alpha)
	Copies the color channels of the current image into distinct gcgDISCRETE2D<short> objects. The destination objects (red, green, blue, alpha) can be NULL, indicating that a channel is not to be copied. The output have the same dimensions of the current object and are composed by short values . The original component values of the current image are preserved in the range [0, 255] for paletted, 24 and 32 bits per pixel. The range of the component values depend on the number of bits for each channel in images with 16 bits per pixel. Use the gcgIMAGE::max attribute to know each channel range: red = [0, max[0]], green = [0, max[1]], blue = [0, max[2]], alpha = [0, max[3]]. More...
bool	exportChannels (gcgDISCRETE2D< int > *red, gcgDISCRETE2D< int > *green, gcgDISCRETE2D< int > *blue, gcgDISCRETE2D< int > *alpha)
	Copies the color channels of the current image into distinct gcgDISCRETE2D<int> objects. The destination objects (red, green, blue, alpha) can be NULL, indicating that a channel is not to be copied. The output have the same dimensions of the current object and are composed by int values . The original component values of the current image are preserved in the range [0, 255] for paletted, 24 and 32 bits per pixel. The range of the component values depend on the number of bits for each channel in images with 16 bits per pixel. Use the gcgIMAGE::max attribute to know each channel range: red = [0, max[0]], green = [0, max[1]], blue = [0, max[2]], alpha = [0, max[3]]. More...
bool	exportChannels (gcgDISCRETE2D< long > *red, gcgDISCRETE2D< long > *green, gcgDISCRETE2D< long > *blue, gcgDISCRETE2D< long > *alpha)
	Copies the color channels of the current image into distinct gcgDISCRETE2D<long> objects. The destination objects (red, green, blue, alpha) can be NULL, indicating that a channel is not to be copied. The output have the same dimensions of the current object and are composed by long values . The original component values of the current image are preserved in the range [0, 255] for paletted, 24 and 32 bits per pixel. The range of the component values depend on the number of bits for each channel in images with 16 bits per pixel. Use the gcgIMAGE::max attribute to know each channel range: red = [0, max[0]], green = [0, max[1]], blue = [0, max[2]], alpha = [0, max[3]]. More...
bool	importChannels (gcgDISCRETE2D< float > *red, gcgDISCRETE2D< float > *green, gcgDISCRETE2D< float > *blue, gcgDISCRETE2D< float > *alpha)
	Imports the distinct gcgDISCRETE2D<float> into the channels of the current image. The source signals (red, green, blue, alpha) must have the same dimensions. Any source can be NULL, indicating that the corresponding channel will have only zeros. The destination image can have 16 or 32 bits per pixel, if the alpha channel is provided. If it is not the case, the current image is adjusted to 32 bits per pixel. The destination image can have 16, 24 or 32 bits per pixel, if the alpha channel is not provided. If this is not the case, the current image is adjusted to 24 bits per pixel. In any case, the dimensions of the current image is adjusted to the sources. The float values of the source signals are clamped to be in the interval [0.0, 1.0] before its conversion to a decimal value to be written to the bitmap. More...
bool	importChannels (gcgDISCRETE2D< double > *red, gcgDISCRETE2D< double > *green, gcgDISCRETE2D< double > *blue, gcgDISCRETE2D< double > *alpha)
	Imports the distinct gcgDISCRETE2D<double> into the channels of the current image. The source signals (red, green, blue, alpha) must have the same dimensions. Any source can be NULL, indicating that the corresponding channel will have only zeros. The destination image can have 16 or 32 bits per pixel, if the alpha channel is provided. If it is not the case, the current image is adjusted to 32 bits per pixel. The destination image can have 16, 24 or 32 bits per pixel, if the alpha channel is not provided. If this is not the case, the current image is adjusted to 24 bits per pixel. In any case, the dimensions of the current image is adjusted to the sources. The double values of the source signals are clamped to be in the interval [0.0, 1.0] before its conversion to a decimal value to be written to the bitmap. More...
bool	importChannels (gcgDISCRETE2D< short > *red, gcgDISCRETE2D< short > *green, gcgDISCRETE2D< short > *blue, gcgDISCRETE2D< short > *alpha)
	Imports the distinct gcgDISCRETE2D<short> into the channels of the current image. The source signals (red, green, blue, alpha) must have the same dimensions. Any source can be NULL, indicating that the corresponding channel will have only zeros. The destination image can have 16 or 32 bits per pixel, if the alpha channel is provided. If it is not the case, the current image is adjusted to 32 bits per pixel. The destination image can have 16, 24 or 32 bits per pixel, if the alpha channel is not provided. If this is not the case, the current image is adjusted to 24 bits per pixel. In any case, the dimensions of the current image is adjusted to the sources. The short values of the source signals are clamped to be in the interval [0, 255] before being written to the bitmap, if the current image has 24 or 32 bits per pixel. If the current image has 16 bits per pixel, the range of the component values depend on the number of bits for each channel. Use the gcgIMAGE::max attribute to know each channel range used for clamping: red = [0, max[0]], green = [0, max[1]], blue = [0, max[2]], alpha = [0, max[3]]. More...
bool	importChannels (gcgDISCRETE2D< int > *red, gcgDISCRETE2D< int > *green, gcgDISCRETE2D< int > *blue, gcgDISCRETE2D< int > *alpha)
	Imports the distinct gcgDISCRETE2D<int> into the channels of the current image. The source signals (red, green, blue, alpha) must have the same dimensions. Any source can be NULL, indicating that the corresponding channel will have only zeros. The destination image can have 16 or 32 bits per pixel, if the alpha channel is provided. If it is not the case, the current image is adjusted to 32 bits per pixel. The destination image can have 16, 24 or 32 bits per pixel, if the alpha channel is not provided. If this is not the case, the current image is adjusted to 24 bits per pixel. In any case, the dimensions of the current image is adjusted to the sources. The int values of the source signals are clamped to be in the interval [0, 255] before being written to the bitmap, if the current image has 24 or 32 bits per pixel. If the current image has 16 bits per pixel, the range of the component values depend on the number of bits for each channel. Use the gcgIMAGE::max attribute to know each channel range used for clamping: red = [0, max[0]], green = [0, max[1]], blue = [0, max[2]], alpha = [0, max[3]]. More...
bool	importChannels (gcgDISCRETE2D< long > *red, gcgDISCRETE2D< long > *green, gcgDISCRETE2D< long > *blue, gcgDISCRETE2D< long > *alpha)
	Imports the distinct gcgDISCRETE2D<long> into the channels of the current image. The source signals (red, green, blue, alpha) must have the same dimensions. Any source can be NULL, indicating that the corresponding channel will have only zeros. The destination image can have 16 or 32 bits per pixel, if the alpha channel is provided. If it is not the case, the current image is adjusted to 32 bits per pixel. The destination image can have 16, 24 or 32 bits per pixel, if the alpha channel is not provided. If this is not the case, the current image is adjusted to 24 bits per pixel. In any case, the dimensions of the current image is adjusted to the sources. The long values of the source signals are clamped to be in the interval [0, 255] before being written to the bitmap, if the current image has 24 or 32 bits per pixel. If the current image has 16 bits per pixel, the range of the component values depend on the number of bits for each channel. Use the gcgIMAGE::max attribute to know each channel range used for clamping: red = [0, max[0]], green = [0, max[1]], blue = [0, max[2]], alpha = [0, max[3]]. More...
Public Member Functions inherited from gcgCLASS
void *	operator new (size_t size)
	Defines a new operator to be used by instatiations of GCGlib classes instead the global one. More...
void *	operator new (size_t size, const std::nothrow_t &) throw ()
	Defines a new operator to be used by instantiations of GCGlib classes instead the global one. Returns a NULL pointer instead of throwing an exception if an error occurs. More...
void *	operator new[] (size_t size)
	Defines a new operator to be used by GCGlib array allocations instead the global one. More...
void *	operator new[] (size_t size, const std::nothrow_t &) throw ()
	Defines a new operator to be used by vector allocations instead the global one. More...
void	operator delete (void *p)
	Defines a delete operator to free instances of GCGlib classes instead the global one. It is designed to match the new operator. More...
void	operator delete (void *p, const std::nothrow_t &) throw ()
	Defines a delete operator to free instances of GCGlib classes instead the global one. It is designed to match the new operator. More...
void	operator delete[] (void *p)
	Defines a delete operator to free instances of arrays for GCGlib classes instead the global one. It is designed to match the new[] operator. More...
void	operator delete[] (void *p, const std::nothrow_t &) throw ()
	Defines a delete operator to free instances of arrays for GCGlib classes instead the global one. It is designed to match the new[] operator. More...

Public Attributes
unsigned char *	data
	Image data where each pixel may be an index (1, 2, 4 and 8 bpp) or the actual color.
unsigned int	width
	Image size in number of pixels.
unsigned int	height
	Image height in number of pixels.
unsigned int	bpp
	Bits per pixel that can assume the values: 1, 2, 4, 8, 16, 24, 32.
unsigned int	rowsize
	Stride in bytes between one row and the next. The last image row appears first in the data buffer.
unsigned int	palettecolors
	Actual number of colors in the palette. It might be less than the maximum number of colors of a given bpp.
unsigned char *	palette
unsigned int	colormasks [4]
	Masks indicating color bits for the channels red, green, blue and alpha for 16 bpp and 32 bpp images.
unsigned int	max [4]
	Maximum decimal value of each channel mask: Red = 0, Green = 1, Blue = 2, Alpha = 3. It depends on colormasks.

Private Attributes
unsigned int	rightshift [4]
	Required right shift to bring each channel bits to the least significant bit.
unsigned int	nbits [4]
	Number of bits of each channel mask.

Detailed Description

Class for handling images with up to 32 bits per pixel and up to 4 channels.

The gcgIMAGE class encapsulates all funcionalities for handling images with up to 4 channels, tipically representing Red, Green, Blue, and Alpha (opacity) information (RGBA). The forth channel can also represent the exponent value on HDR images (RGBE). With bpp (bits per pixel) up to 8, the image has a palette that stores the current image colors. The palette might not have all possible colors. For instance, a 8 bpp image can have only 25 colors on the palette. Check palettecolors attribute to know how many colors are actually used. The gcgIMAGE::data field points to a bitmap of indices related to the palette. Images with 24 bpp are treated always as 8 bit channels (1 byte) for red, green and blue, stored in that order (color masks are not used). For images with 16 or 32 bpp, the masks defining which bits belong to which channel can be freely adjusted. In both cases the actual image pixels are stored in gcgIMAGE::data. Whatever the bpp, the image rows are 4 aligned to enhance memory access. The actual rowsize in bytes is given by the rowsize attribute. Use it to direct access rows, regarding that the last image row appears first in the gcgIMAGE::data buffer (address zero). The bits are stored in RGBA order, according to the four channel color masks colormasks. Most methods can receive the destiny image as a parameter. The methods copy and handle all needed information to keep the image consistent. The gcgIMAGE currently supports up to 8 bits per channel in the bitmap and exactly 8 bits per pixel in palettes. Do not change any of the image attributes unless you are absolutely sure about you are doing.

Since

0.01.0

Constructor & Destructor Documentation

gcgIMAGE()

gcgIMAGE::gcgIMAGE

(

)

Constructs a valid but empty image. The image can be used as destiny image in any gcgIMAGE method or GCGlib function.

See also

~gcgIMAGE()

~gcgIMAGE()

virtual gcgIMAGE::~gcgIMAGE ( )

virtual

Releases all image resources by calling destroyImage().

See also

gcgIMAGE()

destroyImage()

Member Function Documentation

combineAdd()

bool gcgIMAGE::combineAdd	(	gcgIMAGE *	source1,
		gcgIMAGE *	source2,
		float	weight1 = 1.0,
		float	weight2 = 1.0,
		float	addthis = 0.0
	)

Combines two source images source1 and source2 by addition. Stores the result in the current object, whose previous data is destroyed. The destination (this) and any source image (source1 and source2) can be the same object. source1 and source2 must be compatible (see gcgIMAGE::isCompatibleWith()). For a given image position, each RGBA component of source1, in the [0, 1] range, is multiplied by weight1 and its corresponding component in source2, also in the [0, 1] range, is multiplied by weight2, and the two results are summed. It is then added to addthis (weight1 * value1 + weight2 * value2 + addthis). The result, one per RGBA component, is clamped to be between 0.0 (minimum intensity) and 1.0 (maximum intensity) and stored in this image. Use the addthis parameter to displace combinations that might result in negative values or values greater than one. All image channels are combined. If the source image is gray scaled, forceLinearPalette() is called for it, and the combination is computed with the indices stored in the bitmap. If the source image is paletted but is not gray scaled, the convolution results in a 32 bits image, since it is not possible to directly combine paletted color images.

Parameters

[in]	source1	first image to be combined by addition. It may be the destination (this).
[in]	source2	second image to be combined by addition. It may be the destination (this).
[in]	weight1	scalar value to multiply each color channel of the first image source1.
[in]	weight2	scalar value to multiply each color channel of the second image source2.
[in]	addthis	floating point number that must be added to the combined values BEFORE being converted to a decimal number to be written in the bitmap. Use this term when the combination might result in negative values or values greater than one. For example, when the combination might yield negative values, set addthis = 0.5. This will shift the -0.5 values (-127 is mapped to 0, for 8 bits) to 0.0, the 0.0 values to 0.5 (0 is mapped to 127, for 8 bits) and the 0.5 value to 1.0 (128 is mapped to 255, for 8 bits).

Returns

true if the combination by addition is successfully computed. If it returns false, check GCG_REPORT_MESSAGE(gcgGetReport()) for knowing the problem.

See also

scale()

combineMult()

combineMult()

bool gcgIMAGE::combineMult	(	gcgIMAGE *	source1,
		gcgIMAGE *	source2,
		float	add1 = 0.0,
		float	add2 = 0.0,
		float	addthis = 0.0
	)

Combines two source images source1 and source2 by multiplication. Stores the result in the current object, whose previous data is destroyed. The destination (this) and any source image (source1 and source2) can be the same object. source1 and source2 must be compatible (see gcgIMAGE::isCompatibleWith()). For a given image position, each RGBA component of source1, in the [0, 1] range, is added to add1 and its corresponding component in source2, also in the [0, 1] range, is added to add2, and the two results are multiplied. It is then added to addthis ((add1 + value1) * (add2 * value2) + addthis). The result, one per RGBA component, is clamped to be between 0.0 (minimum intensity) and 1.0 (maximum intensity) and stored in this image. Use the addthis parameter to displace combinations that might result in negative values or values greater than one. All image channels are combined. If the source image is gray scaled, forceLinearPalette() is called for it, and the combination is computed with the indices stored in the bitmap. If the source image is paletted but is not gray scaled, the convolution results in a 32 bits image, since it is not possible to directly combine paletted color images.

Parameters

[in]	source1	first image to be combined by multiplication. It may be the destination (this).
[in]	source2	second image to be combined by multiplication. It may be the destination (this).
[in]	add1	scalar value to be added to each color channel of the first image source1.
[in]	add2	scalar value to be added to each color channel of the second image source2.
[in]	addthis	floating point number that must be added to the combined values BEFORE being converted to a decimal number to be written in the bitmap. Use this term when the combination might result in negative values or values greater than one. For example, when the combination might yield negative values, set addthis = 0.5. This will shift the -0.5 values (-127 is mapped to 0, for 8 bits) to 0.0, the 0.0 values to 0.5 (0 is mapped to 127, for 8 bits) and the 0.5 value to 1.0 (128 is mapped to 255, for 8 bits).

Returns

true if the combination by multiplication is successfully computed. If it returns false, check GCG_REPORT_MESSAGE(gcgGetReport()) for knowing the problem.

See also

scale()

combineAdd()

convertBits()

bool gcgIMAGE::convertBits	(	gcgIMAGE *	source,
		unsigned int	newbpp
	)

Computes an equivalent image of source but with a different number of bits per pixel. The result is stored in this image, whose previous data is destroyed. The destination (this) and the source can be the same object. Currently, the following conversions are supported: [1, 2 or 4 bits] to [8 bits]: paletted images to a palette with 256 colors; [1, 2, 4 or 8 bits] to [24 bits]: paletted images to 24 bits with 8 bits per channel, where the alpha values in palette colors are discarded; [16 bits] to [24 bits]: 16 bits with arbitrary masks to 24 bits with 8 bits per channel, where the alpha values (if its mask is non zero) are discarded; [16 bits] to [32 bits]: 16 bits with arbitrary masks to 32 bits with 8 bits per channel, where the alpha values (if its mask is non zero) are copied to the corresponding 8 bit channel; [32 bits] to [24 bits]: 32 bits with 8 bits per channel to 24 bits with 8 bits per channel, where the alpha value is discarded.

Parameters

[in]	source	image whose bits per pixel should be converted to newbpp and stored in this image. It may be the destination (this).
[in]	newbpp	new bits per pixel that the destination image must have.

Returns

true if the image with new bits per pixel is successfully computed. If it returns false, check GCG_REPORT_MESSAGE(gcgGetReport()) for knowing the problem.

See also

convertGrayScale()

convertGrayScale8bits()

convertGrayScale()

bool gcgIMAGE::convertGrayScale

(

gcgIMAGE *

source

)

Computes a gray scaled version of source, keeping its number of bits per pixel. The result is stored in this image, whose previous data is destroyed. The destination (this) and the source can be the same object. If the source has 1, 2, 4 or 8 bits per pixel, the palette RGB colors are converted to gray scale and the indices of the bitmap are forced to be linear through a call to forceLinearPalette(). In any other bpp, the actual RGB color bits are forced to be gray by a simple arithmetic average between their original values. In all cases, the alpha/exponent values (if present) are just copied.

Parameters

[in]

source

image that should be converted to a gray scaled version and stored in this image, keeping the original number of bits per pixel. It may be the destination (this).

Returns

true if the gray scaled image is successfully computed. If it returns false, check GCG_REPORT_MESSAGE(gcgGetReport()) for knowing the problem.

See also

convertGrayScale8bits()

convertBits()

isGrayScale()

forceLinearPalette()

convertGrayScale8bits()

bool gcgIMAGE::convertGrayScale8bits

(

gcgIMAGE *

source

)

Computes a gray scaled version of source, but with 8 bits per pixel. The result is stored in this image, whose previous data is destroyed. The destination (this) and the source can be the same object. The resulting image has a linear palette varying uniformly from index 0 (black) to index 255 (white). In all cases, the alpha/exponent values are ignored in the computation and discarded since they generally cannot be mapped to the palette.

Parameters

[in]

source

image that should be converted to a gray scaled version and stored in this image, keeping the original number of bits per pixel. It may be the destination (this).

Returns

true if the gray scaled image with 8 bits is successfully computed. If it returns false, check GCG_REPORT_MESSAGE(gcgGetReport()) for knowing the problem.

See also

convertGrayScale()

convertBits()

isGrayScale()

forceLinearPalette()

convolutionX()

bool gcgIMAGE::convolutionX	(	gcgIMAGE *	source,
		gcgDISCRETE1D< float > *	mask,
		float	addthis = 0
	)

Computes the convolution product of an unidimensional floating point mask mask with each row (left to right) of source image source. The result is stored in this image, whose previous data is destroyed. The destination (this) and the source can be the same object. Generally, the mask elements are given in the interval [0.0, 1.0]. Each convolved value, one per pixel, is clamped to be between 0.0 (minimum intensity) and 1.0 (maximum intensity). Use the addthis parameter to displace convolutions that might result in negative values (high pass for example) or values greater than one. All image channels are convolved with mask. If the source image is gray scaled, forceLinearPalette() is called for it, and the convolution is computed with the indices stored in the bitmap. If the source image is paletted but is not gray scaled (i.e. RGBA), the convolutions results in a 32 bits image, since it is not possible to directly filter paletted color images.

Parameters

[in]	source	image that will have each row convolved with mask. The rows are symmetrically extended on their borders.
[in]	mask	floating point discrete signal that will be convolved with the source image. The origin attribute of the mask is used.
[in]	addthis	floating point number that must be added to the convolved values BEFORE being converted to a decimal number to be written in the bitmap. Use this term when the convolution might result in negative values or values greater than one. For example, when applying a high pass filter, which naturally yields negative values, set addthis = 0.5. This will shift the -0.5 values (-127 is mapped to 0, for 8 bits) to 0.0, the 0.0 values to 0.5 (0 is mapped to 127, for 8 bits) and the 0.5 value to 1.0 (128 is mapped to 255, for 8 bits).

Returns

true if the row convolutions are successfully computed. If it returns false, check GCG_REPORT_MESSAGE(gcgGetReport()) for knowing the problem.

See also

convolutionY()

convolutionXY()

gcgDISCRETE1D<float>

convolutionXY()

bool gcgIMAGE::convolutionXY	(	gcgIMAGE *	source,
		gcgDISCRETE2D< float > *	mask,
		float	addthis = 0
	)

Computes the convolution product of a bidimensional floating point mask mask with the source image source. The result is stored in this image, whose previous data is destroyed. The destination (this) and the source can be the same object. Generally, the mask elements are given in the interval [0.0, 1.0]. Each convolved value, one per pixel, is clamped to be between 0.0 (minimum intensity) and 1.0 (maximum intensity). Use the addthis parameter to displace convolutions that might result in negative values (high pass for example) or values greater than one. All image channels are convolved with mask. If the source image is gray scaled, forceLinearPalette() is called for it, and the convolution is computed with the indices stored in the bitmap. If the source image is paletted but is not gray scaled (i.e. RGBA), the convolution results in a 32 bits image, since it is not possible to directly filter paletted color images. This function is highly computation expensive. Use it ONLY when the 2D filter is not separable. In that case, the use an application of convolutionX() followed by convolutionY() is preferable and much faster.

Parameters

[in]	source	image that will be convolved with mask. The columns are symmetrically extended on their borders.
[in]	mask	floating point discrete signal that will be convolved with the source image. The origin attribute of the mask is used.
[in]	addthis	floating point number that must be added to the convolved values BEFORE being converted to a decimal number to be written in the bitmap. Use this term when the convolution might result in negative values or values greater than one. For example, when applying a high pass filter, which naturally yields negative values, set addthis = 0.5. This will shift the -0.5 values (-127 is mapped to 0, for 8 bits) to 0.0, the 0.0 values to 0.5 (0 is mapped to 127, for 8 bits) and the 0.5 value to 1.0 (128 is mapped to 255, for 8 bits).

Returns

true if the 2D convolution is successfully computed. If it returns false, check GCG_REPORT_MESSAGE(gcgGetReport()) for knowing the problem.

See also

convolutionX()

convolutionY()

gcgDISCRETE2D<float>

convolutionY()

bool gcgIMAGE::convolutionY	(	gcgIMAGE *	source,
		gcgDISCRETE1D< float > *	mask,
		float	addthis = 0
	)

Computes the convolution product of an undimensional floating point mask mask with each column (bottom to top) of source image source. The result is stored in this image, whose previous data is destroyed. The destination (this) and the source can be the same object. Generally, the mask elements are given in the interval [0.0, 1.0]. Each convolved value, one per pixel, is clamped to be between 0.0 (minimum intensity) and 1.0 (maximum intensity). Use the addthis parameter to displace convolutions that might result in negative values (high pass for example) or values greater than one. All image channels are convolved with mask. If the source image is gray scaled, forceLinearPalette() is called for it, and the convolution is computed with the indices stored in the bitmap. If the source image is paletted but is not gray scaled (i.e. RGBA), the convolution results in a 32 bits image, since it is not possible to directly filter paletted color images.

Parameters

[in]	source	image that will have each column convolved with mask. The columns are symmetrically extended on their borders.
[in]	mask	floating point discrete signal that will be convolved with the source image. The origin attribute of the mask is used.
[in]	addthis	floating point number that must be added to the convolved values BEFORE being converted to a decimal number to be written in the bitmap. Use this term when the convolution might result in negative values or values greater than one. For example, when applying a high pass filter, which naturally yields negative values, set addthis = 0.5. This will shift the -0.5 values (-127 is mapped to 0, for 8 bits) to 0.0, the 0.0 values to 0.5 (0 is mapped to 127, for 8 bits) and the 0.5 value to 1.0 (128 is mapped to 255, for 8 bits).

Returns

true if the column convolutions are successfully computed. If it returns false, check GCG_REPORT_MESSAGE(gcgGetReport()) for knowing the problem.

See also

convolutionX()

convolutionXY()

gcgDISCRETE1D<float>

copyImage()

bool gcgIMAGE::copyImage

(

gcgIMAGE *

source

)

Copies the pixel and palette data if the source image is equivalent to this image: same dimensions, same bits per pixel, same masks, same number of colors in the palette. If they are not compatible this image is leaved unchanged. The destination (this) and the source can be the same object.

Parameters

[in]

source

pointer to the source image. It must be non-null. A warning is issued if it is not a valid image. The destiny image receives a copy of source's pixel data.

Returns

true if the image is copied from source. If it returns false, check GCG_REPORT_MESSAGE(gcgGetReport()) for knowing the problem.

See also

createImage()

createSimilar()

duplicateSubimage()

duplicateImage()

destroyImage()

isCompatibleWith()

createImage()

bool gcgIMAGE::createImage	(	unsigned int	width,
		unsigned int	height,
		unsigned int	bpp,
		bool	usealpha = false
	)

Image creation. Alocates all necessary space for the image indicated by the parameters. Sets all indices (if bpp < 16) or colors (if bpp >= 16) with zero values. If bpp < 16, it creates and sets a gray scale palette.

Parameters

[in]	width	image width. It must be non-zero.
[in]	height	image height. It must be non-zero.
[in]	bpp	bits per pixel. It must be one of the list: 1, 2, 4, 8, 16, 24 or 32. If bpp < 16, a paletted image is created. The palette is initiated with gray scale colors. If bpp is 24, an image with 8 bits for red, green and blue channels is created and the color masks are ignored. If the alpha/exponent channel is not used (see usealpha), a 16 bpp image has by default 5 bits for blue, 6 bits for green and 5 bits for red, in that order from the least significant bits (unsigned short) to the most. Also, if bpp is 32, 8 bits for blue, green and red channels are used by default, in that order, from the second most siginificant byte (unsigned int) to the least. The most significant byte is unused. More than 8 bits per pixel are not supported.
[in]	usealpha	flags if the image uses the forth channel for alpha (opacity) or exponent values. Note that paletted images (bpp < 16) has always the the 8 bits alpha/exponent channel stored for each color entry in the table. Also 24 bpp images can not have alpha bits. Thus, the usealpha parameter only affects 16 or 32 bits per pixel images. If false, see the bitmask distribution in bpp parameter. If it is true, the image is created with some of the color bits for alpha/exponent channel. If bpp is 16, then the image is created by default with 4 bits for blue, green, red and alpha channels, in that order from the least significant bits (unsigned short) to the most. If bpp is 32, 8 bits for alpha, blue, green and red channels are used by default, in that order, from the most siginificant byte (unsigned int) to the least.

Returns

true if the image is correctly created. If it returns false, check GCG_REPORT_MESSAGE(gcgGetReport()) for knowing the problem.

See also

createSimilar()

duplicateImage()

duplicateSubimage()

copyImage()

destroyImage()

createSimilar()

bool gcgIMAGE::createSimilar

(

gcgIMAGE *

source

)

Creates an image with the same dimensions, bits per pixel, color masks and palette of a source image. Only palette data, if used, is copied to the current image. This is useful for creating temporary images compatible with the source.

Parameters

[in]

source

pointer to the source image. It must be non-null. A warning is issued if it is not a valid image. The destiny image receives all attributes of the source image: dimensions, bits per pixel, color masks and palette. The gcgIMAGE::data is allocated but not copied.

Returns

true if the current image is correctly created and similar to the source image. If it returns false, check GCG_REPORT_MESSAGE(gcgGetReport()) for knowing the problem.

See also

createImage()

duplicateImage()

duplicateSubimage()

copyImage()

destroyImage()

isCompatibleWith()

destroyImage()

bool gcgIMAGE::destroyImage

(

)

Releases all resources used by the image. After destroyed, the image becomes invalid and must be recreated.

Returns

true if the image was released. If it returns false, check GCG_REPORT_MESSAGE(gcgGetReport()) for knowing the problem.

See also

createImage()

duplicateImage()

duplicateSubimage()

copyImage()

createSimilar()

duplicateImage()

bool gcgIMAGE::duplicateImage

(

gcgIMAGE *

source

)

Makes an independent copy of the source image. Creates an image similar to the source image and copies all of its contents. The duplicata is stored in this image, whose previous data is destroyed. The destination (this) and the source can be the same object.

Parameters

[in]

source

pointer to the source image. It must be non-null. A warning is issued if it is not a valid image. The destiny image receives all attributes of the source image: dimensions, bits per pixel, color masks, palette, and pixel data. The source can be the destination.

Returns

true if the image is a duplication of source. If it returns false, check GCG_REPORT_MESSAGE(gcgGetReport()) for knowing the problem.

See also

createImage()

createSimilar()

duplicateSubimage()

copyImage()

destroyImage()

isCompatibleWith()

duplicateSubimage()

bool gcgIMAGE::duplicateSubimage	(	gcgIMAGE *	source,
		int	left,
		int	top,
		unsigned int	width,
		unsigned int	height
	)

Makes an independent copy of a subregion of the source image. Creates an image to the source image but with different size and copies the pixel data of its subregion. The result is stored in this image, whose previous data is destroyed. The destination (this) and the source can be the same object.

Parameters

[in]	source	pointer to the source image. It must be non-null. A warning is issued if it is not a valid image. The destiny image receives all attributes of the source image: bits per pixel, color masks and palette. The dimensions has the subregion extents. The pixel data of the subregion is copied. The source can be the destination.
[in]	left	coordinate of the left column of the subregion to be copied. It can be outside source image domain.
[in]	top	coordinate of the top row of the subregion to be copied. It can be outside source image domain.
[in]	width	number of columns to be copied from width column. It must be non-zero.
[in]	height	number of rows to be copied from top row. It must be non-zero.

Returns

true if the image is a duplication of a subregion of source. If it returns false, check GCG_REPORT_MESSAGE(gcgGetReport()) for knowing the problem.

See also

createImage()

createSimilar()

duplicateImage()

copyImage()

destroyImage()

isCompatibleWith()

exportChannels() [1/5]

bool gcgIMAGE::exportChannels	(	gcgDISCRETE2D< float > *	red,
		gcgDISCRETE2D< float > *	green,
		gcgDISCRETE2D< float > *	blue,
		gcgDISCRETE2D< float > *	alpha
	)

Copies the color channels of the current image into distinct gcgDISCRETE2D<float> objects. The destination objects (red, green, blue, alpha) can be NULL, indicating that a channel is not to be copied. The output have the same dimensions of the current object and are composed by float values . The original component values of the current image are converted and scaled to the [0.0, 1.0] range.

Parameters

[out]	red	pointer to a gcgDISCRETE2D<float> object that will receive the red component of the current image. If it is NULL, the red channel is ignored.
[out]	green	pointer to a gcgDISCRETE2D<float> object that will receive the green component of the current image. If it is NULL, the green channel is ignored.
[out]	blue	pointer to a ggcgDISCRETE2D<float> object that will receive the blue component of the current image. If it is NULL, the blue channel is ignored.
[out]	alpha	pointer to a gcgDISCRETE2D<float> object that will receive the alpha component of the current image. If it is NULL, the alpha channel is ignored.

Returns

true if the selected channels (non-null gcgDISCRETE2D<float> pointers) are copied to the respective objects. If it returns false, check GCG_REPORT_MESSAGE(gcgGetReport()) for knowing the problem.

See also

importChannels()

exportChannels() [2/5]

bool gcgIMAGE::exportChannels	(	gcgDISCRETE2D< double > *	red,
		gcgDISCRETE2D< double > *	green,
		gcgDISCRETE2D< double > *	blue,
		gcgDISCRETE2D< double > *	alpha
	)

Copies the color channels of the current image into distinct gcgDISCRETE2D<double> objects. The destination objects (red, green, blue, alpha) can be NULL, indicating that a channel is not to be copied. The output have the same dimensions of the current object and are composed by double values . The original component values of the current image are converted and scaled to the [0.0, 1.0] range.

Parameters

[out]	red	pointer to a gcgDISCRETE2D<double> object that will receive the red component of the current image. If it is NULL, the red channel is ignored.
[out]	green	pointer to a gcgDISCRETE2D<double> object that will receive the green component of the current image. If it is NULL, the green channel is ignored.
[out]	blue	pointer to a ggcgDISCRETE2D<double> object that will receive the blue component of the current image. If it is NULL, the blue channel is ignored.
[out]	alpha	pointer to a gcgDISCRETE2D<double> object that will receive the alpha component of the current image. If it is NULL, the alpha channel is ignored.

Returns

true if the selected channels (non-null gcgDISCRETE2D<double> pointers) are copied to the respective objects. If it returns false, check GCG_REPORT_MESSAGE(gcgGetReport()) for knowing the problem.

See also

importChannels()

exportChannels() [3/5]

bool gcgIMAGE::exportChannels	(	gcgDISCRETE2D< short > *	red,
		gcgDISCRETE2D< short > *	green,
		gcgDISCRETE2D< short > *	blue,
		gcgDISCRETE2D< short > *	alpha
	)

Copies the color channels of the current image into distinct gcgDISCRETE2D<short> objects. The destination objects (red, green, blue, alpha) can be NULL, indicating that a channel is not to be copied. The output have the same dimensions of the current object and are composed by short values . The original component values of the current image are preserved in the range [0, 255] for paletted, 24 and 32 bits per pixel. The range of the component values depend on the number of bits for each channel in images with 16 bits per pixel. Use the gcgIMAGE::max attribute to know each channel range: red = [0, max[0]], green = [0, max[1]], blue = [0, max[2]], alpha = [0, max[3]].

Parameters

[out]	red	pointer to a gcgDISCRETE2D<short> object that will receive the red component of the current image. If it is NULL, the red channel is ignored.
[out]	green	pointer to a gcgDISCRETE2D<short> object that will receive the green component of the current image. If it is NULL, the green channel is ignored.
[out]	blue	pointer to a ggcgDISCRETE2D<short> object that will receive the blue component of the current image. If it is NULL, the blue channel is ignored.
[out]	alpha	pointer to a gcgDISCRETE2D<short> object that will receive the alpha component of the current image. If it is NULL, the alpha channel is ignored.

Returns

true if the selected channels (non-null gcgDISCRETE2D<short> pointers) are copied to the respective objects. If it returns false, check GCG_REPORT_MESSAGE(gcgGetReport()) for knowing the problem.

See also

importChannels()

exportChannels() [4/5]

bool gcgIMAGE::exportChannels	(	gcgDISCRETE2D< int > *	red,
		gcgDISCRETE2D< int > *	green,
		gcgDISCRETE2D< int > *	blue,
		gcgDISCRETE2D< int > *	alpha
	)

Copies the color channels of the current image into distinct gcgDISCRETE2D<int> objects. The destination objects (red, green, blue, alpha) can be NULL, indicating that a channel is not to be copied. The output have the same dimensions of the current object and are composed by int values . The original component values of the current image are preserved in the range [0, 255] for paletted, 24 and 32 bits per pixel. The range of the component values depend on the number of bits for each channel in images with 16 bits per pixel. Use the gcgIMAGE::max attribute to know each channel range: red = [0, max[0]], green = [0, max[1]], blue = [0, max[2]], alpha = [0, max[3]].

Parameters

[out]	red	pointer to a gcgDISCRETE2D<int> object that will receive the red component of the current image. If it is NULL, the red channel is ignored.
[out]	green	pointer to a gcgDISCRETE2D<int> object that will receive the green component of the current image. If it is NULL, the green channel is ignored.
[out]	blue	pointer to a ggcgDISCRETE2D<int> object that will receive the blue component of the current image. If it is NULL, the blue channel is ignored.
[out]	alpha	pointer to a gcgDISCRETE2D<int> object that will receive the alpha component of the current image. If it is NULL, the alpha channel is ignored.

Returns

true if the selected channels (non-null gcgDISCRETE2D<int> pointers) are copied to the respective objects. If it returns false, check GCG_REPORT_MESSAGE(gcgGetReport()) for knowing the problem.

See also

importChannels()

exportChannels() [5/5]

bool gcgIMAGE::exportChannels	(	gcgDISCRETE2D< long > *	red,
		gcgDISCRETE2D< long > *	green,
		gcgDISCRETE2D< long > *	blue,
		gcgDISCRETE2D< long > *	alpha
	)

Copies the color channels of the current image into distinct gcgDISCRETE2D<long> objects. The destination objects (red, green, blue, alpha) can be NULL, indicating that a channel is not to be copied. The output have the same dimensions of the current object and are composed by long values . The original component values of the current image are preserved in the range [0, 255] for paletted, 24 and 32 bits per pixel. The range of the component values depend on the number of bits for each channel in images with 16 bits per pixel. Use the gcgIMAGE::max attribute to know each channel range: red = [0, max[0]], green = [0, max[1]], blue = [0, max[2]], alpha = [0, max[3]].

Parameters

[out]	red	pointer to a gcgDISCRETE2D<long> object that will receive the red component of the current image. If it is NULL, the red channel is ignored.
[out]	green	pointer to a gcgDISCRETE2D<long> object that will receive the green component of the current image. If it is NULL, the green channel is ignored.
[out]	blue	pointer to a ggcgDISCRETE2D<long> object that will receive the blue component of the current image. If it is NULL, the blue channel is ignored.
[out]	alpha	pointer to a gcgDISCRETE2D<long> object that will receive the alpha component of the current image. If it is NULL, the alpha channel is ignored.

Returns

true if the selected channels (non-null gcgDISCRETE2D<long> pointers) are copied to the respective objects. If it returns false, check GCG_REPORT_MESSAGE(gcgGetReport()) for knowing the problem.

See also

importChannels()

forceLinearPalette()

bool gcgIMAGE::forceLinearPalette

(

)

Classify the palette colors in ascending order of the sum R+G+B. The bitmap indices are adjusted accordingly. The resulting image has indices that correspond directly to the average intensity of the palette color. As a result, the bitmap indices can be used directly in several image processing tasks, notably if the image is gray scaled. The original alpha/exponent values are preserved. This function does not check if palette colors are duplicated.

Returns

true if the image has been converted to a version with linear palette. If it returns false, check GCG_REPORT_MESSAGE(gcgGetReport()) for knowing the problem.

See also

isGrayScale()

convertGrayScale()

convertBits()

convertGrayScale8bits()

getPaletteColor()

bool gcgIMAGE::getPaletteColor	(	int	index,
		VECTOR4	color
	)

Gets the RGBA color stored in the position index of the palette, in the range [0, palettecolors - 1]. Generally, palettecolors = (2 powered to bpp) - 1. This method is valid only for paletted images, i.e. bits per pixel <= 8. Note that gcgIMAGE currently allocates 8 bits for each channel in the palette.

Parameters

[in]	index	position in the palette. It must be in the range [0, palettecolors - 1].
[out]	color	pointer to an array of 4 floats that will receive the color in RGBA order. The values are normalized between 0.0 (no intensity) and 1.0 (maximum intensity). Paletted colors always have an Alpha/Exponent value that is returned in the forth float.

Returns

true if the color is successfully retrieved. If it returns false, check GCG_REPORT_MESSAGE(gcgGetReport()) for knowing the problem.

See also

setPaletteColor()

getPixelColor()

bool gcgIMAGE::getPixelColor	(	unsigned int	i,
		unsigned int	j,
		VECTOR4	color
	)

Retrieves the color of the pixel with coordinates (i, j). This method is not recommended for high performance processes since it always computes the pixel address and normalizes the color values. Access gcgIMAGE::data directly whenever possible. If the image has a palette, it calls getPixelIndex() and getPaletteColor() to retrieve the color, which is much slower. Note that gcgIMAGE currently supports up to 8 bits per channel.

Parameters

[in]	i	column coordinate of the pixel. It must be in the range [0, width-1].
[in]	j	row coordinate of the pixel. It must be in the range [0, height-1].
[out]	color	pointer to an array of 4 floats that will receive the pixel color in RGBA order. The values are normalized between 0.0 (no intensity) and 1.0 (maximum intensity). If the image has not the Alpha/Exponent channel, the forth float is ignored.

Returns

true if the color is successfully retrieved. If it returns false, check GCG_REPORT_MESSAGE(gcgGetReport()) for knowing the problem.

See also

setPixelColor()

getPixelIndex()

getPaletteColor()

getPixelIndex()

int gcgIMAGE::getPixelIndex	(	unsigned int	i,
		unsigned int	j
	)

Gets the palette index of the pixel with coordinates (i, j), in the range [0, palettecolors - 1]. Generally, palettecolors = (2 powered to bpp) - 1. This method is valid only for paletted images, i.e. bits per pixel <= 8.

Parameters

[in]	i	column coordinate of the pixel. It must be in the range [0, width-1].
[in]	j	row coordinate of the pixel. It must be in the range [0, height-1].

Returns

if positive or zero, it is the color index at position (i, j). If negative, the operation has failed. Check GCG_REPORT_MESSAGE(gcgGetReport()) for knowing the problem.

See also

setPixelIndex()

forceLinearPalette()

importChannels() [1/5]

bool gcgIMAGE::importChannels	(	gcgDISCRETE2D< float > *	red,
		gcgDISCRETE2D< float > *	green,
		gcgDISCRETE2D< float > *	blue,
		gcgDISCRETE2D< float > *	alpha
	)

Imports the distinct gcgDISCRETE2D<float> into the channels of the current image. The source signals (red, green, blue, alpha) must have the same dimensions. Any source can be NULL, indicating that the corresponding channel will have only zeros. The destination image can have 16 or 32 bits per pixel, if the alpha channel is provided. If it is not the case, the current image is adjusted to 32 bits per pixel. The destination image can have 16, 24 or 32 bits per pixel, if the alpha channel is not provided. If this is not the case, the current image is adjusted to 24 bits per pixel. In any case, the dimensions of the current image is adjusted to the sources. The float values of the source signals are clamped to be in the interval [0.0, 1.0] before its conversion to a decimal value to be written to the bitmap.

Parameters

[in]	red	pointer to a gcgDISCRETE2D<float> that will provide the red component to the current image. If it is NULL, the red component of all pixels is set to zero.
[in]	green	pointer to a gcgDISCRETE2D<float> that will provide the green component to the current image. If it is NULL, the green component of all pixels is set to zero.
[in]	blue	pointer to a gcgDISCRETE2D<float> that will provide the blue component to the current image. If it is NULL, the blue component of all pixels is set to zero.
[in]	alpha	pointer to a gcgDISCRETE2D<float> that will provide the alpha component to the current image. If it is NULL, the alpha component of all pixels is set to zero.

Returns

true if the selected channels (non-null gcgDISCRETE2D<float> pointers) are imported into the current image. If it returns false, check GCG_REPORT_MESSAGE(gcgGetReport()) for knowing the problem.

See also

exportChannels()

importChannels() [2/5]

bool gcgIMAGE::importChannels	(	gcgDISCRETE2D< double > *	red,
		gcgDISCRETE2D< double > *	green,
		gcgDISCRETE2D< double > *	blue,
		gcgDISCRETE2D< double > *	alpha
	)

Imports the distinct gcgDISCRETE2D<double> into the channels of the current image. The source signals (red, green, blue, alpha) must have the same dimensions. Any source can be NULL, indicating that the corresponding channel will have only zeros. The destination image can have 16 or 32 bits per pixel, if the alpha channel is provided. If it is not the case, the current image is adjusted to 32 bits per pixel. The destination image can have 16, 24 or 32 bits per pixel, if the alpha channel is not provided. If this is not the case, the current image is adjusted to 24 bits per pixel. In any case, the dimensions of the current image is adjusted to the sources. The double values of the source signals are clamped to be in the interval [0.0, 1.0] before its conversion to a decimal value to be written to the bitmap.

Parameters

[in]	red	pointer to a gcgDISCRETE2D<double> that will provide the red component to the current image. If it is NULL, the red component of all pixels is set to zero.
[in]	green	pointer to a gcgDISCRETE2D<double> that will provide the green component to the current image. If it is NULL, the green component of all pixels is set to zero.
[in]	blue	pointer to a gcgDISCRETE2D<double> that will provide the blue component to the current image. If it is NULL, the blue component of all pixels is set to zero.
[in]	alpha	pointer to a gcgDISCRETE2D<double> that will provide the alpha component to the current image. If it is NULL, the alpha component of all pixels is set to zero.

Returns

true if the selected channels (non-null gcgDISCRETE2D<double> pointers) are imported into the current image. If it returns false, check GCG_REPORT_MESSAGE(gcgGetReport()) for knowing the problem.

See also

exportChannels()

importChannels() [3/5]

bool gcgIMAGE::importChannels	(	gcgDISCRETE2D< short > *	red,
		gcgDISCRETE2D< short > *	green,
		gcgDISCRETE2D< short > *	blue,
		gcgDISCRETE2D< short > *	alpha
	)

Imports the distinct gcgDISCRETE2D<short> into the channels of the current image. The source signals (red, green, blue, alpha) must have the same dimensions. Any source can be NULL, indicating that the corresponding channel will have only zeros. The destination image can have 16 or 32 bits per pixel, if the alpha channel is provided. If it is not the case, the current image is adjusted to 32 bits per pixel. The destination image can have 16, 24 or 32 bits per pixel, if the alpha channel is not provided. If this is not the case, the current image is adjusted to 24 bits per pixel. In any case, the dimensions of the current image is adjusted to the sources. The short values of the source signals are clamped to be in the interval [0, 255] before being written to the bitmap, if the current image has 24 or 32 bits per pixel. If the current image has 16 bits per pixel, the range of the component values depend on the number of bits for each channel. Use the gcgIMAGE::max attribute to know each channel range used for clamping: red = [0, max[0]], green = [0, max[1]], blue = [0, max[2]], alpha = [0, max[3]].

Parameters

[in]	red	pointer to a gcgDISCRETE2D<short> that will provide the red component to the current image. If it is NULL, the red component of all pixels is set to zero.
[in]	green	pointer to a gcgDISCRETE2D<short> that will provide the green component to the current image. If it is NULL, the green component of all pixels is set to zero.
[in]	blue	pointer to a gcgDISCRETE2D<short> that will provide the blue component to the current image. If it is NULL, the blue component of all pixels is set to zero.
[in]	alpha	pointer to a gcgDISCRETE2D<short> that will provide the alpha component to the current image. If it is NULL, the alpha component of all pixels is set to zero.

Returns

true if the selected channels (non-null gcgDISCRETE2D<short> pointers) are imported into the current image. If it returns false, check GCG_REPORT_MESSAGE(gcgGetReport()) for knowing the problem.

See also

exportChannels()

importChannels() [4/5]

bool gcgIMAGE::importChannels	(	gcgDISCRETE2D< int > *	red,
		gcgDISCRETE2D< int > *	green,
		gcgDISCRETE2D< int > *	blue,
		gcgDISCRETE2D< int > *	alpha
	)

Imports the distinct gcgDISCRETE2D<int> into the channels of the current image. The source signals (red, green, blue, alpha) must have the same dimensions. Any source can be NULL, indicating that the corresponding channel will have only zeros. The destination image can have 16 or 32 bits per pixel, if the alpha channel is provided. If it is not the case, the current image is adjusted to 32 bits per pixel. The destination image can have 16, 24 or 32 bits per pixel, if the alpha channel is not provided. If this is not the case, the current image is adjusted to 24 bits per pixel. In any case, the dimensions of the current image is adjusted to the sources. The int values of the source signals are clamped to be in the interval [0, 255] before being written to the bitmap, if the current image has 24 or 32 bits per pixel. If the current image has 16 bits per pixel, the range of the component values depend on the number of bits for each channel. Use the gcgIMAGE::max attribute to know each channel range used for clamping: red = [0, max[0]], green = [0, max[1]], blue = [0, max[2]], alpha = [0, max[3]].

Parameters

[in]	red	pointer to a gcgDISCRETE2D<int> that will provide the red component to the current image. If it is NULL, the red component of all pixels is set to zero.
[in]	green	pointer to a gcgDISCRETE2D<int> that will provide the green component to the current image. If it is NULL, the green component of all pixels is set to zero.
[in]	blue	pointer to a gcgDISCRETE2D<int> that will provide the blue component to the current image. If it is NULL, the blue component of all pixels is set to zero.
[in]	alpha	pointer to a gcgDISCRETE2D<int> that will provide the alpha component to the current image. If it is NULL, the alpha component of all pixels is set to zero.

Returns

true if the selected channels (non-null gcgDISCRETE2D<int> pointers) are imported into the current image. If it returns false, check GCG_REPORT_MESSAGE(gcgGetReport()) for knowing the problem.

See also

exportChannels()

importChannels() [5/5]

bool gcgIMAGE::importChannels	(	gcgDISCRETE2D< long > *	red,
		gcgDISCRETE2D< long > *	green,
		gcgDISCRETE2D< long > *	blue,
		gcgDISCRETE2D< long > *	alpha
	)

Imports the distinct gcgDISCRETE2D<long> into the channels of the current image. The source signals (red, green, blue, alpha) must have the same dimensions. Any source can be NULL, indicating that the corresponding channel will have only zeros. The destination image can have 16 or 32 bits per pixel, if the alpha channel is provided. If it is not the case, the current image is adjusted to 32 bits per pixel. The destination image can have 16, 24 or 32 bits per pixel, if the alpha channel is not provided. If this is not the case, the current image is adjusted to 24 bits per pixel. In any case, the dimensions of the current image is adjusted to the sources. The long values of the source signals are clamped to be in the interval [0, 255] before being written to the bitmap, if the current image has 24 or 32 bits per pixel. If the current image has 16 bits per pixel, the range of the component values depend on the number of bits for each channel. Use the gcgIMAGE::max attribute to know each channel range used for clamping: red = [0, max[0]], green = [0, max[1]], blue = [0, max[2]], alpha = [0, max[3]].

Parameters

[in]	red	pointer to a gcgDISCRETE2D<long> that will provide the red component to the current image. If it is NULL, the red component of all pixels is set to zero.
[in]	green	pointer to a gcgDISCRETE2D<long> that will provide the green component to the current image. If it is NULL, the green component of all pixels is set to zero.
[in]	blue	pointer to a gcgDISCRETE2D<long> that will provide the blue component to the current image. If it is NULL, the blue component of all pixels is set to zero.
[in]	alpha	pointer to a gcgDISCRETE2D<long> that will provide the alpha component to the current image. If it is NULL, the alpha component of all pixels is set to zero.

Returns

true if the selected channels (non-null gcgDISCRETE2D<long> pointers) are imported into the current image. If it returns false, check GCG_REPORT_MESSAGE(gcgGetReport()) for knowing the problem.

See also

exportChannels()

isCompatibleWith()

bool gcgIMAGE::isCompatibleWith

(

gcgIMAGE *

source

)

Checks if both images are compatible: same dimensions, same bits per pixel, same masks, same palette. But not necessarily the same pixel data.

Parameters

[in]

source

pointer to the source image to be compared with. It must be non-null. A warning is issued if it is not a valid image.

Returns

true if source is compatible with the current image.

See also

copyImage()

createSimilar()

isValid()

isGrayScale()

bool gcgIMAGE::isGrayScale

(

)

Checks if the image has only gray scaled colors. If the image is paletted, the palette colors are first checked. If the palette has colors which are not gray, then all indices and corresponding colors are checked. This means that a gray scaled image might have a palette with non gray colors. If the image is not paletted, all bitmap values are verified. A color is a gray tone if R = G = B. The alpha/exponent channel, if present, is ignored.

Returns

true if the image has only gray colors. It also returns false If the current image is not valid, check GCG_REPORT_MESSAGE(gcgGetReport()) for errors.

See also

convertGrayScale()

convertBits()

convertGrayScale8bits()

forceLinearPalette()

isValid()

bool gcgIMAGE::isValid

(

)

Checks if the current image is valid: dimensions are non-zero, pixel data is allocated and bits per pixel is 1, 2, 4, 8, 16, 24 or 32. If the image has a palette, checks if it is allocated.

Returns

true if the current image is valid and can be used by any GCGlib method or function.

See also

createImage()

createSimilar()

duplicateImage()

duplicateSubimage()

copyImage()

destroyImage()

loadBMP()

bool gcgIMAGE::loadBMP

(

const char *

filename

)

Loads a file image in BMP format.

Parameters

[in]

filename

pointer to a string representing the file name. It must be non-null.

Returns

true if the image is succesfully loaded. If it returns false, check GCG_REPORT_MESSAGE(gcgGetReport()) for knowing the problem.

See also

loadJPG()

loadImage()

loadPCX()

loadTGA()

loadImage()

bool gcgIMAGE::loadImage

(

const char *

filename

)

Loads a file image based on its extension. If the file extension does not match .tga, .bmp, .pcx, .jpg or .jpeg, an error is issued.

Parameters

[in]

filename

pointer to a string representing the file name. It must be non-null.

Returns

true if the image is succesfully loaded. If it returns false, check GCG_REPORT_MESSAGE(gcgGetReport()) for knowing the problem.

See also

loadJPG()

loadBMP()

loadPCX()

loadTGA()

loadJPG()

bool gcgIMAGE::loadJPG

(

const char *

filename

)

Loads a file image in JPEG format. This function uses the Independent JPEG Group Library.

Parameters

[in]

filename

pointer to a string representing the file name. It must be non-null.

Returns

true if the image is succesfully loaded. If it returns false, check GCG_REPORT_MESSAGE(gcgGetReport()) for knowing the problem.

See also

loadImage()

loadBMP()

loadPCX()

loadTGA()

loadPCX()

bool gcgIMAGE::loadPCX

(

const char *

filename

)

Loads a file image in PCX format, paletted with 256 colors.

Parameters

[in]

filename

pointer to a string representing the file name. It must be non-null.

Returns

true if the image is succesfully loaded. If it returns false, check GCG_REPORT_MESSAGE(gcgGetReport()) for knowing the problem.

See also

loadJPG()

loadBMP()

loadImage()

loadTGA()

loadTGA()

bool gcgIMAGE::loadTGA

(

const char *

filename

)

Loads a file image in TGA format.

Parameters

[in]

filename

pointer to a string representing the file name. It must be non-null.

Returns

true if the image is succesfully loaded. If it returns false, check GCG_REPORT_MESSAGE(gcgGetReport()) for knowing the problem.

See also

loadJPG()

loadBMP()

loadPCX()

loadImage()

mergeChannels()

bool gcgIMAGE::mergeChannels	(	gcgIMAGE *	red,
		gcgIMAGE *	green,
		gcgIMAGE *	blue,
		gcgIMAGE *	alpha = NULL
	)

Merges the distinct gray scaled images into the channels of the current image. The source images (red, green, blue, alpha) must not be the source (this). All sources must be mutually compatible (see gcgIMAGE::isCompatibleWith()). Any source can be NULL, indicating that the corresponding channel will have only zeros. The destination image can have 16 or 32 bits per pixel, if the alpha channel is provided. If it is not the case, the current image is adjusted to 32 bits per pixel. The destination image can have 16, 24 or 32 bits per pixel, if the alpha channel is not provided. If this is not the case, the current image is adjusted to 24 bits per pixel. In any case, the dimensions of the current image is adjusted to the sources. The source images MUST have 8 bits per pixel and be gray scaled. Their indices are assumed to be in the [0, 255] range with a linear palette (see gcgIMAGE::forceLinearPalette()), which means that their indices values match the gray level.

Parameters

[in]	red	pointer to a gcgIMAGE that will provide the red component to the current image. It must have 8 bits per pixel with a linear gray scaled palette. The red channel values are then obtained directly from its indices. If it is NULL, the red component of all pixels is set to zero. It must not be this image.
[in]	green	pointer to a gcgIMAGE that will provide the green component to the current image. It must have 8 bits per pixel with a linear gray scaled palette. The green channel values are then obtained directly from its indices. If it is NULL, the green component of all pixels is set to zero. It must not be this image.
[in]	blue	pointer to a gcgIMAGE that will provide the blue component to the current image. It must have 8 bits per pixel with a linear gray scaled palette. The blue channel values are then obtained directly from its indices. If it is NULL, the blue component of all pixels is set to zero. It must not be this image.
[in]	alpha	pointer to a gcgIMAGE that will provide the alpha component to the current image. It must have 8 bits per pixel with a linear gray scaled palette. The alpha channel values are then obtained directly from its indices. If it is NULL, the alpha component of all pixels is set to zero. It must not be this image.

Returns

true if the selected channels (non-null gcgIMAGE pointers) are merged into the current image. If it returns false, check GCG_REPORT_MESSAGE(gcgGetReport()) for knowing the problem.

See also

splitChannels()

saveBMP()

bool gcgIMAGE::saveBMP

(

const char *

filename

)

Saves the image in BMP format. If the image has 8 bits per pixel, a RLE compressed version is computed and, if it is smaller than the uncompressed version, it is saved. All other versions are saved uncompressed.

Parameters

[in]

filename

pointer to a string representing the file name. It must be non-null.

Returns

true if the image is succesfully saved. If it returns false, check GCG_REPORT_MESSAGE(gcgGetReport()) for knowing the problem.

See also

saveJPG()

loadBMP()

saveJPG()

bool gcgIMAGE::saveJPG	(	const char *	filename,
		int	quality
	)

Saves the image in JPG format. This method uses the Independent JPEG Group library. Only 24 bits RGB and gray scaled images are supported. Jpeg format does not include alpha/exponent channel. If this image has not these formats, the function automatically computes a compatible image for saving.

Parameters

[in]	filename	pointer to a string representing the file name. It must be non-null.
[in]	quality	parameter in the range [0..100] that indicates the image quality. If closer to 0, the image is saved with poor quality but the final file size is smaller. Closer to 100 the image has high frequencies preserved but the file size tends to be bigger.

Returns

true if the image is succesfully saved. If it returns false, check GCG_REPORT_MESSAGE(gcgGetReport()) for knowing the problem.

See also

saveBMP()

loadJPG()

scale()

bool gcgIMAGE::scale	(	float	weight,
		gcgIMAGE *	source,
		float	addthis = 0.0
	)

Scales a source image source and stores the result in the current object, whose previous data is destroyed. The destination (this) and the source can be the same object. Each pixel component of the source, in the [0, 1] range, is multiplied by weight and then summed to addthis (weight * value + addthis). The result, one per RGBA component, is clamped to be between 0.0 (minimum intensity) and 1.0 (maximum intensity) and stored in this image. Use the addthis parameter to displace scalings that might result in negative values or values greater than one. All image channels are scaled. If the source image is gray scaled, forceLinearPalette() is called for it, and the scaling is computed with the indices stored in the bitmap. If the source image is paletted but is not gray scaled, the convolution results in a 32 bits image.

Parameters

[in]	weight	scalar value to multiply each color channel.
[in]	source	image that will have each pixel color scaled by the formula I = weight * color + addthis.
[in]	addthis	floating point number that must be added to the scale values BEFORE being converted to a decimal number to be written in the bitmap. Use this term when the scaling might result in negative values or values greater than one. For example, when scaling with a negative weight, yielding negative values, set addthis = 0.5. This will shift the -0.5 values (-127 is mapped to 0, for 8 bits) to 0.0, the 0.0 values to 0.5 (0 is mapped to 127, for 8 bits) and the 0.5 value to 1.0 (128 is mapped to 255, for 8 bits).

Returns

true if the scaling is successfully computed. If it returns false, check GCG_REPORT_MESSAGE(gcgGetReport()) for knowing the problem.

See also

combineAdd()

combineMult()

setPaletteColor()

bool gcgIMAGE::setPaletteColor	(	int	index,
		VECTOR4	color
	)

Sets the RGBA color in the position index of the palette, in the range [0, palettecolors - 1]. Generally, palettecolors = (2 powered to bpp) - 1. This method is valid only for paletted images, i.e. bits per pixel <= 8. Note that gcgIMAGE currently allocates 8 bits for each channel in the palette.

Parameters

[in]	index	position in the palette. It must be in the range [0, palettecolors - 1].
[in]	color	pointer to an array of 4 floats having the pixel color in RGBA order. The values must be normalized between 0.0 (minimum intensity) and 1.0 (maximum intensity). Paletted colors always have an Alpha/Exponent value that is returned in the forth float.

Returns

true if the color is successfully stored. If it returns false, check GCG_REPORT_MESSAGE(gcgGetReport()) for knowing the problem.

See also

getPaletteColor()

setPixelColor()

bool gcgIMAGE::setPixelColor	(	unsigned int	i,
		unsigned int	j,
		VECTOR4	color
	)

Sets the color of the pixel with coordinates (i, j). This method is not recommended for high performance processes since it always computes the pixel address and converts the color values. Access gcgIMAGE::data directly whenever possible. If the image has a palette, it finds the color in the palette closest (squared euclidian distance) to color and then calls setPixelIndex() to set the color, which is considerably slow. Note that gcgIMAGE currently supports up to 8 bits per channel.

Parameters

[in]	i	column coordinate of the target pixel. It must be in the range [0, width-1].
[in]	j	row coordinate of the target pixel. It must be in the range [0, height-1].
[in]	color	pointer to an array of 4 floats having the pixel color in RGBA order. The values must be normalized between 0.0 (minimum intensity) and 1.0 (maximum intensity). If the image has not the Alpha/Exponent channel, the forth float is ignored.

Returns

true if the color is successfully stored. If it returns false, check GCG_REPORT_MESSAGE(gcgGetReport()) for knowing the problem.

See also

getPixelColor()

setPixelIndex()

setPaletteColor()

setPixelIndex()

bool gcgIMAGE::setPixelIndex	(	unsigned int	i,
		unsigned int	j,
		int	newindex
	)

Sets the palette index of the pixel with coordinates (i, j), in the range [0, palettecolors - 1]. This method is valid only for paletted images, i.e. bits per pixel <= 8.

Parameters

[in]	i	column coordinate of the pixel. It must be in the range [0, width-1].
[in]	j	row coordinate of the pixel. It must be in the range [0, height-1].
[in]	newindex	new palette index of the pixel. It must be in the range [0, palettecolors]. Generally, palettecolors = (2 powered to bpp) - 1.

Returns

true if the index is successfully stored. If it returns false, check GCG_REPORT_MESSAGE(gcgGetReport()) for knowing the problem.

See also

getPixelIndex()

forceLinearPalette()

splitChannels()

bool gcgIMAGE::splitChannels	(	gcgIMAGE *	red,
		gcgIMAGE *	green,
		gcgIMAGE *	blue,
		gcgIMAGE *	alpha = NULL
	)

Copies the color channels of the current image into distinct gray scaled images. The destination images (red, green, blue, alpha) must not be the source (this). Any destination can be NULL, indicating that a channel is not to be copied. The output are 8 bits per pixel, gray scaled images, with the same dimensions of the source. The original component values of the current image are converted and scaled to the [0, 255] range. All output images have linear palettes which means that the original channel value match their indices.

Parameters

[out]	red	pointer to a gcgIMAGE that will receive the red component of the current image. If it is NULL, the red channel is ignored. It must not be this image.
[out]	green	pointer to a gcgIMAGE that will receive the green component of the current image. If it is NULL, the green channel is ignored. It must not be this image.
[out]	blue	pointer to a gcgIMAGE that will receive the blue component of the current image. If it is NULL, the blue channel is ignored. It must not be this image.
[out]	alpha	pointer to a gcgIMAGE that will receive the alpha component of the current image. If it is NULL, the alpha channel is ignored. It must not be this image.

Returns

true if the selected channels (non-null gcgIMAGE pointers) are copied to the respective images. If it returns false, check GCG_REPORT_MESSAGE(gcgGetReport()) for knowing the problem.

See also

mergeChannels()

templateMatching()

bool gcgIMAGE::templateMatching	(	unsigned int	imgleft,
		unsigned int	imgbottom,
		unsigned int	imgwidth,
		unsigned int	imgheight,
		gcgDISCRETE2D< float > *	mask,
		VECTOR2	position
	)

Finds the pixel coordinates (x, y) that gives the greatest Sum of Absolute Differences (SAD) with the alignment of the bidimensional mask and the image's pixels. The mask is called the template which has to be discovered in the current image. It is represented by an gcgDISCRETE2D<float> object normaly having points with values between 0.0 and 1.0. Each color of the image is a RGB triple with channel values normalized between 0.0 and 1.0. The origin of mask is aligned with all points inside the region defined starting at (imgleft, imgbottom), with imgwidth by imgheight pixels, and the sum of absolute differences are computed for all color channels. The total sum of absolute differences is the sum of the result of all channels. The pixel coordinate with greatest total sum is returned in position. If the source image is paletted and gray scaled, forceLinearPalette() is called for it, and the sum of absolute differences is computed with the indices stored in the bitmap. In all other configurations the actual RGB values of the pixels are used in the computation. This function is highly computation expensive. Try to reduce the search space by setting properly the imgleft, imgbottom, imgwidth and imgheight parameters.

Parameters

[in]	imgleft	left column of the region to search the pixel with greatest Sum of Absolute Differences.
[in]	imgbottom	bottom row of the region to search the pixel with greatest Sum of Absolute Differences.
[in]	imgwidth	width of the region to search the pixel with greatest Sum of Absolute Differences.
[in]	imgheight	height of the region to search the pixel with greatest Sum of Absolute Differences.
[in]	mask	floating point bidimensional signal that represents the template to be found in the current image. Generally the values of mask are between 0.0 and 1.0. The origin attribute of the mask is used for aligment with the pixels.
[out]	position	pointer to an array of two floats that will receive the pixel coordinates that, aligned with the mask's origin, gives the greatest Sum of Absolute Differences (SAD).

Returns

true if the template was successfully matched with a subimage of the current image. If it returns false, check GCG_REPORT_MESSAGE(gcgGetReport()) for knowing the problem.

See also

gcgDISCRETE2D<float>

transformColorSpace()

bool gcgIMAGE::transformColorSpace	(	gcgIMAGE *	source,
		MATRIX4	matrix
	)

Applies the linear tranformation defined by a 4 x 4 matrix in all image colors. It is called a color space transform. Each image pixel has a color vector [R G B A] composed by the red, green, blue and alpha values, normalized between 0.0 (darker) and 1.0 (brigher). This method computes the matrix-vector multiplication [R' G' B' A'] = matrix * [R G B A]. The resulting color components [R' G' B' A'] are clamped between 0.0 and 1.0 and stored in the image bits. If the image has no alpha/exponent channel defined, the last column and the last row of the matrix must be 0 to avoid errors. If this is not the case, the resulting color is undefined. For 24 bits images, the last column is ignored (alpha component is set to zero: A = 0) and the last row is ignored (A' is not computed). The result is stored in this image, whose previous data is destroyed. The destination (this) and the source can be the same object. It is useful in color calibration processes.

Parameters

[in]	source	image that will have each color tranformed by matrix.
[in]	matrix	pointer to an array of 16 floats representing a matrix of 4 x 4 elements. First 4 elements form the row 1, and so on.

Returns

true if the color space is successfully transformed. If it returns false, check GCG_REPORT_MESSAGE(gcgGetReport()) for knowing the problem.

Member Data Documentation

palette

unsigned char* gcgIMAGE::palette

If it is non-null, the gcgIMAGE::data elements are indices to a color stored in this table. Each color in this array is 4 byte long and stores the RGB plus the another channel (alpha or exponent).

---

The documentation for this class was generated from the following file:

• M:/Documentos/Projetos/Projetos/GCGlib/src/gcg.h