<?xml version="1.0" encoding="utf-8"?>

<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->

<!-- This component and the accompanying materials are made available under the terms of the License 

"Eclipse Public License v1.0" which accompanies this distribution, 

and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->

<!-- Initial Contributors:

    Nokia Corporation - initial contribution.

Contributors: 

-->

<!DOCTYPE concept

  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">

<concept id="GUID-FFA5956E-0632-42F5-A2F9-0503888EF72B" xml:lang="en"><title>EGL

Reference Implementation Component</title><shortdesc>The EGL Reference Implementation component implements the minimum

EGL functionality to support OpenWF composition. It does not implement the

EGL functionality required to support the use of the Khronos rendering APIs,

such as OpenGL ES and OpenVG. Typically device creators replace the reference

implementation with a fully functional implementation of their own. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

<p><b>Target audience</b>: Device creators. </p>

<section id="GUID-3400F826-F4A6-4BCA-BF98-9CD941532B8A"><title>Implemented

APIs</title><p>The EGL Reference Implementation implements the following EGL

1.4 APIs: </p><ul>

<li><codeph>eglGetError()</codeph></li>

<li><codeph>eglGetDisplay()</codeph></li>

<li><codeph>eglInitialize()</codeph></li>

<li><codeph>eglTerminate()</codeph></li>

<li><codeph>eglReleaseThread()</codeph></li>

<li><codeph>eglQueryString()</codeph></li>

<li><codeph>eglGetProcAddress()</codeph></li>

</ul><p>The EGL Reference Implementation also implements the following reusable

sync extension functions:</p><ul>

<li><codeph>eglCreateSyncKHR()</codeph></li>

<li><codeph>eglDestroySyncKHR()</codeph></li>

<li><codeph>eglClientWaitSyncKHR()</codeph></li>

<li><codeph>eglSignalSyncKHR()</codeph></li>

<li><codeph>eglGetSyncAttribKHR()</codeph></li>

</ul><p>The Reference Implementation implements <codeph>eglGetProcAddress()</codeph> ,

which supports retrieving OpenWF-C extension functions. </p><p>Calling any

of the unsupported APIs panics the client with the <codeph>EEglPanicNotSupported</codeph> 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.</p></section>

<section id="GUID-264ED891-CB0A-4D6D-8640-8A11A9BD79A5"><title>Implementation-specific

information</title><p>The Reference Implementation returns the following implementation-specific

strings: </p><table id="GUID-EAEA383C-E4ED-4C11-A957-6EFFEECDE6BD">

<tgroup cols="2"><colspec colname="col1"/><colspec colname="col2"/>

<thead>

<row>

<entry valign="top">String</entry>

<entry valign="top">Value</entry>

</row>

</thead>

<tbody>

<row>

<entry>EGL_CLIENT_APIS</entry>

<entry>“”</entry>

</row>

<row>

<entry>EGL_EXTENSIONS</entry>

<entry>“EGL_KHR_reusable_sync”</entry>

</row>

<row>

<entry>EGL_VENDOR</entry>

<entry>“Nokia”</entry>

</row>

<row>

<entry>EGL_VERSION</entry>

<entry>“1.4 Reference EGL”</entry>

</row>

</tbody>

</tgroup>

</table></section>

<section id="GUID-CD9221D3-55FC-479B-A3DE-B28BBF32DAC0"><title>Private

signaling function</title><p>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 <codeph>eglSignalSyncKHR()</codeph> signaling function

and obtains the error code using <codeph>eglGetError()</codeph>, the error

code is not available to the application. </p><p>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.</p><codeblock xml:space="preserve">EGLint egl_Private_SignalSyncNOK(

              EGLDisplay dpy,

              EGLSyncKHR sync,

              EGLenum mode)</codeblock><p>The extension name of this private

signal function is <codeph>EGL_NOK__private__signal_sync</codeph>, which can

be obtained using <codeph>eglQueryString()</codeph>. </p><p>When the same

vendor implements both EGL and OpenWF-C, the vendor might implement a different

solution.</p> </section>

<section id="GUID-8ED3006D-56A3-4512-A1A8-0E88149C236B"><title>Thread handling</title><p>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.</p><p>The Reference Implementation

uses its own heap to allow the creation, access and destruction of process-wide

objects from any thread. This includes the <codeph>EGLDisplay</codeph> and <codeph>EGLSync</codeph> objects.

 The heap is created in a local chunk.</p><p>For simplicity, the Reference

Implementation supports only one display: <codeph>EGL_DEFAULT_DISPLAY</codeph>.

 A request to obtain any other <codeph>EGLDisplay</codeph> returns <codeph>EGL_NO_DISPLAY</codeph>. <codeph>EGLDisplay</codeph> is

a process-wide resource that can be accessed from any thread. Its behavior

follows the EGL specification for <codeph>eglGetDisplay()</codeph>, <codeph>eglInitialize()</codeph> and <codeph>eglTerminate()</codeph>.</p><p>Each

client thread can have its own EGL error. Error handling and thread state

management follows the EGL specification for <codeph>eglGetError()</codeph> and <codeph>eglReleaseThread()</codeph>.</p></section>

<section id="GUID-8B9FB71D-8DC8-4944-9DA8-AEC821C1041D"><title>DLL summary</title><table id="GUID-80E05C78-5FD4-5489-A1DA-A759EB7F9530">

<tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/>

<thead>

<row>

<entry>DLL</entry>

<entry>Description</entry>

</row>

</thead>

<tbody>

<row>

<entry><filepath>libegl_ref.dll</filepath> </entry>

<entry>The EGL reference implementation. </entry>

</row>

<row>

<entry><filepath>libEGL.dll</filepath></entry>

<entry>In the emulator, this provides a mechanism that switches among different

EGL implementation DLLs used in different scenarios, including the Reference

Implementation mentioned above. For ARM builds, the file above is renamed

to this during the ROM build process. This is controlled by IBY files.</entry>

</row>

</tbody>

</tgroup>

</table><p>To allow different EGL implementations to be used on a platform,

the Reference Implementation is built with a target name of <filepath>libegl_ref.dll</filepath>.

However, EGL Clients should link their code against <filepath>libEGL.lib</filepath>.</p></section>

<section id="GUID-0685C8AA-5F35-49B7-BF02-C147BCDCCE89"><title>Enabling the

EGL Reference Implementation</title><p><b>Emulator</b></p><p>To enable the

ScreenPlay OpenWF-C components and the EGL Reference Implementation in the

emulator, add the following lines to the <filepath>\epoc32\data\epoc.ini</filepath> file:</p><codeblock xml:space="preserve">SYMBIAN_GRAPHICS_USE_OPENWF

SYMBIAN_GRAPHICS_USE_EGL_REF</codeblock><p><b>PlatSim

and Hardware</b></p><p>To build the EGL

Reference Implementation component in the ROM image for PlatSim or other hardware

platforms, use the following arguments to the <codeph>buildrom</codeph> command:</p><codeblock xml:space="preserve">buildrom -DSYMBIAN_GRAPHICS_USE_OPENWF -DSYMBIAN_GRAPHICS_USE_EGL_REF ...</codeblock><p>Existing ROM build tools have a mechanism

to select a specific EGL implementation in a ROM image and rename it to <filepath>libEGL.dll</filepath>.

The generic <filepath>egl.iby</filepath> file which is part of EGL interface

component uses the <codeph>EGL_DRV</codeph> macro to perform the selection.

 For more information, refer to <xref href="GUID-946E64D6-3E5D-5264-AD5D-29D3AD296543.dita">Selection

of Adaptations</xref>. </p></section>

</conbody><related-links>

<link href="GUID-DEA883D0-7C53-407A-AC5D-0A3208E667C7.dita">

<linktext>EGL Reusable Sync Extension</linktext></link>

<link href="GUID-A5914CFF-6F86-53E8-9928-36D3379835B1.dita"><linktext>EGL Interface

Overview</linktext></link>

</related-links></concept>