---

CmImage Class Reference

IMAGE Class. More...

Inheritance diagram for CmImage:

Public Methods
virtual	~CmImage (void)
	CmImage (const char *fname)
	Creates a CmImage object from an file.
	CmImage (int imgw, int imgh, int np)
	Creates an empty CmImage object.
void	install (void)
	Prepares the image object for drawing.
void	uninstall (void)
	Frees resources allocated by a CmImage.
int	getWidth (void)
	Returns the image width in pixels.
int	getHeight (void)
	Returns the image height in pixels.
int	getNColors (void)
	Returns the number of colors in the image.
int	getNPlanes (void)
	Returns the number of planes in the image.
void	getPixelRGB (int x, int y, int *pr, int *pg, int *pb)
	Returns the R-G-B values of an image pixel.
void	setPixelRGB (int x, int y, int r, int g, int b)
	Sets the R-G-B values of an image pixel.
int	getPixelIndex (int x, int y)
	Returns the colormap index value of an image pixel.
void	setPixelIndex (int x, int y, int i)
	Sets the colormap index value of an image pixel.
void	getCMapEntry (int i, int *pr, int *pg, int *pb)
	Returns the R-G-B values of a colormap entry in the image.
void	setCMapEntry (int i, int r, int g, int b)
	Sets the R-G-B values of an entry in the image colormap.
void	merge (CmImage *src, int xo, int yo, int transparent)
	Copies the 'src' CmImage to the calling CmImage object starting at offset 'xo','yo'.
void	setMask (CmImage *mask)
	Enables masked drawing for the calling CmImage object.
void	setMaskByCMapIndex (int id)
void	setMaskByPixel (int x, int y)
void	setMaskByRGB (int r, int g, int b)
void	addAlphaChannel (void)
	Adds the alpha channel to an image structure.
int	getPixelAlpha (int x, int y)
	Gets the alpha value associated to pixel x,y in the image.
void	setPixelAlpha (int x, int y, CARD8 alpha)
	Sets the alpha value associated to pixel x,y in the image.
CmImage *	clone (void)
	Allocates a new CmImage object using pixels in the calling CmImage object.
CmImage *	createImageMaskByCMapIndex (int index)
	Creates a CmImage object suitable for use as a Mask for the calling object.
CmImage *	createImageMaskByRGB (int r, int g, int b)
	Creates a CmImage object suitable for use as a Mask for the calling object.
CmImage *	createImageMaskByPixel (int x, int y)
void	computeBackgroundRGB (int *pr, int *pg, int *pb)
Static Public Methods
void	addDefaultTypeGIF (void)
	Adds GIF format to the list of image types supported by default constructor.
void	addDefaultTypeTIFF (void)
	Adds TIFF format to the list of image types supported by default constructor.
void	addDefaultTypeJPEG (void)
	Adds JPEG format to the list of image types supported by default constructor.
void	addDefaultTypePNG (void)
	Adds PNG format to the list of image types supported by default constructor.
void	addPath (const char *path)
	Adds a path to the image search path list.
void	removePath (const char *path)
	Removes a previously added image search path.
Protected Methods
void	allocImage (int imgw, int imgh, int np)

---

Detailed Description

IMAGE Class.

A CmImage object stores an image that can be drawn in a CmDrawArea object or can be set as background for CmPushButton, CmRadioButton and CmToggleButton objects. Before drawing the image you must install() it, that is: allocate image colors. If your image is not currently displayed in any object and you want to keep it in memory, you can uninstall() it in order to free image colors. This is particularly recommended if you run your application in a colormap based color system (16 or 256 color modes). Installing an image can also cause further resource allocation: under Windows a BITMAP is created, under X-Window a PIXMAP is allocated in the server's memory, under GRX a GrContext is created. CmImage objects can be created by loading a BMP file or by specifying the image attributes as the dimensions and the depth.

---

Constructor & Destructor Documentation

virtual CmImage::~CmImage (  void    )  [virtual]

CmImage::CmImage (  const char *    fname )

Creates a CmImage object from an file. If the bitmap file loading fails for any reason, then a dummy c++ object is created. You can test such failure by comparing the image width returned by the getWidth method with the zero value. By default the only supported image type is BMP. You can add more types by calling one or more of the static methods addDefaultTypeGIF(), addDefaultTypeTIFF(), addDefaultTypeJPEG(), addDefaultTypePNG(). Unless the image filename specifies a full pathname, the image file is searched in a default path list. See addPath () for more information on default locations for image files. Parameters: fname  The name of the image file to load.

CmImage::CmImage (  int    imgw, int    imgh, int    np )

Creates an empty CmImage object. You can set image pixel colors using setPixelRGB in case of a True Color image (24 planes), or setPixelIndex and setCMapEntry in case of a colormapped image (nplanes != 24). Parameters: imgw  The desired image width. imgh  The desired image height. np  The desired number of color planes. Valid values are 1, 4, 8, 24.

---

Member Function Documentation

void CmImage::addAlphaChannel (  void    )

Adds the alpha channel to an image structure.

void CmImage::addDefaultTypeGIF (  void    )  [static]

Adds GIF format to the list of image types supported by default constructor. After having called this static method the application code is enabled to load GIF image files.

void CmImage::addDefaultTypeJPEG (  void    )  [static]

Adds JPEG format to the list of image types supported by default constructor. After having called this static method the application code is enabled to load JPEG image files. If you use this method in your program, you'll have to link the external jpeg-6b library by Independent JPEG Group.

void CmImage::addDefaultTypePNG (  void    )  [static]

Adds PNG format to the list of image types supported by default constructor. After having called this static method the application code is enabled to load PNG image files. If you use this method in your program, you'll have to link the external libpng 1.2.5 library.

void CmImage::addDefaultTypeTIFF (  void    )  [static]

Adds TIFF format to the list of image types supported by default constructor. After having called this static method the application code is enabled to load TIFF image files. If you use this method in your program, you'll have to link the external tiff library by Sam Leffler.

void CmImage::addPath (  const char *    path )  [static]

Adds a path to the image search path list. Via this method you can extend the image path search list. Image files that cannot be found in the program's working directory are first searched in the Directory list specified by the MGUI_IMAGE_PATH environment variable (paths separated by ';' or ':'), then in the following subdirectories: <application name> images tiles . of the following base directories: $HOME/mgui/sys (Unix), $USERPROFILE/mgui/sys (non UNIX) /usr/local/mgui/sys (Unix), $ALLUSERSPROFILE/mgui/sys (non Unix) $MGUIDIR or actual MGUISYS directory Parameters: path  The additional path where to search image files.

void CmImage::allocImage (  int    imgw, int    imgh, int    np )  [protected]

CmImage* CmImage::clone (  void    )

Allocates a new CmImage object using pixels in the calling CmImage object.

void CmImage::computeBackgroundRGB (  int *    pr, int *    pg, int *    pb )

CmImage* CmImage::createImageMaskByCMapIndex (  int    index )

Creates a CmImage object suitable for use as a Mask for the calling object. The returned image has a 1 plane depth and same dimensions as the calling object. Pixels in the calling object that are using the colormap entry specified by the 'index' argument will generate zero pixels in the returned mask. Provided that the returned image is used to set the image mask (see: setMask ), the 'index' argument specifies a color in the calling CmImage object to be made 'transparent'. This method works correctly ONLY with Colormapped images.

CmImage* CmImage::createImageMaskByPixel (  int    x, int    y )

CmImage* CmImage::createImageMaskByRGB (  int    r, int    g, int    b )

Creates a CmImage object suitable for use as a Mask for the calling object. The returned image has a 1 plane depth and same dimensions as the calling object. Pixels in the calling object having an R-G-B value exactly equal to that provided by the 'r', 'g', 'b' arguments will generate zero pixels in the returned mask. Provided that the returned image is used to set the image mask (see: setMask ), the 'index' argument specifies a color in the calling CmImage object to be made 'transparent'. This method works with both TryeColor and Colormapped images. For Colormapped images, the createImageMaskByCMapIndex method is more performant.

void CmImage::getCMapEntry (  int    i, int *    pr, int *    pg, int *    pb )

Returns the R-G-B values of a colormap entry in the image. This method works ONLY with Colormapped images. Parameters: i  Index in the colormap table to get R-G-B values from. pr  Points to an integer variable that will contain the Red pixel value on return. pg  Points to an integer variable that will contain the Green pixel value on return. pb  Points to an integer variable that will contain the Blue pixel value on return.

int CmImage::getHeight (  void    )

Returns the image height in pixels.

int CmImage::getNColors (  void    )

Returns the number of colors in the image. A zero value is returned if the image is TrueColor, that is: 24 planes image with no colormap.

int CmImage::getNPlanes (  void    )

Returns the number of planes in the image.

int CmImage::getPixelAlpha (  int    x, int    y )

Gets the alpha value associated to pixel x,y in the image.

int CmImage::getPixelIndex (  int    x, int    y )

Returns the colormap index value of an image pixel. The pixel is identified by the 'x' and 'y' arguments (upper left corner of the image). This method works ONLY with Colormapped images. A negative value (-1) is returned if the image is TrueColor.

void CmImage::getPixelRGB (  int    x, int    y, int *    pr, int *    pg, int *    pb )

Returns the R-G-B values of an image pixel. This method works with both TrueColor and Colormapped images. Parameters: x  The X coordinate of the pixel y  The Y coordinate of the pixel (top to bottom of image) pr  A pointer to an integer variable that will contain the Red pixel value on return. pg  A pointer to an integer variable that will contain the Green pixel value on return. pb  A pointer to an integer variable that will contain the Blue pixel value on return.

int CmImage::getWidth (  void    )

Returns the image width in pixels.

void CmImage::install (  void    )

Prepares the image object for drawing. This method causes the image colors to be allocated and a system dependent pixmap to be created.

void CmImage::merge (  CmImage *    src, int    xo, int    yo, int    transparent )

Copies the 'src' CmImage to the calling CmImage object starting at offset 'xo','yo'. Pixels in 'src' having a color index equal to 'transparent' are not copied. This function only works with colormapped images having the same depth (2, 16 or 256 colors).

void CmImage::removePath (  const char *    path )  [static]

Removes a previously added image search path. This method has no effect on existing paths in the list that haven't been added using addPath(). Parameters: path  The additional path where to search image files.

void CmImage::setCMapEntry (  int    i, int    r, int    g, int    b )

Sets the R-G-B values of an entry in the image colormap. This method works ONLY with Colormapped images. Parameters: i  The X coordinate of the pixel r  The Red component to set to the colormap entry. g  The Blue component to set to the colormap entry. b  The Blue component to set to the colormap entry.

void CmImage::setMask (  CmImage *    mask )

Enables masked drawing for the calling CmImage object. The 'mask' image must be a 1 plane image having same dimensions as the calling object. Only pixels in the calling object having a corresponding pixel value of 1 in the associated mask will be output.

void CmImage::setMaskByCMapIndex (  int    id )

void CmImage::setMaskByPixel (  int    x, int    y )

void CmImage::setMaskByRGB (  int    r, int    g, int    b )

void CmImage::setPixelAlpha (  int    x, int    y, CARD8    alpha )

Sets the alpha value associated to pixel x,y in the image.

void CmImage::setPixelIndex (  int    x, int    y, int    i )

Sets the colormap index value of an image pixel. The pixel is identified by the 'x' and 'y' arguments (upper left corner of the image). This method takes effect ONLY in Colormapped images.

void CmImage::setPixelRGB (  int    x, int    y, int    r, int    g, int    b )

Sets the R-G-B values of an image pixel. This method works with both TrueColor and Colormapped images. In case of Colormapped image, the nearest color defined in the image colormap is used to set the pixel value. Parameters: x  The X coordinate of the pixel y  The Y coordinate of the pixel (top to bottom of image) r  The Red component to set to the pixel value. g  The Blue component to set to the pixel value. b  The Blue component to set to the pixel value.

void CmImage::uninstall (  void    )

Frees resources allocated by a CmImage. This method causes the image colors to be released and the system dependent pixmap to be destroyed. The image can be re-installed again if necessary.

---