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 <type> parameter of eglCreateSyncKHR, and returned
in <value> when eglGetSyncAttribKHR is called with <attribute>
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 <type> associated with the
specified display <dpy> and the specified EGLStream <stream>, and
returns a handle to the new object. <attrib_list> 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 <stream> must not be EGL_STREAM_STATE_CREATED_KHR or
EGL_STREAM_STATE_DISCONNECTED_KHR.
If <type> is EGL_SYNC_NEW_FRAME_NV, a stream-new-frame reusable
sync object is created. In this case <attrib_list> 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 <stream> 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 <dpy> is not the name of a valid, initialized EGLDisplay,
EGL_NO_SYNC_KHR is returned and an EGL_BAD_DISPLAY error is
generated.
* If <attrib_list> is neither NULL nor empty (containing only
EGL_NONE), EGL_NO_SYNC_KHR is returned and an EGL_BAD_ATTRIBUTE
error is generated.
* If <stream> is not a valid EGLStream created for <dpy>,
EGL_NO_SYNC_KHR is returned and an EGL_BAD_STREAM error is
generated.
* If <stream>'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 <type> has already been created for
<stream> (and not destroyed), EGL_NO_SYNC_KHR is returned and
an EGL_BAD_ACCESS error is generated.
* If <type> 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
