Name

    KHR_stream_producer_aldatalocator

Name Strings

    EGL_KHR_stream_producer_aldatalocator

Contributors

    Acorn Pooley

Contacts

    Acorn Pooley, NVIDIA  (apooley 'at' nvidia.com)

Notice

    Copyright (c) 2011-2013 The Khronos Group Inc. Copyright terms at
        http://www.khronos.org/registry/speccopyright.html

Status

    Complete.
    Approved by the Khronos Board of Promoters on December 2, 2011.

Version

    Version 4, October 4, 2011

Number

    EGL Extension #35

Dependencies

    Requires EGL 1.2 or later.
    Requires OpenMAX AL 1.1 or later.

    Requires the EGL_KHR_stream extension.
    Requires the OpenMAX_AL_EGLStream_DataLocator extension.

Overview

    This extension (in conjunction with the
    OpenMAX_AL_EGLStream_DataLocator extension to OpenMAX AL)
    allows an OpenMAX AL MediaPlayer object to be connected as the
    producer of an EGLStream.

    After the EGLStream is created and connected to a consumer, the
    OpenMAX AL MediaPlayer object is created by calling <pEngine>'s
    CreateMediaPlayer() method. The <pImageVideoSnk> argument points
    to an XADataLocator_EGLStream containing the EGLStreamKHR handle
    of the stream.  The CreateMediaPlayer() method creates a
    MediaPlayer object and connects it as the producer of the
    EGLStream.  (Note that the pFormat member of the XADataSink
    structure is ignored in this case and may be NULL.)

    Once connected the MediaPlayer inserts image frames into the
    EGLStream.

Replace section "3.10.3.1 No way to connect producer to EGLStream" in
the EGL_KHR_stream extension with this:

    3.10.3.1 OpenMAX AL Stream Producer

    An OpenMAX AL MediaPlayer object can act as a producer for an
    EGLStream.  First create the EGLStream and connect a consumer to
    it so that the EGLStream is in EGL_STREAM_STATE_CONNECTING_KHR
    state.

    At this point the application can create an OpenMAX AL MediaPlayer
    object as described in the OpenMAX AL specification and the
    OpenMAX_AL_EGLStream_DataLocator extension.  The application
    should create an XADataSink structure with pLocator pointing to an
    XADataLocator_EGLStream structure referencing the EGLStream (in
    the pEGLStream member) and the EGLDisplay used to create the
    EGLStream (in the pEGLDisplay member).  The pFormat field of the
    XADataSink is ignored and should be NULL.  This XADataSink
    structure is passed as the <pImageVideoSnk> argument to
    <pEngine>'s CreateMediaPlayer() method.

    If the OpenMAX AL implementation is unable to convert image frames
    to a format usable by <stream>'s consumer then CreateMediaPlayer
    will fail with a XA_RESULT_CONTENT_UNSUPPORTED error.

    After CreateMediaPlayer() has returned successfully, <stream>'s
    state will be one of
        - EGL_STREAM_STATE_EMPTY_KHR
        - EGL_STREAM_STATE_NEW_FRAME_AVAILABLE_KHR
        - EGL_STREAM_STATE_OLD_FRAME_AVAILABLE_KHR
    and the OpenMAX AL MediaPlayer object returned in <pPlayer> will
    be connected as the producer of <stream>.  If the MediaPlayer
    object is destroyed then <stream>'s state will become
    EGL_STREAM_STATE_DISCONNECTED_KHR.

    Image and video frame data generated by the OpenMAX AL object (as
    described in the OpenMAX AL spec) are inserted into <stream> (as
    described in section "3.10.5 EGLStream operation" of the
    EGL_KHR_stream extension).

    The OpenMAX AL object will use the value of the
    EGL_CONSUMER_LATENCY_USEC_KHR attribute of <stream> to determine
    when to insert each image frame.  If the
    EGL_CONSUMER_LATENCY_USEC_KHR attribute is modified (by the
    consumer and/or by the application) then OpenMAX AL object
    will adjust its timing within 500 milliseconds of the change.  If
    an image frame is intended to appear to the user at time T (e.g.
    so that it is synchronized with audio) then the OpenMAX AL object
    must insert the image frame at time
        T - EGL_CONSUMER_LATENCY_USEC_KHR

Issues
    1.  How many image frame buffers should be used?

        RESOLVED: This is left up to the OpenMAX AL implementation.

    2.  How is the image frame size determined?

        Could also expose EGL_WIDTH and EGL_HEIGHT in the attrib_list
        as a hint (or as a requirement) as to what size should be
        used.  However, a MediaPlayer object typically knows what size
        to decode based on the source of the data.  So this is
        probably not necessary.  If needed it can be added with a
        layered extension.

        RESOLVED: Leave this up to the OpenMAX AL MediaPlayer object.

    3.  What image frame format should be used?

        RESOLVED: This is a negotiation between the consumer and
        producer, but ultimately the producer must convert to the
        format that the consumer requests, or fail if that is not
        possible.

        Details of any such communication is implementation dependent
        and outside the scope of this specification.

    4.  Should this extension create an XADataSink structure rather
        than making the application create its own as described in
        OpenMAX_AL_EGLStream_DataLocator?

        RESOLVED: NO  no need to do this.

    5.  (This issue no longer applies)
        Should this extension allow the application to ignore the
        XADataSink structure returned by eglStreamProducerALDataSource
        and instead use its own?

        RESOLVED: This issue no longer applies

    6.  (This issue no longer applies)
        Should eglStreamProducerALDataSource check that <ppDataSink>
        is not NULL and that <ppDataSink> points to a pointer that is
        NULL?

        RESOLVED: This issue no longer applies


Revision History

    #4  (October 4, 2011) Acorn Pooley
        - Convert from an NV extension to a KHR extension

    #3  (September 23, 2011) Acorn Pooley
        - Eliminate the eglStreamProducerALDataSource function.
        - Rename AL0124b_EGLImageStream_DataLocator_Nokia to
          OpenMAX_AL_EGLStream_DataLocator and point to new link.
        - Resolve issue 2

    #2  (July 6, 2011) Acorn Pooley
        - remove the creation of the XADataSink by
          eglStreamProducerALDataSource()

    #1  (June 30, 2011) Acorn Pooley
        - initial draft

# vim:ai:ts=4:sts=4:expandtab:textwidth=70