VCF::Image

VCF::Image Class Reference

The Image class is an abstract class that defines how you can work with and manipulate an image. More...

#include <vcf/GraphicsKit/Image.h>

Inheritance diagram for VCF::Image:


Public Types
typedef uint32	ImageDescriptor
enum	ImageType { itColor = 0x4, itGrayscale = 1 }
	This indicates the type of image. More...
enum	ImageChannelSize { ics8Bit = 0x08, ics16Bit = 0x10, ics32Bit = 0x20 }
	This indicates the size of each channel. More...
enum	ImageChannelType { ictInteger = 0, ictFloatingPoint = 1 }
enum	PixelLayoutOrder { ploRGBA, ploBGRA, ploARGB, ploABGR }
Public Member Functions
virtual	~Image ()
virtual ImageType	getType () const =0
	returns the type of image that this Image instance represents.
virtual ImageChannelSize	getChannelSize () const =0
	returns the number of bits each channel value represents.
virtual ImageChannelType	getChannelType () const =0
	returns whether the values for a channel are integer based or floating point based.
virtual PixelLayoutOrder	getPixelLayoutOrder () const =0
	returns the pixel layout order.
virtual void	setSize (const uint32 &width, const uint32 &height)=0
virtual uint32	getWidth ()=0
virtual uint32	getHeight ()=0
virtual void	addImageSizeChangedHandler (EventHandler *handler)=0
virtual void	removeImageSizeChangedHandler (EventHandler *handler)=0
virtual void	beginDrawing ()=0
	Call this method before calling getImageContext() to "lock" the images pixels and ensure that the GraphicsContext returns is properly sycnhed with the image's data.
virtual void	finishedDrawing ()=0
virtual GraphicsContext *	getImageContext ()=0
	This retreives a graphics context for drawing on.
virtual Color *	getTransparencyColor ()=0
	returns the color that is used to blend with the contents of a GraphicsContext when the Image is drawn.
virtual void	setTransparencyColor (Color *transparencyColor)=0
virtual bool	isTransparent ()=0
	Indicates whether or not the Image is using a transparent color.
virtual void	setIsTransparent (const bool &transparent)=0
virtual void *	getData ()=0

Detailed Description

The Image class is an abstract class that defines how you can work with and manipulate an image.

An image provides access to information such as the pixel layout, the number of color channels in the image, the number of bits in each channel, and whether or not the channel data is floating point or integer based. You can get or set the height or width of an image. You can manipulate the bits of the image as well. Setting the size will destroy any existing data in the image.

Image bits are manipulated through the ImageBits class. Each image has an ImageBits instance - the ImageBits holds a pointer to the buffer of data for the image. Depending on the system the buffer may be allocated by the VCF or it may be allocated by the platform. In other words, *don't* reallocate or delete this memory - it's not your's to play with! Feel to modify the pixel values to your heart's content though.

Image* img = //... get the image from somewhere

SysPixelType* pixels = img->getImageBits()->pixels_;
//assume a 4 color channel image
int sz = img->getHeight() * img->getWidth();
for (int i=0;i<sz;i++ ) {
    pixels[i].b = //...determine some cool blue value
    pixels[i].g = //...determine some cool green value
    pixels[i].r = //...determine some cool red value
    pixels[i].a = //...determine some cool alpha value
}

Each platform defines a specific type of SysPixelType. For example on Win32 it's defined as BGRAPixel<unsigned char>, which means that each pixel type is laid out in blue, green, red, alpha order, and each unit (of b,g,r,a) is an unsigned char (8 bits). By default, the ImageBits data uses this as it unit of storage in it's buffer.

To support AGG integration, the ImageBits has a renderBuffer_ member. You can initialize this like so :

img->getImageBits()->attachRenderBuffer( img->getWidth(), img->getHeight() );

Once initialized, you can use the render buffer in AGG operations (see http://www.antigrain.com/doc/index.html for more on AGG).

Unlike many of the other classes in the VCF, the Image class does not use a peer. Instead a concrete platform implementation is provided for each platform the VCF is ported to. So what you have is (on Win32, for example):

 Image
  |
  +--- AbstractImage
               |
               +--- Win32Image

Thus any instance of an Image that you deal with on the Win32 platform is ultimately a Win32Image instance. The AbstractImage is used to implement the basic housekeeping methods that are almost certainly guaranteed to be the same no matter the platform. The rest are then implemented in the concrete platform class.

Part of the idea behind the ImageBits class is to support a number of different image types. The idea being that we would have 4 channel color images, or 1 channel grey scale images, with potentially different channel sizes and pixel layout order. This is currently accomplished through the use of templates.

Note:: Currently while we have the potential to support grey scale images, we do not in practice actually do so yet. Nor do we fully support alpha blending - we do have the data there, we just don't make any use of it yet.

We do support a *sort* of transparency. The image has ability to set a transparency color, and then toggle whether or not this should be used (see Image::setTransparencyColor() and Image::setIsTransparent() ) .

Drawing images is done by creating an image and then calling the various image drawing methods on the GraphicsContext.

Drawing an image (on Win32) means we take a couple of things into consideration:

1) do we have a current transform in the GraphicsContext that is not an identity set? An identity set means that nothing needs to be transformed.

2) is the image transparent (Image::isTransparent() returns true)?

If the current transform is *not* "default" i.e. it's an identity set, then we do the more complex code that uses AGG to transform the image and then blend it with the underlying bits that belong to the graphics context HDC.

If the transform is default then we create a sub image and transfer whatever pixels we need that are within our image bounds rect. Then if the image is transparent we execute some insane code that uses a 1 bit mask to clear out, or render invisible (using extra HBITMAP's and ROP code magic) and pixels in the image that correspond to the image's transparent color. So if an image has it's transparent color set to "green" then any green pixels in the image will become invisible and the underlying pixels of the graphics context will show through.

Member Typedef Documentation

typedef uint32 VCF::Image::ImageDescriptor

Member Enumeration Documentation

enum VCF::Image::ImageChannelSize

This indicates the size of each channel.

Enumerator:

ics8Bit

ics16Bit

ics32Bit

enum VCF::Image::ImageChannelType

Enumerator:

ictInteger

ictFloatingPoint

enum VCF::Image::ImageType

This indicates the type of image.
An image may be either Color (this is the default) or Grayscale. Color images have four channels, grayscale images have 1. The precise value of the enum is the number of channels the image has. Thus itGrayscale is 1 for one channel, and itColor is 4 for 4 channels.
Enumerator:

itColor Indicates a Color image with four channels.

itGrayscale Indicates a Grayscale image with one channel.

enum VCF::Image::PixelLayoutOrder

Enumerator:

ploRGBA

ploBGRA

ploARGB

ploABGR

Constructor & Destructor Documentation

virtual VCF::Image::~Image ( ) [inline, virtual]

Member Function Documentation

virtual void VCF::Image::addImageSizeChangedHandler ( EventHandler * handler ) [pure virtual]

Implemented in VCF::AbstractImage.

virtual void VCF::Image::beginDrawing ( ) [pure virtual]

Call this method before calling getImageContext() to "lock" the images pixels and ensure that the GraphicsContext returns is properly sycnhed with the image's data.

Implemented in VCF::GTKImage, VCF::OSXImage, VCF::Win32Image, VCF::Win32GrayScaleImage, and VCF::XCBImagePeer.

virtual void VCF::Image::finishedDrawing ( ) [pure virtual]

Implemented in VCF::GTKImage, VCF::OSXImage, VCF::Win32Image, VCF::Win32GrayScaleImage, and VCF::XCBImagePeer.

virtual ImageChannelSize VCF::Image::getChannelSize ( ) const [pure virtual]

returns the number of bits each channel value represents.
For example, by default, on Win32 systems, an Image is a full color RGBA image, with each value of a channel taking 8 bits, thus a single of pixel of this type of image takes up 32 bits - 4 channels with each channel component 8 bits in size.
Returns:
the channel's component size. Can be one of the following values:

Image::ics8Bit - each channel component is 8 bits in sizem, thus the numerical value of this enum is 8.

Image::ics16Bit - each channel component is 8 bits in sizem, thus the numerical value of this enum is 16.

Image::ics32Bit - each channel component is 8 bits in sizem, thus the numerical value of this enum is 32.

The last two types (Image::ics16Bit and Image::ics32Bit) are typically used for high end imaging.
Implemented in VCF::AbstractImage.

virtual ImageChannelType VCF::Image::getChannelType ( ) const [pure virtual]

returns whether the values for a channel are integer based or floating point based.

Returns:
ImageChannelType the image channel's value type. Can be one of

Image::ictInteger - the value of a channel is integer based. It's min and max values can be expressed by ImageBits::Traits::minVal() and ImageBits::Traits::maxVal() respectively. Typically this is a value between 0 and 2^{getChannelSize()} (inclusive).

Image::ictFloatingPoint - the value of a channel is integer based. It's min and max values can be expressed by ImageBits::Traits::minVal() and ImageBits::Traits::maxVal() respectively. Typically this is a value in the range of 0.0 and 1.0 inclusive.

Implemented in VCF::AbstractImage.

virtual void* VCF::Image::getData ( ) [pure virtual]

Implemented in VCF::AbstractImage.

virtual uint32 VCF::Image::getHeight ( ) [pure virtual]

Implemented in VCF::AbstractImage.

virtual GraphicsContext* VCF::Image::getImageContext ( ) [pure virtual]

This retreives a graphics context for drawing on.
Any drawing performed on the graphics context will be reflected in the internal pixel data of the image. On some platforms this may be "instantaneous" because the pixel data of the image is directly linked to the GraphicsContext (i.e. Win32), while on other platforms the drawing on the GraphicsContext needs to be "flushed" back to the images pixels. Because of this, you must call beginDrawing() before calling getImageContext(), and call finishedDrawing() when you're done with the GraphicsContext. Concrete implemententations of this class will transfer the image's contents to the GraphicsContext for beginDrawing(), finishedDrawing() will update the image's data due to any changes in the GraphicsContext. To ensure that you call these functions correctly, use the ImageContext class. An example:
Image* image = getImage(); //get an image from somewhere //new code block... { ImageContext gc = image; //the ImageContext automatically calls beginDrawing() gc->rectangle( 20, 20, 400, 60 ); gc->strokePath(); } // the ImageContext destructor calls finishedDrawing() for you

See also:
ImageContext

Implemented in VCF::AbstractImage.

virtual PixelLayoutOrder VCF::Image::getPixelLayoutOrder ( ) const [pure virtual]

returns the pixel layout order.
This explains how the individual color components of each of the color channels are laid out.
Returns:
PixelLayoutOrder the binary layout order of a single pixel value. Can be one of

Image::ploRGBA - indicates the Red value is in the MSB position, followed by Green, Blue and finally Alpha values. In code it might look like this for an Image with integer based 8 bit color channels
uint32 pixelColor = (redVal << 24) | (greenVal << 16) | (blueVal << 8) | (alphaVal);
Extracting the values from a single pixel color would be:
redVal = (pixelColor & 0xFF000000) >> 24; greenVal = (pixelColor & 0x00FF0000) >> 16; blueVal = (pixelColor & 0x0000FF00) >> 8; alphaVal = (pixelColor & 0x000000FF);

Image::ploBGRA - indicates the Blue value is in the MSB position, followed by Green, Red and finally Alpha values. In code it might look like this for an Image with integer based 8 bit color channels
uint32 pixelColor = (blueVal << 24) | (greenVal << 16) | (redVal << 8) | (alphaVal);
Extracting the values from a single pixel color would be:
blueVal = (pixelColor & 0xFF000000) >> 24; greenVal = (pixelColor & 0x00FF0000) >> 16; redVal = (pixelColor & 0x0000FF00) >> 8; alphaVal = (pixelColor & 0x000000FF);

Image::ploARGB - indicates the Alpha value is in the MSB position, followed by Red, Green and finally Blue values. In code it might look like this for an Image with integer based 8 bit color channels
uint32 pixelColor = (alphaVal << 24) | (redVal << 16) | (greenVal << 8) | (blueVal);
Extracting the values from a single pixel color would be:
alphaVal = (pixelColor & 0xFF000000) >> 24; redVal = (pixelColor & 0x00FF0000) >> 16; greenVal = (pixelColor & 0x0000FF00) >> 8; blueVal = (pixelColor & 0x000000FF);
This is typically the way it would be stored on a linux based port of VCF.

Image::ploABGR - indicates the Alpha value is in the MSB position, followed by Blue, Green and finally Red values. In code it might look like this for an Image with integer based 8 bit color channels
uint32 pixelColor = (alphaVal << 24) | (blueVal << 16) | (greenVal << 8) | (redVal);
Extracting the values from a single pixel color would be:
alphaVal = (pixelColor & 0xFF000000) >> 24; blueVal = (pixelColor & 0x00FF0000) >> 16; greenVal = (pixelColor & 0x0000FF00) >> 8; redVal = (pixelColor & 0x000000FF);
This is typically the way it would be stored on a Win32 based port of VCF.

Implemented in VCF::AbstractImage.

virtual Color* VCF::Image::getTransparencyColor ( ) [pure virtual]

returns the color that is used to blend with the contents of a GraphicsContext when the Image is drawn.
Only used when the Image is set to Transparent
Implemented in VCF::AbstractImage.

virtual ImageType VCF::Image::getType ( ) const [pure virtual]

returns the type of image that this Image instance represents.
The integer value also indicates the number of color channels the Image has. Currently there are only 2 types, full color 4 channel RGBA images, and 1 channel grayscale images.
Returns:
ImageType the value that represent the images type. The values have the follwing meanings:

Image::itColor - indicate a full color image with red, green, blue, and alpha channels present. The integer value of this is 4 and can be used in operations to determine the total data size of the image, for example.

Image::itGrayscale - indicates a grayscale image with a single channel. The numerical value of this is 1.

Implemented in VCF::AbstractImage.

virtual uint32 VCF::Image::getWidth ( ) [pure virtual]

Implemented in VCF::AbstractImage.

virtual bool VCF::Image::isTransparent ( ) [pure virtual]

Indicates whether or not the Image is using a transparent color.

Returns:
bool if this is true then the Image is transparent and the contents of the underlying GraphicsContext will show through wherever a pixel in the image is found that is the transparency color

Implemented in VCF::AbstractImage.

virtual void VCF::Image::removeImageSizeChangedHandler ( EventHandler * handler ) [pure virtual]

Implemented in VCF::AbstractImage.

virtual void VCF::Image::setIsTransparent ( const bool & transparent ) [pure virtual]

Implemented in VCF::AbstractImage.

virtual void VCF::Image::setSize ( const uint32 & width,

const uint32 & height

) [pure virtual]

Implemented in VCF::AbstractImage, VCF::GrayScaleImage, VCF::OSXImage, VCF::Win32Image, and VCF::Win32GrayScaleImage.

virtual void VCF::Image::setTransparencyColor ( Color * transparencyColor ) [pure virtual]

Implemented in VCF::AbstractImage.

The documentation for this class was generated from the following file:

vcf/GraphicsKit/Image.h