Name
EXT_stream_consumer_egloutput
Name Strings
EGL_EXT_stream_consumer_egloutput
Contributors
Daniel Kartch
James Jones
Christopher James Halse Rogers
Contacts
Daniel Kartch, NVIDIA (dkartch 'at' nvidia.com)
Status
Complete
Version
Version 7 - December 28th, 2015
Number
EGL Extension #81
Extension Type
EGL display extension
Dependencies
Requires EGL_KHR_stream.
Requires EGL_EXT_output_base.
Overview
Increasingly, EGL and its client APIs are being used in place of
"native" rendering APIs to implement the basic graphics
functionality of native windowing systems. This creates demand
for a method to initialize EGL displays and surfaces directly on
top of native GPU or device objects rather than native window
system objects. The mechanics of enumerating the underlying
native devices and constructing EGL displays and surfaces from
them have been solved in various platform and implementation-
specific ways. The EGL device family of extensions offers a
standardized framework for bootstrapping EGL without the use of
any underlying "native" APIs or functionality.
This extension describes how to bind EGLOutputLayerEXTs as stream
consumers to send rendering directly to a display device without an
intervening window system.
New Types
None
New Functions
EGLBoolean eglStreamConsumerOutputEXT(
EGLDisplay dpy,
EGLStreamKHR stream,
EGLOutputLayerEXT layer);
New Tokens
None
Replace section "3.10.2.1 No way to connect consumer to EGLStream" in
the EGL_KHR_stream extension with:
3.10.2.1 EGLOutputLayerEXT consumer
Call
EGLBoolean eglStreamConsumerOutputEXT(
EGLDisplay dpy,
EGLStreamKHR stream,
EGLOutputLayerEXT layer);
to connect <output> as the consumer of <stream>.
On failure EGL_FALSE is returned and an error is generated.
- EGL_BAD_DISPLAY is generated if <dpy> is not a valid,
initialized EGLDisplay.
- EGL_BAD_STREAM_KHR is generated if <stream> is not a valid
EGLStreamKHR created for <dpy>.
- EGL_BAD_STATE_KHR is generated if <stream> is not in state
EGL_STREAM_STATE_CREATED_KHR.
- EGL_BAD_OUTPUT_LAYER_EXT is generated if <layer> is not a
valid EGLOutputLayerEXT created for <dpy>.
On success, <layer> is bound to <stream>, <stream> is placed in the
EGL_STREAM_STATE_CONNECTING_KHR state, and EGL_TRUE is returned.
Initially, no changes occur to the image displayed on <layer>. When
the <stream> enters state EGL_STREAM_STATE_NEW_FRAME_AVAILABLE_KHR,
<layer> will begin displaying frames, without further action
required on the application's part, as they become available, taking
into account any timestamps, swap intervals, or other limitations
imposed by the stream or producer attributes.
Modifying the output layer's display mode is outside the scope of
EGL. If the producer does not automatically adjust it's dimensions
to match the consumer, then the caller is responsible for ensuring
that the producer's frame size and the display mode are compatible
before the first frame is placed in the stream. If these are not
compatible, the behavior is implementation dependent, but may not
hang or terminate. Among other possible behaviors, the
implementation may scale or letterbox the frames, post a blank image
to the display, or discard the frames without posting.
Many display mode setting APIs have a mechanism that restricts
which of their clients can modify output attributes. Since
EGLOutput stream consumers will need to modify output attributes,
they require access to a display mode setting API handle with the
appropriate capabilities. If the application fails to provide
access to such permissions or privileged native objects when creating
the EGLDisplay associated with an output stream consumer and EGL is
not able to acquire them, the behavior of the stream consumer will be
undefined. Similarly, if the application or operating system revokes
the output modification permissions provided to the EGLDisplay, or
revokes permissions from the privileged native objects provided to
the EGLDisplay, future behavior of the stream consumer is undefined.
If <layer> is rebound to a different stream by a subsequent call
to eglStreamConumerOutputEXT, then <stream> will be placed into the
EGL_STREAM_STATE_DISCONNECTED_KHR state.
Issues
1. What happens to the display if the stream is destroyed while
still connected?
RESOLVED: The EGLOutputLayer will maintain a reference to the
last frame consumed from the stream until a new frame is
received (through connection of a new stream or some interface
defined by another extension) or until the EGLOutputLayer is
destroyed. Until one of these occurs, the output will ensure
that memory containing the frame remains valid, but will do no
further reprogramming of the display layer state. In the event
the EGLOutputLayer is destroyed, the reference to the frame is
released, and random/invalid images may subsequently be
displayed if the application does not take separate action to
reprogram or disable the display. This behavior should
probably be defined in the EGL_EXT_output_base extension and
be shared regardless of the means by which the displayed image
was posted.
2. What happens to the stream if the display output is flipped to a
different image by a mechanism outside EGL?
RESOLVED: Using native display APIs to directly change the
visible framebuffer while an EGLStream is bound to an
EGLOutputLayer has undefined results which depend on the
implementation, the display capabilities, and the
compatibility of the competing framebuffer sizes and formats.
A partial list of possible outcomes includes one interface
overriding the other, the visible image alternating between
the two frames, or the visible image becoming corrupted or
displaying random memory.
3. What happens if the display mode settings are not compatible
with the size and/or format of the incoming frames?
RESOLVED: The behavior is implementation and device dependent.
The display may not terminate or hang, but otherwise may modify
or ignore the incoming frames. Additional extensions can be
defined if greater control of this behavior is desired.
4. How can changes to the display mode settings be synchronized
with changes in the size/format of frames generated by the
producer?
RESOLVED: The base specification will assume that the
producer's frame size and the output layer's display mode are
established at initialization time and do not change for the
life of the stream. The ability to modify these states and
synchronize such modifications must be provided by additional
extensions.
5. The EGL_KHR_stream_producer_eglsurface extension, which is
likely to be used as a producer for streams directed to outputs,
explicitly ignores eglSwapInterval. But a swap interval is
desirable when directing output to a display screen. How can
this functionality be provided?
RESOLVED: EGL_SWAP_INTERVAL_EXT added as an attribute to output
layers in the EGL_EXT_output_base specification.
6. How does EGL acquire the necessary capabilities to modify
display attributes from the application?
RESOLVED: The application provides EGL with the necessary
permissions or native object handles when creating its EGLDisplay.
7. What is the behavior of EGLOutput stream consumers when EGL does
not have the necessary permissions to modify output attributes?
RESOLVED: The behavior is undefined. Other options would be to
block consumption of frames indefinitely until permissions are
acquired via unspecified or native mechanisms, or to return
frames to the producer immediately when consumption fails due to
lack of permissions. However, both of these options may rely on
assumptions about the behavior of the underlying mode setting
APIs. Future extensions may refined the behavior of streams in
this case.
Revision History:
#7 (December 28th, 2015) James Jones
- Added issues 6 and 7.
- Added language to document the resolution of issues 6 and 7.
#6 (August 22nd, 2014) James Jones
- Marked complete.
- Marked remaining unresolved issues resolved.
- Added an "Extension Type" section.
- Listed Daniel as the contact.
#5 (June 5th, 2014) Daniel Kartch
- Added resolution for issues 3 and 4 and updated description
accordingly.
#4 (May 28th, 2014) Daniel Kartch
- Added Issue 5 and its resolution.
#3 (January 17th, 2014) Daniel Kartch
- Updated issues section with some proposed solutions and new
issues.
#2 (November 13th, 2013) Daniel Kartch
- Replaced EGLOutputEXT with EGLOutputLayerEXT, as per changes
to EXT_output_base.
- Updated possible error states to reflect requirement that
output handles are now associated with a particular
EGLDisplay.
#1 (October 28th, 2013) Daniel Kartch
- Initial draft
