NovaTK::Image Class Reference

List of all members.


Detailed Description

This is a client-side image. An image is not a widget and thus can be drawn on any window since it has no windows of its own. This class allows direct access to the image data which allows for more than static images. Direct access to the image data allows for it to be used as a graphical output medium.
Note:
While this class tries to make image manipulation logical and simple, if you need to directly manipulate the raw image data you MUST take into account the data format used by the user's machine. Unfortunately, NovaTK cannot present a consistent data format across all platforms and configurations since this requires converting between NovaTK's format and the platform's format for every change which would make image manipulation slow and defeat the advantages of direct access. There are two aspects of the format you must consider: the scanline (The length of a row of the image in bytes) and the byte order(the pixel format).
See also:
ImageView

GetScanline

GetFormat

DataFormat

NovaTK::Util::CalcImageScanline


Public Types

enum  DataFormat {
  RGB, BGR, ARGB, BGRA,
  ARGB_Premultiplied, BGRA_Premultiplied, Bitmap
}

Public Member Functions

NOVATKAPI NStatus Create (uint c_width, uint c_height)
NOVATKAPI NStatus Create (uint c_width, uint c_height, uint depth)
NOVATKAPI void Destroy ()
NOVATKAPI void CopyData (const unsigned char *rgbData)
NOVATKAPI void Draw (Window *window, uint dest_x, uint dest_y, const Rectangle &src) const
NOVATKAPI void Draw (Window *window, uint dest_x, uint dest_y) const
NOVATKAPI ImageGetCopy () const
NOVATKAPI void Resize (uint r_w, uint r_h)
NOVATKAPI NStatus Clear (uint color)
NOVATKAPI NStatus PutPixel (uint x, uint y, uint color)
NOVATKAPI NStatus PutLine (uint src_x, uint src_y, uint dest_x, uint dest_y, uint color)
NOVATKAPI NStatus PutRectangle (const Rectangle &r, uint color)
NOVATKAPI NStatus PutImage (Image *src_image, const Rectangle &src, uint dst_x, uint dst_y, char *colorkey=0)
NOVATKAPI DataFormat GetFormat () const
NOVATKAPI uint GetScanline () const
NOVATKAPI uint GetDepth () const
NOVATKAPI void GetChannelShifts (uint &redShift, uint &greenShift, uint &blueShift, uint &alphaShift)
NOVATKAPI void GetChannelMasks (ulong &redMask, ulong &greenMask, ulong &blueMask, ulong &alphaMask)
uint GetWidth () const
uint GetHeight () const
unsigned char * GetDataPtr () const
NOVATKAPI NStatus Convert (const unsigned char *srcData, DataFormat orig_format)

Member Enumeration Documentation

Identifies the different pixel formats of the raw image data.

Enumerator:
RGB  Byte Format (3 bytes per pixel): RED, GREEN, BLUE (RRGGBB)
BGR  Byte Format (3 bytes per pixel): BLUE, GREEN, RED (BBGGRR)
ARGB  Byte Format (4 bytes per pixel): ALPHA, RED, GREEN, BLUE (0xAARRGGB)
BGRA  Byte Format (4 bytes per pixel): BLUE, GREEN, RED, ALPHA (0xBBGGRRAA)
ARGB_Premultiplied  Byte Format (4 bytes per pixel): ALPHA, RED, GREEN, BLUE. The premultiplied format uses the same byte order as ARGB, however the channels red, green and blue are each multiplied by the alpha channel where the alpha value is in the range 0.0-1.0. This is achieved by multiplying those channels by the alpha channel divided by 255. Another way to express this format is (A, AR, AG, AB). This format speeds up the alpha blending of images by eliminating the need to multiply the pixels by the alpha value before hand.
BGRA_Premultiplied  Byte Format (4 bytes per pixel): BLUE, GREEN, RED, ALPHA. The premultiplied format uses the same byte order as BGRA, however the channels red, green and blue are each multiplied by the alpha channel where the alpha value is in the range 0.0-1.0. This is achieved by multiplying those channels by the alpha channel divided by 255. Another way to express this format is (AB, AG, AR, A). This format speeds up the alpha blending of images by eliminating the need to multiply the pixels by the alpha value before hand.
Bitmap  Byte Format (1 BIT per pixel).


Member Function Documentation

NStatus NovaTK::Image::Create ( uint  c_width,
uint  c_height 
)

Initializes the image to the dimensions given and clears it to black.

Returns:
NOVATK_SUCCESS upon success otherwise returns NOVATK_ERROR_GENERAL_FAILURE.

NStatus NovaTK::Image::Create ( uint  c_width,
uint  c_height,
uint  depth 
)

Initializes the image of the specified depth to the dimensions given and clears it to black.

Returns:
NOVATK_SUCCESS upon success otherwise returns NOVATK_ERROR_GENERAL_FAILURE.

void NovaTK::Image::Destroy (  ) 

Destroys the data and freeing all memory allocated by the object.

void NovaTK::Image::CopyData ( const unsigned char *  rgbData  ) 

Copies the data from rgbData without resizing the image. The data should be in the same format of Image and should be of exactly the same dimensions.

Parameters:
rgbData - The raw image data to copy over this object's data.
See also:
GetFormat

void NovaTK::Image::Draw ( Window window,
uint  dest_x,
uint  dest_y,
const Rectangle src 
) const

Draws the specified region of the image on the window at the specified location.

Parameters:
window - The window on which this image will be drawn.
dest_x - The location upon the window where the left edge of the image will be drawn.
dest_y - The location upon the window where the top edge of the image will be drawn.
src - Defines the region of the image which will be drawn at (dest_x, dest_y).

void NovaTK::Image::Draw ( Window window,
uint  dest_x,
uint  dest_y 
) const

Draws the entire image on the window at the specified location.

Parameters:
window - The window on which this image will be drawn.
dest_x - The location upon the window where the left edge of the image will be drawn.
dest_y - The location upon the window where the top edge of the image will be drawn.

Image * NovaTK::Image::GetCopy (  )  const

Creates a new image that is a copy of this image.

Returns:
A pointer to the copy.

void NovaTK::Image::Resize ( uint  r_w,
uint  r_h 
)

Resizes the image to the dimensions specified. Note that this applies to the image data ONLY thus if original dimensions were larger then any data beyond the new dimensions will be dropped.

Parameters:
r_w New width of the image.
r_h New height of the image.

NStatus NovaTK::Image::Clear ( uint  color  ) 

Fills the image with the solid color specified.

Parameters:
color The color to fill the image with.
Returns:
NOVATK_SUCCESS upon success, NOVATK_ERROR_MEMALLOC_FAILURE if memory allocation failed, NOVATK_ERROR_OUT_OF_BOUNDS if the color specified is not valid otherwise returns NOVATK_ERROR_GENERAL_FAILURE.
See also:
NovaTK::Color

NStatus NovaTK::Image::PutPixel ( uint  x,
uint  y,
uint  color 
)

Overwrite the pixel at the specified location with a pixel of the specified color.

Parameters:
x - Horizontal position of the pixel
y - Vertical position of the pixel
color - The color of the pixel to write.
Returns:
NOVATK_SUCCESS upon success, NOVATK_ERROR_OUT_OF_BOUNDS if x or y lie outside of the image or the specified color ID does not exist otherwise returns NOVATK_ERROR_GENERAL_FAILURE.
See also:
NovaTK_Color

NStatus NovaTK::Image::PutLine ( uint  src_x,
uint  src_y,
uint  dest_x,
uint  dest_y,
uint  color 
)

Draws a line on the image from the specified source to the destination.

Parameters:
src_x - Horizontal offset of the line's source.
src_y - Vertical offset of the line's source.
dest_x - Horizontal offset of the line's destination.
dest_y - Vertical offset of the line's destination.
color - The color of the line to be drawn.
Returns:
NOVATK_SUCCESS upon success, NOVATK_ERROR_OUT_OF_BOUNDS if x or y lie outside of the image or the specified color ID does not exist otherwise returns NOVATK_ERROR_GENERAL_FAILURE.
See also:
NovaTK_Color

NStatus NovaTK::Image::PutRectangle ( const Rectangle r,
uint  color 
)

Draws a filled rectange of the dimensions specified by r at the location specified by r.

Parameters:
r Defines the location and dimensions of the rectangle.
color The color of the rectangle.
Returns:
NOVATK_SUCCESS upon success, NOVATK_ERROR_OUT_OF_BOUNDS if x or y lie outside of the image or the specified color ID does not exist otherwise returns NOVATK_ERROR_GENERAL_FAILURE.
See also:
NovaTK_Color

NStatus NovaTK::Image::PutImage ( Image src_image,
const Rectangle src,
uint  dst_x,
uint  dst_y,
char *  colorkey = 0 
)

Copies the rectangle defined by src_x, src_y, src_width and src_height of src_image to this image at the offset of dst_x and dst_y.

The parameter, colorkey, is used for transparency. It must be an array of three characters and describes a pixel value, hence the first character represents red, the second, green, and the third, blue. If colorkey is NULL, then it is ignored and the entire source image will be copied. If a colorkey is defined then any pixel matching the colorkey will not be copied.

Parameters:
src_image - The image to be copied from.
src - Specifies the region of src_image to be copied to this image.
dst_x - Specifies the horizontal offset of where the source rectangle is to be copied.
dst_y - Specifies the vertical offset of where the source rectangle is to be copied.
colorkey - Specifies the transparent pixel.
Returns:
NOVATK_SUCCESS upon success otherwise returns NOVATK_ERROR_GENERAL_FAILURE.

Image::DataFormat NovaTK::Image::GetFormat (  )  const

Returns:
The pixel format of the image.
See also:
DataFormat

uint NovaTK::Image::GetScanline (  )  const

Returns:
The width of a single row of the image data in bytes inclusive of padding. Padding is dependent upon the backend being used.

uint NovaTK::Image::GetDepth (  )  const

Returns:
The color depth of the image.

void NovaTK::Image::GetChannelShifts ( uint &  redShift,
uint &  greenShift,
uint &  blueShift,
uint &  alphaShift 
)

Obtains the shift values for each channel for the image format used by the user's platform. The shift value is the number of bits the value is shifted to the left in a 32-bit value representing the pixel value. If the image format used by the user's platform doesn't support an alpha channel the alphaShift can be ignored.

void NovaTK::Image::GetChannelMasks ( ulong &  redMask,
ulong &  greenMask,
ulong &  blueMask,
ulong &  alphaMask 
)

Obtains the masks for each channel that can be applied to a pixel which is stored in a 32 bit value (unsigned long). If the image format used by the user's platform doesn't support an alpha channel the mask returned for this channel will contain a zero value as there is no alpha channel to be obtained.

uint NovaTK::Image::GetWidth (  )  const [inline]

Returns:
The width of the image in pixels.

uint NovaTK::Image::GetHeight (  )  const [inline]

Returns:
The height of the image in pixels.

unsigned char* NovaTK::Image::GetDataPtr (  )  const [inline]

Returns:
A pointer to the raw image data.

NStatus NovaTK::Image::Convert ( const unsigned char *  srcData,
DataFormat  orig_format 
)

Converts the data from an existing image from the specified format to the format used by the user's platform and copies the resulting data to this image. Note that the dimensions of the source image and this image MUST match and that the scanline of srcData must be correct for its format. Also be aware that the correct scanline for the same image in a particular format may differ from platform to platform.

Parameters:
srcData - Pointer to the data of the source image.
orig_format - The format of srcData.
Returns:
NOVATK_SUCCESS upon success or NOVATK_ERROR_BAD_REQUEST if the requested conversion is not valid.
See also:
NovaTK::Util::CalcImageScanline


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

Generated on Sat Sep 13 22:34:19 2008 for NovaTK by  doxygen 1.5.5