Collapse all Symbian^3 Application Developer Library

CCamera::CCameraSnapshot Class Reference

class CCamera::CCameraSnapshot : public CBase

This class allows the client to request snapshot data in a specified image format for both still images and video.

Snapshot object may be created out of new classes: CCameraImageCapture and CCameraVideoCaptureControl . The client selects snapshot parameters calling PrepareSnapshotL(const TSnapshotParameters& aSnapshotParameters) . It can then enable and disable the snapshot generation by calling EnableSnapshotL() and DisableSnapshotL() . The client application using this API shall provide MCaptureImageObserver and MCaptureVideoObserver interface. Callbacks available are MCaptureImageObserver :: ClientSnapshotForImageReady and MCaptureVideoObserver::ClientSnapshotReady .

Snapshots are supposed to be displayed on a particular viewfinder. So, while destruction, client shall destroy snapshot first. In general, child objects shall be destroyed before the parent objects.

Following is valid for older clients who created snapshots using NewL method:- The client selects snapshot parameters calling PrepareSnapshotL() . It can then start and stop receiving notifications from the ECam implementation by calling StartSnapshot() and StopSnapshot() . The client application using this API should provide MCameraObserver2 interface to be signalled, with event KUidECamEventCameraSnapshot, when snapshot data is available to be retrieved from the ECam implementation. The client can then retrieve the snapshot data from the ECam implementation calling SnapshotDataL() .

Note:

This class provides a standardised client interface for the camera snapshot. Classes cannot be derived from it.

If the class methods leave, the output type parameter value is not guaranteed to be valid.

Inherits from

CCamera::CCameraSnapshot
- CBase

Nested Classes and Structures

CCamera::CCameraSnapshot::TSnapshotParameters

Public Member Functions
	~CCameraSnapshot ()
IMPORT_C CCamera::CCameraV2Histogram *	CreateHistogramHandleL ()
IMPORT_C void	DisableSnapshotL ()
IMPORT_C void	EnableSnapshotL ()
IMPORT_C void	GetSnapshotParametersL ( TSnapshotParameters &)
IMPORT_C void	GetSnapshotStatusL ( TSnapshotState &)
IMPORT_C TBool	IsSnapshotActive ()
IMPORT_C CCameraSnapshot *	NewL ( CCamera &)
IMPORT_C void	PrepareSnapshotL ( CCamera::TFormat , const TPoint &, const TSize &, const TRgb &, TBool )
IMPORT_C void	PrepareSnapshotL ( CCamera::TFormat , const TSize &, TBool )
IMPORT_C void	PrepareSnapshotL (const TSnapshotParameters &)
IMPORT_C void	SelectSnapshotVideoFramesL ( TSnapshotVideoFrames )
IMPORT_C void	SetBgColorL (const TRgb &)
IMPORT_C void	SetPositionL (const TPoint &)
IMPORT_C void	SetSnapshotParametersL (const TSnapshotParameters &)
IMPORT_C MCameraBuffer &	SnapshotDataL ( RArray < TInt > &)
IMPORT_C void	StartSnapshot ()
IMPORT_C void	StopSnapshot ()
IMPORT_C TUint32	SupportedFormats ()

Private Member Functions
	CCameraSnapshot ( CCamera &)
void	ConstructL ()
void	ConstructL (const MImplementationFactory &, TInt )
IMPORT_C CCameraSnapshot *	CreateL ( CCamera &, MImplementationFactory &, TInt )

Inherited Functions
	CBase::CBase()
	CBase::Delete(CBase *)
	CBase::Extension_(TUint,TAny &,TAny )
	CBase::operator new(TUint)
	CBase::operator new(TUint,TAny *)
	CBase::operator new(TUint,TLeave)
	CBase::operator new(TUint,TLeave,TUint)
	CBase::operator new(TUint,TUint)
	CBase::~CBase()

Public Member Enumerations
enum	TSnapshotState { ESnapshotNotCreated , ESnapshotInactive , ESnapshotActive , ESnapshotDisabled }
enum	TSnapshotVideoFrames { ESnapshotVideoFirstFrame , ESnapshotVideoLastFrame , ESnapshotVideoFirstAndLastFrame , ESnapshotVideoEveryFrame }

Private Attributes
MCameraSnapshot *	iImpl
MCameraSnapshot2 *	iImpl2
CCamera &	iOwner

Constructor & Destructor Documentation

CCameraSnapshot(CCamera &)

CCameraSnapshot

(

CCamera &

aOwner

)

[private]

Constructor for the CCamera::CCameraSnapshot class.

Parameters

CCamera & aOwner

A reference to the camera object for which a camera snapshot object is to be created.

~CCameraSnapshot()

IMPORT_C

~CCameraSnapshot

(

)

Destructor for the CCamera::CCameraSnapshot class.

Note:

The child objects(for example,hisotgrams) created out of this snapshot class object shall be delete beforehand.

Member Functions Documentation

ConstructL()

void

ConstructL

(

)

[private]

CCameraSnapshot second phase constructor.

This function is used to initialise internal state of the object. It uses reference to the camera to retrieve snapshot interface pointer.

leave: KErrNotSupported if this functionality is not supported; also any system wide error.

ConstructL(const MImplementationFactory &, TInt)

void	ConstructL	(	const MImplementationFactory &	aImplFactory,
			TInt	aClientViewFinderId
		)	[private]

CCameraSnapshot second phase constructor

Function used to initialise internal state of the object specifically for image capture or video capture. This may be used in other possible cases as well.

leave: KErrNoMemory Out of memory; or any other error code as well.

Note:

This method is supposed to be used by this class only.

Parameters

const MImplementationFactory & aImplFactory	A constant reference to the MImplementationFactory derived object.
TInt aClientViewFinderId	The client viewfinder on which this client snapshot will be displayed.

CreateHistogramHandleL()

IMPORT_C CCamera::CCameraV2Histogram *

CreateHistogramHandleL

(

)

const

Retrieve pointer to histogram API in order to use it specifically for snapshots.

leave: May leave with any error code.

Note:

Different types of histogram may be used for a snapshot. Every time this method will be called on the CCameraSnapshot class object, a new type of histogram will be created.

CreateL(CCamera &, MImplementationFactory &, TInt)

IMPORT_C CCameraSnapshot *	CreateL	(	CCamera &	aCamera,
			MImplementationFactory &	aImplFactory,
			TInt	aClientViewFinderId
		)	[private, static]

Factory function that creates a new camera snapshot object specifically for image capture or video capture.

leave: KErrNoMemory if out of memory; also any system wide error.

Parameters

CCamera & aCamera	A reference to the camera object for which a camera snapshot object is to be created.
MImplementationFactory & aImplFactory	A reference to the MImplementationFactory derived object.
TInt aClientViewFinderId	The client viewfinder on which this client snapshot will be displayed.

DisableSnapshotL()

IMPORT_C void

DisableSnapshotL

(

)

Deactivates the snapshot feature if it is active.

Once the snapshot has been deactivated, the client will no longer receive notifications about snapshots.

leave: KErrNotSupported if the implementation of this method is not present.

EnableSnapshotL()

IMPORT_C void

EnableSnapshotL

(

)

Activates the snapshot feature. Calls to this method when the snapshot feature is already active will be ignored.

The client will not receive snapshot notifications until the snapshot feature is activated.

Client shall implement the observers: MCaptureImageObserver and MCaptureVideoObserver . Snapshot notifications will be send to the clients via these observers and not through events.

leave: KErrNotSupported if the implementation of this method is not present.

GetSnapshotParametersL(TSnapshotParameters &)

IMPORT_C void

GetSnapshotParametersL

(

TSnapshotParameters &

aSnapshotParameters

)

Retrieves the snapshot parameters used by the ECam implementation for snapshot creation.

leave: May leave with any error code.

Note:

This method is used to retrieve snapshot parameters.

Parameters

TSnapshotParameters & aSnapshotParameters

Retrieves the currently used snapshot parameters.

GetSnapshotStatusL(TSnapshotState &)

IMPORT_C void

GetSnapshotStatusL

(

TSnapshotState &

aSnapshotState

)

const

Retrieves the current status for the snapshot.

leave: May leave with any error code.

Note:

This method is used to retrieve the snapshot status.

Parameters

TSnapshotState & aSnapshotState

Retrieves information about the snapshot current state.

IsSnapshotActive()

IMPORT_C TBool

IsSnapshotActive

(

)

const

Use void GetSnapshotStatusL(CCamera::CCameraSnapshot::TSnapshotState& aSnapshotState) const ;

Determines if the snapshot feature is active.

NewL(CCamera &)

IMPORT_C CCameraSnapshot *

NewL

(

CCamera &

aCamera

)

[static]

Factory function that creates a new camera snapshot object on the heap.

leave: KErrNoMemory if out of memory; also any system wide error.

Note:

This will be deprecated shortly. Snapshot should be used via CCameraImageCapture::GetSnapshotHandleL() or CCameraVideoCaptureControl::GetSnapshotHandleL() .

Clients using MCameraObserver are not recommended to use this extension class since they cannot handle events.

Parameters

CCamera & aCamera

A reference to the camera object for which a camera snapshot object is to be created.

PrepareSnapshotL(CCamera::TFormat, const TPoint &, const TSize &, const TRgb &, TBool)

IMPORT_C void	PrepareSnapshotL	(	CCamera::TFormat	aFormat,
			const TPoint &	aPosition,
			const TSize &	aSize,
			const TRgb &	aBgColor,
			TBool	aMaintainAspectRatio
		)

Use void PrepareSnapshotL(const CCamera::CCameraSnapshot::TSnapshotParameters& aSnapshotParameters) ;

Sets the properties of the snapshot data including the background colour and the position of the snapshot.

leave: KErrNotSupported if the specified image format is not supported; also any system wide error.

Parameters

CCamera::TFormat aFormat	The image format that the snapshot must have.
const TPoint & aPosition	The top left corner position (in pixels) which determines the layout of the snapshot image within the dimensions provided by the aSize parameter when the snapshot has been scaled maintaining its aspect ratio. See also SetPositionL().
const TSize & aSize	The size of the snapshot in pixels.
const TRgb & aBgColor	The background colour to be used if the snapshot has been scaled (maintaining its aspect ratio) and does not fully fill the dimension provided by the aSize parameter. See also SetBgColorL().
TBool aMaintainAspectRatio	Set to ETrue if the aspect ratio of the snapshot image must be maintained when scaling down.

PrepareSnapshotL(CCamera::TFormat, const TSize &, TBool)

IMPORT_C void	PrepareSnapshotL	(	CCamera::TFormat	aFormat,
			const TSize &	aSize,
			TBool	aMaintainAspectRatio
		)

Use void PrepareSnapshotL(const CCamera::CCameraSnapshot::TSnapshotParameters& aSnapshotParameters) ;

Sets the properties of the snapshot data, excluding the background colour and the position of the snapshot. This method can be used when the client wishes to determine the layout and background colour after the snapshot image has been generated. See also SetPositionL() and SetBgColorL() .

leave: KErrNotSupported if the specified image format is not supported; also any system wide error.

Parameters

CCamera::TFormat aFormat	The image format that the snapshot must have.
const TSize & aSize	The size of the snapshot in pixels.
TBool aMaintainAspectRatio	Set to ETrue if the aspect ratio of the snapshot image must be maintained when scaling down.

PrepareSnapshotL(const TSnapshotParameters &)

IMPORT_C void

PrepareSnapshotL

(

const TSnapshotParameters &

aSnapshotParameters

)

Sets the properties of the snapshot. ECam implementation may use a different size than that specified by this method. GetSnapshotParametersL may be used by the client know the actual parameters being used for snapshot creation.

leave: May leave with any error code.

Note:

This method is used to provide snapshot parameters.

Parameters

const TSnapshotParameters & aSnapshotParameters

The snaspshot parameters.

SelectSnapshotVideoFramesL(TSnapshotVideoFrames)

IMPORT_C void

SelectSnapshotVideoFramesL

(

TSnapshotVideoFrames

aSnapshotVideoFrames

)

The method specifies the frames to be used from video captured data in order to create snapshot for video.

leave: May leave with any error code.

Parameters

TSnapshotVideoFrames aSnapshotVideoFrames

A TSnapshotVideoFrames used to specify the desired frames to be used for creating snapshots for video.

SetBgColorL(const TRgb &)

IMPORT_C void

SetBgColorL

(

const TRgb &

aBgColor

)

Use void SetSnapshotParametersL(const CCamera::CCameraSnapshot::TSnapshotParameters& aSnapshotParameters) ;

Sets the background colour to be used if the snapshot has been scaled (maintaining its aspect ratio) and does not fully fill the snapshot size as specified in PrepareSnapshot().

leave: KErrNotSupported if the specified image format is not supported; also any system wide error.

Parameters

const TRgb & aBgColor

The new background colour.

SetPositionL(const TPoint &)

IMPORT_C void

SetPositionL

(

const TPoint &

aPosition

)

Use void SetSnapshotParametersL(const CCamera::CCameraSnapshot::TSnapshotParameters& aSnapshotParameters) ;

Sets the top left corner position (in pixels), where the snapshot should be laid out after scaling down (maintaining its aspect ratio). The position is within the dimensions provided by the snapshot size specified in PrepareSnapshot().

leave: KErrNotSupported if the specified image format is not supported; also any system wide error.

Parameters

const TPoint & aPosition

The top left corner position in pixels of the snapshot.

SetSnapshotParametersL(const TSnapshotParameters &)

IMPORT_C void

SetSnapshotParametersL

(

const TSnapshotParameters &

aSnapshotParameters

)

Sets/updates the snapshot parameters.

leave: May leave with any error code.

Note:

This method is used to set/update snapshot parameters.

Parameters

const TSnapshotParameters & aSnapshotParameters

The desired snapshot parameters.

SnapshotDataL(RArray< TInt > &)

IMPORT_C MCameraBuffer &

SnapshotDataL

(

RArray < TInt > &

aFrameIndexOrder

)

Use callbacks: MCaptureImageObserver::ClientSnapshotForImageReady and MCaptureVideoObserver::ClientSnapshotReady

Returns the snapshot data from ECam implementation to the client.

The data is returned in an MCameraBuffer object. In the case where the driving mode returns more than one image (burst mode, bracket mode, etc.) the buffer contains several snapshots which may be returned in any order. The aFrameIndexOrder array provides the image sequence numbers in the order in which the snapshots for those images are returned within the MCameraBuffer .

Note:

The client application using this API should provide MCameraObserver2 interface to be signalled when snapshot data is available to be retrieved from the ECAM implementation.

KUidECamEventCameraSnapshot

leave: KErrNoMemory if the ECam implementation has not been able to create the camera buffer; also any system wide error.

Parameters

RArray < TInt > & aFrameIndexOrder

A reference to an array that will receive the image sequence numbers in the order to which the snapshots within MCameraBuffer relate.

StartSnapshot()

IMPORT_C void

StartSnapshot

(

)

Use void EnableSnapshotL() ;

Activates the snapshot feature. Calls to this method when the snapshot feature is already active will be ignored.

The client will not receive snapshot notifications until the snapshot feature is activated.

KUidECamEventCameraSnapshot

StopSnapshot()

IMPORT_C void

StopSnapshot

(

)

Use void DisableSnapshotL() ;

Deactivates the snapshot feature if it is active.

Once the snapshot has been deactivated, the client will no longer receive notifications about snapshots.

SupportedFormats()

IMPORT_C TUint32

SupportedFormats

(

)

Gets a list of camera formats for which the ECam implementation supports snapshots.

Member Enumerations Documentation

Enum TSnapshotState

Describes the state of snapshot. The enumeration list may be extended in future.

Enumerators

ESnapshotNotCreated	Snapshot has not been prepared.
ESnapshotInactive	Snapshot has been prepared but not yet enabled.
ESnapshotActive	Snapshot has been prepared and enabled but not yet disabled.
ESnapshotDisabled	Snapshot has been disabled.

Enum TSnapshotVideoFrames

Specifies the video frames to be used in order to create snapshots fo video. The enumeration list may be extended in future.

Enumerators

ESnapshotVideoFirstFrame	Snapshot for video created from first video frame. Used by default.
ESnapshotVideoLastFrame	Snapshot for video created from last video frame.
ESnapshotVideoFirstAndLastFrame	Snapshot for video created from first and last video frame.
ESnapshotVideoEveryFrame	Snapshot for video created from every video frame.

Member Data Documentation

MCameraSnapshot * iImpl

MCameraSnapshot *

iImpl

[private]

MCameraSnapshot2 * iImpl2

MCameraSnapshot2 *

iImpl2

[private]

CCamera & iOwner

CCamera &

iOwner

[private]