NV_stream_sync

EGL_NV_stream_sync

Acorn Pooley
Marcus Lorentzon

Ian Stewart, NVIDIA  (istewart 'at' nvidia.com)

Complete

Version 6, June 5, 2012

EGL Extension #56

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.

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.

EGLSyncKHR eglCreateStreamSyncNV(
    EGLDisplay   dpy,
    EGLStreamKHR stream,
    EGLenum type,
    const EGLint *attrib_list);

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

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.

    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);
                }
            }
        }

#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