Capturing still images

To capture still images or to use the display as a viewfinder, build your application around the Symbian Ecam camera utility. To make use of the onboard camera to capture an image, the application needs to repeat the steps described in the illustration below.

Figure: The steps required to capture a still image

Important implementation considerations include:

There is a source and binary compatibility break related to the advanced camera features in the Camera API between S60 3rd Edition, Feature Pack 1 and Feature Pack 2. For more information, see Evolution of the Camera API.
The settings you can use in your application depend on what the camera hardware on the device supports.

Capturing still images on a mobile device

To capture images, use the methods of the CCamera and MCameraObserver classes to construct your application. From S60 3rd Edition, Feature Pack 2 onwards you should use the MCameraObserver2 class instead of MCameraObserver in order to access the advanced camera features of the CCamera::CCameraAdvancedSettings class.

To capture still images, follow the steps below:

Initialize the onboard camera.
- Create a camera object using the CCamera::NewL() method. If you are using the MCameraObserver2 class, use CCamera::New2L() instead.
- Reserve the camera for your application using the CCamera::Reserve() method. MCameraObserver::ReserveComplete() is called upon completion. MCameraObserver2 calls for MCameraObserver2::HandleEvent upon completion.
- Switch on the camera power using the CCamera::PowerOn() method. MCameraObserver::PowerOnComplete() is called upon completion. MCameraObserver2 calls for MCameraObserver2::HandleEvent upon completion.
- If needed, share the camera between multiple clients using the CCamera::NewDuplicateL() method. If you are using the MCameraObserver2 class, use CCamera::NewDuplicate2L() instead. This function needs the handle of an existing camera object (use CCamera::Handle()).
Configure the camera settings.
- Before you adjust the settings, make sure the camera hardware supports the particular option. Use CCamera::CameraInfo() to retrieve and TCameraInfo to specify the camera information.
  For example, to find out what image formats are supported by the onboard camera, use the TCameraInfo::iImageFormatsSupported member variable.
- Specify the image format using the TCameraInfo::iImageFormatsSupported method. For a list of possible formats, see CCamera::TFormat.
  
  From S60 3rd Edition onwards, all devices support image capture in EXIF JPEG format (CCamera::EFormatExif), which is encoded with JPEG and requires no additional conversion.
- Specify the desired image size using the CCamera::EnumerateCaptureSizes() method.
- Additionally, you can set, for example, the brightness, contrast, zoom level, flash mode, exposure and white balance of the image. For more information on the options, see the CCamera class.
  
  From S60 3rd Edition, Feature Pack 2 onwards, camera settings such as these are controlled through the CCamera::CCameraAdvancedSettings class. All settings directly under CCamera, can still be used.
- Before you can call CCamera::CaptureImage(), allocate memory and set up image format, size and clipping rectangle using the CCamera::PrepareImageCaptureL() method. This needs to be called only once for multiple captures.
Use the display of the device as a viewfinder by transferring image data from the camera to the display memory.
- Start the transfer of viewfinder data with direct screen access using the CCamera::StartViewFinderDirectL() method.
- Transfer viewfinder data as a bitmap using the CCamera::StartViewFinderBitmapsL() method. MCameraObserver::ViewFinderFrameReady() is called upon completion. MCameraObserver2 calls for MCameraObserver2::ViewFinderReady upon completion.
- Set viewfinder mirroring on and flip the image horizontally using the CCamera::SetViewFinderMirrorL() method.
- Stop the transfer of viewfinder data to the screen using the CCamera::StopViewFinder() method.
Capture the image.
- Capture one or multiple images using the CCamera::CaptureImage() method. MCameraObserver::ImageReady() is called upon completion. MCameraObserver2 calls for MCameraObserver2::ImageBufferReady() upon completion.
To exit the application or to switch it to the background, switch off the camera power using the CCamera::PowerOff() method and release the camera for other applications using the CCamera::Release() method.
The CCamera, MCameraObserver, and MCameraObserver2 classes are defined in the ecam.h header file. Add the following line to the .h file, which is used to deploy the API:
```
#include <ecam.h>
```
Make sure you have correct capabilities information set for your application. You need at least the UserEnvironment capability.
Make sure ecam.lib is accessible to your linker when compiling your application by including it in your mmp file or by editing the project properties in your IDE, depending on your build environment.

Additional information on capturing an image

For a reference example, see S60 Platform: Camera Example with Autofocus Support on Forum Nokia.

For more information on the use of CCamera::CCameraAdvancedSettings, see Symbian Onboard Camera Advanced Settings API on Forum Nokia Developer Community Wiki.