Collapse all Symbian^3 Application Developer Library

RSurfaceManagerDriver Class Reference

class RSurfaceManagerDriver : public RBusLogicalChannel

RSurface Manager driver. This is a simple user side interface class derived from RBusLogicalChannel with each surface manager function implemented with a call to DoControl

Inherits from

RSurfaceManagerDriver
- RBusLogicalChannel
  - RHandleBase

Nested Classes and Structures

Public Member Functions
TInt	AddSurfaceHint (const TSurfaceId &, const RSurfaceManager::THintPair &)
TInt	CloseSurface (const TSurfaceId &)
TInt	CreateSurface (const RSurfaceManager::TSurfaceCreationAttributesBuf &, TSurfaceId &)
TInt	CreateSurface (const RSurfaceManager::TSurfaceCreationAttributesBuf &, TSurfaceId &, const RChunk &)
TInt	GetBufferOffset (const TSurfaceId &, TInt , TInt &)
TInt	GetSurfaceHint (const TSurfaceId &, RSurfaceManager::THintPair &)
TInt	GetSurfaceManagerAttrib ( RSurfaceManager::TSurfaceManagerAttrib , TInt &)
TInt	MapSurface (const TSurfaceId &, RChunk &)
const TDesC &	Name ()
TInt	Open ()
TInt	OpenSurface (const TSurfaceId &)
TInt	SetSurfaceHint (const TSurfaceId &, const RSurfaceManager::THintPair &)
TInt	SurfaceInfo (const TSurfaceId &, RSurfaceManager::TInfoBuf &)
TInt	SynchronizeCache (const TSurfaceId &, TInt , RSurfaceManager::TSyncOperation )
TVersion	VersionRequired ()

Inherited Functions
	RBusLogicalChannel::DoCancel(TUint)
	RBusLogicalChannel::DoControl(TInt)
	RBusLogicalChannel::DoControl(TInt,TAny *)
	RBusLogicalChannel::DoControl(TInt,TAny ,TAny )
	RBusLogicalChannel::DoCreate(const TDesC &,const TVersion &,TInt,const TDesC ,const TDesC8 ,TOwnerType,TBool)
	RBusLogicalChannel::DoRequest(TInt,TRequestStatus &)
	RBusLogicalChannel::DoRequest(TInt,TRequestStatus &,TAny *)
	RBusLogicalChannel::DoRequest(TInt,TRequestStatus &,TAny ,TAny )
	RBusLogicalChannel::DoSvControl(TInt)
	RBusLogicalChannel::DoSvControl(TInt,TAny *)
	RBusLogicalChannel::DoSvControl(TInt,TAny ,TAny )
	RBusLogicalChannel::Open(RMessagePtr2,TInt,TOwnerType)
	RBusLogicalChannel::Open(TInt,TOwnerType)
	RHandleBase::Attributes()const
	RHandleBase::BTraceId()const
	RHandleBase::Close()
	RHandleBase::DoExtendedClose()
	RHandleBase::Duplicate(const RThread &,TOwnerType)
	RHandleBase::FullName()const
	RHandleBase::FullName(TDes &)const
	RHandleBase::Handle()const
	RHandleBase::HandleInfo(THandleInfo *)
	RHandleBase::Name()const
	RHandleBase::NotifyDestruction(TRequestStatus &)
	RHandleBase::Open(const TFindHandleBase &,TOwnerType)
	RHandleBase::OpenByName(const TDesC &,TOwnerType,TInt)
	RHandleBase::RHandleBase()
	RHandleBase::RHandleBase(TInt)
	RHandleBase::SetHandle(TInt)
	RHandleBase::SetHandleNC(TInt)
	RHandleBase::SetReturnedHandle(TInt)
	RHandleBase::SetReturnedHandle(TInt,RHandleBase &)

Private Member Enumerations
enum	TSurfaceManagerControl { EControlCreateSurface , EControlOpenSurface , EControlCloseSurface , EControlAccessSurfaceData , EControlSurfaceInfo , EControlCreateSurfaceEx , EControlSynchronizeCache , EControlGetSurfaceHint , EControlSetSurfaceHint , EControlAddSurfaceHint , EControlGetBufferOffset , EControlGetSurfaceManagerAttrib }

Inherited Enumerations
	RHandleBase:TAttributes

Inherited Attributes
	RHandleBase::iHandle

Member Functions Documentation

AddSurfaceHint(const TSurfaceId &, const RSurfaceManager::THintPair &)

TInt	AddSurfaceHint	(	const TSurfaceId &	aSurface,
			const RSurfaceManager::THintPair &	aHint
		)	[inline]

Adds a new surface hint to the surface. This function will fail if the surface already has its maximum number of hints or if the hint key is a duplicate or invalid. Parameters:

Pre-condition: The surface is open in the calling process.; Atleast one free space to add a hint pair.; The new hint key should be unique.

Post-condition: New hint pair will be added in the surface.

Parameters

const TSurfaceId & aSurface	The surface identifier originally returned when the surface was created.
const RSurfaceManager::THintPair & aHint	The value of the hint pair to add.

CloseSurface(const TSurfaceId &)

TInt

CloseSurface

(

const TSurfaceId &

aSurfaceId

)

[inline]

Closes the surface. Decrements the reference count for the surface for the calling process. If the surface has other owners, it will not be deleted from memory. If this is the last process to close the surface, the surface will be deleted and the surface ID will become invalid.

Pre-condition: The surface is open.

Post-condition: The surface is closed.

Parameters

const TSurfaceId & aSurfaceId

The surface identifier originally returned when the surface was created.

CreateSurface(const RSurfaceManager::TSurfaceCreationAttributesBuf &, TSurfaceId &)

TInt	CreateSurface	(	const RSurfaceManager::TSurfaceCreationAttributesBuf &	aReqs,
			TSurfaceId &	aSurfaceId
		)	[inline]

Creates a surface and allocates the memory for the surface. It does not map the surface memory into this process. Sets the surface ID, aSurfaceId, to a globally unique identifier for the surface. The most significant byte of the 4th TUint in the TSurfaceId will be set to a value to identify the surface type. The surface will be open with a reference count of 1 in this process after a successful call to CreateSurface.

The creation attributes are validated as follows: The alignment is 1,2,4, 8,16,32,64 or TPageAlignment::EPageAligned. The offset to first buffer is correctly aligned. The width and height are both greater than zero. There is at least one buffer. The calculated chunk size isn't so big that it will exceed a signed int. The caching attribute is valid If the offset between the start of one buffer and the next is specified, it must be correctly aligned and at least as big as the buffer size calculated from the height and stride. A surface hint key of zero is allowed when creating a surface, it is ignored

If offset to first buffer or offset between buffers is not aligned properly, then surface manager will do the alignment, based on surface is CPU cached or not.

If surface is CPU cached it will be aligned with minimum of the specified alignment 32(for alignment 1, 2, 4, 8, 16, 32) or 64.
If surface is not CPU cached it will be aligned based on creation attribute's alignment. For page alignment it will be rounded to page size.

Pre-condition: The device driver is loaded and a channel to it has been opened.

Post-condition: The surface is created and opened in the creating process.

Parameters

const RSurfaceManager::TSurfaceCreationAttributesBuf & aReqs	Input parameter, specifies attributes of the surface required.
TSurfaceId & aSurfaceId	Output parameter, the surface ID, set if the call succeeds.

CreateSurface(const RSurfaceManager::TSurfaceCreationAttributesBuf &, TSurfaceId &, const RChunk &)

TInt	CreateSurface	(	const RSurfaceManager::TSurfaceCreationAttributesBuf &	aReqs,
			TSurfaceId &	aSurfaceId,
			const RChunk &	aChunkHandle
		)	[inline]

Creates a surface in the shared chunk memory specified by the user. Sets a new surface ID aSurfaceId to a globally unique identifier for the surface. The most significant byte of the 4th TUint in the TSurfaceId will be set to a value to identify the surface type. The surface will be open with a reference count of 1 in this process after a successful call to CreateSurface. The creation attributes are validated as follows: The alignment is 1,2,4, 8,16,32,64 or page alignment. The offset to first buffer is correctly aligned. The width and height are both greater than zero. There is at least one buffer. The chunk should be a valid shared chunk of the necessary size. If the offset between the start of one buffer and the next is specified, it must be correctly aligned and at least as big as the buffer size calculated from the height and stride. A surface hint key of zero is allowed when creating a surface, it is ignored

The offset can be 0 and that means the surface manager will calculate the offset The TSurfaceCreationAttributes members iContiguous and iCacheAttribute will not be used for already existing chunks Also, note that surface manager will not do any rounding for offset to first buffer and offset between buffer. Surface manager will expect exact aligned values for this buffer attributes, otherwise surface creation will fail.

Preconditions:

Pre-condition: The device driver is loaded and a channel has been opened. A valid shared chunk should be created and big enough for the requested size. The shared chunk type should be Shared Kernel multiple and should be right the size, ie., the size should be calculated as Offset to first buffer + (the number of buffers * ((stride * height * pixel depth in bytes) rounded up to the specified alignment) all rounded to a page size

Post-condition: The surface manager opens the chunk.

Parameters

const RSurfaceManager::TSurfaceCreationAttributesBuf & aReqs	Input parameter, specifies attributes of the surface required.
TSurfaceId & aSurfaceId	Output parameter, the surface ID, set if the call succeeds.
const RChunk & aChunkHandle	Handle of the existing shared chunk.

GetBufferOffset(const TSurfaceId &, TInt, TInt &)

TInt	GetBufferOffset	(	const TSurfaceId &	aSurfaceId,
			TInt	aBuffer,
			TInt &	aOffset
		)	[inline]

Get the offset of the specified buffer from the base address of the underlying chunk.

To obtain the address of the buffer, the offset returned must be added onto the base address of the RChunk returned in a call to MapSurface() . Note that buffer offsets are immutable during the lifetime of the surface.

Pre-condition: The surface is open in the calling process.

Parameters

const TSurfaceId & aSurfaceId	The surface identifier originally returned when the surface was created.
TInt aBuffer	The buffer for which the offset is requested. Indexed from 0.
TInt & aOffset	Output parameter set to the offset within the chunk.

GetSurfaceHint(const TSurfaceId &, RSurfaceManager::THintPair &)

TInt	GetSurfaceHint	(	const TSurfaceId &	aSurfaceId,
			RSurfaceManager::THintPair &	aHint
		)	[inline]

Get the surface hint value for the given surface ID and hint pair key.

Pre-condition: The surface is open in the calling process.; Hint key should be a key for a hint set for this surface.

Post-condition: The hint value will be updated in the hint pair.

Parameters

const TSurfaceId & aSurfaceId	The surface identifier originally returned when the surface was created.
RSurfaceManager::THintPair & aHint	The hint value for the requested hint pair key.

GetSurfaceManagerAttrib(RSurfaceManager::TSurfaceManagerAttrib, TInt &)

TInt	GetSurfaceManagerAttrib	(	RSurfaceManager::TSurfaceManagerAttrib	aAttrib,
			TInt &	aValue
		)	[inline]

Parameters

RSurfaceManager::TSurfaceManagerAttrib aAttrib
TInt & aValue

MapSurface(const TSurfaceId &, RChunk &)

TInt	MapSurface	(	const TSurfaceId &	aSurfaceId,
			RChunk &	aHandle
		)	[inline]

Maps the surface into the current client process address space. The actual memory will remain mapped into the calling process for as long as the RChunk handle aHandle is open. The RChunk handle is owned by the calling thread, so will need to be duplicated if passed to other threads in the process.

Pre-condition: The surface is open.

Post-condition: The surface memory will be mapped into the calling porcesses address space.

RChunk RHandleBase::Duplicate

Parameters

const TSurfaceId & aSurfaceId	The surface identifier originally returned when the surface was created.
RChunk & aHandle	Output parameter, handle to the implementation specific Shared Chunk.

Name()

const TDesC &

Name

(

)

[static, inline]

The driver's name

Open()

TInt

Open

(

)

[inline]

Opens a channel to the surface manager logical device driver.

Pre-condition: The logical device driver has been loaded

User::LoadLogicalDevice

OpenSurface(const TSurfaceId &)

TInt

OpenSurface

(

const TSurfaceId &

aSurfaceId

)

[inline]

Opens a surface. If the surface is already open in this process, this call increments the reference count for the surface for this process. If the surface hasn't been opened in this process, it opens the surface in this process and sets the reference count to 1 for this process. A surface will be deleted when all its reference counts are 0.

Pre-condition: The surface id is for an existing surface.

Post-condition: The surface is open in this process.

Parameters

const TSurfaceId & aSurfaceId

The surface id originally returned when the surface was created.

SetSurfaceHint(const TSurfaceId &, const RSurfaceManager::THintPair &)

TInt	SetSurfaceHint	(	const TSurfaceId &	aSurfaceId,
			const RSurfaceManager::THintPair &	aHint
		)	[inline]

Set the surface hint value for the surface Id. Parameters:

Pre-condition: The surface is open in the calling process.; The Hint key should be a key for a hint set for this surface.; Only mutable hints can be updated.

Post-condition: The hint value will be updated in the surface hint pair.

Parameters

const TSurfaceId & aSurfaceId	The surface identifier originally returned when the surface was created.
const RSurfaceManager::THintPair & aHint	The value of the hint pair to set.

SurfaceInfo(const TSurfaceId &, RSurfaceManager::TInfoBuf &)

TInt	SurfaceInfo	(	const TSurfaceId &	aSurfaceId,
			RSurfaceManager::TInfoBuf &	aInfo
		)	[inline]

Returns information about a particular surface identified by its surface ID.

Pre-condition: The surface is open in the calling process.

Parameters

const TSurfaceId & aSurfaceId	The surface identifier originally returned when the surface was created.
RSurfaceManager::TInfoBuf & aInfo	TInfoBuf to receive the information about the surface.

SynchronizeCache(const TSurfaceId &, TInt, RSurfaceManager::TSyncOperation)

TInt	SynchronizeCache	(	const TSurfaceId &	aSurfaceId,
			TInt	aBuffer,
			RSurfaceManager::TSyncOperation	aOperation
		)	[inline]

This function ensures the memory is updated consistently before and/or after triggering non CPU hardware access. Also ensures the CPU cache and the physical memory are in a consistent state before and after non CPU hardware or DMA access to the physical memory.

Pre-condition: The surface is open in the calling process.

Post-condition: The surface buffer memory will be synchronized properly with cache contents.

Parameters

const TSurfaceId & aSurfaceId	The surface identifier originally returned when the surface was created.
TInt aBuffer	The buffer number indexed from 0 within the surface whose memory region is to be flushed.
RSurfaceManager::TSyncOperation aOperation	Specifies the sync operation as before non CPU hardware reads or before non CPU hardware writes or after non CPU hardware writes between physical memory of the surface and the cache contents.

VersionRequired()

TVersion

VersionRequired

(

)

[static, inline]

The driver's version

Member Enumerations Documentation

Enum TSurfaceManagerControl

Enumerators

EControlCreateSurface
EControlOpenSurface
EControlCloseSurface
EControlAccessSurfaceData
EControlSurfaceInfo
EControlCreateSurfaceEx
EControlSynchronizeCache
EControlGetSurfaceHint
EControlSetSurfaceHint
EControlAddSurfaceHint
EControlGetBufferOffset
EControlGetSurfaceManagerAttrib