Name NV_stream_sync Name Strings EGL_NV_stream_sync Contributors Acorn Pooley Marcus Lorentzon Contacts Ian Stewart, NVIDIA (istewart 'at' nvidia.com) Status Complete Version Version 6, June 5, 2012 Number EGL Extension #56 Dependencies Requires EGL 1.2. Requires EGL_KHR_stream extension Requires EGL_KHR_reusable_sync This extension is written based on the wording of the EGL 1.2 specification. Overview This extension defines a new type of reusable sync object. This sync object will be signaled each time a new image frame becomes available in an EGLStream for the consumer to consume. New functions EGLSyncKHR eglCreateStreamSyncNV( EGLDisplay dpy, EGLStreamKHR stream, EGLenum type, const EGLint *attrib_list); New Tokens Accepted by the parameter of eglCreateSyncKHR, and returned in when eglGetSyncAttribKHR is called with EGL_SYNC_TYPE_KHR: EGL_SYNC_NEW_FRAME_NV 0x321F Add a new paragraph to section "3.8.1 Sync Objects" in the EGL_KHR_reusable_sync extension, just before the paragraph that mentions the eglClientWaitSyncKHR function: The command EGLSyncKHR eglCreateStreamSyncNV( EGLDisplay dpy, EGLStreamKHR stream, EGLenum type, const EGLint *attrib_list); creates a sync object of the specified associated with the specified display and the specified EGLStream , and returns a handle to the new object. is an attribute-value list specifying other attributes of the sync object, terminated by an attribute entry EGL_NONE. Attributes not specified in the list will be assigned their default values. The state of must not be EGL_STREAM_STATE_CREATED_KHR or EGL_STREAM_STATE_DISCONNECTED_KHR. If is EGL_SYNC_NEW_FRAME_NV, a stream-new-frame reusable sync object is created. In this case must be NULL or empty (containing only EGL_NONE). Attributes of the reusable stream-new-frame sync object are set as follows: Attribute Name Initial Attribute Value(s) --------------- -------------------------- EGL_SYNC_TYPE_KHR EGL_SYNC_NEW_FRAME_NV EGL_SYNC_STATUS_KHR EGL_UNSIGNALED_KHR Any time the state of transitions to EGL_STREAM_STATE_NEW_FRAME_AVAILABLE_KHR (from any other state), the returned stream-new-frame reusable sync object is signaled. (This effectively means the sync object will become signaled whenever the producer inserts a new image frame into the EGLStream.) EGL does not automatically unsignal the stream-new-frame reusable sync object. Generally applications will want to unsignal the sync object after it has been signaled so that the availability of the next frame can be detected. Errors ------ * If is not the name of a valid, initialized EGLDisplay, EGL_NO_SYNC_KHR is returned and an EGL_BAD_DISPLAY error is generated. * If is neither NULL nor empty (containing only EGL_NONE), EGL_NO_SYNC_KHR is returned and an EGL_BAD_ATTRIBUTE error is generated. * If is not a valid EGLStream created for , EGL_NO_SYNC_KHR is returned and an EGL_BAD_STREAM error is generated. * If 's state is EGL_STREAM_STATE_CREATED_KHR or EGL_STREAM_STATE_DISCONNECTED_KHR then EGL_NO_SYNC_KHR is returned and an EGL_BAD_ACCESS error is generated. * If a sync object of has already been created for (and not destroyed), EGL_NO_SYNC_KHR is returned and an EGL_BAD_ACCESS error is generated. * If is not a supported type of stream sync object, EGL_NO_SYNC_KHR is returned and an EGL_BAD_ATTRIBUTE error is generated. Issues 1. Is this extension useful, or does the built in blocking behavior of the consumer described by the EGL_NV_stream_consumer_gltexture extension render this un-useful? RESOLVED: Yes. It is useful to have a thread waiting on the signal. 2. Does EGL automatically unsignal the sync object? RESOLVED: No. After the sync object has been signaled, it is up to the application to unsignal it before waiting on it again. It is important to check for the availability of another frame by querying EGL_PRODUCER_FRAME_KHR after unsignaling the sync object and before waiting on the sync object to prevent a race condition. This can be done using the following code: void ConsumeFrames(EGLDisplay dpy, EGLStreamKHR stream) { EGLuint64KHR last_frame = 0; EGLuint64KHR new_frame = 0; EGLSyncKHR sync; sync = eglCreateStreamSyncNV(dpy, stream, EGL_SYNC_NEW_FRAME_NV, 0); for(;;) { eglSignalSyncKHR(dpy, sync, EGL_UNSIGNALED_KHR); eglQueryStreamu64KHR(dpy, stream, EGL_PRODUCER_FRAME_KHR, &new_frame); if (new_frame != last_frame) { last_frame = new_frame; ConsumeNewFrame(stream); } else { eglClientWaitSyncKHR(dpy, sync, 0, EGL_FOREVER_KHR); } } } Revision History #7 (July 10, 2013) Jon Leech - Fix spelling of 'signalled' -> 'signaled' and assign extension number for publication. #6 (June 5, 2012) Acorn Pooley - Add error if stream is in state EGL_STREAM_STATE_CREATED_KHR or EGL_STREAM_STATE_DISCONNECTED_KHR when sync is created. #5 (September 30, 2011) Acorn Pooley - Change eglCreateStreamSyncKHR to eglCreateStreamSyncNV #4 (September 28, 2011) Acorn Pooley - Add issue 2 - Fix return type of eglCreateStreamSyncNV #3 (September 27, 2011) Acorn Pooley - Assign enum values (bug 8064) #2 (July 6, 2011) Acorn Pooley - Rename EGL_KHR_image_stream to EGL_KHR_stream #1 (June 30, 2011) Acorn Pooley - Initial draft