1Name 2 3 NV_stream_frame_limits 4 5Name Strings 6 7 EGL_NV_stream_frame_limits 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 4 - October 27, 2016 24 25Number 26 27 EGL Extension #113 28 29Dependencies 30 31 Requires EGL_KHR_stream 32 33 Interacts with EGL_EXT_stream_consumer_egloutput 34 35Overview 36 37 Some stream consumers may allow more than one frame to be acquired 38 at a time, so that applications can operate on sequences of images 39 rather than individual images. This in turn may lead to producers 40 allocating additional buffers to keep the fifo full while fulfilling 41 the consumer's needs. Applications may wish to limit the resources 42 allocated for a given stream, and some stream implementations may be 43 able to operate more efficiently if they know in advance how many 44 buffers will be used. 45 46 This extension defines two new stream attributes which provide hints 47 as to how many frames the application will require, allowing the 48 implementation to plan accordingly. 49 50New functions 51 52 None 53 54New tokens 55 56 Accepted as an attribute name in the <attrib_list> parameter of 57 eglCreateStreamKHR and as the <attribute> parameter of 58 eglQueryStreamKHR. 59 60 EGL_PRODUCER_MAX_FRAME_HINT_NV 0x3337 61 EGL_CONSUMER_MAX_FRAME_HINT_NV 0x3338 62 63 64Add to "Table 3.10.4.4 EGLStream Attributes" 65 66 Attribute Read/Write Type Section 67 ------------------------------ ---------- ------ ---------- 68 EGL_PRODUCER_MAX_FRAME_HINT_NV io EGLint 3.10.4.x 69 EGL_CONSUMER_MAX_FRAME_HINT_NV io EGLint 3.10.4.x+1 70 71Add new subsections to section "3.10.4 EGLStream Attributes" 72 73 3.10.4.x EGL_PRODUCER_MAX_FRAME_HINT_NV Attribute 74 75 The EGL_PRODUCER_MAX_FRAME_HINT_NV attribute indicates a limit on how 76 many outstanding frames the producer application intends to have at 77 any given time. This includes all frames currently being generated, 78 waiting in in the stream's mailbox or FIFO, and held by the consumer. 79 Its default value is EGL_DONT_CARE. 80 81 The implementation may make use of this hint to determine how many 82 buffers or other resources to allocate for the stream. It is not 83 necessarily an error for an application to attempt to insert more 84 than this many frames into the stream at once. However, exceeding 85 available resources may cause a producer to block or return an error, 86 as per its specification. 87 88 3.10.4.x+1 EGL_CONSUMER_MAX_FRAME_HINT_NV Attribute 89 90 The EGL_CONSUMER_MAX_FRAME_HINT_NV attribute indicates a limit on how 91 many frames the consumer application intends to acquire at the same 92 time. Its default value EGL_DONT_CARE. 93 94 The implementation may make use of this hint to determine how many 95 buffers or other resources to allocate for the stream. It is not 96 necessarily an error for an application to attempt to acquire more 97 than this many frames at once. However, exceeding available resources 98 may cause the consumer or producer to block or return an error, as per 99 their specifications. 100 101Add to the description of eglStreamConsumerOutputEXT in the 102EGL_KHR_stream_consumer_egloutput extension 103 104 When the producer generates frames faster than the output device can 105 display them, <stream>'s EGL_CONSUMER_MAX_FRAME_HINT_NV attribute can 106 be used to throttle the output. No more than the specified number of 107 frames will be scheduled for display at a time. If specified, the value 108 should be set to at least 2, to allow one frame to be displayed while 109 another is acquired and scheduled for display. 110 111Issues 112 113 1. Is a generic stream extension really necessary, or can such 114 limits instead be imposed in the producer and consumer 115 interfaces? 116 117 RESOLVED: Yes, it is necessary. There are several use cases 118 where an application may need to impose limits and cannot do so 119 through the producer and consumer interfaces: 120 a) The producer and client interfaces are already published and 121 do not allow room for extension to impose limits. 122 b) The stream is cross-process, and one process needs to impose 123 limits on the endpoint provided by the other process. 124 In addition, a common method for imposing such limits simplifies 125 programming of large application suites which make use of 126 multiple types of producers and consumers, and allows the limits 127 on producer and consumer endpoints to be set to compatible 128 values. 129 130 2. Should the attributes be hints or hard limits? 131 132 RESOLVED: Hints. The variety of possible producers and consumers 133 makes it difficult to specify what the behavior should be if a 134 hard limit is exceeded. The goal here is to allow the application 135 to coordinate its resource requirements with the implementation. 136 If it fails to limit itself to the hinted values, we allow 137 producers or consumers to block or fail as appropriate for their 138 interfaces, but do not require it. 139 140Revision History 141 142 #4 (October 27, 2016) Daniel Kartch 143 - Clean up for publication 144 145 #3 (September 14, 2106) Daniel Kartch 146 - Switched from hard limits to hints 147 148 #2 (January 8, 2016) Daniel Kartch 149 - Assigned enum values 150 151 #1 (October 30, 2015) Daniel Kartch 152 - Initial draft 153