Working with Overlays

Purpose

This documents provides detailed description about creating and working with Overlays.

Setup and Configuration Requirements

The following are the setup and configuration requirements you need to follow before Overlay implementation:

• Licensee need to provide McameraOverlay, interface class implementation.

• The providers of the camera extension API for extra features of image overlays, must provide MCameraOverlay2, interface class implementation.

Creating Overlays

The following tasks cover the creation of overlays:

1. Create an object of class Ccamera::CCameraOverlay using the CcameraOverlay::NewL() factory method.

   This class maps the exported call to McameraOverlay class and McameraOverlay2, which provides the overlay functionality.

2. In second phase construction for CCameraOverlay,

   • retrieve the handle to the concrete implementation for McameraOverlay and McameraOverlay2 using Ccamera::CustomInterface() method, when specific UIDS are passed.

   • KECamMCameraOverlayUid and KECamMCameraOverlay2Uid are used to retrieve handle for McameraOverlay and McameraOverlay2 derived class objects respectively.

3. Get information about the overlay functionality supported by the ECam implementation server using CCamera::CCameraOverlay::GetOverlaySupport() method.

   • Class Ccamera::CcameraOverlay::ToverlaySupportInfo retrieves the supported color formats.

   • ECam implementation uses ToverlaySupportInfo::Size() and ToverlaySupportInfo::Version() to verify if client requires the same version of ToverlaySupportInfo. Client retrieves the overlay support per camera mode by passing the desired camera mode through ToverlaySupportInfo::iDesiredCameraMode.

   • In viewfinder mode, client also passes the viewfinder handle ToverlaySupportInfo::iViewFinderHandle, for which the overlay support information is required.

   • If client specifies ToverlaySupportInfo:: iDesiredCameraMode as CCamera::CCameraOverlay::EmodeNone and ToverlaySupportInfo:: iViewFinderHandle as KECamOverlayNoSpecificViewFinderHandle, ECAM implementation provides the overlay support information applicable to every camera mode.

4. Create an image overlay object using CCamera::CCameraOverlay::CreateOverlayL() method. After successful creation of overlay object on the ECam implementation, client receives a specific overlay handle as return value of CCamera::CCameraOverlay::CreateOverlayL(). Client also passes the parameters representing the overlay and the image to be used as an overlay.

Working with Overlays

You can do the following tasks when working with overlays.

1. Make sure that you create an overlay object using CCamera::CCameraOverlay::CreateOverlayL() method. Multiple overlays may be created by the client. The specific overlay handle represents a particular overlay.

2. Get the overlay image data for a specified overlay using CCamera::CCameraOverlay::GetOverlayBitmapL() method. ECam implementation transfers the ownership of the overlay image to the client.

3. Get the overlay image parameters for a specified overlay using CCamera::CCameraOverlay::GetOverlayParametersL() method.

   • ECam implementation uses ToverlayParameters object passed by the client to provide the relevant information. If overlay type specified by ToverlayParameters::iCurrentTypes is CCamera::CCameraOverlay::ToverlayType::EperPixel, alpha value given by ToverlayParameters::iAlphaValue will not be used.

   • ToverlayParameters:: iViewFinderHandle provides the handle for the viewfinder on which the overlay is supposed to be applied.

   • Only one viewfinder handle can be passed. If KECamOverlayNoSpecificViewFinderHandle is provided by the implementation, then the overlay is supposed to be applied for every viewfinder handle of type as given by iCurrentModes. If KECamOverlayInvalidViewFinderHandle is provided, then TOverlayParameters::iCurrentModes will not be omitted and overlay will be applied for every viewfinder along with other camera modes.

4. Set overlay image data usingCCamera::CCameraOverlay::SetOverlayBitmapL() method, if it was not specified when the overlay was created using CreateOverlayL() method. This changes the overlay image data for a specified overlay.

5. When this method is called, overlay size should not be changed for a given overlay. Hence, the client should not call SetOverlayParametersL() after this method, since the new parameters might not be compatible with the overlay image set.

6. Set the new parameters for the specific overlay using CCamera::CCameraOverlay::SetOverlayParametersL() method.

   This might exit with an error if SetOverlayBitmapL() API is called before this method.

7. Set the overlay image data using CCamera::CCameraOverlay::SetModifiableOverlayBitmapL() method, if it was not specified byCreateOverlayL() during overlay creation.

   Ownership of the overlay image is passed to the ECam implementation. See also step 5 above.

8. Use the overloaded CCamera::CCameraOverlay::GetAllOverlaysInZOrderL (CCamera::CCameraOverlay::TOverlayCameraMode aOverlayCameraMode, TInt aViewFinderHandle, RArray<TUint>& aOverlayHandles) method to get all mode-specific overlays in z-order from the ECam implementation server.

9. Implementation gives preference to the sequence in which the client has passed the overlay handles, if any mis-match occurs with the z-order of each such overlay. Implementation can improve the z-order of the overlays if required, to remove any ambiguity.

10. Use the overloaded CCamera::CCameraOverlay::SetAllOverlaysInZOrderL(CCamera::CCameraOverlay::TOverlayCameraMode aOverlayCameraMode, TInt aViewFinderHandle, const RArray<TUint>& aOverlayHandles) method to set all mode-specific overlays in z-order from the ECam implementation server. See step 9 above.

11. Release the specific overlay from the ECam implementation server using CCamera::CCameraOverlay::ReleaseOverlay() method.

The following example code snippets illustrates the overlay implementation:

CFbsBitmap* bitmap = new (ELeave) CFbsBitmap;
CCamera::CCameraOverlay::TOverlayParameters parameters;
TUint ovrhandle =0; 
ovrhandle = ovrlay->CreateOverlayL(parameters, bitmap));
CFbsBitmap* getBitmap = new (ELeave) CFbsBitmap;
ovrlay->GetOverlayBitmapL(ovrhandle, getBitmap);

ovrlay->GetOverlayParametersL(ovrhandle, parameters);

//client changes the bitmap as desired.
ovrlay->SetOverlayBitmapL(ovrhandle, bitmap);


CFbsBitmap* modifiedBitmap = new (ELeave) CFbsBitmap; 
ovrlay->SetModifiableOverlayBitmapL(ovrhandle,modifiedBitmap);   

ovrlay->ReleaseOverlay(ovrhandle);

RArray<TUint> overlayHandles;
ovrlay->GetAllOverlaysInZOrderL(CCamera::CCameraOverlay::EModeStillImage,1,overlayHandles);
ovrlay->SetAllOverlaysInZOrderL(overlayHandles);

Miscellaneous

Overlay camera modes

You can specify the possible camera modes in which the overlay could be used using enum TOverlayCameraMode in the following way:

See also

Overview of the overlay functionality

The Overlay tutorial