<?xml version="1.0" encoding="utf-8"?>
<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->
<!-- This component and the accompanying materials are made available under the terms of the License 
"Eclipse Public License v1.0" which accompanies this distribution, 
and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->
<!-- Initial Contributors:
    Nokia Corporation - initial contribution.
Contributors: 
-->
<!DOCTYPE concept
  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
<concept id="GUID-11F00FB3-7353-5545-9A39-BEB3B489A15C" xml:lang="en"><title>Creating
a Graphics Resource Adaptation</title><shortdesc>This topic provides information about creating a graphics resource
adaptation. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>
<p><b>Target audience</b>: Device creators.</p>
<note type="note">The Graphics Resource and Graphics Resource Adaptation components
are deprecated in Symbian^3 and will be removed in Symbian^4 (S^4). However,
new Graphics Resource Interface and Implementation components are planned
for S^4. The new interface component will provide a similar but reduced API
that is optimized for sharing images across processes.  </note>
<section id="GUID-1169B355-204B-4E32-A4E3-B083FE3A8456"><title>Required background</title> <p>This
topic assumes an understanding of the material contained in the following: </p> <ul>
<li id="GUID-36766311-AE66-5835-88BA-A196A02E6118"><p><xref href="GUID-59C9EF92-8207-5FA5-AA20-0DB00C211BF1.dita">Graphics
Resource Services Collection Overview</xref>  </p> </li>
<li id="GUID-DBB1E138-C862-555B-8CC3-089DA0933950"><p><xref href="GUID-82B0B4B9-6BC2-5BEF-B3B0-D57AC57F8D8A.dita">Graphics
Resource Component Overview</xref>  </p> </li>
<li id="GUID-73947232-DE71-590F-A553-44E601936CD7"><p><xref href="GUID-29C7FBFB-2F33-58CA-86BE-978E3187E4D6.dita">Image
Compatibility Guarantees</xref>  </p> </li>
</ul> </section>
<section id="GUID-254498CD-E4C3-4D4B-B3A2-F6AFB78B7F14"><title>Packaging the
DLL</title> <p>When packaging the adaptation, the following rules apply: </p> <ul>
<li id="GUID-07F0C6AB-39FB-56EA-B760-70756EB63687"><p>The graphics resource
adaptation must be packaged as a DLL with the name <b>graphicsresourceadapter.dll</b>. </p> </li>
<li id="GUID-5DB1D47F-269C-5756-B61E-6435CD3D0066"><p>The second and third
UIDs must be <codeph>0x1000008D</codeph> and <codeph>0x10285A71</codeph>,
respectively. </p> </li>
<li id="GUID-7EE8AE66-E8C2-5A06-B07D-23032EBE3C51"><p>All capabilities except
TCB (Trusted Computing Base) are required. </p> </li>
<li id="GUID-164F71FE-3BC8-5433-AC9B-2A3876073980"><p>The <codeph>NOEXPORTLIBRARY</codeph> keyword
must be used in the MMP file to prevent the generation of LIB/DSO files during
the build process. </p> </li>
</ul> <p>Here is a snippet of an example MMP file: </p> <codeblock id="GUID-98AD4AEC-60CC-56ED-9099-B83E8261CE75" xml:space="preserve">TARGET graphicsresourceadapter.dll
TARGETTYPE DLL
CAPABILITY All -Tcb
UID 0x1000008D 0x10285A71
VENDORID &lt;Your vendor ID in hex&gt;
NOEXPORTLIBRARY</codeblock> <p>The reference adaptation component has one
implementation for the emulator and several implementations for different
hardware configurations. These latter ones have different names and the one
that is to be used in the device is renamed to <filepath>graphicsresourceadapter.dll</filepath> during
the ROM building process. You may want to use a similar approach. See <xref href="GUID-946E64D6-3E5D-5264-AD5D-29D3AD296543.dita">Selection of Adaptations</xref> for
more information. </p> <p>Because the Graphics Resource Adaptation component
is optional, the <xref href="GUID-82B0B4B9-6BC2-5BEF-B3B0-D57AC57F8D8A.dita">Graphics
Resource component</xref> provides a <b>stub implementation</b> for platform
security reasons. When a functional adaptation is not present, the stub implementation
is compiled into a DLL called <filepath>graphicsresourceadapter.dll</filepath> and
is installed in the ROM in order to prevent a SIS file installing a rogue
DLL with this name. </p> </section>
<section id="GUID-DA7CA4DC-0830-4962-A648-7CE7520069FC"><title>The exported
function</title> <p>The graphics resource adaptation DLL is a polymorphic
interface DLL that must export a single function at ordinal position one.
The function that must be exported is <xref href="GUID-62D3F49B-E048-3C07-ABDC-2DB6CC268127.dita#GUID-62D3F49B-E048-3C07-ABDC-2DB6CC268127/GUID-695826EA-AD3A-31B5-BC6F-0D29066AE3B3"><apiname>MSgDriverAdapter::New()</apiname></xref>.
Here is its definition from the stub implementation: </p> <codeblock id="GUID-52F4C7DE-0F65-54F0-ACB1-878145BA29CA" xml:space="preserve">
EXPORT_C TInt MSgDriverAdapter::New(MSgDriverAdapter*&amp; /*aPtr*/)
    {
    return KErrNotSupported;
    }</codeblock> <p>This simply returns <xref href="GUID-F89DA3F0-2A48-3F9B-8F08-29350E92D0E4.dita"><apiname>KErrNotSupported</apiname></xref> to
indicate that the graphics resource functionality is not supported. This is
because, as mentioned above, the stub implementation is used for platform
security reasons when no functional Graphics Resource adaptation is present. </p> <p>In
a functional implementation, the function must create a multi-threaded heap,
allocate from it and initialize a new instance of the singleton class that
implements the <xref href="GUID-62D3F49B-E048-3C07-ABDC-2DB6CC268127.dita"><apiname>MSgDriverAdapter</apiname></xref> interface and return it
in the pointer argument. </p> </section>
<section id="GUID-2792BB88-8B70-4B6D-AD3D-FBACE870B3A7"><title>Implementing
the interfaces</title> <p>The <xref href="GUID-82B0B4B9-6BC2-5BEF-B3B0-D57AC57F8D8A.dita">Graphics
Resource Component</xref> provides a Hardware Adaptation Interface (HAI),
which separates the generic and adaptation parts. This defines a set of interfaces
for which the adaptation must provide an implementation. As long as the implementation
conforms to the interface specifications and contracts, you are free to write
the adaptation as you see fit. </p> <p>The following is a class diagram of
the interfaces. </p> <fig id="GUID-D23E912B-C752-5F20-A595-3F779B4E7C5D">
<title>              Figure 1: The graphics resource adapter interfaces  
         </title>
<image href="GUID-BFA254D4-5104-5B15-8035-2491B57D136D_d0e247694_href.png" placement="inline"/>
</fig> <p> <b>Driver adapter</b>. You must provide a concrete driver adapter
class that implements the <xref href="GUID-62D3F49B-E048-3C07-ABDC-2DB6CC268127.dita"><apiname>MSgDriverAdapter</apiname></xref> interface. This
is a singleton class. A single instance of it is created for each process
that uses the Graphics Resource API. The singleton is responsible for creating
image adapter and image collection adapter objects. </p> <p> <b>Image adapter</b>.
You must provide at least one concrete image adapter class that implements
the <xref href="GUID-B339AA1C-5E2B-314D-A220-07893AA1B10A.dita"><apiname>MSgImageAdapter</apiname></xref> interface. You can provide as many
concrete image adapter classes as needed. The driver adapter singleton creates
an instance of the appropriate image adapter class for each image that is
created or opened by the process. </p> <p>There are three different ways in
which an image adapter object can be created: </p> <ul>
<li id="GUID-C02BEF84-57D6-52FB-B631-02AFCF6AE387"><p>A call to <xref href="GUID-62D3F49B-E048-3C07-ABDC-2DB6CC268127.dita#GUID-62D3F49B-E048-3C07-ABDC-2DB6CC268127/GUID-EE8F0719-E923-3B79-8D8D-068625B8BE09"><apiname>MSgDriverAdapter::CreateImage()</apiname></xref>,
which creates an image and its image adapter object. </p> </li>
<li id="GUID-64159685-6CC5-5ED7-9B69-2ACF97576492"><p>A call to <xref href="GUID-62D3F49B-E048-3C07-ABDC-2DB6CC268127.dita#GUID-62D3F49B-E048-3C07-ABDC-2DB6CC268127/GUID-21D8361F-5F19-3F5F-8BAB-A8EA2171ADAD"><apiname>MSgDriverAdapter::OpenDrawable()</apiname></xref>,
which opens an existing image for which the ID is known. This also creates
an image adapter object for the image if one does not already exist within
the process. This function enables images to be shared between processes.
Note that the driver adapter singleton does not create image adapter objects
in a process (A) for images that are created by another process (B) if they
are not opened in process A. </p> </li>
<li id="GUID-CAF50D78-4656-5831-BBF9-44F25A5F0A7E"><p>A call to <xref href="GUID-95174AD4-74FB-37E2-8D71-E182467581B4.dita#GUID-95174AD4-74FB-37E2-8D71-E182467581B4/GUID-C9C6153B-1D71-3790-BE3D-56C2CC6DF14F"><apiname>MSgImageCollectionAdapter::OpenImage()</apiname></xref>,
which creates an image adapter object to encapsulate a surface buffer belonging
to an existing image collection. </p> </li>
</ul> <p>The implementation of these functions must use the shared multi-threaded
heap owned by the driver adapter singleton for all allocations and perform
any initialization that is required. </p> <p> <b>Image collection adapter</b>.
You must provide a concrete image collection adapter class that implements
the <xref href="GUID-95174AD4-74FB-37E2-8D71-E182467581B4.dita"><apiname>MSgImageCollectionAdapter</apiname></xref> interface. The driver adapter
singleton creates an instance of this class for each image collection that
is created by the process. </p> <p>The purpose of the image collection class
is to provide interoperability with the <xref href="GUID-0DC3E5AA-1706-5255-ACD6-E7AB732E1095.dita">composition
engine</xref> and <xref href="GUID-8E8FE99A-5F4D-5B0F-87AB-A58EB4BEB6E9.dita">Surface
Update Server</xref>. Therefore, unlike image adapters and platform-specific
resource adapters, which you are free to implement as you see fit, you must
implement the image collection adapter in terms of surfaces that are compatible
with the Surface Manager. The implementation of the <xref href="GUID-95174AD4-74FB-37E2-8D71-E182467581B4.dita#GUID-95174AD4-74FB-37E2-8D71-E182467581B4/GUID-3E96077B-FB6D-33D4-B10D-299350496DEF"><apiname>MSgImageCollectionAdapter::SurfaceId()</apiname></xref> function
must return the surface ID of the image collection's surface. </p> <p>There
are two different methods that create image collections: </p> <ul>
<li id="GUID-4F3335D5-0D6A-57F5-88BF-0493F36E5A6B"><p> <xref href="GUID-62D3F49B-E048-3C07-ABDC-2DB6CC268127.dita#GUID-62D3F49B-E048-3C07-ABDC-2DB6CC268127/GUID-4BA00DC9-85BD-36D5-9B3F-A1B27BA78D84"><apiname>MSgDriverAdapter::CreateImageCollection()</apiname></xref>.
This creates a single image collection and its associated image collection
adapter object. </p> </li>
<li id="GUID-73E36A71-4981-5A3F-BF17-43068705427C"><p> <xref href="GUID-62D3F49B-E048-3C07-ABDC-2DB6CC268127.dita#GUID-62D3F49B-E048-3C07-ABDC-2DB6CC268127/GUID-DD16AD64-4459-3067-9165-6B1BB574DDBD"><apiname>MSgDriverAdapter::CreateImageCollections()</apiname></xref>.
This creates a number of image collections that share a single memory chunk
(in order to save memory if only one of the image collections will be in use
at a time). Although they share a memory chunk, each of these image collections
has its own surface ID and image collection adapter object. This function
also creates the associated image collection adapter objects. </p> </li>
</ul> <p>The implementation of these functions must use the shared multi-threaded
heap owned by the driver adapter singleton for all allocations and perform
any initialization that is required. </p> <p>For interoperability with applications
that expect images, you must provide an implementation of <xref href="GUID-95174AD4-74FB-37E2-8D71-E182467581B4.dita#GUID-95174AD4-74FB-37E2-8D71-E182467581B4/GUID-C9C6153B-1D71-3790-BE3D-56C2CC6DF14F"><apiname>MSgImageCollectionAdapter::OpenImage()</apiname></xref>.
This wraps up a surface buffer as an image by creating a suitable image adapter
object for it. </p> </section>
<section id="GUID-4AEFB09D-0E75-476E-BFEF-03A5E97B3925"><title>Resource types</title> <p>The
Symbian reference adaptation provides only one type of resource—the image
(2D pixel buffer). However, you can define additional types of resources—for
example, for handling vector data. A UID is used to identify the <b>resource
type</b>. The <xref href="GUID-1129AC1A-3A70-3B2E-9E23-E6491B50EFB2.dita"><apiname>KSgImageTypeUid</apiname></xref> constant represents the UID
for images. This is defined as follows: </p> <codeblock id="GUID-B93AB2AB-AA24-5664-93BD-09D395C623BE" xml:space="preserve">const TUid KSgImageTypeUid = {0x10285A73};</codeblock> <p>If you create a new resource type, you must obtain a UID from Symbian
Signed to represent its runtime type. The implementation of the <xref href="GUID-185B6C03-E4F3-382A-AAD5-BA5D85334CBB.dita#GUID-185B6C03-E4F3-382A-AAD5-BA5D85334CBB/GUID-E557C57C-0808-3DD9-83C3-45181AAE56A7"><apiname>MSgDrawableAdapter::DrawableType()</apiname></xref> function
must return the UID of the resource type. </p> <p>Related to the resource
type is the <b>handle type</b>. This constrains the type of resource that
can be opened by calls to the <xref href="GUID-62D3F49B-E048-3C07-ABDC-2DB6CC268127.dita#GUID-62D3F49B-E048-3C07-ABDC-2DB6CC268127/GUID-21D8361F-5F19-3F5F-8BAB-A8EA2171ADAD"><apiname>MSgDriverAdapter::OpenDrawable()</apiname></xref> function.
The implementation of this function must check that the actual runtime type
of the resource to be opened is compatible with the handle that will contain
a reference to it. The function must return an error if the runtime resource
type is not compatible with the specified handle type. </p> <p>Two handle
types are defined by Symbian: </p> <ul>
<li id="GUID-DF05975C-0C71-5BA3-84CA-CCEA4289E481"><p>The image handle type,
which can contain a reference to an image resource only. This has the same
UID as the image resource type (mentioned above). </p> </li>
<li id="GUID-685E7C70-A10D-56E2-9F0A-D4A742ECD3F8"><p>The drawable handle
type, which can contain a reference to an image or any platform-specific resource
type. This is defined as follows: </p> <codeblock id="GUID-83427673-6CE0-511B-BB15-BACFD87AAE03" xml:space="preserve">const TUid KSgDrawableTypeUid = {0x102858EB};</codeblock> </li>
</ul> </section>
<section id="GUID-D435C12A-782C-5CC7-9E19-8FBD35C9D652"><title>Reference counting</title> <p>All
of the adapter objects apart from the driver adapter singleton must be reference
counted as follows: </p> <ul>
<li id="GUID-6004AAE4-CEF4-565C-A073-3095DCA27A3E"><p>Each time that an adapter
object is created, its reference count must be set to one. </p> </li>
<li id="GUID-5DAC9C2E-9700-59A7-8B26-16E29D93F65F"><p>For resources that can
be shared between processes, the implementation of <xref href="GUID-62D3F49B-E048-3C07-ABDC-2DB6CC268127.dita#GUID-62D3F49B-E048-3C07-ABDC-2DB6CC268127/GUID-21D8361F-5F19-3F5F-8BAB-A8EA2171ADAD"><apiname>MSgDriverAdapter::OpenDrawable()</apiname></xref> checks
for the existence of the resource adapter object in the process in which the
resource is to be opened. If the adapter object exists in that process, the
implementation increments its reference count. If the adapter object does
not exist in that process, the implementation creates one and sets its reference
count to one. </p> </li>
<li id="GUID-5E2A9601-AE6B-5ED4-AB1F-B84BDF3C56C8"><p>All reference-counted
adapter objects are destroyed in the same way—the implementation of the <codeph>Close()</codeph> function
decrements the reference count and destroys the adapter object when the reference
count reaches zero. When the adapter object is destroyed, the reference count
on the underlying resource must also be decremented and the underlying resource
must be destroyed when its reference count reaches zero. </p> <p>The <codeph>Close()</codeph> function
is part of the <xref href="GUID-47124FC9-A94D-3687-8CAA-61DEE3C1805E.dita"><apiname>MSgResourceAdapter</apiname></xref> interface, from which <xref href="GUID-95174AD4-74FB-37E2-8D71-E182467581B4.dita"><apiname>MSgImageCollectionAdapter</apiname></xref> and <xref href="GUID-185B6C03-E4F3-382A-AAD5-BA5D85334CBB.dita"><apiname>MSgDrawableAdapter</apiname></xref> (and ultimately <xref href="GUID-B339AA1C-5E2B-314D-A220-07893AA1B10A.dita"><apiname>MSgImageAdapter</apiname></xref>) inherit. </p> <p> </p> </li>
</ul> <p>The following diagram shows an image that is shared between two processes—one
of which has two handles to the image and the other a single handle. When
all of the handles to the image are closed, the image itself is destroyed. </p> <fig id="GUID-189A3A15-947A-5C39-9B84-630679944C30">
<title>              Figure 2: Reference counting resources and adapter objects
           </title>
<image href="GUID-582B36BD-88B3-5B5B-8A20-058318E80D0B_d0e247930_href.png" placement="inline"/>
</fig> </section>
<section id="GUID-A254D2A4-AAF4-43CA-9C4F-DB41F5F2F13B"><title>Thread safety</title> <p>All
of the adapter objects can potentially be shared between all of the threads
in the process. This means that they must all be thread safe. Normally you
implement thread safety by using mutexes. The reference implementation handles
this by using a single mutex per process to synchronize access to all of the
adapter objects in the process. </p> <p>When running on multiple processors,
such as symmetric multiprocessing (SMP), using a separate mutex for each adapter
object might provide a more efficient solution. This approach can improve
performance by avoiding unnecessary serialization but it has drawbacks. For
example, each additional mutex increases the memory usage. In addition multiple
mutexes are more complex to program and require very careful program design
in order to prevent the occurrence of deadlocks and other synchronization
problems. </p> <p>All of the adapter objects, including the driver adapter
singleton, can potentially be created in the context of one thread and destroyed
in the context of a different thread. Therefore they must be allocated from
a multi-threaded heap shared between all the threads in the process and owned
by the driver adapter singleton. </p> </section>
<section id="GUID-D0F63C01-8CAE-436C-9058-4E570A858D58"><title>Extension interfaces</title> <p>The <xref href="GUID-185B6C03-E4F3-382A-AAD5-BA5D85334CBB.dita#GUID-185B6C03-E4F3-382A-AAD5-BA5D85334CBB/GUID-D1BFFF76-37B5-3DD5-A4E3-51B98264CB91"><apiname>MSgDrawableAdapter::GetInterface()</apiname></xref> function provides an optional mechanism for platforms to extend the HAI
by defining extension interfaces. These can be accessed by using the <xref href="GUID-6F23F34A-A0BE-349C-ADE7-61A5AEF48018.dita#GUID-6F23F34A-A0BE-349C-ADE7-61A5AEF48018/GUID-0D64A708-42C3-361A-B463-E9C0F3542919"><apiname>RSgDrawable::GetInterface()</apiname></xref> method,
which delegates to <xref href="GUID-185B6C03-E4F3-382A-AAD5-BA5D85334CBB.dita#GUID-185B6C03-E4F3-382A-AAD5-BA5D85334CBB/GUID-D1BFFF76-37B5-3DD5-A4E3-51B98264CB91"><apiname>MSgDrawableAdapter::GetInterface()</apiname></xref>. </p> </section>
</conbody><related-links>
<link href="GUID-26E51AB0-C0FC-55EA-B747-C834E2D4FD27.dita"><linktext>Graphics
Resource Services Collection</linktext></link>
</related-links></concept>