xref: /third_party/EGL/extensions/NV/EGL_NV_stream_sync.txt

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