Surface Manager Overview

Summary

The Surface Manager creates and manages graphics composition surfaces:

• The Surface Manager allocates memory to which it controls access and that it can safely permit hardware to access.

• The Surface Manager maintains size and format information.

• The Surface Manager keeps track of the clients using each surface.

The Surface Manager provides an API that allows clients to create, open, access (map to) and close surfaces. A client can also simply request a surface's attributes. Clients cannot change a surface's attributes which, once the surface has been created, are generally immutable.

Surfaces are uniquely identified by a 128 bit surface ID. This comprises eight bits that identify the surface type and 120 bits that identify the surface itself.

A client that creates a surface can pass its ID to another process. That process can then become a client of the Surface Manager and use the ID to access the surface. Access to a surface is strictly limited to clients that know the ID.

Architecture

The Surface Manager creates and manages surfaces that are used as input to the composition engine.

The Surface Manager is an adaptation component, which means that it can be modified or replaced to suit the exact hardware that is available on a specific device.

The Symbian Surface Manager consists of:

• A generic DLL that provides the user-side API. This provides features to create and delete surfaces, to access surface pixel data and to query surface attributes. It routes the calls through to the device driver.

• A reference implementation, which consists of a Logical Device Driver (LDD) and a kernel extension. This implements surfaces as shared chunks, which allow memory to be mapped into the address space of multiple applications and to be available to hardware such as the MBX GPU. This allows instant access and avoids copying or moving large amounts of data.

  Shared chunks are memory regions that can be safely shared between user-side and kernel-side processes. The implementation is a kernel extension because shared chunks can only be created by the kernel. As a kernel extension it is controlled using an LDD. It performs shared chunk allocation and allows the client to specify caching attributes.

Device creators can replace the reference implementation and retain the user-side API. Alternatively, it is possible to replace both the implementation and the user-side API or to replace the implementation and to extend the user-side API.

It is generally necessary to create a custom Surface Manager implementation if hardware-accelerated surfaces (surfaces stored in memory managed by the GPU) are to be used. Device creators can also provide their own APIs on top of the Surface Manager. The following diagram shows the default configuration and two possible adaptation configurations.

Description

Features of the Surface Manager API and reference implementation include:

• Cache control

  Surface Manager allows cached or uncached operation. If the Memory Management Unit (MMU) supports caching, the client can specify the caching attributes that the Surface Manager is to use for the shared chunk allocation. This enables the Surface Manager to create surfaces in shared chunks that are suitable for both hardware and software renderers. If the MMU does not support the requested caching attribute, a lesser one is used. The client can subsequently query the supported cache behavior.

• Chunk adoption

  Clients can specify a pre-existing shared chunk when creating surfaces. The shared chunk can originate from an existing surface allocated through the Surface Manager or from another driver. The Surface Manager adopts the chunk passed in instead of allocating new memory. This means that pixel data that has already been written to a shared chunk by, for example, the camera driver, can be used as input to the composition engine.

  This functionality also allows memory to be saved because one chunk can be used for both landscape and portrait orientations of a surface when both orientations are not required at the same time.

• Hinting support

  Like metadata, surface hints contain information about surface content. Hints are defined by the device creator and consist of key-value pairs, each of which has a flag that determines whether the value can be changed. Other processes that have access to the surface can read this data and change it if the hint is mutable. They can also add hints after creation of the surface.

• Surface states

  The Surface Manager determines the relationship between each client process and each Surface ID. Each process sees each surface ID as being in one of the following states:

  • Invalid. No surface exists with that ID.

  • Closed. The surface exists, but is not open in the process.

  • Open. The process has opened the surface.

  • Mapped. The process has mapped the surface into its address space. This implies that the surface is open in that process.

  Multiple processes that refer to the same surface may have different relationships with that surface. For example, the surface may be mapped in one process but simply open in another process. Most Surface Manager operations require the surface to be in a particular state relative to the calling process. If the surface is not in the required state an error is returned.

• Reference Counting

  The Surface Manager maintains a reference count for each surface. The count is started when the surface is created, gets incremented each time a client calls OpenSurface() and gets decremented each time CloseSurface() is called. When the count drops to zero the Surface Manager deletes the surface and releases the memory.

  When a process exits or closes its session with the Surface Manager, the Surface Manager closes all of the surfaces that the process has open.

Executables

The Surface Manager component contains the following executable files:

Typical uses

Typical use involves creating a surface, querying its properties and passing the surface ID to another process. A second process can then open the surface.

Clients of the Surface Manager simply create an instance of the client side class RSurfaceManager and use its API. The complexities of device driver communication, memory management and thread safety are completely encapsulated.

RSurfaceManager surfaceManager;
surfaceManager.Open();
...
// Surface Manager now ready for use

Creating a surface

Before creating a surface, you specify its attributes through the TSurfaceCreationAttributes class.

class TSurfaceCreationAttributes
    {
    public:
    TSize iSize;                    // Width/height in pixels
    TInt iBuffers;                  // Number of buffers in the surface
    TUidPixelFormat iPixelFormat;   // Pixel format 
    TInt iStride;                   // Number of bytes between start of one line and start of next
    TInt iOffsetToFirstBuffer;      // Reserve space before the surface pixel data
    TInt iAlignment;                // Buffer alignment. 1,2,4,8 byte aligned
    TBool iContiguous;              // Whether you want physically contiguous memory
    TCacheAttribute iCacheAttrib;   // Caching attributes
    TInt iOffsetBetweenBuffers;     // Offset from start of one buffer and start of next in bytes
    THintPair* iSurfaceHints;       // Array of hints associated with the surface
    TInt iHintCount;                // Number of hints in the array
    TBool iMappable;                // Whether the surface should be mappable
    };

When the Surface Manager creates a surface, it creates an ID for the surface and passes it back to the client. The client then uses the ID to refer to the surface. The client can pass the ID to other applications or processes which can then use it to gain access to the surface through the Surface Manager.

For an example of creating a surface, see Creating a Graphics Surface Tutorial.

Accessing a Surface

The following code fragment illustrates how a second client can access an existing surface once it has the ID.

RSurfaceManager surfaceManager;
surfaceManager.Open();
    
RChunk chunk;
    
surfaceManager.OpenSurface(surfaceId);
surfaceManager.MapSurface(surfaceId, chunk);
    
// retrieve surface information
RSurfaceManager::TInfoBuf infoBuf;
RSurfaceManager::TSurfaceInfoV01& surfaceInfo = infoBuf();   
    
surfaceManager.SurfaceInfo(surfaceId, surfaceInfo);
    
...
    
// tidy up.

The fragment also illustrates how to get information about a surface's attributes.