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