Bitmap Transform Library Guide

Purpose

Bitmap Transform makes it possible for bitmap images to be resized and rotated as described below.

Introducing Bitmap Transformation

The resizing or scale (CBitmapScaler) and rotation (CBitmapRotator) actions are asynchronous operations that take a pointer to a TRequestStatus object, which is signalled on completion of the requested action. The client application or calling DLL will hold the TRequestStatus values within active objects. As with any use of an active object it is necessary to have an active scheduler present in the same thread as the application making use of the object.

Note: CBitmapScaler and CBitmapRotator are not able them to run in their own thread.

Bitmap Transformation Example - Bitmap scaling

There are two variants of the CBitmapScaler::Scale() function. The first variant performs rescaling on an image contained in one CFbsBitmap object and places the result in another object. The second variant rescales an image contained in a CFbsBitmap object and places the result back in the same object. This is illustrated below.

void Scale(TRequestStatus* aRequestStatus, CFbsBitmap& aSrcBitmap, CFbsBitmap& aTgtBitmap, TBool aMaintainAspectRatio = ETrue);
void Scale(TRequestStatus* aRequestStatus, CFbsBitmap& aBitmap, const TSize& aDestinationSize, TBool aMaintainAspectRatio = ETrue);

If two CFbsBitmap objects are specified in the scale operation, the dimensions of the destination object are used as the rescaling factors, subject to the aspect ratio setting (described below).

If only the one CFbsBitmap object is specified in the scale operation, the scaling factor is taken from TSize subject to the aspect ratio setting.

The aspect ratio is maintained if aMaintainAspectRatio is ETrue. If the ratio is used, then the image is rescaled to the smaller of the horizontal and vertical scaling factors. This is best explained by use of an example.

In this example, the source image is 50 pixels wide by 150 pixels high (an aspect ratio of 1:3), aMaintainAspectRatio is set to ETrue, and the proposed rescaling is to 75 pixels wide by 300 high. Applying this ratio to the smaller of the horizontal and vertical factors means using a new value for the larger rescaling factor so that the aspect ratio matches that of the source image. The smaller value is 75 pixels, the aspect ratio required is 1:3 so the larger value will be 75*3 which is 225. The image will be rescaled to 75 wide by 225 high.

Bitmap Transformation Example - Bitmap rotation

There are two variants of the CBitmapScaler::Rotate() function. The first performs a rotational action on an image contained in one CFbsBitmap object and places the result in another object. The second variant performs a rotational action on an image contained in a CFbsBitmap object and places the result back in the same object. Valid rotational increments are specified in CBitmapRotator::TRotationAngle.

Note: CBitmapScaler::Rotate() does not support user specified rotational angles. The only values allowed are those specified in CBitmapRotator::TRotationAngle.

void Rotate(TRequestStatus* aRequestStatus, CFbsBitmap& aSrcBitmap, CFbsBitmap& aTgtBitmap, TRotationAngle aAngle);

void Rotate(TRequestStatus* aRequestStatus, CFbsBitmap& aBitmap, TRotationAngle aAngle);

	ERotation90DegreesClockwise
	ERotation180DegreesClockwise
	ERotation270DegreesClockwise
	EMirrorHorizontalAxis
	EMirrorVerticalAxis