Selection of Adaptations

Adaptation naming conventions

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.

By convention, these files have names of the form component_<vendor or feature>.ext, where component is the abbreviated name of the component, <vendor or feature> is the name of the implementer or some identifying feature of the adaptation and .ext is the filename extension.

For example, here is the IBY file for an EGL adaptation. This has the name egl_sw_abc.iby. The sw in the name indicates that the implementation uses a software rather than a hardware solution and abc is the name of the hypothetical implementer.

// 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__

In addition to the adaptation-specific IBY file, each adaptation component has a generic IBY file, which has a name of the form component.iby. For example, the generic IBY file for EGL is called egl.iby.

If you change the name of a DLL during the ROM building process, use the LINKAS statement in the MMP file to specify the required adaptation name. For example:

TARGET      libegl_sw_abc.dll
TARGETTYPE  DLL
LINKAS      libEGL.dll
...

Component-specific macros

The selection of adaptations for inclusion in a ROM involves component-specific macros. These macros have names of the form COMPONENT_DRV, where COMPONENT is the abbreviated component name and _DRV indicates that it refers to an adaptation or driver. The following table lists the adaptation components and their corresponding macros.

These macros are defined in a central file called graphics_adaptation.hby, which is exported from the Common Graphics Header component. The .hby filename extension indicates that it is a header file for inclusion in OBEY files. OBEY files that use these macros must #include this HBY file like this.

#include <graphics_adaptation.hby>

The HBY file assigns the name of one of the Symbian adaptation's IBY file to each of these macros. For example:

#define EGL_DRV <egl_sw_abc.iby>

Each component's generic IBY file includes the component's macro. For example, here is the generic EGL IBY file:

// egl.iby
            
#ifndef __EGL_IBY__
#define __EGL_IBY__
        
#include <graphics_adaptation.hby>
#include EGL_DRV
        
#endif

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.

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.

Selecting a custom adaptation

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 #define in graphics_adaptation.hby.

Specifying the custom adaptation in the OBY file

To select a specific custom adaptation, #define the component's macro in the OBY file for the ROM build. For example:

#define EGL_DRV <egl_sw_abc.iby>

This is the recommended way of specifying custom adaptations.

Specifying the custom adaptation on the Command Line

To select a custom adaptation on the Command Line, specify the custom adaptation's IBY file in the BUILDROM command as follows:

BUILDROM ... –DCOMPONENT_DRV="^<"component_adaptation.iby"^>" ... 

Where COMPONENT_DRV is the name of the macro and component_adaptation.iby is the name of the custom adaptation's IBY file. The ^ character is required to escape the < and > characters.

Here is an example:

-DEGL_DRV="^<"egl_sw_abc.iby"^>"

This overrides the default value set out in graphics_adaptation.hby. You can override multiple components on the Command Line. However, configuring the OBY file as explained above is the preferred approach.

Configurations

Symbian provides named configurations to simplify the selection of adaptations for a particular environment. The named configurations are shown in the following table.

You can select a configuration at ROM build time by using the SYMBIAN_GRAPHICS_ADAPTATION macro. For example:

BUILDROM ... –DSYMBIAN_GRAPHICS_ADAPTATION=SGA_SW ...

You can use this macro in conjunction with the SYMBIAN_GRAPHICS_USE_OPENWF macro (which is described in Enabling the Graphics Architecture Variants).

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 .iby characters have been omitted to save space.

The following table shows the equivalent information for the non-ScreenPlay configuration.