// Copyright (c) 2007-2009 Nokia Corporation and/or its subsidiary(-ies).

// All rights reserved.

// This component and the accompanying materials are made available

// under the terms of "Eclipse Public License v1.0"

// which accompanies this distribution, and is available

// at the URL "http://www.eclipse.org/legal/epl-v10.html".

//

// Initial Contributors:

// Nokia Corporation - initial contribution.

//

// Contributors:

//

// Description:

//

/**

 @file

 @publishedPartner

 @prototype

*/

#ifndef  ECAMCAPTURECONTROL_H

#define  ECAMCAPTURECONTROL_H

#include <e32base.h>

#include <ecam.h>

#include <ecamadvsettings.h>

#ifdef SYMBIAN_ENABLE_SPLIT_HEADERS

#include <ecamconst.h>

#include <ecamadvsettingsconst.h>

#endif

#include <mm/conversioncoefficient.h>

#ifndef SYMBIAN_ENABLE_SPLIT_HEADERS

#include <ecamcapturecontrolconst.h>

#endif

class MCameraPreImageCaptureControl;

class MCameraImageCapture;

class MCameraPostImageCaptureControl;

class MCameraVideoCaptureControl;

class MHistogramV2Buffer;

/** 

Special ImageMaxMemorySize when client does not have any specific preference. Also used when 

this setting of maximum memory size is not supported. 

*/

static const TInt KECamNoSpecificMaxMemorySize = -1;

/** 

The current Version of the TPrepareImageParameters class.

*/

static const TUint KECamPrepareImageParametersCurrentVersion = 1;

/** 

The current Version of the TPrepareVideoParameters class.

*/

static const TUint KECamPrepareVideoParametersCurrentVersion = 1;

/**

The current Version of the TDriveModeDependentAttributes class. 

@publishedPartner

@prototype

*/

static const TUint KECamDriveModeDependentAttributesCurrentVersion = 1;

/**

	Uid used to identify the CCameraPreImageCaptureControl API.

	This API is used to control the pre-imagecapture operations.

	@see CCamera::CCameraPreImageCaptureControl

*/

static const TUid  KECamPreImageCaptureControlUid 	= {KECamPreImageCaptureControlUidValue};

/**

	Uid used to identify the CCameraImageCapture API.

	This API is used to capture the image and perform other control operations after capture the image.

	@see CCamera::CCameraImageCapture

*/

static const TUid  KECamImageCaptureUid 	= {KECamImageCaptureUidValue};

/**

	Uid used to identify the CCameraPostImageCaptureControl API.

	This API is used to control the post-imagecapture operations.

	@see CCamera::CCameraPostImageCaptureControl

*/

static const TUid  KECamPostImageCaptureControlUid 	= {KECamPostImageCaptureControlUidValue};

/**

	Uid used to identify the CCamera Video Capture Control API.

	This API is used to control the video capture operations.

	@see CCamera::CCameraVideoCaptureControl

*/

static const TUid  KECamVideoCaptureControlUid 	= {KECamVideoCaptureControlUidValue};

/** 

Notification that the camera is ready for next prepare. Next prepare can either be still or video.

@note  If drive mode is EDriveModeTimeNudgeCapture this callback will only be received when the client deletes the 

	   existing CCameraImageCapture object as more than one instance can not be created if this drive mode is used.

*/

static const TUid  KUidECamEventReadyForNextPrepare = {KUidECamEventReadyForNextPrepareUidValue};

/** 

Notification that the camera is ready for next capture. Next capture can either be still or video.

@note  If drive mode is EDriveModeTimeNudgeCapture this callback will only be received once the total required amount

	   of images are captured (ie. pre-capture images + 1 + post-capture images) and the implementation is ready with

	   another set of pre-capture images (so implementation is prepared for next CaptureImage() call).

*/

static const TUid  KUidECamEventReadyForNextCapture = {KUidECamEventReadyForNextCaptureUidValue};

/** 

Notification that the image has been exposed to the sensor.

ECam implementation will notify the client that the image has been exposed to the sensor.

@see CCamera::CCameraPreImageCaptureControl::GetCaptureEventSupportInfoL

*/

static const TUid  KUidECamEventImageCaptureEvent = {KUidECamEventImageCaptureEventUidValue};

/**

Specifies the priority which may be assigned to the captured images which are still pending.

The enumeration list may be extended in future.

*/

enum TECamImagePriority

	{

	/** Low Priority */

	EECamImagePriorityLow,

	/** Medium Priority */

	EECamImagePriorityMedium,

	/** Standard Priority */

	EECamImagePriorityStandard,

	/** High Priority */

	EECamImagePriorityHigh,

	/** Very High Priority */

	EECamImagePriorityVeryHigh

	};

/**	

A mixin class to be implemented by the client in order to use the PreImageCaptureControl API. The derived class methods 

are called by the implementation when the pre image capture operations are ready to be notified accordingly.

@see CCamera::CCameraPreImageCaptureControl

*/	

class MPreImageCaptureControlObserver

	{

public:

	/**

	Implementation sends this callback as a result of PrepareImageCapture completion. Every time client calls 

	CCameraPreImageCaptureControl::PrepareImageCapture, a new CCameraImageCapture* will be passed to the client for

	image capture operations. Implementation will create the CCameraImageCapture* object after allocating the memory 

	resources required. Ownership of CCameraImageCapture* object will be passed to the client.

	@param aCaptureImageHandle

		   Retrieves pointer to the CCameraImageCapture object created by the implementation.

	@param aErrorCode

		   Appropriate error code. 

		   KErrECamImageResourceNotReleased when camera device is capable of preparing only still or video.

		   KErrECamVideoResourceNotReleased when camera device is capable of preparing only still or video.

	@note  Every time client needs to change the prepare image settings, a new instance of CCameraImageCapture will be 

		   provided to it by the implementation.

	@note  If error is KErrECamImageResourceNotReleased and client wants to successfully call the Prepare method again, 

		   client needs to delete all CCameraImageCapture objects and any Snapshot and Histogram objects associated with

		   it as well.   

	@note  If error is KErrECamVideoResourceNotReleased and client wants to successfully call the Prepare method again,

		   client needs to call ReleaseVideoResource to unprepare video and then delete any Snapshot and Histogram 

		   objects associated with it as well.

	@note  If drive mode is set to EDriveModeTimeNudgeCapture the client will only receive this callback once the implementation

		   is ready with the number of pre-capture images specified in TDriveModeDependentAttributes.

	*/

	virtual void PrepareImageComplete(CCamera::CCameraImageCapture* aCaptureImageHandle, TInt aErrorCode)=0;

	/**

	Gets a custom interface for future callbacks. This method will be called by the implementation to get a new interface

	which would support future callbacks.

	@param  aInterface

		    The Uid of the particular interface function required for callbacks.

	@param  aPtrInterface

		    The implementation has to type-cast the retrieved custom interface pointer to the appropriate type.	

	@return The error code.

	*/

	virtual TInt CustomInterface(TUid aInterface, TAny*& aPtrInterface)=0;

	}; 

/**

A mixin class to be implemented by the client in order to use the Capture Image API. The derived class methods are 

called by the implementation when the image capture operations are ready to be notified accordingly.

Implementation shall keep track of CCameraImageCapture object deletion. It has to ensure that a callback is not send 

should the client destroy the CCameraImageCapture class object when the callback is queued to be send across. 

Ownership of CCameraImageCapture is retained by the client.

@see CCamera::CCameraImageCapture

@see CCamera::CCameraPostImageCaptureControl

*/

class MCaptureImageObserver

	{

public:

	/**

	Implementation sends this callback to provide client the handle to control individual images to be captured. For

	example, client may want to destroy the image even before the completion for some reasons.

	This callback may be send to the client after the image is exposed to the sensor.

	@param  aCaptureImageHandle

			Reference to CCameraImageCapture class object which was used to issue the capture image operation.

			CCameraPostImageCaptureControl instances will be owned by CCameraImageCapture and would be available until 

			new capture command is issued using the owning CCameraImageCapture instance. If client wishes to initiate new 

			capture but preserve the CCameraPostImageCaptureControl instances from previous capture, it would have to 

			create a new CCameraImageCapture instance and use that for the new capture.

	@param  aPostCaptureControlId

			Id used to identify a particular CCameraPostImageCaptureControl object associated with the given 

			CCameraImageCapture class object. This will be used to control the individual image.

	@note   If, in case, there is some problem at implementation level while the image capture operation, for example, not

			enough memory to create the class object CCameraPostImageCaptureControl, this callback may not be send. In such

			cases, ImageCaptureComplete callback can be send with appropriate error code.

	@note   Whether direct saving option is used or buffers are used for images, this callback will be received in both 

			the cases.

	*/

	virtual void IndividualImageControlHandle(CCamera::CCameraImageCapture& aCaptureImageHandle, TPostCaptureControlId aPostCaptureControlId)=0;

	/**

	Implementation sends this callback when the individual image is ready and direct saving option is not used.

	@param  aCaptureImageHandle

			Reference to CCameraImageCapture class object which was used to issue the capture image operation.

			CCameraPostImageCaptureControl instances will be owned by CCameraImageCapture and would be available until 

			new capture command is issued using the owning CCameraImageCapture instance. If client wishes to initiate new 

			capture but preserve the CCameraPostImageCaptureControl instances from previous capture, it would have to 

			create a new CCameraImageCapture instance and use that for the new capture.

	@param  aPostCaptureControlId

			Id used to identify a particular CCameraPostImageCaptureControl object associated with the given 

			CCameraImageCapture class object. This will be used to retrieve the individual image buffer.

	@param  aErrorCode

			Appropriate error code. 

	@note	If direct saving option is not used, this callback will be received by the client. 

	*/

	virtual void ImageBufferReady(CCamera::CCameraImageCapture& aCaptureImageHandle, TPostCaptureControlId aPostCaptureControlId, TInt aErrorCode)=0;

	/** 

	Implementation sends this callback when a particular client snapshot data is available. The snapshot data represents

	the individual image which may be in any drive mode. 

	If a call to CCameraSnapshot::EnableSnapshotL() (on the CCameraImageCapture instance) is made without a successful call 

	to CCameraSnapshot::PrepareSnapshotL(const TSnapshotParameters& aSnapshotParameters) (on the CCameraImageCapture 

	instance), then the callback returns KErrBadHandle.

	@param  aCaptureImageHandle

			Reference to CCameraImageCapture class object which was used to issue the capture image operation.

	@param  aPostCaptureControlId

			Id used to identify a particular CCameraPostImageCaptureControl object associated with the given 

			CCameraImageCapture class object. This is needed to identify the image which is represented by this snapshot.

	@param  aSnapshotBuffer

			Pointer to MCameraBuffer2 which retrieves the snapshot data for the individual image. The ownership will be 

			retained by the implementation. Client needs to call Release in order to indicate the implementation

			that the buffer can be re-used. Client shall never try to delete the pointer. NULL, if error.

	@param  aErrorCode

			Appropriate error code.

	*/

	virtual void ClientSnapshotForImageReady(CCamera::CCameraImageCapture& aCaptureImageHandle, TPostCaptureControlId aPostCaptureControlId, MCameraBuffer2* aSnapshotBuffer, TInt aErrorCode)=0;

	/** 

	Implementation sends this callback when the cut down version(lower resolution) of the individual image has

	been directly saved to the file.

	Client may use the cut down version of the actual image to view the image beforehand and may cancel the actual

	individual image.

	@param  aCaptureImageHandle

			Reference to CCameraImageCapture class object which was used to issue the capture image operation.

	@param  aPostCaptureControlId

			Id used to identify a particular CCameraPostImageCaptureControl object associated with the given 

			CCameraImageCapture class object. This may be used to cancel the actual image which might be currently 

			undergoing any processing options or even pause/resume ongoing processing options.

	@param  aErrorCode

			Appropriate error code.

	@note	If direct saving option is being used, this callback may be received by the client.

	*/

	virtual void CutDownImageDirectSavingCompleted(CCamera::CCameraImageCapture& aCaptureImageHandle, TPostCaptureControlId aPostCaptureControlId, TInt aErrorCode)=0;

	/** 

	Implementation sends this callback when the individual image has been directly saved to the file.

	This implies that the processing options associated with the image has been finally completed.

	@param  aCaptureImageHandle

			Reference to CCameraImageCapture class object which was used to issue the capture image operation.

			CCameraPostImageCaptureControl instances will be owned by CCameraImageCapture and would be available until 

			new capture command is issued using the owning CCameraImageCapture instance. If client wishes to initiate new 

			capture but preserve the CCameraPostImageCaptureControl instances from previous capture, it would have to 

			create a new CCameraImageCapture instance and use that for the new capture.

	@param  aPostCaptureControlId

			Id used to identify a particular CCameraPostImageCaptureControl object associated with the given 

			CCameraImageCapture class object.

	@param  aErrorCode

			Appropriate error code.

	@note	If direct saving option is being used, this callback will be received by the client.

	*/

	virtual void ImageDirectSavingCompleted(CCamera::CCameraImageCapture& aCaptureImageHandle, TPostCaptureControlId aPostCaptureControlId, TInt aErrorCode)=0;

	/**

	Implementation sends this callback when the Capture Image operation has been completed. This will be send to mark the 

	completion of the image capture even if direct saving option is being used.

	@param  aCaptureImageHandle

			Reference to CCameraImageCapture class object which was used to issue the capture image operation.

			CCameraPostImageCaptureControl instances will be owned by CCameraImageCapture and would be available until 

			new capture command is issued using the owning CCameraImageCapture instance. If client wishes to initiate new 

			capture but preserve the CCameraPostImageCaptureControl instances from previous capture, it would have to 

			create a new CCameraImageCapture instance and use that for the new capture. 

	@param  aErrorCode

			Appropriate error code. 

	@note	This callback marks the completion of image capture operation. So, whether direct saving option is used or 

			buffers are used for images, this callback will be received in both the cases.

	@note  If drive mode is EDriveModeTimeNudgeCapture this callback will only be received once the total required amount

		   of images are captured (ie. pre-capture images + 1 + post-capture images) and the implementation is ready with

		   another set of pre-capture images (so implementation is prepared for next CaptureImage() call).

	*/

	virtual void ImageCaptureComplete(CCamera::CCameraImageCapture& aCaptureImageHandle, TInt aErrorCode)=0;

	/**

	Implementation sends this callback in order to notify the client about availability of the histogram data for the

	individual image. If a call to CCameraV2Histogram::StartHistogram() (on the CCameraImageCapture instance) is made 

	without	a previous successful call to CCameraV2Histogram::PrepareClientHistogramL() (on the CCameraImageCapture 

	instance) then the callback returns KErrBadHandle.

	@param  aCaptureImageHandle

			Reference to CCameraImageCapture class object which was used to issue the capture image operation.

	@param  aPostCaptureControlId

			Id used to identify a particular CCameraPostImageCaptureControl object associated with the given 

			CCameraImageCapture class object. This provides the individual image for which the client histogram data 

			is available.

	@param  aClientHistogramBuffer

			Pointer to MHistogramV2Buffer which retrieves a single histogram for the individual image alongwith 

			relevant information about it. The ownership will be retained by the implementation. Client needs to call 

			Release in order to indicate the implementation that the buffer can be re-used. Client shall never try to 

			delete the pointer. NULL, if error.

	@param  aErrorCode

			Appropriate error code.

	*/

	virtual void ClientHistogramForImageReady(CCamera::CCameraImageCapture& aCaptureImageHandle, TPostCaptureControlId aPostCaptureControlId, MHistogramV2Buffer* aClientHistogramBuffer, TInt aErrorCode)=0;

	/**

	Implementation sends this callback in order to notify the client about availability of the histogram data for the

	snapshot of the individual image. If a call to CCameraV2Histogram::StartHistogram() (on the snapshot) is made without

	a previous successful call to CCameraV2Histogram::PrepareClientHistogramL() (on the snapshot) then the callback 

	returns KErrBadHandle.

	@param  aCaptureImageHandle

			Reference to CCameraImageCapture class object which was used to issue the capture image operation. This 

			provides handle to the snapshot(CCameraImageCapture::GetSnapshotHandleL()) for which the histogram data 

			is available.

	@param  aPostCaptureControlId

			Id used to identify a particular CCameraPostImageCaptureControl object associated with the given 

			CCameraImageCapture class object. This provides a mapping between the individual image and the snapshot for 

			which the client histogram data is available.

	@param  aClientHistogramBuffer

			Pointer to MHistogramV2Buffer which retrieves a single histogram for the snapshot of the individual image 

			alongwith relevant information about it. The ownership will be retained by the implementation. Client needs to call 

			Release in order to indicate the implementation that the buffer can be re-used. Client shall never try to 

			delete the pointer. NULL, if error.

	@param  aErrorCode

			Appropriate error code. 

	*/

	virtual void ClientHistogramForSnapshotReady(CCamera::CCameraImageCapture& aCaptureImageHandle, TPostCaptureControlId aPostCaptureControlId, MHistogramV2Buffer* aClientHistogramBuffer, TInt aErrorCode)=0;

	/**

	Implementation sends this callback in order to notify the client about the failure of processing options for the 

	individual image.

	@param  aCaptureImageHandle

			Reference to CCameraImageCapture class object which was used to issue the capture image operation.

	@param  aPostCaptureControlId

			Id used to identify a particular CCameraPostImageCaptureControl object associated with the given

			CCameraImageCapture class object. This provides the individual image for which the processing options

			has failed.

	@param  aProcessingTypes

			Bitfield of TEcamProcessingOptions associated with the image that have failed.

	@param  aErrorCode

			Appropriate error code.

	*/

	virtual void ProcessingFailed(CCamera::CCameraImageCapture& aCaptureImageHandle, TPostCaptureControlId aPostCaptureControlId, TUint aProcessingTypes, TInt aErrorCode) = 0;

	/**

	Gets a custom interface for future callbacks. This method will be called by the implementation to get a new interface

	which would support future callbacks.

	@param  aInterface

		    The Uid of the particular interface function required for callbacks.

	@param  aPtrInterface

		    The implementation has to type-cast the retrieved custom interface pointer to the appropriate type.	

	@return The error code.

	*/

	virtual TInt CustomInterface(TUid aInterface, TAny*& aPtrInterface)=0;

	};

/** 

CCameraPreImageCaptureControl class exposes an API for controlling image operations/settings prior to image capture. 

@note  This class is not intended for sub-classing and used to standardise existing

       varieties of implementations.

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

@note  Client should not use old Capture methods present in class CCamera. Class CCameraImageCapture and class 

	   CCameraPostImageCaptureControl should be used rather.

@publishedPartner

@prototype

*/

class CCamera::CCameraPreImageCaptureControl : public CBase

	{

	/* so can use internal factory functions etc. */

	friend class CCamera;

public:

	/**

	Specifies the type of direct saving.

	The enumeration list may be extended in future.

	*/

	enum TDirectSavingType

		{

		/** Image saved in buffers. Direct saving to file not being used. Callback used is 

		MCaptureImageObserver::ImageBufferReady. */

		EDirectSavingNotUsed					= 0x00,

		/** Image saved to file as per the format specified. Image saved after any processing options have completed. 

		Callback used is MCaptureImageObserver::ImageDirectSavingCompleted(). */

		EDirectSavingHighResolutionFileOnly		= 0x01,

		/** Image saved to file as per the format specified. Also, a lower resolution image gets saved in a separately 

		specified file. This helps in retrieving the lower resolution image sooner than the higher resolution

		image gets saved. Callback used for lower resolution image saving is MCaptureImageObserver::

		CutDownImageDirectSavingCompleted(). */

		EDirectSavingWithLowerResolutionFile	= 0x02

		};

	/**

	Specifies the various type of direct snapshot support.

	The enumeration list may be extended in future.

	*/	

	enum TDirectSnapshotType

		{

		/** Direct snapshot not supported. */

		EDirectSnapshotNotSupported			= 0x00,

		/** Direct Snapshot supported. It will be displayed on the same direct viewfinder screen, out of which it has 

		been created */

		EDirectSnapshotSupported			= 0x01

		};

	/** Provides any extra drive mode dependent parameters to be used for image capture. */ 

	class TDriveModeDependentAttributes

		{

	public:

		IMPORT_C TDriveModeDependentAttributes();

		IMPORT_C TUint Size() const;

		IMPORT_C TUint Version() const;

	private:

		//for future expansion

		TUint iSize:24;

		TUint iVersion:8;

		//for future use

		TInt iReserved1;

		TInt iReserved2;

		TInt iReserved3;

	public:

		/** If drive mode is EDriveModeTimeNudgeCapture this represents the number of images to be captured

		(pre-capture images) before client initiates actual image capture operation. */

		TInt iParam1;

		/** If drive mode is EDriveModeTimeNudgeCapture this represents the number of images to be captured

		(post-capture images) after client initiates actual image capture operation. */

		TInt iParam2;

		};

	/**

	Specifies the available processing options.

	The enumeration list may be extended in future.

	@publishedPartner

	@prototype

	*/	

	enum TEcamProcessingOptions

		{

		/** Processing options are not supported.*/

		EEcamProcessingNone 		= 0x00000000,

		/** Enable normal processing when image capture is initiated.*/

		EEcamNormalProcessing 		= 0x00000001,

		/** Enable background processing when image capture is initiated.*/

		EEcamBackgroundProcessing 	= 0x00000002