1Name 2 3 NV_stream_consumer_eglimage 4 5Name Strings 6 7 EGL_NV_stream_consumer_eglimage 8 9Contributors 10 11 Mukund Keshava 12 James Jones 13 Daniel Kartch 14 Sandeep Shinde 15 Pyarelal Knowles 16 Leo Xu 17 18Contacts 19 20 Mukund Keshava, NVIDIA (mkeshava 'at' nvidia.com) 21 22Status 23 24 Draft 25 26Version 27 28 Version 3 - November 27, 2019 29 30Number 31 32 EGL Extension #139 33 34Extension Type 35 36 EGL display extension 37 38Dependencies 39 40 Requires the EGL_KHR_stream extension. 41 42 Requires the EGL_KHR_reusable_sync extension. 43 44 This extension is written against the wording of the EGL 1.5 45 Specification 46 47Overview 48 49 An EGLStream consists of a sequence of image frames. This extension 50 allows these frames to be acquired as EGLImages. Frames from the 51 stream would be used as the content for the EGLImage. 52 53New Procedures and Functions 54 55 EGLBoolean eglStreamImageConsumerConnectNV( 56 EGLDisplay dpy, 57 EGLStreamKHR stream, 58 EGLint num_modifiers, 59 EGLuint64KHR *modifiers, 60 EGLAttrib* attrib_list); 61 62 EGLint eglQueryStreamConsumerEventNV( 63 EGLDisplay dpy, 64 EGLStreamKHR stream, 65 EGLTime timeout, 66 EGLenum *event, 67 EGLAttrib *aux); 68 69 EGLBoolean eglStreamAcquireImageNV( 70 EGLDisplay dpy, 71 EGLStreamKHR stream, 72 EGLImage *pImage, 73 EGLSync sync); 74 75 EGLBoolean eglStreamReleaseImageNV( 76 EGLDisplay dpy, 77 EGLStreamKHR stream, 78 EGLImage image, 79 EGLSync sync); 80 81New Tokens 82 83 Accepted by the <target> parameter of eglCreateImage: 84 85 EGL_STREAM_CONSUMER_IMAGE_NV 0x3373 86 87 Returned as an <event> from eglQueryStreamConsumerEventNV: 88 89 EGL_STREAM_IMAGE_ADD_NV 0x3374 90 EGL_STREAM_IMAGE_REMOVE_NV 0x3375 91 EGL_STREAM_IMAGE_AVAILABLE_NV 0x3376 92 93Add to section "3.9 EGLImage Specification and Management" of 94the EGL 1.5 Specification, in the description of eglCreateImage: 95 96 "Values accepted for <target> are listed in Table 3.10, below. 97 98 +-------------------------------+-----------------------------------+ 99 | <target> | Notes | 100 +-------------------------------+-----------------------------------+ 101 | EGL_STREAM_CONSUMER_IMAGE_NV | Used with EGLStream objects | 102 +-------------------------------+-----------------------------------+ 103 Table 3.10: Legal values for eglCreateImage target parameter. 104 105 If <target> is EGL_STREAM_CONSUMER_IMAGE_NV, a new EGLImage will be 106 created for the next consumer image frame in the EGLStream 107 referenced by <buffer> which is not currently bound to an EGLImage. 108 If the stream's producer reuses memory buffers for multiple image 109 frames, then an EGLImage obtained in this way will persist for the 110 next image frame that uses the same buffer, unless destroyed in 111 the interim. Otherwise, the user must create a new EGLImage for 112 every frame. Creating the EGLImage does not guarantee that the 113 image contents will be ready for use. The EGLImage must first be 114 acquired from the stream after creation. 115 116 If the EGLImage created for a consumer image frame is destroyed via 117 eglDestroyImage, a new EGLImage needs to be created via 118 eglCreateImage for the same consumer image frame. 119 120 <dpy> must be a valid initialized display. <ctx> must be 121 EGL_NO_CONTEXT. <buffer> must be a handle to a valid EGLStream 122 object, cast into the type EGLClientBuffer. 123 124 Add to the list of error conditions for eglCreateImage: 125 126 "* If <target> is EGL_STREAM_CONSUMER_IMAGE_NV and <buffer> is 127 not a valid stream handle associated with <dpy>, the error 128 EGL_BAD_STREAM_KHR is generated. 129 130 * If <target> is EGL_STREAM_CONSUMER_IMAGE_NV, and <ctx> is not 131 EGL_NO_CONTEXT, the error EGL_BAD_PARAMETER is generated. 132 133 * If <target> is EGL_STREAM_CONSUMER_IMAGE_NV, and there are no 134 buffers in the <stream> currently or if there are no buffers 135 associated with the stream that are not already bound to 136 EGLImages EGL_BAD_ACCESS is generated. 137 138 eglCreateImage needs to be called with EGL_STREAM_CONSUMER_IMAGE_NV 139 as the <target> for every valid buffer in the EGLStream. 140 141Add section "3.10.2 Connecting an EGLStream to a consumer" in the 142EGL_KHR_stream extension with this: 143 144 3.10.2.2 EGLImage consumer 145 146 Call 147 148 EGLBoolean eglStreamImageConsumerConnectNV( 149 EGLDisplay dpy, 150 EGLStreamKHR stream, 151 EGLint num_modifiers, 152 EGLuint64KHR *modifiers, 153 EGLAttrib* attrib_list); 154 155 to connect the EGLImage consumer to the <stream>. An EGLImage 156 consumer allows image frames inserted in the stream to be received 157 as EGLImages, which can then be bound to any other object which 158 supports EGLImage. For each image frame, an EGLImage must first be 159 created as described in section "3.9 EGLImage Specification and 160 Management" of the EGL 1.5 Specification, and then the frame 161 contents must be latched to the EGLImage as described below. 162 163 In <modifiers> the consumer can advertise an optional list of 164 supported DRM modifiers as described in 165 EXT_image_dma_buf_import_modifiers. This information could be 166 used by the producer to generate consumer supported image frames. 167 168 If not NULL, <attrib_list> points to an array of name/value 169 pairs, terminated by EGL_NONE. Currently no attributes are 170 supported. 171 172 On success, EGL_TRUE is returned. 173 174 - <stream> state is set to EGL_STREAM_STATE_CONNECTING_KHR 175 allowing the producer to be connected. 176 177 On failure, EGL_FALSE is returned and an error is generated. 178 179 - EGL_BAD_DISPLAY is generated if <dpy> is not the handle of a 180 valid EGLDisplay object. 181 182 - EGL_BAD_STREAM_KHR is generated if <stream> is not a valid 183 valid stream handle associated with <dpy>. 184 185 - EGL_BAD_STATE_KHR is generated if the <stream> state is not 186 EGL_STREAM_STATE_CREATED_KHR before 187 eglStreamImageConsumerConnectNV is called. 188 189 Call 190 191 EGLint eglQueryStreamConsumerEventNV( 192 EGLDisplay dpy, 193 EGLStreamKHR stream, 194 EGLTime timeout, 195 EGLenum *event, 196 EGLAttrib *aux); 197 198 to query the <stream> for the next pending event. 199 eglQueryStreamConsumerEventNV returns in <event> the event type 200 and returns in <aux> additional data associated with some events. 201 202 If no event is pending at the time eglQueryStreamConsumerEventNV is 203 called, it will wait up to <timeout> nanoseconds for one to arrive 204 before returning. If <timeout> is EGL_FOREVER, the function will 205 not time out and will only return if an event arrives or the stream 206 becomes disconnected. 207 208 On success, EGL_TRUE is returned. A new event will be returned. 209 The valid events are as follows: 210 211 - EGL_STREAM_IMAGE_ADD_NV is returned if a buffer is present in 212 the stream which has not yet been bound to an EGLImage with 213 eglCreateImage. 214 215 - EGL_STREAM_IMAGE_REMOVE_NV indicates that a buffer has been 216 removed from the stream and its EGLImage, whose handle is 217 returned in <aux>, can be destroyed when the consumer 218 application no longer requires it. 219 220 - EGL_STREAM_IMAGE_AVAILABLE_NV indicates that there is a 221 new frame available in the stream that can be acquired via 222 eglStreamAcquireImageNV. 223 224 On failure, EGL_FALSE is returned and an error is generated and 225 <event> and <aux> are not modified. 226 227 - EGL_BAD_STREAM_KHR is generated if <stream> is not a valid 228 valid stream handle associated with <dpy>. 229 230 EGL_TIMEOUT_EXPIRED is returned if the <timeout> duration is 231 complete, and there are no valid events that occured in this 232 duration. The <event> and <aux> parameters are not modified. 233 234 Call 235 236 EGLBoolean eglStreamAcquireImageNV( 237 EGLDisplay dpy, 238 EGLStreamKHR stream, 239 EGLImage *pImage, 240 EGLSync sync); 241 242 to "latch" the next image frame in the image stream from <stream> 243 into an EGLImage. 244 245 The consumer application needs to create a reusable EGLSync object 246 using eglCreateSync with EGL_SYNC_STATUS set to EGL_SIGNALED prior 247 to to this command. 248 249 eglStreamAcquireImageNV accepts a handle to a previously created 250 <sync> object. eglStreamAcquireImageNV will write into the 251 <sync> object and this indicates when the producer will be done 252 writing to the frame. It also resets the state of the <sync> object 253 to unsignaled. 254 255 If <sync> is EGL_NO_SYNC, the consumer ignores the sync object. 256 257 On success, EGL_TRUE is returned. 258 259 - <pImage> will have the most recent frame from the <stream> 260 261 On failure, eglStreamAcquireImageNV returns EGL_FALSE, and an error 262 is generated. 263 264 - EGL_BAD_DISPLAY is generated if <dpy> is not a valid, 265 initialized EGLDisplay. 266 267 - EGL_BAD_STREAM_KHR is generated if <stream> is not a valid 268 valid stream handle associated with <dpy>. 269 270 - EGL_BAD_ACCESS is generated if there are no frames in the 271 <stream> that are available to acquire. 272 273 Call 274 275 EGLBoolean eglStreamReleaseImageNV( 276 EGLDisplay dpy, 277 EGLStreamKHR stream, 278 EGLImage image, 279 EGLSync sync); 280 281 to release the <image> frame back to the stream. This takes a 282 <sync> that indicates when the consumer will be done using the 283 frame. Before calling eglStreamReleaseImageNV, the <image> 284 needs to have previously been acquired with 285 eglStreamAcquireImageNV. 286 287 If <sync> is EGL_NO_SYNC, then the sync object is ignored. 288 The eglStreamReleaseImageNV call makes a copy of the <sync>, so the 289 caller is free to delete or reuse the <sync> as it chooses. 290 291 On success, EGL_TRUE is returned, and the frame is successfully 292 returned back to the stream. 293 294 On failure, eglStreamReleaseImageNV returns EGL_FALSE, and an 295 error is generated. 296 297 - EGL_BAD_DISPLAY is generated if <dpy> is not a valid, 298 initialized EGLDisplay. 299 300 - EGL_BAD_STATE_KHR is generated if <stream> is not in state 301 EGL_STREAM_STATE_NEW_FRAME_AVAILABLE_KHR or 302 EGL_STREAM_STATE_OLD_FRAME_AVAILABLE_KHR. 303 304 - EGL_BAD_STREAM_KHR is generated if <stream> is not a valid 305 EGLStream created for <dpy>. 306 307 - EGL_BAD_PARAMETER is generated if <image> is either invalid, 308 or is not held by the consumer. 309 310 - EGL_BAD_PARAMETER is generated if <sync> is not a valid 311 EGLSync object or EGL_NO_SYNC. 312 313 If an acquired EGLImage has not yet released when eglDestroyImage 314 is called, then, then an implicit eglStreamReleaseImageNV will be 315 called. 316 317Add a new subsection 3.10.4.3.1 at the end of section "3.10.4.3 318EGL_STREAM_STATE_KHR Attribute" in the EGL_KHR_stream extension spec: 319 320 3.10.4.3.1 Interaction with EGL_STREAM_STATE_KHR 321 322 Image frames that have been presented to the stream on the producer 323 side, but have not been bound to an EGLImage on the consumer side 324 yet, do not affect the EGLStream state. 325 326 If a new frame is presented to the stream, the stream state goes 327 into EGL_STREAM_STATE_NEW_FRAME_AVAILABLE_KHR only if this frame is 328 bound to an EGLImage on the consumer, and if it has not already 329 been acquired. 330 331 If an EGLImage bound on the consumer side has been destroyed via 332 eglDestroyImage, then the stream goes into 333 EGL_STREAM_STATE_EMPTY_KHR if there are no consumer frames left, 334 that are bound to an EGLImage. 335 336Issues 337 338 339Revision History 340 341 #3 (November 27, 2019) Mukund Keshava 342 - Refined some subsections with more details 343 344 #2 (November 22, 2019) Mukund Keshava 345 - Refined some subsections with more details 346 - Added new subsection 3.10.4.3.1 347 348 #1 (November 13, 2019) Mukund Keshava 349 - initial draft 350