// Copyright (c) 2005-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
 @released
*/

#ifndef  ECAMIMAGEPROCESSINGINTF_H
#define  ECAMIMAGEPROCESSINGINTF_H

#include <ecamimageprocessing.h>
#include <ecam/ecamadvsettingsintfuids.hrh>

/** This is the UID which is used to obtain the interface MCameraImageProcessing, via the 
CCamera::CustomInterface() call, which provides implementation of the M-class interface. */   
static const TUid KECamMCameraImageProcessingUid 	=  {KECamMCameraImageProcessingUidValue};

/** 
This is the UID which is used to obtain the interface MCameraImageProcessing2, via the 
CCamera::CustomInterface() call, which provides implementation of the M-class interface. 
*/   
static const TUid KECamMCameraImageProcessing2Uid 	=  {KECamMCameraImageProcessing2UidValue};

/** 
This is the UID which is used to obtain the interface MCameraImageProcessing3, via the 
CCamera::CustomInterface() call, which provides implementation of the M-class interface. 
@publishedPartner
@prototype
*/   
static const TUid KECamMCameraImageProcessing3Uid 	=  {KECamMCameraImageProcessing3UidValue};


/** 
Mixin class for implementation by providers of the Image Processing Camera Extension API.

This class is used to perform image processing operations on the camera.
These include brightness, contrast, gamma, hue, sharpness and saturation adjustments. The client is also 
able to perform simple image transformations like cropping, rotation, mirroring, scaling, noise reduction and glare reduction. .  
When an operation selection is complete, all clients are notified with the respective event UID.

As often cameras may support only a subset of discrete values of the allowed range, 
the API allows the client to retrieve those and use them explicitly.   

@note it is assumed that setting a new value for a transformations(transform, adjust, effect) effectively
	  activates the transformations. Whilst for effects and adjustments there is always a value, transforms 
	  may have a dependency on other parameters and 
	  crop - requires setting of source rectangle.
	  scale - will use setting of source rectangle, and the magnification factor is 
	  				determined by the source rectangle and the output size. This is always magnification.
	  				if a value is set, it is assumed to be a scaling factor multiplied by KECamFineResolutionFactor
	  			and set to integer.
	  mirror - values of TMirror type.
	  rotation - the angle in degrees.
	  noise reduction - TNoiseReduction.
	  glare removal - TGlareReduction.	

Example 
		Let's assume that an application would need to check whether gamma correction is 
        supported on a particular platform. After obtaining a valid pointer to the interface, 
        it would call GetSupportedTransformationsL() to obtain the list of the supported 
        tranformations and check whether KUidECamEventImageProcessingAdjustGamma
		is in the list. If it is then call SetTranformationValue(KUidECamEventImageProcessingAdjustGamma, 200);
		to set the new value. A notification will be generated to the client to indicate success.
		
@publishedPartner
@released 	
*/
class MCameraImageProcessing
	{
	
public:
	
	/** 
	Releases the interface. 
	*/
    virtual void Release()=0;

	/** Get all transformations supported on the camera. 
	    
	@param  aTransformations
			An empty RArray of TUids to store the UIDs of the supported transformations.

	@leave KErrNoMemory Out of memory. May also leave as a result of other system errors.
	*/
	virtual void GetSupportedTransformationsL(RArray<TUid>& aTransformations) const=0;

	/** Get currently active transformations on the camera. 
	    
	@param  aTransformations
			An empty RArray of TUids to store the UIDs of the supported transformations.

	@leave KErrNoMemory Out of memory. May also leave as a result of other system errors.  
	*/
	virtual void GetActiveTransformationsL(RArray<TUid>& aTransformations) const=0;

	/** Get all values supported by an active transformation.
	    
	@param  aTransformation
			The UID of active transform for which values are requested.
			
	@param  aValues 
	        An array of integers to represent the values for the requested transformation.
	        
	@param  aInfo
	        Additional information describing the returned array of values.
	        
	@note   depending on the value of aInfo parameter, same array of values may describe 
	        different set of values.
	        When camera device doesn't support this, empty array should be returned and TValueInfo should be ENotActive,
	        and the corresponding getter/setters for this feature should not be used.
	        
	@leave KErrNoMemory Out of memory. May also leave as a result of other system errors. 
	*/
	virtual void GetTransformationSupportedValuesL(TUid aTransformation, RArray<TInt>& aValues, TValueInfo& aInfo) const=0;

	/** 
	@deprecated Use TInt GetTransformationValue(TUid aTransformation, TInt& aTransformationValue);
	
	Get the current value of a transformation

	@param aTransformation
		   The UID of the transformation

	@return The integer value of the tranformation. 	   
	*/
	virtual TInt TransformationValue(TUid aTransformation) const=0;

	/** Get the current value of a transformation

	@param aTransformation
		   The UID of the transformation
		   
	@param aTransformationValue
		   Reference to the integer value of the tranformation.

	@return system wide error code. 	   
	*/
	virtual TInt GetTransformationValue(TUid aTransformation, TInt& aTransformationValue) const=0;

	/** Set new value for a transformation. 
	 A notification event with the transformation UID is sent to 
	 all clients. UIDs are in the form KUidECamEventImageProcessingXXXX.

	@param aTransformation
		   The UID of the transformation

	@param aValue
		  The integer value of the tranformation. 	   
	*/
	virtual void SetTransformationValue(TUid aTransformation, TInt aValue)=0;

	/** Get the sequence of all active transforms, ordered in order of execution.
	 
	@param aTransformSequence
		   an empty array to be populated with sequence of transform UIDs, 
		   where transform entries with smaller index are executed earlier. 
		
	@leave KErrNoMemory Out of memory. May also leave as a result of other system errors.	   
	*/
	virtual void GetActiveTransformSequenceL(RArray<TUid>& aTransformSequence) const=0;

	/** 
	Set the order of all active transform in terms of execution. The transforms with 
	smaller index are executed earlier.

	@param aTransformSequence
		   The list of ordered transforms, where transforms with smaller 
		   index are executed earlier.
	  
	@leave KErrNoMemory Out of memory. May also leave as a result of other system errors.
	*/
	virtual void SetActiveTransformSequenceL(RArray<TUid>& aTransformSequence)=0;

	/**
	Set the source rectangle for KUidECamEventImageProcessingTransformScale or 
	KUidECamEventImageProcessingTransformCrop.
	The coordinates should fall within the current image rectangle. The result 
	is always a logical AND operation between the two rectangles.
			   
	@param aRect
		   a reference to TRect object which describes the coordinates of the 
		   area of interest. 
	*/
	virtual void SetSourceRect(const TRect& aRect)=0;

	/**
	Get the source rectangle for KUidECamEventImageProcessingTransformScale or 
	KUidECamEventImageProcessingTransformCrop.
	The coordinates should fall within the current image rectangle. The result 
	is always a logical AND operation between the two rectangles.
			   
	@param aRect
			a reference to a TRect object to hold the current source rectangle 
			coordinates. If it has not been set, the coordinates match these of 
			the whole image.      
	*/
	virtual void GetSourceRect(TRect& aRect) const=0;
	};

/** 
Mixin class for implementation of extended features like color swap and color accent processing 
by providers of the Image Processing Camera Extension API.

@publishedPartner
@released
*/
class MCameraImageProcessing2
	{
	
public:
	
	/** 
	Releases the interface. 
	*/
    virtual void Release()=0;	
    
	/**
	Retrieves the maximum number of simultaneous color swapping possible.
	
	@param aConcurrentColorSwappingSupported
		   Retrieves the number of simultaneous color swapping supported. 
		   Retrieves 0 when swapping feature is not supported.
	
	@leave May leave as a result of some error. 
	*/		
	virtual void GetConcurrentColorSwappingsSupportedL(TInt& aConcurrentColorSwappingSupported) const=0;
	
	/**
	Retrieves the color swapping capabilites per entry, if different entries have different capabilities 
	otherwise the same capabilities retrieved for a particular entry can be assumed to be valid for every entry
	
	@param aIndex 
		   This is a value from 0 to numOfSimultaneousColorSwappings -1. Color swapping capabilities specific to 
		   a particular entry are retrieved. If uniform capability exists for every entry, then this method need not 
		   be called per entry.	
		   
	@param aColorSwapCapabilities
		   This retrieves the color swap capabilities.
		   
	@leave May leave as a result of some error.
	*/
	virtual void GetColorSwapCapabilitiesL(TInt aIndex, CCamera::CCameraImageProcessing::TColorOperationCapabilities& aColorSwapCapabilities) const=0;

	/**
	Set the color swap entries
	
	@param aIndex
		   This is a value from 0 to numOfSimultaneousColorSwappings -1. This helps in managing the limited no. of 
		   simultaneous color swaps. If parameters are already set for the given entry, then it's up to the implementation
		   to replace the existing one or discard it. 
    
    @param aColorSwapParameters
    	   The parameters necessary to define clearly the color swapping operation for the given entry. 
    	   iEntryStatus has to be updated by the implementation as per the result of the setting operation. 
    	   So, iEntryStatus value is redundant at this point.
    	   
	@note  Triggers KUidECamEventCIPSetColorSwapEntry to all MCameraObserver2 clients of the camera. 
		   HandleEvent is used to report the result or any possible error. TECAMEvent2 class should 
		   be used in order to provide the entry no. of the color being set. 
		   Implementation Hint: On success, entry status (iEntryStatus) for that entry should
		   be set to TValueInfo::EDiscreteSteps and saved on the implementation side.
	*/
	virtual void SetColorSwapEntry(TInt aIndex, const CCamera::CCameraImageProcessing::TColorOperationEntry& aColorSwapParameters)=0; 
	
	/**
	Removes the color swap entry corresponding to the given index
	
	@param aIndex
		   This gives the color swapping entry to be removed. 
		   
	@note  Triggers KUidECamEventCIPRemoveColorSwapEntry to all MCameraObserver2 clients of the camera.
		   HandleEvent is used to report the result or any possible error. TECAMEvent2 class should be
		   used in order to provide the entry no. of the color being removed. 
		   Implementation Hint: On success, entry status (iEntryStatus) for that entry should
		   be set to TValueInfo::ENotActive and saved on the implementation side.
	*/
	virtual void RemoveColorSwapEntry(TInt aIndex)=0;
	
	/**
	Get the details of the color swap entry corresponding to the given index
	
	@param aIndex
		   This gives the color swapping entry whose information has to be retrieved.
	
	@param aColorSwapParameters
		   This contains the parameters currently being used by the color swapping operation for the given entry.
	
	@leave May leave as a result of some error. 
	*/
	virtual void GetColorSwapEntryL(TInt aIndex, CCamera::CCameraImageProcessing::TColorOperationEntry& aColorSwapParameters) const=0; 
	
	/**
	Starts the color swapping process after taking into account the color swap entries updated up to this point.
	
	@note Triggers KUidECamEventCIPStartColorSwap to all MCameraObserver2 
		  clients of the camera. HandleEvent is used to report the result or any possible error. 
		  One possible error case is when more than one entry describe the same color source. 
		  New ecam error KErrECamColorOperationConflict used in such a case.
	*/
	virtual void StartColorSwapping()=0;
	
	/**
	Cancel the color swapping process.
	
	@leave May leave as a result of some error.
	
	@note  Used to cancel the color swapping process which might have been just started. 
		   If the issued StartColorSwappingL() gets cancelled, its event should report KErrCancel.
	*/
	virtual void CancelColorSwappingL()=0;
	
	/**
	Retrieves the maximum number of color entries on which simultaneous color accent process is possible.
	
	@param aConcurrentColorAccentSupported
		   Retrieves the number of color entries on which simultaneous color accent process is possible. 
		   Retrieves 0 when color accent process is not supported.
	
	@leave May leave as a result of some error. 
	*/
	virtual void GetConcurrentColorAccentSupportedL(TInt& aConcurrentColorAccentSupported) const=0;
	
	/**
	Retrieves the color accent capabilites per entry, if different entries have different capabilities 
	otherwise the same capabilities retrieved for a particular entry can be assumed to be valid for every entry
	
	@param aIndex 
		   This is a value from 0 to numOfSimultaneousColorAccent -1. Color accent capabilities specific to 
		   a particular entry are retrieved. If uniform capability exists for every entry, then this method need not 
		   be called per entry.	
		   
	@param aColorAccentCapabilities
		   This retrieves the color accent capabilities.
		   
	@leave May leave as a result of some error.
	*/
	virtual void GetColorAccentCapabilitiesL(TInt aIndex, CCamera::CCameraImageProcessing::TColorOperationCapabilities& aColorAccentCapabilities) const=0;
	
	/**
	Set the color accent entries
	
	@param aIndex
		   This is a value from 0 to numOfSimultaneousColorAccent -1. This helps in managing the limited no. of 
		   simultaneous color accent. If parameters are already set for the given entry, then it's up to the implementation
		   to replace the existing one or discard it. 
    
    @param aColorAccentParameters
    	   The parameters necessary to define clearly the color accent operation for the given entry. 
    	   iEntryStatus has to be updated by the implementation as per the result of the setting operation. 
    	   So, iEntryStatus value is redundant at this point. The parameters defined for target colors in 
    	   TColorOperationEntry are redundant for color accent.
    	   
	@note  Triggers KUidECamEventCIPSetColorAccentEntry to all MCameraObserver2 clients of the camera. 
		   HandleEvent is used to report the result or any possible error. TECAMEvent2 class should be 
		   used in order to provide the entry no. of the color being set. 
		   Implementation Hint: On success, entry status (iEntryStatus) for that entry should
		   be set to TValueInfo::EDiscreteSteps and saved on the implementation side.
	*/
	virtual void SetColorAccentEntry(TInt aIndex, const CCamera::CCameraImageProcessing::TColorOperationEntry& aColorAccentParameters)=0; 

	/**
	Removes the color accent entry corresponding to the given index
	
	@param aIndex
		   This gives the color accent entry to be removed. 
		   
	@note  Triggers KUidECamEventCIPRemoveColorAccentEntry to all MCameraObserver2 clients of the camera.
		   HandleEvent is used to report the result or any possible error. TECAMEvent2 class should be 
		   used in order to provide the entry no. of the color being removed. 
		   Implementation Hint: On success, entry status (iEntryStatus) for that entry should
		   be set to TValueInfo::ENotActive and saved on the implementation side.
	*/
	virtual void RemoveColorAccentEntry(TInt aIndex)=0;
	 
	/**
	Get the details of the color accent entry corresponding to the given index
	
	@param aIndex
		   This gives the color accent entry whose information has to be retrieved.
	
	@param aColorAccentParameters
		   This contains the parameters currently being used by the color accent operation for the given entry.
		   The parameters defined for target colors in TColorOperationEntry are redundant for color accent.
	
	@leave May leave as a result of some error. 
	*/
	virtual void GetColorAccentEntryL(TInt aIndex, CCamera::CCameraImageProcessing::TColorOperationEntry& aColorAccentParameters) const=0; 
	
	/**
	Starts the color accent process after taking into account the color accent entries updated up to this point.
	
	@note  Triggers KUidECamEventCIPStartColorAccent to all MCameraObserver2 
		   clients of the camera. HandleEvent is used to report the result or any possible error. 
	*/
	virtual void StartColorAccent()=0;
	
	/**
	Cancel the color accent process.
	
	@leave May leave as a result of some error.
	
	@note  Used to cancel the color accent process which might have been just started. 
		   If the issued StartColorAccentL() gets cancelled, its event should report KErrCancel.
	*/
	virtual void CancelColorAccentL()=0;
	};
	
/** 
Mixin class for implementation of extended features like custom orientation and event filtering 
by providers of the Image Processing Camera Extension API.

@publishedPartner
@prototype
*/
class MCameraImageProcessing3
	{

public:
	
	/** 
	Releases the interface. 
	*/
    virtual void Release()=0;
	
	/**
	Retrieves the supported options for a particular orientation reference.

	@param  aOrientationReference
			A TOrientationReference for which supported relative custom orientation have to retrieved.
			
	@param  aSupportedRelativeRotation
			A bitfield which retrieves the supported TRelativeRotation for 'aOrientationReference'
			
	@param  aSupportedRelativeMirroring
			A bitfield which retrieves the supported TRelativeMirror for 'aOrientationReference'
			
	@param  aSupportedRelativeFlipping
			A bitfield which retrieves the supported TRelativeFlipping for 'aOrientationReference'

	@leave  May leave with any error code.
	*/
	virtual void GetSupportedRelativeOrientationOptionsL(CCamera::CCameraImageProcessing::TOrientationReference aOrientationReference, 
			TUint& aSupportedRelativeRotation, TUint& aSupportedRelativeMirroring, TUint& aSupportedRelativeFlipping) const=0;
	
	/**
	Retrieves the options which is being used for the current orientation reference.

	@param  aOrientationReference
			A TOrientationReference which is the current orientation reference being used.
			
	@param  aRelativeRotation
			A TRelativeRotation which is the current relative rotation being used with aOrientationReference.
			
	@param  aRelativeMirror
			A TRelativeMirror which is the current relative mirroring being used with aOrientationReference.
			
	@param  aRelativeFlipping
			A TRelativeFlipping which is the current relative flipping being used with aOrientationReference.
			
	@leave  May leave with any error code.
	*/													
	virtual void GetCurrentRelativeOrientationOptionsL(CCamera::CCameraImageProcessing::TOrientationReference& aOrientationReference, 
											CCamera::CCameraImageProcessing::TRelativeRotation& aRelativeRotation, 
											CCamera::CCameraImageProcessing::TRelativeMirror& aRelativeMirror, 
											CCamera::CCameraImageProcessing::TRelativeFlipping& aRelativeFlipping) const=0;
	
	/**
	Sets the options which would be used with the desired orientation reference.

	@param  aOrientationReference
			The desired TOrientationReference.
			
	@param  aRelativeRotation
			The desired TRelativeRotation which would be used with 'aOrientationReference'.
			
	@param  TRelativeMirror
			The desired TRelativeMirror which would be used with 'aOrientationReference'

	@param  TRelativeFlipping
			The desired TRelativeFlipping which would be used with 'aOrientationReference'
			
	@note   Event KUidECamEventImageProcessingTransformRelativeOrientation is used to notify clients about relative 
			custom orientation setting operation.
			
	@note   If the current picture orientation (Refer CCamera::CCameraAdvancedSettings::TPictureOrientation) is not possible
			to be achieved with the relative custom orientation, event KUidECamEventPictureOrientationUnachievable will be
			notified to the client.
			
	@note   If the dimension of the image gets changed by the desired relative orientation options, notification 
			KUidECamEventCameraSettingImageSize will be notified to the client.
	*/												
	virtual void SetRelativeOrientationOptions(CCamera::CCameraImageProcessing::TOrientationReference aOrientationReference, 
											CCamera::CCameraImageProcessing::TRelativeRotation aRelativeRotation, 
											CCamera::CCameraImageProcessing::TRelativeMirror aRelativeMirror, 
											CCamera::CCameraImageProcessing::TRelativeFlipping aRelativeFlipping) const=0;
	};
	
#endif // ECAMIMAGEPROCESSINGINTF_H