1Name 2 3 KHR_stream 4 KHR_stream_attrib 5 6Name Strings 7 8 EGL_KHR_stream 9 EGL_KHR_stream_attrib 10 11Contributors 12 13 Marcus Lorentzon 14 Acorn Pooley 15 Robert Palmer 16 Greg Prisament 17 Daniel Kartch 18 Miguel A. Vico Moya 19 20Contacts 21 22 Acorn Pooley, NVIDIA (apooley 'at' nvidia.com) 23 Marcus Lorentzon, ST-Ericsson AB (marcus.xm.lorentzon 'at' stericsson.com) 24 Daniel Kartch, NVIDIA (dkartch 'at' nvidia.com) 25 26Notice 27 28 Copyright (c) 2009-2016 The Khronos Group Inc. Copyright terms at 29 http://www.khronos.org/registry/speccopyright.html 30 31Status 32 33 Complete. 34 Approved by the Khronos Board of Promoters on December 2, 2011. 35 36Version 37 38 Version 27 - May 23, 2016 39 40Number 41 42 EGL Extension #32 43 44Dependencies 45 46 EGL_KHR_stream requires EGL 1.2. 47 48 EGL_KHR_stream_attrib requires EGL_KHR_stream and EGL 1.5. 49 50 EGL_KHR_stream_attrib interacts with 51 EGL_KHR_stream_consumer_gltexture. 52 53 This extension is written based on the wording of the EGL 1.2 54 specification. 55 56Overview 57 58 This extension defines a new object, the EGLStream, that can be 59 used to efficiently transfer a sequence of image frames from one 60 API to another. The EGLStream has mechanisms that can help keep 61 audio data synchronized to video data. 62 63 Each EGLStream is associated with a "producer" that generates 64 image frames and inserts them into the EGLStream. The producer is 65 responsible for inserting each image frame into the EGLStream at 66 the correct time so that the consumer can display the image frame 67 for the appropriate period of time. 68 69 Each EGLStream is also associated with a "consumer" that 70 retrieves image frames from the EGLStream. The consumer is 71 responsible for noticing that an image frame is available and 72 displaying it (or otherwise consuming it). The consumer is also 73 responsible for indicating the latency when that is possible (the 74 latency is the time that elapses between the time it is retrieved 75 from the EGLStream until the time it is displayed to the user). 76 77 Some APIs are stream oriented (examples: OpenMAX IL, OpenMAX AL). 78 These APIs may be connected directly to an EGLStream as a producer 79 or consumer. Once a stream oriented producer is "connected" to an 80 EGLStream and "started" it may insert image frames into the 81 EGLStream automatically with no further interaction from the 82 application. Likewise, once a stream oriented consumer is 83 "connected" to an EGLStream and "started" it may retrieve image 84 frames from the EGLStream automatically with no further interaction 85 from the application. 86 87 Some APIs are rendering oriented and require interaction with the 88 application during the rendering of each frame (examples: OpenGL, 89 OpenGL ES, OpenVG). These APIs will not automatically insert or 90 retrieve image frames into/from the EGLStream. Instead the 91 application must take explicit action to cause a rendering 92 oriented producer to insert an image frame or to cause a rendering 93 oriented consumer to retrieve an image frame. 94 95 The EGLStream conceptually operates as a mailbox. When the 96 producer has a new image frame it empties the mailbox (discards 97 the old contents) and inserts the new image frame into the 98 mailbox. The consumer retrieves the image frame from the mailbox 99 and examines it. When the consumer is finished examining the 100 image frame it is either placed back in the mailbox (if the 101 mailbox is empty) or discarded (if the mailbox is not empty). 102 103 Timing is mainly controlled by the producer. The consumer 104 operated with a fixed latency that it indicates to the producer 105 through the EGL_CONSUMER_LATENCY_USEC_KHR attribute. The consumer 106 is expected to notice when a new image frame is available in the 107 EGLStream, retrieve it, and display it to the user in the time 108 indicated by EGL_CONSUMER_LATENCY_USEC_KHR. The producer controls 109 when the image frame will be displayed by inserting it into the 110 stream at time 111 T - EGL_CONSUMER_LATENCY_USEC_KHR 112 where T is the time that the image frame is intended to appear to 113 the user. 114 115 This extension does not cover the details of how a producer or a 116 consumer works or is "connected" to an EGLStream. Different kinds 117 of producers and consumers work differently and are described in 118 additional extension specifications. (Examples of producer 119 specifications: 120 EGL_KHR_stream_producer_eglsurface 121 EGL_KHR_stream_producer_aldatalocator 122 OpenMAX_AL_EGLStream_DataLocator 123 Example of consumer extension specification: 124 EGL_KHR_stream_consumer_gltexture 125 ) 126 127 128Glossary 129 130 EGLStream 131 An EGL object that transfers a sequence of image frames from one 132 API to another (e.g. video frames from OpenMAX AL to OpenGL ES). 133 134 Image frame 135 A single image in a sequence of images. The sequence may be 136 frames of video data decoded from a video file, images output by a 137 camera sensor, surfaces rendered using OpenGL ES commands, or 138 generated in some other manner. An image frame has a period of 139 time during which it is intended to be displayed on the screen 140 (starting with the "Image Frame Display Time" and ending with the 141 "Image Frame Display Time" of the next image frame in the 142 sequence). 143 144 Image Frame Insertion Time 145 The point in time when the producer inserts the image frame into 146 the EGLStream. This is the "Image Frame Intended Display Time" 147 minus the "Consumer Latency". 148 149 Image Frame Intended Display Time 150 The point in time when the user should first see the image frame 151 on the display screen. 152 153 Image Frame Actual Display Time 154 The point in time when the user actually first sees the image frame 155 on the display screen. 156 157 Consumer Latency 158 The elapsed time between an image frame's "Image Frame Insertion 159 Time" and its "Image Frame Actual Display Time". The consumer is 160 responsible for predicting this and indicating its value to the 161 EGLStream. The producer is responsible for using this value to 162 calculate the "Image Frame Insertion Time" for each image frame. 163 The application has access to this value through the 164 EGL_CONSUMER_LATENCY_USEC attribute. 165 166 Producer 167 The entity that inserts image frames into the EGLStream. The 168 producer is responsible for timing: it must insert image frames at 169 a point in time equal to the "Image Frame Intended Display Time" 170 minus the "Consumer Latency". 171 172 Consumer 173 The entity that retrieves image frames from the EGLStream. When 174 the image frames are to be displayed to the user the consumer is 175 responsible for calculating the "Consumer Latency" and reporting 176 it to the EGLSteam. 177 178 State (stream state) 179 At any given time an EGLStream is in one of several states. See 180 section "3.10.4.3 EGL_STREAM_STATE_KHR Attribute" in this 181 extension for a description of the states and what transitions 182 occur between them. 183 184New Types 185 186 This is the type of a handle that represents an EGLStream object. 187 188 typedef void* EGLStreamKHR; 189 190 This is a 64 bit unsigned integer. 191 192 typedef khronos_uint64_t EGLuint64KHR; 193 194New functions defined by EGL_KHR_stream 195 196 EGLStreamKHR eglCreateStreamKHR( 197 EGLDisplay dpy, 198 const EGLint *attrib_list); 199 200 EGLBoolean eglDestroyStreamKHR( 201 EGLDisplay dpy, 202 EGLStreamKHR stream); 203 204 EGLBoolean eglStreamAttribKHR( 205 EGLDisplay dpy, 206 EGLStreamKHR stream, 207 EGLenum attribute, 208 EGLint value); 209 210 EGLBoolean eglQueryStreamKHR( 211 EGLDisplay dpy, 212 EGLStreamKHR stream, 213 EGLenum attribute, 214 EGLint *value); 215 216 EGLBoolean eglQueryStreamu64KHR( 217 EGLDisplay dpy, 218 EGLStreamKHR stream, 219 EGLenum attribute, 220 EGLuint64KHR *value); 221 222New functions defined by EGL_KHR_stream_attrib 223 224 EGLStreamKHR eglCreateStreamAttribKHR( 225 EGLDisplay dpy, 226 const EGLAttrib *attrib_list); 227 228 EGLBoolean eglSetStreamAttribKHR( 229 EGLDisplay dpy, 230 EGLStreamKHR stream, 231 EGLenum attribute, 232 EGLAttrib value); 233 234 EGLBoolean eglQueryStreamAttribKHR( 235 EGLDisplay dpy, 236 EGLStreamKHR stream, 237 EGLenum attribute, 238 EGLAttrib *value); 239 240 EGLBoolean eglStreamConsumerAcquireAttribKHR( 241 EGLDisplay dpy, 242 EGLStreamKHR stream 243 const EGLAttrib *attrib_list); 244 245 EGLBoolean eglStreamConsumerReleaseAttribKHR( 246 EGLDisplay dpy, 247 EGLStreamKHR stream, 248 const EGLAttrib *attrib_list); 249 250New Tokens 251 252 This value is returned from eglCreateStreamKHR in the case of an 253 error. It is an error to attempt to use this value as a parameter 254 to any EGL or client API function. 255 256 EGL_NO_STREAM_KHR ((EGLStreamKHR)0) 257 258 This enum is accepted as an attribute in the <attrib_list> parameter 259 of eglCreateStreamKHR and as the <attribute> parameter of 260 eglStreamAttribKHR, eglSetStreamAttribKHR, eglQueryStreamKHR and 261 eglQueryStreamAttribKHR. 262 263 EGL_CONSUMER_LATENCY_USEC_KHR 0x3210 264 265 These enums are accepted as the <attribute> parameter of 266 eglQueryStreamu64KHR. 267 268 EGL_PRODUCER_FRAME_KHR 0x3212 269 EGL_CONSUMER_FRAME_KHR 0x3213 270 271 This enum is accepted as the <attribute> parameter of 272 eglQueryStreamKHR and eglQueryStreamAttribKHR. 273 274 EGL_STREAM_STATE_KHR 0x3214 275 276 Returned in the <value> parameter of eglQueryStreamKHR or 277 eglQueryStreamAttribKHR when <attribute> is EGL_STREAM_STATE. 278 279 EGL_STREAM_STATE_CREATED_KHR 0x3215 280 EGL_STREAM_STATE_CONNECTING_KHR 0x3216 281 EGL_STREAM_STATE_EMPTY_KHR 0x3217 282 EGL_STREAM_STATE_NEW_FRAME_AVAILABLE_KHR 0x3218 283 EGL_STREAM_STATE_OLD_FRAME_AVAILABLE_KHR 0x3219 284 EGL_STREAM_STATE_DISCONNECTED_KHR 0x321A 285 286 These errors may be generated by EGLStream calls. 287 288 EGL_BAD_STREAM_KHR 0x321B 289 EGL_BAD_STATE_KHR 0x321C 290 291Add a new section "2.5 Streams" after section "2.4 Shared State" 292 293 EGL allows efficient interoperation between APIs through the 294 EGLStream object. An EGLStream represents a sequence of image 295 frames. 296 297 Each EGLStream is associated with a producer that generates image 298 frames and inserts them into the EGLStream. Each EGLStream is 299 also associated with a consumer that retrieves image frames from 300 the EGLStream. 301 302Add a new section "3.10 EGLStreams" after section "3.9 Posting the 303Color Buffer" 304 305 3.10 EGLStreams 306 307 EGL provides functions to create and destroy EGLStreams, for 308 querying and setting attributes of EGLStreams, and for connecting 309 EGLStreams to producers and consumers. 310 311 Each EGLStream may be connected to only one producer and one 312 consumer. Once an EGLStream is connected to a consumer, it will 313 be connected to that consumer until the EGLStream is destroyed. 314 Likewise, once an EGLStream is connected to a producer it will be 315 connected to that producer until the EGLStream is destroyed. 316 Further semantics are described for each type of consumer and 317 producer that can be connected. 318 319Add subsection 3.10.1 to section "3.10 EGLStreams" 320 321 3.10.1 Creating an EGLStream 322 323 Call 324 325 EGLStreamKHR eglCreateStreamKHR( 326 EGLDisplay dpy, 327 const EGLint *attrib_list); 328 329 to create a new EGLStream. <dpy> specifies the EGLDisplay used for 330 this operation. The function returns a handle to the created 331 EGLStream. 332 333 The EGLStream cannot be used until it has been connected to a 334 consumer and then to a producer (refer to section "3.10.2 335 Connecting an EGLStream to a consumer" and section "3.10.3 336 Connecting an EGLStream to a producer"). It must be connected to 337 a consumer before being connected to a producer. 338 339 There is no way for the application to query the size, 340 colorformat, or number of buffers used in the EGLStream (although 341 these attributes may be available from the producer's API or the 342 consumer's API depending on what type of producer/consumer is 343 connected to the EGLStream). 344 345 The parameter <attrib_list> contains a list of attributes and 346 values to set for the EGLStream. Attributes not in the list are 347 set to default values. EGLStream attributes are described in 348 section "3.10.4 EGLStream Attributes". 349 350 If an error occurs eglCreateStreamKHR will return 351 EGL_NO_STREAM_KHR and generate an error. 352 353 - EGL_BAD_ATTRIBUTE is generated if any of the parameters in 354 attrib_list is not a valid EGLStream attribute. 355 356 - EGL_BAD_ACCESS is generated if any of the parameters in 357 attrib_list is read only. 358 359 - EGL_BAD_PARAMETER is generated if any of the values in 360 attrib_list is outside the valid range for the attribute. 361 362 - EGL_BAD_ALLOC is generated if not enough resources are 363 available to create the EGLStream. 364 365 - EGL_BAD_DISPLAY is generated if <dpy> is not a valid, 366 initialized EGLDisplay. 367 368If EGL_KHR_stream_attrib is present, add to the end of this section 369 370 Streams may also be created by calling 371 372 EGLStreamKHR eglCreateStreamAttribKHR( 373 EGLDisplay dpy, 374 const EGLAttrib *attrib_list); 375 376 This is equivalent to eglCreateStreamKHR, but allows pointer 377 and handle attributes to be provided on 64-bit systems. 378 379Add section 3.10.2 to section "3.10 EGLStreams" 380 381 3.10.2 Connecting an EGLStream to a consumer. 382 383 Before using an EGLStream it must be connected to a consumer. 384 385 Refer to sections 3.10.2.1 and following for different ways to 386 connect a consumer to an EGLStream. 387 388 Once an EGLStream is connected to a consumer it will remain 389 connected to the same consumer until the EGLStream is destroyed. 390 391 If the consumer is destroyed then the EGLStream's state will 392 become EGL_STREAM_STATE_DISCONNECTED_KHR. 393 394 Any attempt to connect an EGLStream which is not in state 395 EGL_STREAM_STATE_CREATED_KHR will fail and generate an 396 EGL_BAD_STATE_KHR error. 397 398 When an EGLStream is connected to a consumer its state becomes 399 EGL_STREAM_STATE_CONNECTING_KHR. 400 401 3.10.2.1 No way to connect consumer to EGLStream 402 403 EGL does not currently define any mechanisms to connect a consumer 404 to an EGLStream. These will be added via additional extensions. 405 406 (Example: See extension specification 407 EGL_KHR_stream_consumer_gltexture) 408 409If EGL_KHR_stream_attrib is present, add to the end of this section 410 411 3.10.2.2 Acquiring and releasing consumer frames 412 413 Methods for acquiring frames from a stream and releasing them back 414 to a stream are dependent on the type of consumer. Some consumers 415 support calling 416 417 EGLBoolean eglStreamConsumerAcquireAttribKHR( 418 EGLDisplay dpy, 419 EGLStreamKHR stream 420 const EGLAttrib *attrib_list); 421 422 to acquire the next available frame in <stream> and 423 424 EGLBoolean eglStreamConsumerReleaseAttribKHR( 425 EGLDisplay dpy, 426 EGLStreamKHR stream, 427 const EGLAttrib *attrib_list); 428 429 to release a frame back to the stream. 430 431 Not all consumers are required to support either or both of these 432 functions. Where supported, the specific behavior is defined by the 433 consumer type, and may be affected by the contents of <attrib_list>. 434 <attrib_list> must either be NULL or a pointer to a list of 435 name/value pairs terminated by EGL_NONE. Valid attributes are 436 listed in tables 3.10.2.1 and 3.10.2.2. 437 438 Attribute Type Section 439 ------------------------ ---------- ------- 440 Currently no acquire attributes are defined 441 442 Table 3.10.2.1 EGLStream Consumer Acquire Attributes 443 444 Attribute Type Section 445 ------------------------ ---------- ------- 446 Currently no release attributes are defined 447 448 Table 3.10.2.2 EGLStream Consumer Release Attributes 449 450 If no new image frame is available in the stream, 451 eglStreamConsumerAcquireAtrribKHR may block, retrieve an old frame, 452 or return an error, as defined by the type of consumer. If one or 453 more image frames are already acquired by the consumer when 454 eglStreamConsumerAcquireAttribKHR is called, the behavior is 455 determined by the type of consumer. 456 457 If successful, eglStreamConsumerAcquireAttribKHR returns EGL_TRUE 458 and an image frame from <stream> will be bound into the address 459 space of the consumer as defined for its type. 460 461 On failure, the function returns EGL_FALSE and generates an error. 462 Additionally, image objects in the consumer's address space may 463 become invalid, as determined by the consumer type. 464 465 - EGL_BAD_ACCESS is generated if the consumer of <stream> does 466 not support acquiring frames through 467 eglStreamConsumerAcquireAttribKHR. 468 469 - EGL_BAD_STATE_KHR is no frame is available for acquisition 470 after any timeout determined by the consumer. 471 472 - EGL_BAD_ATTRIBUTE is generated if an attribute name in 473 <attrib_list> is not recognized or is not supported by the 474 consumer. 475 476 - EGL_BAD_STREAM_KHR is generated if <stream> is not a valid 477 EGLStream created for <dpy>. 478 479 - EGL_BAD_DISPLAY is generated if <dpy> is not a valid 480 EGLDisplay. 481 482 - EGL_NOT_INITIALIZED is generated if <dpy> is not initialized. 483 484 Calling eglStreamConsumerReleaseAttribKHR will release a frame held 485 by the consumer back to the stream. If more than one frame is held 486 by the consumer, the frame returned is determined by the consumer 487 type and the contents of <attrib_list>. If no frames are currently 488 held, the behavior is determined by the consumer type. Once 489 returned, the consumer may no longer access the contents of the 490 frame, and attempts to do so will result in errors as determined by 491 the consumer type. Upon success, eglStreamConsumerReleaseAttribKHR 492 returns EGL_TRUE. 493 494 If eglStreamConsumerReleaseAttribKHR fails, EGL_FALSE is returned 495 and an error is generated. 496 497 - EGL_BAD_ACCESS is generated if the consumer of <stream> does 498 not support releasing frames through 499 eglStreamConsumerReleaseAttribKHR. 500 501 - EGL_BAD_STATE_KHR is generated if <stream> is not in state 502 EGL_STREAM_STATE_EMPTY_KHR, 503 EGL_STREAM_STATE_NEW_FRAME_AVAILABLE_KHR or 504 EGL_STREAM_STATE_OLD_FRAME_AVAILABLE_KHR. 505 506 - EGL_BAD_ATTRIBUTE is generated if an attribute name in 507 <attrib_list> is not recognized or is not supported by the 508 consumer. 509 510 - EGL_BAD_STREAM_KHR is generated if <stream> is not a valid 511 EGLStream created for <dpy>. 512 513 - EGL_BAD_DISPLAY is generated if <dpy> is not a valid 514 EGLDisplay. 515 516 - EGL_NOT_INITIALIZED is generated if <dpy> is not initialized. 517 518If EGL_KHR_stream_consumer_gltexture is present in addition to 519EGL_KHR_stream_attrib, the eglStreamConsumerAcquireKHR function is 520equivalent to eglStreamConsumerAcquireAttribKHR with <attrib_list> set 521to NULL, the eglStreamConsumerReleaseKHR function is equivalent to 522eglStreamConsumerReleaseAttribKHR with <attrib_list> set to NULL, and 523the definitions provided for those functions define their behavior for 524a GL texture consumer. 525 526Add section 3.10.3 to section "3.10 EGLStreams" 527 528 3.10.3 Connecting an EGLStream to a producer. 529 530 Before using an EGLStream it must be connected to a producer. The 531 EGLStream must be connected to a consumer before it may be 532 connected to a producer. 533 534 The size and colorformat of the images in the EGLStream are 535 determined by the EGL implementation based on the requirements of 536 the producer and the consumer. The EGL implementation may 537 determine these at the time the producer is connected to the 538 EGLStream, at the time that the first image frame is inserted into 539 the EGLStream, or any time in between (this is left up to the 540 implementation). 541 542 It is the responsibility of the producer to convert the images to 543 a form that the consumer can consume. The producer may negotiate 544 with the consumer as to what formats and sizes the consumer is 545 able to consume, but this negotiation (whether it occurs and how 546 it works) is an implementation detail. If the producer is unable 547 to convert the images to a form that the consumer can consume then 548 the attempt to connect the producer to the EGLStream will fail and 549 generate an EGL_BAD_MATCH error. 550 551 Refer to sections 3.10.3.1 and following for different ways to 552 connect a producer to an EGLStream. 553 554 Once an EGLStream is connected to a producer it will remain 555 connected to the same producer until the EGLStream is destroyed. 556 If the producer is destroyed then the EGLStream's state will 557 become EGL_STREAM_STATE_DISCONNECTED_KHR (refer to "3.10.4.3 558 EGL_STREAM_STATE_KHR Attribute"). 559 560 Any attempt to connect an EGLStream which is not in state 561 EGL_STREAM_STATE_CONNECTING_KHR will fail and generate an 562 EGL_BAD_STATE_KHR error. 563 564 When an EGLStream is connected to a producer its state becomes 565 EGL_STREAM_STATE_EMPTY_KHR. At this point the producer may begin 566 inserting image frames and the consumer may begin consuming image 567 frames, so the state may immediately change to 568 EGL_STREAM_STATE_NEW_FRAME_AVAILABLE_KHR and/or 569 EGL_STREAM_STATE_OLD_FRAME_AVAILABLE_KHR. 570 571 3.10.3.1 No way to connect producer to EGLStream 572 573 EGL does not currently define any mechanisms to connect a producer 574 to an EGLStream. These will be added via additional extensions. 575 576 (For example see extension specifications 577 EGL_KHR_stream_producer_eglsurface 578 EGL_KHR_stream_producer_aldatalocator 579 OpenMAX_AL_EGLStream_DataLocator 580 .) 581 582Add section 3.10.4 to section "3.10 EGLStreams" 583 584 3.10.4 EGLStream Attributes 585 586 Each EGLStream contains a set of attributes and values as 587 described in table 3.10.4.4. Each attribute has a type and a 588 value and is either read-only (ro), read/write (rw) or initialize 589 only (io - meaning it may be set in the attrib_list but not 590 changed once the EGLStream is created). 591 592 Attribute Read/Write Type Section 593 -------------------------- ---------- ------ -------- 594 EGL_STREAM_STATE_KHR ro EGLint 3.10.4.3 595 EGL_PRODUCER_FRAME_KHR ro EGLuint64KHR 3.10.4.4 596 EGL_CONSUMER_FRAME_KHR ro EGLuint64KHR 3.10.4.5 597 EGL_CONSUMER_LATENCY_USEC_KHR rw EGLint 3.10.4.6 598 599 Table 3.10.4.4 EGLStream Attributes 600 601 3.10.4.1 Setting EGLStream Attributes 602 603 Call 604 605 EGLBoolean eglStreamAttribKHR( 606 EGLDisplay dpy, 607 EGLStreamKHR stream, 608 EGLint attribute, 609 EGLint value); 610 611 to set the value of an attribute for an EGLStream. The <value> is 612 the new value for <attribute>. Only read/write (rw) attributes 613 with type EGLint may be set with eglStreamAttribKHR (see "Table 614 3.10.4.4 EGLStream Attributes"). 615 616 If an error occurs, EGL_FALSE is returned and an error is 617 generated. 618 619 - EGL_BAD_STATE_KHR is generated if <stream> is in 620 EGL_STREAM_STATE_DISCONNECTED_KHR state. 621 622 - EGL_BAD_ATTRIBUTE is generated if <attribute> is not a valid 623 EGLStream attribute. 624 625 - EGL_BAD_ACCESS is generated if <attribute> is read only. 626 627 - EGL_BAD_PARAMETER is generated if value is outside the valid 628 range for <attribute>. 629 630 - EGL_BAD_STREAM_KHR is generated if <stream> is not a valid 631 EGLStream created for <dpy>. 632 633 - EGL_BAD_DISPLAY is generated if <dpy> is not a valid, 634 initialized EGLDisplay. 635 636 3.10.4.2 Querying EGLStream Attributes 637 638 Call 639 640 EGLBoolean eglQueryStreamKHR( 641 EGLDisplay dpy, 642 EGLStreamKHR stream, 643 EGLint attribute, 644 EGLint *value); 645 646 to query the value of an EGLStream's attribute with type EGLint 647 and call 648 649 EGLBoolean eglQueryStreamu64KHR( 650 EGLDisplay dpy, 651 EGLStreamKHR stream, 652 EGLenum attribute, 653 EGLuint64KHR *value); 654 655 to query the value of an EGLStream's attribute with type 656 EGLuint64KHR. 657 658 If an error occurs EGL_FALSE is returned and an error is 659 generated. 660 661 - EGL_BAD_STREAM_KHR is generated if <stream> is not a valid 662 EGLStream created for <dpy>. 663 664 - EGL_BAD_ATTRIBUTE is generated by eglQueryStreamKHR if 665 <attribute> is not a valid EGLStream attribute with type 666 EGLint. 667 668 - EGL_BAD_ATTRIBUTE is generated by eglQueryStreamu64KHR if 669 <attribute> is not a valid EGLStream attribute with type 670 EGLuint64KHR. 671 672 3.10.4.3 EGL_STREAM_STATE_KHR Attribute 673 674 The EGL_STREAM_STATE_KHR attribute is read only. It indicates the 675 state of the EGLStream. The EGLStream may be in one of the 676 following states: 677 678 - EGL_STREAM_STATE_CREATED_KHR - The EGLStream has been created 679 but not yet connected to a producer or a consumer. 680 681 - EGL_STREAM_STATE_CONNECTING_KHR - The EGLStream has been 682 connected to a consumer but not yet connected to a producer. 683 684 - EGL_STREAM_STATE_EMPTY_KHR - the EGLStream has been connected 685 to a consumer and a producer, but the producer has not yet 686 inserted any image frames. 687 688 - EGL_STREAM_STATE_NEW_FRAME_AVAILABLE_KHR - the producer has 689 inserted at least one image frame that the consumer has not 690 yet retrieved. 691 692 - EGL_STREAM_STATE_OLD_FRAME_AVAILABLE_KHR - the producer has 693 inserted at least one image frame, and the consumer has 694 already retrieved the most recently inserted image frame. 695 696 - EGL_STREAM_STATE_DISCONNECTED_KHR - either the producer or the 697 consumer (or both) are no longer connected to the EGLStream 698 (e.g. because they have been destroyed). Once the 699 EGLStream is in this state it will remain in this state 700 until the EGLStream is destroyed. In this state only 701 eglQueryStreamKHR and eglDestroyStreamKHR are valid 702 operations. 703 704 Only the following state transitions may occur: 705 706 -> EGL_STREAM_STATE_CREATED_KHR 707 A new EGLStream is created in this state. 708 709 EGL_STREAM_STATE_CREATED_KHR -> 710 EGL_STREAM_STATE_CONNECTING_KHR 711 Occurs when a consumer is connected to the EGLStream. 712 713 EGL_STREAM_STATE_CONNECTING_KHR -> 714 EGL_STREAM_STATE_EMPTY_KHR 715 Occurs when a producer is connected to the EGLStream. 716 717 EGL_STREAM_STATE_EMPTY_KHR -> 718 EGL_STREAM_STATE_NEW_FRAME_AVAILABLE_KHR 719 Occurs the first time the producer inserts an image frame. 720 721 EGL_STREAM_STATE_NEW_FRAME_AVAILABLE_KHR -> 722 EGL_STREAM_STATE_OLD_FRAME_AVAILABLE_KHR 723 Occurs when the consumer begins examining a newly inserted 724 image frame. 725 726 EGL_STREAM_STATE_OLD_FRAME_AVAILABLE_KHR -> 727 EGL_STREAM_STATE_NEW_FRAME_AVAILABLE_KHR 728 Occurs when the producer inserts a new image frame. 729 730 * -> 731 EGL_STREAM_STATE_DISCONNECTED_KHR 732 Occurs when the producer or consumer is destroyed or is 733 otherwise unable to function normally. 734 735 736 3.10.4.4 EGL_PRODUCER_FRAME_KHR Attribute 737 738 The EGL_PRODUCER_FRAME_KHR attribute indicates how many image 739 frames have been inserted into the EGLStream by the producer. 740 This is also known as the "frame number" of the most recently 741 inserted frame (where the first frame inserted has a frame number 742 of 1). When EGL_STREAM_STATE_KHR is EGL_STREAM_STATE_CREATED_KHR, 743 EGL_STREAM_STATE_CONNECTING_KHR, or EGL_STREAM_STATE_EMPTY_KHR 744 then this value is 0. This value will wrap back to 0 after 745 about 10 million millennia. 746 747 3.10.4.4 EGL_CONSUMER_FRAME_KHR Attribute 748 749 The EGL_CONSUMER_FRAME_KHR attribute indicates the frame number of 750 the image frame that the consumer most recently retrieved. This is 751 the value that EGL_PRODUCER_FRAME_KHR contained just after this 752 image frame was inserted into the EGLStream. 753 754 3.10.4.5 EGL_CONSUMER_LATENCY_USEC_KHR Attribute 755 756 This attribute indicates the number of microseconds that elapse (on 757 average) from the time that an image frame is inserted into the 758 EGLStream by the producer until the image frame is visible to the 759 user. 760 761 It is the responsibility of the consumer to set this value. Some 762 types of consumers may simply set this value to zero or an 763 implementation constant value. Other consumers may adjust this 764 value dynamically as conditions change. 765 766 It is the responsibility of the producer to use this information to 767 insert image frames into the EGLStream at an appropriate time. 768 The producer should insert each image frame into the stream at the 769 time that frame should appear to the user MINUS the 770 EGL_CONSUMER_LATENCY_USEC_KHR value. Some types of producers may 771 ignore this value. 772 773 The application may modify this value to adjust the timing of the 774 stream (e.g. to make video frames coincide with an audio track 775 under direction from a user). However the value set by the 776 application may be overridden by some consumers that dynamically 777 adjust the value. This will be noted in the description of 778 consumers which do this. 779 780If EGL_KHR_stream_attrib is present, add to the end of section "3.10.4.1 781Setting EGLStream Attributes" 782 783 Attributes may also be set by calling 784 785 EGLBoolean eglSetStreamAttribKHR( 786 EGLDisplay dpy, 787 EGLStreamKHR stream, 788 EGLenum attribute, 789 EGLAttrib value); 790 791 This is equivalent to eglStreamAttribKHR, but allows attributes 792 with pointer and handle types, in addition to EGLint. 793 794If EGL_KHR_stream_attrib is present, add to the end of section "3.10.4.2 795Querying EGLStream Attributes" 796 797 Attributes may also be queried by calling 798 799 EGLBoolean eglQueryStreamAttribKHR( 800 EGLDisplay dpy, 801 EGLStreamKHR stream, 802 EGLenum attribute, 803 EGLAttrib *value); 804 805 This is equivalent to eglQueryStreamKHR, but allows attributes with 806 pointer and handle types, in addition to EGLint. 807 808Add sections 3.10.5 and 3.10.6 to section "3.10 EGLStreams" 809 810 3.10.5 EGLStream operation 811 812 3.10.5.1 EGLStream operation in mailbox mode 813 814 The EGLStream conceptually operates as a mailbox. 815 816 When the producer has a new image frame it empties the mailbox and 817 inserts the new image frame into the mailbox. If the image frame 818 is intended to be displayed at time T then the producer must 819 insert it into the EGLStream at time 820 T - EGL_CONSUMER_LATENCY_USEC_KHR 821 822 The consumer retrieves the image frame from the mailbox and 823 examines it. When the consumer is finished examining the image 824 frame it is either placed back in the mailbox (if the mailbox is 825 empty) or discarded (if the mailbox is not empty). 826 827 This operation implies 2 things: 828 829 - If the consumer consumes frames slower than the producer 830 inserts frames, then some frames may be lost (never seen by 831 the consumer). 832 833 - If the consumer consumes frames faster than the producer 834 inserts frames, then the consumer may see some frames more 835 than once. 836 837 Some details of EGLStream operation are dependent on the type of 838 producer and consumer that are connected to it. Refer to the 839 documentation for the producer and consumer for more details 840 (section 3.10.2.* and 3.10.3.*). 841 842 843 3.10.6 Destroying an EGLStream 844 845 Call 846 847 EGLBoolean eglDestroyStreamKHR( 848 EGLDisplay dpy, 849 EGLStreamKHR stream); 850 851 to mark an EGLStream for deletion. After this call returns the 852 <stream> will no longer be a valid stream handle. The resources 853 associated with the EGLStream may not be deleted until the 854 producer and consumer have released their references to the 855 resources (if any). Exactly how this is done is dependent on the 856 type of consumer and producer that is connected to the EGLStream. 857 858 If an error occurs, EGL_FALSE is returned and an error is 859 generated. 860 861 - EGL_BAD_STREAM_KHR is generated if <stream> is not a valid 862 EGLStream created for <dpy>. 863 864 865Issues 866 1. Are EGL_WIDTH and EGL_HEIGHT parameters needed? 867 868 RESOLVED: No. The width and height of images managed by the 869 stream are determined by the producer. No application access 870 to the size is currently required. 871 872 2. Is EGL_BUFFER_SHOW_ALL_KHR required, or should the stream always 873 act as EGL_BUFFER_REPLACE_KHR? 874 875 RESOLVED: this has been removed. The old 876 EGL_BUFFER_SHOW_ALL_KHR behavior is described in a separate 877 extension: EGL_KHR_stream_fifo 878 879 3. What are the exact semantics of the producer? 880 881 RESOLVED: The exact semantics vary depending on the type of 882 producer. Refer to the extension that defines the type of 883 producer for more information. 884 885 In general, the producer is responsible for inserting image 886 frames into the EGLStream at the correct time. The correct 887 time depends on how the image frames are being created and on 888 the value of EGL_CONSUMER_LATENCY_USEC_KHR. 889 890 4. What are the exact semantics of the consumer? 891 892 RESOLVED: The exact semantics vary depending on the type of 893 consumer. Refer to the extension that defines the type of 894 consumer for more information. 895 896 In general, the consumer is responsible for retrieving image 897 frames from the EGLStream when they become available. The 898 consumer is also responsible for setting the 899 EGL_CONSUMER_LATENCY_USEC_KHR when that is possible. 900 901 5. When will the EGLStream resources be deleted? 902 903 RESOLVED: this depends on the type of consumer and producer. 904 Refer to the description of the consumer and producer (e.g. in 905 the extension that describes them). 906 907 6. How does A/V sync work? 908 909 RESOLVED: The producer is responsible for A/V sync, but the 910 consumer needs to help. The consumer indicates the latency 911 (the average time that it takes the consumer to retrieve an 912 image from the EGLStream and place it on the display screen) 913 by setting the EGL_CONSUMER_LATENCY_USEC_KHR. The producer 914 uses knowledge about the audio stream to determine the correct 915 time to display an image frame, and inserts the image frame at 916 that time MINUS the EGL_CONSUMER_LATENCY_USEC_KHR. 917 918 7. What if the consumer cannot determine the latency? 919 920 RESOLVED: If the consumer does not set the 921 EGL_CONSUMER_LATENCY_USEC_KHR attribute then its default value 922 will be used. This default value is implementation defined 923 and may be zero. See the description of the specific type of 924 consumer you are using (e.g. the extension that defines it) 925 for more details related to that consumer. 926 927 8. What colorformats are supported by EGLStream 928 929 RESOLVED: No specific formats are required, but it is expected 930 that this work with the main YUV formats supported by the 931 platform's video HW and the main RGB(A) formats supported by 932 the platform's OpenGL (ES) hardware. It is the responsibility 933 of the producer to negotiate a format that will work with the 934 consumer. If the internal formats supported by the producer 935 do not coincide with the internal formats supported by the 936 consumer then the producer may choose to convert to a format 937 that the consumer understands, or it may choose to fail and 938 generate an error when an attempt is made to connect it to the 939 EGLStream. Exactly which it does for which formats is further 940 discussed in the producer endpoint documentation (refer to the 941 extension that describes the producer endpoint). 942 943 9. Is any EGLImage extension required by this extension? 944 945 RESOLVED: No. This extension may be implemented using some of 946 the same code that is used to implement EGLImages, but there 947 is no dependency on EGLImages. 948 949 10. Why describe the "io" attribute type if no attributes use it. 950 951 RESOLVED: Future extensions will add attributes of "io" type 952 (initialize only - meaning they can be set in the attribute 953 list when creating the EGLStream, but not modified once the 954 EGLStream is created). Rather than requiring each such 955 extension to describe the "io" type (and possibly getting 956 slightly different definitions or types in different 957 extensions) the "io" type is defined here so that other 958 extensions can easily use it. This helps layered 959 extensions to all use the same language. 960 961 962Revision History 963 964 #27 (May 23, 2016) Daniel Kartch 965 - For compatibility with EGL 1.5 and support of 64-bit 966 platforms, add EGL_KHR_stream_attrib extension with variants 967 of original functions that accept attributes of type 968 EGLAttrib. 969 - Corrected line length violations. 970 971 #26 (July 12, 2012) Acorn Pooley 972 - Fix error in description of consumer latency. 973 974 #25 (October 12, 2011) Acorn Pooley 975 - Add issue 10 976 977 #24 (October 11, 2011) Acorn Pooley 978 - add error condition to eglDestroyStreamKHR 979 980 #23 (October 5, 2011) Acorn Pooley 981 - refer to related EGL_KHR_... extension specs rather than 982 EGL_NV_... ones. 983 984 #22 (September 27, 2011) Acorn Pooley 985 - Fix enum value for EGL_STREAM_STATE_KHR (bug 8064) 986 987 #21 (September 27, 2011) Acorn Pooley 988 - Assign enum values (bug 8064) 989 990 #20 (September 23, 2011) Acorn Pooley 991 - Rename EGL_NO_IMAGE_STREAM_KHR to EGL_NO_STREAM_KHR 992 993 #19 (Aug 3, 2011) Acorn Pooley 994 - fix some error conditions 995 996 #18 (Aug 2, 2011) Acorn Pooley 997 - Add eglQueryStreamu64KHR 998 - add EGLuint64KHR 999 - make EGL_PRODUCER_FRAME_KHR and EGL_CONSUMER_FRAME_KHR 64 1000 bit. 1001 1002 #17 (Aug 2, 2011) Acorn Pooley 1003 - fix grammar 1004 1005 #16 (July 6, 2011) Acorn Pooley 1006 - rename from EGL_KHR_image_stream to EGL_KHR_stream 1007 1008 #15 (June 29, 2011) Acorn Pooley 1009 - major re-write 1010 - remove EGL_SWAP_MODE_KHR and EGL_BUFFER_SHOW_ALL_KHR 1011 - add new functions: 1012 eglStreamAttribKHR 1013 eglQueryStreamKHR 1014 - add new attributes: 1015 EGL_CONSUMER_LATENCY_USEC_KHR 1016 EGL_PRODUCER_FRAME_KHR 1017 EGL_CONSUMER_FRAME_KHR 1018 EGL_STREAM_STATE_KHR 1019 - add concept of EGL_STREAM_STATE_KHR 1020 - add new error: 1021 EGL_BAD_STATE_KHR 1022 - add more thorough overview section 1023 - add description of buffering 1024 - place the functions in section 3 of the spec (were in 1025 section 2) 1026 - mention some of the consumer and producer specs that may be 1027 needed to make use of this extension. 1028 - remove very old issues that no longer make any sense 1029 - add new issues and resolutions 1030 1031 #14 (June 4, 2010) Greg Prisament 1032 - fix minor typo 1033 1034 #13 (June 2, 2010) Marcus Lorentzon 1035 - add EGL enum values 1036 1037 #12 (May 21, 2010) Marcus Lorentzon 1038 - add clarifications on swap modes 1039 1040 #11 (April 13, 2010) Marcus Lorentzon 1041 - fix tyops 1042 - make eglDestroyStream return EGLBoolean, not void 1043 1044 #10 (March 17, 2010) Marcus Lorentzon 1045 - fix typo 1046 - remove obsolete text 1047 - update issue 2 resolution 1048 1049 #9 (December 15, 2009) Marcus Lorentzon 1050 - move EGL_IMAGE_USE_* attributes to the endpoint extension 1051 - resolved issue 5 1052 1053 #8 (December 6, 2009) Marcus Lorentzon 1054 - remove EGL_INIT_COLOR_KHR 1055 - relax the definition of the Producer to allow not only video 1056 frames to be generated 1057 - clean up the language of recently produced, supplied, pending 1058 images 1059 1060 #7 (October 19, 2009) Acorn Pooley 1061 - Update based on comments from Robert and Bruce 1062 - remove mention of OpenWF 1063 - make EGL_BUFFER_REPLACE_KHR be the default EGL_SWAP_MODE_KHR 1064 - add issue 5 1065 - remove EGLAPI and EGLAPIENTRY 1066 1067 #6 (September 16, 2009) Acorn Pooley 1068 - remove EGL_WIDTH and EGL_HEIGHT parameters 1069 - add issue 4 1070 - clarify swap modes 1071 - other clarifications and simplifications 1072 1073 #5 (July 2, 2009) Acorn Pooley 1074 - remove reference to no-longer-existing <images> parameter. 1075 - mention dependancy on EGL_KHR_image_uses extension. 1076 - add description of EGL_IMAGE_USE_AS_* enums. 1077 1078 #4 (June 3, 2009) Acorn Pooley 1079 - Fix typos: change old EGLImageStream occurances to EGLStream 1080 1081 #3 (April 22, 2009) Marcus Lorentzon 1082 - Updated revide comments 1083 - Removed external image support 1084 1085 #2 (March 30, 2009) Marcus Lorentzon 1086 - Replaced image surface with image stream 1087 1088 #1 (February 21, 2009) Marcus Lorentzon 1089 - Initial draft 1090 1091# vim:ai:ts=4:sts=4:expandtab:textwidth=70 1092