<?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-946E64D6-3E5D-5264-AD5D-29D3AD296543" xml:lang="en"><title>Selection

of Adaptations</title><shortdesc>The Graphics package contains a number of adaptation and customization

components. These are called <b>adaptations</b> in this topic. Symbian provides

implementations of these components. However, device creators can create their

own implementations—for example, to take advantage of the specific hardware

that is available in a particular device. This topic describes how to select

adaptations for inclusion in a ROM. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

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

<section id="GUID-2E93EB5D-5060-4E73-8B93-A6C0D7742AB7"><title>Adaptation

naming conventions</title> <p>Adaptations must have a specific name in the

ROM. The mechanism for selecting adaptations is based on the assumption that

all Symbian and non-Symbian adaptations have unique names and are renamed

to the required adaptation name during the ROM build process. This means that

all adaptation DLL, EXE and IBY files must have unique names. </p> <p>By convention,

these files have names of the form <codeph>component_&lt;vendor or feature&gt;.ext</codeph>,

where <codeph>component</codeph> is the abbreviated name of the component, <codeph>&lt;vendor

or feature&gt;</codeph> is the name of the implementer or some identifying feature

of the adaptation and <codeph>.ext</codeph> is the filename extension. </p> <p>For

example, here is the IBY file for an EGL adaptation. This has the name <filepath>egl_sw_abc.iby</filepath>.

The <filepath>sw</filepath> in the name indicates that the implementation

uses a software rather than a hardware solution and <filepath>abc</filepath> is

the name of the hypothetical implementer. </p> <codeblock id="GUID-1172A380-EEF2-5A1D-89DA-D503CBDC16D2" xml:space="preserve">// egl_sw_abc.iby

#ifndef __EGL_SW_ABC_IBY__

#define __EGL_SW_ABC_IBY__

file=ABI_DIR\BUILD_DIR\libegl_sw_abc.dll                 \sys\bin\libEGL.dll

#include <graphicsresource.iby>

#endif // __EGL_SW_ABC_IBY__

</codeblock> <p>In addition to the <b>adaptation-specific</b> IBY file, each

adaptation component has a <b>generic</b> IBY file, which has a name of the

form <filepath>component.iby</filepath>. For example, the generic IBY file

for EGL is called <filepath>egl.iby</filepath>. </p> <p>If you change the

name of a DLL during the ROM building process, use the <codeph>LINKAS</codeph> statement

in the MMP file to specify the required adaptation name. For example: </p> <codeblock id="GUID-74500A23-C098-5481-B512-583B63512610" xml:space="preserve">TARGET      libegl_sw_abc.dll

TARGETTYPE  DLL

LINKAS      libEGL.dll

...</codeblock> </section>

<section id="GUID-70CE663F-3B37-4654-BD21-E7B6CB848356"><title>Component-specific

macros</title> <p>The selection of adaptations for inclusion in a ROM involves

component-specific macros. These macros have names of the form <codeph>COMPONENT_DRV</codeph>,

where <codeph>COMPONENT</codeph> is the abbreviated component name and <codeph>_DRV</codeph> indicates

that it refers to an adaptation or driver. The following table lists the adaptation

components and their corresponding macros. </p> <table id="GUID-1E1802AD-D786-5BBD-9180-FC3F4A43A27F">

<tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/>

<thead>

<row>

<entry>Component</entry>

<entry>Macro</entry>

</row>

</thead>

<tbody>

<row>

<entry><xref href="GUID-BB4F5388-32EA-5A2E-845D-E5339D2040E9.dita">DirectGDI Adaptation</xref> </entry>

<entry><codeph>DIRECTGDI_DRV</codeph> </entry>

</row>

<row>

<entry><xref href="GUID-DC3A8785-3ED3-5696-A5ED-AB66588A5C14.dita">EGL Implementation</xref> </entry>

<entry><codeph>EGL_DRV</codeph> </entry>

</row>

<row>

<entry><xref href="GUID-E6E6A439-B3CC-5FEA-9148-2DB5F37003F2.dita">Extended Bitmap

Rasterizer Plug-in</xref> </entry>

<entry><codeph>FBSRASTERIZER_DRV</codeph> </entry>

</row>

<row>

<entry><xref href="GUID-5E46C0EE-BD7D-5C85-8083-575BB2888AA7.dita">Graphics Resource

Adaptation</xref>  </entry>

<entry><codeph>GRAPHICSRESOURCE_DRV</codeph> </entry>

</row>

<row>

<entry><xref href="GUID-7DD1BC7B-B3F7-515D-8DC8-B699B947B434.dita">OpenGLES Implementation</xref> </entry>

<entry><codeph>OPENGLES_DRV</codeph>  </entry>

</row>

<row>

<entry><xref href="GUID-20419A98-3787-5F10-9CAD-2BC5D7560776.dita">OpenVG Implementation</xref>  </entry>

<entry><codeph>OPENVG_DRV</codeph> </entry>

</row>

<row>

<entry><xref href="GUID-8BEE0411-C6E9-5840-BE22-EC271A4D97DD.dita">OpenWF Composition

Implementation</xref></entry>

<entry><codeph>OPENWFCLIB_DRV</codeph> </entry>

</row>

<row>

<entry><xref href="GUID-C7B420DE-CEDA-5D3F-8095-71136E862CDF.dita">Surface Manager</xref> </entry>

<entry><codeph>SURFACEMANAGER_DRV</codeph> </entry>

</row>

<row>

<entry><xref href="GUID-81A0A2E9-4BB9-58BF-B2D3-08098E7E9C7C.dita">Surface Update

Server</xref> </entry>

<entry><codeph>SURFACEUPDATE_DRV</codeph> </entry>

</row>

</tbody>

</tgroup>

</table> <p>These macros are defined in a central file called <filepath>graphics_adaptation.hby</filepath>,

which is exported from the Common Graphics Header component. The <filepath>.hby</filepath> filename

extension indicates that it is a header file for inclusion in OBEY files.

OBEY files that use these macros must <codeph>#include</codeph> this HBY file

like this. </p> <codeblock id="GUID-B118E007-2AE3-5267-BC8C-3EDBB386F04A" xml:space="preserve">#include &lt;graphics_adaptation.hby&gt;</codeblock> <p>The

HBY file assigns the name of one of the Symbian adaptation's IBY file to each

of these macros. For example: </p> <codeblock id="GUID-CA1400A1-159D-5460-9CED-C9EB45BF7BC6" xml:space="preserve">#define EGL_DRV &lt;egl_sw_abc.iby&gt;</codeblock> <p>Each

component's generic IBY file includes the component's macro. For example,

here is the generic EGL IBY file: </p> <codeblock id="GUID-DF7F660B-5A6E-58DE-B53B-6138E3D6CEAB" xml:space="preserve">// egl.iby

#ifndef __EGL_IBY__

#define __EGL_IBY__

#include <graphics_adaptation.hby>

#include EGL_DRV

#endif</codeblock> <p>To select a custom adaptation simply redefine the relevant

macro to specify the custom adaptation IBY file. You can do this in the OBY

file for the ROM build or on the ROMBUILD command line as described next. </p> <p>Symbian

also provides a number of named configurations to simplify the selection of

a set of Symbian adaptations for a particular environment. These named configurations

are described below. </p> </section>

<section id="GUID-3D02BA62-F9C9-4B57-902E-39D6728CA5E9"><title>Selecting

a custom adaptation</title> <p>Selecting a custom adaptation involves defining

the adaptation component's macro to specify the filename of the custom adaptation's

IBY file. The preferred way of doing this is in the OBY file. However, it

is also possible to do it on the ROMBUILD command line. Both methods override

the corresponding <codeph>#define</codeph> in <filepath>graphics_adaptation.hby</filepath>. </p> <p><b>Specifying

the custom adaptation in the OBY file </b> </p> <p>To select a specific custom

adaptation, <codeph>#define</codeph> the component's macro in the OBY file

for the ROM build. For example: </p> <codeblock id="GUID-8C1738C3-B9A8-5449-B0D4-89AC1BAB7ECA" xml:space="preserve">#define EGL_DRV &lt;egl_sw_abc.iby&gt;</codeblock> <p>This is the recommended way of specifying custom adaptations. </p> <p><b>Specifying

the custom adaptation on the Command Line </b> </p> <p>To select a custom

adaptation on the Command Line, specify the custom adaptation's IBY file in

the BUILDROM command as follows: </p> <codeblock id="GUID-D2020015-B7E8-5E2C-9AC0-73A09FA78264" xml:space="preserve">BUILDROM ... –DCOMPONENT_DRV="^&lt;"component_adaptation.iby"^&gt;" ... 

</codeblock> <p>Where <codeph>COMPONENT_DRV</codeph> is the name of the macro

and <filepath>component_adaptation.iby</filepath> is the name of the custom

adaptation's IBY file. The ^ character is required to escape the < and

&gt; characters. </p> <p>Here is an example: </p> <codeblock id="GUID-4FF32002-4665-500A-A5A5-465EED6EC824" xml:space="preserve">-DEGL_DRV="^&lt;"egl_sw_abc.iby"^&gt;"</codeblock> <p>This overrides the default value set out in <filepath>graphics_adaptation.hby</filepath>.

You can override multiple components on the Command Line. However, configuring

the OBY file as explained above is the preferred approach. </p> </section>

<section id="GUID-F4A3FFFF-7A5C-40AF-8CA2-25AD82950D58"><title>Configurations</title><p>Symbian

provides named configurations to simplify the selection of adaptations for

a particular environment. The named configurations are shown in the following

table. </p> <table id="GUID-4633D949-513D-5A47-985A-3F88F9A67CDE">

<tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/>

<thead>

<row>

<entry>Configuration</entry>

<entry>Description</entry>

</row>

</thead>

<tbody>

<row>

<entry><p> <codeph>SGA_CLASSIC</codeph>  </p> </entry>

<entry><p>Non-ScreenPlay environment. Used by default for non-ScreenPlay. </p> </entry>

</row>

<row>

<entry><p> <codeph>SGA_SW</codeph>  </p> </entry>

<entry><p>ScreenPlay environment using software-based adaptations. Used by

default for ScreenPlay. </p> </entry>

</row>

<row>

<entry><p> <codeph>SGA_SW_NO_GRAPHICSRESOURCE</codeph>  </p> </entry>

<entry><p>ScreenPlay environment using software-based adaptation and stubbed-out

Graphics Resource and DirectGDI adapters. </p> </entry>

</row>

</tbody>

</tgroup>

</table><p>You can select a configuration at ROM build time by using the <codeph>SYMBIAN_GRAPHICS_ADAPTATION</codeph> macro.

For example: </p> <codeblock id="GUID-FAE4A161-B77B-5AEE-AB00-1F195587CCA5" xml:space="preserve">BUILDROM ... –DSYMBIAN_GRAPHICS_ADAPTATION=SGA_SW ...</codeblock> <p>You

can use this macro in conjunction with the <codeph>SYMBIAN_GRAPHICS_USE_OPENWF</codeph> macro

(which is described in <xref href="GUID-6D8A1FC7-095B-587E-8274-23C132978C53.dita">Enabling

the Graphics Architecture Variants</xref>). </p> <p>These configurations select

adaptations by specifying the adaptation IBY files to use. The following table

shows the macro names for the relevant ScreenPlay components and the corresponding

IBY file for each of the ScreenPlay configurations. The trailing <filepath>.iby</filepath> characters

have been omitted to save space. </p> <table id="GUID-0BFCC648-77CF-59FF-B811-C1705B9114D1">

<tgroup cols="3"><colspec colname="col0"/><colspec colname="col1"/><colspec colname="col2"/>

<thead>

<row>

<entry>Macro</entry>

<entry><codeph>SGA_SW</codeph> </entry>

<entry><codeph>                 SGA_SW_NO_GRAPHICSRESOURCE</codeph> </entry>

</row>

</thead>

<tbody>

<row>

<entry><p> <codeph>SURFACEMANAGER_DRV</codeph>  </p> </entry>

<entry><p> <filepath>surfacemanager_ref</filepath>  </p> </entry>

<entry><p> <filepath>surfacemanager_ref</filepath>  </p> </entry>

</row>

<row>

<entry><p> <codeph>SURFACEUPDATE_DRV</codeph>  </p> </entry>

<entry><p> <filepath>surfaceupdate_ref</filepath>  </p> </entry>

<entry><p> <filepath>surfaceupdate_ref</filepath>  </p> </entry>

</row>

<row>

<entry><p> <codeph>GRAPHICSRESOURCE_DRV</codeph>  </p> </entry>

<entry><p> <filepath>graphicsresourceadapter_sw</filepath>  </p> </entry>

<entry><p> <filepath>N/A</filepath>  </p> </entry>

</row>

<row>

<entry><p> <codeph>DIRECTGDI_DRV</codeph>  </p> </entry>

<entry><p> <filepath>directgdiadapter_sw</filepath>  </p> </entry>

<entry><p> <filepath>N/A</filepath>  </p> </entry>

</row>

<row>

<entry><p> <codeph>EGL_DRV</codeph>  </p> </entry>

<entry><p> <filepath>egl_ref.iby</filepath>  </p> </entry>

<entry><p> <filepath>egl_ref.iby</filepath>  </p> </entry>

</row>

<row>

<entry><p> <codeph>OPENGLES_DRV</codeph>  </p> </entry>

<entry><p> <filepath>opengles_sw</filepath>  </p> </entry>

<entry><p> <filepath>opengles_sw</filepath>  </p> </entry>

</row>

<row>

<entry><p> <codeph>OPENVG_DRV</codeph>  </p> </entry>

<entry><p> <filepath>openvg_sw</filepath>  </p> </entry>

<entry><p> <filepath>openvg_sw</filepath>  </p> </entry>

</row>

<row>

<entry><p> <codeph>OPENWFCLIB_DRV</codeph>  </p></entry>

<entry><p> <filepath>openwfc_ref</filepath> </p></entry>

<entry><p> <filepath>openwfc_ref</filepath>  </p></entry>

</row>

<row>

<entry><p> <codeph>FBSRASTERIZER_DRV</codeph>  </p> </entry>

<entry><p> <filepath> fbsrasterizer_stub</filepath>  </p> </entry>

<entry><p> <filepath>fbsrasterizer_stub</filepath>  </p> </entry>

</row>

</tbody>

</tgroup>

</table><p>The following table shows the equivalent information for the non-ScreenPlay

configuration. </p> <table id="GUID-9974BDAA-3FC0-50BC-9BC7-F414035E755B">

<tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/>

<thead>

<row>

<entry>Macro</entry>

<entry><codeph>SGA_CLASSIC</codeph> </entry>

</row>

</thead>

<tbody>

<row>

<entry><p> <codeph>EGL_DRV</codeph>  </p> </entry>

<entry><p> <filepath>egl_sw_nongce</filepath>  </p> </entry>

</row>

<row>

<entry><p> <codeph>OPENGLES_DRV</codeph>  </p> </entry>

<entry><p> <filepath>opengles_sw</filepath>  </p> </entry>

</row>

<row>

<entry><p> <codeph>OPENVG_DRV</codeph>  </p> </entry>

<entry><p> <filepath>openvg_sw</filepath>  </p> </entry>

</row>

<row>

<entry><p> <codeph>FBSRASTERIZER_DRV</codeph>  </p> </entry>

<entry><p> <filepath>fbsrasterizer_stub </filepath>  </p> </entry>

</row>

</tbody>

</tgroup>

</table> </section>

</conbody><related-links>

<link href="GUID-6D8A1FC7-095B-587E-8274-23C132978C53.dita"><linktext>Enabling

the Graphics Architecture                 Variants</linktext></link>

<link href="GUID-EF62BF88-3687-505D-8BD7-EEDF36246E56.dita"><linktext>Graphics

Hardware Acceleration</linktext></link>

</related-links></concept>