Name
NV_stream_fifo_synchronous
Name Strings
EGL_NV_stream_fifo_synchronous
Contributors
Daniel Kartch
Adam Cheney
Contacts
Daniel Kartch, NVIDIA (dkartch 'at' nvidia.com)
Status
Draft
Version
Version 4 - October 27, 2016
Number
EGL Extension #111
Extension Type
EGL display extension
Dependencies
Requires EGL_KHR_stream_fifo
Interactions with EGL_NV_stream_sync and
EGL_KHR_stream_consumer_gltexture
This extension affects implementations of stream synchronization and
GL texture consumer extensions in that it alters when functions
waiting for new frames will be unblocked. However, as these waits
are still tied to transitions to the
EGL_STREAM_STATE_NEW_FRAME_AVAILALBLE_KHR state, no changes are
required to the wording of those specifications.
Overview
On platforms which support asynchronous rendering, frames may be
inserted into a stream by the producer and become available to the
consumer before rendering of the images has completed. When this
happens, commands issued by the consumer which read from the image
must implicitly wait before they can be executed. In many use cases,
this is desirable behavior. Rendering pipelines are kept full, and
frames are created and processed as fast as possible.
However, in the case of a compositor which is consuming frames from
multiple producers at once, combining them into a single output
image, this can slow the compositor to the frame rate of the slowest
producer. If the application acquires and uses an image from one
producer which requires a long time to finish rendering, it will be
prevented from presenting new frames from faster producers in a
timely fashion. In this case, the compositor would prefer to reuse
an older frame from the slower producer until the new one is ready.
This could be handled with existing interfaces by the producer
issuing appropriate Finish call before inserting the frame into the
stream. However this requires the producer to have knowledge of the
consumer's use case, and also introduces undesirable bubbles into
the producer's pipeline which will slow it even further.
This extension allows streams to be configured to defer the
availability of new frames inserted by the producer until they are
ready to be used. The producer proceeds as normal, but the frames
visible to the consumer through query and acquire operations do not
update immediately.
Interactions of this feature with a stream operating in mailbox mode
would be hard to define. Because newly inserted frames replace
previous unacquired ones, it is possible that the consumer would
never see a completed frame become available. Therefore this feature
is only available for streams operating in FIFO mode.
New Types
None
New Functions
None
New Tokens
Accepted as an attribute name in the <attrib_list> parameter of
eglCreateStreamKHR and a the <attribute> parameter of
eglQueryStreamKHR:
EGL_STREAM_FIFO_SYNCHRONOUS_NV 0x3336
Add new entry to table "3.10.4.4 EGLStream Attributes" in the
EGL_KHR_stream extension
Attribute Read/Write Type Section
------------------------------ ---------- ---------- --------
EGL_STREAM_FIFO_SYNCHRONOUS_NV io EGLBoolean 3.10.4.y
Add new subsection to section "3.10.4 EGLStream Attributes" in the
EGL_KHR_stream extension
3.10.4.y EGL_STREAM_FIFO_SYNCHRONOUS_NV Attribute
The EGL_STREAM_FIFO_SYNCHRONOUS_NV attribute controls whether frames
inserted by the producer become available to the consumer
synchronously or asynchronously. If set to EGL_FALSE, then when a
present operation for a new frame successfully completes, the state
will immediately become EGL_STREAM_NEW_FRAME_AVAILABLE_KHR, queries
of the most recently produced frame will indicate this frame, and
acquire operations will be able to retrieve this frame. If set to
EGL_TRUE, then until any asynchronous rendering for this frame
completes, the state will not update, any queries of the most
recently produced frame will only indicate the frame whose rendering
most recently completed, and acquire operations will only obtain
older completed frames.
The default value is EGL_FALSE. If set to EGL_TRUE, the value of
EGL_STREAM_FIFO_LENGTH_KHR must be non-zero, or an EGL_BAD_MATCH
error will be generated.
Replace first two sentences of section "3.10.4.4 EGL_PRODUCER_FRAME
Attribute" in the EGL_KHR_stream extension
The EGL_PRODUCER_FRAME_KHR attribute indicates how many image
frames have become available for the consumer to acquire. This is
also known as the "frame number" of the most recent ready frame
(where the first frame inserted has a frame number of 1). In
asynchronous operation, this is the frame most recently inserted by
the producer. In synchronous operation, this is the frame whose
image content generation has most recently finished.
Replace contents of section "3.10.4.x+3 EGL_STREAM_TIME_PRODUCER_KHR" in
the EGL_KHR_stream_fifo extension
This indicates the timestamp of the most recent ready frame in the
EGLStream (i.e. frame number EGL_PRODUCER_FRAME_KHR).
Replace the second through fifth paragraphs of "3.10.5.2 EGLStream operation
in fifo mode" in the EGL_KHR_stream_fifo extension.
In fifo mode the EGLStream conceptually operates as a fifo. An image
frame in the fifo is considered "ready" if all operations on the
image scheduled prior to its insertion in the stream have completed,
or if the value of EGL_STREAM_FIFO_SYNCHRONOUS_NV is EGL_FALSE.
When the consumer wants to consume a new image frame, behavior
depends on the state of the EGLStream. If the state is
EGL_STREAM_STATE_NEW_FRAME_AVAILABLE_KHR then the image frame at the
tail of the fifo is ready, and is removed from the fifo. If the
state is EGL_STREAM_STATE_OLD_FRAME_AVAILABLE_KHR then the fifo has
no ready image frames and the consumer consumes the same frame that
it most recently consumed. Otherwise there are no image frames
available to consume (behavior in this case is described in the
documentation for each type of consumer - see section "3.10.2
Connecting an EGLStream to a consumer").
When EGL_STREAM_FIFO_SYNCHRONOUS_NV is EGL_FALSE, any consumer
operations which read from the image frame must implicitly wait for
any producer operations used to generate the image contents to
complete. Apart from the assumption that any such operations will
eventually finish, there are no guaranteed bounds on the time
required, and therefore no guaranteed bounds on when the consumer's
operations will complete. In cases where reusing a previous frame is
preferable to unknown latency between the time a consumer acquires a
new frame and the time its processing of that frame is done,
EGL_STREAM_FIFO_SYNCHRONOUS_NV should be set to EGL_TRUE.
If there is no new ready frame at the tail of the fifo when the
consumer is finished consuming an image frame then the consumer
holds on to the image frame in case it needs to be consumed again
later (this happens if the consumer wants to consume another image
frame before the producer has inserted a new image frame into the
fifo, or before any such frame has finished rendering in the case of
synchronous operation). In this case the state of the EGLStream
will be EGL_STREAM_STATE_OLD_FRAME_AVAILABLE_KHR until a new image
frame is ready (or until the state becomes
EGL_STREAM_STATE_DISCONNECTED_KHR).
The producer inserts image frames at the head of the fifo. If the
fifo is full (already contains <L> image frames, where <L> is the
value of the EGL_STREAM_FIFO_LENGTH_KHR attribute) then the producer
is stalled until the fifo is no longer full. When there is at
least one ready frame at the tail of the fifo, the EGLStream state
is EGL_STREAM_STATE_NEW_FRAME_AVAILABLE_KHR.
Issues
None
Revision History
#4 (October 27, 2016) Daniel Kartch
- Clean up for publication
#3 (September 30, 2015) Daniel Kartch
- Reserve enum.
#2 (March 30, 2015) Daniel Kartch
- Fix grammatical and typographical errors.
#1 (March 27, 2015) Daniel Kartch
- Initial draft
