EGL Porting Guide

Required functionality

The implementation DLL must implement:

• All of the standard functions declared in the EGL Interface component.

• The EGL Reusable Sync Extension if OpenWF Composition is in use.

• The EGL Resource Profiling Extension which can be used to retrieve GPU resource utilization information.

Any implementation-specific functions can be included in the DLL or placed into a separate DLL.

Symbian implementations must use the following native type interpretations for compatibility. Window and pixmap types are actually defined as void* to avoid compilation problems for C programs. However, the native types specified must be used, because pointers are cast to these types within the implementation.

For information about implementing window surfaces and pixmaps, see:

• Window Surface Implementation
• Pixmap Implementation

Warning

Implementations of the EGL APIs must not open a session (RFbsSession) with the Font and Bitmap Server because this can lead to a deadlock caused by the Font and Bitmap Server's dependence on EGL. Therefore within the implementation of the EGL APIs:

• Do not call RWsSession::Connect() to create a session to the Window Server because this automatically creates an RFbsSession.

• Do not call any of the Font and Bitmap Server APIs except on a CFbsBitmap object that has been passed into the function as an argument.

Library file

The EGL implementation must not deliver the libEGL.lib file, because it is provided by the EGL Interface component. To prevent a LIB file being automatically generated, place the NOEXPORTLIBRARY directive in the MMP project file that builds the implementation DLL.

The LIB file delivered by the EGL Interface component has only EGL standard functions and no implementation-specific functions. This is to ensure that client programs do not link to implementation-specific functions and so are portable across EGL implementations.

EGL version variability point

The EGL Interface component provides header files for EGL 1.2, 1.3 and 1.4. The EGL 1.4 headers are used by default. However, there is a variability point that can be used to change the header version. This allows a staged migration from one version to the next.

The variability point consists of adding one of the following #define identifiers to the eglheaders.mmh file:

• SYMBIAN_EGLHEADERS_API_VERSION_1_4
• SYMBIAN_EGLHEADERS_API_VERSION_1_3
• SYMBIAN_EGLHEADERS_API_VERSION_1_2

The eglheaders.mmh file is #included in the EGL Interface component's bld.inf and egllib.mmp files.

Ordinal reservation

Symbian has adopted an ordinal reservation scheme for EGL in order to maximize extensibility while minimizing compatibility problems. The scheme is shown in the following table.

The following diagram illustrates a typical ordinal usage scenario.

Figure 1. Typical EGL ordinal usage scenario

Note the following:

• The DEF file for the EGL Interface uses ordinal position entry points 2-249.

• The TARGETTYPE keyword is set to IMPLIB in the EGL Interfaces's MMP file to indicate that only a LIB file is to be generated.

• The DEF file for the EGL implementation uses the full range of ordinal position entry points.

• The NOEXPORT keyword is used in the implementation's MMP file to suppress the generation of a LIB file.

• The TARGETTYPE keyword is set to DLL in the implementation's MMP file to indicate that it is a DLL project.

Internal functions

The LIB file that the EGL Interface component produces is used to access the public methods of libEGL.dll. However, the DLL also has private methods. Sometimes internal access to these private methods is required—for example, by the implementation of an EGL client rendering API, such as OpenVG.

When access to the private methods is required, it is recommended that the EGL implementation provides a separate private LIB file containing the internal API calls. This private LIB file works in a similar way to the public one in that it does not create a DLL. Appropriate clients can then link to the private LIB file when required. Applications should use the public LIB file to access the public methods of the EGL DLL.

This mechanism ensures that normal clients never see the internal API calls and avoids tight coupling with a specific implementation.

Figure 2. EGL implementation's private LIB file

Note the following:

• The DEF file for the private interface uses ordinal position entry points 1 and 250-499.

• The TARGETTYPE keyword is set to IMPLIB in the private interface's MMP file to indicate that only a LIB file is to be generated.

• The LINKAS keyword is used in the private interface's MMP file to indicate that it is to work with libEGL.dll.

Extension functions

If an EGL implementation provides an extension to EGL, clients must use the standard EGL function eglGetProcAddress() to access that functionality. This mechanism allows client programs to access the extension function without the need to expose the function through the DEF file.

UIDs

The Symbian platform libraries are given unique identifiers when they are built. The following UIDs have been allocated for EGL implementations:

The UIDs are provided in egluids.hrh, which is provided in the EGL Interface component.

Platform security

From Symbian OS v9.0 onwards, platform security must be considered. Essentially this requires adding the following lines to the MMP file:

CAPABILITY All –Tcb 
VENDORID <your vendor id in hex> 

ROM building

Building a ROM image for a target platform involves using IBY files. There is a generic IBY file called egl.iby for the EGL implementation. This must not be replaced. However, you can create an implementation-specific IBY file. This should have a unique name with the format egl_adaptation.iby, where adaptation is replaced by the vendor's name. For example:

// EGL_VENDOR.IBY
    
#ifndef __EGL_VENDOR_IBY__
#define __EGL_VENDOR_IBY__
    
REM EGL Vendor implementation
    
file=ABI_DIR/BUILD_DIR/libegl_vendor.dll                 /sys/bin/libEGL.dll
    
#endif

This IBY file must be exported by the bld.inf file to the /epoc32/rom/include/ folder.

You can include this implementation-specific IBY file in a device ROM configuration file by adding the following line to a top-level OBY file like this:

#define EGL_DRV <egl_vendor.iby>

This is the preferred method. However, an alternative is to specify the IBY on the BUILDROM command line like this:

BUILDROM ... –DEGL_DRV="^<"EGL_vendor.iby"^>" ... 

Notice that the ^ character is used as an escape character for the < and > characters.

See Selection of Adaptations for more information.

Project files

Here is an example MMP file:

#include "/epoc32/include/platform/egl/egluids.hrh" // For UIDs
     
// These statements are always required: 
target          libEGL.dll             // Destination filename
targettype      dll                    // Binary build type
uid             KUidSharedDllUidValue KUidEGLDllUidValue       // File UIDs
capability      All –Tcb               // Platform Security requirement
vendorid        <Your vendor ID in hex>
NOEXPORTLIBRARY                        // Suppress generation of LIB/DSO file
DEFFILE         libegl13.def
         
// These statements are examples and may vary:
userinclude     ../include             // Local include files
systeminclude   /epoc32/include        // Symbian include files
    
sourcepath      ../egl                 // Relative path to source files
    
source          context.cpp            // Source files
source          display.cpp
source          egl.cpp
source          surface.cpp
    
library         euser.lib              // For the user library.
library         fbscli.lib             // For CFbsBitmap, etc.
library         bitgdi.lib             // For CFbsBitmapDevice, CFbsBitGc, etc.
library         ws32.lib               // For RWindow, Direct Screen Access, etc.

Example bld.inf

A bld.inf file is also required:

PRJ_PLATFORMS
DEFAULT      
    
PRJ_EXPORTS
egl_vendor.iby       /epoc32/rom/include/egl_vendor.iby
      
PRJ_MMPFILES
./egl.mmp