<?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-26FD66B4-A291-5DAD-991D-40AB5316F30C"><title> Initializing And Processing an Image Tutorial</title><prolog><metadata><keywords/></metadata></prolog><conbody><p>This document gives you more information about Image Processor. </p> <section><title>Purpose</title> <p>The purpose of this tutorial is to show you how to initialize and process an image. </p> <p><b>Required background</b> </p> <p>Image Processor features are provided through the Imaging Frameworks and the Imaging Plug-ins components. </p> <p><b>Introduction</b> </p> <p>Every new instance of Image Processor must be initialized before processing. </p> <p><b>Initializing an image </b> </p> <p>You need to choose an input image you want to work with. You can start </p> <ul><li id="GUID-DDB8CA71-838F-539E-93E2-E0A7666573CC"><p>with an image file stored on flash memory or a hard drive </p> </li> <li id="GUID-D8DFE478-7542-5A43-BC51-61D294E5D8D9"><p>with a memory buffer containing an image of any of the supported image formats </p> </li> <li id="GUID-E7FFA3E5-F264-51F2-8420-C4B9CDE538BE"><p>with a Symbian bitmap or image frame </p> </li> <li id="GUID-60E1993A-51A7-5596-8D46-63F0BBB8D172"><p>by only specifying a background colour. </p> </li> </ul> <p>An image stored on file is the most likely option if you are building an editor (most mobile cameras store images in JPEG format on flash memory). If you transfer images from your Digital Still Camera (DSC) or your PC to your mobile phone, the images are probably stored as JPEG files. </p> <p>If you build a camera application, you receive viewfinder data from the camera module. In this case you will use Symbian bitmaps or image frames. </p> <p>If you want to start with an empty image, only specify the background colour. For example, if you want to create a collage of several images, you do not really have a main source image and it is memory efficient to set a ‘blank’ input. </p> <p><b>Processing an image </b> </p> <p>When you process an image, all the operations and settings you specified in your Image Processor instance are performed on your input image. </p> <p>There are three options to choose from to get the output format. In a mobile imaging application there are at least two formats you want your results in. You want to see a preview of the result on the screen of the mobile phone – in which case you render to a bitmap or image frame. When you are satisfied with the preview you want to apply the operations and effects on the source image that is usually significantly larger – you will then render to a file on the flash memory. </p> <p>To see a preview of the image call <xref href="GUID-77F2CAB1-78AC-3527-A8B3-D1B24D730A54.dita#GUID-77F2CAB1-78AC-3527-A8B3-D1B24D730A54/GUID-68B932DF-3E62-3018-BDCC-C720A0B5949C"><apiname>Imageprocessor::TPreview::RenderL()</apiname></xref>. To apply the effects on the source image to get a full resolution result call <xref href="GUID-13E30312-DD05-3581-9A59-C3569A981657.dita#GUID-13E30312-DD05-3581-9A59-C3569A981657/GUID-81D98D3A-7B5A-3D2E-81CE-A3F2F3D5BCA5"><apiname>ImageProcessor::CImgProcessor::ProcessL()</apiname></xref> which will render to the output you have set. </p> </section> <section><title>Using the image processor</title> <p>The following tasks are covered in this tutorial: </p> <ul><li id="GUID-FEAF6932-E193-5177-BFCD-A2CB6FB8DFF3"><p><xref href="GUID-26FD66B4-A291-5DAD-991D-40AB5316F30C.dita#GUID-26FD66B4-A291-5DAD-991D-40AB5316F30C/GUID-12E1341A-966C-5033-BEB0-6F2C0705CCE3">How to set an input image</xref>  </p> </li> <li id="GUID-1362E175-4652-5645-A1E8-2732F2DF9EE4"><p><xref href="GUID-26FD66B4-A291-5DAD-991D-40AB5316F30C.dita#GUID-26FD66B4-A291-5DAD-991D-40AB5316F30C/GUID-F3DCFD1D-A5E2-5005-8598-621A96646514">How to set an output image</xref>  </p> </li> <li id="GUID-0FBDA00D-1738-52A7-B5F3-74E29E719D04"><p><xref href="GUID-26FD66B4-A291-5DAD-991D-40AB5316F30C.dita#GUID-26FD66B4-A291-5DAD-991D-40AB5316F30C/GUID-681FC188-0A6C-5A18-8073-7CD55A18B010">How to process the image</xref>  </p> </li> </ul> <p id="GUID-12E1341A-966C-5033-BEB0-6F2C0705CCE3"><b>Basic procedure to set an input image</b> </p> <p>The various ways to set an input image are as follows: </p> <ul><li id="GUID-49FACCE8-1728-5E3C-96AF-048B402C563B"><p>To create an internal pixel buffer for an input image use <xref href="GUID-13E30312-DD05-3581-9A59-C3569A981657.dita#GUID-13E30312-DD05-3581-9A59-C3569A981657/GUID-F0B8B499-1782-313F-95D2-960A91AA8A3A"><apiname>ImageProcessor::CImgProcessor::CreateInputL(CFbsBitmap&amp;

                  )</apiname></xref>. </p> </li> <li id="GUID-8BBB9526-BCF0-5B12-909F-FCF107AE73F0"><p>To create an internal pixel buffer for an input image use <xref href="GUID-13E30312-DD05-3581-9A59-C3569A981657.dita#GUID-13E30312-DD05-3581-9A59-C3569A981657/GUID-207ABDE3-158A-340F-B8F1-5F73F2DB70DD"><apiname>ImageProcessor::CImgProcessor::CreateInputL(CImageFrame&amp;

                  )</apiname></xref>. </p> </li> <li id="GUID-FF4FA4E8-3090-57F3-B6AB-F2D69E3728D8"><p>To create an internal pixel buffer for an input image using a size and then initialize the source image with a colour use <xref href="GUID-13E30312-DD05-3581-9A59-C3569A981657.dita#GUID-13E30312-DD05-3581-9A59-C3569A981657/GUID-278503A5-4D72-305D-BCB0-0DF4FB922CFA"><apiname>ImageProcessor::CImgProcessor::CreateInputL(const TSize&amp;

                  )</apiname></xref>. </p> </li> <li id="GUID-9A7EAD5F-7F11-5C9E-944B-08D7A3D1F5E2"><p>To set or update an input image to a specified file name use <xref href="GUID-13E30312-DD05-3581-9A59-C3569A981657.dita#GUID-13E30312-DD05-3581-9A59-C3569A981657/GUID-8B07E48A-FF93-3A59-8C29-D37C2FE92B09"><apiname>ImageProcessor::CImgProcessor::SetInputL(const TDesC&amp;

                  )</apiname></xref>. </p> </li> <li id="GUID-C13CD1AE-BBDB-58E3-85CE-FBEF7B72DDB0"><p>To set or updated an input image to a file use <xref href="GUID-13E30312-DD05-3581-9A59-C3569A981657.dita#GUID-13E30312-DD05-3581-9A59-C3569A981657/GUID-36789050-2FD1-36EE-8B2F-E92EF35732C8"><apiname>ImageProcessor::CImgProcessor::SetInputL(RFile&amp; )</apiname></xref>. </p> </li> <li id="GUID-22F43407-00DE-59F9-BD3B-1CA53981B9E2"><p>To set or update a DRM protected input image use <xref href="GUID-13E30312-DD05-3581-9A59-C3569A981657.dita#GUID-13E30312-DD05-3581-9A59-C3569A981657/GUID-A1318F8A-D415-3416-945F-960D4A5F91F7"><apiname>ImageProcessor::CImgProcessor::SetInputL(TMMSource&amp; )</apiname></xref>. </p> </li> <li id="GUID-4FA894C9-857A-5FAC-A6FC-4F6755073980"><p>To set or update an input image from a memory buffer use <xref href="GUID-13E30312-DD05-3581-9A59-C3569A981657.dita#GUID-13E30312-DD05-3581-9A59-C3569A981657/GUID-0F3D9FA8-91BB-3C2A-B774-47B12F946991"><apiname>ImageProcessor::CImgProcessor::SetInputL(const TDesC8&amp;

                  )</apiname></xref>. </p> </li> <li id="GUID-1214AC4F-E0D9-585E-99B9-E7DCA7BC289C"><p>To set or update an input image from a provided bitmap use <xref href="GUID-13E30312-DD05-3581-9A59-C3569A981657.dita#GUID-13E30312-DD05-3581-9A59-C3569A981657/GUID-2A58C2C2-82B8-3FEE-9592-DDA899F5E276"><apiname>ImageProcessor::CImgProcessor::SetInputL(const CFbsBitmap&amp;

                  )</apiname></xref>. </p> </li> <li id="GUID-439696FB-08DE-541B-BA86-A13098DB052C"><p>To set or update an input image from a provided image frame use <xref href="GUID-13E30312-DD05-3581-9A59-C3569A981657.dita#GUID-13E30312-DD05-3581-9A59-C3569A981657/GUID-4235276B-51D9-3FC9-94DB-E8055F921341"><apiname>ImageProcessor::CImgProcessor::SetInputL(const CImageFrame&amp;

                  )</apiname></xref>. </p> </li> </ul> <p id="GUID-F3DCFD1D-A5E2-5005-8598-621A96646514"><b>Basic procedure to set an output image</b> </p> <p>The various ways to set an output image are as follows: </p> <ul><li id="GUID-DAB7C887-94E0-5654-BC42-C926D86D2C7A"><p>To set an output image image to a file call <xref href="GUID-13E30312-DD05-3581-9A59-C3569A981657.dita#GUID-13E30312-DD05-3581-9A59-C3569A981657/GUID-E7B8F47A-BCFA-3FC1-8947-D63D65151C2D"><apiname>ImageProcessor::CImgProcessor::SetOutputL(const TDesC&amp;

                  )</apiname></xref>. </p> </li> <li id="GUID-579ABD52-B3D8-5E53-A2BA-CB7869B18DDA"><p>To set an output image to a file represented by a file handle call <xref href="GUID-13E30312-DD05-3581-9A59-C3569A981657.dita#GUID-13E30312-DD05-3581-9A59-C3569A981657/GUID-C110C8DC-D83F-384E-B2F6-D394D55B7F1E"><apiname>ImageProcessor::CImgProcessor::SetOutputL(RFile&amp;

                  )</apiname></xref>. </p> </li> <li id="GUID-111D5DDA-677C-5F08-93D9-CE931CFED288"><p>To set an output image to the memory buffer call <xref href="GUID-13E30312-DD05-3581-9A59-C3569A981657.dita#GUID-13E30312-DD05-3581-9A59-C3569A981657/GUID-388BD9E0-FBAB-37E5-835B-0A875C2A0B94"><apiname>ImageProcessor::CImgProcessor::SetOutputL(RBuf8&amp; )</apiname></xref>. </p> </li> <li id="GUID-1B0AF58D-9ADB-59B7-99DD-CFE2701ED6A9"><p>To set an output image to a pixel buffer call <xref href="GUID-13E30312-DD05-3581-9A59-C3569A981657.dita#GUID-13E30312-DD05-3581-9A59-C3569A981657/GUID-4ADE2F1C-41C8-34E8-893C-17021849C72D"><apiname>ImageProcessor::CImgProcessor::SetOutputL(CImageFrame&amp;

                  )</apiname></xref>. </p> </li> <li id="GUID-8534B622-766A-556B-B054-B78B9F2EDAD6"><p>To set an output image to an OS native bitmap call <xref href="GUID-13E30312-DD05-3581-9A59-C3569A981657.dita#GUID-13E30312-DD05-3581-9A59-C3569A981657/GUID-18200F37-819C-31C1-83ED-739DA4911EC1"><apiname>ImageProcessor::CImgProcessor::SetOutputL(CFbsBitmap&amp;

                  )</apiname></xref>. </p> </li> </ul> <p> <b>Note:</b> Rendering is not performed when you set an output image. In case of setting the output image to a memory buffer <codeph>RBuf8</codeph> instance should not contain pre-allocated memory. </p> <p id="GUID-681FC188-0A6C-5A18-8073-7CD55A18B010"><b>Basic procedure to process the image</b> </p> <p>The high level steps to process an image are as follows: </p> <ul><li id="GUID-8DC5181E-E2B2-5767-A369-0F23389ED119"><p>To initialize the Image Processor instance call <xref href="GUID-13E30312-DD05-3581-9A59-C3569A981657.dita#GUID-13E30312-DD05-3581-9A59-C3569A981657/GUID-FF3D1D45-1330-3718-920E-D8EB135D2592"><apiname>ImageProcessor::CImgProcessor::InitializeL()</apiname></xref>. </p> <p> <b>Note:</b> By default the initialization of Image Processor is asynchronous. </p> </li> <li id="GUID-0EF128C0-719C-5072-955E-C03E17778D9F"><p>To set an input image call <xref href="GUID-13E30312-DD05-3581-9A59-C3569A981657.dita#GUID-13E30312-DD05-3581-9A59-C3569A981657/GUID-0448A658-7DD6-3767-82FC-1EE64B1CBEE3"><apiname>ImageProcessor::CImgProcessor::SetInputL()</apiname></xref>. </p> </li> <li id="GUID-A80B9E4D-EAE8-5F3F-A880-B15022D0AB4E"><p>To set an output image call <xref href="GUID-13E30312-DD05-3581-9A59-C3569A981657.dita#GUID-13E30312-DD05-3581-9A59-C3569A981657/GUID-D79E1EEA-5054-355E-8E61-E2AF5C7A229D"><apiname>ImageProcessor::CImgProcessor::SetOutputL()</apiname></xref>. </p> </li> <li id="GUID-74D87831-2393-5A6A-95B8-2F922056D014"><p>To retrieve information about an output image call <xref href="GUID-13E30312-DD05-3581-9A59-C3569A981657.dita#GUID-13E30312-DD05-3581-9A59-C3569A981657/GUID-537F658F-3246-3A50-B528-7D801339AD08"><apiname>ImageProcessor::CImgProcessor::TOutputInfo()</apiname></xref>. </p> </li> <li id="GUID-BCF98768-978D-54AF-B056-67A31342C7B8"><p>To set quality for an output image (in the case of JPEG output) call <xref href="GUID-408690CC-6F47-31B2-90B6-95C4049FEFFB.dita#GUID-408690CC-6F47-31B2-90B6-95C4049FEFFB/GUID-24974F21-B5D7-32DD-B8D8-757A2BA0AA55"><apiname>TOutputInfo::SetJpegQualityL(TReal32&amp; )</apiname></xref>. </p> </li> <li id="GUID-D5BCC7BF-8885-5A27-AF86-D06D63CFE8B7"><p>To process an input image and create the output image call <xref href="GUID-13E30312-DD05-3581-9A59-C3569A981657.dita#GUID-13E30312-DD05-3581-9A59-C3569A981657/GUID-81D98D3A-7B5A-3D2E-81CE-A3F2F3D5BCA5"><apiname>ImageProcessor::CImgProcessor::ProcessL()</apiname></xref>. </p> </li> </ul> <p><b>Example </b> </p> <codeblock id="GUID-8A927236-96E7-5A32-BD97-29A688BBE6A3" xml:space="preserve">

 ImageProcessor::ImageProcessor::CImgProcessor* imageProcessor = ImageProcessor::ImageProcessor::CImgProcessor::NewL(iFs, observer);

    CleanupStack::PushL(imageProcessor);

    // Initialize the Image Processor instance. By default the initialization is asynchronous.

    // (It might take some time to load Image Processor plugin and initialize it).

    imageProcessor->InitializeL();

    // Wait for asynchronous callback

    CActiveScheduler::Start();

    // Set input and output images

    imageProcessor->SetInputL(KInputFileName, KImageTypeJPGUid);

    imageProcessor->SetOutputL(KOutputFileName, KImageTypeJPGUid);

    // Get the TOutputInfo interface

    TOutputInfo* outputInfo = imageProcessor->OutputInfoL();

    // Set 0.75 quality for an output image.

    // (Note. Default quality value for an output image is the same as for the input image.)

    TReal32 quality = 0.75f;

    outputInfo->SetJpegQualityL(quality);

    // Process the input image to an output image. 

    // an output image size is QVGA and an output image keeps the same aspect ration as the input image.  

    imageProcessor->ProcessL(TSize(320, 240), ETrue);

    // Wait for asynchronous callback

    CActiveScheduler::Start();

    CleanupStack::PopAndDestroy(); //imageProcessor

</codeblock> </section> </conbody><related-links><link href="GUID-F221B15F-B5DE-516F-8FB0-75C1971DB3AF.dita"><linktext>Adding Effects And Filters

                Guide</linktext> </link> <link href="GUID-03866ADB-5916-5B31-BCF0-44F94E12B740.dita"><linktext>Pluggable Advanced Image Editing

                Libraries</linktext> </link> </related-links></concept>