Working with the Histogram

This document introduces how to work with a histogram.

Purpose

This document describes the various APIs for working with a Histogram.

Introduction

A histogram provides details about the exposure and light on a scene. You can use the histogram to adjust the screen settings accordingly.

The code in this tutorial can be found in ecamextendedfunctest.cpp.

Working with a Histogram

The high level steps to work with histogram are shown here:

Make sure that you call CCameraV2Histogram::PrepareClientHistogramL before calling CCameraV2Histogram::StartHistogram API.
Use CCameraV2Histogram::StartHistogram call to start getting histogram notifications once a direct or a client based histogram is prepared.
Use CCamera::CCameraV2Histogram::GetHistogramStateL to get the list of histograms that are currently active. A histogram continues to be in an active state if StartHistogram() has been called on it and has not been yet stopped.
Use GetDirectHistogramPropertiesL API to get the current properties used by a direct histogram.
Call UpdateDirectHistogramPropertiesL API to update the properties of a direct histogram with the new values and call GetDirectHistogramPropertiesL to verify it.

Receiving Histograms

The histogram data is received as follows:

Use MDirectViewFinderObserver::ClientHistogramReady call back to notify the client about availability of the histogram data.
If a call to CCameraV2Histogram::StartHistogram is made without a previous successful call to CCameraV2Histogram:: + PrepareClientHistogramL, the callback returns KErrBadHandle.
This provides a pointer to MHistogramV2Buffer that retrieves a single histogram.
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.

Example

The following example illustrates the sequence for working with a histogram for client viewfinder.

Start a histogram.
histogram_CVF->StartHistogram();
Confirm whether a specific histogram is active.
TBool histogramActive = EFalse; +histogram_CVF->GetHistogramStateL(histogramActive);
Get the current properties of a direct histogram.
CCamera::CCameraV2Histogram::TDirectHistogramParameters histogramParameters; +histogram_CVF->GetDirectHistogramPropertiesL(histogramParameters);
Update the properties of histogram with the new values.
CCamera::CCameraV2Histogram::TDirectHistogramParameters histogramParameters; +histogram_CVF->UpdateDirectHistogramPropertiesL(histogramParameters);