| 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 |
| |
