IlvBitmap Class Reference

Port class. More...

#include <ilviews/base/port.h>

Inheritance diagram for IlvBitmap:

List of all members.

Public Member Functions
	IlvBitmap (IlvDisplay *display, IlvWindowsHandle hBitmap, IlBoolean owner=((IlBoolean) 0))
	Constructor from an HBITMAP.
	IlvBitmap (IlvDisplay *display, IlvDim width, IlvDim height, IlUShort depth)
	Constructor.
	IlvBitmap (IlvDisplay *display, IlvDim width, IlvDim height, IlUShort depth, unsigned char *data, IlBoolean bitOrder=((IlBoolean) 1), IlUShort padding=32)
	Constructor.
IlBoolean	computeMask ()
	Computes the mask of this bitmap.
IlUShort	depth () const
	Retrieves the depth of this bitmap.
IlvBitmapAnimationHandler *	getAnimationHandler () const
	Returns the animation handler connected to this bitmap.
IlvBitmap *	getMask () const
	Retrieves the mask of this bitmap.
const char *	getName () const
	Retrieves the name of this bitmap.
IlInt	getTransparentColorIndex () const
	Retrieves the transparent color of this bitmap.
virtual IlBoolean	isABitmap () const
	Queries the nature of this port.
void	lock ()
	Locks the bitmap.
virtual IlBoolean	save (ostream &stream) const
	Saves a bitmap to a stream.
virtual IlBoolean	save (const char *filename) const
	Saves the bitmap to a file.
IlBoolean	saveAscii (const char *filename) const
	Saves an ASCII representation of this bitmap to a file.
void	setAnimationHandler (IlvBitmapAnimationHandler *handler)
	Sets the animation handler connected to this bitmap.
void	setMask (IlvBitmap *mask)
	Sets the mask of this bitmap.
void	setName (const char *name)
	Sets the name of this bitmap.
void	setTransparentColorIndex (IlInt tcIndex)
	Sets the transparent color of this bitmap.
void	unLock ()
	Unlocks the bitmap.
void	useColor (IlvColor *color)
	Verbose:.
Friends
class	IlvDisplay

---

Detailed Description

Port class.

Library: display

Instances of the IlvBitmap class are rectangular areas that store a group of pixels that make an image. These images can be in full color. In this case, each pixel value represents a color index when your display system has no true-color capabilities. To find the exact color that will be displayed for this pixel, the system lookup table is consulted. If your display system has true color capabilities, then each pixel of the bitmap stores its complete color information.

Also, images can be monochrome. In this case, there is only one bit per pixel, and the drawing of these one-bit-deep bitmaps will take place by setting the 1 pixels to the foreground color of the palette that is used, and the 0 pixels will be set to the background color of this palette or left unchanged.

A colored bitmap can be associated a mask. A mask is a monochrome bitmap that indicates which of the pixels in the actual source image will be displayed. The pixels in the bitmap that correspond to '0' bits in the mask will be capable of not being displayed, achieving the effect of a transparent bitmap, that is, a color bitmap that has transparent parts.

Because IlvBitmap derives from IlvPort, you can actually draw into bitmap using the member functions of its parent classes. Most of the time, though, a bitmap is made from the conversion of a data file using an IlvBitmapStreamer.

See also:

IlvBitmapData, IlvBitmapStreamer, IlvIcon, IlvTransparentIcon, IlvZoomableIcon, IlvZoomableTransparentIcon.

---

Constructor & Destructor Documentation

IlvBitmap::IlvBitmap	(	IlvDisplay *	display,
		IlvDim	width,
		IlvDim	height,
		IlUShort	depth,
		unsigned char *	data,
		IlBoolean	bitOrder = ((IlBoolean) 1),
		IlUShort	padding = 32
	)

Constructor.

Initializes an empty image. Its content is unpredictable but the memory area to hold a future valid image is allocated and made available.

Parameters:

	display	The display where this bitmap is created.
	width	The width of this new bitmap.
	height	The height of this new bitmap.
	depth	The depth of this new bitmap, that is, how many bits should be used to hold the pixel value of each individual image element. This can be either 1 for monochrome bitmaps, or the depth of the display as returned by calling display->screenDepth().
	data	The initial data that initializes the bitmap pixel. This data must respect the following rules: The whole image is given as a series of scan lines from image top to bottom. The pixel values are packed into bytes from left to right, and each scan line must be padded to padding bits. The bits are packed into padding bit words from left to right with a bit order defined by bitOrder. The data may be composed in three different ways - either successive bytes or successive 32-bit integers - depending on the display depth: If depth is 1, the data must be made of successive bytes, where each bit describes a pixel of the image. If depth is greater than 1 but less than or equal to 8, the bitmap uses a lookup color table (also called color map) and each byte of data gives the index in this color map where the actual color value can be found. If depth is strictly greater than 8, the data must be made of successive 32-bit integers in MSB format. In that case, each of the three color components consists of 8-bits. These three bytes must be packed into 32 bits in this way: value = (red << 16) | (green << 8) | blue
	bitOrder	Indicates the bit order of the data. The data bits are considered most significant bits first if bitOrder is IlTrue, or least significant bits first if bitOrder is set to IlFalse.
	padding	The padding value. The length of each scan line in data must be a multiple of this value.

IlvBitmap::IlvBitmap	(	IlvDisplay *	display,
		IlvDim	width,
		IlvDim	height,
		IlUShort	depth
	)

Constructor.

Initializes a bitmap that has the indicated size and depth. The initial contents are unpredictable.

Parameters:

	display	The display where this bitmap is created.
	width	The width of this new bitmap.
	height	The height of this new bitmap.
	depth	The depth of this new bitmap, that is, how many bits should be used to hold the pixel value of each individual image element. This can be either 1 for monochrome bitmaps, or the depth of the display as returned by calling display->screenDepth().

IlvBitmap::IlvBitmap	(	IlvDisplay *	display,
		IlvWindowsHandle	hBitmap,
		IlBoolean	owner = ((IlBoolean) 0)
	)

Constructor from an HBITMAP.

Initializes a bitmap from a Windows handle to a bitmap (HBITMAP). The width, height, and depth are retrieved directly from the HBITMAP.

Parameters:

	display	A pointer to an IlvDisplay.
	hBitmap	The HBITMAP.
	owner	A Boolean that indicates whether the object must delete the HBITMAP when this parameter is IlTrue or not delete it when this parameter is IlFalse.

---

Member Function Documentation

IlBoolean IlvBitmap::computeMask

(

)

Computes the mask of this bitmap.

This member function computes a monochrome mask of the image currently stored in this bitmap. This mask is used to draw this bitmap transparently. The mask has the same dimensions as this bitmap, but every pixel of the original image that matches the transparent color index will be converted to a '0' bit in the output mask (see setTransparentColorIndex). All other pixels will result in a '1' in the mask. The original image may be modified after a call to computeMask.

Returns:

IlTrue if the mask is successfully computed (that is, there is a transparent color index that was used to compute the image mask). If the original bitmap is monochrome, or if the transparent color index has not been set, then this member function returns IlFalse.

IlUShort IlvBitmap::depth

(

)

const [virtual]

Retrieves the depth of this bitmap.

Returns:

The depth of the bitmap.

Reimplemented from IlvSystemPort.

IlvBitmapAnimationHandler* IlvBitmap::getAnimationHandler

(

)

const

Returns the animation handler connected to this bitmap.

Returns:

The animation handler connected to this bitmap, or 0 if there's none.

See also:

IlvBitmapAnimationHandler, setAnimationHandler

IlvBitmap* IlvBitmap::getMask

(

)

const

Retrieves the mask of this bitmap.

Returns:

The image mask bitmap, or 0 if there is none (that is, the bitmap has no transparent area).

const char* IlvBitmap::getName

(

)

const

Retrieves the name of this bitmap.

Returns:

The name of the bitmap object, if any was set.

IlInt IlvBitmap::getTransparentColorIndex

(

)

const

Retrieves the transparent color of this bitmap.

Returns:

The index of the color that must be considered as transparent in the bitmap. This index will be used to compute the image mask when the bitmap is first requested to be displayed as transparent. It is automatically updated when creating the bitmap from a bitmap file that stores the transparent color information. A returned value of -1 means that this bitmap has no transparent color.

virtual IlBoolean IlvBitmap::isABitmap

(

)

const [virtual]

Queries the nature of this port.

Returns:

A Boolean value that is always IlTrue.

Reimplemented from IlvSystemPort.

void IlvBitmap::lock

(

)

Locks the bitmap.

You must call this function if you want this bitmap to be shared among different objects (such as in the IlvIcon class).

virtual IlBoolean IlvBitmap::save

(

ostream &

stream

)

const [virtual]

Saves a bitmap to a stream.

Writes out the binary description of the image.

Parameters:

stream

The output stream where this bitmap is saved.

Returns:

IlTrue if the save is successful, and IlFalse otherwise.

virtual IlBoolean IlvBitmap::save

(

const char *

filename

)

const [virtual]

Saves the bitmap to a file.

Writes out the binary description of the image.

Parameters:

filename

The filename of the file where this bitmap is saved.

Returns:

IlTrue if the save is successful, and IlFalse otherwise.

IlBoolean IlvBitmap::saveAscii

(

const char *

filename

)

const

Saves an ASCII representation of this bitmap to a file.

The description of this IlvBitmap image will be stored in XBM (black and white) or XPM (color) format. This makes it easier, for example, to transfer your images from one site to another. The IlvDisplay class has a member function that lets you read from this new format (see IlvDisplay::readAsciiBitmap).

Parameters:

filename

The filename of the file where this bitmap is saved.

Returns:

IlTrue if the save is successful, and IlFalse otherwise.

void IlvBitmap::setAnimationHandler

(

IlvBitmapAnimationHandler *

handler

)

Sets the animation handler connected to this bitmap.

The animation handler is deleted when the bitmap will be deleted.

Parameters:

handler

The animation handler.

See also:

IlvBitmapAnimationHandler, getAnimationHandler

void IlvBitmap::setMask

(

IlvBitmap *

mask

)

Sets the mask of this bitmap.

The previous mask is unlocked, and the new mask is locked.

Parameters:

mask

The new mask of this bitmap.

void IlvBitmap::setName

(

const char *

name

)

Sets the name of this bitmap.

Parameters:

name

The string that is copied as the new name of this bitmap.

void IlvBitmap::setTransparentColorIndex

(

IlInt

tcIndex

)

Sets the transparent color of this bitmap.

Parameters:

tcIndex

The new transparent color index of this bitmap.

void IlvBitmap::unLock

(

)

Unlocks the bitmap.

If no more objects are locking this bitmap, it will then be destroyed.

void IlvBitmap::useColor

(

IlvColor *

color

)

Verbose:.

Indicates that the color referred to as color is used in this bitmap. The effect of this function call is that the color will be locked, and referenced to be unlocked when the bitmap is destroyed.

Parameters:

color

The color that this bitmap is indicated to use.