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

     2 // All rights reserved.

     3 // This component and the accompanying materials are made available

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

     5 // which accompanies this distribution, and is available

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

     7 //

     8 // Initial Contributors:

     9 // Nokia Corporation - initial contribution.

    10 //

    11 // Contributors:

    12 //

    13 // Description:

    14 //

    15 

    16 /**

    17  @file

    18  @publishedAll

    19  @released

    20 */

    21 #ifndef ECAM_H

    22 #define ECAM_H

    23 

    24 #include <e32base.h>

    25 #include <ecamuids.hrh>

    26 #include <e32property.h>

    27 

    28 #ifndef SYMBIAN_ENABLE_SPLIT_HEADERS

    29 #include <ecamdef.h>

    30 #endif

    31 

    32 class MFrameBuffer;

    33 class RWsSession;

    34 class CWsScreenDevice;

    35 class RWindowBase;

    36 class CFbsBitmap;

    37 

    38 typedef TInt TPostCaptureControlId;

    39 

    40 /** Specifies camera device information.

    41 

    42 If either zoom or digital zoom are available then the appropriate entries

    43 in this class will be set to indicate the range of values that they may take.

    44 This should be implemented such that a setting of zero corresponds to no zoom,

    45 and a step of one corresponds to the smallest increment available, in a linear

    46 fashion.

    47 

    48 There are also zoom factors that correspond to the actual zoom factor when

    49 at minimum (non-digital only) and maximum zoom. Negative zoom values represent

    50 macro functionality.

    51 

    52 Image capture, if supported, is simply a case of transferring the current

    53 image from the camera to the client via MCameraObserver::ImageReady(). The

    54 camera class must set the iImageFormatsSupported bitfield to indicate the

    55 formats available.

    56 

    57 @publishedAll

    58 @released

    59 */

    60 class TCameraInfo

    61 	{

    62 public:

    63 	/** Possible directions in which the camera may point.

    64 	*/

    65 	enum TCameraOrientation

    66 		{

    67 		/** Outward pointing camera for taking pictures.

    68 		Camera is directed away from the user. */

    69 		EOrientationOutwards,

    70 		/** Inward pointing camera for conferencing.

    71 		Camera is directed towards the user. */

    72 		EOrientationInwards,

    73 		/** Mobile camera capable of multiple orientations.

    74 		Camera orientation may be changed by the user. */

    75 		EOrientationMobile,

    76 		/** Camera orientation is not known. */

    77 		EOrientationUnknown

    78 		};

    79 

    80 	/** Various flags describing the features available for a particular implementation

    81 	*/

    82 	enum TOptions

    83 		{

    84 		/** View finder display direct-to-screen flag */

    85 		EViewFinderDirectSupported		= 0x0001,

    86 		/** View finder bitmap generation flag */

    87 		EViewFinderBitmapsSupported		= 0x0002,

    88 		/** Still image capture flag */

    89 		EImageCaptureSupported			= 0x0004,

    90 		/** Video capture flag */

    91 		EVideoCaptureSupported			= 0x0008,

    92 		/** View finder display mirroring flag */

    93 		EViewFinderMirrorSupported		= 0x0010,

    94 		/** Contrast setting flag */

    95 		EContrastSupported				= 0x0020,

    96 		/** Brightness setting flag */

    97 		EBrightnessSupported			= 0x0040,

    98 		/** View finder clipping flag */

    99 		EViewFinderClippingSupported	= 0x0080,

   100 		/** Still image capture clipping flag */

   101 		EImageClippingSupported			= 0x0100,

   102 		/** Video capture clipping flag */

   103 		EVideoClippingSupported			= 0x0200

   104 		};

   105 public:

   106 	/** Version number and name of camera hardware. */

   107 	TVersion iHardwareVersion;

   108 	/** Version number and name of camera software (device driver). */

   109 	TVersion iSoftwareVersion;

   110 	/** Orientation of this particular camera device. */

   111 	TCameraOrientation iOrientation;

   112 

   113 	/** Bitfield of TOptions available */

   114 	TUint32 iOptionsSupported;

   115 	/** The supported flash modes.

   116 	

   117 	This is a bitfield of CCamera::TFlash values. 

   118 	

   119 	If methods CCamera::New2L() or CCamera::NewDuplicate2L() are not used to create the CCamera object, it is assumed that the 

   120 	application may not be able to cope with any future additions to the enum values. So, any unrecognised enum value passed 

   121     from the implementation should be filtered by ECAM Implementation.

   122     To receive unrecognised/extra added enum values, application should rather use CCamera::New2L() or CCamera::NewDuplicate2L() 

   123     to create camera object. This is an indication to ECAM implementation. In this case, application is assumed 

   124     to be prepared to receive unrecognised enum values.

   125     @see CCamera::CCameraAdvancedSettings::SupportedFlashModes()

   126 	

   127 	*/

   128 	TUint32 iFlashModesSupported;

   129 	/** The supported exposure modes.

   130 	

   131 	This is a bitfield of CCamera::TExposure values. */

   132 	TUint32 iExposureModesSupported;

   133 	

   134 	/** The supported white balance settings.

   135 	

   136 	This is a bitfield of of CCamera::TWhiteBalance values. 

   137 	

   138 	If methods CCamera::New2L() or CCamera::NewDuplicate2L() are not used to create the CCamera object, it is assumed that the 

   139 	application may not be able to cope with any future additions to the enum values. So, any unrecognised enum value passed 

   140     from the implementation should be filtered by ECAM Implementation.

   141     To receive unrecognised/extra added enum values, application should rather use CCamera::New2L() or CCamera::NewDuplicate2L() 

   142     to create camera object. This is an indication to ECAM implementation. In this case, application is assumed 

   143     to be prepared to receive unrecognised enum values.

   144     Refer to CCamera::CCameraAdvancedSettings::SupportedWhiteBalanceModes() implementation

   145     

   146     @see CCamera::CCameraAdvancedSettings::SupportedWhiteBalanceModes()

   147 	*/

   148 	TUint32 iWhiteBalanceModesSupported;

   149 

   150 	/** Minimum zoom value allowed. 

   151 	

   152 	Must be negative, or zero if not supported.

   153 	

   154 	This is the minimum value that may be passed to CCamera::SetZoomFactorL(). */

   155 	TInt iMinZoom;

   156 	/** Maximum zoom value allowed. 

   157 	

   158 	Must be positive, or zero if not supported.

   159 	

   160 	This is the maximum value that may be passed to CCamera::SetZoomFactorL(). */

   161 	TInt iMaxZoom;

   162 	/** Maximum digital zoom value allowed. 

   163 	

   164 	Must be positive, or zero if not supported.

   165 

   166 	This is the maximum value that may be passed to CCamera::SetDigitalZoomFactorL(). 

   167 	Digital zoom factor is assumed to be a linear scale from 0 to iMaxDigitalZoom. */

   168 	TInt iMaxDigitalZoom;

   169 

   170 	/** Image size multiplier corresponding to minimum zoom value. 

   171 	

   172 	Must be between 0 and 1 inclusive. Both 0 and 1 indicate that macro functionality 

   173 	is not supported. */

   174 	TReal32 iMinZoomFactor;

   175 	/** Image size multiplier corresponding to maximum zoom value. 

   176 	

   177 	May take the value 0, or values greater than or equal to 1. Both 0 and 1 indicate 

   178 	that zoom functionality is not supported. */

   179 	TReal32 iMaxZoomFactor;

   180 	/** Image size multiplier corresponding to maximum digital zoom value. 

   181 		

   182 	Implementation recommendation is to use 'appropriate value' for maximum digital zoom which could cover only values 

   183 	given by new digital zoom methods based on image format and capture mode.

   184 	

   185 	Must be greater than or equal to 1. */

   186 	TReal32 iMaxDigitalZoomFactor;

   187 

   188 	/** Count of still image capture sizes allowed.

   189 	

   190 	Number of different image sizes that CCamera::EnumerateCaptureSizes() will 

   191 	support, based on the index passed in. Index must be between 0 and iNumImageSizesSupported-1. */

   192 	TInt iNumImageSizesSupported;

   193 	/** The supported still image formats.

   194 	

   195 	This is a bitfield of CCamera::TFormat values. */

   196 	TUint32 iImageFormatsSupported;

   197 

   198 	/** Count of video frame sizes allowed. 

   199 	

   200 	This is the number of different video frame sizes that CCamera::EnumerateVideoFrameSizes() 

   201 	will support, based on the specified index. The index must be between 0 and 

   202 	iNumVideoFrameSizesSupported-1. */

   203 	TInt iNumVideoFrameSizesSupported;

   204 	/** Count of video frame rates allowed.

   205 	

   206 	This is the number of different video frame rates that CCamera::EnumerateVideoFrameRates() 

   207 	will support, based on the specified index. The index must be between 0 and 

   208 	iNumVideoFrameRatesSupported-1. */

   209 	TInt iNumVideoFrameRatesSupported;

   210 	/** The supported video frame formats.

   211 

   212 	This is a bitfield of video frame CCamera::TFormat values. 

   213 	

   214 	If methods CCamera::New2L() or CCamera::NewDuplicate2L() are not used to create the CCamera object, it is assumed that the 

   215 	application may not be able to cope with any future additions to the enum values. So, any unrecognised enum value passed 

   216     from the implementation should be filtered by the ECAM implementation.

   217     To receive unrecognised/extra added enum values, the application should rather use CCamera::New2L() or CCamera::NewDuplicate2L() 

   218     to create the camera object. This is an indication to the ECAM implementation. In this case, the application is assumed 

   219     to be prepared to receive unrecognised enum values.	

   220 	*/

   221 	TUint32 iVideoFrameFormatsSupported;

   222 	/** Maximum number of frames per buffer that may be requested. */

   223 	TInt iMaxFramesPerBufferSupported;

   224 	/** Maximum number of buffers allowed */

   225 	TInt iMaxBuffersSupported;

   226 	};

   227 

   228 /** Mixin base class for camera clients.

   229 

   230 An application must implement an MCameraObserver or MCameraObserver2 (recommended)

   231 in order to use the camera API. This derived class is called when the camera is 

   232 ready for use, an image has been captured or a buffer of video data is ready, including 

   233 when errors occur.

   234 

   235 Implementations of the camera API should use MCameraObserver::FrameBufferReady()

   236 and MFrameBuffer::Release() to co-ordinate the mapping of any special memory

   237 objects.

   238 

   239 @publishedAll

   240 @released

   241 */

   242 class MCameraObserver

   243 	{

   244 public:

   245 	/** Camera reservation is complete.

   246 

   247 	Called asynchronously when CCamera::Reserve() completes.

   248 

   249 	@param  aError

   250 	        An error on failure and KErrNone on success.

   251 	*/

   252 	virtual void ReserveComplete(TInt aError)=0;

   253 

   254 	/** Indicates camera power on is complete.

   255 

   256 	Called on completion of CCamera:PowerOn().

   257 

   258 	@param  aError

   259 	        KErrNone on success, KErrInUse if the camera is in

   260 	        use by another client or KErrNoMemory if insufficient system memory is available.

   261 	*/

   262 	virtual void PowerOnComplete(TInt aError)=0;

   263 

   264 	/** Tests whether transfer of view finder data has completed.

   265 

   266 	Called periodically in response to the use of CCamera::StartViewFinderBitmapsL().

   267 

   268 	@param  aFrame

   269 	        The view finder frame.

   270 	*/

   271 	virtual void ViewFinderFrameReady(CFbsBitmap& aFrame)=0;

   272 

   273 	/** Transfers the current image from the camera to the client.

   274 

   275 	Called asynchronously when CCamera::CaptureImage() completes.

   276 

   277 	@param  aBitmap

   278 	        On return, a pointer to an image held in CFbsBitmap form if

   279 	        this was the format specified in CCamera::PrepareImageCaptureL().

   280 	@param  aData

   281 	        On return, a pointer to an HBufC8 if this was the format specified

   282 	        in CCamera::PrepareImageCaptureL(). NULL if there was an error.

   283 	@param  aError

   284 	        KErrNone on success or an error code on failure.

   285 	*/

   286 	virtual void ImageReady(CFbsBitmap* aBitmap,HBufC8* aData,TInt aError)=0;

   287 

   288 	/** Passes a filled frame buffer to the client.

   289 

   290 	Called asynchronously, when a buffer has been filled with the required number

   291 	of video frames by CCamera::StartVideoCapture().

   292 

   293 	@param  aFrameBuffer

   294 	        On return, a pointer to an MFrameBuffer if successful,

   295 	        or NULL if not successful.

   296 	@param  aError

   297 	        KErrNone if successful, or an error code if not successful.

   298 	*/

   299 	virtual void FrameBufferReady(MFrameBuffer* aFrameBuffer,TInt aError)=0;

   300 	};

   301 

   302 

   303 /**

   304 Class used for passing camera picture data between camera and client in the V2 observer.

   305 Used for viewfinder, image capture and video capture.

   306 

   307 The class offers APIs for the client to access the data as a descriptor, a bitmap

   308 or a handle to a kernel chunk. Depending on the format previously requested by

   309 the client, one or more of the API choices may be inappropriate e.g. an image will

   310 not be avaiable as a bitmap in the FBS unless the client has specifically requested

   311 it.

   312 

   313 The buffer may contain multiple frames.

   314 

   315 @publishedAll

   316 @released

   317 */

   318 class MCameraBuffer

   319 	{

   320 public:

   321 	/** 

   322 	Returns the number of frames of image data contained within the buffer. This

   323 	would be 1 for a image capture, and match the requested count

   324 	for video capture. For other methods in this class that take a aFrameIndex

   325 	param, 0 <= aFrameIndex < NumFrames()

   326 

   327 	@return The number of frames of image data in the buffer. 

   328 	*/

   329 	virtual TInt NumFrames()=0;

   330 	/**

   331 	Returns a pointer to a descriptor containing a frame of camera data. The format

   332 	will have been previously specified by a CCamera class method.

   333 

   334 	@param  aFrameIndex

   335 	        The index of the required frame. For a still image this should be 0.

   336 

   337 	@leave  KErrArgument if aIndex is out of range and 

   338 	@leave  KErrNotSupported if the camera data is actually bitmaps in the FBS.

   339 

   340 	@return A pointer to a descriptor containing a frame of image data.

   341 	*/

   342 	virtual TDesC8* DataL(TInt aFrameIndex)=0;

   343 

   344 	/** 

   345 	Returns a reference to a FBS bitmap containing a frame of image data.

   346 

   347 	@param  aFrameIndex 

   348 	        The index of the required frame. For a still image this should be 0.

   349 

   350 	@leave  KErrArgument if aIndex is out of range and 

   351 	@leave  KErrNotSupported if the picture data is not a FBS bitmap.

   352 

   353 	@return A reference to a FBS bitmap containing a frame of picture data. 

   354 	*/

   355 	virtual CFbsBitmap& BitmapL(TInt aFrameIndex)=0;

   356 

   357 	/** 

   358 	Returns a handle for the chunk that contains the camera data.

   359 	The RChunk is exposed so that it can potentially be shared between multiple

   360 	processes.

   361 	The ptr returned by DataL(aFrameIndex) is effectively derived from this

   362 	RChunk (where both are supported simulataneously). The equivalent ptr would be:

   363 	TPtrC8* ptr;

   364 	ptr.Set(ChunkL().Base() + ChunkOffset(aFrameIndex), FrameSize(aFrameIndex));

   365 

   366 	@leave  KErrNotSupported if the chunk is not available.

   367 

   368 	@return A reference to a handle to the chunk that contains the buffer of picture data. 

   369 	*/

   370 	virtual RChunk& ChunkL()=0;

   371 

   372 	/** 

   373 	Returns the offset into the chunk that contains the frame specified by aFrameIndex.

   374 	The client would add this offset to the ptr returned by ChunkL().Base() to

   375 	get the address of the start of the frame data. 

   376 	

   377 	@param  aIndex 

   378 	        The index of the required frame. For a still image this should be 0.

   379 

   380 	@leave  KErrNotSupported if the chunk is not available 

   381 	@leave  KErrArgument if aIndex is out of range.

   382 

   383 	@return The offset into the chunk for the start of the frame. 

   384 	*/

   385 	virtual TInt ChunkOffsetL(TInt aFrameIndex)=0;

   386 

   387 	/** 

   388 	Returns the size of the data in bytes that comprises the frame specified by aIndex.

   389 	

   390 	@param  aFrameIndex 

   391 	        The index of the required frame. For a still image this should be 0.

   392 

   393 	@leave  KErrArgument 

   394 			if aIndex is out of range.

   395 

   396 	@return Returns the size of the data in bytes that comprises the frame. 

   397 	*/

   398 	virtual TInt FrameSize(TInt aFrameIndex)=0;

   399 

   400 	/** 

   401 	Releases the buffer. Once the client has processed

   402 	the picture data it should use this method to signal to CCamera that the

   403 	buffer can be re-used.

   404 	*/

   405 	virtual void Release()=0;

   406 public:

   407 

   408 	/** 

   409 	Sequential frame number of the first frame in the buffer, counting from when

   410 	CCamera::StartVideoCapture() was called and including frames dropped due to

   411 	lack of buffers. Always zero for still images. May also be used by client viewfinders.

   412 	*/

   413 	TInt iIndexOfFirstFrameInBuffer;

   414 

   415 	/** 

   416 	Time elapsed from when CCamera::StartVideoCapture() was called until the first

   417 	frame in the buffer was captured. Always zero for still images.

   418 	*/

   419 	TTimeIntervalMicroSeconds iElapsedTime;

   420 	};

   421 

   422 /** 

   423 	Uid used to identify the event that the request to Reserve() has completed

   424 */

   425 static const TUid  KUidECamEventReserveComplete = {0x101F7D3B};

   426 

   427 /** 

   428 	Uid used to identify the event that the request to PowerOn() has completed

   429 */

   430 static const TUid  KUidECamEventPowerOnComplete = {0x101F7D3C};

   431 

   432 /** 

   433 	Uid used to identify the event that the client has lost

   434 	control of the camera

   435 */

   436 static const TUid  KUidECamEventCameraNoLongerReserved = {0x101F7D3D};

   437 

   438 /** 

   439 Uid used to notify the client who made the new reserve request. 

   440 

   441 Error value KErrECamHighPriorityReserveRequesterExists indicates another such reserve request is outstanding and

   442 has higher priority than this one.

   443 Error value KErrCancel indicates a new reserve requester with higher priority than the current requester has 

   444 been made. That's why, this one got cancelled.

   445 Any other error may also occur.

   446 @see CCamera::CCameraAdvancedSettings::ReserveL(const TTimeIntervalMicroseconds32& aMaxTimeToWait, TBool aKickOut);

   447 */

   448 static const TUid  KUidECamEventNewReserveComplete = {KUidECamEventNewReserveCompleteUidValue};

   449 

   450 /**

   451 @publishedAll

   452 @released

   453 

   454 General purpose class to describe an ECam event.

   455 

   456 Contains a UID to define the actual event type, and an integer to define the event code.

   457 

   458 */

   459 

   460 class TECAMEvent

   461 	{

   462 public:

   463 	

   464 	/**

   465 	Constructor.

   466 	

   467 	@param  aEventType

   468 	        A UID to define the type of event.

   469 	@param  aErrorCode

   470 	        The error code associated with the event.

   471 

   472 	*/

   473 	IMPORT_C TECAMEvent(TUid aEventType, TInt aErrorCode);

   474 

   475 	/**

   476 	Default constructor.

   477 	

   478 	Provided so this class can be packaged in a TPckgBuf<>.

   479 	*/

   480 	IMPORT_C TECAMEvent();

   481 	

   482 	/**

   483 	A UID to define the event type.

   484 	*/

   485 	TUid iEventType;

   486 

   487 	/**

   488 	The error code associated with the event.

   489 	*/

   490 	TInt iErrorCode;

   491 	};

   492 

   493 /** 

   494 Uid used to identify a particular version of TECAMEvent base class being used i.e. TECAMEvent2 . 

   495 Useful for MCameraObserver2::HandleEvent implementation to detect the version of TECAMEvent base class.

   496 */

   497 static const TUid  KUidECamEventClass2 = {KUidECamEventClass2UidValue};

   498 

   499 /** 

   500 event indicating setting of color entry in the color swap operation. This is a part of class CCamera::CCameraImageProcessing. 

   501 This event should be packed in TECAMEvent2 class.

   502 

   503 @note  TECAMEvent2::iParam represents color entry.

   504 */

   505 static const TUid  KUidECamEventCIPSetColorSwapEntry 		   = {KUidECamEventCIPSetColorSwapEntryUidValue};

   506 static const TUid  KUidECamEvent2CIPSetColorSwapEntry 		   = {KUidECamEventCIPSetColorSwapEntryUidValue};

   507 

   508 /** 

   509 event indicating removal of color entry in the color swap operation. This is a part of class CCamera::CCameraImageProcessing. 

   510 This event should be packed in TECAMEvent2 class.

   511 

   512 @note  TECAMEvent2::iParam represents color entry.

   513 */

   514 static const TUid  KUidECamEventCIPRemoveColorSwapEntry 	   = {KUidECamEventCIPRemoveColorSwapEntryUidValue};

   515 static const TUid  KUidECamEvent2CIPRemoveColorSwapEntry 	   = {KUidECamEventCIPRemoveColorSwapEntryUidValue};

   516 

   517 /** 

   518 event indicating setting of color entry in the color accent operation. This is a part of class CCamera::CCameraImageProcessing. 

   519 This event should be packed in TECAMEvent2 class.

   520 

   521 @note  TECAMEvent2::iParam represents color entry.

   522 */

   523 static const TUid  KUidECamEventCIPSetColorAccentEntry 		   = {KUidECamEventCIPSetColorAccentEntryUidValue};

   524 static const TUid  KUidECamEvent2CIPSetColorAccentEntry 	   = {KUidECamEventCIPSetColorAccentEntryUidValue};

   525 

   526 /** 

   527 event indicating removal of color entry in the color accent operation. This is a part of class CCamera::CCameraImageProcessing. 

   528 This event should be packed in TECAMEvent2 class.

   529 

   530 @note  TECAMEvent2::iParam represents color entry.

   531 */

   532 static const TUid  KUidECamEventCIPRemoveColorAccentEntry 	   = {KUidECamEventCIPRemoveColorAccentEntryUidValue};

   533 static const TUid  KUidECamEvent2CIPRemoveColorAccentEntry 	   = {KUidECamEventCIPRemoveColorAccentEntryUidValue};

   534 

   535 /** 

   536 event indicating issue of pre capture warnings. This is a part of class CCamera::CCameraAdvancedSettings. 

   537 This event should be packed in TECAMEvent2 class.

   538 

   539 This TUid is available from the following methods only to the API clients using CCamera::New2L() or CCamera::

   540 NewDuplicate2L():-

   541 void CCamera::CCameraAdvancedSettings::GetSupportedSettingsL(RArray<TUid>& aSettings) const;

   542 void CCamera::CCameraAdvancedSettings::GetActiveSettingsL(RArray<TUid>& aActiveSettings) const;

   543 void CCamera::CCameraAdvancedSettings::GetDisabledSettingsL(RArray<TUid>& aDisabledSettings) const;

   544 

   545 @note  TECAMEvent2::iParam represents bit field describing all PreCaptureWarnings currently issued.

   546 */

   547 static const TUid  KUidECamEventCameraSettingPreCaptureWarning 	= {KUidECamEventCameraSettingPreCaptureWarningUidValue};

   548 static const TUid  KUidECamEvent2CameraSettingPreCaptureWarning = {KUidECamEventCameraSettingPreCaptureWarningUidValue};

   549 	

   550 /**

   551 Special type of TECAMEvent class used to retrieve some extra information from particular events received

   552 

   553 @publishedAll

   554 @released

   555 */	

   556 class TECAMEvent2 : public TECAMEvent

   557 	{

   558 public:

   559 

   560 	IMPORT_C static TBool IsEventEncapsulationValid(const TECAMEvent& aECAMEvent);

   561 

   562 	IMPORT_C TECAMEvent2(TUid aEventType, TInt aErrorCode, TInt aParam);

   563 	

   564 	IMPORT_C const TUid& EventClassUsed() const;

   565 	

   566 private:

   567 	/** 

   568 	Uid representing this version of TECAMEvent base class. Uid used is KUidECamEventClass2 

   569 	*/

   570 	TUid iEventClassUsed;

   571 	

   572 	/**

   573 	Reserved for future

   574 	TInt iReserved1; -> Made Public TInt iParam1

   575 	*/

   576 	

   577 	/**

   578 	Reserved for future	

   579 	*/

   580 	TInt iReserved2; 

   581 	

   582 	

   583 public:

   584 	/**

   585 	iParam1 will be used to provide extra information if iParam is not sufficient.

   586 	This signifies different things for different valid events.

   587 				

   588 	Future events may also use this class member variable.

   589 	*/

   590 	TInt iParam1;

   591 	

   592 	/**

   593 	This signifies different things for different valid events.

   594 				

   595 	Future events may also use this class member variable.

   596 	*/	

   597 	TInt iParam;

   598 	};

   599 

   600 /** Mixin base class V2 for camera clients.

   601 

   602 An application must implement an MCameraObserver2 (or MCameraObserver) in order to use the camera

   603 API. This derived class is called when the camera is ready for use, an image

   604 has been captured or a buffer of video data is ready, including when errors

   605 occur.

   606 

   607 @publishedAll

   608 @released

   609 */

   610 

   611 class MCameraObserver2

   612 	{

   613 public:

   614 	/** 

   615 	A camera event has completed.

   616 	@note Implementations of MCameraObserver2 should ignore events which are not recognised and should not leave.

   617 

   618 	@param  aEvent

   619 	        A reference to a TECAMEvent. This can be completion of a call to Reserve() 

   620 			or a call to PowerOn() or a notification that the client has lost control 

   621 			of the camera.

   622 			The event contains a uid identifying the event and an accompanying

   623 			error code (KErrNone for the successful completion of a request).

   624 			The error will be KErrNotReady for a request that was made out of the

   625 			correct sequence.

   626 			The error will be KErrAccessDenied for a Reserve() request that failed

   627 			because a higher priority client already controls the camera.

   628 	

   629 	@note   This may internally call TECAMEvent2::IsEventEncapsulationValid(aEvent) and also for any other derived version of TECAMEvent 

   630 			class to know whether correct version of TECAMEvent base class has been used. 

   631 	*/

   632 	virtual void HandleEvent(const TECAMEvent& aEvent)=0;

   633 

   634 	/** 

   635 	Notifies client of new view finder data. Called periodically in response to 

   636 	the use of CCamera::StartViewFinderL().

   637 

   638 	@param  aCameraBuffer

   639 	        A reference to an MCameraBuffer if successful, or NULL if not successful.

   640 

   641 	@param  aError

   642 	        KErrNone if successful, or an error code if not successful.

   643 	*/

   644 	virtual void ViewFinderReady(MCameraBuffer& aCameraBuffer,TInt aError)=0;

   645 

   646 	/** 

   647 	Notifies the client of a new captured camera image. Called asynchronously 

   648 	when CCamera::CaptureImage() completes.

   649 

   650 	@param  aCameraBuffer

   651 	        A reference to an MCameraBuffer if successful, or NULL if not successful.

   652 

   653 	@param  aError

   654 	        KErrNone if successful, or an error code if not successful.

   655   

   656 	@note   If new image capture classes used, then this callback will not be used. Refer MCaptureImageObserver

   657 	*/

   658 	virtual void ImageBufferReady(MCameraBuffer& aCameraBuffer,TInt aError)=0;

   659 

   660 	/** 

   661 	Notifies the client of new captured video. Called asynchronously and periodically

   662 	after CCamera::StartVideoCapture() is called. The buffer has been filled with the 

   663 	required number of video frames specified PrepareVideoCaptureL().

   664 

   665 	@param  aCameraBuffer

   666 	        A reference to an MCameraBuffer if successful, or NULL if not successful.

   667 

   668 	@param  aError

   669 	        KErrNone if successful, or an error code if not successful.

   670 	*/

   671 	virtual void VideoBufferReady(MCameraBuffer& aCameraBuffer,TInt aError)=0;

   672 	};

   673 

   674 

   675 /** Base class for camera devices.

   676 

   677 Provides the interface that an application uses to control, and acquire images

   678 from, the camera.

   679 

   680 An application must supply an implementation of MCameraObserver2 (or MCameraObserver).

   681 

   682 @publishedAll

   683 @released

   684 */

   685 class CCamera : public CBase

   686 

   687 	{

   688 	

   689 	friend class CCameraPlugin;

   690 

   691 public:

   692 	class CCameraPresets;

   693 	class CCameraAdvancedSettings;

   694 	class CCameraImageProcessing;

   695 	class CCameraHistogram;

   696 	class CCameraV2Histogram;

   697 	class CCameraOverlay;

   698 	class CCameraSnapshot;

   699 	class CCameraDirectViewFinder;

   700 	class CCameraV2DirectViewFinder;

   701 	class CCameraClientViewFinder;

   702 	class CCameraPreImageCaptureControl;

   703 	class CCameraImageCapture;

   704 	class CCameraPostImageCaptureControl;

   705 	class CCameraVideoCaptureControl;

   706     class CCameraDirectSnapshot;

   707     class CCameraContinuousZoom;

   708 

   709 public:

   710 	/** Possible still image and video frame formats

   711 

   712 	Formats are read from left to right, starting at the top of the image. YUV

   713 	format is as defined by ITU-R BT.601-4. */

   714 	enum TFormat

   715 		{

   716 		/** 8 bit greyscale values, 0=black, 255=white. */

   717 		EFormatMonochrome			= 0x0001,

   718 		/** Packed RGB triplets, 4 bits per pixel with red in the least significant bits

   719 		and the 4 most significant bits unused. */

   720 		EFormat16bitRGB444			= 0x0002,

   721 		/** Packed RGB triplets, 5 bits per pixel for red and blue and 6 bits for green,

   722 		with red in the least significant bits. */

   723 		EFormat16BitRGB565			= 0x0004,

   724 		/** Packed RGB triplets, 8 bits per pixel with red in the least significant bits

   725 		and the 8 most significant bits unused. */

   726 		EFormat32BitRGB888			= 0x0008,

   727 		/** JFIF JPEG. */

   728 		EFormatJpeg					= 0x0010,

   729 		/** EXIF JPEG */

   730 		EFormatExif					= 0x0020,

   731 		/** CFbsBitmap object with display mode EColor4K. */

   732 		EFormatFbsBitmapColor4K		= 0x0040,

   733 		/** CFbsBitmap object with display mode EColor64K. */

   734 		EFormatFbsBitmapColor64K	= 0x0080,

   735 		/** CFbsBitmap object with display mode EColor16M. */

   736 		EFormatFbsBitmapColor16M	= 0x0100,

   737 		/** Implementation dependent. */

   738 		EFormatUserDefined			= 0x0200,

   739 		/** 4:2:0 format, 8 bits per sample, Y00Y01Y10Y11UV. */

   740 		EFormatYUV420Interleaved	= 0x0400,

   741 		/** 4:2:0 format, 8 bits per sample, Y00Y01Y02Y03...U0...V0... */

   742 		EFormatYUV420Planar			= 0x0800,

   743 		/** 4:2:2 format, 8 bits per sample, UY0VY1.  Maps to Graphics' EUidPixelFormatYUV_422Interleaved in pixelformats.h. */

   744 		EFormatYUV422				= 0x1000,

   745 		/** 4:2:2 format, 8 bits per sample, Y1VY0U.  Maps to Graphics' EUidPixelFormatYUV_422InterleavedReversed in pixelformats.h. */

   746 		EFormatYUV422Reversed		= 0x2000,

   747 		/** 4:4:4 format, 8 bits per sample, Y00U00V00 Y01U01V01... */

   748 		EFormatYUV444				= 0x4000,

   749 		/** 4:2:0 format, 8 bits per sample, Y00Y01Y02Y03...U0V0... */

   750 		EFormatYUV420SemiPlanar		= 0x8000,

   751 		/** CFbsBitmap object with display mode EColor16MU. */

   752 		EFormatFbsBitmapColor16MU 	= 0x00010000,

   753 		/** Motion JPEG for video 

   754 		@note This value is available only to the API clients using CCamera::New2L() or CCamera::NewDuplicate2L().

   755 		@internalTechnology

   756 		*/

   757 		EFormatMJPEG				= 0x00020000,

   758 		

   759 		/** 

   760 		Compressed H264 video format. 

   761 		@note This value is available only to the API clients using CCamera::New2L() or CCamera::NewDuplicate2L().

   762 		@prototype

   763 		*/

   764 		EFormatEncodedH264          = 0x00040000,

   765 

   766 		/**

   767 		4:2:2 format, 8 bits per sample, Y0UY1V. Maps to Graphics' EUidPixelFormatYUV_422Reversed in pixelformats.h.

   768 		@note This value is available only to the API clients using CCamera::New2L() or CCamera::NewDuplicate2L().

   769 		@prototype

   770 		*/

   771 		EFormatYUV222ReversedV2		= 0x00080000

   772 		};

   773 		

   774 	/** Specifies whether contrast is set automatically. */

   775 	enum TContrast

   776 		{

   777 		/** Sets the contrast automatically. */

   778 		EContrastAuto		= KMinTInt

   779 		};

   780 	/** Specifies whether brightness is set automatically. */

   781 	enum TBrightness

   782 		{

   783 		/** Sets the brightness automatically. */

   784 		EBrightnessAuto		= KMinTInt

   785 		};

   786 	/** Specifies the type of flash. */

   787 	enum TFlash

   788 		{

   789 		/** No flash, always supported. */

   790 		EFlashNone			= 0x0000,

   791 		/** Flash will automatically fire when required. */

   792 		EFlashAuto			= 0x0001,

   793 		/** Flash will always fire. */

   794 		EFlashForced		= 0x0002,

   795 		/** Reduced flash for general lighting */

   796 		EFlashFillIn		= 0x0004,

   797 		/** Red-eye reduction mode. */	

   798 		EFlashRedEyeReduce	= 0x0008,

   799 		/** Flash at the moment when shutter opens. */

   800 		EFlashSlowFrontSync = 0x0010,

   801 		/** Flash at the moment when shutter closes. */

   802 		EFlashSlowRearSync  = 0x0020, 

   803 		/** User configurable setting */	

   804 		EFlashManual		= 0x0040,

   805 		/** Constant emission of light during video mode  

   806             @note This value is available only to the API clients using CCamera::New2L() or CCamera::NewDuplicate2L()

   807 		*/

   808 		EFlashVideoLight    = 0x0080

   809 		};

   810 	/** Specifies the type of exposure. - EExposureAuto is the default value. */

   811 	enum TExposure

   812 		{

   813 		/** Set exposure automatically. Default, always supported.

   814 		This may imply auto aperture so clients may receive a KUidEcamEvent2CameraSettingAutoAperture event notification some time later. */

   815 		EExposureAuto		= 0x0000,

   816 		/** Night-time setting for long exposures. */

   817 		EExposureNight		= 0x0001,

   818 		/** Backlight setting for bright backgrounds. */

   819 		EExposureBacklight	= 0x0002,

   820 		/** Centered mode for ignoring surroundings. */

   821 		EExposureCenter		= 0x0004,

   822 		/** Sport setting for very short exposures. */

   823 		EExposureSport 		= 0x0008,

   824 		/** Generalised setting for very long exposures. */

   825 		EExposureVeryLong 	= 0x0010,

   826 		/** Snow setting for daylight exposure. */

   827 		EExposureSnow 		= 0x0020,

   828 		/** Beach setting for daylight exposure with reflective glare. */

   829 		EExposureBeach 		= 0x0040,

   830 		/** Programmed exposure setting. */

   831 		EExposureProgram 	= 0x0080,

   832 		/** Aperture setting is given priority. */

   833 		EExposureAperturePriority 	= 0x0100,

   834 		/** Shutter speed setting is given priority.

   835 		This may imply auto aperture so clients may receive a KUidEcamEvent2CameraSettingAutoAperture event notification some time later. */

   836 		EExposureShutterPriority	= 0x0200,

   837 		/** User selectable exposure value setting. */	

   838 		EExposureManual				= 0x0400,

   839 		/** Exposure night setting with colour removed to get rid of colour noise. */

   840 		EExposureSuperNight			= 0x0800,

   841 		/** Exposure for infra-red sensor on the camera */

   842 		EExposureInfra				= 0x1000

   843 		};

   844 		

   845 	/** Specifies how the white balance is set. */

   846 	enum TWhiteBalance

   847 		{

   848 		/** Set white balance automatically. Default, always supported. */

   849 		EWBAuto				= 0x0000,

   850 		/** Normal daylight. */

   851 		EWBDaylight			= 0x0001,

   852 		/** Overcast daylight. */

   853 		EWBCloudy			= 0x0002,

   854 		/** Tungsten filament lighting. */

   855 		EWBTungsten			= 0x0004,

   856 		/** Fluorescent tube lighting */

   857 		EWBFluorescent		= 0x0008,

   858 		/** Flash lighting. */

   859 		EWBFlash			= 0x0010,

   860 		/** High contrast daylight primarily snowy */

   861 		EWBSnow 			= 0x0020,

   862 		/** High contrast daylight primarily near the sea */

   863 		EWBBeach 			= 0x0040,

   864 		/** User configurable mode */

   865 		EWBManual 			= 0x0080,

   866 		/** Shade */

   867  		EWBShade			= 0x0100,

   868  		/** auto skin

   869 

   870  		If New2L()/NewDuplicate2L() are not used to create camera object, this

   871 		enum value would be considered as unrecognized and filtered out in 'supported'

   872 		or 'getter' methods.

   873  		*/

   874  		EWBAutoSkin			= 0x0200,

   875  		/** horizon

   876 

   877  		If New2L()/NewDuplicate2L() are not used to create camera object, this

   878 		enum value would be considered as unrecognized and filtered out in 'supported'

   879 		or 'getter' methods.

   880 		*/

   881  		EWBHorizon 			= 0x0400,

   882  		/** Daylight Under Water

   883 

   884  		If New2L()/NewDuplicate2L() are not used to create camera object, this

   885 		enum value would be considered as unrecognized and filtered out in 'supported'

   886 		or 'getter' methods.

   887 		*/

   888  		EWBDaylightUnderWater  = 0x0800

   889 		};

   890 

   891 public:

   892 	/**

   893 	Determines the number of cameras on the device.

   894 

   895     @return Count of cameras present on the device.

   896 	*/

   897 	IMPORT_C static TInt CamerasAvailable();

   898 

   899     /**

   900     @deprecated Use static CCamera* New2L(MCameraObserver2& aObserver,TInt aCameraIndex,TInt aPriority);

   901 

   902 	Creates an object representing a camera.

   903 

   904 	@param  aObserver

   905 	        Reference to class derived from MCameraObserver2 designed to receive

   906 	        notification of asynchronous event completion.

   907 	@param	aCameraIndex

   908 	        Index from 0 to CamerasAvailable()-1 inclusive specifying the

   909 	        camera device to use.

   910 	@param	aPriority

   911 	        Value from -100 to 100 indicating relative priority of client to

   912 	        use camera.

   913 

   914 	@return Pointer to a fully constructed CCamera object. Ownership is passed

   915 	        to the caller.

   916 

   917 	@leave  KErrNoMemory if out of memory.

   918 	@leave  KErrNotSupported if aCameraIndex is out of range.

   919 	@leave  KErrPermissionDenied if the application does not have

   920 	        the UserEnvironment capability.

   921 

   922 	@capability	UserEnvironment

   923 			An application that creates a CCamera object must have

   924 			the UserEnvironment capability.

   925 

   926     @capability MultimediaDD

   927 	        A process requesting or using this method that has MultimediaDD capability will

   928 			always have precedence over a process that does not have MultimediaDD.

   929 

   930 	@note   Applications using this method to create camera object may not receive enums/uids added in future(after being baselined).

   931 			To receive them, they should rather use New2L() or NewDuplicate2L(), in which case, they should prepare

   932 			themselves to receive unrecognised values.

   933 	*/

   934 	IMPORT_C static CCamera* NewL(MCameraObserver2& aObserver,TInt aCameraIndex,TInt aPriority);

   935 

   936 	/**

   937 	Creates an object representing a camera.

   938 	Clients prepare themselves to receive unrecognised enum, uids etc.

   939 

   940 	@param  aObserver

   941 	        Reference to class derived from MCameraObserver2 designed to receive

   942 	        notification of asynchronous event completion.

   943 	@param	aCameraIndex

   944 	        Index from 0 to CamerasAvailable()-1 inclusive specifying the

   945 	        camera device to use.

   946 	@param	aPriority

   947 	        Value from -100 to 100 indicating relative priority of client to

   948 	        use camera.

   949 

   950 	@return Pointer to a fully constructed CCamera object. Ownership is passed

   951 	        to the caller.

   952 

   953 	@leave  KErrNoMemory if out of memory.

   954 	@leave  KErrNotSupported if aCameraIndex is out of range.

   955 	@leave  KErrPermissionDenied if the application does not have

   956 	        the UserEnvironment capability.

   957 

   958 	@capability	UserEnvironment

   959 			An application that creates a CCamera object must have

   960 			the UserEnvironment capability.

   961 

   962     @capability MultimediaDD

   963 	        A process requesting or using this method that has MultimediaDD capability will

   964 			always have precedence over a process that does not have MultimediaDD.

   965 

   966 	@note   Clients using this creation method should prepare themselves to receive any unrecognised enum values, uids

   967 			from 'supported' or 'getter' methods

   968 	*/

   969 	IMPORT_C static CCamera* New2L(MCameraObserver2& aObserver,TInt aCameraIndex,TInt aPriority);

   970 

   971 	/**

   972 	Creates an object representing a camera.

   973 

   974 	@param  aObserver

   975 	        Reference to class derived from MCameraObserver designed to receive

   976 	        notification of asynchronous event completion.

   977 	@param	aCameraIndex

   978 	        Index from 0 to CamerasAvailable()-1 inclusive specifying the

   979 	        camera device to use.

   980 

   981 	@leave  KErrNoMemory if out of memory.

   982 	@leave  KErrNotSupported if aCameraIndex is out of range.

   983 	@leave  KErrPermissionDenied if the application does not have

   984 	        the UserEnvironment capability.

   985 

   986 	@return Pointer to a fully constructed CCamera object. Ownership is passed

   987 	        to the caller.

   988 

   989 	@capability	UserEnvironment

   990 				An application that creates a CCamera object must have

   991 				the UserEnvironment capability.

   992 

   993 	@note   Applications using this method to create camera object may not receive enums/uids added in future(after being baselined).

   994 			To receive them, they should rather use New2L() or NewDuplicate2L(), in which case, they should prepare

   995 			themselves to receive unrecognised values.

   996 	*/

   997 	IMPORT_C static CCamera* NewL(MCameraObserver& aObserver,TInt aCameraIndex);

   998 

   999 	/**

  1000 	@deprecated Use static CCamera* NewDuplicate2L(MCameraObserver2& aObserver,TInt aCameraHandle);

  1001 

  1002 	Duplicates the original camera object for use by, for example, multimedia systems.

  1003 

  1004 	May leave with KErrNoMemory or KErrNotFound if aCameraHandle is not valid.

  1005 

  1006 	@param  aObserver

  1007 	        Reference to an observer.

  1008 	@param  aCameraHandle Handle of an existing camera object.

  1009 

  1010 	@leave  KErrNoMemory if out of memory.

  1011 	@leave  KErrNotFound if aCameraHandle is not valid.	   

  1012 	@leave  KErrPermissionDenied if the application does not have

  1013 	        the UserEnvironment capability.

  1014 

  1015 	@return Duplicate of the original camera object. 

  1016 	

  1017 	@capability	UserEnvironment

  1018 				An application that creates a CCamera object must have

  1019 				the UserEnvironment capability.

  1020 	

  1021 	@note   Applications using this method to create camera object may not receive enums/uids added in future(after being baselined). 

  1022 			To receive them, they should rather use New2L() or NewDuplicate2L(), in which case, they should prepare 

  1023 			themselves to receive unrecognised values.

  1024 	*/

  1025 	IMPORT_C static CCamera* NewDuplicateL(MCameraObserver2& aObserver,TInt aCameraHandle);

  1026 	

  1027 	/** 

  1028 	Duplicates the original camera object for use by, for example, multimedia systems.

  1029 	Clients prepare themselves to receive unrecognised enum, uids etc.

  1030 

  1031 	May leave with KErrNoMemory or KErrNotFound if aCameraHandle is not valid.

  1032 

  1033 	@param  aObserver

  1034 	        Reference to an observer.

  1035 	@param  aCameraHandle Handle of an existing camera object.

  1036 

  1037 	@leave  KErrNoMemory if out of memory.

  1038 	@leave  KErrNotFound if aCameraHandle is not valid.	   

  1039 	@leave  KErrPermissionDenied if the application does not have

  1040 	        the UserEnvironment capability.

  1041 

  1042 	@return Duplicate of the original camera object. 

  1043 	

  1044 	@capability	UserEnvironment

  1045 				An application that creates a CCamera object must have

  1046 				the UserEnvironment capability.

  1047 				

  1048 	@note   Clients using this creation method should prepare themselves to receive any unrecognised enum values, uids 

  1049 			from 'supported' or 'getter' methods

  1050 	*/

  1051 	IMPORT_C static CCamera* NewDuplicate2L(MCameraObserver2& aObserver,TInt aCameraHandle);

  1052 	

  1053 	/** 

  1054 	Duplicates the original camera object for use by, for example, multimedia systems.

  1055 

  1056 	@leave  KErrNoMemory if out of memory.

  1057 	@leave  KErrNotFound if aCameraHandle is not valid.	   

  1058 	@leave  KErrPermissionDenied if the application does not have

  1059 	        the UserEnvironment capability.

  1060 

  1061 	@param  aObserver

  1062 	        Reference to an observer.

  1063 	@param  aCameraHandle Handle of an existing camera object.

  1064 

  1065 	@return Duplicate of the original camera object. 

  1066 	

  1067 	@capability	UserEnvironment

  1068 				An application that creates a CCamera object must have

  1069 				the UserEnvironment capability.

  1070 				

  1071 	@note   Applications using this method to create camera object may not receive enums/uids added in future(after being baselined). 

  1072 			To receive them, they should rather use New2L() or NewDuplicate2L(), in which case, they should prepare 

  1073 			themselves to receive unrecognised values.

  1074 	*/

  1075 	IMPORT_C static CCamera* NewDuplicateL(MCameraObserver& aObserver,TInt aCameraHandle);	

  1076 

  1077 	/** 

  1078 	Gets information about the camera device.

  1079 

  1080 	@param  aInfo 

  1081 	        On return, information about the camera device. See TCameraInfo. 

  1082 	*/

  1083 	virtual void CameraInfo(TCameraInfo& aInfo) const=0;

  1084 

  1085 	/** 

  1086 	Asynchronous function that performs any required initialisation and reserves

  1087 	the camera for exclusive use.

  1088 

  1089 	Calls MCameraObserver:: ReserveComplete() when complete. 

  1090 	*/

  1091 	virtual void Reserve()=0;

  1092 

  1093 	/** 

  1094 	De-initialises the camera, allowing it to be used by other clients. 

  1095 	*/

  1096 	virtual void Release()=0;

  1097 

  1098 	/** 

  1099 	Asynchronous method to switch on camera power.

  1100 

  1101 	User must have successfully called Reserve() prior to calling this function.

  1102 

  1103 	Calls MCameraObserver::PowerOnComplete() when power on is complete. 

  1104 	*/

  1105 	virtual void PowerOn()=0;

  1106 

  1107 	/** 

  1108 	Synchronous function for switching off camera power. 

  1109 	*/

  1110 	virtual void PowerOff()=0;

  1111 

  1112 	/**

  1113 	Gets the device-unique handle of this camera object.

  1114 

  1115 	@return  The device-unique handle of this camera object. 

  1116 	*/

  1117 	virtual TInt Handle()=0;

  1118 

  1119 	/** 

  1120 	Sets the zoom factor.

  1121 

  1122 	This must be in the range of TCameraInfo::iMinZoom to TCameraInfo::iMaxZoom

  1123 	inclusive. May leave with KErrNotSupported if the specified zoom factor is

  1124 	out of range.

  1125 

  1126 	@param aZoomFactor 

  1127 	       Required zoom factor.

  1128 	*/

  1129 	virtual void SetZoomFactorL(TInt aZoomFactor = 0)=0;

  1130 

  1131 	/** 

  1132 	Gets the currently set zoom factor.

  1133 

  1134 	@return  The currently set zoom factor.

  1135 	*/