1Name 2 3 NV_stream_reset 4 5Name Strings 6 7 EGL_NV_stream_reset 8 9Contributors 10 11 Daniel Kartch 12 13Contacts 14 15 Daniel Kartch, NVIDIA (dkartch 'at' nvidia.com) 16 17Status 18 19 Draft 20 21Version 22 23 Version 6 - October 27, 2016 24 25Number 26 27 EGL Extension #112 28 29Extension Type 30 31 EGL display extension 32 33Dependencies 34 35 Requires the EGL_KHR_stream extension. 36 37 Modifies the EGL_KHR_stream_fifo extension. 38 39 Modifies the EGL_KHR_stream_consumer_gltexture extension. 40 41 Modifies the EGL_EXT_stream_consumer_egloutput extension. 42 43 Interacts with the EGL_KHR_stream_cross_process_fd and 44 EGL_NV_stream_remote extensions. 45 46 This extension is written based on the wording of version 26 of the 47 EGL_KHR_stream extension. 48 49Overview 50 51 The base stream extension requires that, once the producer inserts 52 the first frame into the stream, at least one frame is always 53 available to be acquired by the consumer until the stream 54 disconnects. However, there are some use cases in which the producer 55 or the consumer may wish to allow the stream to empty without 56 permanently disconnecting. 57 58 An example of a use case where the producer may wish to empty the 59 stream is a security or rear-view camera which temporarily stops 60 producing new frames, perhaps due to a hardware reset. Continuing to 61 display the last frame available would produce a false impression of 62 the current state, and should be avoided for safety reasons. A 63 better solution would be to let the consumer know there was no 64 available image, so that it could take appropriate actions, and then 65 recover when the camera begins streaming again. 66 67 This use case could be handled with existing functionality by 68 disconnecting and destroying the stream and then recreating and 69 reconnecting it when new frames are available. However, this can be 70 burdensome, particularly when the producer and consumer reside in 71 separate processes. 72 73 An example of a use case where the consumer may wish to empty the 74 stream is an image processer which operates on each frame exactly 75 once. After processing, it will not waste resources operating on the 76 same frame a second time. This use case can be handled by carefully 77 monitoring the availability of a new frame before performing an 78 acquire operation. But returning the buffer(s) as soon as they are 79 no longer needed allows for better resource management. 80 81 This extension allows a stream to be completely drained of existing 82 frames by the consumer or flushed of existing frames by the producer 83 without disconnecting, so that processing may continue again when 84 new frames are produced. 85 86New Functions 87 88 EGLBoolean eglResetStreamNV( 89 EGLDisplay dpy, 90 EGLStreamKHR stream); 91 92New Tokens 93 94 Accepted as an attribute in the <attrib_list> parameter of 95 eglCreateStreamKHR and the <attrib> parameter of eglQueryStreamKHR: 96 97 EGL_SUPPORT_RESET_NV 0x3334 98 EGL_SUPPORT_REUSE_NV 0x3335 99 100To table "3.10.4.4 EGLStream Attributes", add entry 101 102 Attribute Read/Write Type Section 103 -------------------------- ---------- ------ ---------- 104 EGL_SUPPORT_RESET_NV io EGLint 3.10.4.x 105 EGL_SUPPORT_REUSE_NV io EGLint 3.10.4.x+1 106 107Modify entries in the list of state transitions in "3.10.4.3 108EGL_STREAM_STATE_KHR Attribute" 109 110 EGL_STREAM_STATE_EMPTY_KHR -> 111 EGL_STREAM_STATE_NEW_FRAME_AVAILABLE_KHR 112 Occurs when the producer inserts the first image frame and any 113 subsequent frame after the stream has been drained. 114 115 EGL_STREAM_STATE_OLD_FRAME_AVAILABLE_KHR -> 116 EGL_STREAM_STATE_NEW_FRAME_AVAILABLE_KHR 117 Occurs when the producer inserts a new image frame and only 118 previously consumed frames are available. 119 120 EGL_STREAM_STATE_NEW_FRAME_AVAILABLE_KHR -> 121 EGL_STREAM_STATE_OLD_FRAME_AVAILABLE_KHR 122 Occurs when the consumer begins examining the last unconsumed 123 frame and reuse of old frames is enabled. 124 125Add entries to the list of state transitions in "3.10.4.3 126EGL_STREAM_STATE_KHR Attribute" 127 128 EGL_STREAM_STATE_OLD_FRAME_AVAILABLE_KHR -> 129 EGL_STREAM_STATE_EMPTY_KHR 130 Occurs when the stream is reset. 131 132 EGL_STREAM_STATE_NEW_FRAME_AVAILABLE_KHR -> 133 EGL_STREAM_STATE_EMPTY_KHR 134 Occurs when the stream is reset or, if reuse of old frames is 135 disabled, when the consumer begins examining the last unconsumed 136 frame. 137 138Add new sections at the end of section "3.10.4 EGLStream Attributes" 139 140 3.10.4.x EGL_SUPPORT_RESET_NV Attribute 141 142 The EGL_SUPPORT_RESET_NV attribute may only be set when the stream 143 is created. By default, it is EGL_FALSE. If set to EGL_TRUE, the 144 stream will allow restoration of the stream state back to 145 EGL_STREAM_STATE_EMPTY_KHR state from 146 EGL_STREAM_STATE_OLD_FRAME_AVAILABLE_KHR or 147 EGL_STREAM_STATE_NEW_FRAME_AVAILABLE_KHR, releasing existing frames, 148 as described in section 3.10.5.x. 149 150 Not all consumers are required to support stream resets. Attempting 151 to attach a consumer which does not support resets to a stream with 152 EGL_SUPPORT_RESET_NV set to EGL_TRUE will fail with an 153 EGL_BAD_MATCH error. 154 155 Not all producers will provide a means to reset streams themselves, 156 but any producer may be connected to a stream which supports resets 157 and may be used with the eglStreamResetNV function. 158 159 3.10.4.x+1 EGL_SUPPORT_REUSE_NV Attribute 160 161 The EGL_SUPPORT_REUSE_NV attribute may only be set when the stream 162 is created. By default, it is EGL_TRUE. If EGL_TRUE, then when the 163 consumer acquires the last available image frame from the stream, it 164 will be held for reuse until a new frame is inserted to replace it. 165 If EGL_FALSE, no frames will be available to the consumer until the 166 producer inserts a new one. 167 168Modify third paragraph of "3.10.5.1 EGLStream operation in mailbox mode" 169 170 The consumer retrieves the image frame from the mailbox and 171 examines it. When the consumer is finished examining the image 172 frame it is either placed back in the mailbox (if the mailbox is 173 empty, supports reuse of frames, and has not been reset) or 174 discarded (otherwise). 175 176If EGL_KHR_stream_fifo is present, insert at beginning of fourth paragraph 177of "3.10.5.2 EGLStream operation in fifo mode" 178 179 If the EGL_SUPPORT_REUSE_NV attribute is EGL_TRUE and the stream has 180 not been reset since the image frame was consumed, then if the fifo 181 is empty ... 182 183Insert a new paragraph after the above 184 185 If the EGL_SUPPORT_REUSE_NV attribute is EGL_FALSE or the stream has 186 been reset, then if the fifo is empty when the consumer is finished 187 consuming an image frame, the frame is discarded and the stream is 188 left in the EGL_STREAM_STATE_EMPTY_KHR state until new frames are 189 produced. 190 191Add a new section to "3.10.5 EGLStream operation" 192 193 3.10.5.x EGLStream reset 194 195 For resource management or safety reasons, it may be necessary to 196 invalidate and reclaim frames pending in the stream. This is only 197 possible if the stream's EGL_SUPPORT_RESET_NV attribute is set to 198 EGL_TRUE. 199 200 Stream resets cause any unconsumed image frames waiting in the 201 stream to be immediately discarded, and place the stream in the 202 EGL_STREAM_STATE_EMPTY_KHR state. Frames currently held by the 203 consumer are not immediately affected, but will be discarded once 204 released, even if the stream would normally hold old frames for 205 reuse. After the reset, new frames inserted by the producer are 206 processed normally. 207 208 Stream resets may be issued by some producers as described in their 209 specifications, and may also be triggered by the application calling 210 211 EGLBoolean eglResetStreamNV( 212 EGLDisplay dpy, 213 EGLStreamKHR stream) 214 215 On success, EGL_TRUE is returned and a reset of the stream is 216 initiated. On failure, EGL_FALSE is returned and an error is 217 generated. 218 219 - EGL_BAD_DISPLAY is generated if <dpy> is not a valid 220 EGLDisplay. 221 222 - EGL_NOT_INITIALIZED is generated if <dpy> is not initialized. 223 224 - EGL_BAD_STREAM_KHR is generated if <stream> is not a valid 225 EGLStream created for <dpy>. 226 227 - EGL_BAD_STATE_KHR is generated if <stream> is in 228 EGL_STREAM_STATE_CREATED_KHR, EGL_STREAM_STATE_CONNECTING_KHR, 229 or EGL_STREAM_STATE_DISCONNECTED_KHR state. 230 231 - EGL_BAD_ACCESS is generated if <stream>'s 232 EGL_SUPPORT_RESET_NV attribute is not EGL_TRUE. 233 234 If a stream is already in the EGL_STREAM_STATE_EMPTY_KHR state, a 235 reset will have no effect. 236 237If EGL_KHR_stream_cross_process_fd or EGL_NV_stream_remote is present, 238add to the list of errors above 239 240 - EGL_BAD_ACCESS is generated if <stream> represents the 241 consumer endpoint of a stream whose producer endpoint is 242 represented by a different EGLStreamKHR handle (e.g. for 243 cross-process streams). 244 245If EGL_KHR_stream_consumer_gltexture is supported, modify the first 246sentence of the fifth paragraph of the description of 247eglStreamConsumerAcquireKHR 248 249 If the producer has not inserted any new image frames since the 250 last call to eglStreamConsumerAcquireKHR, and the stream has been 251 reset or does not support reuse of frames, then 252 eglStreamConsumerAcquireKHR will fail. If it has not been reset and 253 reuse is supported, then eglStreamConsumerAcquireKHR will "latch" 254 the same image frame it latched last time 255 eglStreamConsumerAcquireKHR was called. 256 257If EGL_EXT_stream_consumer_egloutput is supported, add to the 258description if eglStreamConsumerOutputEXT 259 260 If the stream is reset to the EGL_STREAM_STATE_EMPTY_KHR state, any 261 currently displayed frame will be released, and the displayed image 262 will be reset to some default state determined by the display 263 hardware and the implementation. Possible behavior includes, but is 264 not limited to, displaying a black screen, displaying a default 265 splash screen, displaying a "no input" message, or powering off the 266 display. If and when the stream again enters the 267 EGL_STREAM_STATE_NEW_FRAME_AVAILABLE_KHR state, processing of frames 268 will resume as described above. 269 270Issues 271 272 1. When this extension is present, should all streams automatically 273 support resetting? 274 275 RESOLVED: No. Applications which are not aware of this extension 276 may not be prepared to handle an unexpected return to the EMPTY 277 state. Therefore support for this feature must be explicitly 278 requested. 279 280Revision History 281 282 #6 (October 27, 2016) Daniel Kartch 283 - Clean up for publication 284 285 #5 (July 23rd, 2015) Daniel Kartch 286 - Added interaction with cross-process streams. 287 288 #4 (July 22nd, 2015) Daniel Kartch 289 - Added enum values. 290 291 #3 (July 20th, 2015) Daniel Kartch 292 - Changed to NV specification 293 - Removed flush option from eglResetStream. Resetting will 294 always flush pending frames. 295 - Added EGL_SUPPORT_REUSE_NV flag to control whether released 296 frames are saved or discarded immediately. 297 - Removed reference to unpublished stream_sequence extension. 298 299 #2 (August 21th, 2014) Daniel Kartch 300 - Added paragraph to indicate that producers do not impose 301 restrictions on use of reset. 302 - Clarified consumer behavior on reset. 303 - Added interactions with GL texture and EGLOutput consumers. 304 305 #1 (August 12th, 2014) Daniel Kartch 306 - Initial draft 307