<?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-7022455A-E738-574E-897E-33243482D69A"><title>Working with the Histogram</title><prolog><metadata><keywords/></metadata></prolog><conbody><p>This document introduces how to work with a histogram. </p> <section><title>Purpose</title> <p>This document describes the various APIs for working with a Histogram. </p> <p><b>Introduction</b> </p> <p>A histogram provides details about the exposure and light on a scene. You can use the histogram to adjust the screen settings accordingly. </p> <p>The code in this tutorial can be found in <filepath>ecamextendedfunctest.cpp</filepath>. </p> </section> <section><title> Working with a Histogram</title> <p>The high level steps to work with histogram are shown here: </p> <ul><li id="GUID-828476F7-BA84-58BC-9246-D5F94B2289AA"><p>Make sure that you call <xref href="GUID-F855433B-95B9-3E7E-9DDE-A1DBCB980DE1.dita#GUID-F855433B-95B9-3E7E-9DDE-A1DBCB980DE1/GUID-0D35B5C5-3242-3EAA-8189-CA5012EA395B"><apiname>CCameraV2Histogram::PrepareClientHistogramL</apiname></xref> before calling <xref href="GUID-F855433B-95B9-3E7E-9DDE-A1DBCB980DE1.dita#GUID-F855433B-95B9-3E7E-9DDE-A1DBCB980DE1/GUID-0F2647B2-98E3-398F-8FCB-9863C0A6F72C"><apiname>CCameraV2Histogram::StartHistogram</apiname></xref> API. </p> </li> <li id="GUID-D2E942CF-9423-539F-BF52-FA11AEF0D6AE"><p>Use <xref href="GUID-F855433B-95B9-3E7E-9DDE-A1DBCB980DE1.dita#GUID-F855433B-95B9-3E7E-9DDE-A1DBCB980DE1/GUID-0F2647B2-98E3-398F-8FCB-9863C0A6F72C"><apiname>CCameraV2Histogram::StartHistogram</apiname></xref> call to start getting histogram notifications once a direct or a client based histogram is prepared. </p> </li> <li id="GUID-A4BCC4E9-FFFA-50B1-8151-4614E228D2F4"><p>Use <xref href="GUID-E159F066-0157-34B4-B154-38D120EAB16C.dita#GUID-E159F066-0157-34B4-B154-38D120EAB16C/GUID-3A9CCBAF-C3D5-3AD6-AF6D-27C98E742B06"><apiname>CCamera::CCameraV2Histogram::GetHistogramStateL</apiname></xref> to get the list of histograms that are currently active. A histogram continues to be in an active state if <xref href="GUID-8419ABA6-01E4-3940-98EB-47F18D0C81ED.dita"><apiname>StartHistogram()</apiname></xref> has been called on it and has not been yet stopped. </p> </li> <li id="GUID-06A92DA6-4660-5A2C-BD28-865D3A8F97D4"><p>Use <xref href="GUID-FCEA4D4C-92B9-39DB-9C63-24DECEFF1CE7.dita"><apiname>GetDirectHistogramPropertiesL</apiname></xref> API to get the current properties used by a direct histogram. </p> </li> <li id="GUID-AD451F40-FB9D-5EC2-BD80-405691DED4C4"><p>Call <xref href="GUID-A8127B84-5084-3EF8-A753-A7292D972A88.dita"><apiname>UpdateDirectHistogramPropertiesL</apiname></xref> API to update the properties of a direct histogram with the new values and call <xref href="GUID-FCEA4D4C-92B9-39DB-9C63-24DECEFF1CE7.dita"><apiname>GetDirectHistogramPropertiesL</apiname></xref> to verify it. </p> </li> </ul> </section> <section><title>Receiving Histograms</title> <p>The histogram data is received as follows: </p> <ul><li id="GUID-6FFFD6C3-2012-58C3-A0BF-E2F4CB794A5F"><p>Use <xref href="GUID-3E9347CF-F172-3E7B-B209-7F9836090F61.dita#GUID-3E9347CF-F172-3E7B-B209-7F9836090F61/GUID-2466E5CD-84E6-3864-94EB-94D1FEBC22E7"><apiname>MDirectViewFinderObserver::ClientHistogramReady</apiname></xref> call back to notify the client about availability of the histogram data. </p> </li> <li id="GUID-A12396DA-3B71-5F7F-864D-7E076F84A8AF"><p>If a call to <xref href="GUID-F855433B-95B9-3E7E-9DDE-A1DBCB980DE1.dita#GUID-F855433B-95B9-3E7E-9DDE-A1DBCB980DE1/GUID-0F2647B2-98E3-398F-8FCB-9863C0A6F72C"><apiname>CCameraV2Histogram::StartHistogram</apiname></xref> is made without a previous successful call to <xref href="GUID-F855433B-95B9-3E7E-9DDE-A1DBCB980DE1.dita#GUID-F855433B-95B9-3E7E-9DDE-A1DBCB980DE1/GUID-FDC496E4-45C2-365A-9C47-2FC11289E96F"><apiname>CCameraV2Histogram::
                PrepareClientHistogramL</apiname></xref>, the callback returns <xref href="GUID-25493BDC-2D2E-3CC5-A5FE-A36804A4388A.dita"><apiname>KErrBadHandle</apiname></xref>. </p> </li> <li id="GUID-E5467A2A-AD6D-5C57-A8D0-D2D929D89063"><p>This provides a pointer to <xref href="GUID-717806EB-DF06-30B2-8189-B677DAFC7B4F.dita"><apiname>MHistogramV2Buffer</apiname></xref> that retrieves a single histogram. </p> </li> <li id="GUID-AB0BCD42-5B4D-5269-A8E8-9862A3BC4A20"><p>If the histogram requested is of direct type, it will be directly embedded into the direct viewfinder. If a non direct histogram is requested, the histogram data will be passed to the camera client. </p> </li> </ul> </section> <section><title>Example</title> <p>The following example illustrates the sequence for working with a histogram for client viewfinder. </p> <ol id="GUID-2B1F73EB-02D0-5BE4-9A43-BEAA8A07B462"><li id="GUID-318781AE-7C79-5182-93CA-A96D8DC68CD6"><p>Start a histogram. </p> <codeblock id="GUID-8192A149-1430-52B7-90AA-3D6D566E852A" xml:space="preserve">histogram_CVF-&gt;StartHistogram();</codeblock> </li> <li id="GUID-5ACC39C2-8BD2-53B2-B46D-4C4B722CC9F3"><p>Confirm whether a specific histogram is active. </p> <codeblock id="GUID-D1686DD6-1AF0-5F35-BBAE-83FF6DDEA0E8" xml:space="preserve">TBool histogramActive = EFalse;
histogram_CVF-&gt;GetHistogramStateL(histogramActive);</codeblock> </li> <li id="GUID-B16273A6-1AC9-548C-BF71-4D6DE2EF19BF"><p>Get the current properties of a direct histogram. </p> <codeblock id="GUID-3813992A-C0A9-518E-9E65-4CE7DE815755" xml:space="preserve">CCamera::CCameraV2Histogram::TDirectHistogramParameters histogramParameters;
histogram_CVF-&gt;GetDirectHistogramPropertiesL(histogramParameters);</codeblock> </li> <li id="GUID-CFEEE142-3946-56E9-92BF-13D3F53223A6"><p>Update the properties of histogram with the new values. </p> <codeblock id="GUID-CDA53A75-F526-523F-86B4-F470328E019D" xml:space="preserve">CCamera::CCameraV2Histogram::TDirectHistogramParameters histogramParameters;
histogram_CVF-&gt;UpdateDirectHistogramPropertiesL(histogramParameters);</codeblock> </li> </ol> </section> </conbody><related-links><link href="GUID-C519E523-E908-5185-949C-C1FAC0BAF0D9.dita"><linktext>Histograms</linktext> </link> <link href="GUID-5A5DDB8C-1E70-5B63-96F1-7ABBFA568866.dita"><linktext>Creating Histograms</linktext> </link> <link href="GUID-7F6A463C-2D33-5B6D-9394-DCB55FEEB5A3.dita"><linktext>Stopping Histograms</linktext> </link> </related-links></concept>