<?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 task

  PUBLIC "-//OASIS//DTD DITA Task//EN" "task.dtd">

<task xml:lang="en" id="GUID-AAA27EE5-E323-5822-A339-690316C2D9B4"><title>Viewfinder's Region of Interest</title><shortdesc>This topic describes how to add area of interest specification and control for viewfinder in the Ecam API. </shortdesc><prolog><metadata><keywords/></metadata></prolog><taskbody><prereq id="GUID-F0AEDC78-B1C7-59FB-AE09-A52813BD902D"><p>Before you start: </p> <ul><li id="GUID-92CA2EA9-8AE9-573A-BCF8-5399DDE53301"><p>Understand <xref href="GUID-367ADFD7-A0F5-59D3-BF83-913CB8126B9D.dita">Overview</xref> of Viewfinder API. </p> </li> </ul> </prereq> <context id="GUID-F2F8630C-5C25-555E-B433-F950BE2D3B0A"><p>The <xref href="GUID-021C509B-C821-3401-B2F4-DE7F52BB16D4.dita"><apiname>CCamera</apiname></xref> API is extended to allow you to give region of interest (ROI) for viewfinder. The areas of interest are approximated by the rectangle shape. You select a preference order for ROIs. This selection of preference is supported by <codeph>CCamera</codeph>. Your selection of preference has higher priority. </p> <p>The ROIs provides multiple uses for <codeph>CCamera</codeph>, they are as follows: </p> <ul><li id="GUID-470B8A6A-B004-5124-8A95-893C1BA5DED6"><p>Extended focus control </p> </li> <li id="GUID-C2F469C9-5D4B-5C8E-A336-0705236833F0"><p>Selection of ROI for 3A algorithms computations (autofocus, automatic exposure and automatic white balance). </p> </li> </ul> </context> <steps id="GUID-4A701EAC-92B4-5098-B641-8E119782FA3B"><step id="GUID-693A56F7-CA46-5C52-B9E0-AC440A59662A"><cmd/><info>Call <xref href="GUID-24FF5ADF-77FD-3F0C-9905-CE9F3AC0144A.dita#GUID-24FF5ADF-77FD-3F0C-9905-CE9F3AC0144A/GUID-F54A4A2C-7C7D-3FED-BDD2-3B370AF9CB17"><apiname>CCameraViewFinder::GetSupportedROIScopeL(TInt&amp;

                )</apiname></xref> to get support and query the number of scope for a viewfinder. For example, If n is the number of ROI scope supported, then scope indices will vary from 0 to –1. </info> </step> <step id="GUID-1E56ECC1-C0B1-5C6E-9006-038F2D3D593C"><cmd/><info>Call <xref href="GUID-24FF5ADF-77FD-3F0C-9905-CE9F3AC0144A.dita#GUID-24FF5ADF-77FD-3F0C-9905-CE9F3AC0144A/GUID-C595C971-DEE6-382C-890F-57E279E5141E"><apiname>CCameraViewFinder::TROIParameters( )</apiname></xref> to provide the ROI per scope to the <codeph>CCamera</codeph> adaptation. The <codeph>TROIParameters</codeph> function is used to allow you to specify a priority with every ROI. </info> </step> <step id="GUID-12CD9C6F-BA8E-5776-9586-0BCFA6DACAF4"><cmd/><info>Call <xref href="GUID-24FF5ADF-77FD-3F0C-9905-CE9F3AC0144A.dita#GUID-24FF5ADF-77FD-3F0C-9905-CE9F3AC0144A/GUID-74970283-BD6F-3E7B-AD58-4DB0249416A9"><apiname>CCameraViewFinder::StartROIOperation(const

                RArray&lt; TROIParameters&gt;&amp;, TInt)</apiname></xref> to perform the operation depending on the ROI scope, <codeph>CCamera</codeph> adaptation adjust the scope priority. </info> <info>When the ROI operation is completed, <codeph>CCamera</codeph> adaptation notifies you the completion of the ROI Operation. You have to know the viewfinder and the scope with which this ROI operation is linked. This can be done by issuing a new event <codeph>KUIdECamEvent2ViewFInderROIReady</codeph> with <codeph>iParam</codeph> as <codeph>iViewFinderHandle</codeph> and <codeph>iParam1</codeph> as <codeph>iROIScopeIndex</codeph>. </info> <info>  Note: You have to prepare a group of the desired region set with high priorities scopes. When you have set the high priorities scopes, you needs to specify the scope based on which the <codeph>CCamera</codeph> adaptation uses the ROIs. </info> </step> <step id="GUID-59F854ED-0EB4-529A-B99B-A12051AC4076"><cmd/><info>Call <xref href="GUID-C8A9654A-AA22-39FE-B1DC-11F49E1D80C1.dita#GUID-C8A9654A-AA22-39FE-B1DC-11F49E1D80C1/GUID-B4DBFB05-BB2D-322B-91D8-45326B340126"><apiname>MDirectViewFInderObserver::ROIChangeReady(CCamera::CCameraV2DirectViewFinder&amp;,

                Tint, Tint)</apiname></xref> to extend the callback associated with the two viewfinders in order to provide the ROI scope notifications. </info> <info>The two notification function notifies you that <codeph>CCamera</codeph> adaptation starts the ROI operation based on the modified set of ROI parameter. </info> </step> <step id="GUID-417A4073-1DC7-5484-B4C6-8413359A229D"><cmd/><info>When the <codeph>CCamera</codeph> adaptation changes the ROI scope, call <xref href="GUID-24FF5ADF-77FD-3F0C-9905-CE9F3AC0144A.dita#GUID-24FF5ADF-77FD-3F0C-9905-CE9F3AC0144A/GUID-94C432C4-EEFC-3A31-8779-5F8698FCF733"><apiname>CCameraViewFinder::GetROIParameters (RArray&lt;

                TROIParameters&gt;&amp;, TInt)</apiname></xref> to retrieve the ROI according to their higher priorities. </info> <info>You can use these regions for any desired purpose depending on the scope. </info> </step> <step id="GUID-578B8B56-46D6-5E3A-B735-2CB1EB19D922"><cmd/><info>Call <xref href="GUID-24FF5ADF-77FD-3F0C-9905-CE9F3AC0144A.dita#GUID-24FF5ADF-77FD-3F0C-9905-CE9F3AC0144A/GUID-B8EBF2A4-3791-3D32-AFE1-8582B2C37654"><apiname>CCameraViewFinder::StopROIOperation(TInt)</apiname></xref> to stop ROI operation for the specific scope. </info> </step> </steps> </taskbody><related-links><link href="GUID-2A6AAD9C-BB99-5145-B4A2-FCEF6BECCFD4.dita"><linktext>Client Viewfinder</linktext> </link> <link href="GUID-BFE8B989-8B73-5D3E-B5F4-13AC016C122C.dita"><linktext>Direct Viewfinder</linktext> </link> </related-links></task>