Collapse all Symbian^3 Product Developer Library

RSurfaceManager Class Reference

class RSurfaceManager

RSurface Manager User API.

Nested Classes and Structures

Public Member Functions
	RSurfaceManager()
IMPORT_C TInt	AddSurfaceHint(const TSurfaceId &, const THintPair &)
IMPORT_C void	Close()
IMPORT_C TInt	CloseSurface(const TSurfaceId &)
IMPORT_C TInt	CreateSurface(const TSurfaceCreationAttributesBuf &, TSurfaceId &)
IMPORT_C TInt	CreateSurface(const TSurfaceCreationAttributesBuf &, TSurfaceId &, const RChunk &)
IMPORT_C TInt	GetBufferOffset(const TSurfaceId &, TInt, TInt &)
IMPORT_C TInt	GetSurfaceHint(const TSurfaceId &, THintPair &)
IMPORT_C TInt	GetSurfaceManagerAttrib(TSurfaceManagerAttrib, TInt &)
IMPORT_C TInt	MapSurface(const TSurfaceId &, RChunk &)
IMPORT_C TInt	Open()
IMPORT_C TInt	OpenSurface(const TSurfaceId &)
IMPORT_C TInt	SetSurfaceHint(const TSurfaceId &, const THintPair &)
IMPORT_C TInt	SurfaceInfo(const TSurfaceId &, TInfoBuf &)
IMPORT_C TInt	SynchronizeCache(const TSurfaceId &, TInt, TSyncOperation)

Private Member Functions
RSurfaceManagerDriver &	Driver()

Public Member Enumerations
enum	TCacheAttribute { ECached = 0, ENotCached = 1 }
enum	TPageAlignment { EPageAligned = -1 }
enum	TSurfaceManagerAttrib { EMaxNumberOfHints = 0x0 }
enum	TSyncOperation { ESyncBeforeNonCPURead, ESyncBeforeNonCPUWrite, ESyncAfterNonCPUWrite }

Public Member Type Definitions
typedef	TPckgBuf< TSurfaceInfoV01 > TInfoBuf
typedef	TPckgBuf< TSurfaceCreationAttributes > TSurfaceCreationAttributesBuf

Private Attributes
TInt32	iDriverBuf

Constructor & Destructor Documentation

RSurfaceManager()

IMPORT_C

RSurfaceManager

(

)

Default constructor

Member Functions Documentation

AddSurfaceHint(const TSurfaceId &, const THintPair &)

IMPORT_C TInt	AddSurfaceHint	(	const TSurfaceId &	aSurface,
			const THintPair &	aHint
		)

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.

Pre-condition: The surface is open in the calling process.; At least one free space to add a hint pair.; The new hint key should be non zero and unique for this surface.

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 THintPair & aHint	The value of the hint pair to add.

Close()

IMPORT_C void

(

)

Closes the connection to the Surface Manager.

Cleanup is performed by the Surface Manager when a client process exits or closes its last connection. It is not guaranteed that the resources held by the Surface Manager are going to be released synchronously.

CloseSurface(const TSurfaceId &)

IMPORT_C TInt

CloseSurface

(

const TSurfaceId &

aSurfaceId

)

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. Resources associated with the surface are not guaranteed to be released synchronously.

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 TSurfaceCreationAttributesBuf &, TSurfaceId &)

IMPORT_C TInt	CreateSurface	(	const TSurfaceCreationAttributesBuf &	aReqs,
			TSurfaceId &	aSurfaceId
		)

Creates a surface and returns its global unique identifier.

Depending on the implementation, this method will allocate the surface in a new shared chunk or in external memory. Surfaces created in external memory cannot be mapped (see TSurfaceInfoV01::iMappable for more information). If the creation succeeds, the surface will be opened with a reference count of 1 in the calling process.

The Surface Manager implementation should validate at least the following:

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 (not zero), 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 Surface Manager implementation will treat iStride, iOffsetToFirstBuffer, and iOffsetBetweenBuffers as minimum values as opposed to required values. The caller of this method must not rely on the passed values as it is not guaranteed that they remain the same after surface creation (SurfaceInfo() and GetBufferOffset() should be used instead).

If iOffsetBetweenBuffers is zero, the Surface Manager implementation will layout buffer at its own discretion. Although, a buffer's offset must remain constant during the surface's lifetime.

If iMappable is EFalse the surface won't be mappable, hence calls to MapSurface() will fail.

Pre-condition: The Surface Manager has been successfully opened.

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

Parameters

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

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

IMPORT_C TInt	CreateSurface	(	const TSurfaceCreationAttributesBuf &	aReqs,
			TSurfaceId &	aSurfaceId,
			const RChunk &	aChunkHandle
		)

Creates a surface in an existing shared chunk specified by the caller and returns its global unique identifier.

If the creation succeeds, the surface will be opened with a reference count of 1 in the calling process.

The Surface Manager implementation should validate at least the following:

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 (not zero), 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 iOffsetBetweenBuffers is zero, the Surface Manager implementation will layout buffer at its own discretion. Although, a buffer's offset must remain constant during the surface's lifetime.

The attributes iContiguous and iCacheAttribute are ignored for existing chunks.

Also, note that surface manager will not do any rounding for offset to first buffer and offset between buffers. It is up to the user, to give exact aligned values for this attributes, otherwise surface creation will fail.

If iMappable is EFalse the surface won't be mappable, hence calls to MapSurface() will fail.

Pre-condition: The Surface Manager has been successfully opened.; A valid shared chunk exists. The shared chunk type should be Shared Kernel multiple and should be right the size, i.e. 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 has opened the chunk.; The surface is created and opened in the creating process.

Parameters

const 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.

Driver()

RSurfaceManagerDriver &

Driver

(

)

[private, inline]

Get a reference of the implementation of the surface manager.

GetBufferOffset(const TSurfaceId &, TInt, TInt &)

IMPORT_C TInt	GetBufferOffset	(	const TSurfaceId &	aSurfaceId,
			TInt	aBuffer,
			TInt &	aOffset
		)

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 &, THintPair &)

IMPORT_C TInt	GetSurfaceHint	(	const TSurfaceId &	aSurfaceId,
			THintPair &	aHint
		)

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.
THintPair & aHint	The hint value for the requested hint pair key.

GetSurfaceManagerAttrib(TSurfaceManagerAttrib, TInt &)

IMPORT_C TInt	GetSurfaceManagerAttrib	(	TSurfaceManagerAttrib	aAttrib,
			TInt &	aValue
		)

Returns information specific to the Surface Manager implementation.

Parameters

TSurfaceManagerAttrib aAttrib	Attribute to retrieve
TInt & aValue	Output parameter set to the value for the specified attribute

MapSurface(const TSurfaceId &, RChunk &)

IMPORT_C TInt	MapSurface	(	const TSurfaceId &	aSurfaceId,
			RChunk &	aHandle
		)

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 aChunk is open.

Whether or not a surface is mappable is determined at creation time, see TSurfaceCreationAttributes::iMappable.

The address of the pixel data in buffer N is chunk.Base() + GetBufferOffset(N).

Surfaces created with existing shared chunks will get the same chunk handle.

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 process's address space. The surface is mapped.

RChunk RHandleBase::Duplicate TSurfaceCreationAttributes::iMappable

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.

Open()

IMPORT_C TInt

Open

(

)

Opens a connection to the Surface Manager.

The connection needs to be closed by calling Close() when it is no longer required.

OpenSurface(const TSurfaceId &)

IMPORT_C TInt

OpenSurface

(

const TSurfaceId &

aSurfaceId

)

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 THintPair &)

IMPORT_C TInt	SetSurfaceHint	(	const TSurfaceId &	aSurfaceId,
			const THintPair &	aHint
		)

Set the surface hint value for the surface ID.

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 THintPair & aHint	The value of the hint pair to set.

SurfaceInfo(const TSurfaceId &, TInfoBuf &)

IMPORT_C TInt	SurfaceInfo	(	const TSurfaceId &	aSurfaceId,
			TInfoBuf &	aInfo
		)

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.
TInfoBuf & aInfo	TInfoBuf to receive the information about the surface.

SynchronizeCache(const TSurfaceId &, TInt, TSyncOperation)

IMPORT_C TInt	SynchronizeCache	(	const TSurfaceId &	aSurfaceId,
			TInt	aBuffer,
			TSyncOperation	aOperation
		)

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.
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.

Member Enumerations Documentation

Enum TCacheAttribute

Enumerators

ECached = 0	CPU cached
ENotCached = 1	Non CPU cached

Enum TPageAlignment

Enumerators

EPageAligned = -1

Specifies iAlignment is a page alignment

Enum TSurfaceManagerAttrib

Enumerators

EMaxNumberOfHints = 0x0

Maximum number of hints per surface

Enum TSyncOperation

Enumerators

ESyncBeforeNonCPURead	Synchronize before non CPU hardware reads from the memory, i.e. if the buffer is cached and may have been written to by the CPU, this type of synchronisation should be used before a peripheral is used to read from the buffer's memory
ESyncBeforeNonCPUWrite	Synchronize before non CPU hardware writes to the memory, i.e. if the buffer is cached and may have been written to by the CPU, this type of synchronisation should be used before a peripheral is used to write to the buffer's memory
ESyncAfterNonCPUWrite	Synchronize after non CPU hardware writes to the memory, i.e. if the buffer is cached, this type of synchronisation should be used after a peripheral has been used to write to the buffer's memory

Member Type Definitions Documentation

Typedef TInfoBuf

typedef TPckgBuf< TSurfaceInfoV01 >

TInfoBuf

Package buf used to pass information about a surface from the driver

Typedef TSurfaceCreationAttributesBuf

typedef TPckgBuf< TSurfaceCreationAttributes >

TSurfaceCreationAttributesBuf

Package buf used to pass the surface creation attributes to the device driver

Member Data Documentation

TInt32 iDriverBuf

TInt32

iDriverBuf

[private]