Main Page Modules Class Hierarchy Data Structures File List Data Fields Globals

Image handling

A MIMAGE object stores an image that can be drawn in a DrawArea object or can be set as background for PushButton, RadioButton and ToggleButton objects. More...


Functions
MIMAGE	MAllocImage (int imgw, int imgh, int np)
	Creates an empty MIMAGE object.
MIMAGE	MReadImageFile (const char *fname)
	Creates a MIMAGE object from an image file.
MIMAGE	MReadPNGFile (const char *fname)
	Creates a MIMAGE object from a PNG file.
MIMAGE	MReadBMPFile (const char *fname)
	Creates a MIMAGE object from a Windows BMP file.
MIMAGE	MReadTIFFFile (const char *fname)
	Creates a MIMAGE object from a TIFF file.
MIMAGE	MReadJPEGFile (const char *fname)
	Creates a MIMAGE object from a JPEG file.
MIMAGE	MReadGIFFile (const char *fname)
	Creates a MIMAGE object from a GIF file.
MIMAGE	MImageClone (MIMAGE img)
	Creates a new image by cloning the one received as parameter.
void	MImageAddDefaultTypeGIF (void)
	Adds GIF format to the list of image types supported by default image loading function MReadImage().
void	MImageAddDefaultTypeTIFF (void)
	Adds TIFF format to the list of image types supported by default image loading function MReadImage().
void	MImageAddDefaultTypeJPEG (void)
	Adds JPEG format to the list of image types supported by default image loading function MReadImage().
void	MImageAddDefaultTypePNG (void)
	Adds PNG format to the list of image types supported by default image loading function MReadImage().
void	MAddImagePath (const char *path)
	Adds a path to the image search path list.
void	MRemoveImagePath (const char *path)
	Removes a previously added image search path.
void	MImageAddAlphaChannel (MIMAGE_DESCR *img)
	Adds the alpha channel to an image structure.
int	MImageGetPixelAlpha (MIMAGE img, int x, int y)
	Gets the alpha value associated to pixel x,y in the image.
void	MImageSetPixelAlpha (MIMAGE img, int x, int y, CARD8 alpha)
	Sets the alpha value associated to pixel x,y in the image.
MIMAGE	MCreateImageMaskByCMapIndex (MIMAGE img, int index)
	Creates a MIMAGE object suitable for use as a Mask for the image object 'img'.
MIMAGE	MCreateImageMaskByPixel (MIMAGE img, int x, int y)
	Creates a mask for image 'img' by pixel position.
MIMAGE	MCreateImageMaskByRGB (MIMAGE img, int r, int g, int b)
	Creates a MIMAGE object suitable for use as a Mask for the image object 'img'.
int	MWriteTIFFFile (MIMAGE img, const char *name, int compression)
	Dumps an image to a TIFF file.
int	MWriteBMPFile (MIMAGE img, const char *fname)
	Dumps an image to a BMP file.
int	MWriteJPEGFile (MIMAGE img, const char *name, int quality)
	Dumps an image to a JPEG file.
void	MFreeImage (MIMAGE img)
	Frees all resources used by the image, making image 'img' no longer useable.
void	MInstallImage (MIMAGE img)
	Prepares the image object for drawing.
void	MUninstallImage (MIMAGE img)
	Frees image resources.
void	MImageGetInfo (MIMAGE img, int pw, int ph, int *pnplanes)
	Returns basic image information: width, height and nr of planes.
void	MImageGetPixelRGB (MIMAGE img, int x, int y, int pr, int pg, int *pb)
	Returns the R-G-B values of an image pixel.
void	MImageSetPixelRGB (MIMAGE img, int x, int y, int r, int g, int b)
	Sets the R-G-B values of an image pixel.
int	MImageGetPixelIndex (MIMAGE img, int x, int y)
	Returns the colormap index value of an image pixel.
void	MImageSetPixelIndex (MIMAGE img, int x, int y, int i)
	Sets the colormap index value of an image pixel.
void	MImageGetCMapEntry (MIMAGE img, int i, int pr, int pg, int *pb)
	Returns the R-G-B values of a colormap entry in the image.
void	MImageSetCMapEntry (MIMAGE img, int i, int r, int g, int b)
	Sets the R-G-B values of an entry in the image colormap.
void	MImageSetMask (MIMAGE dst, MIMAGE mask)
	Enables masked drawing for the 'dst' image.
void	MImageMerge (MIMAGE dst, MIMAGE src, int xo, int yo, int transparent)
	Copies the image 'src' over 'dst' starting at offset 'xo','yo'.
void	MImageComputeBackgroundRGB (MIMAGE img, int pr, int pg, int *pb)
void	MImageSetMaskByCMapIndex (MIMAGE img, int id)
void	MImageSetMaskByPixel (MIMAGE img, int x, int y)
void	MImageSetMaskByRGB (MIMAGE img, int r, int g, int b)

Detailed Description

A MIMAGE object stores an image that can be drawn in a DrawArea object or can be set as background for PushButton, RadioButton and ToggleButton 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.

Function Documentation

void MAddImagePath ( const char * path )

Adds a path to the image search path list.
Via this function 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.

MIMAGE MAllocImage ( int imgw,

int imgh,

int np

)

Creates an empty MIMAGE object.
You can set image pixel colors using MImageSetPixelRGB in case of a True Color image (24 planes), or MImageSetPixelIndex and MImageSetCMapEntry 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.

MIMAGE MCreateImageMaskByCMapIndex ( MIMAGE img,

int index

)

Creates a MIMAGE object suitable for use as a Mask for the image object 'img'.
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: MImageSetMask ), the 'index' argument specifies a color in the calling CmImage object to be made 'transparent'. This method works correctly ONLY with Colormapped images.

MIMAGE MCreateImageMaskByPixel ( MIMAGE img,

int x,

int y

)

Creates a mask for image 'img' by pixel position.
The returned image is able to mask all pixels in the source image having the same color of the pixel at position 'x', 'y'.

MIMAGE MCreateImageMaskByRGB ( MIMAGE img,

int r,

int g,

int b

)

Creates a MIMAGE object suitable for use as a Mask for the image object 'img'.
The returned image has a 1 plane depth and same dimensions as the image object 'img'. Pixels in 'img' 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: MImageSetMask ), the 'index' argument specifies a color in the calling CmImage object to be made 'transparent'. This function works with both TryeColor and Colormapped images. For Colormapped images, the createImageMaskByCMapIndex method is more performant.

void MFreeImage ( MIMAGE img )

Frees all resources used by the image, making image 'img' no longer useable.

void MImageAddAlphaChannel ( MIMAGE_DESCR * img )

Adds the alpha channel to an image structure.

void MImageAddDefaultTypeGIF ( void )

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

void MImageAddDefaultTypeJPEG ( void )

Adds JPEG format to the list of image types supported by default image loading function MReadImage().
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 MImageAddDefaultTypePNG ( void )

Adds PNG format to the list of image types supported by default image loading function MReadImage().
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 MImageAddDefaultTypeTIFF ( void )

Adds TIFF format to the list of image types supported by default image loading function MReadImage().
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.

MIMAGE MImageClone ( MIMAGE img )

Creates a new image by cloning the one received as parameter.

void MImageComputeBackgroundRGB ( MIMAGE img,

int * pr,

int * pg,

int * pb

)

void MImageGetCMapEntry ( MIMAGE img,

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:

img The source MIMAGE

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.

void MImageGetInfo ( MIMAGE img,

int * pw,

int * ph,

int * pnplanes

)

Returns basic image information: width, height and nr of planes.

int MImageGetPixelAlpha ( MIMAGE img,

int x,

int y

)

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

int MImageGetPixelIndex ( MIMAGE img,

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 MImageGetPixelRGB ( MIMAGE img,

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:

img The source MIMAGE

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.

void MImageMerge ( MIMAGE dst,

MIMAGE src,

int xo,

int yo,

int transparent

)

Copies the image 'src' over 'dst' 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 MImageSetCMapEntry ( MIMAGE img,

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:

img The source MIMAGE

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 MImageSetMask ( MIMAGE dst,

MIMAGE mask

)

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

void MImageSetMaskByCMapIndex ( MIMAGE img,

int id

)

void MImageSetMaskByPixel ( MIMAGE img,

int x,

int y

)

void MImageSetMaskByRGB ( MIMAGE img,

int r,

int g,

int b

)

void MImageSetPixelAlpha ( MIMAGE img,

int x,

int y,

CARD8 alpha

)

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

void MImageSetPixelIndex ( MIMAGE img,

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 MImageSetPixelRGB ( MIMAGE img,

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:

img The source MIMAGE

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 MInstallImage ( MIMAGE img )

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

MIMAGE MReadBMPFile ( const char * fname )

Creates a MIMAGE object from a Windows BMP file.
Both uncompressed and RLE compressed formats are supported. If the bitmap file loading fails for any reason, then a NULL value is returned.
Parameters:

fname The name of the BMP file to load.

MIMAGE MReadGIFFile ( const char * fname )

Creates a MIMAGE object from a GIF file.

MIMAGE MReadImageFile ( const char * fname )

Creates a MIMAGE object from an image file.
If the bitmap file loading fails for any reason, then a NULL value is returned. This function is capable of loading a generic image file among the supported types defined as default. At program startup, only the BMP image format is available as a default type. If you want to add further image types in the default list, then you have to explicitly instruct the library by calling one or more of the functions: MImageAddDefaultTypeGIF(), MImageAddDefaultTypeTIFF(), MImageAddDefaultTypeJPEG(), MImageAddDefaultTypePNG().
Unless the image filename specifies a full pathname, the image file is searched in a default path list. See MAddImagePath () for more information on default locations for image files.

Parameters:

fname The name of the image file to load.

MIMAGE MReadJPEGFile ( const char * fname )

Creates a MIMAGE object from a JPEG file.

MIMAGE MReadPNGFile ( const char * fname )

Creates a MIMAGE object from a PNG file.
If the image file loading fails for any reason, then a NULL value is returned.
Parameters:

fname The name of the PNG file to load. If it does not specify an absolute pathname and the file is not found in the program's current directory, then it is searched for in the MGUI Sys directory MGetSysDir .

MIMAGE MReadTIFFFile ( const char * fname )

Creates a MIMAGE object from a TIFF file.

void MRemoveImagePath ( const char * path )

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 MUninstallImage ( MIMAGE img )

Frees image resources.
This method causes the image colors to be freed and the system dependent pixmap to be destroyed. The image can be re-installed again later if necessary.

int MWriteBMPFile ( MIMAGE img,

const char * fname

)

Dumps an image to a BMP file.

int MWriteJPEGFile ( MIMAGE img,

const char * name,

int quality

)

Dumps an image to a JPEG file.

int MWriteTIFFFile ( MIMAGE img,

const char * name,

int compression

)

Dumps an image to a TIFF file.

Generated on Sun Jun 29 13:03:09 2003 for MGui API by

1.3-rc2

Image handling

Functions

Detailed Description

Function Documentation