Collapse all Symbian^3 Product Developer Library

CDirectGdiDriver Class Reference

class CDirectGdiDriver : public CBase

Provides an interface which is intended to be used by DirectGDI client applications. It will be implemented using the handle/body idiom, where the handle part will form the public and private API that is intended to be used by DirectGDI client applications and other DirectGDI generic parts, and the body part defines the HAI that needs to be implemented by an adaptation. The implementation of the handle part will be generic for all adaptations. The implementation of the body part is adaptation specific and provides interfaces for initialisation, termination, construction of the concrete drawing engine and the creation of source or target rendering. Initialisation and termination are intended to give opportunities for an adaptation to perform any thread specific tasks which may be required. This class is intended to be a singleton within a thread. It delegates to an adaptation-specific implementation that provides a platform-specific mechanism.

Inherits from

CDirectGdiDriver
- CBase

Public Member Functions
IMPORT_C void	Close()
IMPORT_C void	Finish()
IMPORT_C void	Flush()
IMPORT_C TInt	GetError()
IMPORT_C TInt	GetInterface(TUid, TAny *&)
IMPORT_C TInt	Open()
IMPORT_C CDirectGdiDriver *	Static()

Private Member Functions
	CDirectGdiDriver()
	~CDirectGdiDriver()
void	CloseDrawableSource(RDirectGdiDrawableSource &)
void	CloseImageTarget(RDirectGdiImageTarget &)
TInt	CreateDrawableSource(RDirectGdiDrawableSource &, const RSgDrawable &)
TInt	CreateEngine(MDirectGdiEngine *&)
TInt	CreateImageTarget(RDirectGdiImageTarget &, const RSgImage &)
TInt	CreateInternalDriver()
void	DestroyEngine(MDirectGdiEngine *)
IMPORT_C void	SetError(TInt)

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()

Private Attributes
CDirectGdiDriverInternal *	iDriverInternal
TInt	iOpenCount

Constructor & Destructor Documentation

CDirectGdiDriver()

CDirectGdiDriver

(

)

[private]

CDirectGdiDriver private constructor as this class is singleton.

Pre-condition: None.

Post-condition: Initialises the member reference counter to zero.

~CDirectGdiDriver()

~CDirectGdiDriver

(

)

[private]

CDirectGdiDriver default destructor.

Pre-condition: None.

Post-condition: None.

panic: DGDI 15, if the resource count is not zero.

Member Functions Documentation

Close()

IMPORT_C void

(

)

Performs adaptation termination which is needed to release any internal resources allocated by the calling thread. It will also perform an implicit Finish() by submitting all outstanding requests from the calling thread. A DirectGDI client's thread that uses the new DirectGDI interfaces must call this method at the end of its lifetime.

CDirectGdiDriver::Open()

Pre-condition: The driver is open from a call to Open().

Post-condition: The object open count is decremented. If the open count reaches zero, any adaptation resources allocated to the calling thread must be released, and the CDirectGdiDriver object for the calling thread is destroyed.

panic: DGDI 14, if Close() is called on a CDirectGdiDriver object that is not open.

CloseDrawableSource(RDirectGdiDrawableSource &)

void

CloseDrawableSource

(

RDirectGdiDrawableSource &

aRDirectGdiDrawableSource

)

[private]

Delegates call to the CDirectGdiDriverInternal object, which destroys the DirectGDI adaptation-specific resource associated with this handle. Calling this method on a handle that is not associated with any DirectGDI adaptation specific resource will do nothing. Once Close() is called, this handle can be reused.

CreateDrawableSource()

Pre-condition: CDirectGdiDriver object has been initialised from the calling thread.

Post-condition: The DirectGDI specific resource associated with this handle will be destroyed (at any time preferred by the adaptation). This handle is no longer associated with a DirectGDI specific resource. The reference counter of the underlying non-image resource is decremented.

Parameters

RDirectGdiDrawableSource & aRDirectGdiDrawableSource

The RDirectGdiDrawableSource object.

CloseImageTarget(RDirectGdiImageTarget &)

void

CloseImageTarget

(

RDirectGdiImageTarget &

aRDirectGdiImageTarget

)

[private]

Delegates call to the CDirectGdiDriverInternal object, which destroys the DirectGDI adaptation specific resource associated with this handle. Calling this method on a handle that is not associated with any DirectGDI adaptation specific resource will do nothing. Once Close() is called, this handle can be reused.

CreateImageTarget()

Pre-condition: CDirectGdiDriver object has been initialised from the calling thread.

Post-condition: The DirectGDI specific resource associated with this handle will be destroyed (at any time preferred by the adaptation). This handle is no longer associated with a DirectGDI specific resource. The reference counter of the underlying image resource is decremented.

Parameters

RDirectGdiImageTarget & aRDirectGdiImageTarget

The RDirectGdiImageTarget object.

CreateDrawableSource(RDirectGdiDrawableSource &, const RSgDrawable &)

TInt	CreateDrawableSource	(	RDirectGdiDrawableSource &	aRDirectGdiDrawableSource,
			const RSgDrawable &	aRSgDrawable
		)	[private]

Delegates the call to the CDirectGdiDriverInternal object, which creates a DirectGDI adaptation-specific resource from the given drawable resource so it can be drawn using the DirectGDI rendering API.

CloseDrawableSource()

Pre-condition: CDirectGdiDriver object has been initialised from the calling thread.

Post-condition: The DirectGDI adaptation-specific resource that is bound to the given drawable resource is created and this handle is now associated with it. The reference counter on the drawable resource is incremented. The CDirectGdiDriver for this thread is now aware of and owns the adaptation specific resource.

panic: DGDI 19, if this handle is already associated with a DirectGDI adaptation-specific drawable resource.

panic: DGDI 20, if the drawable resource is not valid.

Parameters

RDirectGdiDrawableSource & aRDirectGdiDrawableSource	The RDirectGdiDrawableSource object to be created
const RSgDrawable & aRSgDrawable	The RSgDrawable object to use when creating aRDirectGdiDrawableSource

CreateEngine(MDirectGdiEngine *&)

TInt

CreateEngine

(

MDirectGdiEngine *&

aMDirectGdiEngine

)

[private]

Delegates call to the CDirectGdiDriverInternal object, which creates a MDirectGdiEngine object.

Pre-condition: CDirectGdiDriver object has been initialised from the calling thread.

Post-condition: None.

Parameters

MDirectGdiEngine *& aMDirectGdiEngine

The MDirectGdiEngine object.

CreateImageTarget(RDirectGdiImageTarget &, const RSgImage &)

TInt	CreateImageTarget	(	RDirectGdiImageTarget &	aRDirectGdiImageTarget,
			const RSgImage &	aRSgImage
		)	[private]

Delegates call to the CDirectGdiDriverInternal object, which creates a DirectGDI adaptation-specific resource from the given image resource so it can be used as a target of DirectGDI rendering.

CloseImageTarget()

Pre-condition: CDirectGdiDriver object has been initialised from the calling thread. The image resource has been fully constructed and created with the correct usage that allows it to be used as a DirectGDI target.

Post-condition: The DirectGDI adaptation-specific resource that is bound to the given image resource is created and this handle is now associated with it. The reference counter on the image resource is incremented.

panic: DGDI 17, if this handle is already associated with a DirectGDI adaptation-specific resource.

panic: DGDI 21, if the image resource is not valid.

Parameters

RDirectGdiImageTarget & aRDirectGdiImageTarget	The RDirectGdiImageTarget object.
const RSgImage & aRSgImage	The RSgImage object.

CreateInternalDriver()

TInt

CreateInternalDriver

(

)

[private]

Create the adaptation/internal object for this driver.

Pre-condition: The adaptation/internal driver object has not been created yet.

Post-condition: The adaptation/internal object has been created.

DestroyEngine(MDirectGdiEngine *)

void

DestroyEngine

(

MDirectGdiEngine *

aMDirectGdiEngine

)

[private]

Delegates call to the CDirectGdiDriverInternal object, which destroys a MDirectGdiEngine object.

Pre-condition: CDirectGdiDriver object has been initialised from the calling thread.

Post-condition: None.

Parameters

MDirectGdiEngine * aMDirectGdiEngine

The MDirectGdiEngine object.

Finish()

IMPORT_C void

Finish

(

)

Ensures all outstanding rendering requests from the calling thread are submitted and processed. This method will wait until all the outstanding rendering requests have been completely processed.

CDirectGdiDriver::Flush()

Pre-condition: CDirectGdiDriver object has been initialised for the calling thread.

Post-condition: All outstanding requests have been completely processed.

Flush()

IMPORT_C void

Flush

(

)

Ensures all outstanding requests on the calling thread are submitted for processing. The method immediately returns and does not wait until all outstanding requests are completely processed. Clients can continue issuing rendering requests after calling this method.

CDirectGdiDriver::Finish()

Pre-condition: CDirectGdiDriver object has been initialised for the calling thread.

Post-condition: All outstanding requests have been submitted for processing.

GetError()

IMPORT_C TInt

GetError

(

)

Returns the first error code (as the result of calling any DirectGDI API), if any, since the last call to this function or, if it has not previously been called, since the CDirectGdiDriver was initialised. Calling this function clears the error code.

CDirectGdiDriver::SetError(TInt)

Pre-condition: CDirectGdiDriver object has been initialised for the calling thread.

Post-condition: The error code has been reset after being read.

GetInterface(TUid, TAny *&)

IMPORT_C TInt	GetInterface	(	TUid	aInterfaceId,
			TAny *&	aInterface
		)

Retrieves a pointer to an instance of the requested extension interface implementation, if provided.

Pre-condition: CDirectGdiDriver object has been initialised for the calling thread.

Parameters

TUid aInterfaceId	The globally unique identifier of the requested interface.
TAny *& aInterface	On return, holds the specified interface, or NULL if the interface cannot be found.

Open()

IMPORT_C TInt

Open

(

)

[static]

Creates a new CDirectGdiDriver object if one has not already been created in this thread. Performs any adaptation initialisation that is needed to allow the calling thread to use functionality provided by the new DirectGDI interfaces. Calling this method multiple times from the same client thread has no effect after the first call, other than to increase the open count.

CDirectGdiDriver::Close()

Pre-condition: None.

Post-condition: The object reference counter is incremented. Adaptation resources for the calling thread are created and initialised. The new DirectGDI interfaces are ready to be used from the calling thread.

SetError(TInt)

IMPORT_C void

SetError

(

TInt

aErr

)

[private]

Sets the error code on the driver. If the error code is already set to a value other than KErrNone, the error code will not be modified.

CDirectGdiDriver::GetError()

Pre-condition: CDirectGdiDriver object has been initialised for the calling thread.

Post-condition: The error code has been set.

Parameters

TInt aErr

The error code to set.

Static()

IMPORT_C CDirectGdiDriver *

Static

(

)

[static]

Returns the singleton instance of CDirectGdiDriver for the calling thread.

Member Data Documentation

CDirectGdiDriverInternal * iDriverInternal

CDirectGdiDriverInternal *

iDriverInternal

[private]

To delegate calls to adaptation.

TInt iOpenCount

TInt

iOpenCount

[private]

A count of how many times this driver object has been opened.