Collapse all Symbian^3 Product Developer Library

RSgDrawable Class Reference

class RSgDrawable

A handle to a reference-counted graphics resource that can be drawn in different rendering pipelines, for example DirectGDI, OpenVG etc. Instances of RSgDrawable allow access to drawable resources created using other APIs without knowing the concrete type of the resource. Since drawable resources are reference-counted they are guaranteed to exist while there are open handles referencing them.

A new RSgDrawable handle does not refer to a drawable resource until a successful call to Open(). Before that point, the handle is said to be a null handle. Instances of RSgDrawable can be shared among threads in the same process.

An RSgDrawable handle is said to be invalid if it is not null but it does not reference an existing drawable resource. Copying an instance of RSgDrawable must be done with extreme care, since it does not increment the reference count of the referenced drawable resource and may therefore allow some RSgDrawable handle to become invalid when the drawable resource is destroyed.

Public Member Functions
	RSgDrawable()
IMPORT_C void	Close()
IMPORT_C TUid	DrawableType()
TInt	GetInterface(M *&)
TInt	GetInterface(const M *&)
TUid	HandleType()
IMPORT_C const TSgDrawableId &	Id()
IMPORT_C TBool	IsNull()
IMPORT_C TInt	Open(const TSgDrawableId &)
IMPORT_C TInt	Open(const TSgDrawableId &, TUint32)

Private Member Functions
IMPORT_C TInt	GetInterface(TUid, TAny *&)

Protected Attributes
TUid	iHandleType
MSgDrawableAdapter *	iImpl

Constructor & Destructor Documentation

RSgDrawable()

IMPORT_C

RSgDrawable

(

)

Default constructor.

Pre-condition: None.

Post-condition: This RSgDrawable handle is null.

Member Functions Documentation

Close()

IMPORT_C void

(

)

Closes a handle to a drawable resource. If there are no remaining handles to the drawable resource, then it can be destroyed by the Graphics Resource driver. Calling Close() on a null handle is allowed but has no effect.

Pre-condition: If this RSgDrawable handle is not null then the Graphics Resource driver is initialised for use in the context of the calling process.; This RSgDrawable handle is valid.

Post-condition: This RSgDrawable handle is null. The reference count for the previously referenced drawable resource, if any, is decremented by one.

panic: SGRES 2 in debug builds if this RSgDrawable handle is invalid.

panic: SGRES 5 in debug builds if this RSgDrawable handle is not null and the Graphics Resource driver is not initialised for use in the context of the calling process.

DrawableType()

IMPORT_C TUid

DrawableType

(

)

const

Retrieves the run-time type of a drawable resource as a globally unique identifier.

Pre-condition: The Graphics Resource driver is initialised for use in the context of the calling process.; This RSgDrawable handle is valid.

Post-condition: None.

panic: SGRES 2 in debug builds if this RSgDrawable handle is invalid.

panic: SGRES 5 in debug builds if the Graphics Resource driver is not initialised for use in the context of the calling process.

RSgDrawable::HandleType()

GetInterface(M *&)

TInt

GetInterface

(

M *&

aInterfacePtr

)

[inline]

Makes an extension interface available on a drawable resource. The extension interface is specified by type. The following example demonstrates how to use this function to get access to an extension interface.

	MExampleExtensionInterface* interface;
	if (drawable.GetInterface(interface) == KErrNone)
		{

Pre-condition: The Graphics Resource driver is initialised for use in the context of the calling process.; This RSgDrawable handle is valid and not null.; The specified interface is supported on the drawable resource.

Post-condition: The specified interface is available until this RSgDrawable handle is closed.

panic: SGRES 2 in debug builds if this RSgDrawable handle is invalid.

panic: SGRES 5 in debug builds if the Graphics Resource driver is not initialised for use in the context of the calling process.

RSgDrawable::GetInterface<M>(const M*&) constWARNING: Function for internal use ONLY. Compatibility is not guaranteed in future releases.

Parameters

M *& aInterfacePtr

On return, a pointer to the specified interface.

GetInterface(const M *&)

TInt

GetInterface

(

const M *&

aInterfacePtr

)

const [inline]

Makes an extension interface available on a drawable resource. The extension interface is specified by type and returned const-qualified. The following example demonstrates how to use this function to get access to an extension interface.

	const MExampleExtensionInterface* interface;
	if (drawable.GetInterface(interface) == KErrNone)
		{

Pre-condition: The Graphics Resource driver is initialised for use in the context of the calling process.; This RSgDrawable handle is valid and not null.; The specified interface is supported on the drawable resource.

Post-condition: The specified interface is available until this RSgDrawable handle is closed.

panic: SGRES 2 in debug builds if this RSgDrawable handle is invalid.

panic: SGRES 5 in debug builds if the Graphics Resource driver is not initialised for use in the context of the calling process.

RSgDrawable::GetInterface<M>(M*&)WARNING: Function for internal use ONLY. Compatibility is not guaranteed in future releases.

Parameters

const M *& aInterfacePtr

On return, a pointer to the specified interface.

GetInterface(TUid, TAny *&)

IMPORT_C TInt	GetInterface	(	TUid	aInterfaceUid,
			TAny *&	aInterfacePtr
		)	const [private]

Makes an extension interface available on a drawable resource. The extension interface is specified by globally unique identifier.

Pre-condition: The Graphics Resource driver is initialised for use in the context of the calling process.; This RSgDrawable handle is valid and not null.; The specified interface is supported on the drawable resource.

Post-condition: The specified interface is available until this RSgDrawable handle is closed.

panic: SGRES 2 in debug builds if this RSgDrawable handle is invalid.

panic: SGRES 5 in debug builds if the Graphics Resource driver is not initialised for use in the context of the calling process.

RSgDrawable::GetInterface<M>(M*&) RSgDrawable::GetInterface<M>(const M*&) const

Parameters

TUid aInterfaceUid	Globally unique identifier of the interface to be made available.
TAny *& aInterfacePtr	On return, a pointer to the specified interface.

HandleType()

TUid

HandleType

(

)

const [inline]

Retrieves the type of a handle derived from RSgDrawable as a globally unique identifier. The type is set by the constructor of the handle and does not depend on the run-time type of the referenced drawable resource.

Pre-condition: None.

Post-condition: None.

RSgDrawable::DrawableType()

Id()

IMPORT_C const TSgDrawableId &

(

)

const

Retrieves the unique identifier of a drawable resource. The unique identifier can be used to share the drawable resource with another process.

Pre-condition: The Graphics Resource driver is initialised for use in the context of the calling process.; This RSgDrawable handle is valid.

Post-condition: None.

panic: SGRES 2 in debug builds if this RSgDrawable handle is invalid.

panic: SGRES 5 in debug builds if the Graphics Resource driver is not initialised for use in the context of the calling process.

IsNull()

IMPORT_C TBool

IsNull

(

)

const

Tests whether this RSgDrawable handle is null.

Pre-condition: None.

Post-condition: None.

Open(const TSgDrawableId &)

IMPORT_C TInt

Open

(

const TSgDrawableId &

aId

)

Opens a new handle to a drawable resource.

Pre-condition: The Graphics Resource driver is initialised for use in the context of the calling process.; This RSgDrawable handle is null.; aId identifies an existing drawable resource.

Post-condition: This RSgDrawable handle references the drawable resource specified by its unique identifier. The reference count for the drawable resource is incremented by one.

panic: SGRES 5 in debug builds if the Graphics Resource driver is not initialised for use in the context of the calling process.

Parameters

const TSgDrawableId & aId

The unique identifier of the drawable resource.

Open(const TSgDrawableId &, TUint32)

IMPORT_C TInt	Open	(	const TSgDrawableId &	aId,
			TUint32	aMode
		)

Opens a new handle to a drawable resource. This overload of Open() is intended for the adaptation layer of renderers to be able to request special options when opening a drawable resource.

Pre-condition: The Graphics Resource driver is initialised for use in the context of the calling process.; This RSgDrawable handle is null.; aId identifies an existing drawable resource.; All of the requested opening options in aMode are supported.

Post-condition: This RSgDrawable handle references the drawable resource specified by its unique identifier. The reference count for the drawable resource is incremented by one.

panic: SGRES 5 in debug builds if the Graphics Resource driver is not initialised for use in the context of the calling process.

TSgDrawableOpenModes

Parameters

const TSgDrawableId & aId	The unique identifier of the drawable resource.
TUint32 aMode	Flags controlling how the drawable resource is opened. The bits of this argument are defined by the enumeration TSgDrawableOpenModes.

Member Data Documentation

TUid iHandleType

TUid

iHandleType

[protected]

MSgDrawableAdapter * iImpl

MSgDrawableAdapter *

iImpl

[protected]