Name

    NV_stream_reset

Name Strings

    EGL_NV_stream_reset

Contributors

    Daniel Kartch

Contacts

    Daniel Kartch, NVIDIA (dkartch 'at' nvidia.com)

Status

    Draft

Version

    Version 6 - October 27, 2016

Number

    EGL Extension #112

Extension Type

    EGL display extension

Dependencies

    Requires the EGL_KHR_stream extension.

    Modifies the EGL_KHR_stream_fifo extension.

    Modifies the EGL_KHR_stream_consumer_gltexture extension.

    Modifies the EGL_EXT_stream_consumer_egloutput extension.

    Interacts with the EGL_KHR_stream_cross_process_fd and
    EGL_NV_stream_remote extensions.

    This extension is written based on the wording of version 26 of the
    EGL_KHR_stream extension.

Overview

    The base stream extension requires that, once the producer inserts
    the first frame into the stream, at least one frame is always
    available to be acquired by the consumer until the stream
    disconnects. However, there are some use cases in which the producer
    or the consumer may wish to allow the stream to empty without
    permanently disconnecting.

    An example of a use case where the producer may wish to empty the
    stream is a security or rear-view camera which temporarily stops
    producing new frames, perhaps due to a hardware reset. Continuing to
    display the last frame available would produce a false impression of
    the current state, and should be avoided for safety reasons. A
    better solution would be to let the consumer know there was no
    available image, so that it could take appropriate actions, and then
    recover when the camera begins streaming again.

    This use case could be handled with existing functionality by
    disconnecting and destroying the stream and then recreating and
    reconnecting it when new frames are available. However, this can be
    burdensome, particularly when the producer and consumer reside in
    separate processes.

    An example of a use case where the consumer may wish to empty the
    stream is an image processer which operates on each frame exactly
    once. After processing, it will not waste resources operating on the
    same frame a second time. This use case can be handled by carefully
    monitoring the availability of a new frame before performing an
    acquire operation. But returning the buffer(s) as soon as they are
    no longer needed allows for better resource management.

    This extension allows a stream to be completely drained of existing
    frames by the consumer or flushed of existing frames by the producer
    without disconnecting, so that processing may continue again when
    new frames are produced.

New Functions

    EGLBoolean eglResetStreamNV(
        EGLDisplay   dpy,
        EGLStreamKHR stream);

New Tokens

    Accepted as an attribute in the <attrib_list> parameter of
    eglCreateStreamKHR and the <attrib> parameter of eglQueryStreamKHR:

        EGL_SUPPORT_RESET_NV                    0x3334
        EGL_SUPPORT_REUSE_NV                    0x3335

To table "3.10.4.4 EGLStream Attributes", add entry

    Attribute                   Read/Write   Type          Section
    --------------------------  ----------   ------        ----------
    EGL_SUPPORT_RESET_NV            io       EGLint        3.10.4.x
    EGL_SUPPORT_REUSE_NV            io       EGLint        3.10.4.x+1

Modify entries in the list of state transitions in "3.10.4.3
EGL_STREAM_STATE_KHR Attribute"

        EGL_STREAM_STATE_EMPTY_KHR ->
        EGL_STREAM_STATE_NEW_FRAME_AVAILABLE_KHR
        Occurs when the producer inserts the first image frame and any
        subsequent frame after the stream has been drained.

        EGL_STREAM_STATE_OLD_FRAME_AVAILABLE_KHR ->
        EGL_STREAM_STATE_NEW_FRAME_AVAILABLE_KHR
        Occurs when the producer inserts a new image frame and only
        previously consumed frames are available.

        EGL_STREAM_STATE_NEW_FRAME_AVAILABLE_KHR ->
        EGL_STREAM_STATE_OLD_FRAME_AVAILABLE_KHR
        Occurs when the consumer begins examining the last unconsumed
        frame and reuse of old frames is enabled.

Add entries to the list of state transitions in "3.10.4.3
EGL_STREAM_STATE_KHR Attribute"

        EGL_STREAM_STATE_OLD_FRAME_AVAILABLE_KHR ->
        EGL_STREAM_STATE_EMPTY_KHR
        Occurs when the stream is reset.

        EGL_STREAM_STATE_NEW_FRAME_AVAILABLE_KHR ->
        EGL_STREAM_STATE_EMPTY_KHR
        Occurs when the stream is reset or, if reuse of old frames is
        disabled, when the consumer begins examining the last unconsumed
        frame.

Add new sections at the end of section "3.10.4 EGLStream Attributes"

    3.10.4.x EGL_SUPPORT_RESET_NV Attribute

    The EGL_SUPPORT_RESET_NV attribute may only be set when the stream
    is created. By default, it is EGL_FALSE. If set to EGL_TRUE, the
    stream will allow restoration of the stream state back to
    EGL_STREAM_STATE_EMPTY_KHR state from
    EGL_STREAM_STATE_OLD_FRAME_AVAILABLE_KHR or
    EGL_STREAM_STATE_NEW_FRAME_AVAILABLE_KHR, releasing existing frames,
    as described in section 3.10.5.x.

    Not all consumers are required to support stream resets. Attempting
    to attach a consumer which does not support resets to a stream with
    EGL_SUPPORT_RESET_NV set to EGL_TRUE will fail with an
    EGL_BAD_MATCH error.

    Not all producers will provide a means to reset streams themselves,
    but any producer may be connected to a stream which supports resets
    and may be used with the eglStreamResetNV function.

    3.10.4.x+1 EGL_SUPPORT_REUSE_NV Attribute

    The EGL_SUPPORT_REUSE_NV attribute may only be set when the stream
    is created. By default, it is EGL_TRUE. If EGL_TRUE, then when the
    consumer acquires the last available image frame from the stream, it
    will be held for reuse until a new frame is inserted to replace it.
    If EGL_FALSE, no frames will be available to the consumer until the
    producer inserts a new one.

Modify third paragraph of "3.10.5.1 EGLStream operation in mailbox mode"

    The consumer retrieves the image frame from the mailbox and
    examines it.  When the consumer is finished examining the image
    frame it is either placed back in the mailbox (if the mailbox is
    empty, supports reuse of frames, and has not been reset) or
    discarded (otherwise).

If EGL_KHR_stream_fifo is present, insert at beginning of fourth paragraph
of "3.10.5.2 EGLStream operation in fifo mode"

    If the EGL_SUPPORT_REUSE_NV attribute is EGL_TRUE and the stream has
    not been reset since the image frame was consumed, then if the fifo
    is empty ...

Insert a new paragraph after the above

    If the EGL_SUPPORT_REUSE_NV attribute is EGL_FALSE or the stream has
    been reset, then if the fifo is empty when the consumer is finished
    consuming an image frame, the frame is discarded and the stream is
    left in the EGL_STREAM_STATE_EMPTY_KHR state until new frames are
    produced.

Add a new section to "3.10.5 EGLStream operation"

    3.10.5.x EGLStream reset

    For resource management or safety reasons, it may be necessary to
    invalidate and reclaim frames pending in the stream. This is only
    possible if the stream's EGL_SUPPORT_RESET_NV attribute is set to
    EGL_TRUE.

    Stream resets cause any unconsumed image frames waiting in the
    stream to be immediately discarded, and place the stream in the
    EGL_STREAM_STATE_EMPTY_KHR state. Frames currently held by the
    consumer are not immediately affected, but will be discarded once
    released, even if the stream would normally hold old frames for
    reuse. After the reset, new frames inserted by the producer are
    processed normally.

    Stream resets may be issued by some producers as described in their
    specifications, and may also be triggered by the application calling

        EGLBoolean eglResetStreamNV(
            EGLDisplay   dpy,
            EGLStreamKHR stream)

    On success, EGL_TRUE is returned and a reset of the stream is
    initiated. On failure, EGL_FALSE is returned and an error is
    generated.

        - EGL_BAD_DISPLAY is generated if <dpy> is not a valid
          EGLDisplay.

        - EGL_NOT_INITIALIZED is generated if <dpy> is not initialized.

        - EGL_BAD_STREAM_KHR is generated if <stream> is not a valid
          EGLStream created for <dpy>.

        - EGL_BAD_STATE_KHR is generated if <stream> is in
          EGL_STREAM_STATE_CREATED_KHR, EGL_STREAM_STATE_CONNECTING_KHR,
          or EGL_STREAM_STATE_DISCONNECTED_KHR state.

        - EGL_BAD_ACCESS is generated if <stream>'s
          EGL_SUPPORT_RESET_NV attribute is not EGL_TRUE.

    If a stream is already in the EGL_STREAM_STATE_EMPTY_KHR state, a
    reset will have no effect.

If EGL_KHR_stream_cross_process_fd or EGL_NV_stream_remote is present,
add to the list of errors above

        - EGL_BAD_ACCESS is generated if <stream> represents the
          consumer endpoint of a stream whose producer endpoint is
          represented by a different EGLStreamKHR handle (e.g. for
          cross-process streams).

If EGL_KHR_stream_consumer_gltexture is supported, modify the first
sentence of the fifth paragraph of the description of
eglStreamConsumerAcquireKHR

    If the producer has not inserted any new image frames since the
    last call to eglStreamConsumerAcquireKHR, and the stream has been
    reset or does not support reuse of frames, then
    eglStreamConsumerAcquireKHR will fail. If it has not been reset and
    reuse is supported, then eglStreamConsumerAcquireKHR will "latch"
    the same image frame it latched last time
    eglStreamConsumerAcquireKHR was called.

If EGL_EXT_stream_consumer_egloutput is supported, add to the
description if eglStreamConsumerOutputEXT

    If the stream is reset to the EGL_STREAM_STATE_EMPTY_KHR state, any
    currently displayed frame will be released, and the displayed image
    will be reset to some default state determined by the display
    hardware and the implementation. Possible behavior includes, but is
    not limited to, displaying a black screen, displaying a default
    splash screen, displaying a "no input" message, or powering off the
    display. If and when the stream again enters the
    EGL_STREAM_STATE_NEW_FRAME_AVAILABLE_KHR state, processing of frames
    will resume as described above.

Issues

    1.  When this extension is present, should all streams automatically
        support resetting?

        RESOLVED: No. Applications which are not aware of this extension
        may not be prepared to handle an unexpected return to the EMPTY
        state. Therefore support for this feature must be explicitly
        requested.

Revision History

    #6  (October 27, 2016) Daniel Kartch
        - Clean up for publication

    #5  (July 23rd, 2015) Daniel Kartch
        - Added interaction with cross-process streams.

    #4  (July 22nd, 2015) Daniel Kartch
        - Added enum values.

    #3  (July 20th, 2015) Daniel Kartch
        - Changed to NV specification
        - Removed flush option from eglResetStream. Resetting will
          always flush pending frames.
        - Added EGL_SUPPORT_REUSE_NV flag to control whether released
          frames are saved or discarded immediately.
        - Removed reference to unpublished stream_sequence extension.

    #2  (August 21th, 2014) Daniel Kartch
        - Added paragraph to indicate that producers do not impose
          restrictions on use of reset.
        - Clarified consumer behavior on reset.
        - Added interactions with GL texture and EGLOutput consumers.

    #1  (August 12th, 2014) Daniel Kartch
        - Initial draft