Symbian^3 Application 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 Close ( )

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*&) const WARNING: 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 & Id ( ) 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]

Copyright ©2010 Nokia Corporation and/or its subsidiary(-ies).
All rights reserved. Unless otherwise stated, these materials are provided under the terms of the Eclipse Public License v1.0.