RSurfaceManager Class Reference

class RSurfaceManager

RSurface Manager User API.

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

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]