Collapse all Symbian^3 Product Developer Library

CCamera::CCameraOverlay Class Reference

class CCamera::CCameraOverlay : public CBase

This class provides support for image overlays. The client can use it to overlay an image onto the viewfinder, snapshots, still images and video. A client can create multiple overlays, where each overlay can be in a different format. The properties of an overlay can be changed after it has been created.

Note:

This class provides a standardised client interface for the camera overlay. Classes cannot be derived from it.

If the class methods leave, the output type parameter value is not guaranteed to be valid.

Inherits from

CCamera::CCameraOverlay
- CBase

Nested Classes and Structures

Public Member Functions
	~CCameraOverlay()
IMPORT_C TUint	CreateOverlayL(const TOverlayParameters &, CFbsBitmap *)
IMPORT_C void	GetAllOverlaysInZOrderL(RArray< TUint > &)
IMPORT_C void	GetAllOverlaysInZOrderL(TOverlayCameraMode, TInt, RArray< TUint > &)
IMPORT_C void	GetOverlayBitmapL(TUint, CFbsBitmap *)
IMPORT_C void	GetOverlayParametersL(TUint, TOverlayParameters &)
IMPORT_C void	GetOverlaySupport(TOverlaySupportInfo &)
IMPORT_C CCameraOverlay *	NewL(CCamera &)
IMPORT_C void	ReleaseOverlay(TUint)
IMPORT_C void	SetAllOverlaysInZOrderL(const RArray< TUint > &)
IMPORT_C void	SetAllOverlaysInZOrderL(TOverlayCameraMode, TInt, const RArray< TUint > &)
IMPORT_C void	SetModifiableOverlayBitmapL(TUint, CFbsBitmap *)
IMPORT_C void	SetOverlayBitmapL(TUint, const CFbsBitmap *)
IMPORT_C void	SetOverlayParametersL(TUint, const TOverlayParameters &)

Private Member Functions
	CCameraOverlay(CCamera &)
void	ConstructL()

Inherited Functions
	CBase::CBase()
	CBase::Delete(CBase *)
	CBase::Extension_(TUint,TAny &,TAny )
	CBase::operator new(TUint)
	CBase::operator new(TUint,TAny *)
	CBase::operator new(TUint,TLeave)
	CBase::operator new(TUint,TLeave,TUint)
	CBase::operator new(TUint,TUint)
	CBase::~CBase()

Public Member Enumerations
enum	TBlendingType { EBlendNone, EBinary, EFullRange, EBinaryDynamic, EFullRangeDynamic }
enum	TOverlayCameraMode { EModeNone = 0x00, EModeStillImage = 0x01, EModeSnapshot = 0x02, EModeViewfinder = 0x04, EModeVideo = 0x08, EModeDirectViewfinder = 0x00010, EModeClientViewfinder = 0x00020, EModeStillImageContinuous = 0x00080, EModeStillImageBracket = 0x00100, EModeStillImageBracketMerge = 0x00200, EModeStillImageTimed = 0x00400, EModeStillImageTimeLapse = 0x00800, EModeStillImageBurst = 0x01000 }
enum	TOverlayType { EOverlayNone = 0x00, EPerPixel = 0x01, EPerPlane = 0x02 }

Private Attributes
MCameraOverlay *	iImpl
MCameraOverlay2 *	iImpl2
CCamera &	iOwner

Constructor & Destructor Documentation

CCameraOverlay(CCamera &)

CCameraOverlay

(

CCamera &

aOwner

)

[private]

Constructor for the CCamera::CCameraOverlay class.

Parameters

CCamera & aOwner

A reference to the camera object for which a camera overlay object is to be created.

~CCameraOverlay()

IMPORT_C

~CCameraOverlay

(

)

Destructor for the CCamera::CCameraOverlay class.

Member Functions Documentation

ConstructL()

void

ConstructL

(

)

[private]

CCameraOverlay second phase constructor.

This function used to initialise internal state of the object. It uses reference to the camera to retrieve overlay interface pointer.

leave: KErrNotSupported if this functionality is not supported; also any system wide error.

CreateOverlayL(const TOverlayParameters &, CFbsBitmap *)

IMPORT_C TUint	CreateOverlayL	(	const TOverlayParameters &	aParameters,
			CFbsBitmap *	aBitmap
		)

Creates an image overlay object on the ECam implementation, returning a handle to the newly created object.

leave: KErrNoMemory if out of memory; also any system wide error.

leave: KErrArgument if the member variables in TOverlayParameters are such that they create mutual exclusion.

Parameters

const TOverlayParameters & aParameters	The parameters characterizing the overlay to be created.
CFbsBitmap * aBitmap	The image that is to become the overlay. By default this is set to NULL, allowing the client to provide the image at some point after the overlay object has been created, by using SetOverlayBitmapL().

GetAllOverlaysInZOrderL(RArray< TUint > &)

IMPORT_C void

GetAllOverlaysInZOrderL

(

RArray< TUint > &

aOverlayHandles

)

Gets all the overlay handles maintained by the ECam implementation, in order of their Z-Value.

leave: KErrNoMemory if out of memory; also any system wide error.

Note:

Implementation shall give preference to the sequence in which the client has passed the overlay handles in case of any mis-match with the 'z-order' of each such overlay. Implementation shall amend the 'z-order' of the overlays if required to remove any ambiguity.

Parameters

RArray< TUint > & aOverlayHandles

Returned list, in Z-Value order, of all the overlay handles maintained on the ECam implementation. The topmost overlay is the first element of the array.

GetAllOverlaysInZOrderL(TOverlayCameraMode, TInt, RArray< TUint > &)

IMPORT_C void	GetAllOverlaysInZOrderL	(	TOverlayCameraMode	aOverlayCameraMode,
			TInt	aViewFinderHandle,
			RArray< TUint > &	aOverlayHandles
		)	const

Gets all the overlay handles maintained by the ECam implementation, in order of their z-value, for a particular camera mode. If for viewfinder, then the handle number is used to get the z-value for the viewfinder whose handle number is passed.

leave: May leave with any error code.

Note:

Parameters

TOverlayCameraMode aOverlayCameraMode	The specific camera mode whose overlays' z-value information is required.
TInt aViewFinderHandle	The specific viewfinder handle, if overlays' z-value information is required for viewfinder camera mode.
RArray< TUint > & aOverlayHandles	Returned list, in z-value order, of all the overlay handles maintained on the ECam implementation. The topmost overlay is the first element of the array.

GetOverlayBitmapL(TUint, CFbsBitmap *)

IMPORT_C void	GetOverlayBitmapL	(	TUint	aOverlayHandle,
			CFbsBitmap *	aBitmap
		)

Gets the overlay image data for a specified overlay.

leave: KErrArgument if aOverlayHandle is out of range; also any system wide error.

leave: KErrNotSupported if a sharing client (which did not create the given overlay) tries to retrieve the overlay bitmap and the implementation may not be interested in providing the overlay.

Note:

The ECam implementation will transfer the ownership of the aBitmap to the client.

Parameters

TUint aOverlayHandle	The handle of the overlay whose overlay image data is to be obtained.
CFbsBitmap * aBitmap	A CFbsBitmap that will receive the returned image data for the overlay.

GetOverlayParametersL(TUint, TOverlayParameters &)

IMPORT_C void	GetOverlayParametersL	(	TUint	aOverlayHandle,
			TOverlayParameters &	aInfo
		)

Gets the parameters that characterize a given overlay.

leave: KErrArgument if aOverlayHandle is out of range; also any system wide error.

Parameters

TUint aOverlayHandle	The handle of the overlay whose parameters are required.
TOverlayParameters & aInfo	Reference to TOverlayParameters object that will contain the returned overlay parameters.

GetOverlaySupport(TOverlaySupportInfo &)

IMPORT_C void

GetOverlaySupport

(

TOverlaySupportInfo &

aInfo

)

Gets information on the overlay functionality supported by the ECam implementation.

Parameters

TOverlaySupportInfo & aInfo

A reference to a TOverlaySupportInfo object that will receive the overlay support information.

NewL(CCamera &)

IMPORT_C CCameraOverlay *

NewL

(

CCamera &

aCamera

)

[static]

Factory function that creates a new camera overlay object on the heap.

leave: KErrNoMemory if out of memory; also any system wide error.

Note:

Clients using MCameraObserver are not recommended to use this extension class since they cannot handle events.

Parameters

CCamera & aCamera

A reference to the camera object for which a camera overlay object is to be created.

ReleaseOverlay(TUint)

IMPORT_C void

ReleaseOverlay

(

TUint

aOverlayHandle

)

Releases the specified overlay handle.

Note:

If the handle specified in aOverlayHandle is invalid (out of range) the function call is ignored and no error is reported.

Parameters

TUint aOverlayHandle

The handle of the overlay that is to be released.

SetAllOverlaysInZOrderL(const RArray< TUint > &)

IMPORT_C void

SetAllOverlaysInZOrderL

(

const RArray< TUint > &

aOverlayHandles

)

Sets the Z-Order of all the overlay handles known by this CCameraOverlay object.

leave: KErrNoMemory if out of memory; also any system wide error.

Note:

Parameters

const RArray< TUint > & aOverlayHandles

The overlay handles in aOverlayHandles array. This must be the complete current set of handles known to this CCameraOverlay object. The client specifies the desired order by placing the topmost overlay in the first element of the array.

SetAllOverlaysInZOrderL(TOverlayCameraMode, TInt, const RArray< TUint > &)

IMPORT_C void	SetAllOverlaysInZOrderL	(	TOverlayCameraMode	aOverlayCameraMode,
			TInt	aViewFinderHandle,
			const RArray< TUint > &	aOverlayHandles
		)

Sets all the overlay handles maintained by the ECam implementation, in order of their z-value for a particular camera mode. If for viewfinder, then the handle number is used to set the z-value for the viewfinder whose handle number is passed.

leave: May leave with any error code.

Note:

Parameters

TOverlayCameraMode aOverlayCameraMode	The specific camera mode whose overlays' z-value is to be set.
TInt aViewFinderHandle	The specific viewfinder handle, if overlays' z-value is required to be set for viewfinder camera mode.
const RArray< TUint > & aOverlayHandles	The overlay handles in aOverlayHandles array. This must be the complete current set of handles known to this CCameraOverlay object for the given camera mode (and for the given viewfinder, if applicable). The client specifies the desired order by placing the topmost overlay in the first element of the array.

SetModifiableOverlayBitmapL(TUint, CFbsBitmap *)

IMPORT_C void	SetModifiableOverlayBitmapL	(	TUint	aOverlayHandle,
			CFbsBitmap *	aBitmap
		)

Allows the overlay image data to be changed for a specified overlay. Ownership of the bitmap is passed to the implementation. Use this function to set the overlay image data if it was not specified when the overlay was created using CreateOverlayL().

leave: May leave with any error code.

Note:

If required, implementation is free to modify the overlay bitmap passed to it.

SetOverlayParametersL should not be called after this method for the given overlay since it may change the overlay parameters considerably. In such a case, SetOverlayParametersL may leave with error KErrArgument.

Parameters

TUint aOverlayHandle	The handle of the overlay whose overlay image data is to be changed.
CFbsBitmap * aBitmap	The new image data for the overlay.

SetOverlayBitmapL(TUint, const CFbsBitmap *)

IMPORT_C void	SetOverlayBitmapL	(	TUint	aOverlayHandle,
			const CFbsBitmap *	aBitmap
		)

Allows the overlay image data to be changed for a specified overlay. Use this function to set the overlay image data if it was not specified when the overlay was created using CreateOverlayL().

leave: KErrArgument if aOverlayHandle is out of range; also any system wide error.

Note:

Once this method is called, overlay size should not be changed for the given overlay. Hence, SetOverlayParametersL should not be called after this method.

Parameters

TUint aOverlayHandle	The handle of the overlay whose overlay image data is to be changed.
const CFbsBitmap * aBitmap	The new image data for the overlay.

SetOverlayParametersL(TUint, const TOverlayParameters &)

IMPORT_C void	SetOverlayParametersL	(	TUint	aOverlayHandle,
			const TOverlayParameters &	aParameters
		)

Sets new parameters that characterize a given overlay.

leave: KErrNotSupported if TOverlayCameraMode passed in TOverlayParameters is not supported; also any system wide error.

leave: KErrArgument if the member variables in TOverlayParameters are such that they create mutual exclusion.

Parameters

TUint aOverlayHandle	The handle of the overlay whose parameters are to be changed.
const TOverlayParameters & aParameters	The new overlay parameters.

Member Enumerations Documentation

Enum TBlendingType

Blending types

Type of supported blending.

Enumerators

EBlendNone	Does not support blending.
EBinary	Supports only binary blending. If alpha value is 0xFF, it is opaque, otherwise transparent.
EFullRange	Full support for blending - all values in the range [0:255].
EBinaryDynamic	Supports only dynamic binary blending - allows values to be changed when overlay is being displayed. If alpha value is 0xFF, it is opaque, otherwise transparent. Since the blending is dynamic, SetModifiableOverlayBitmapL shall be used such that the bitmap could be changed by the implementation.
EFullRangeDynamic	Full support for dynamic blending - all values in the range [0:255] allows values to be changed when overlay is being displayed. Since the blending is dynamic, SetModifiableOverlayBitmapL shall be used such that the bitmap could be changed by the implementation.

Enum TOverlayCameraMode

Overlay camera mode types

Represents the possible camera modes in which the overlay could be used. Several types can be combined when returning ECam implementation support for various modes.

Enumerators

EModeNone = 0x00	Overlays are not supported for any camera mode.
EModeStillImage = 0x01	The image can be overlaid on captured images. The camera is in still image mode. This effectively means all the still image drive modes and its interpretation may be implementation-specific. Explicit definition of drive modes is recommended instead.
EModeSnapshot = 0x02	The image can be overlaid on a snapshot. The camera has snapshot functionality set on.
EModeViewfinder = 0x04	The image can be overlaid on a viewfinder. The camera is displaying directly to viewfinder. This mode shall not be used if any of the viewfinder submodes is specified. Note: Overlay visibility for different viewfinder modes (direct/client-based) is implementation-specific; viewfinder modes should be explicitly specified by clients instead.
EModeVideo = 0x08	The image can be overlaid on a video frame. The camera is in video mode.
EModeDirectViewfinder = 0x00010	The image is to be overlaid on direct viewfinder Note: This value is available only to the API clients using CCamera::New2L() or CCamera::NewDuplicate2L()
EModeClientViewfinder = 0x00020	The image is to be overlaid on client-based viewfinder Note: This value is available only to the API clients using CCamera::New2L() or CCamera::NewDuplicate2L()
EModeStillImageContinuous = 0x00080	The image is to be overlaid when Continuous Still Image driving mode is active. Note: This value is available only to the API clients using CCamera::New2L() or CCamera::NewDuplicate2L()
EModeStillImageBracket = 0x00100	The image is to be overlaid when Still Image Bracketing driving mode is active. Note: This value is available only to the API clients using CCamera::New2L() or CCamera::NewDuplicate2L()
EModeStillImageBracketMerge = 0x00200	The image is to be overlaid when Still Image Bracketing with Merge option driving mode is active. Note: This value is available only to the API clients using CCamera::New2L() or CCamera::NewDuplicate2L()
EModeStillImageTimed = 0x00400	The image is to be overlaid when Timed Still Image driving mode is active. Note: This value is available only to the API clients using CCamera::New2L() or CCamera::NewDuplicate2L()
EModeStillImageTimeLapse = 0x00800	The image is to be overlaid when Timed Still Image with Lapse option driving mode is active. Note: This value is available only to the API clients using CCamera::New2L() or CCamera::NewDuplicate2L()
EModeStillImageBurst = 0x01000	The image is to be overlaid when Still Image Burst driving mode is active. Note: This value is available only to the API clients using CCamera::New2L() or CCamera::NewDuplicate2L()

Enum TOverlayType

Overlay types

Type in which alpha value will be provided.

Enumerators

EOverlayNone = 0x00	Does not support overlays.
EPerPixel = 0x01	Blending is on a per pixel basis, where the alpha value information is provided in the overlay bitmap itself. The alpha value is specified in each pixel of the bitmap (it is the alpha componenet of the TRgb object). The display mode of the bitmap should be such that alpha value is supported. TOverlayParameters::iAlphaValue is neglected in this case.
EPerPlane = 0x02	Blending is on a per plane basis, where all pixels are affected by the same alpha value. The alpha value is provided through TOverlayParameters::iAlphaValue.

Member Data Documentation

MCameraOverlay * iImpl

MCameraOverlay *

iImpl

[private]

MCameraOverlay2 * iImpl2

MCameraOverlay2 *

iImpl2

[private]

CCamera & iOwner

CCamera &

iOwner

[private]