EGL Reference Implementation Component

Implemented APIs

The EGL Reference Implementation implements the following EGL 1.4 APIs:

• eglGetError()
• eglGetDisplay()
• eglInitialize()
• eglTerminate()
• eglReleaseThread()
• eglQueryString()
• eglGetProcAddress()

The EGL Reference Implementation also implements the following reusable sync extension functions:

• eglCreateSyncKHR()
• eglDestroySyncKHR()
• eglClientWaitSyncKHR()
• eglSignalSyncKHR()
• eglGetSyncAttribKHR()

The Reference Implementation implements eglGetProcAddress() , which supports retrieving OpenWF-C extension functions.

Calling any of the unsupported APIs panics the client with the EEglPanicNotSupported panic code and the return value and EGL error code are undefined. This behavior deliberately does not conform to the EGL specification. It is intended to make it easy to detect errors in the platform configuration—for example, where the intention was to use a fully-functional EGL implementation instead of the Reference Implementation.

Implementation-specific information

The Reference Implementation returns the following implementation-specific strings:

Private signaling function

Both applications and middleware APIs, such as OpenWF-C may need to signal on the EGL sync object. However, once the middleware API calls the standard eglSignalSyncKHR() signaling function and obtains the error code using eglGetError(), the error code is not available to the application.

The EGL reference implementation therefore has the following private signaling function, which returns the error code instead of generating an EGL error. This enables the OpenWF implementation to signal the sync object and get the error code without setting the EGL error. This means that from the application level, the normal EGL error behavior is maintained.

EGLint egl_Private_SignalSyncNOK(
              EGLDisplay dpy,
              EGLSyncKHR sync,
              EGLenum mode)

The extension name of this private signal function is EGL_NOK__private__signal_sync, which can be obtained using eglQueryString().

When the same vendor implements both EGL and OpenWF-C, the vendor might implement a different solution.

Thread handling

The Reference Implementation allows the supported EGL APIs to be used from multiple threads within the same process. The Reference Implementation maintains the process and thread state in order to conform to the correct behavior described in the EGL specification. Access to process-wide objects is serialized and protected by mutex to prevent race conditions.

The Reference Implementation uses its own heap to allow the creation, access and destruction of process-wide objects from any thread. This includes the EGLDisplay and EGLSync objects. The heap is created in a local chunk.

For simplicity, the Reference Implementation supports only one display: EGL_DEFAULT_DISPLAY. A request to obtain any other EGLDisplay returns EGL_NO_DISPLAY. EGLDisplay is a process-wide resource that can be accessed from any thread. Its behavior follows the EGL specification for eglGetDisplay(), eglInitialize() and eglTerminate().

Each client thread can have its own EGL error. Error handling and thread state management follows the EGL specification for eglGetError() and eglReleaseThread().

DLL summary

To allow different EGL implementations to be used on a platform, the Reference Implementation is built with a target name of libegl_ref.dll. However, EGL Clients should link their code against libEGL.lib.

Enabling the EGL Reference Implementation

Emulator

To enable the ScreenPlay OpenWF-C components and the EGL Reference Implementation in the emulator, add the following lines to the \epoc32\data\epoc.ini file:

SYMBIAN_GRAPHICS_USE_OPENWF
SYMBIAN_GRAPHICS_USE_EGL_REF

PlatSim and Hardware

To build the EGL Reference Implementation component in the ROM image for PlatSim or other hardware platforms, use the following arguments to the buildrom command:

buildrom -DSYMBIAN_GRAPHICS_USE_OPENWF -DSYMBIAN_GRAPHICS_USE_EGL_REF ...

Existing ROM build tools have a mechanism to select a specific EGL implementation in a ROM image and rename it to libEGL.dll. The generic egl.iby file which is part of EGL interface component uses the EGL_DRV macro to perform the selection. For more information, refer to Selection of Adaptations.