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 as the consumer of . On failure EGL_FALSE is returned and an error is generated. - EGL_BAD_DISPLAY is generated if is not a valid, initialized EGLDisplay. - EGL_BAD_STREAM_KHR is generated if is not a valid EGLStreamKHR created for . - EGL_BAD_STATE_KHR is generated if is not in state EGL_STREAM_STATE_CREATED_KHR. - EGL_BAD_OUTPUT_LAYER_EXT is generated if is not a valid EGLOutputLayerEXT created for . On success, is bound to , is placed in the EGL_STREAM_STATE_CONNECTING_KHR state, and EGL_TRUE is returned. Initially, no changes occur to the image displayed on . When the enters state EGL_STREAM_STATE_NEW_FRAME_AVAILABLE_KHR, 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 is rebound to a different stream by a subsequent call to eglStreamConumerOutputEXT, then 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