--- a/Symbian3/PDK/Source/GUID-FFA5956E-0632-42F5-A2F9-0503888EF72B.dita Thu Mar 11 15:24:26 2010 +0000
+++ b/Symbian3/PDK/Source/GUID-FFA5956E-0632-42F5-A2F9-0503888EF72B.dita Thu Mar 11 18:02:22 2010 +0000
@@ -1,147 +1,147 @@
-<?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><p><codeph>eglGetError()</codeph></p></li>
-<li><p><codeph>eglGetDisplay()</codeph></p></li>
-<li><p><codeph>eglInitialize()</codeph></p></li>
-<li><p><codeph>eglTerminate()</codeph></p></li>
-<li><p><codeph>eglReleaseThread()</codeph></p></li>
-<li><p><codeph>eglQueryString()</codeph></p></li>
-<li><p><codeph>eglGetProcAddress()</codeph></p></li>
-</ul><p>The EGL Reference Implementation also implements the following reusable
-sync extension functions:</p><ul>
-<li><p><codeph>eglCreateSyncKHR()</codeph></p></li>
-<li><p><codeph>eglDestroySyncKHR()</codeph></p></li>
-<li><p><codeph>eglClientWaitSyncKHR()</codeph></p></li>
-<li><p><codeph>eglSignalSyncKHR()</codeph></p></li>
-<li><p><codeph>eglGetSyncAttribKHR()</codeph></p></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>Signaling is often used by both a third party
-application and its middleware API, such as OpenWF-C. However, once the middleware
-API calls the <codeph>eglSignalSyncKHR()</codeph> standard signaling function
-and obtains the error code using <codeph>eglGetError()</codeph>, the error
-code is not available to the application. </p><p>The following private signaling
-function returns the error without generating the error code. This is an implementation-specific
-function, which gives the OpenWF-C implementation a mechanism for calling
-into the EGL implementation.</p><codeblock xml:space="preserve">EGLint egl_Private_SignalSyncNOK(
- EGLDisplay dpy,
- EGLSyncKHR sync,
- EGLenum mode)</codeblock><p>Generally when the same vendor implements
-both EGL and OpenWF-C, the vendor will implement their own private functions.</p><p><i>Note</i>:
-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> </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><p> <filepath>libegl_ref.dll</filepath> </p> </entry>
-<entry><p>The EGL reference implementation.</p> </entry>
-</row>
-<row>
-<entry><p><filepath>libEGL.dll</filepath></p></entry>
-<entry><p>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. </p></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>
+<?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><p><codeph>eglGetError()</codeph></p></li>
+<li><p><codeph>eglGetDisplay()</codeph></p></li>
+<li><p><codeph>eglInitialize()</codeph></p></li>
+<li><p><codeph>eglTerminate()</codeph></p></li>
+<li><p><codeph>eglReleaseThread()</codeph></p></li>
+<li><p><codeph>eglQueryString()</codeph></p></li>
+<li><p><codeph>eglGetProcAddress()</codeph></p></li>
+</ul><p>The EGL Reference Implementation also implements the following reusable
+sync extension functions:</p><ul>
+<li><p><codeph>eglCreateSyncKHR()</codeph></p></li>
+<li><p><codeph>eglDestroySyncKHR()</codeph></p></li>
+<li><p><codeph>eglClientWaitSyncKHR()</codeph></p></li>
+<li><p><codeph>eglSignalSyncKHR()</codeph></p></li>
+<li><p><codeph>eglGetSyncAttribKHR()</codeph></p></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>Signaling is often used by both a third party
+application and its middleware API, such as OpenWF-C. However, once the middleware
+API calls the <codeph>eglSignalSyncKHR()</codeph> standard signaling function
+and obtains the error code using <codeph>eglGetError()</codeph>, the error
+code is not available to the application. </p><p>The following private signaling
+function returns the error without generating the error code. This is an implementation-specific
+function, which gives the OpenWF-C implementation a mechanism for calling
+into the EGL implementation.</p><codeblock xml:space="preserve">EGLint egl_Private_SignalSyncNOK(
+ EGLDisplay dpy,
+ EGLSyncKHR sync,
+ EGLenum mode)</codeblock><p>Generally when the same vendor implements
+both EGL and OpenWF-C, the vendor will implement their own private functions.</p><p><i>Note</i>:
+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> </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><p> <filepath>libegl_ref.dll</filepath> </p> </entry>
+<entry><p>The EGL reference implementation.</p> </entry>
+</row>
+<row>
+<entry><p><filepath>libEGL.dll</filepath></p></entry>
+<entry><p>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. </p></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>
\ No newline at end of file