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

CImage

Methods Index

Heritage
Description
Color
Color Look-Up Tables
Image Format
Image Coordinates
Reading and Writing Model
Usage
Enums
Protected Data Members
Public Methods
Constructor, Destructor, and Initializer Methods
Helper Operators
Read/Write Methods
State Methods

CImage


Heritage

Superclass: None

Subclasses: None


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:

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:

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)

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

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


Protected Data Members

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


Public Methods

Constructor, Destructor, and Initializer Methods

CImage();
CImage(XVT_IMAGE_FORMAT theFormat, short theWidth, short theHeight);
CImage(const CStringRW &theFileName);
CImage(XVT_IOSTREAM theIOStream);
CImage(XVT_IMAGE theImageId);
CImage(int theResId);
CImage(XVT_PIXMAP thePixmap);
CImage(const CImage &theImage);
CImage & operator= (const CImage &theImage);

~CImage();

Helper Operators

operator XVT_IMAGE (void) const;

CImage& operator= (XVT_IMAGE theImageId);

Read/Write Methods

BOOLEAN Read(const CStringRW &theFile);
BOOLEAN ReadIOStream(XVT_IOSTREAM theIOStream);
BOOLEAN Write(
const CStringRW &theFile = NULLString,
PWR_IMAGE_FILETYPE theType = DEFAULT);
BOOLEAN WriteIOStream(
XVT_IOSTREAM theIOStream = NULL,
PWR_IMAGE_FILETYPE theType = DEFAULT);

State Methods

void FillRect(COLOR theColor, const CRect &theFrame);
void Transfer(const CRect &theDestFrame,
const CImage &theSourceImage,
const CRect &theSourceFrame);
void TransferPixmap(const CRect &theDestFrame, 
XVT_PIXMAP thePixmap,
const CRect &theSourceFrame);
void SetPixel(const CPoint &theLoc, COLOR theColor);
COLOR GetPixel(const CPoint &theLoc) const;
XVT_IMAGE_FORMAT GetFormat(void) const;	
void GetDimensions(short *theWidth,
short *theHeight) const;
short GetWidth(void) const;
short GetHeight(void) const;
COLOR GetCLUTEntry(short theIndex) const;
short GetNumColors(void) const;
void GetResolution(long *theHRes, long *theVRes) const;
long GetHRes(void) const;
long GetVRes(void) const; 
void SetCLUTEntry(short theIndex, COLOR theColor);
void SetNumColors(short theNum);
void SetResolution(long theHRes, long theVRes);
void SetHRes(long theHRes);
void SetVRes(long theVRes);



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

support@xvt.com


Visit our online help desk for tech support

Copyright © 2009, Providence Software Solutions Inc. All rights reserved.