OpenGL ES Porting Guide

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:

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:

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