<?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-5A5DDB8C-1E70-5B63-96F1-7ABBFA568866"><title>Creating Histograms </title><prolog><metadata><keywords/></metadata></prolog><conbody><p>This document introduces how to create a histogram. </p> <section><title>Purpose</title> <p>This document describes the various APIs used to create a Histogram. </p> <p><b>Introduction</b> </p> <p>You can request histograms for image capture, video capture and viewfinder separately or you can combine viewfinder functionality with image or video capture. Histograms provide information about the exposure of light on a captured frame. </p> <p>The key classes are described in <xref href="GUID-3074D4E5-25EA-5DA0-877D-6E3086DCBDB5.dita">Histogram Overview</xref>. </p> </section> <section><title>Creating a Histogram </title> <p>You can create instance of a histogram class from the following class objects: </p> <ul><li id="GUID-A416D08B-D229-5085-95F9-CB5ADC593670"><p>snapshot </p> </li> <li id="GUID-ABC4E85C-D0D5-5987-957F-5AD418DBDD75"><p>image capture </p> </li> <li id="GUID-EC3CB0AE-55C0-5E24-A402-195251A2CD6E"><p>video capture </p> </li> <li id="GUID-929E10C0-3C52-583C-B61A-AB696F22429E"><p>version2 direct viewfinder </p> </li> <li id="GUID-1F8C1088-8A3D-5990-8F11-B57D81E40FED"><p>client viewfinder </p> </li> </ul> <p>This provides better handling of histogram features by tying it closely to the given object. </p> <p> <b>Note</b>: </p> <p>Client is not allowed to create object of this class directly. </p> <p><b>Setup and Configuration Requirements</b> </p> <p>The following are the setup and configuration requirements you need to follow before Histogram implementation: </p> <ul><li id="GUID-90B7676B-A5B6-5B70-AED4-BEF1EFF70C64"><p>Licensees need to provide the implementation of <xref href="GUID-3EE49C9F-944F-3FA0-9B03-0BDCAE63A103.dita"><apiname>CcameraV2Histogram</apiname></xref> and <xref href="GUID-E29318E9-D94F-3576-BA18-400FB8556C27.dita"><apiname>MCameraV2Histogram</apiname></xref> class for the camera v2 histogram. </p> </li> <li id="GUID-7CD76ECD-43FF-5BFF-8297-30C297953114"><p>Clients need to provide the interfaces: <xref href="GUID-B17FB3E0-2650-3DEF-8055-AF283639789E.dita"><apiname>McaptureImageObserver</apiname></xref>, <xref href="GUID-AD4944AA-1C8D-3332-A5BC-4439A0E030C1.dita"><apiname>McaptureVideoObserver</apiname></xref>, <xref href="GUID-05EEF6CC-E007-348C-8643-AA02D634F90C.dita"><apiname>MdirectViewFinderObserver</apiname></xref> and <xref href="GUID-C4F40144-7132-309A-B648-E366786B4DE4.dita"><apiname>MclientViewFinderObserver</apiname></xref> to receive notifications about direct histogram display or client histogram data availability. </p> </li> </ul> <p> <b>Note</b>: </p> <p> <xref href="GUID-BAFF01BC-405C-37B2-8AC3-F96CF756C300.dita#GUID-BAFF01BC-405C-37B2-8AC3-F96CF756C300/GUID-1D73AED2-1EEB-3BC1-A19C-C25A38EDB9BB"><apiname>McameraObserver2::HandleEvent</apiname></xref> will not be used with this class. </p> <p><b>Basic Procedure for Creating Histograms</b> </p> <p>The high level steps to create a histogram are shown here: </p> <ul><li id="GUID-C4F9F1F4-B5C5-53A4-80B6-237CE3FFDF85"><p>Create a new camera histogram object using <xref href="GUID-021C509B-C821-3401-B2F4-DE7F52BB16D4.dita#GUID-021C509B-C821-3401-B2F4-DE7F52BB16D4/GUID-E159F066-0157-34B4-B154-38D120EAB16C"><apiname>CCamera::CCameraV2Histogram</apiname></xref> class. This class allows the client to get histogram data in a specified format for an image. For example, luminance based histogram, average colour value histogram and so on. </p> </li> <li id="GUID-8E9869ED-2215-59A4-8E95-FF38CC611035"><p>This class maps the exported call to a method of mixin class <xref href="GUID-E29318E9-D94F-3576-BA18-400FB8556C27.dita"><apiname>MCameraV2Histogram</apiname></xref>, which provides the camera version 2 histogram functionality. </p> </li> <li id="GUID-80009232-A3F2-5612-B46F-B5AA95D7A71E"><p>Pass a pointer to object of type <xref href="GUID-E29318E9-D94F-3576-BA18-400FB8556C27.dita"><apiname>MCameraV2Histogram</apiname></xref> to the <xref href="GUID-F855433B-95B9-3E7E-9DDE-A1DBCB980DE1.dita"><apiname>CCameraV2Histogram</apiname></xref> object by the owning camera during the construction phase. </p> </li> <li id="GUID-697049C9-803B-5737-AB41-EDE17E5885A1"><p>Obtain this pointer using a call to <xref href="GUID-4E8A5141-5E4A-322A-9892-8DC49D04986E.dita#GUID-4E8A5141-5E4A-322A-9892-8DC49D04986E/GUID-1F537D7D-5451-3834-869D-3092A4773B83"><apiname>Ccamera::CustomInterface()</apiname></xref> with UID value <xref href="GUID-39174B44-20CF-32C8-8264-DAB8ACD054CF.dita"><apiname>KECamMCameraHistogramUid</apiname></xref>. </p> </li> <li id="GUID-4B1CE635-5141-5254-BEBD-EC59ED1F5669"><p>List the type of histograms supported by the camera using <xref href="GUID-FBCDC241-866B-32A0-BE5F-E59C0181AA51.dita"><apiname>GetSupportedHistogramsL()</apiname></xref> API. </p> </li> <li id="GUID-66674E2B-563C-5362-A2B3-E1CFFCDE90BB"><p>Check if direct histogram is supported using <xref href="GUID-ED38DE35-6C52-33C4-868E-E663C7235771.dita"><apiname>GetDirectHistogramSupportInfoL()</apiname></xref> API. </p> </li> <li id="GUID-BCE79AE4-49BD-5CEE-8F8E-FACB9B065FD1"><p>Create a request to prepare a direct or client based histogram using <xref href="GUID-D30FDFEF-054C-39F9-9A6F-11F1FF560D0D.dita"><apiname>PrepareDirectHistogramL()</apiname></xref> or <xref href="GUID-F855433B-95B9-3E7E-9DDE-A1DBCB980DE1.dita#GUID-F855433B-95B9-3E7E-9DDE-A1DBCB980DE1/GUID-10B10333-DD7F-3731-8297-5A4155BD9DD4"><apiname>CCameraV2Histogram::PrepareClientHistogramL()</apiname></xref> APIs appropriately. </p> </li> </ul> </section> <section><title>Example</title> <p>The following example illustrates the sequence for creating a histogram: </p> <ol id="GUID-1B30A03E-6B0C-576A-9387-C03A60AD5D7E"><li id="GUID-BE008E89-0538-5D91-9490-B4943D31569A"><p>The following creates the new camera histogram object. </p> <codeblock id="GUID-D4D5FD9E-FB81-50B2-B8D6-D51EB7E2929F" xml:space="preserve">CCamera* camera;//exists beforehand

CCamera::CCameraClientViewFinder* clientVF;//exists beforehand

MCameraObserver* observer2;//exists beforehand

clientVF  = CCamera::CCameraClientViewFinder::NewL(*camera, *clientVFObserver);    

CCamera::CCameraV2Histogram* histogram_CVF = clientVF-&gt;CreateHistogramHandleL();</codeblock> </li> <li id="GUID-941D2BDE-A9C9-50F9-8D6B-5629A993EE5C"><p>Find out about the supported set of values. </p> <codeblock id="GUID-DC85D107-A94A-523B-AE6C-05CE0CA394A7" xml:space="preserve">TUint supportedHistogramType=0;

histogram_CVF-&gt;GetSupportedHistogramsL(supportedHistogramType);</codeblock> <p>Get the information about direct histograms. </p> <codeblock id="GUID-EF78CBC3-F706-59EE-9251-EA4E9D326081" xml:space="preserve">    TBool directHistogramSupported = EFalse;

histogram_CVF-&gt;GetDirectHistogramSupportInfoL(directHistogramSupported);</codeblock> </li> <li id="GUID-C05F76AD-91A6-5A56-BF92-828B908BF6D7"><p>Prepare the selected or available histogram. </p> <ul><li id="GUID-F8C14127-4F21-58A9-BD4D-A81496F2AA17"><p>direct access </p> <codeblock id="GUID-F7061052-DA32-5437-810F-71CB5C379AB1" xml:space="preserve">Camera::CCameraV2Histogram::TDirectHistogramParameters histogramParameters;

histogram_CVF-&gt;PrepareDirectHistogramL(histogramParameters);</codeblock> </li> <li id="GUID-42AA310D-41B2-5094-A934-A30A75819186"><p>non direct access </p> <codeblock id="GUID-E4EF2CD1-11F4-5368-AB9F-F17CDD9E9C55" xml:space="preserve">CCamera::CCameraV2Histogram::THistogramType histogramType = CCamera::CCameraV2Histogram::Eluminance;