Onboard Camera Overview

This document introduces you to the Onboard Ecam API.

Purpose

The Onboard Camera provides functionality to control a digital camera and to request and receive specific image data from it. Still or video images may be captured. A camera may be controlled with its output media going into a non-Symbian platform sink (for example, into hardware), or it may be controlled with output going into the Symbian platform.

The API defines basic common operations, but is also extensible to allow for proprietary properties.

Onboard Ecam API Library Details

The DLL that provides the functionality and the library to which your code must link is identified below.

DLL LIB Short Description

ecam.dll

ecam.lib

These files are used for implementing the Onboard Camera functions.

Architectural Relationship

The Onboard Camera provides images to clients. A client may be an application with image requirements, or the Multimedia Framework. Clients have specific priorities and may pre-empt others in their interactions with the camera.

Licensees and partners implement the camera functionality for the camera hardware on their phone. All cameras are ECom plug-ins sub-classed from the CCameraPlugin class.

When a new camera object is required, the ECam library requests a camera plug-in from the ECom framework. When more than one ROM based plug-ins have been registered on the platform, the one with the highest version defined in its resource file is selected.

Description

Client Applications can use the onboard camera function for a number of tasks, including:

Controlling camera power, using the view finder, making basic camera image settings, capturing a still image, capturing video, making advanced settings, getting snapshots, getting image histograms, using image overlays, using preset camera settings, image processing on the camera.

Key Onboard Ecam API Classes

The key classes that make up the Onboard Camera are as follows:

  • CCamera

    It provides the base class for camera devices. This is the interface that the client application uses to communicate with the camera. It provides all the functions necessary to control, and acquire images from, the camera.

  • MCameraObserver2

    It is an observer class which permits access to picture data as descriptors, bitmaps or chunks. It defines an event-handling interface that is called when events are generated from use of the camera functions, or from external sources such as the camera being plugged or unplugged.

    MCameraObserver is an earlier version of this callback interface.

  • TCameraInfo

    It provides information about the camera. This includes: the version number and name of camera hardware, camera orientation, whether the camera supports still image capture and so on.

  • MCameraBuffer

    It is the buffer class used by MCameraObserver2 to pass back view finder data, images and video frames. It enables the client to choose in which way it accesses the picture data (descriptor, bitmap or kernel chunk).

  • TECAMEvent

    It is a simple event class containing a UID to identify the event and a status code. It is passed to MCameraObserver2 as functional argument using HandleEvent method, when a request is completed. The request is complete, if a control of the camera switches, camera hardware settings changes, or due to external events such as the camera being plugged in.

    Use a derived version of TECAMEvent and TECAMEvent2 to pass additional information required by extended API to the API client along with the error event code.

  • CCamera::CCameraAdvancedSettings

    It provides domain specific get and set methods for well known camera hardware settings that relate directly to the image acquisition phase for both still images and video.

  • CCamera::CCameraPresets

    It associates a single command with setting of several camera parameters to specific values (and ranges). The class allows clients without knowledge of the camera specifics to achieve comparable results for different cameras.

  • CCamera::CCameraImageProcessing

    It is used to perform image processing operations on still images, video, viewfinder (both client and direct). These include brightness, contrast, gamma, hue, sharpness and saturation adjustments on the camera. The client is also able to perform simple image transformations like cropping, rotation, mirroring, scaling, noise reduction and glare reduction.

  • CCamera::CCameraOverlay

    It allows the client to overlay an image onto the view finder, snapshots, still images, and video.

  • CCamera::CCameraHistogram allows the client to get histogram data ( MHistogramBuffer ) in a specified format for an image, such as a luminance-based, or average colour value histogram.

    This class is deprecated, so use CCamera::CCameraV2Histogram class.

  • CCamera::CCameraSnapshot

    It allows the client to request snapshot data in a specified image format for both still images and video. Snapshot object can be created specifically for still images and video APIs.

  • CCamera::CCameraDirectViewFinder used for those viewfinders that use only viewfinder APIs of Ccamera. It provides support for Direct View Finder functionalities, such as pause and resume. see also Viewfinder API Overview .

  • CCamera::CCameraClientViewFinder

    It provides support for multiple client View Finder.

  • CCamera::CCameraPreImageCaptureControl

    It allows to control image operations or its settings prior to image capture.

  • CCamera::CCameraImageCapture

    It captures the image and controls the overall capture.

  • CCamera::CCameraPostImageCaptureControl

    It retrieves the image data from individual images and also controls the captured images individually.

  • CCamera::CCameraVideoCaptureControl

    It controls the operations related to video capture.

The class diagram of CCamera is shown below:

Using Onboard Ecam API

The clients can use CCamera function to control and acquire image data from the camera.