<?xml version="1.0" encoding="utf-8"?>

<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->

<!-- This component and the accompanying materials are made available under the terms of the License 

"Eclipse Public License v1.0" which accompanies this distribution, 

and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->

<!-- Initial Contributors:

    Nokia Corporation - initial contribution.

Contributors: 

-->

<!DOCTYPE concept

  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">

<concept xml:lang="en" id="GUID-9D6C086F-7621-5522-AE0B-81CBD5E99125"><title>Bitmap Transform Library Guide</title><shortdesc>This topic provides more detailed information about and code snippets for the Bitmap Transform library. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody><section id="GUID-7D1E45F2-2793-5BE5-8F9E-1F92228A4C06"><title>Purpose</title> <p>Bitmap Transform makes it possible for bitmap images to be resized and rotated as described below. </p> </section> <section><title>Introducing Bitmap Transformation</title> <p>The resizing or scale (<xref href="GUID-2008D827-A84A-3170-A8BD-86002BA37979.dita"><apiname>CBitmapScaler</apiname></xref>) and rotation (<xref href="GUID-D0835677-6790-3038-8893-83E7186F47E7.dita"><apiname>CBitmapRotator</apiname></xref>) actions are asynchronous operations that take a pointer to a <xref href="GUID-E0B34F3E-D4C4-3232-B8B1-7DB35B454646.dita"><apiname>TRequestStatus</apiname></xref> object, which is signalled on completion of the requested action. The client application or calling DLL will hold the <codeph>TRequestStatus</codeph> 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. </p> <p> <b>Note:</b>  <xref href="GUID-2008D827-A84A-3170-A8BD-86002BA37979.dita"><apiname>CBitmapScaler</apiname></xref> and <xref href="GUID-D0835677-6790-3038-8893-83E7186F47E7.dita"><apiname>CBitmapRotator</apiname></xref> are not able them to run in their own thread. </p> </section> <section><title>Bitmap Transformation Example - Bitmap scaling</title> <p>There are two variants of the <xref href="GUID-2008D827-A84A-3170-A8BD-86002BA37979.dita#GUID-2008D827-A84A-3170-A8BD-86002BA37979/GUID-CCE10188-A9FD-38C8-89EC-3908C91DD25A"><apiname>CBitmapScaler::Scale()</apiname></xref> function. The first variant performs rescaling on an image contained in one <xref href="GUID-683A1D42-2764-3EB7-BD19-9E12559199AB.dita"><apiname>CFbsBitmap</apiname></xref> object and places the result in another object. The second variant rescales an image contained in a <codeph>CFbsBitmap</codeph> object and places the result back in the same object. This is illustrated below. </p> <codeblock id="GUID-0979C855-4592-5652-BE58-4DA92C54CEFD" xml:space="preserve">void Scale(TRequestStatus* aRequestStatus, CFbsBitmap&amp; aSrcBitmap, CFbsBitmap&amp; aTgtBitmap, TBool aMaintainAspectRatio = ETrue);

void Scale(TRequestStatus* aRequestStatus, CFbsBitmap&amp; aBitmap, const TSize&amp; aDestinationSize, TBool aMaintainAspectRatio = ETrue);</codeblock> <p>If two <codeph>CFbsBitmap</codeph> 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). </p> <p>If only the one <codeph>CFbsBitmap</codeph> object is specified in the scale operation, the scaling factor is taken from <xref href="GUID-938244B2-5E1A-39F7-8ACA-E6DE4C44A313.dita"><apiname>TSize</apiname></xref> subject to the aspect ratio setting. </p> <p>The aspect ratio is maintained if <codeph>aMaintainAspectRatio</codeph> is <codeph>ETrue</codeph>. 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. </p> <p>In this example, the source image is 50 pixels wide by 150 pixels high (an aspect ratio of 1:3), <codeph>aMaintainAspectRatio</codeph> is set to <codeph>ETrue</codeph>, 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. </p> </section> <section><title>Bitmap Transformation Example - Bitmap rotation</title> <p>There are two variants of the <xref href="GUID-2008D827-A84A-3170-A8BD-86002BA37979.dita#GUID-2008D827-A84A-3170-A8BD-86002BA37979/GUID-A655241C-5339-35E2-8BDE-EDAF13ECC87A"><apiname>CBitmapScaler::Rotate()</apiname></xref> function. The first performs a rotational action on an image contained in one <xref href="GUID-683A1D42-2764-3EB7-BD19-9E12559199AB.dita"><apiname>CFbsBitmap</apiname></xref> object and places the result in another object. The second variant performs a rotational action on an image contained in a <codeph>CFbsBitmap</codeph> object and places the result back in the same object. Valid rotational increments are specified in <xref href="GUID-D0835677-6790-3038-8893-83E7186F47E7.dita#GUID-D0835677-6790-3038-8893-83E7186F47E7/GUID-D89261A3-D59C-38BC-BF55-B0C758AC9C85"><apiname>CBitmapRotator::TRotationAngle</apiname></xref>. </p> <p>Note: <xref href="GUID-2008D827-A84A-3170-A8BD-86002BA37979.dita#GUID-2008D827-A84A-3170-A8BD-86002BA37979/GUID-A655241C-5339-35E2-8BDE-EDAF13ECC87A"><apiname>CBitmapScaler::Rotate()</apiname></xref> does not support user specified rotational angles. The only values allowed are those specified in <xref href="GUID-D0835677-6790-3038-8893-83E7186F47E7.dita#GUID-D0835677-6790-3038-8893-83E7186F47E7/GUID-D89261A3-D59C-38BC-BF55-B0C758AC9C85"><apiname>CBitmapRotator::TRotationAngle</apiname></xref>. </p> <codeblock id="GUID-4FF39951-1B71-5267-813B-32828EB4A73B" xml:space="preserve">void Rotate(TRequestStatus* aRequestStatus, CFbsBitmap&amp; aSrcBitmap, CFbsBitmap&amp; aTgtBitmap, TRotationAngle aAngle);

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

</codeblock> <table id="GUID-A207445C-18A1-5BA0-9E98-2D1C8A3126E7"><tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/><tbody><row><entry><fig id="GUID-E8157802-DA4E-5C30-94CE-E91DCD632187"><image href="GUID-27529BB0-8034-56B0-82FA-3E4CFDEBC99A_d0e299272_href.png" placement="inline"/></fig> </entry> <entry><p> <codeph>ERotation90DegreesClockwise</codeph>  </p> </entry> </row> <row><entry><fig id="GUID-FEF7BCE4-26B8-552A-9E86-C7F21AA8D88A"><image href="GUID-29F55D74-A206-5862-9C83-2C5045B2DB7F_d0e299287_href.png" placement="inline"/></fig> </entry> <entry><p> <codeph>ERotation180DegreesClockwise</codeph>  </p> </entry> </row> <row><entry><fig id="GUID-A12CB5D1-599B-5F85-B879-610EA9CD2CF9"><image href="GUID-37888891-DFB2-5A93-9547-3B22410906BF_d0e299302_href.png" placement="inline"/></fig> </entry> <entry><p> <codeph>ERotation270DegreesClockwise</codeph>  </p> </entry> </row> <row><entry><fig id="GUID-37EC2688-E3AC-51A4-86F9-95124DDF40F8"><image href="GUID-BA1071D5-E358-5B33-9204-CDCD0CECEF0A_d0e299317_href.png" placement="inline"/></fig> </entry> <entry><p> <codeph>EMirrorHorizontalAxis</codeph>  </p> </entry> </row> <row><entry><fig id="GUID-DFFCC6D6-B7F7-5047-B93D-CF79B2D47F17"><image href="GUID-399F7F7D-3E8E-58BB-9925-9F34C561C39A_d0e299332_href.png" placement="inline"/></fig> </entry> <entry><p> <codeph>EMirrorVerticalAxis</codeph>  </p> </entry> </row> </tbody> </tgroup> </table> </section> </conbody><related-links><link href="GUID-88091838-03FC-550F-9A3D-DA70907EF955.dita"><linktext>Imaging Frameworks overview</linktext> </link> <link href="GUID-C0B39D73-0A3C-5289-A774-7BE590037404.dita"><linktext> Bitmap Transform Library

                Overview</linktext> </link> <link href="GUID-9D6C086F-7621-5522-AE0B-81CBD5E99125.dita"><linktext>Bitmap Transform Library Guide</linktext> </link> <link href="GUID-E6692CDA-9E24-57AE-9BC2-14D68D6480C3.dita"><linktext>Enhanced Features for Encoder and