Name INTEL_native_event_objectsName Strings EGL_INTEL_native_event_objectsNotice Copyright 2010 Intel Cooperation. All rights reserved.Contributors Robert BraggContacts Robert Bragg, Intel (robert.bragg 'at' intel.com)Status IssuedVersion 1 - Jun 15, 2010Number TBDDependencies Requires EGL 1.4 This extension is written against the wording of the EGL 1.4 Specification.Overview This extension defines some new functions designed to add an event delivery mechanism to EGL built on top of the platform's native event delivery mechanism. On unix this means being able to get a list of file descriptors from EGL that can be passed to poll(2) to efficiently put your application to sleep while waiting for events from the driver. On a platform such as Windows you would get a list of HANDLES for event objects that could be passed to WaitForMultipleObjects() to do much the same thing. This extension doesn't define any specific events it's expected that other specs will choose to depend on this extension if they need a way to report events to the application framework. Examples of events we'd hope to see become available once this extension is in place are: SwapBuffersComplete events to notify when an asynchronous eglSwapBuffers request has completed and SyncObjectSignaled events to notify when a sync object becomes signaled.New Procedures and Functions EGLBoolean eglGetNativeEventObjectsINTEL( EGLDisplay dpy, EGLNativeEventObject *objects, EGLint object_size, EGLint *num_objects); EGLBoolean eglPrepareForEventsWaitINTEL( EGLDisplay dpy, EGLBoolean *dispatch_ready, EGLint *timeout); EGLBoolean eglCheckForEventsINTEL( EGLDisplay dpy, EGLBoolean *dispatch_ready); EGLBoolean eglDispatchEventsINTEL( EGLDisplay dpy);New Types /* A platform dependant typedef used to integrate with native * event handling APIs */ EGLNativeEventObjectNew Tokens NoneAdditions to Chapter 2 of the EGL 1.4 Specification (EGL Operation) Add the following text to a new subsection titled "Events" after the "Initialization" subsection: There are numerous requests exposed by the rendering APIs supported by EGL that, due to their typical interaction with a separate graphics processor, happen asynchronously with respect to work on the CPU. It is desirable to have a way for drivers to deliver events to application in a way that takes advantage of native event delivery mechanism so that the operating system can for instance put the process to sleep while it is waiting for events instead of busy-waiting and wasting CPU resources. A list of EGLNativeEventObjects can be queried from EGL and depending on how that type is defined for your platform these objects can be cast and used with your native event handling APIs. For example on Unix an EGLNativeEventObject would typically be a file descriptor that can be passed to the poll(2) system call to know when there is something to be read from that file. The processing of events in EGL has a three stage lifecycle designed to ease integration with higher level frameworks that may be tracking many different event sources, not just those from EGL. 1) Prepare Firstly the application must notify EGL when it is idle and preparing to ask the operating system to block and wait for further events. This gives EGL an opportunity to check if there are in fact already outstanding events to be dispatched before letting the process go to sleep. If there aren't any events to dispatch yet then this gives the EGL driver an opportunity to specify a maximum time that the process should sleep while waiting for the next event. 2) Check When the application regains control from any native event handling mechanism, perhaps because one of the event objects has had an event delivered to it or the maximum timeout specified in the prepare stage was reached, then EGL should be given control again so it can check each of the event objects for outstanding events that may be ready to be "Dispatched". 3) Dispatch Finally if either the prepare or check stages determine that there are events ready to be dispatched then the application needs to give EGL control to process and dispatch these events back to the application.Additions to Chapter 3 of the EGL 1.4 Specification (EGL Functions and Errors) Add the following text to a new subsection titled "Event Handling" after the "Initialization" subsection: "3.2 Event Handling An EGLNativeEventObject defines a platform dependant object that can used with the operating systems native event handling APIs. Use EGLBoolean eglGetNativeEventObjectsINTEL( EGLDisplay dpy, EGLNativeEventObject *objects, EGLint object_size, EGLint *num_object); to get the list of native event objects for the given display. <objects> is a pointer to a buffer containing <object_size> elements. On success, EGL_TRUE is returned. The number of objects is returned in <num_object>, and elements 0 through <num_object> - 1 of the objects are filled in with the native event objects. No more than <object_size> EGLNativeEventObjects will be returned even if more are available on the specified display. However if eglGetNativeEventObjectsINTEL is called with <objects> = NULL then no objects are returned, but the total number of objects available will be returned in <num_object>. On failure EGL_FALSE will be returned. An EGL_NOT_INITIALIZED error is generated if EGL is not initialized on dpy. An EGL_BAD_PARAMETER error is generated if <num_object> is NULL. Use EGLBoolean eglPrepareForEventsWaitINTEL( EGLDisplay dpy, EGLBoolean *dispatch_ready, EGLint *timeout); to notify EGL that the application is idle and preparing to ask the operating system to put the current thread to sleep until an event is received. On success, EGL_TRUE is returned. If there are already events ready to be dispatched before letting the operating system put the thread to sleep then <dispatch_ready> will be set to EGL_TRUE. If there are no events ready to be dispatched <dispatch_ready> will be set to EGL_FALSE and <timeout> will be be set to the maximum time (in milliseconds) that the thread should be made to sleep. On failure EGL_FALSE will be returned. An EGL_NOT_INITIALIZED error is generated if EGL is not initialized on dpy. An EGL_BAD_PARAMETER error is generated if <dispatch_ready> is NULL or <timeout> is NULL. Use EGLBoolean eglCheckForEventsINTEL( EGLDisplay dpy, EGLBoolean *dispatch_ready); to notify EGL that the application has regained control after being put to sleep by the operating system to wait for events. EGL will check if any of the event objects now have events ready to be dispatched. On success, EGL_TRUE is returned. If there are events ready to be dispatched <dispatch_ready> is set to EGL_TRUE otherwise it is set to EGL_FALSE. On failure EGL_FALSE will be returned. An EGL_NOT_INITIALIZED error is generated if EGL is not initialized on dpy. An EGL_BAD_PARAMETER error is generated if <dispatch_ready> is NULL. Use EGLBoolean eglDispatchEventsINTEL( EGLDisplay dpy); whenever a call to eglPrepareForEventsWaitINTEL or eglCheckForEventsINTEL reports that there are events ready to be dispatched. On success, EGL_TRUE is returned. On failure EGL_FALSE will be returned. An EGL_NOT_INITIALIZED error is generated if EGL is not initialized on dpy.Dependencies on OpenGL ES NoneDependencies on OpenVG NoneIssues NoneRevision History Version 1, 15/06/2010 - First draft