OpenGL ES Porting Guide

Variant: ScreenPlay and non-ScreenPlay. Target audience: Device creators.

Required functionality

The implementation DLL must implement all of the standard functions declared in the OpenGLES Interface component and optionally any implementation-specific functions. Alternatively, implementation-specific functions can be placed into a separate DLL.

In order to avoid future binary compatibility issues, the reserved ordinal entry points are reserved for new functions introduced into the specification. Therefore you must not use them for implementation-specific functions.

LIB files

The OpenGL ES implementation must not deliver the LIB files, because they are provided by the OpenGLES Interface component and are part of the interface declaration and not its implementation. To prevent LIB files being automatically generated, place the NOEXPORTLIBRARY directive in the MMP project file that builds the implementation DLL.

The LIB files delivered in the OpenGLES Interface component have only OpenGL ES 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 OpenGL ES implementations.

Extension functions

An OpenGL ES implementation can optionally provide extension functions. When you add an extension function, if possible do not add new exports to the OpenGL ES library, because this means you must also add them to the DEF file. This may lead to an ordinal conflict and therefore a compatibility break for clients in the future—for example, if the specification introduces new functions and these are added to the DEF file at the same ordinal position.

Clients can use the standard EGL function eglGetProcAddress() to access the extension functionality instead. If function exports cannot be avoided, place them in a separate library so that they can have their own DEF file. If required, this can be linked to the OpenGL ES implementation so that eglGetProcAddress() can also return the address.

glQueryMatrixxOES

The glQueryMatrixxOES() extension function is an exception to this rule. It has been explicitly added to the OpenGL ES 1.0 and 1.1 DEF files (openglesu.def and opengles11u.def, respectively. This function is therefore expected to be present, even if stubbed out, in implementations of OpenGL ES 1.0 and 1.1. However, this approach has changed in OpenGL ES 1.1 v1. This entry is not present in libglesv1_cm11u.def and eglGetProcAddress() should be used instead to call the glQueryMatrixxOES() extension.

Note that the glQueryMatrixxOES() extension has been deprecated in OpenGL ES 1.1. Instead you can get the various matrices by calling GetFixedv() or GetFloatv(), or by using the OES_matrix_get() core extension.

Internal functions

Sometimes internal access to the OpenGL ES implementation is required—for example, in a bench marking or regression test for the OpenGL ES implementation. To avoid tight coupling with a specific implementation in these circumstances, it is recommended that the OpenGL ES implementation provides a separate vendor-specific LIB file containing the internal API calls. Then appropriate clients can link to that internal LIB file when required. This mechanism ensures that normal clients never see the internal API calls.

UIDs

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

Library UID2 UID3

OpenGL ES 1.1 v1 Common Profile

0x1000008d

0x102836BE

OpenGL ES 1.1 Common Profile

0x1000008d

0x101FCABD

OpenGL ES 1.1 Common-Lite Profile

0x1000008d

0x101FCAE8

OpenGL ES 2.0

0x1000008d

0x10285A7A

ROM building

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

// OPENGLES_VENDOR.IBY + +#ifndef __OPENGLES_VENDOR_IBY__ +#define __OPENGLES_VENDOR_IBY__ + +REM OpenGL ES implementation + +// Includes the EGL entry points. +file=ABI_DIR/BUILD_DIR/libGLES_CM.dll sys/bin/libGLES_CM.dll + +// Does NOT include the EGL entry points. +file=ABI_DIR/BUILD_DIR/libGLESv1_CM.dll sys/bin/libGLESv1_CM.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 OPENGLES_DRV <opengles_vendor.iby>

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

BUILDROM ... –DOPENGLES_DRV="^<"opengles_vendor.iby"^>" ...

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

See Selection of Adaptations for more information.

Project file macros

When providing an implementation of OpenGL ES (rather than merely using OpenGL ES), the header files must be included in such a way that the functions are declared as exported symbols (rather than imported symbols). This is a distinction seen at link-time. To achieve this, place the following macros in the implementation's MMP file:

OpenGL ES API MMP Project File Macro

OpenGL ES 1.X

MACRO __GL_EXPORTS

OpenGL ES 2.0

MACRO SYMBIAN_OGLES_DLL_EXPORTS

Example project (MMP) file

Here is an example MMP file:

#include "/epoc32/include/platform/GLES/openglesuids.hrh" // For uids + +// These statements are always required: +target libGLES_CM.dll // Destination filename +targettype dll // Binary build type +capability All -TCB // Platform Security requirement +uid KUidSharedDllUidValue KUidOpenGLESCommonProfileDllUidValue +vendorid <your vendor id in hex> +noexportlibrary // Suppress generation of LIB/DSO file +DEFFILE opengles.def + +macro __GL_EXPORTS + +// These statements are examples and may vary: +userinclude ../include // Local include files +systeminclude /epoc32/include // General Symbian include files + +sourcepath ../opengles // Relative path to source files + +source context.cpp // Source files +source display.cpp +source egl.cpp +source surface.cpp + +library euser.lib +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 file

The bld.inf file specifies the exports and the MMP files. For example:

PRJ_PLATFORMS +DEFAULT + +PRJ_EXPORTS +opengles_vendor.iby /epoc32/rom/include/opengles_vendor.iby + +PRJ_MMPFILES +./opengles.mmp