1Name 2 3 EXT_stream_consumer_egloutput 4 5Name Strings 6 7 EGL_EXT_stream_consumer_egloutput 8 9Contributors 10 11 Daniel Kartch 12 James Jones 13 Christopher James Halse Rogers 14 15Contacts 16 17 Daniel Kartch, NVIDIA (dkartch 'at' nvidia.com) 18 19Status 20 21 Complete 22 23Version 24 25 Version 7 - December 28th, 2015 26 27Number 28 29 EGL Extension #81 30 31Extension Type 32 33 EGL display extension 34 35Dependencies 36 37 Requires EGL_KHR_stream. 38 Requires EGL_EXT_output_base. 39 40Overview 41 42 Increasingly, EGL and its client APIs are being used in place of 43 "native" rendering APIs to implement the basic graphics 44 functionality of native windowing systems. This creates demand 45 for a method to initialize EGL displays and surfaces directly on 46 top of native GPU or device objects rather than native window 47 system objects. The mechanics of enumerating the underlying 48 native devices and constructing EGL displays and surfaces from 49 them have been solved in various platform and implementation- 50 specific ways. The EGL device family of extensions offers a 51 standardized framework for bootstrapping EGL without the use of 52 any underlying "native" APIs or functionality. 53 54 This extension describes how to bind EGLOutputLayerEXTs as stream 55 consumers to send rendering directly to a display device without an 56 intervening window system. 57 58New Types 59 60 None 61 62New Functions 63 64 EGLBoolean eglStreamConsumerOutputEXT( 65 EGLDisplay dpy, 66 EGLStreamKHR stream, 67 EGLOutputLayerEXT layer); 68 69New Tokens 70 71 None 72 73Replace section "3.10.2.1 No way to connect consumer to EGLStream" in 74the EGL_KHR_stream extension with: 75 76 3.10.2.1 EGLOutputLayerEXT consumer 77 78 Call 79 80 EGLBoolean eglStreamConsumerOutputEXT( 81 EGLDisplay dpy, 82 EGLStreamKHR stream, 83 EGLOutputLayerEXT layer); 84 85 to connect <output> as the consumer of <stream>. 86 87 On failure EGL_FALSE is returned and an error is generated. 88 89 - EGL_BAD_DISPLAY is generated if <dpy> is not a valid, 90 initialized EGLDisplay. 91 92 - EGL_BAD_STREAM_KHR is generated if <stream> is not a valid 93 EGLStreamKHR created for <dpy>. 94 95 - EGL_BAD_STATE_KHR is generated if <stream> is not in state 96 EGL_STREAM_STATE_CREATED_KHR. 97 98 - EGL_BAD_OUTPUT_LAYER_EXT is generated if <layer> is not a 99 valid EGLOutputLayerEXT created for <dpy>. 100 101 On success, <layer> is bound to <stream>, <stream> is placed in the 102 EGL_STREAM_STATE_CONNECTING_KHR state, and EGL_TRUE is returned. 103 Initially, no changes occur to the image displayed on <layer>. When 104 the <stream> enters state EGL_STREAM_STATE_NEW_FRAME_AVAILABLE_KHR, 105 <layer> will begin displaying frames, without further action 106 required on the application's part, as they become available, taking 107 into account any timestamps, swap intervals, or other limitations 108 imposed by the stream or producer attributes. 109 110 Modifying the output layer's display mode is outside the scope of 111 EGL. If the producer does not automatically adjust it's dimensions 112 to match the consumer, then the caller is responsible for ensuring 113 that the producer's frame size and the display mode are compatible 114 before the first frame is placed in the stream. If these are not 115 compatible, the behavior is implementation dependent, but may not 116 hang or terminate. Among other possible behaviors, the 117 implementation may scale or letterbox the frames, post a blank image 118 to the display, or discard the frames without posting. 119 120 Many display mode setting APIs have a mechanism that restricts 121 which of their clients can modify output attributes. Since 122 EGLOutput stream consumers will need to modify output attributes, 123 they require access to a display mode setting API handle with the 124 appropriate capabilities. If the application fails to provide 125 access to such permissions or privileged native objects when creating 126 the EGLDisplay associated with an output stream consumer and EGL is 127 not able to acquire them, the behavior of the stream consumer will be 128 undefined. Similarly, if the application or operating system revokes 129 the output modification permissions provided to the EGLDisplay, or 130 revokes permissions from the privileged native objects provided to 131 the EGLDisplay, future behavior of the stream consumer is undefined. 132 133 If <layer> is rebound to a different stream by a subsequent call 134 to eglStreamConumerOutputEXT, then <stream> will be placed into the 135 EGL_STREAM_STATE_DISCONNECTED_KHR state. 136 137Issues 138 139 1. What happens to the display if the stream is destroyed while 140 still connected? 141 142 RESOLVED: The EGLOutputLayer will maintain a reference to the 143 last frame consumed from the stream until a new frame is 144 received (through connection of a new stream or some interface 145 defined by another extension) or until the EGLOutputLayer is 146 destroyed. Until one of these occurs, the output will ensure 147 that memory containing the frame remains valid, but will do no 148 further reprogramming of the display layer state. In the event 149 the EGLOutputLayer is destroyed, the reference to the frame is 150 released, and random/invalid images may subsequently be 151 displayed if the application does not take separate action to 152 reprogram or disable the display. This behavior should 153 probably be defined in the EGL_EXT_output_base extension and 154 be shared regardless of the means by which the displayed image 155 was posted. 156 157 2. What happens to the stream if the display output is flipped to a 158 different image by a mechanism outside EGL? 159 160 RESOLVED: Using native display APIs to directly change the 161 visible framebuffer while an EGLStream is bound to an 162 EGLOutputLayer has undefined results which depend on the 163 implementation, the display capabilities, and the 164 compatibility of the competing framebuffer sizes and formats. 165 A partial list of possible outcomes includes one interface 166 overriding the other, the visible image alternating between 167 the two frames, or the visible image becoming corrupted or 168 displaying random memory. 169 170 3. What happens if the display mode settings are not compatible 171 with the size and/or format of the incoming frames? 172 173 RESOLVED: The behavior is implementation and device dependent. 174 The display may not terminate or hang, but otherwise may modify 175 or ignore the incoming frames. Additional extensions can be 176 defined if greater control of this behavior is desired. 177 178 4. How can changes to the display mode settings be synchronized 179 with changes in the size/format of frames generated by the 180 producer? 181 182 RESOLVED: The base specification will assume that the 183 producer's frame size and the output layer's display mode are 184 established at initialization time and do not change for the 185 life of the stream. The ability to modify these states and 186 synchronize such modifications must be provided by additional 187 extensions. 188 189 5. The EGL_KHR_stream_producer_eglsurface extension, which is 190 likely to be used as a producer for streams directed to outputs, 191 explicitly ignores eglSwapInterval. But a swap interval is 192 desirable when directing output to a display screen. How can 193 this functionality be provided? 194 195 RESOLVED: EGL_SWAP_INTERVAL_EXT added as an attribute to output 196 layers in the EGL_EXT_output_base specification. 197 198 6. How does EGL acquire the necessary capabilities to modify 199 display attributes from the application? 200 201 RESOLVED: The application provides EGL with the necessary 202 permissions or native object handles when creating its EGLDisplay. 203 204 7. What is the behavior of EGLOutput stream consumers when EGL does 205 not have the necessary permissions to modify output attributes? 206 207 RESOLVED: The behavior is undefined. Other options would be to 208 block consumption of frames indefinitely until permissions are 209 acquired via unspecified or native mechanisms, or to return 210 frames to the producer immediately when consumption fails due to 211 lack of permissions. However, both of these options may rely on 212 assumptions about the behavior of the underlying mode setting 213 APIs. Future extensions may refined the behavior of streams in 214 this case. 215 216Revision History: 217 218 #7 (December 28th, 2015) James Jones 219 - Added issues 6 and 7. 220 - Added language to document the resolution of issues 6 and 7. 221 222 #6 (August 22nd, 2014) James Jones 223 - Marked complete. 224 - Marked remaining unresolved issues resolved. 225 - Added an "Extension Type" section. 226 - Listed Daniel as the contact. 227 228 #5 (June 5th, 2014) Daniel Kartch 229 - Added resolution for issues 3 and 4 and updated description 230 accordingly. 231 232 #4 (May 28th, 2014) Daniel Kartch 233 - Added Issue 5 and its resolution. 234 235 #3 (January 17th, 2014) Daniel Kartch 236 - Updated issues section with some proposed solutions and new 237 issues. 238 239 #2 (November 13th, 2013) Daniel Kartch 240 - Replaced EGLOutputEXT with EGLOutputLayerEXT, as per changes 241 to EXT_output_base. 242 - Updated possible error states to reflect requirement that 243 output handles are now associated with a particular 244 EGLDisplay. 245 246 #1 (October 28th, 2013) Daniel Kartch 247 - Initial draft 248 249