1 <?xml version="1.0" encoding="utf-8"?>

     2 <!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->

     3 <!-- This component and the accompanying materials are made available under the terms of the License 

     4 "Eclipse Public License v1.0" which accompanies this distribution, 

     5 and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->

     6 <!-- Initial Contributors:

     7     Nokia Corporation - initial contribution.

     8 Contributors: 

     9 -->

    10 <!DOCTYPE concept

    11   PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">

    12 <concept id="GUID-EBE2D1D3-3A99-54BF-B5C0-08E9267F5750" xml:lang="en"><title>Creating

    13 a DirectGDI Adaptation</title><shortdesc>This topic provides information about creating a DirectGDI adaptation. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

    14 <p><b>Target audience</b>: Device creators. </p>

    15 <note type="note">DirectGDI is deprecated in Symbian^3.</note>

    16 <section id="GUID-A08F6D35-01A5-4548-8134-5300ECC0AC36"><title>Required background</title> <p>This

    17 topic assumes an understanding of the material contained in the following: </p> <ul>

    18 <li id="GUID-81CDAB03-A761-5784-BC92-61248F317444"><p><xref href="GUID-CD4B8ECA-AFE7-593C-B095-5D642EA2EC61.dita">DirectGDI

    19 Component Overview</xref>  </p> </li>

    20 <li id="GUID-FAA72B71-BD87-5796-BDE2-EE739D01CC97"><p><xref href="GUID-E9C6DBBF-1910-595D-94A1-67664CF7B7A6.dita">DirectGDI

    21 Interface Component Overview</xref>  </p> </li>

    22 <li id="GUID-66E61F77-3E30-5134-8712-3AD63F9E35CC"><p><xref href="GUID-22E46647-D677-5A47-A7E0-E1E0AE736B27.dita">DirectGDI

    23 Adaptation Overview</xref>  </p> </li>

    24 </ul> </section>

    25 <section id="GUID-9EA9C05C-919C-48B5-AE77-412CD316DF19"><title>Packaging the

    26 DLL</title> <p>When packaging the adaptation, the following rules apply: </p> <ul>

    27 <li id="GUID-C56B01DF-0C5E-511E-B0E6-842DC1643F4D"><p>The DirectGDI adaptation

    28 must be packaged as a DLL with the name <b>directgdiadapter.dll</b>. </p> </li>

    29 <li id="GUID-823E502D-A732-5F3D-98C8-F1AA790028FB"><p>The second and third

    30 UIDs must be <codeph>0x1000008D</codeph> and <codeph>0x102858E9</codeph>,

    31 respectively. </p> </li>

    32 <li id="GUID-9D1E5C7F-B9C6-5954-9B72-92D97172D977"><p>All capabilities except

    33 TCB (Trusted Computing Base) are required. </p> </li>

    34 <li id="GUID-3D0E73B9-8D09-5923-93CD-6ABED9FAE91D"><p>The <codeph>NOEXPORTLIBRARY</codeph> keyword

    35 must be used in the MMP file to prevent the generation of LIB/DSO files during

    36 the build process. </p> </li>

    37 </ul> <p>Here is a snippet of an example MMP file: </p> <codeblock id="GUID-01137A07-7723-5D31-ABB6-A9B86B047139" xml:space="preserve">TARGET directgdiadapter.dll

    38 TARGETTYPE DLL

    39 CAPABILITY All -Tcb

    40 UID 0x1000008D 0x102858E9

    41 VENDORID <Your vendor ID in hex>

    42 NOEXPORTLIBRARY</codeblock> <p>The reference adaptation component has several

    43 implementations for different configurations. These have different names and

    44 the one that is to be used in the device is renamed to <filepath>directgdiadapter.dll</filepath> during

    45 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

    46 more information. </p> <p>Because the DirectGDI Adaptation component is optional,

    47 the <xref href="GUID-A2E07A3C-B3A8-50B9-BD60-F1F01795FA24.dita">DirectGDI component</xref> provides

    48 a <b>stub implementation</b> for platform security reasons. When a functional

    49 adaptation is not present, the stub implementation is compiled into a DLL

    50 called <filepath>directgdiadapter.dll</filepath> and is installed in the ROM

    51 in order to prevent a SIS file installing a rogue DLL with this name. </p> </section>

    52 <section id="GUID-7B23C611-51FE-47E3-8F8D-0D1696132046"><title>The exported

    53 function</title> <p>The DirectGDI adaptation DLL is a polymorphic interface

    54 DLL that must export a single function at ordinal position one. The function

    55 that must be exported is <xref href="GUID-1E407D78-0FD3-30F2-BDC5-B531F34D4A27.dita#GUID-1E407D78-0FD3-30F2-BDC5-B531F34D4A27/GUID-0E41EA26-2DF7-3AB5-AC06-20EB080A6596"><apiname>CDirectGdiDriverInternal::New()</apiname></xref>.

    56 Here is its definition in the stub implementation: </p> <codeblock id="GUID-C0E2A910-2B63-56BF-A745-AE6198E221DE" xml:space="preserve">EXPORT_C TInt CDirectGdiDriverInternal::New(CDirectGdiDriverInternal*&amp; aInternal, RLibrary /*aLibrary*/)

    57     {

    58     aInternal = NULL;

    59     return KErrNotSupported;

    60     }</codeblock> <p>This simply returns <xref href="GUID-F89DA3F0-2A48-3F9B-8F08-29350E92D0E4.dita"><apiname>KErrNotSupported</apiname></xref> to

    61 indicate that the DirectGDI functionality is not supported. This is because,

    62 as mentioned above, the stub implementation is used for platform security

    63 reasons when no functional DirectGDI adaptation is present. </p> <p>In a functional

    64 implementation, the function must create a new instance of the class that

    65 is derived from <xref href="GUID-1E407D78-0FD3-30F2-BDC5-B531F34D4A27.dita"><apiname>CDirectGdiDriverInternal</apiname></xref> and return it

    66 in the pointer argument. </p> </section>

    67 <section id="GUID-2E9B5826-9CED-466C-8AB5-C6E386AA7744"><title>Implementing

    68 the interfaces</title> <p>The <xref href="GUID-E9C6DBBF-1910-595D-94A1-67664CF7B7A6.dita">DirectGDI

    69 Interface</xref> component provides a Hardware Adaptation Interface (HAI),

    70 which separates the generic and adaptation parts of the DirectGDI framework.

    71 The component defines a set of interfaces for which the adaptation must provide

    72 an implementation. As long as the implementation conforms to the interface

    73 specifications and contracts, you are free to write the adaptation as you

    74 see fit. </p> <p> <b>Driver adapter</b>. You must create a concrete driver

    75 adapter class that implements all the pure virtual functions of <xref href="GUID-1E407D78-0FD3-30F2-BDC5-B531F34D4A27.dita"><apiname>CDirectGdiDriverInternal</apiname></xref>.

    76 This driver adapter is a singleton class. A single instance can be created

    77 for each process or each thread that uses the DirectGDI API, depending on

    78 your requirements. The driver adapter is responsible for creating and destroying

    79 drawing engines, and creating and destroying implementations of <xref href="GUID-66A0A534-7BB6-304F-9A5E-17A125DA916F.dita"><apiname>RDirectGdiDrawableSource</apiname></xref> and <xref href="GUID-8F7C2E3C-3DF6-3C76-85C0-04922A99E9D0.dita"><apiname>RDirectGdiImageTarget</apiname></xref>. </p> <p> <b>Engine adapter</b>. You must create a concrete engine adapter

    80 class that implements the <xref href="GUID-97E3E8DD-A2DA-3961-96E3-41AEAFFDD275.dita"><apiname>MDirectGdiEngine</apiname></xref> interface. A

    81 concrete engine adapter instance is created for each instance of <xref href="GUID-09AFDE10-489E-3215-B821-DE7B2D31A007.dita"><apiname>CDirectGdiContext</apiname></xref>.

    82 The engine adapter performs the actual drawing and blitting routines that

    83 enable rendering to an <xref href="GUID-8F7C2E3C-3DF6-3C76-85C0-04922A99E9D0.dita"><apiname>RDirectGdiImageTarget</apiname></xref> instance.

    84 Because DirectGDI is a replacement for BitGDI, the behaviour of the engine

    85 adapter must match the behaviour of BitGDI as far as possible. If an exact

    86 match is not possible, the behaviour must be as close as possible. </p> <p>In

    87 addition, you must create implementations of adaptation-specific resources

    88 that correspond to the following handle classes: </p> <ul>

    89 <li id="GUID-7E672B36-9E55-5DB2-9C18-75C065B99F08"><p> <xref href="GUID-8F7C2E3C-3DF6-3C76-85C0-04922A99E9D0.dita"><apiname>RDirectGdiImageTarget</apiname></xref>  </p> </li>

    90 <li id="GUID-5EEF64D2-B049-56DA-8411-104B3F726C4F"><p> <xref href="GUID-66A0A534-7BB6-304F-9A5E-17A125DA916F.dita"><apiname>RDirectGdiDrawableSource</apiname></xref>  </p> </li>

    91 </ul> </section>

    92 <section id="GUID-456AD066-04AC-42E5-853F-7C581B72402A"><title>Extension interfaces</title> <p>The <xref href="GUID-0C7CD826-95FD-3DD2-9394-3A20316C9C61.dita#GUID-0C7CD826-95FD-3DD2-9394-3A20316C9C61/GUID-B1BFB404-4778-32FD-80B6-E909FE9E5687"><apiname>CDirectGdiDriver::GetInterface()</apiname></xref> function provides an optional mechanism for DirectGDI adaptations to extend

    93 the HAI by defining extension interfaces. The DirectGDI client can access

    94 these by using the <xref href="GUID-0C7CD826-95FD-3DD2-9394-3A20316C9C61.dita#GUID-0C7CD826-95FD-3DD2-9394-3A20316C9C61/GUID-B1BFB404-4778-32FD-80B6-E909FE9E5687"><apiname>CDirectGdiDriver::GetInterface()</apiname></xref> method. </p> </section>

    95 <section id="GUID-AF6C6E59-16F4-4BBE-A59B-6EDF1C2748AC"><title>Performance

    96 considerations</title> <p>Sometimes the requirements of graphics hardware

    97 mean that images and glyphs must be converted from one format to another (for

    98 example, from <xref href="GUID-683A1D42-2764-3EB7-BD19-9E12559199AB.dita"><apiname>CFbsBitmap</apiname></xref> to <codeph>VGImage</codeph>) every

    99 time they are drawn. In these circumstances, you may want to consider introducing

   100 a caching mechanism to store the converted images and glyphs in order to reduce

   101 unnecessary format conversions. </p> </section>

   102 <section id="GUID-CD79B79F-5566-40E5-BB73-693BA8F95EBC"><title>Conformance

   103 testing</title> <p>DirectGDI should produce output that is comparable to BitGDI.

   104 You can test your DirectGDI adaptation by using the DirectGDI test suite.

   105 This compares test images created using all of the <xref href="GUID-40D3BA6E-24FB-34AD-99D0-1119458C1E7F.dita"><apiname>CDirectGDIContext</apiname></xref> APIs

   106 with those generated using BitGDI. Fine tuning the adaptation to match the

   107 BitGDI reference images as closely as possible ensures a continued look and

   108 feel. </p> </section>

   109 </conbody><related-links>

   110 <link href="GUID-CD4B8ECA-AFE7-593C-B095-5D642EA2EC61.dita"><linktext>DirectGDI

   111 Overview</linktext></link>

   112 <link href="GUID-E9C6DBBF-1910-595D-94A1-67664CF7B7A6.dita"><linktext>DirectGDI

   113 Interface Component                 Overview</linktext></link>

   114 <link href="GUID-22E46647-D677-5A47-A7E0-E1E0AE736B27.dita"><linktext>DirectGDI

   115 Adaptation Overview</linktext></link>

   116 </related-links></concept>