os/mm/imagingandcamerafws/camerafw/Include/CameraOverlay.h
changeset 0 bde4ae8d615e
     1.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.2 +++ b/os/mm/imagingandcamerafws/camerafw/Include/CameraOverlay.h	Fri Jun 15 03:10:57 2012 +0200
     1.3 @@ -0,0 +1,314 @@
     1.4 +// Copyright (c) 2005-2009 Nokia Corporation and/or its subsidiary(-ies).
     1.5 +// All rights reserved.
     1.6 +// This component and the accompanying materials are made available
     1.7 +// under the terms of "Eclipse Public License v1.0"
     1.8 +// which accompanies this distribution, and is available
     1.9 +// at the URL "http://www.eclipse.org/legal/epl-v10.html".
    1.10 +//
    1.11 +// Initial Contributors:
    1.12 +// Nokia Corporation - initial contribution.
    1.13 +//
    1.14 +// Contributors:
    1.15 +//
    1.16 +// Description:
    1.17 +//
    1.18 +
    1.19 +/**
    1.20 + @file
    1.21 + @publishedAll
    1.22 + @released
    1.23 +*/
    1.24 +
    1.25 +#ifndef CAMERAOVERLAY_H
    1.26 +#define CAMERAOVERLAY_H
    1.27 +
    1.28 +#include <ecam.h>
    1.29 +#include <ecam/ecamcommonuids.hrh>
    1.30 +#ifndef SYMBIAN_ENABLE_SPLIT_HEADERS
    1.31 +#include <ecam/cameraoverlayconst.h>
    1.32 +#endif
    1.33 +
    1.34 +class MCameraOverlay;
    1.35 +class MCameraOverlay2;
    1.36 +
    1.37 +
    1.38 +/** 
    1.39 +This is the UID which is used to obtain the CCameraOverlay interface, 
    1.40 +via a call to CCamera::CustomInterface().
    1.41 +
    1.42 +@see KECamOverlayUidValue
    1.43 +@see CCamera::CCameraOverlay
    1.44 +*/
    1.45 +static const TUid  KECamOverlayUid = {KECamOverlayUidValue};
    1.46 +
    1.47 +	
    1.48 +/**
    1.49 +This class provides support for image overlays. 
    1.50 +The client can use it to overlay an image onto the viewfinder, snapshots, still images and video. 
    1.51 +A client can create multiple overlays, where each overlay can be in a different format. 
    1.52 +The properties of an overlay can be changed after it has been created.
    1.53 +
    1.54 +@note This class provides a standardised client interface for the camera overlay. Classes cannot be derived from it.
    1.55 +
    1.56 +@note   If the class methods leave, the output type parameter value is not guaranteed to be valid.
    1.57 +
    1.58 +@publishedAll
    1.59 +@released
    1.60 +*/
    1.61 +class CCamera::CCameraOverlay: public CBase
    1.62 +	{
    1.63 +	
    1.64 +	friend class CCamera;
    1.65 +	
    1.66 +public:	
    1.67 +	/** 
    1.68 +	Overlay camera mode types 
    1.69 +	 
    1.70 +	Represents the possible camera modes in which the overlay could be used.
    1.71 +	Several types can be combined when returning ECam implementation support for various modes. 
    1.72 +	*/
    1.73 +	enum TOverlayCameraMode
    1.74 +		{
    1.75 +		/**	Overlays are not supported for any camera mode. */
    1.76 +		EModeNone 		=  0x00,
    1.77 +		/**	The image can be overlaid on captured images.
    1.78 +		The camera is in still image mode. This effectively means all the still image drive modes and
    1.79 +		its interpretation may be implementation-specific. 
    1.80 +		Explicit definition of drive modes is recommended instead.
    1.81 +		*/
    1.82 +		EModeStillImage	=  0x01,
    1.83 +		/**	The image can be overlaid on a snapshot.
    1.84 +		The camera has snapshot functionality set on. 
    1.85 +		*/
    1.86 +		EModeSnapshot	=  0x02,		
    1.87 +		/**	
    1.88 +		The image can be overlaid on a viewfinder. 
    1.89 +		The camera is displaying directly to viewfinder. 
    1.90 +		This mode shall not be used if any of the viewfinder submodes is specified.
    1.91 +		    @note Overlay visibility for different viewfinder modes (direct/client-based) is 
    1.92 +		    implementation-specific; viewfinder modes should be explicitly specified by clients instead.
    1.93 +		*/
    1.94 +		EModeViewfinder	=  0x04,
    1.95 +		/**	The image can be overlaid on a video frame. 
    1.96 +		The camera is in video mode. */
    1.97 +		EModeVideo		=  0x08,
    1.98 +		/**
    1.99 +		    The image is to be overlaid on direct viewfinder
   1.100 +		    @note This value is available only to the API clients using CCamera::New2L() or CCamera::NewDuplicate2L()
   1.101 +		*/
   1.102 +		EModeDirectViewfinder       = 0x00010,
   1.103 +		/**
   1.104 +		    The image is to be overlaid on client-based viewfinder
   1.105 +		    @note This value is available only to the API clients using CCamera::New2L() or CCamera::NewDuplicate2L()
   1.106 +		*/
   1.107 +		EModeClientViewfinder       = 0x00020,
   1.108 +		/**
   1.109 +		    The image is to be overlaid when Continuous Still Image driving mode is active.
   1.110 +		    @note This value is available only to the API clients using CCamera::New2L() or CCamera::NewDuplicate2L()
   1.111 +		*/		
   1.112 +		EModeStillImageContinuous   = 0x00080,
   1.113 +		/**
   1.114 +		    The image is to be overlaid when Still Image Bracketing driving mode is active.
   1.115 +		    @note This value is available only to the API clients using CCamera::New2L() or CCamera::NewDuplicate2L()
   1.116 +		*/		
   1.117 +        EModeStillImageBracket		= 0x00100,
   1.118 +		/**
   1.119 +		    The image is to be overlaid when Still Image Bracketing with Merge option driving mode is active.
   1.120 +		    @note This value is available only to the API clients using CCamera::New2L() or CCamera::NewDuplicate2L()
   1.121 +		*/        
   1.122 +        EModeStillImageBracketMerge	= 0x00200,
   1.123 +		/**
   1.124 +		    The image is to be overlaid when Timed Still Image driving mode is active.
   1.125 +		    @note This value is available only to the API clients using CCamera::New2L() or CCamera::NewDuplicate2L()
   1.126 +		*/         
   1.127 +        EModeStillImageTimed		= 0x00400,
   1.128 +		/**
   1.129 +		    The image is to be overlaid when Timed Still Image with Lapse option driving mode is active.
   1.130 +		    @note This value is available only to the API clients using CCamera::New2L() or CCamera::NewDuplicate2L()
   1.131 +		*/         
   1.132 +        EModeStillImageTimeLapse	= 0x00800,
   1.133 +		/**
   1.134 +		    The image is to be overlaid when Still Image Burst driving mode is active.
   1.135 +		    @note This value is available only to the API clients using CCamera::New2L() or CCamera::NewDuplicate2L()
   1.136 +		*/         
   1.137 +        EModeStillImageBurst		= 0x01000
   1.138 +		};
   1.139 +	
   1.140 +	/** 
   1.141 +	Overlay types 
   1.142 +	 
   1.143 +	Type in which alpha value will be provided.
   1.144 +	*/
   1.145 +	enum TOverlayType
   1.146 +		{
   1.147 +		/** Does not support overlays. */
   1.148 +		EOverlayNone  	=  0x00,
   1.149 +		/** Blending is on a per pixel basis, where the alpha value information is provided in the overlay bitmap itself. 
   1.150 +		The alpha value is specified in each pixel of the bitmap (it is the alpha componenet of the TRgb object). The 
   1.151 +		display mode of the bitmap should be such that alpha value is supported. TOverlayParameters::iAlphaValue is 
   1.152 +		neglected in this case. */
   1.153 +		EPerPixel		=  0x01,
   1.154 +		/** Blending is on a per plane basis, where all pixels are affected by the same alpha value. The alpha value is
   1.155 +		provided through TOverlayParameters::iAlphaValue. */
   1.156 +		EPerPlane		=  0x02	
   1.157 +		};
   1.158 +	
   1.159 +	/** 
   1.160 +	Blending types 
   1.161 +	 
   1.162 +	Type of supported blending.
   1.163 +	*/
   1.164 +	enum TBlendingType
   1.165 +		{
   1.166 +		/** Does not support blending. */
   1.167 +		EBlendNone,
   1.168 +		/** Supports only binary blending. If alpha value is 0xFF, it is opaque, otherwise transparent. */
   1.169 +		EBinary,
   1.170 +		/** Full support for blending - all values in the range [0:255]. */
   1.171 +		EFullRange,
   1.172 +		/** Supports only dynamic binary blending - 
   1.173 +		allows values to be changed when overlay is being displayed. If alpha value is 0xFF, it is opaque, 
   1.174 +		otherwise transparent. Since the blending is dynamic, SetModifiableOverlayBitmapL shall be used such that the
   1.175 +		bitmap could be changed by the implementation. */
   1.176 +		EBinaryDynamic,
   1.177 +		/** Full support for dynamic blending - all values in the range [0:255] 
   1.178 +		- allows values to be changed when overlay is being displayed. Since the blending is dynamic, 
   1.179 +		SetModifiableOverlayBitmapL shall be used such that the bitmap could be changed by the implementation. */
   1.180 +		EFullRangeDynamic
   1.181 +		};
   1.182 +		
   1.183 +	/**
   1.184 + 	Overlay support information characterizing the overlay functionality as a whole.
   1.185 + 	@publishedPartner
   1.186 +	@prototype
   1.187 + 	*/
   1.188 +	class TOverlaySupportInfo
   1.189 +	{
   1.190 +	public:
   1.191 +		IMPORT_C explicit TOverlaySupportInfo();
   1.192 +		
   1.193 +		IMPORT_C TUint Size() const;
   1.194 +		IMPORT_C TUint Version() const;
   1.195 +		
   1.196 +	public:
   1.197 +		/** The camera modes that the ECam implementation supports when applying overlays.
   1.198 +		The modes are held as a bitwise logical OR of the relevant individual modes
   1.199 +		defined in CCamera::CCameraOverlay::TOverlayCameraMode. */
   1.200 +		TUint 		  iSupportedModes; 
   1.201 +		/** The camera types that the ECam implementation supports when applying overlays.
   1.202 +		The types are held as a bitwise logical OR of the relevant individual types
   1.203 +		defined in CCamera::CCameraOverlay::TOverlayType. */
   1.204 +		TUint 		  iSupportedTypes; 
   1.205 +		/** Represents blending type for EPerPlane overlay Type.*/
   1.206 +		TBlendingType iPerPlane;
   1.207 +		/** Represents blending type for EPerPixel overlay Type.*/
   1.208 +		TBlendingType iPerPixel;
   1.209 +		/** Whether overlapping overlays are supported. */
   1.210 +		TBool         iCanOverlap;  
   1.211 +		
   1.212 +		/** This is an input parameter which the client needs to provide. It represents the specific camera mode for which
   1.213 +		the overlay support information is required.
   1.214 +		Default values for iDesiredCameraMode (that is, CCamera::CCameraOverlay::EModeNone) and iViewFinderHandle (that is, 
   1.215 +		KECamOverlayInvalidViewFinderHandle) implies that the client is using the TOverlaySupportInfo as before and 
   1.216 +		iSupportedModes will not be neglected. Refer to TOverlaySupportInfo().
   1.217 +		*/
   1.218 +		TOverlayCameraMode iDesiredCameraMode;
   1.219 +		/** This is also another input parameter which the client needs to provide. It represents the specific viewfinder 
   1.220 +		handle for which the overlay support information is required. 
   1.221 +		If iViewFinderHandle is KECamOverlayNoSpecificViewFinderHandle, then generic overlay support is required which will 
   1.222 +		be valid for every viewfinder handle of type iDesiredCameraMode.
   1.223 +		Default values for iDesiredCameraMode (that is, CCamera::CCameraOverlay::EModeNone) and iViewFinderHandle (that is, 
   1.224 +		KECamOverlayInvalidViewFinderHandle) implies that the client is using the TOverlaySupportInfo as before and 
   1.225 +		iSupportedModes will not be neglected. Refer to TOverlaySupportInfo().
   1.226 +		*/
   1.227 +		TInt iViewFinderHandle; 
   1.228 +		
   1.229 +		private:
   1.230 +		// reserved for future expansion
   1.231 +		TInt iReserved3;	 
   1.232 +	};
   1.233 +		
   1.234 +	/**
   1.235 + 	Overlay parameters characterizing a particular overlay.
   1.236 + 	@publishedPartner
   1.237 +	@prototype
   1.238 + 	*/
   1.239 +	class TOverlayParameters
   1.240 +	{
   1.241 +	public:
   1.242 +		IMPORT_C explicit TOverlayParameters();
   1.243 +		
   1.244 +		IMPORT_C TUint Size() const;
   1.245 +		IMPORT_C TUint Version() const;		
   1.246 +		
   1.247 +	public:
   1.248 +		/** The camera modes in which this image overlay can be used.
   1.249 +		The modes are held as a bitwise logical OR of the relevant individual modes
   1.250 +		defined in CCamera::CCameraOverlay::TOverlayCameraMode. */
   1.251 +		TUint 	iCurrentModes; 	
   1.252 +		/** The camera types in which this image overlay can be used.
   1.253 +		The types are held as a bitwise logical OR of the relevant individual types
   1.254 +		defined in CCamera::CCameraOverlay::TOverlayType. */
   1.255 +		TUint 	iCurrentTypes; 	
   1.256 +		/** This is the alpha value to be applied when iCurrentTypes contains type 
   1.257 +		CCamera::CCameraOverlay::TOverlayType::EPerPlane. The alpha value for red, green and blue is packed into this
   1.258 +		TInt. The layout of this TInt is such that the most significant byte (from left side) is not used at all and the
   1.259 +		remaining three bytes (after the most significant byte) contains the alpha value for red, green and blue.
   1.260 +		Otherwise, if iCurrentTypes only contains type CCamera::CCameraOverlay::TOverlayType::EPerPixel, 
   1.261 +		then iAlphaValue will not be used. */
   1.262 +		TInt 	iAlphaValue; 	
   1.263 +		/** Top left corner within the original image, where the overlay image is to be blended. */
   1.264 +		TPoint 	iPosition; 		
   1.265 +		/** The z-order of the overlay to indicate relative depth when several overlays are applied.
   1.266 +		Values are in the range 0 to 100. The overlay with iZOrder of 0 is the deepest.*/
   1.267 +		TUint   iZOrder;       
   1.268 +		/** The handle for the viewfinder on which the overlay is supposed to be applied. Only one viewfinder handle can be passed.
   1.269 +		If KECamOverlayNoSpecificViewFinderHandle is provided by the client, then the overlay is supposed to be applied for every
   1.270 +		viewfinder handle of type as given by iCurrentModes.
   1.271 +		If KECamOverlayInvalidViewFinderHandle, then the default implementation is being used where 
   1.272 +		TOverlayParameters::iCurrentModes will not be neglected and overlay will be applied for every viewfinder alongwith
   1.273 +		other camera modes.
   1.274 +		*/
   1.275 +		TInt iViewFinderHandle;
   1.276 +	private:
   1.277 +		// reserved for future expansion.
   1.278 +		TInt iReserved2;
   1.279 +		TInt iReserved3;
   1.280 +		// Reserved members which came into existence as a result of removing Tsize public member variable.
   1.281 +		TInt iReserved4;
   1.282 +		TInt iReserved5;	 
   1.283 +	};
   1.284 +		
   1.285 +public:
   1.286 +	
   1.287 +	IMPORT_C static CCameraOverlay* NewL(CCamera& aCamera);
   1.288 +	IMPORT_C ~CCameraOverlay();
   1.289 +	IMPORT_C void GetOverlaySupport(TOverlaySupportInfo& aInfo);   
   1.290 +
   1.291 +	IMPORT_C TUint CreateOverlayL(const TOverlayParameters& aParameters, CFbsBitmap* aBitmap);
   1.292 +	IMPORT_C void ReleaseOverlay(TUint aOverlayHandle);
   1.293 +
   1.294 +	IMPORT_C void SetOverlayBitmapL(TUint aOverlayHandle, const CFbsBitmap* aBitmap);
   1.295 +	IMPORT_C void SetModifiableOverlayBitmapL(TUint aOverlayHandle, CFbsBitmap* aBitmap);
   1.296 +		
   1.297 +	IMPORT_C void GetOverlayBitmapL(TUint aOverlayHandle, CFbsBitmap* aBitmap);
   1.298 +	IMPORT_C void GetOverlayParametersL(TUint aOverlayHandle, TOverlayParameters& aInfo);
   1.299 +	IMPORT_C void SetOverlayParametersL(TUint aOverlayHandle, const TOverlayParameters& aParameters);
   1.300 +
   1.301 +	IMPORT_C void GetAllOverlaysInZOrderL(RArray<TUint>& aOverlayHandles);
   1.302 +	IMPORT_C void SetAllOverlaysInZOrderL(const RArray<TUint>& aOverlayHandles);
   1.303 +	
   1.304 +	IMPORT_C void GetAllOverlaysInZOrderL(TOverlayCameraMode aOverlayCameraMode, TInt aViewFinderHandle, RArray<TUint>& aOverlayHandles) const;
   1.305 +	IMPORT_C void SetAllOverlaysInZOrderL(TOverlayCameraMode aOverlayCameraMode, TInt aViewFinderHandle, const RArray<TUint>& aOverlayHandles);
   1.306 +
   1.307 +private:
   1.308 +	CCameraOverlay(CCamera& aOwner);
   1.309 +	void ConstructL();
   1.310 +
   1.311 +private:
   1.312 +	CCamera&        iOwner; 
   1.313 +	MCameraOverlay* iImpl;    // not owned
   1.314 +	MCameraOverlay2* iImpl2;  // not owned
   1.315 +	};	
   1.316 +
   1.317 +#endif // CAMERAOVERLAY_H