NV_stream_frame_limits

EGL_NV_stream_frame_limits

Daniel Kartch

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

Draft

Version 4 - October 27, 2016

EGL Extension #113

Requires EGL_KHR_stream

Interacts with EGL_EXT_stream_consumer_egloutput

Some stream consumers may allow more than one frame to be acquired
at a time, so that applications can operate on sequences of images
rather than individual images. This in turn may lead to producers
allocating additional buffers to keep the fifo full while fulfilling
the consumer's needs. Applications may wish to limit the resources
allocated for a given stream, and some stream implementations may be
able to operate more efficiently if they know in advance how many
buffers will be used.

This extension defines two new stream attributes which provide hints
as to how many frames the application will require, allowing the
implementation to plan accordingly.

None

Accepted as an attribute name in the <attrib_list> parameter of
eglCreateStreamKHR and as the <attribute> parameter of
eglQueryStreamKHR.

    EGL_PRODUCER_MAX_FRAME_HINT_NV             0x3337
    EGL_CONSUMER_MAX_FRAME_HINT_NV             0x3338

    Attribute                       Read/Write   Type      Section
    ------------------------------  ----------  ------   ----------
    EGL_PRODUCER_MAX_FRAME_HINT_NV      io      EGLint   3.10.4.x
    EGL_CONSUMER_MAX_FRAME_HINT_NV      io      EGLint   3.10.4.x+1

3.10.4.x EGL_PRODUCER_MAX_FRAME_HINT_NV Attribute

The EGL_PRODUCER_MAX_FRAME_HINT_NV attribute indicates a limit on how
many outstanding frames the producer application intends to have at
any given time. This includes all frames currently being generated,
waiting in in the stream's mailbox or FIFO, and held by the consumer.
Its default value is EGL_DONT_CARE.

The implementation may make use of this hint to determine how many
buffers or other resources to allocate for the stream. It is not
necessarily an error for an application to attempt to insert more
than this many frames into the stream at once. However, exceeding
available resources may cause a producer to block or return an error,
as per its specification.

3.10.4.x+1 EGL_CONSUMER_MAX_FRAME_HINT_NV Attribute

The EGL_CONSUMER_MAX_FRAME_HINT_NV attribute indicates a limit on how
many frames the consumer application intends to acquire at the same
time. Its default value EGL_DONT_CARE.

The implementation may make use of this hint to determine how many
buffers or other resources to allocate for the stream. It is not
necessarily an error for an application to attempt to acquire more
than this many frames at once. However, exceeding available resources
may cause the consumer or producer to block or return an error, as per
their specifications.

When the producer generates frames faster than the output device can
display them, <stream>'s EGL_CONSUMER_MAX_FRAME_HINT_NV attribute can
be used to throttle the output. No more than the specified number of
frames will be scheduled for display at a time. If specified, the value
should be set to at least 2, to allow one frame to be displayed while
another is acquired and scheduled for display.

1.  Is a generic stream extension really necessary, or can such
    limits instead be imposed in the producer and consumer
    interfaces?

    RESOLVED: Yes, it is necessary. There are several use cases
    where an application may need to impose limits and cannot do so
    through the producer and consumer interfaces:
    a) The producer and client interfaces are already published and
    do not allow room for extension to impose limits.
    b) The stream is cross-process, and one process needs to impose
    limits on the endpoint provided by the other process.
    In addition, a common method for imposing such limits simplifies
    programming of large application suites which make use of
    multiple types of producers and consumers, and allows the limits
    on producer and consumer endpoints to be set to compatible
    values.

2.  Should the attributes be hints or hard limits?

    RESOLVED: Hints. The variety of possible producers and consumers
    makes it difficult to specify what the behavior should be if a
    hard limit is exceeded. The goal here is to allow the application
    to coordinate its resource requirements with the implementation.
    If it fails to limit itself to the hinted values, we allow
    producers or consumers to block or fail as appropriate for their
    interfaces, but do not require it.

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

#3  (September 14, 2106) Daniel Kartch
    - Switched from hard limits to hints

#2  (January 8, 2016) Daniel Kartch
    - Assigned enum values

#1  (October 30, 2015) Daniel Kartch
    - Initial draft