14           </title> <image href="GUID-A021A398-2FD0-5AAA-90B9-418996877600_d0e277947_href.png" placement="inline"/></fig> <p>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. </p> <p>The Symbian Surface Manager consists of: </p> <ul><li id="GUID-FBE13EEF-D6E7-5D9A-AC7B-B8D05AFEDDDD"><p>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. </p> </li> <li id="GUID-9D528A65-1A06-548F-8CF5-7603932E5910"><p>A reference implementation, which consists of a Logical Device Driver (LDD) and a kernel extension. This implements surfaces as <xref href="GUID-51514A4B-0220-557B-9F7A-FB110CEFEF10.dita">shared chunks</xref>, 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. </p> <p>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. </p> </li> </ul> <fig id="GUID-C33ED56C-4E4D-5A13-BC19-3E723C68A583"><title>

    14           </title> <image href="GUID-A021A398-2FD0-5AAA-90B9-418996877600_d0e283947_href.png" placement="inline"/></fig> <p>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. </p> <p>The Symbian Surface Manager consists of: </p> <ul><li id="GUID-FBE13EEF-D6E7-5D9A-AC7B-B8D05AFEDDDD"><p>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. </p> </li> <li id="GUID-9D528A65-1A06-548F-8CF5-7603932E5910"><p>A reference implementation, which consists of a Logical Device Driver (LDD) and a kernel extension. This implements surfaces as <xref href="GUID-51514A4B-0220-557B-9F7A-FB110CEFEF10.dita">shared chunks</xref>, 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. </p> <p>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. </p> </li> </ul> <fig id="GUID-C33ED56C-4E4D-5A13-BC19-3E723C68A583"><title>

    16           </title> <image href="GUID-5606802D-7517-5BA5-A3BD-A54C417A1B64_d0e277977_href.png" placement="inline"/></fig> <p>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. </p> <p>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. </p> <fig id="GUID-F1EA4AD3-6711-5FF0-8E79-817F6DD1E02D"><title>

    16           </title> <image href="GUID-5606802D-7517-5BA5-A3BD-A54C417A1B64_d0e283977_href.png" placement="inline"/></fig> <p>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. </p> <p>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. </p> <fig id="GUID-F1EA4AD3-6711-5FF0-8E79-817F6DD1E02D"><title>

    18           </title> <image href="GUID-57372CC6-C7CC-5802-B24C-66A272359968_d0e277989_href.png" placement="inline"/></fig> </section> <section><title>Description</title> <p>Features of the Surface Manager API and reference implementation include: </p> <ul><li id="GUID-58933ADA-DD25-57A6-A263-61CF858A67AF"><p> <b>Cache control</b>  </p> <p>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. </p> </li> <li id="GUID-C82A0E75-B9AA-59E0-960C-8EC4CF079D94"><p> <b>Chunk adoption</b>  </p> <p>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. </p> <p>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. </p> </li> <li id="GUID-1B8CE968-1F8A-5BA9-83F6-EDB2912DFCD0"><p> <b>Hinting support</b>  </p> <p>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. </p> </li> <li id="GUID-11218802-D733-52E1-8C2E-78ECF48AD4DD"><p> <b>Surface states</b>  </p> <p>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: </p> <ul><li id="GUID-9946AA45-923A-5AFD-8713-62D2B4181E28"><p> <b>Invalid</b>. No surface exists with that ID. </p> </li> <li id="GUID-BDCA4B3B-00F0-5258-A9BB-C5E5D283DB99"><p> <b>Closed</b>. The surface exists, but is not open in the process. </p> </li> <li id="GUID-ED6CCEAF-B11B-5A40-8FF0-598996AC2944"><p> <b>Open</b>. The process has opened the surface. </p> </li> <li id="GUID-88A677B6-0374-5494-9405-59F27A433CE6"><p> <b>Mapped</b>. The process has mapped the surface into its address space. This implies that the surface is open in that process. </p> </li> </ul> <p>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. </p> </li> <li id="GUID-8E5B4474-9D5C-5C7A-94EA-A7CE5F3F5CDF"><p> <b>Reference Counting</b>  </p> <p>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 <codeph>OpenSurface()</codeph> and gets decremented each time <codeph>CloseSurface()</codeph> is called. When the count drops to zero the Surface Manager deletes the surface and releases the memory. </p> <p>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. </p> </li> </ul> </section> <section><title>Executables</title> <p>The Surface Manager component contains the following executable files: </p> <table id="GUID-482D8833-2DA6-579A-8A84-F79AC8BB066A"><tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/><thead><row><entry>Name</entry> <entry>Description</entry> </row> </thead> <tbody><row><entry><p> <filepath>Surfacemanager.dll</filepath>  </p> </entry> <entry><p>The Surface Manager user-side API, which provides features to create and delete surfaces, to access surface pixel data and to query surface attributes. This routes the calls through to the device driver. </p> </entry> </row> <row><entry><p> <filepath>surfacemanagerdriver.ldd</filepath>  </p> </entry> <entry><p>A system memory logical device driver and kernel extension. It performs shared chunk allocation and allows the client to specify caching attributes. </p> </entry> </row> </tbody> </tgroup> </table> </section> <section><title>Typical uses</title> <p>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. </p> <p>Clients of the Surface Manager simply create an instance of the client side class <xref href="GUID-733B8BFA-7BC2-3A6D-A66F-F788413D25A9.dita"><apiname>RSurfaceManager</apiname></xref> and use its API. The complexities of device driver communication, memory management and thread safety are completely encapsulated. </p> <codeblock id="GUID-821CBBD0-C966-5720-960E-28F2A01CEEE2" xml:space="preserve">RSurfaceManager surfaceManager;

    18           </title> <image href="GUID-57372CC6-C7CC-5802-B24C-66A272359968_d0e283989_href.png" placement="inline"/></fig> </section> <section><title>Description</title> <p>Features of the Surface Manager API and reference implementation include: </p> <ul><li id="GUID-58933ADA-DD25-57A6-A263-61CF858A67AF"><p> <b>Cache control</b>  </p> <p>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. </p> </li> <li id="GUID-C82A0E75-B9AA-59E0-960C-8EC4CF079D94"><p> <b>Chunk adoption</b>  </p> <p>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. </p> <p>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. </p> </li> <li id="GUID-1B8CE968-1F8A-5BA9-83F6-EDB2912DFCD0"><p> <b>Hinting support</b>  </p> <p>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. </p> </li> <li id="GUID-11218802-D733-52E1-8C2E-78ECF48AD4DD"><p> <b>Surface states</b>  </p> <p>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: </p> <ul><li id="GUID-9946AA45-923A-5AFD-8713-62D2B4181E28"><p> <b>Invalid</b>. No surface exists with that ID. </p> </li> <li id="GUID-BDCA4B3B-00F0-5258-A9BB-C5E5D283DB99"><p> <b>Closed</b>. The surface exists, but is not open in the process. </p> </li> <li id="GUID-ED6CCEAF-B11B-5A40-8FF0-598996AC2944"><p> <b>Open</b>. The process has opened the surface. </p> </li> <li id="GUID-88A677B6-0374-5494-9405-59F27A433CE6"><p> <b>Mapped</b>. The process has mapped the surface into its address space. This implies that the surface is open in that process. </p> </li> </ul> <p>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. </p> </li> <li id="GUID-8E5B4474-9D5C-5C7A-94EA-A7CE5F3F5CDF"><p> <b>Reference Counting</b>  </p> <p>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 <codeph>OpenSurface()</codeph> and gets decremented each time <codeph>CloseSurface()</codeph> is called. When the count drops to zero the Surface Manager deletes the surface and releases the memory. </p> <p>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. </p> </li> </ul> </section> <section><title>Executables</title> <p>The Surface Manager component contains the following executable files: </p> <table id="GUID-482D8833-2DA6-579A-8A84-F79AC8BB066A"><tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/><thead><row><entry>Name</entry> <entry>Description</entry> </row> </thead> <tbody><row><entry><p> <filepath>Surfacemanager.dll</filepath>  </p> </entry> <entry><p>The Surface Manager user-side API, which provides features to create and delete surfaces, to access surface pixel data and to query surface attributes. This routes the calls through to the device driver. </p> </entry> </row> <row><entry><p> <filepath>surfacemanagerdriver.ldd</filepath>  </p> </entry> <entry><p>A system memory logical device driver and kernel extension. It performs shared chunk allocation and allows the client to specify caching attributes. </p> </entry> </row> </tbody> </tgroup> </table> </section> <section><title>Typical uses</title> <p>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. </p> <p>Clients of the Surface Manager simply create an instance of the client side class <xref href="GUID-733B8BFA-7BC2-3A6D-A66F-F788413D25A9.dita"><apiname>RSurfaceManager</apiname></xref> and use its API. The complexities of device driver communication, memory management and thread safety are completely encapsulated. </p> <codeblock id="GUID-821CBBD0-C966-5720-960E-28F2A01CEEE2" xml:space="preserve">RSurfaceManager surfaceManager;