1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/os/mm/imagingandcamerafws/camerafw/source/CameraOverlay.cpp Fri Jun 15 03:10:57 2012 +0200
1.3 @@ -0,0 +1,509 @@
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 +#include <ecam/mcameraoverlay.h>
1.26 +#ifdef SYMBIAN_ENABLE_SPLIT_HEADERS
1.27 +#include <ecam/cameraoverlayconst.h>
1.28 +#endif
1.29 +#include "ecamversion.h"
1.30 +
1.31 +const TUint KBaselinedOverlayModeMask = (CCamera::CCameraOverlay::EModeVideo << 1) - 1;
1.32 +const TUint KOverlayGlobalStillMode = (CCamera::CCameraOverlay::EModeStillImageContinuous
1.33 + | CCamera::CCameraOverlay::EModeStillImageBracket
1.34 + | CCamera::CCameraOverlay::EModeStillImageBracketMerge
1.35 + | CCamera::CCameraOverlay::EModeStillImageTimed
1.36 + | CCamera::CCameraOverlay::EModeStillImageTimeLapse
1.37 + | CCamera::CCameraOverlay::EModeStillImageBurst);
1.38 +/**
1.39 +Factory function that creates a new camera overlay object on the heap.
1.40 +
1.41 +@param aCamera
1.42 + A reference to the camera object for which a camera overlay object is to be created.
1.43 +
1.44 +@leave KErrNoMemory if out of memory; also any system wide error.
1.45 +
1.46 +@return A pointer to the newly created camera overlay object.
1.47 +
1.48 +@note Clients using MCameraObserver are not recommended to use this extension class since they cannot handle events.
1.49 +*/
1.50 +
1.51 +EXPORT_C CCamera::CCameraOverlay* CCamera::CCameraOverlay::NewL(CCamera& aCamera)
1.52 + {
1.53 + CCamera::CCameraOverlay* self = new (ELeave) CCamera::CCameraOverlay(aCamera);
1.54 + CleanupStack::PushL(self);
1.55 + self->ConstructL();
1.56 + CleanupStack::Pop(self);
1.57 +
1.58 + return self;
1.59 + }
1.60 +
1.61 +/**
1.62 +CCameraOverlay second phase constructor.
1.63 +
1.64 +This function used to initialise internal state of the object.
1.65 +It uses reference to the camera to retrieve overlay interface pointer.
1.66 +
1.67 +@leave KErrNotSupported if this functionality is not supported; also any system wide error.
1.68 +*/
1.69 +void CCamera::CCameraOverlay::ConstructL()
1.70 + {
1.71 + iImpl = static_cast<MCameraOverlay*>(iOwner.CustomInterface(KECamMCameraOverlayUid));
1.72 +
1.73 + if (iImpl == NULL)
1.74 + {
1.75 + User::Leave(KErrNotSupported);
1.76 + }
1.77 +
1.78 + iImpl2 = static_cast<MCameraOverlay2*>(iOwner.CustomInterface(KECamMCameraOverlay2Uid));
1.79 + }
1.80 +
1.81 +/**
1.82 +Constructor for the CCamera::CCameraOverlay class.
1.83 +
1.84 +@param aOwner
1.85 + A reference to the camera object for which a camera overlay object is to be created.
1.86 +*/
1.87 +CCamera::CCameraOverlay::CCameraOverlay(CCamera& aOwner):iOwner(aOwner), iImpl(NULL), iImpl2(NULL)
1.88 + {
1.89 + }
1.90 +
1.91 +/**
1.92 +Destructor for the CCamera::CCameraOverlay class.
1.93 +*/
1.94 +EXPORT_C CCamera::CCameraOverlay::~CCameraOverlay()
1.95 + {
1.96 + if (iImpl != NULL)
1.97 + {
1.98 + iImpl->Release();
1.99 + }
1.100 + if (iImpl2 != NULL)
1.101 + {
1.102 + iImpl2->Release();
1.103 + }
1.104 + }
1.105 +
1.106 +/**
1.107 +Creates an image overlay object on the ECam implementation, returning a handle to the newly created object.
1.108 +
1.109 +@param aParameters
1.110 + The parameters characterizing the overlay to be created.
1.111 +@param aBitmap
1.112 + The image that is to become the overlay.
1.113 + By default this is set to NULL, allowing the client to provide the image at some point after
1.114 + the overlay object has been created, by using SetOverlayBitmapL().
1.115 +
1.116 +@leave KErrNoMemory if out of memory; also any system wide error.
1.117 +
1.118 +@leave KErrArgument if the member variables in TOverlayParameters are such that they create mutual exclusion.
1.119 +
1.120 +@return The overlay handle.
1.121 +*/
1.122 +EXPORT_C TUint CCamera::CCameraOverlay::CreateOverlayL(const TOverlayParameters& aParameters, CFbsBitmap* aBitmap)
1.123 + {
1.124 + CCamera::CCameraOverlay::TOverlayParameters overlayParameters = aParameters;
1.125 + if (aParameters.iCurrentModes & EModeViewfinder)
1.126 + {
1.127 + overlayParameters.iCurrentModes |= EModeClientViewfinder;
1.128 + overlayParameters.iCurrentModes |= EModeDirectViewfinder;
1.129 + }
1.130 + if (aParameters.iCurrentModes & EModeStillImage)
1.131 + {
1.132 + overlayParameters.iCurrentModes |= KOverlayGlobalStillMode;
1.133 + }
1.134 + return iImpl->CreateOverlayL(overlayParameters, aBitmap);
1.135 + }
1.136 +
1.137 +/**
1.138 +Allows the overlay image data to be changed for a specified overlay.
1.139 +Use this function to set the overlay image data if it was not specified when the overlay
1.140 +was created using CreateOverlayL().
1.141 +
1.142 +@param aOverlayHandle
1.143 + The handle of the overlay whose overlay image data is to be changed.
1.144 +@param aBitmap
1.145 + The new image data for the overlay.
1.146 +
1.147 +@leave KErrArgument if aOverlayHandle is out of range; also any system wide error.
1.148 +
1.149 +@note Once this method is called, overlay size should not be changed for the given overlay. Hence, SetOverlayParametersL
1.150 + should not be called after this method.
1.151 +*/
1.152 +EXPORT_C void CCamera::CCameraOverlay::SetOverlayBitmapL(TUint aOverlayHandle, const CFbsBitmap* aBitmap)
1.153 + {
1.154 + iImpl->SetOverlayBitmapL(aOverlayHandle, aBitmap);
1.155 + }
1.156 +
1.157 +/**
1.158 +@publishedPartner
1.159 +@prototype
1.160 +
1.161 +Allows the overlay image data to be changed for a specified overlay. Ownership of the bitmap is passed to the
1.162 +implementation.
1.163 +Use this function to set the overlay image data if it was not specified when the overlay was created using
1.164 +CreateOverlayL().
1.165 +
1.166 +@param aOverlayHandle
1.167 + The handle of the overlay whose overlay image data is to be changed.
1.168 +@param aBitmap
1.169 + The new image data for the overlay.
1.170 +
1.171 +@leave May leave with any error code.
1.172 +
1.173 +@note If required, implementation is free to modify the overlay bitmap passed to it.
1.174 +
1.175 +@note SetOverlayParametersL should not be called after this method for the given overlay since it may change the overlay
1.176 + parameters considerably. In such a case, SetOverlayParametersL may leave with error KErrArgument.
1.177 +*/
1.178 +EXPORT_C void CCamera::CCameraOverlay::SetModifiableOverlayBitmapL(TUint aOverlayHandle, CFbsBitmap* aBitmap)
1.179 + {
1.180 + if(iImpl2 != NULL)
1.181 + {
1.182 + iImpl2->SetModifiableOverlayBitmapL(aOverlayHandle, aBitmap);
1.183 + }
1.184 + else
1.185 + {
1.186 + User::Leave(KErrNotSupported);
1.187 + }
1.188 + }
1.189 +
1.190 +/**
1.191 +Gets the overlay image data for a specified overlay.
1.192 +
1.193 +@param aOverlayHandle
1.194 + The handle of the overlay whose overlay image data is to be obtained.
1.195 +@param aBitmap
1.196 + A CFbsBitmap that will receive the returned image data for the overlay.
1.197 +
1.198 +@leave KErrArgument if aOverlayHandle is out of range; also any system wide error.
1.199 +
1.200 +@leave KErrNotSupported if a sharing client (which did not create the given overlay) tries to retrieve the overlay bitmap
1.201 + and the implementation may not be interested in providing the overlay.
1.202 +
1.203 +@note The ECam implementation will transfer the ownership of the aBitmap to the client.
1.204 +*/
1.205 +EXPORT_C void CCamera::CCameraOverlay::GetOverlayBitmapL(TUint aOverlayHandle, CFbsBitmap* aBitmap)
1.206 + {
1.207 + iImpl->GetOverlayBitmapL(aOverlayHandle, aBitmap);
1.208 + }
1.209 +
1.210 +/**
1.211 +Gets the parameters that characterize a given overlay.
1.212 +
1.213 +@param aOverlayHandle
1.214 + The handle of the overlay whose parameters are required.
1.215 +@param aInfo
1.216 + Reference to TOverlayParameters object that will contain the returned overlay parameters.
1.217 +
1.218 +@leave KErrArgument if aOverlayHandle is out of range; also any system wide error.
1.219 +*/
1.220 +EXPORT_C void CCamera::CCameraOverlay::GetOverlayParametersL(TUint aOverlayHandle, TOverlayParameters& aInfo)
1.221 + {
1.222 + iImpl->GetOverlayParametersL(aOverlayHandle, aInfo);
1.223 +
1.224 + // for clients not using CCamera::New2L() turn new overlay modes into old ones
1.225 + if (iOwner.CameraVersion() == KCameraDefaultVersion)
1.226 + {
1.227 + // specific viewfinder modes into "old" EModeViewfinder
1.228 + if (aInfo.iCurrentModes & (EModeClientViewfinder | EModeDirectViewfinder))
1.229 + {
1.230 + aInfo.iCurrentModes |= EModeViewfinder;
1.231 + }
1.232 + // turn different drive modes into "old" EModeStillImage
1.233 + if (aInfo.iCurrentModes & ( EModeStillImageContinuous | EModeStillImageBracket |
1.234 + EModeStillImageBracketMerge | EModeStillImageTimed |
1.235 + EModeStillImageTimeLapse | EModeStillImageBurst
1.236 + )
1.237 + )
1.238 + {
1.239 + aInfo.iCurrentModes |= EModeStillImage;
1.240 + }
1.241 + // for old clients we present only old set of features
1.242 + aInfo.iCurrentModes &= KBaselinedOverlayModeMask;
1.243 + }
1.244 + else
1.245 + {
1.246 + if (aInfo.iCurrentModes & EModeViewfinder)
1.247 + {
1.248 + aInfo.iCurrentModes |= EModeClientViewfinder;
1.249 + aInfo.iCurrentModes |= EModeDirectViewfinder;
1.250 + }
1.251 + if (aInfo.iCurrentModes & EModeStillImage)
1.252 + {
1.253 + aInfo.iCurrentModes |= KOverlayGlobalStillMode;
1.254 + }
1.255 + }
1.256 + }
1.257 +
1.258 +/**
1.259 +Sets new parameters that characterize a given overlay.
1.260 +
1.261 +@param aOverlayHandle
1.262 + The handle of the overlay whose parameters are to be changed.
1.263 +@param aParameters
1.264 + The new overlay parameters.
1.265 +
1.266 +@leave KErrNotSupported if TOverlayCameraMode passed in TOverlayParameters is not supported;
1.267 + also any system wide error.
1.268 +
1.269 +@leave KErrArgument if the member variables in TOverlayParameters are such that they create mutual exclusion.
1.270 +*/
1.271 +EXPORT_C void CCamera::CCameraOverlay::SetOverlayParametersL(TUint aOverlayHandle, const TOverlayParameters& aParameters)
1.272 + {
1.273 + CCamera::CCameraOverlay::TOverlayParameters overlayParameters = aParameters;
1.274 + if (aParameters.iCurrentModes & EModeViewfinder)
1.275 + {
1.276 + overlayParameters.iCurrentModes |= EModeClientViewfinder;
1.277 + overlayParameters.iCurrentModes |= EModeDirectViewfinder;
1.278 + }
1.279 + if (aParameters.iCurrentModes & EModeStillImage)
1.280 + {
1.281 + overlayParameters.iCurrentModes |= KOverlayGlobalStillMode;
1.282 + }
1.283 +
1.284 + iImpl->SetOverlayParametersL(aOverlayHandle, overlayParameters);
1.285 + }
1.286 +
1.287 +/**
1.288 +Releases the specified overlay handle.
1.289 +
1.290 +@note If the handle specified in aOverlayHandle is invalid (out of range) the function
1.291 + call is ignored and no error is reported.
1.292 +
1.293 +@param aOverlayHandle
1.294 + The handle of the overlay that is to be released.
1.295 +*/
1.296 +EXPORT_C void CCamera::CCameraOverlay::ReleaseOverlay(TUint aOverlayHandle)
1.297 + {
1.298 + iImpl->ReleaseOverlay(aOverlayHandle);
1.299 + }
1.300 +
1.301 +/**
1.302 +Gets information on the overlay functionality supported by the ECam implementation.
1.303 +
1.304 +@param aInfo
1.305 + A reference to a TOverlaySupportInfo object that will receive the overlay support information.
1.306 +*/
1.307 +EXPORT_C void CCamera::CCameraOverlay::GetOverlaySupport(TOverlaySupportInfo& aInfo)
1.308 + {
1.309 + iImpl->GetOverlaySupport(aInfo);
1.310 + // we hide new overlay modes for clients not using New2L()/NewDuplicate2L()
1.311 + if (iOwner.CameraVersion() == KCameraDefaultVersion)
1.312 + {
1.313 + aInfo.iSupportedModes &= KBaselinedOverlayModeMask;
1.314 + }
1.315 + else
1.316 + {
1.317 + if (aInfo.iSupportedModes & EModeViewfinder)
1.318 + {
1.319 + aInfo.iSupportedModes |= EModeClientViewfinder;
1.320 + aInfo.iSupportedModes |= EModeDirectViewfinder;
1.321 + }
1.322 + if (aInfo.iSupportedModes & EModeStillImage)
1.323 + {
1.324 + aInfo.iSupportedModes |= KOverlayGlobalStillMode;
1.325 + }
1.326 + }
1.327 + }
1.328 +
1.329 +/**
1.330 +Gets all the overlay handles maintained by the ECam implementation, in order of their Z-Value.
1.331 +
1.332 +@param aOverlayHandles
1.333 + Returned list, in Z-Value order, of all the overlay handles maintained on the ECam implementation.
1.334 + The topmost overlay is the first element of the array.
1.335 +
1.336 +@leave KErrNoMemory if out of memory; also any system wide error.
1.337 +
1.338 +@note Implementation shall give preference to the sequence in which the client has passed the overlay handles in case of
1.339 + any mis-match with the 'z-order' of each such overlay. Implementation shall amend the 'z-order' of the overlays if
1.340 + required to remove any ambiguity.
1.341 +*/
1.342 +EXPORT_C void CCamera::CCameraOverlay::GetAllOverlaysInZOrderL(RArray<TUint>& aOverlayHandles)
1.343 + {
1.344 + iImpl->GetAllOverlaysInZOrderL(aOverlayHandles);
1.345 + }
1.346 +
1.347 +/**
1.348 +Sets the Z-Order of all the overlay handles known by this CCameraOverlay object.
1.349 +
1.350 +@param aOverlayHandles
1.351 + The overlay handles in aOverlayHandles array. This must be the complete current set
1.352 + of handles known to this CCameraOverlay object. The client specifies the desired
1.353 + order by placing the topmost overlay in the first element of the array.
1.354 +
1.355 +@leave KErrNoMemory if out of memory; also any system wide error.
1.356 +
1.357 +@note Implementation shall give preference to the sequence in which the client has passed the overlay handles in case of
1.358 + any mis-match with the 'z-order' of each such overlay. Implementation shall amend the 'z-order' of the overlays if
1.359 + required to remove any ambiguity.
1.360 +*/
1.361 +EXPORT_C void CCamera::CCameraOverlay::SetAllOverlaysInZOrderL(const RArray<TUint>& aOverlayHandles)
1.362 + {
1.363 + iImpl->SetAllOverlaysInZOrderL(aOverlayHandles);
1.364 + }
1.365 +
1.366 +/**
1.367 +Constructor for the TOverlaySupportInfo class.
1.368 +*/
1.369 +EXPORT_C CCamera::CCameraOverlay::TOverlaySupportInfo::TOverlaySupportInfo()
1.370 + {
1.371 + iDesiredCameraMode = CCamera::CCameraOverlay::EModeNone;
1.372 + iViewFinderHandle = KECamOverlayInvalidViewFinderHandle;
1.373 + }
1.374 +
1.375 +/**
1.376 +Returns the size of the class. Used for extensibility by deriving from this base class and adding new member variables.
1.377 +Intended to be used for implementation of methods where this class reference is passed as function arguments.
1.378 +Implementation of such methods can find out the whether the actual class passed is base or the derived one. So, if a new application
1.379 +is made to run on an old implementation, an error may occur once the old implementation detects this by getting
1.380 +the size information of the T class passed. Also, if an old application is made to run on a new implementation, this can be
1.381 +corrrectly handled if the derived class variables handling is done in a proper 'if-else' statement.
1.382 +
1.383 +@return The size of the class.
1.384 +
1.385 +@note The size will be modified when the T-class gets updated.
1.386 +*/
1.387 +EXPORT_C TUint CCamera::CCameraOverlay::TOverlaySupportInfo::Size() const
1.388 + {
1.389 + return sizeof(CCamera::CCameraOverlay::TOverlaySupportInfo);
1.390 + }
1.391 +
1.392 +/**
1.393 +Returns the version of the class. Used for extensibility specially when the class members are not added but the Reserved
1.394 +members get used at a later stage.
1.395 +
1.396 +@return The version of the class.
1.397 +
1.398 +@note The version will be modified when the T-class gets updated.
1.399 +*/
1.400 +EXPORT_C TUint CCamera::CCameraOverlay::TOverlaySupportInfo::Version() const
1.401 + {
1.402 + return KECamOverlaySupportInfoCurrentVersion;
1.403 + }
1.404 +
1.405 +/**
1.406 +Constructor for the TOverlayParameters class.
1.407 +*/
1.408 +EXPORT_C CCamera::CCameraOverlay::TOverlayParameters::TOverlayParameters()
1.409 + {
1.410 + iViewFinderHandle = KECamOverlayInvalidViewFinderHandle;
1.411 + }
1.412 +
1.413 +/**
1.414 +Returns the size of the class. Used for extensibility by deriving from this base class and adding new member variables.
1.415 +Intended to be used for implementation of methods where this class reference is passed as function arguments.
1.416 +Implementation of such methods can find out the whether the actual class passed is base or the derived one. So, if a new application
1.417 +is made to run on an old implementation, an error may occur once the old implementation detects this by getting
1.418 +the size information of the T class passed. Also, if an old application is made to run on a new implementation, this can be
1.419 +corrrectly handled if the derived class variables handling is done in a proper 'if-else' statement.
1.420 +
1.421 +@return The size of the class.
1.422 +
1.423 +@note The size will be modified when the T-class gets updated.
1.424 +*/
1.425 +EXPORT_C TUint CCamera::CCameraOverlay::TOverlayParameters::Size() const
1.426 + {
1.427 + return sizeof(CCamera::CCameraOverlay::TOverlayParameters);
1.428 + }
1.429 +
1.430 +/**
1.431 +Returns the version of the class. Used for extensibility specially when the class members are not added but the Reserved
1.432 +members get used at a later stage.
1.433 +
1.434 +@return The version of the class.
1.435 +
1.436 +@note The version will be modified when the T-class gets updated.
1.437 +*/
1.438 +EXPORT_C TUint CCamera::CCameraOverlay::TOverlayParameters::Version() const
1.439 + {
1.440 + return KECamOverlayParametersCurrentVersion;
1.441 + }
1.442 +
1.443 +/**
1.444 +@publishedPartner
1.445 +@prototype
1.446 +
1.447 +Gets all the overlay handles maintained by the ECam implementation, in order of their z-value, for a particular camera mode.
1.448 +If for viewfinder, then the handle number is used to get the z-value for the viewfinder whose handle number is passed.
1.449 +
1.450 +@param aOverlayCameraMode
1.451 + The specific camera mode whose overlays' z-value information is required.
1.452 +
1.453 +@param aViewFinderHandle
1.454 + The specific viewfinder handle, if overlays' z-value information is required for viewfinder camera mode.
1.455 +
1.456 +@param aOverlayHandles
1.457 + Returned list, in z-value order, of all the overlay handles maintained on the ECam implementation.
1.458 + The topmost overlay is the first element of the array.
1.459 +
1.460 +@leave May leave with any error code.
1.461 +
1.462 +@note Implementation shall give preference to the sequence in which the client has passed the overlay handles in case of
1.463 + any mis-match with the 'z-order' of each such overlay. Implementation shall amend the 'z-order' of the overlays if
1.464 + required to remove any ambiguity.
1.465 +*/
1.466 +EXPORT_C void CCamera::CCameraOverlay::GetAllOverlaysInZOrderL(CCamera::CCameraOverlay::TOverlayCameraMode aOverlayCameraMode, TInt aViewFinderHandle, RArray<TUint>& aOverlayHandles) const
1.467 + {
1.468 + if(iImpl2 != NULL)
1.469 + {
1.470 + iImpl2->GetAllOverlaysInZOrderL(aOverlayCameraMode, aViewFinderHandle, aOverlayHandles);
1.471 + }
1.472 + else
1.473 + {
1.474 + User::Leave(KErrNotSupported);
1.475 + }
1.476 + }
1.477 +
1.478 +/**
1.479 +@publishedPartner
1.480 +@prototype
1.481 +
1.482 +Sets all the overlay handles maintained by the ECam implementation, in order of their z-value for a particular camera mode.
1.483 +If for viewfinder, then the handle number is used to set the z-value for the viewfinder whose handle number is passed.
1.484 +
1.485 +@param aOverlayCameraMode
1.486 + The specific camera mode whose overlays' z-value is to be set.
1.487 +
1.488 +@param aViewFinderHandle
1.489 + The specific viewfinder handle, if overlays' z-value is required to be set for viewfinder camera mode.
1.490 +
1.491 +@param aOverlayHandles
1.492 + The overlay handles in aOverlayHandles array. This must be the complete current set
1.493 + of handles known to this CCameraOverlay object for the given camera mode (and for the given viewfinder, if applicable).
1.494 + The client specifies the desired order by placing the topmost overlay in the first element of the array.
1.495 +
1.496 +@leave May leave with any error code.
1.497 +
1.498 +@note Implementation shall give preference to the sequence in which the client has passed the overlay handles in case of
1.499 + any mis-match with the 'z-order' of each such overlay. Implementation shall amend the 'z-order' of the overlays if
1.500 + required to remove any ambiguity.
1.501 +*/
1.502 +EXPORT_C void CCamera::CCameraOverlay::SetAllOverlaysInZOrderL(CCamera::CCameraOverlay::TOverlayCameraMode aOverlayCameraMode, TInt aViewFinderHandle, const RArray<TUint>& aOverlayHandles)
1.503 + {
1.504 + if(iImpl2 != NULL)
1.505 + {
1.506 + iImpl2->SetAllOverlaysInZOrderL(aOverlayCameraMode, aViewFinderHandle, aOverlayHandles);
1.507 + }
1.508 + else
1.509 + {
1.510 + User::Leave(KErrNotSupported);
1.511 + }
1.512 + }