Class TBitmapUtil

TBitmapUtil

Support

Supported from 5.0

Description

Provides fast read/write access to the image data of a bitmap.

Functionality includes getting and setting the individual pixels of a bitmap. Common to this is the concept of the current pixel position. This is held as member data and is changed by using various efficient functions. For example, incrementing the position’s x- or y co-ordinate is much quicker than setting a completely new position. This efficiency issue is important as these functions are used as part of the frequently used blitting DDA — used for creating stretched or compressed versions of bitmaps.

Due to the defragmentation process that is used to compress the FBSRV heap, bitmaps may be moved in memory at any time — including whilst the bitmaps’ contents are being manipulated. Therefore, operations to lock and unlock the heap — preventing and allowing the heap to be compressed — are provided. The use of these functions, surrounding any calls to the other member functions maximises the simplicity and efficiency of these functions.

Note that this class does not support bitmaps whose display mode is EColor16M. If the bitmap is EColor16M, then its data can be read/written directly, by calling CFbsBitmap::DataAddress() to get a pointer to the data area.

Defined in TBitmapUtil:
Begin(), DecXPos(), DecYPos(), End(), GetPixel(), IncXPos(), IncYPos(), SetPixel(), SetPos(), TBitmapUtil()

TBitmapUtil(CFbsBitmap* aBitmap);

Description

Constructs a TBitmapUtil object for the specified bitmap.

Parameters

CFbsBitmap* aBitmap The bitmap on which this TBitmapUtil will operate.

void Begin(const TPoint& aPosition);

Description

Sets the current pixel position to the specified position and locks the heap.

This function must be called before using any of the other functions provided by this class, otherwise damage to data may occur. It must also be matched by a subsequent call to End().

Parameters

const TPoint& aPosition The position to which the current pixel position should be set.

Panic codes

FBSERV 10 The bitmap's display mode is EColor16M.

void Begin(const TPoint& aPosition,const TBitmapUtil& aUtil);

Description

Sets the current pixel position to the specified position when the heap is already locked.

The function assumes that the heap has already been locked by the specified TBitMapUtil object associated with another bitmap.

Parameters

const TPoint& aPosition The position to which the current pixel position should be set. const TBitmapUtil& aUtil The TBitmapUtil object which has already locked the heap.

Panic codes

FBSERV 10 The bitmap's display mode is EColor16M.

void End();

Description

Unlocks the heap.

There must be exactly one call to End() for each previous call to Begin() for a given TBitmapUtil object. Failure to call End() may result in the device locking.

TUint32 GetPixel() const;

Description

Gets the value of the pixel at the current pixel position.

In normal usage, the value returned will immediately be used as the parameter to a call to SetPixel(). To remove the overhead of constructing a TRgb, the function uses a TUint32 rather than a TRgb to hold an RGB value.

Return value

TUint32 The value of the pixel at the current pixel position.

void SetPixel(TUint32 aValue);

Description

Sets the value of the pixel at the current pixel position.

To remove the overhead of constructing a TRgb, the function uses a TUint32 rather than a TRgb to hold an RGB value.

Parameters

TUint32 aValue The value to which the pixel at the current pixel position is to be set.

void SetPixel(const TBitmapUtil& aSource);

Description

Sets the value of the pixel at the current pixel position to that returned by aSource.GetPixel().

Parameters

const TBitmapUtil& aSource The TBitmapUtil of the source bitmap, whose pixel value is used to set the pixel at the current pixel position.

void DecXPos();

Description

Decrements the x co-ordinate of the current pixel position.

void DecYPos();

Description

Decrements the y co-ordinate of the current pixel position.

void IncXPos();

Description

Increments the x co-ordinate of the current pixel position.

void IncYPos();

Description

Increments the y co-ordinate of the current pixel position.

void SetPos(const TPoint& aPosition);

Description

Sets a new current pixel position.

Parameters

const TPoint& aPosition The new current pixel position.