Methods Index

CImage

Heritage

Description

CImage encapsulates the usage of XVT portable images. XVT's portable images feature lets your application manipulate, display, and print bitmapped graphic images in several different file formats. You can create images on the platform(s) of your choice and easily move them to other platforms.

Your application can use images created on different GUI environments because XVT-Power++ methods can read several different image file formats. XVT supports the following formats:

MS-Windows and OS/2 BMP
Macintosh PICT (on the Macintosh only)
X Window System xpm
X Window System xbm

Your application does not have to provide special code for each image format. When the files are read, they are converted (in memory) into an XVT image. XVT's stored images are compatible with the MS-Windows BMP format.

Because the native graphics systems of the XVT-supported platforms use different standard formats, XVT has established the MS-Windows BMP format as the portable image file format for all XVT products. The XVT Portability Toolkit can display MS-Windows BMP images on any supported platform, automatically making any necessary conversions.

Note: Reading and writing of Macintosh PICT formats is supported on the Macintosh only.

Color

All XVT graphics, image, and pixmap operations use a red-green-blue (RGB) color model.

Images and pixmaps use one of three color formats:

Monochrome format
Indexed format
True color format

The formats differ in the number of colors displayable and in the amount of memory used by one pixel. The following table summarizes the three formats:

Format Displayable Colors Memory per Pixel
Monochrome Two (black and white) One bit
Indexed Up to 256 One byte
True color Up to 16 million One COLOR value (32 bits; 8 are not currently used)


Format	Displayable Colors	Memory per Pixel
Monochrome	Two (black and white)	One bit
Indexed	Up to 256	One byte
True color	Up to 16 million	One `COLOR` value (32 bits; 8 are not currently used)

Color Look-Up Tables

The indexed color mode uses a color look-up table (or "CLUT"). Each pixel uses one byte as an index into the look-up table. A CLUT contains up to 256 COLOR entries. As a result, an image or pixmap that uses indexed color can contain up to 256 different colors simultaneously.

Image Format

The XVT Portability Toolkit's XVT_IMAGE_FORMAT enumerated type defines four values for the color formats available for images:

XVT_IMAGE_* values: Format:
XVT_IMAGE_NONE No color
XVT_IMAGE_CL8 Indexed color
XVT_IMAGE_RGB True color
XVT_IMAGE_MONO Monochrome


XVT_IMAGE_* values:	Format:
`XVT_IMAGE_NONE`	No color
`XVT_IMAGE_CL8`	`Indexed color`
`XVT_IMAGE_RGB`	`True color`
`XVT_IMAGE_MONO`	`Monochrome`

Note: XVT_IMAGE_CL8 is the only format that has a color look-up table.

Image Coordinates

A CImage always has an origin of 0,0; the CPoint and CRect used by a CImage are relative to 0,0.

Reading and Writing Model

The XVT-Power++ provides methods for reading and writing several different common image file formats as well as I/O stream objects. The writing methods store the specified image file or I/O stream object in a file format compatible with the MS-Windows BMP format. However, on the Macintosh you can read and write to Macintosh PICT files.

Usage

The following examples illustrate several uses of CImage:

Constructing an Image

CImage anImage("file.bmp");
				// from a file
CImage anImage(myData->itsXVTStream);
				// from XVT_IOSTREAM
CImage anImage(XVT_IMAGE_CL8, 100, 100);
				// width=height=100
CImage anImageCopy(anOriginalImage);
				// from an existing image
CImage anImage(aPiXMap); 
				// from an XVT_PIXMAP
CImage anImage = anExistingImageID;
				// will consume XVT_IMAGE

CImage anImage is an empty constructor. It does not create an image, so it is not valid. Use this constructor when reading a file of an unknown type, like this:

struct Tools {
CImage itsImage;
long itsCommands[];
};
Tools aToolBar;

 ... determine file ...

aToolBar.itsImage.Read("known_file.macpict");

The following code illustrates the exact usage of the CImage anImage constructor to get a valid image:

anImage.Read(...);
anImage.ReadIOStream(...);
anImage = anImage2;
anImage = imageID;

Manipulating an Image

COLOR aCol = anImage.GetCLUTEntry(12);
anImage.SetPixel(CPoint(5, 5), COLOR_RED);

Reading or Writing an Image

Images remember how they were read, so writing them is simple. For example:

anImage.Write();
anImage2.WriteIOStream();

If you read or reread the image after creation, the I/O information is reset for writing.

You can also write images to an alternate format. For example:

anImage.Write("file.bmp");
anImage2.WriteIOStream(anIOStream);

If you try to write an image either without reading it or without specifying an output name or stream, the process fails and returns an error. For example:

CImage anImage(aPixmap);
BOOLEAN isOk = anImage.Write();
						// error! does not know what
						// to write! Returns FALSE
BOOLEAN isOk = anImage.Write("file.bmp");
						// OK

Enums

PWR_IMAGE_FILETYPE

DEFAULT BMP; use on all platforms
MACPICT Macintosh PICT; use only on the Macintosh


`DEFAULT`	BMP; use on all platforms
`MACPICT`	Macintosh PICT; use only on the Macintosh

Protected Data Members

XVT_IMAGE itsImageId; The image ID
CImageIO *itsIO; The image's I/O implementation


`XVT_IMAGE`	`itsImageId;`	The image ID
`CImageIO`	`*itsIO;`	The image's I/O implementation

Public Methods

Constructor, Destructor, and Initializer Methods

CImage();

An empty constructor. This method does not create an image, so it is not valid. Use this empty constructor when reading a file (see "Usage"

CImage(XVT_IMAGE_FORMAT theFormat, short theWidth, short theHeight);

A constructor, which creates a CImage object of specified format (theFormat), width (theWidth), and height (theHeight).

CImage(const CStringRW &theFileName);

A constructor that creates a image from a file specified by theFileName. The file can be an xbm, xpm, BMP, or Macintosh PICT.

CImage(XVT_IOSTREAM theIOStream);

A constructor that creates an image object from the I/O stream object specified by theIOStream. Keep in mind that the created image references the I/O stream, and you are responsible for maintaining the integrity of that stream.

CImage(XVT_IMAGE theImageId);

A constructor that creates an image object from the passed-in theImageId. The XVT Portability Toolkit XVT_IMAGE object is not modified.

CImage(int theResId);

A constructor that creates an image object from the URL resource ID specified by theResId.

CImage(XVT_PIXMAP thePixmap);

A constructor that creates an image object from an XVT Portability Toolkit XVT_PIXMAP object.

CImage(const CImage &theImage);

A copy constructor, which duplicates the image object specified by theImage.

CImage & operator= (const CImage &theImage);

An assignment operator, which copies the attributes of theImage.

~CImage();

The destructor, which deletes the image object.

Helper Operators

operator XVT_IMAGE (void) const;

A conversion operator, which returns a reference to an image. Given a CImage object, this operator gets an XVT Portability Toolkit XVT_IMAGE object. This operator is used with XVT Portability Toolkit image functions. Since this method returns a direct reference into internal information, use this method carefully. Specifically, do not use this method in cases in which the calling method might destroy or alter the handle.

CImage& operator= (XVT_IMAGE theImageId);

An assignment operator, which consumes an XVT Portability Toolkit image.

Read/Write Methods

BOOLEAN Read(const CStringRW &theFile);

Reads an image from a file. You can then write the file as the same file, as a different file, as an XVT_IOSTREAM, or, on the Macintosh only, as a Macintosh PICT.

BOOLEAN ReadIOStream(XVT_IOSTREAM theIOStream);

Reads an image from an I/O stream. You can then write the I/O stream as the same I/O stream, as a different I/O stream, as a file, or, on the Macintosh only, as a Macintosh PICT.

BOOLEAN Write(
	const CStringRW &theFile		= NULLString,
	PWR_IMAGE_FILETYPE theType	= DEFAULT);

Writes (saves) an image to a file independent of how the image was read. Images remember how they were read, so writing them is simple. You can write a newly-created image, an image created from resources (URL), or an image created from a file. However, if you try to write an image either without reading it or without specifying an output name or stream, the process fails and returns FALSE.

BOOLEAN WriteIOStream(
	XVT_IOSTREAM theIOStream		= NULL,
	PWR_IMAGE_FILETYPE theType	= DEFAULT);

Writes (saves) an image to an I/O stream independent of how the image was read. Images remember how they were read, so writing them is simple. You can write a newly-created image, an image created from resources (URL), or an image created from a file. However, if you try to write an image either without reading it or without specifying an output name or stream, the process fails and returns FALSE.

State Methods

void FillRect(COLOR theColor, const CRect &theFrame);

Fills a rectangular region in an image with the color value specified by theColor. If there is no color in the image that matches the fill color exactly, the nearest color is used. If any portion of theFrame lies outside the boundary of the image, the portion(s) will be clipped.

void Transfer(const CRect &theDestFrame,
	const CImage &theSourceImage, 
	const CRect &theSourceFrame);

Copies the contents of a rectangular region in the source image into a rectangular region in the destination image. If theSourceFrame and theDestFrame are not congruent, this method translates and scales the source region as necessary to fit it into the destination frame. Any parts of the source or destination rectangles that fall outside of the bounds of their respective containers are ignored.

void TransferPixmap(const CRect &theDestFrame, 
	XVT_PIXMAP thePixmap, 
	const CRect &theSourceFrame);

Copies the contents of a rectangular region in the source pixmap into a rectangular region in the destination image. Colors in the source pixmap are mapped into the closest matching colors in the destination image. If theSourceFrame and theDestFrame are not congruent, this function translates and scales the source region as necessary to fit it into the destination rectangle. Any parts of the source or destination rectangles that fall outside of the bounds of their respective containers are ignored.

void SetPixel(const CPoint &theLoc, COLOR theColor);

Sets the color value of a pixel in an image. theLoc is the location of the pixel relative to 0,0. This method handles the arithmetic for the array addressing and converting colors to different color formats.

COLOR GetPixel(const CPoint &theLoc) const;

Returns the color value of a pixel in an image. theLoc is the location of the pixel relative to 0,0. This method handles the arithmetic for the array addressing and converting colors to different color formats.

XVT_IMAGE_FORMAT GetFormat(void) const;

Returns the color format of an image.

void GetDimensions(short *theWidth,
	short *theHeight) const;

Returns the dimensions of an image in the variables pointed to by theWidth and theHeight.

short GetWidth(void) const;

Returns only the width of an image.

short GetHeight(void) const;

Returns the only the height of an image object, in the variables pointed to by theHeight.

COLOR GetCLUTEntry(short theIndex) const;

Retrieves the color entry in an image's look-up table. theIndex is the color entry to retrieve. This method is useful only for images with an XVT Portability Toolkit color format of XVT_IMAGE_CL8, since the other formats do not have look-up tables.

short GetNumColors(void) const;

Returns the number of colors in an image's look-up table. This method is useful only for images with an XVT Portability Toolkit color format of XVT_IMAGE_CL8, since the other formats do not have look-up tables.

void GetResolution(long *theHRes, long *theVRes) const;

Gets the horizontal and vertical resolution of an image in pixels.

long GetHRes(void) const;

Gets only the horizontal resolution of an image in pixels.

long GetVRes(void) const;

Gets only the vertical resolution of an image in pixels.

void SetCLUTEntry(short theIndex, COLOR theColor);

Sets the color value of an entry in a color look-up table. theIndex must be between 0 and 255 (inclusive). This method does not alter the number of colors used by the image, nor does it alter the image itself. The method is useful only with images with the XVT Portability Toolkit color format XVT_IMAGE_CL8, since the other formats do not have look-up tables.

void SetNumColors(short theNum);

Sets the number of colors used by an image. The number set by this method affects how colors are mapped when the image is transferred to a window or pixmap, or from a pixmap. The color-mapping process constructs color tables to map colors to/from the image's colors, but only for the number of colors set by this function. This method is useful only with images with an XVT Portability Toolkit color format of XVT_IMAGE_CL8, since the other formats do not have look-up tables.

void SetResolution(long theHRes, long theVRes);

Sets the horizontal and vertical resolution of an image in pixels.

void SetHRes(long theHRes);

Sets only the horizontal resolution of an image in pixels.

void SetVRes(long theVRes);

Sets only the vertical resolution of an image in pixels.

[Classes] [Prev] [Next] [Methods]

support@xvt.com