EGL +Porting Guide

Target audience: Device creators.

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.

+ + + +OpenGL ES type +Native type +Defined type + + + + +EGLNativeDisplayType +int +int + + +EGLNativeWindowType +RWindow * +void* + + + +EGLNativePixmapType +CFbsBitmap * +void* + + + +

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.

+ + + +Ordinals +Description +Owner + + + + +

Reserved for use by implementations.

EGL implementer

+ + +

2…249

Reserved for the EGL Interface component to use for the standard +functions that are defined in the EGL specification. In order to avoid future +binary compatibility issues, do not use these in your implementation.

Symbian

+ + +

250…499

Reserved for use by implementations.

EGL implementer

+ + + +

The following diagram illustrates a typical ordinal usage scenario.

+ 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.

+ 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:

+ + + +Library + UID2 +UID3 + + + + +EGL +0x1000008d +0x10281AB8 + + + +

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