IGImagePixelAccessor

IGImagePixelAccessor facilitates pixel-level image modifications. This class provides a transient, convenience-oriented pixel-level accessor object that is created on the stack. It provides functions that access and modify the pixels of the referenced image. It should not be copied, assigned or streamed.


IGImagePixelAccessor - Member Functions and Data by Group

Constructors & Destructor

Use these functions to create and destroy a pixel image accessor object. The only way to create a pixel image accessor object is to specify an existing image of class IGImage. Other constructors are currently disabled.


[view class]
~IGImagePixelAccessor
public:
~IGImagePixelAccessor()
Virtual destructor. Destroys the pixel-image accessor object.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
IGImagePixelAccessor
Constructs a pixel image accessor object for the given, referenced image.
public:
IGImagePixelAccessor(const IGImage& referencedImage)

referencedImage
A reference to the image of class IGImage to be accessed.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Writing Images to and Reading Them from Files

Use these functions to read and write images to and from files using the given image format and file name.


[view class]
loadFromFile
public:
static IBitmapHandle loadFromFile( const IString& imageFilename, EImageFormat imageFormat = kUNKNOWN, EDitherType ditherStyle = kNoDither )
Reads the image from the given file using the specified image format and dithering style and returns a reference to that pixel image.

imageFilename
The file name string.
imageFormat
The image format.
ditherStyle
The dithering style.

Return
A reference to this image.

Exception

Through

a graphic exception if failing to create the image.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
writeToFile
Outputs the image into a file using the specified filename and format.
public:
static void writeToFile( const IString& imageFilename, EImageFormat imageFormat, IBitmapHandle bmp )
This function assumes an inherent 8-bit format for GIF files. A runtime error occurs if you attempt to write a GIF file using this function while specifying a format other than 8 bits per pixel.

imageFilename
The filename.
imageFormat
The image format.
bmp
The bitmap handle of the image.

Return
True if image is successfully written to file.

Exception

Through

a graphic exception if failing to write to a file.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Getting and Setting Pixel Values

Use the functions in this group to get or set the value of a pixel.


[view class]
pixel
public:
bool pixel( const IGPoint2D&, IBaseColor& valueOfThePixelReturned ) const
Returns the value of the specified pixel, given the pixel position, and returns FALSE if the pixel is positioned outside the image bounds.

const IGPoint2D&
The position of the pixel.
IBaseColor
The base color of the pixel.
valueOfThePixelReturned
The returned value of the pixel.

Return
FALSE if the position is outside of the image bounds; otherwise, TRUE.

Exception

Fails

a parameter assertion if the position is outside the image bounds.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setPixel
public:
void setPixel( const IGPoint2D&, const IBaseColor& valueOfThePixel )
Sets the value of the specified pixel using the given pixel position, base color, and value.

IGPoint2D
A constant reference to the position of the pixel.
IBaseColor
A constant reference to the base color.
valueOfThePixel
The value to be copied.

Exception

Fails

a parameter assertion if the position is outside the image bounds.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Getting and Setting the Pixel Row

Use the functions in this group to get or set the value of a pixel row.


[view class]
pixelRow
Gets the values of a row of pixels.
public:
bool pixelRow( const IGPoint2D&, IRGBAColorArray& valueOfThePixelsReturned ) const
To identify the row of pixels whose values you want to obtain, this function uses the starting point referred to by the IGPoint2D parameter and the row's length whose size is given by the IRGBColorArray.

IGPoint2D
A constant reference to the starting point of the row whose pixel values you want to obtain.
IRGBColorArray
A reference to the array giving the length of the row.
valueOfThePixelsReturned
The returned pixel values.

Return
FALSE if the row is clipped; otherwise TRUE.

Exception

Fails

a parameter assertion if the row is outside the image bounds.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setPixelRow
Sets the values of a row of pixels.
public:
void setPixelRow( const IGPoint2D&, const IRGBAColorArray& valueOfThePixels )
The function uses the given value for the pixels, and the row's starting point and length.

IGPoint2D
A constant reference to the starting point of the row.
IRGBColorArray
An array that gives the length, or size, of the row of pixels.
valueOfThePixels
The values to be copied.

Return
FALSE if the row is clipped; otherwise, TRUE.

Exception

Fails

a parameter assertion if the row is outside the image bounds.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Loading the Image from a File and Writing It Out to One

Use these functions to load or write IGImagePixelAccessor objects to or from a specified file.


[view class]
loadImageFromFile
public:
static IGImage* loadImageFromFile( const IString& imageFilename )
Loads the image from the given file.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
writeImageToFile
public:
static void writeImageToFile( const IString& imageFilename, EImageFormat imageFormat, IGImage* )
Writes the IGImagePixelAccessor object out to the specified file.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


IGImagePixelAccessor - Enumerations


[view class]
EDitherType
enum EDitherType { kNoDither, 
                   kErrorDither, 
                   kHalftoneDither }
Defines various image dither methods.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
EImageFormat
enum EImageFormat { kUNKNOWN=-2, 
                    kCOMPRESS=-1, 
                    kBMP=0, 
                    kGIF=1, 
                    kJPG=2, 
                    kXPM=3 }
Defined various type of image formats.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

OS/2 Considerations

The kJPG image format is not supported.

Windows Considerations

The kJPG image format is not supported.


IGImagePixelAccessor - Inherited Member Functions and Data

Inherited Public Functions

Inherited Public Data

Inherited Protected Functions

Inherited Protected Data