os::BitmapImage Class Reference
[The Syllable Graphical User Interface API]

Container for bitmap image data. More...

Inheritance diagram for os::BitmapImage:

List of all members.

Public Member Functions
	BitmapImage (uint32 nFlags=Bitmap::SHARE_FRAMEBUFFER)
	Default constructor.
	BitmapImage (const BitmapImage &cSource, uint32 nFlags=Bitmap::SHARE_FRAMEBUFFER)
	Copy constructor.
	BitmapImage (StreamableIO *pcSource, uint32 nFlags=Bitmap::SHARE_FRAMEBUFFER)
	Constructor.
	BitmapImage (const uint8 *pData, const IPoint &cSize, color_space eColorSpace, uint32 nFlags=Bitmap::SHARE_FRAMEBUFFER)
	Constructor.
virtual	~BitmapImage ()
virtual const String	ImageType (void) const
	Get object type.
virtual bool	IsValid (void) const
	Find out if the bitmap object is valid.
virtual status_t	Load (StreamableIO *pcSource, const String &cType="")
	Load bitmap from a stream (file, memory, resource etc.
virtual status_t	Save (StreamableIO *pcDest, const String &cType)
	Write bitmap to a stream.
virtual void	Draw (const Point &cPos, View *pcView)
	Draw an image to a View.
virtual void	Draw (const Rect &cSource, const Rect &cDest, View *pcView)
	Draw an image to a View.
virtual status_t	SetSize (const Point &cSize)
	Scale the bitmap.
virtual Point	GetSize (void) const
	Get bitmap size.
void	SetBitmapData (const uint8 *pData, const IPoint &cSize, color_space eColorSpace, uint32 nFlags=Bitmap::SHARE_FRAMEBUFFER)
	Set raw bitmap data.
color_space	GetColorSpace () const
	Get bitmap colour space.
virtual status_t	SetColorSpace (color_space eColorSpace)
	Set colour space.
virtual Bitmap *	LockBitmap (void)
	Lock the internal Bitmap object.
virtual void	UnlockBitmap (void)
	Unlock the internal Bitmap object.
virtual BitmapImage &	operator= (const BitmapImage &cSource)
	Copy the contents of another bitmap.
virtual View *	GetView ()
	Obtain a View for rendering into the bitmap.
virtual void	ResizeCanvas (const Point &cSize)
	Change the size of the bitmap.
virtual uint32 *	operator[] (int row)
	Direct access to pixels.
void	Sync ()
	Flush the render queue, and wait til the rendering is done.
void	Flush ()
	Flush the render queue.
virtual status_t	ApplyFilter (const Message &cFilterData)
status_t	GrayFilter (void)
	Create a greyed image.
status_t	HighlightFilter (void)
	Make the image highlighted.
status_t	AlphaToOverlay (uint32 cTransparentColor)
	Convert alpha channel to overlay.
status_t	GlowFilter (Color32_s cInnerColor, Color32_s cOuterColor, int nRadius)
	Add glow effect to the image.
status_t	ColorizeFilter (Color32_s cColor)
Classes
class	Private

---

Detailed Description

Description:

The BitmapImage class contains image data in the form of a bitmap and implements methods for loading and saving images via Translators.

Example:

        File cFile( "picture.png" );
        Image *pcImage;
        pcImage = new BitmapImage( &cFile );    // Load picture.png
        pcImage->GrayFilter();

See also:

os::Image, os::VectorImage, os::Bitmap

Author:

Henrik Isaksson ([email protected])

---

Constructor & Destructor Documentation

BitmapImage::BitmapImage

(

uint32

nFlags = Bitmap::SHARE_FRAMEBUFFER

)

Parameters:

nFlags

Bitmap flags, see os::Bitmap.

See also:

os::Bitmap, os::BitmapImage::IsValid()

Note:

This constructor does not create the internal Bitmap object. Thus BitmapImage::IsValid() will return false after this creator is used. Note that the methods BitmapImage::Load(), BitmapImage::SetBitmapData(), BitmapImage::SetSize(), BitmapImage::ResizeCanvas() (re)initialise the internal Bitmap object, so one of these must be called before operations such as BitmapImage::Draw(), BitmapImage::GetSize() etc can be used.

Author:

Henrik Isaksson ([email protected])

BitmapImage::BitmapImage	(	const BitmapImage &	cSource,
		uint32	nFlags = Bitmap::SHARE_FRAMEBUFFER
	)

Parameters:

	cSource	Original BitmapImage object to copy.
	nFlags	Bitmap flags, see os::Bitmap.

Author:

Henrik Isaksson ([email protected])

BitmapImage::BitmapImage	(	StreamableIO *	pcSource,
		uint32	nFlags = Bitmap::SHARE_FRAMEBUFFER
	)

Parameters:

	pcSource	A pointer to a StreamableIO object. Could be a file, a resource or any data source that can be represented as a stream of data. The Translator API is used to try to recognize the format and load it as bitmap data. If you need to explicitly specify the file format, use Load().
	nFlags	Bitmap flags, see os::Bitmap.

See also:

Load(), os::Bitmap

Author:

Henrik Isaksson ([email protected])

BitmapImage::BitmapImage	(	const uint8 *	pData,
		const IPoint &	cSize,
		color_space	eColorSpace,
		uint32	nFlags = Bitmap::SHARE_FRAMEBUFFER
	)

Parameters:

	pData	Pointer to an array of raw bitmap data.
	cSize	The size of the bitmap in pixels.
	eColorSpace	Color space, for instance CS_RGB32.
	nFlags	Bitmap flags, see os::Bitmap.

See also:

os::color_space, os::Bitmap

Author:

Henrik Isaksson ([email protected])

BitmapImage::~BitmapImage

(

)

[virtual]

---

Member Function Documentation

const String BitmapImage::ImageType

(

void

)

const [virtual]

Description:

Used for run-time type checking. Returs the class name, "BitmapImage".

See also:

Image::ImageType()

Author:

Henrik Isaksson ([email protected])

Implements os::Image.

bool BitmapImage::IsValid

(

void

)

const [virtual]

Description:

Use to find out if the object contains a usable bitmap.

See also:

Image::IsValid()

Author:

Henrik Isaksson ([email protected])

Implements os::Image.

status_t BitmapImage::Load	(	StreamableIO *	pcSource,
		const String &	cType = ""
	)			[virtual]

).

Description:

This method loads and translates bitmaps in any format supported by the Translators from any data source that can be represented as a stream.

Parameters:

	pcSource	A pointer to a StreamableIO object. Could be a file, a resource or any data source that can be represented as a stream of data. The Translator API is used to try to recognize the format and load it as bitmap data.
	cType	Used to specify a specific file format, if the automatic recognition is not enough.

Example:

                File cFile( "picture.png" );
                myImage->Load( &cFile, "image/png" );

See also:

Save(), os::File, os::StreamableIO, os::MemFile

Author:

Henrik Isaksson ([email protected])

Implements os::Image.

status_t BitmapImage::Save	(	StreamableIO *	pcDest,
		const String &	cType
	)			[virtual]

Description:

This method translates and writes bitmaps to a stream in any Translator supported format. (Note! At the time of writing there are no Translators capable of translating from the internal format to any other format.)

Parameters:

	pcDest	A pointer to a StreamableIO object.
	cType	String that describes the file format, eg "image/png".

Example:

                File cFile( "picture.png" );
                myImage->Save( &cFile, "image/png" );

Note:

This method can only be used if the bitmap was created with the SHARE_FRAMEBUFFER flag.

See also:

Load(), os::File, os::StreamableIO, os::MemFile

Author:

Henrik Isaksson ([email protected])

Implements os::Image.

void BitmapImage::Draw	(	const Point &	cPos,
		View *	pcView
	)			[virtual]

Description:

This method renders the image to a View object.

Parameters:

	cPos	Position in the destination View to draw at.
	pcView	The View to draw in.

See also:

os::View

Author:

Henrik Isaksson ([email protected])

Implements os::Image.

void BitmapImage::Draw	(	const Rect &	cSource,
		const Rect &	cDest,
		View *	pcView
	)			[virtual]

Description:

This method renders the image to a View object.

Parameters:

	cSource	Rectangular region in the source Image to draw.
	cDest	Rectangular region in the destination View to draw the image in. If the size of cDest is not equal to cSource, the image data from cSource will be scaled to fit.
	pcView	The View to draw in.

Todo:

Implement scaling. Needs support from os::View.

See also:

os::View

Author:

Henrik Isaksson ([email protected])

Implements os::Image.

status_t BitmapImage::SetSize

(

const Point &

cSize

)

[virtual]

Description:

Scales the bitmap to the specified size. Returns an error if memory for a new bitmap can not be allocated. SetSize may provide better quality scaling than Draw(), which is optimized for speed rather than quality. The image will remain unchanged if memory allocation fails.

Parameters:

cSize

The new size.

See also:

GetSize(), ResizeCanvas()

Author:

Henrik Isaksson ([email protected])

Reimplemented from os::Image.

Point BitmapImage::GetSize

(

void

)

const [virtual]

Description:

Returns the size of the internal bitmap object.

Return values:

Actual

Bitmap size.

See also:

SetSize()

Author:

Henrik Isaksson ([email protected])

Reimplemented from os::Image.

void BitmapImage::SetBitmapData	(	const uint8 *	pData,
		const IPoint &	cSize,
		color_space	eColorSpace,
		uint32	nFlags = Bitmap::SHARE_FRAMEBUFFER
	)

Description:

Set raw bitmap data.

Parameters:

	pData	Pointer to an array of raw bitmap data.
	cSize	The size of the bitmap in pixels.
	eColorSpace	Color space, for instance CS_RGB32.
	nFlags	Bitmap flags, see os::Bitmap. SHARE_FRAMEBUFFER is assumed.

See also:

os::color_space, os::Bitmap

Author:

Henrik Isaksson ([email protected])

color_space BitmapImage::GetColorSpace

(

)

const

Description:

Returns the colour space for the image.

Return values:

The

bitmap's colour space, one of the values in os::color_space.

See also:

os::color_space, SetColorSpace()

Author:

Henrik Isaksson ([email protected])

status_t BitmapImage::SetColorSpace

(

color_space

eColorSpace

)

[virtual]

Description:

Transform the bitmap to a different colour space. This method may reduce the quality of the image data!

Parameters:

eColorSpace

The colour space, eg. CS_RGB32.

Return values:

0

for success, -1 for failure.

Todo:

Implement BitmapImage::SetColorSpace

See also:

os::color_space, GetColorSpace()

Author:

Henrik Isaksson ([email protected])

Bitmap * BitmapImage::LockBitmap

(

void

)

[virtual]

Description:

Lock the internal Bitmap object so it can be safely manipulated.

Example:

        Bitmap  *myBitmap = myImage->LockBitmap();
        if( myBitmap ) {

                ...

                myImage->UnlockBitmap();
        }

Note:

Don't forget to Unlock the Bitmap by calling UnlockBitmap().

Return values:

Pointer

to the locked Bitmap. If the internal Bitmap is not valid, returns NULL (see IsValid()).

See also:

UnlockBitmap(), IsValid(), os::Bitmap

Author:

Henrik Isaksson ([email protected])

void BitmapImage::UnlockBitmap

(

void

)

[virtual]

Description:

Unlock the internal Bitmap object

See also:

LockBitmap(), os::Bitmap

Author:

Henrik Isaksson ([email protected])

BitmapImage & BitmapImage::operator=

(

const BitmapImage &

cSource

)

[virtual]

Description:

Copy the contents of another bitmap.

Note:

The source bitmap must be created with SHARE_FRAMEBUFFER flag. If not, the assignment has no effect.

See also:

os::Bitmap

View * BitmapImage::GetView

(

)

[virtual]

Description:

Returns a pointer to a View, that can be used for rendering into the bitmap. This is useful for double buffering.

Note:

When finished drawing to the View, you need to call Sync(). The drawing operations might not take place until you have done so.

The BitmapImage should be initialized with the flag ACCEPT_VIEWS. If it isn't, GetView() will try to re-allocate the bitmap, changing this flag.

Author:

Henrik Isaksson ([email protected])

void BitmapImage::ResizeCanvas

(

const Point &

cSize

)

[virtual]

Description:

Changes the size of the bitmap to the specified size. Returns an error if memory for a new bitmap can not be allocated. Note that the image data is lost. To change the size of the image, use SetSize() instead.

Parameters:

cSize

The new size.

See also:

SetSize(), GetSize()

Author:

Henrik Isaksson ([email protected])

uint32 * BitmapImage::operator[]

(

int

row

)

[virtual]

Description:

Returns a pointer to a row of raw pixel data.

Note:

The BitmapImage should be initialized with the flag SHARE_FRAMEBUFFER. If it isn't, this method will try to re-allocate the bitmap, changing this flag.

Author:

Henrik Isaksson ([email protected])

void BitmapImage::Sync

(

void

)

Description:

Call this method before accessing bitmap data that you have created by rendering to the View associated with this BitmapImage.

See also:

Window::Sync(), Bitmap::Sync(), GetView()

Author:

Henrik Isaksson

void BitmapImage::Flush

(

void

)

Description:

See Window::Sync().

See also:

Window::Sync(), Bitmap::Sync(), GetView()

Author:

Henrik Isaksson

status_t BitmapImage::ApplyFilter

(

const Message &

cFilterData

)

[virtual]

Reimplemented from os::Image.

status_t BitmapImage::GrayFilter

(

void

)

Description:

Removes colour information and makes the image brighter, primarily intended for GUI components, where it will be used to create "disabled" icons.

Note:

The greying algorithm may change in future versions. On certain systems it may also be adapted to suit their displays.

Author:

Henrik Isaksson ([email protected])

status_t BitmapImage::HighlightFilter

(

void

)

Description:

Make the image highlighted, for use with icons, for instance.

Note:

The highlighting algorithm may change in future versions. On certain systems it may also be adapted to suit their displays.

Author:

Henrik Isaksson ([email protected])

status_t BitmapImage::AlphaToOverlay

(

uint32

cTransparentColor

)

Description:

Convert an image with alpha transparency to overlay transparency. Overlay may provide better rendering performance, but does not support gradual transparency; it's either fully transparent or entirely opaque.

The conversion is done by setting all pixels with >25%

transparency to TRANSPARENT_RGB32, which is pure white. Any pixel that is pure white, will have it's colour changed. (The blue component is tweaked +/- one LSB).

Parameters:

cTransparentColor

The colour that will be transparent. Typically you will use the default, TRANSPARENT_RGB32.

See also:

os::View, os::Bitmap, os::View::DrawBitmap()

Author:

Henrik Isaksson ([email protected])

status_t BitmapImage::GlowFilter	(	Color32_s	cInnerColor,
		Color32_s	cOuterColor,
		int	nRadius
	)

Description:

Adds a "glowing" outline to the image.

Parameters:

	cInnerColor	The colour nearest the edge of the picture.
	cOuterColor	The colour at the edge of the glow. Tip: set a low opacity here, to blend the glow with the background.
	nRadius	The width of the glow.

Note:

This function requires an image with correct alpha channel data.

Author:

Henrik Isaksson ([email protected])

status_t BitmapImage::ColorizeFilter

(

Color32_s

cColor

)

---