sl@0: // Copyright (c) 2005-2009 Nokia Corporation and/or its subsidiary(-ies).
sl@0: // All rights reserved.
sl@0: // This component and the accompanying materials are made available
sl@0: // under the terms of "Eclipse Public License v1.0"
sl@0: // which accompanies this distribution, and is available
sl@0: // at the URL "http://www.eclipse.org/legal/epl-v10.html".
sl@0: //
sl@0: // Initial Contributors:
sl@0: // Nokia Corporation - initial contribution.
sl@0: //
sl@0: // Contributors:
sl@0: //
sl@0: // Description:
sl@0: //
sl@0: 
sl@0: /**
sl@0:  @file
sl@0:  @publishedPartner
sl@0:  @prototype
sl@0: */
sl@0: 
sl@0: #ifndef CAMERASNAPSHOT_H
sl@0: #define CAMERASNAPSHOT_H
sl@0: 
sl@0: #include <ecam.h>
sl@0: #include <gdi.h>
sl@0: #include <ecamcapturecontrol.h>
sl@0: #include <ecam/ecamcommonuids.hrh>
sl@0: #ifdef SYMBIAN_ENABLE_SPLIT_HEADERS
sl@0: #include <ecam/ecamcommonuidsconst.hrh>
sl@0: #endif
sl@0: class MCameraSnapshot;
sl@0: class MCameraSnapshot2;
sl@0: 
sl@0: class MImplementationFactory;
sl@0: 
sl@0: /** 
sl@0: Constant used to specify the default display time. When this default display time is specified by the client, the implementation 
sl@0: may use its own time interval in order to display the direct snapshot data.
sl@0: 
sl@0: @see CCamera::CCameraSnapshot::TSnapshotParameters::iDisplayTime
sl@0: 
sl@0: @publishedPartner
sl@0: @prototype
sl@0: */
sl@0: static const TInt KECamSnapshotDefaultDisplayTime = 0;
sl@0: 
sl@0: /** 
sl@0: The current Version of the TSnapshotParameters class.
sl@0: 
sl@0: @publishedPartner
sl@0: @prototype
sl@0: */
sl@0: static const TUint KECamSnapshotParametersCurrentVersion = 1;
sl@0: 
sl@0: /** 
sl@0: UID used to identify the event that, the request for snapshot has completed successfully.
sl@0: A callback to MCameraObserver2::HandleEvent() will occur when the snapshot data is ready to be retrieved.
sl@0: If a call to StartSnapshot() is made without a successful call to PrepareSnapshotL() then the callback returns KErrNotReady.
sl@0: */
sl@0: static const TUid KUidECamEventCameraSnapshot = {KUidECamEventSnapshotUidValue};
sl@0: 
sl@0: /** 
sl@0: UID used to identify the CCamera::CCameraSnapshot API.
sl@0: This is the UID which is used to obtain the CCameraSnapshot interface, 
sl@0: via a call to CCamera::CustomInterface().
sl@0: 
sl@0: @see KECamSnapshotUidValue
sl@0: @see CCamera::CCameraSnapshot
sl@0: */
sl@0: static const TUid KECamSnapshotUid = {KECamSnapshotUidValue};
sl@0: 
sl@0: /**
sl@0: This class allows the client to request snapshot data in a specified image format for both still images and video.
sl@0: 
sl@0: Snapshot object may be created out of new classes: CCameraImageCapture and CCameraVideoCaptureControl. The client selects 
sl@0: snapshot parameters calling PrepareSnapshotL(const TSnapshotParameters& aSnapshotParameters). It can then enable and 
sl@0: disable the snapshot generation by calling EnableSnapshotL() and DisableSnapshotL(). The client application using this API 
sl@0: shall provide MCaptureImageObserver and MCaptureVideoObserver interface. Callbacks available are MCaptureImageObserver::
sl@0: ClientSnapshotForImageReady and MCaptureVideoObserver::ClientSnapshotReady.
sl@0: 
sl@0: Snapshots are supposed to be displayed on a particular viewfinder. So, while destruction, client shall destroy snapshot 
sl@0: first. In general, child objects shall be destroyed before the parent objects.
sl@0: 
sl@0: Following is valid for older clients who created snapshots using NewL method:-
sl@0: The client selects snapshot parameters calling PrepareSnapshotL(). It can then start and stop 
sl@0: receiving notifications from the ECam implementation by calling StartSnapshot() and StopSnapshot().
sl@0: The client application using this API should provide MCameraObserver2 interface to be signalled,
sl@0: with event KUidECamEventCameraSnapshot, when snapshot data is available to be retrieved from 
sl@0: the ECam implementation.
sl@0: The client can then retrieve the snapshot data from the ECam implementation calling SnapshotDataL().
sl@0: 
sl@0: @note This class provides a standardised client interface for the camera snapshot. Classes cannot be derived from it.
sl@0: 
sl@0: @note   If the class methods leave, the output type parameter value is not guaranteed to be valid.
sl@0: 
sl@0: @publishedPartner
sl@0: @prototype
sl@0: */
sl@0: 
sl@0: class CCamera::CCameraSnapshot: public CBase
sl@0: 	{
sl@0: 	
sl@0: 	friend class CCamera;
sl@0: 
sl@0: 	friend CCamera::CCameraSnapshot* CCamera::CCameraImageCapture::GetSnapshotHandleL(TInt aClientViewFinderId) const;
sl@0: 	friend CCamera::CCameraSnapshot* CCamera::CCameraVideoCaptureControl::GetSnapshotHandleL(TInt aClientViewFinderId) const;
sl@0: 
sl@0: public:
sl@0: 	/** 
sl@0: 	Describes the state of snapshot. 
sl@0: 	The enumeration list may be extended in future.
sl@0: 	*/
sl@0: 	enum TSnapshotState
sl@0: 		{
sl@0: 		/** Snapshot has not been prepared. */
sl@0: 		ESnapshotNotCreated,
sl@0: 		/** Snapshot has been prepared but not yet enabled. */
sl@0: 		ESnapshotInactive,
sl@0: 		/** Snapshot has been prepared and enabled but not yet disabled. */
sl@0: 		ESnapshotActive,
sl@0: 		/** Snapshot has been disabled. */
sl@0: 		ESnapshotDisabled,
sl@0: 		};
sl@0: 	
sl@0: 	/** 
sl@0: 	Specifies the video frames to be used in order to create snapshots fo video. 
sl@0: 	The enumeration list may be extended in future.
sl@0: 	*/	
sl@0: 	enum TSnapshotVideoFrames
sl@0: 		{
sl@0: 		/** Snapshot for video created from first video frame. Used by default. */
sl@0: 		ESnapshotVideoFirstFrame,
sl@0: 		/** Snapshot for video created from last video frame. */
sl@0: 		ESnapshotVideoLastFrame,
sl@0: 		/** Snapshot for video created from first and last video frame. */
sl@0: 		ESnapshotVideoFirstAndLastFrame,
sl@0: 		/** Snapshot for video created from every video frame. */
sl@0: 		ESnapshotVideoEveryFrame
sl@0: 		};
sl@0: 		
sl@0: 	/**
sl@0: 	Specifes the parameters necessary for client snapshots.
sl@0: 	*/
sl@0: 	class TSnapshotParameters
sl@0: 		{
sl@0: 	public:
sl@0: 		IMPORT_C TSnapshotParameters();
sl@0: 		
sl@0: 		IMPORT_C TUint Size() const;
sl@0: 		IMPORT_C TUint Version() const;
sl@0: 				
sl@0: 		IMPORT_C TBool IsAspectRatioMaintained() const;
sl@0: 		
sl@0: 		IMPORT_C void SetAspectRatioState(TBool aIsAspectRatioMaintained);
sl@0: 		
sl@0: 	private:
sl@0: 		//for future expansion
sl@0: 		TUint iSize:24;
sl@0: 		TUint iVersion:8;
sl@0: 		
sl@0: 		// reserved for future expansion
sl@0: 		TInt iReserved1;
sl@0: 		TInt iReserved2;
sl@0: 		TInt iReserved3;
sl@0: 		
sl@0: 		TInt iReserved5;
sl@0: 		TInt iReserved6;
sl@0: 		TInt iReserved7;
sl@0: 		
sl@0: 		TUint iReserved4:31;
sl@0: 		
sl@0: 		/** Set to ETrue if the aspect ratio of the snapshot image must be maintained when scaling down */
sl@0: 		TUint iIsAspectRatioMaintained:1;
sl@0: 		
sl@0: 	public:
sl@0: 		/** The image format that the snapshot must have. */
sl@0: 		CCamera::TFormat iFormat;
sl@0: 		/** The top left corner position (in pixels) which determines the layout of the snapshot image  
sl@0: 		within the dimensions provided by the iSnapshotSize parameter when the snapshot has been scaled 
sl@0: 		maintaining its aspect ratio. ECam implementation is supposed to calculate the proportion between
sl@0: 		the top left corner and the snapshot size and hence use it, in case, the snapshot size used is different. */
sl@0: 		TPoint iPosition;
sl@0: 		/** The size of the snapshot in pixels. The snapshot size may be changed by the implementation to meet hardware 
sl@0: 		requirements, performance etc. */
sl@0: 		TSize iSnapshotSize;
sl@0: 		};
sl@0: 	
sl@0: public:	
sl@0: 	IMPORT_C static CCameraSnapshot* NewL(CCamera& aCamera);
sl@0: 	
sl@0:     IMPORT_C CCamera::CCameraV2Histogram* CreateHistogramHandleL() const;
sl@0:     
sl@0:   	IMPORT_C TUint32 SupportedFormats();
sl@0: 	
sl@0: 	IMPORT_C void PrepareSnapshotL(CCamera::TFormat aFormat, const TPoint& aPosition, const TSize& aSize, const TRgb& aBgColor, TBool aMaintainAspectRatio);
sl@0: 	IMPORT_C void PrepareSnapshotL(CCamera::TFormat aFormat, const TSize& aSize, TBool aMaintainAspectRatio);
sl@0: 	
sl@0: 	IMPORT_C void SetBgColorL(const TRgb& aBgColor); 
sl@0: 	IMPORT_C void SetPositionL(const TPoint& aPosition);
sl@0: 	
sl@0: 	IMPORT_C TBool IsSnapshotActive() const;
sl@0: 	IMPORT_C void StartSnapshot();
sl@0: 	IMPORT_C void StopSnapshot();
sl@0: 	    	
sl@0: 	IMPORT_C MCameraBuffer& SnapshotDataL(RArray<TInt>& aFrameIndexOrder);
sl@0: 	
sl@0: 	IMPORT_C ~CCameraSnapshot();
sl@0: 	
sl@0: 	IMPORT_C void PrepareSnapshotL(const TSnapshotParameters& aSnapshotParameters);
sl@0: 	
sl@0: 	IMPORT_C void GetSnapshotParametersL(TSnapshotParameters& aSnapshotParameters);
sl@0: 	IMPORT_C void SetSnapshotParametersL(const TSnapshotParameters& aSnapshotParameters); 
sl@0: 	
sl@0: 	IMPORT_C void GetSnapshotStatusL(TSnapshotState& aSnapshotState) const;
sl@0: 	
sl@0: 	IMPORT_C void SelectSnapshotVideoFramesL(TSnapshotVideoFrames aSnapshotVideoFrames);
sl@0: 	
sl@0: 	IMPORT_C void EnableSnapshotL();
sl@0: 	IMPORT_C void DisableSnapshotL();
sl@0: 	
sl@0: private:
sl@0: 	IMPORT_C static CCameraSnapshot* CreateL(CCamera& aCamera, MImplementationFactory& aImplFactory, TInt aClientViewFinderId);
sl@0: 	
sl@0: 	CCameraSnapshot(CCamera& aOwner);
sl@0: 	void ConstructL();
sl@0: 	void ConstructL(const MImplementationFactory& aImplFactory, TInt aClientViewFinderId);
sl@0: 
sl@0: private:	
sl@0: 	CCamera&        iOwner;
sl@0: 	MCameraSnapshot*  iImpl;   // not owned
sl@0: 	MCameraSnapshot2* iImpl2;  // not owned
sl@0: 	};
sl@0: 	
sl@0: #endif // CAMERASNAPSHOT_H