CS000904 - Capturing an image
捕捉一个图像
==================================================================
Knowledge Base Home
ID CS000904 Creation date April 17, 2008
Platform S60 3rd Edition, MR Tested on devices Nokia N95 8GB
Category Symbian C++ Subcategory Imaging
Keywords (APIs, classes, methods, functions):
CCamera, MCameraObserver, CCamera::Reserve(), CCamera::PowerOn(), CCamera::CaptureImage(),
MCameraObserver::ReserveComplete(), MCameraObserver::PowerOnComplete(), MCameraObserver::ImageReady()
======================================================================================
Overview
This snippet demonstrates how to capture an image using the Camera API (ecam.lib). Basically, the flow of operations goes like this:
1. A camera controller that acts as an interface between the UI and the camera engine is created (here, in CAppUi).
2. CCameraController::InitializeCameraL() is called. It will initialize the camera engine and reserve the camera.
3. Reserving the camera is an asynchronous operation. On completion, the MCameraObserver::ReserveComplete() function will be called (or actually the CCameraEngine::ReserveComplete() function, because CCameraEngine implements MCameraObserver interface).
4. The camera is powered on (CCamera::PowerOn()). This, too, is an asynchronous operation. Eventually, it will call MCameraObserver::PowerOnComplete().
5. The PowerOnComplete() function prepares the capture and sets the engine to idle state.
6. When the picture is needed, CCameraController::SnapL() is called. This will delegate the command to the engine (CCameraEngine::SnapL()), which in turn delegates it to the actual camera (CCamera::CaptureImage()).
7. Capturing an image is an asynchronous operation, which will call MCameraObserver::ImageReady() on completion.
This snippet can be self-signed.
---------------------------------------------------------------------------------------------------
这个代码片段说明如何使用Camera API 来捕获一张图片。其操作流程基本如下:
1.创建一个照相机控制器,作为UI和照相机引擎的接口
2.调用 CCameraController::InitializeCameraL(),初始化相机引擎 并 为程序保留相机
3.保留相机是异步的操作,完成后MCameraObserver::ReserveComplete()被调用,
或者实际上是调用了 CCameraEngine::ReserveComplete() ,因为CCameraEngine实现了MCameraObserver的接口。
4.启动相机也是一个异步操作(CCamera::PowerOn()),最后,他会调用 MCameraObserver::PowerOnComplete()。
5.PowerOnComplete()函数准备捕获并设置引擎到空闲状态。
6.需要捕获图片时,调用CCameraController::SnapL(),这会委托调用 CCameraEngine::SnapL(),接下来会委托给 实际的相机 CCamera::CaptureImage()。
7.捕获图片是一个异步操作,完成时会调用MCameraObserver::ImageReady()。
===================================================================
MMP file
--------------------------------------------------------------
The following capabilities and libraries are required:
CAPABILITY UserEnvironment
----------------------------------------------------
LIBRARY ecam.lib
========================================================
Header file: Camera.hrh
-------------------------------------------------------------
#ifndef __CAMERA_HRH_
#define __CAMERA_HRH_
enum TEngineState
{
EEngineNotReady,
ECameraReserved,
EEngineIdle,
ESnappingPicture
};
#endif /*__CAMERA_HRH_*/
==========================================================
Header file: CCameraController.h
------------------------------------------
#ifndef __CCAMERACONTROLLER_H_
#define __CCAMERACONTROLLER_H_
#include <e32base.h> // CBase
#include "Camera.hrh"
// Forward declarations
class CCameraEngine;
/**
* Interface between the UI and the camera engine.
*/
class CCameraController : public CBase
{
public: // Constructors and destructor
/**
* Two-phased constructor.
*/
static CCameraController* NewL();
/**
* Destructor.
*/
virtual ~CCameraController();
private: // Constructors and destructor
/**
* Symbian OS default constructor.
*/
CCameraController();
/**
* Symbian OS constructor.
*/
void ConstructL();
public: // New functions
/**
* Initializes the camera.
*/
void InitializeCameraL();
/**
* Snaps an image through the Camera API
*/
void SnapL();
private: // Data
CCameraEngine* iCameraEngine;
};
#endif /*__CCAMERACONTROLLER_H_*/
====================================================================
Source file: CCameraController.cpp
----------------------------------------------------------
#include "Camera.hrh"
#include "CCameraController.h"
#include "CCameraEngine.h"
/*
-------------------------------------------------------------------------------
Two-phased constructor
-------------------------------------------------------------------------------
*/
CCameraController* CCameraController::NewL()
{
CCameraController* self = new (ELeave) CCameraController();
CleanupStack::PushL(self);
self->ConstructL();
CleanupStack::Pop(self);
return self;
}
/*
-------------------------------------------------------------------------------
Destructor. Frees allocated resources.
-------------------------------------------------------------------------------
*/
CCameraController::~CCameraController()
{
delete iCameraEngine;
}
/*
-------------------------------------------------------------------------------
C++ default constructor
-------------------------------------------------------------------------------
*/
CCameraController::CCameraController()
{
}
/*
-------------------------------------------------------------------------------
Symbian OS 2nd phase constructor
-------------------------------------------------------------------------------
*/
void CCameraController::ConstructL()
{
}
/*
-------------------------------------------------------------------------------
Initializes the still image capture engine
-------------------------------------------------------------------------------
*/
void CCameraController::InitializeCameraL()
{
if (!iCameraEngine)
{
iCameraEngine = CCameraEngine::NewL();
iCameraEngine->ReserveCameraL();
}
}
/*
-------------------------------------------------------------------------------
Takes an image
-------------------------------------------------------------------------------
*/
void CCameraController::SnapL()
{
iCameraEngine->SnapL();
}
==========================================================
Header file: CCameraEngine.h
----------------------------------------
#ifndef __CCAMERAENGINE_H_
#define __CCAMERAENGINE_H_
#include <ECam.h> // CCamera, MCameraObserver
#include "Camera.hrh"
class CCameraEngine : public MCameraObserver
{
public: // Constructors and destructor
/**
* Two-phased constructor.
*/
static CCameraEngine* NewL();
/**
* Destructor.
*/
virtual ~CCameraEngine();
private: // Constructors and destructor
/**
* Symbian OS default constructor.
*/
CCameraEngine();
/**
* Symbian OS constructor.
*/
void ConstructL();
private: // Methods from base classes
/**
* From MCameraObserver.
* Gets called when CCamera::Reserve() is completed.
*/
virtual void ReserveComplete(TInt aError);
/**
* From MCameraObserver.
* Gets called when CCamera::PowerOn() is completed.
*/
virtual void PowerOnComplete(TInt aError);
/**
* From MCameraObserver.
* Gets called when CCamera::StartViewFinderBitmapsL() is completed.
*/
virtual void ViewFinderFrameReady(CFbsBitmap& aFrame);
/**
* From MCameraObserver.
* Gets called when CCamera::CaptureImage() is completed.
*/
virtual void ImageReady(CFbsBitmap* aBitmap,
HBufC8* aData, TInt aError);
/**
* From MCameraObserver.
* Gets called when CCamera::StartVideoCapture() is completed.
*/
virtual void FrameBufferReady(MFrameBuffer* aFrameBuffer,
TInt aError);
public: // New Functions
/**
* Takes a picture.
*/
void SnapL();
/**
* Reserves the camera.
*/
void ReserveCameraL();
private: // Data
CCamera* iCamera;
TEngineState iState;
};
#endif /*__CCAMERAENGINE_H_*/
=================================================================
Source file: CCameraEngine.cpp
-----------------------------------------------------
#include "Camera.hrh"
#include "CCameraEngine.h"
/*
-------------------------------------------------------------------------------
Two-phased constructor
-------------------------------------------------------------------------------
*/
CCameraEngine* CCameraEngine::NewL()
{
CCameraEngine* self = new (ELeave) CCameraEngine();
CleanupStack::PushL(self);
self->ConstructL();
CleanupStack::Pop(self);
return self;
}
/*
-------------------------------------------------------------------------------
Destructor. Frees allocated resources.
-------------------------------------------------------------------------------
*/
CCameraEngine::~CCameraEngine()
{
delete iCamera;
}
/*
-------------------------------------------------------------------------------
C++ default constructor
-------------------------------------------------------------------------------
*/
CCameraEngine::CCameraEngine()
{
iState = EEngineNotReady;
}
/*
-------------------------------------------------------------------------------
Symbian OS 2nd phase constructor
-------------------------------------------------------------------------------
*/
void CCameraEngine::ConstructL()
{
// TODO: It is assumed here that the device has a camera.
// Add error handling, if this may not be the case.
// Camera index 0 is the main camera
iCamera = CCamera::NewL(*this, 0);
}
/*
-------------------------------------------------------------------------------
Reserves the camera.
-------------------------------------------------------------------------------
*/
void CCameraEngine::ReserveCameraL()
{
iCamera->Reserve();
// On completion, MCameraObserver::ReserveComplete() will be called
}
/*
-------------------------------------------------------------------------------
Symbian Onboard Camera API observer. Gets called after CCamera::Reserve() is
called.
-------------------------------------------------------------------------------
*/
void CCameraEngine::ReserveComplete(TInt aError)
{
// TODO: Error handling
iState = ECameraReserved;
iCamera->PowerOn();
}
/*
-------------------------------------------------------------------------------
Symbian Onboard Camera API observer. Gets called after CCamera::PowerOn() is
called.
-------------------------------------------------------------------------------
*/
void CCameraEngine::PowerOnComplete(TInt aError)
{
// TODO: Error handling
// Prepare the capture. It is assumed here that the device supports
// capturing in EXIF JPEG format.
CCamera::TFormat format = CCamera::EFormatExif;
const TInt KImageSizeIndex = 1; // 2nd largest image size
iCamera->PrepareImageCaptureL(format, KImageSizeIndex);
// Everything is ready. Set the engine to idle state.
iState = EEngineIdle;
}
/*
-------------------------------------------------------------------------------
Symbian Onboard Camera API observer. Gets called after
CCamera::StartViewFinderBitmapsL() is called.
-------------------------------------------------------------------------------
*/
void CCameraEngine::ViewFinderFrameReady(CFbsBitmap& aFrame)
{
// Not important in this snippet
}
/*
-------------------------------------------------------------------------------
Symbian Onboard Camera API observer. Gets called after CCamera::CaptureImage()
is called.
-------------------------------------------------------------------------------
*/
void CCameraEngine::ImageReady(CFbsBitmap* aBitmap, HBufC8* aData, TInt aError)
{
// TODO: Error handling
// Image saving is not demonstrated in this snippet
// ...
// The engine is ready for another go
iState = EEngineIdle;
}
/*
-------------------------------------------------------------------------------
Symbian Onboard Camera API observer. Gets called once
CCamera::StartVideoCapture() is called.
-------------------------------------------------------------------------------
*/
void CCameraEngine::FrameBufferReady(MFrameBuffer* aFrameBuffer, TInt aError)
{
// TODO: Error handling
// Capturing video is not demonstrated in this snippet
}
/*
-------------------------------------------------------------------------------
Takes a picture
-------------------------------------------------------------------------------
*/
void CCameraEngine::SnapL()
{
// Snapping a picture is only possible if the engine is in idle state
if (iState == EEngineIdle)
{
iState = ESnappingPicture;
iCamera->CaptureImage();
// On completion, MCameraObserver::ImageReady() will be called
}
else
{
User::Leave(KErrNotReady);
}
}
=========================================================
Source file: CAppUi.cpp
-------------------------------------
#include "CCameraController.h"
iCameraController = CCameraController::NewL();
iCameraController->InitializeCameraL();
=============================================================
Postconditions
An image is captured, and CCameraEngine::ImageReady() function is called.
一张图片被捕获,并调用CCameraEngine::ImageReady()
===========================================================================
See also
? CS000905 - Saving a captured image
? S60 Platform: Camera Example with AutoFocus Support