1Name 2 3 NV_stream_fifo_synchronous 4 5Name Strings 6 7 EGL_NV_stream_fifo_synchronous 8 9Contributors 10 11 Daniel Kartch 12 Adam Cheney 13 14Contacts 15 16 Daniel Kartch, NVIDIA (dkartch 'at' nvidia.com) 17 18Status 19 20 Draft 21 22Version 23 24 Version 4 - October 27, 2016 25 26Number 27 28 EGL Extension #111 29 30Extension Type 31 32 EGL display extension 33 34Dependencies 35 36 Requires EGL_KHR_stream_fifo 37 38Interactions with EGL_NV_stream_sync and 39EGL_KHR_stream_consumer_gltexture 40 41 This extension affects implementations of stream synchronization and 42 GL texture consumer extensions in that it alters when functions 43 waiting for new frames will be unblocked. However, as these waits 44 are still tied to transitions to the 45 EGL_STREAM_STATE_NEW_FRAME_AVAILALBLE_KHR state, no changes are 46 required to the wording of those specifications. 47 48Overview 49 50 On platforms which support asynchronous rendering, frames may be 51 inserted into a stream by the producer and become available to the 52 consumer before rendering of the images has completed. When this 53 happens, commands issued by the consumer which read from the image 54 must implicitly wait before they can be executed. In many use cases, 55 this is desirable behavior. Rendering pipelines are kept full, and 56 frames are created and processed as fast as possible. 57 58 However, in the case of a compositor which is consuming frames from 59 multiple producers at once, combining them into a single output 60 image, this can slow the compositor to the frame rate of the slowest 61 producer. If the application acquires and uses an image from one 62 producer which requires a long time to finish rendering, it will be 63 prevented from presenting new frames from faster producers in a 64 timely fashion. In this case, the compositor would prefer to reuse 65 an older frame from the slower producer until the new one is ready. 66 67 This could be handled with existing interfaces by the producer 68 issuing appropriate Finish call before inserting the frame into the 69 stream. However this requires the producer to have knowledge of the 70 consumer's use case, and also introduces undesirable bubbles into 71 the producer's pipeline which will slow it even further. 72 73 This extension allows streams to be configured to defer the 74 availability of new frames inserted by the producer until they are 75 ready to be used. The producer proceeds as normal, but the frames 76 visible to the consumer through query and acquire operations do not 77 update immediately. 78 79 Interactions of this feature with a stream operating in mailbox mode 80 would be hard to define. Because newly inserted frames replace 81 previous unacquired ones, it is possible that the consumer would 82 never see a completed frame become available. Therefore this feature 83 is only available for streams operating in FIFO mode. 84 85New Types 86 87 None 88 89New Functions 90 91 None 92 93New Tokens 94 95 Accepted as an attribute name in the <attrib_list> parameter of 96 eglCreateStreamKHR and a the <attribute> parameter of 97 eglQueryStreamKHR: 98 99 EGL_STREAM_FIFO_SYNCHRONOUS_NV 0x3336 100 101Add new entry to table "3.10.4.4 EGLStream Attributes" in the 102EGL_KHR_stream extension 103 104 Attribute Read/Write Type Section 105 ------------------------------ ---------- ---------- -------- 106 EGL_STREAM_FIFO_SYNCHRONOUS_NV io EGLBoolean 3.10.4.y 107 108Add new subsection to section "3.10.4 EGLStream Attributes" in the 109EGL_KHR_stream extension 110 111 3.10.4.y EGL_STREAM_FIFO_SYNCHRONOUS_NV Attribute 112 113 The EGL_STREAM_FIFO_SYNCHRONOUS_NV attribute controls whether frames 114 inserted by the producer become available to the consumer 115 synchronously or asynchronously. If set to EGL_FALSE, then when a 116 present operation for a new frame successfully completes, the state 117 will immediately become EGL_STREAM_NEW_FRAME_AVAILABLE_KHR, queries 118 of the most recently produced frame will indicate this frame, and 119 acquire operations will be able to retrieve this frame. If set to 120 EGL_TRUE, then until any asynchronous rendering for this frame 121 completes, the state will not update, any queries of the most 122 recently produced frame will only indicate the frame whose rendering 123 most recently completed, and acquire operations will only obtain 124 older completed frames. 125 126 The default value is EGL_FALSE. If set to EGL_TRUE, the value of 127 EGL_STREAM_FIFO_LENGTH_KHR must be non-zero, or an EGL_BAD_MATCH 128 error will be generated. 129 130Replace first two sentences of section "3.10.4.4 EGL_PRODUCER_FRAME 131Attribute" in the EGL_KHR_stream extension 132 133 The EGL_PRODUCER_FRAME_KHR attribute indicates how many image 134 frames have become available for the consumer to acquire. This is 135 also known as the "frame number" of the most recent ready frame 136 (where the first frame inserted has a frame number of 1). In 137 asynchronous operation, this is the frame most recently inserted by 138 the producer. In synchronous operation, this is the frame whose 139 image content generation has most recently finished. 140 141Replace contents of section "3.10.4.x+3 EGL_STREAM_TIME_PRODUCER_KHR" in 142the EGL_KHR_stream_fifo extension 143 144 This indicates the timestamp of the most recent ready frame in the 145 EGLStream (i.e. frame number EGL_PRODUCER_FRAME_KHR). 146 147Replace the second through fifth paragraphs of "3.10.5.2 EGLStream operation 148in fifo mode" in the EGL_KHR_stream_fifo extension. 149 150 In fifo mode the EGLStream conceptually operates as a fifo. An image 151 frame in the fifo is considered "ready" if all operations on the 152 image scheduled prior to its insertion in the stream have completed, 153 or if the value of EGL_STREAM_FIFO_SYNCHRONOUS_NV is EGL_FALSE. 154 155 When the consumer wants to consume a new image frame, behavior 156 depends on the state of the EGLStream. If the state is 157 EGL_STREAM_STATE_NEW_FRAME_AVAILABLE_KHR then the image frame at the 158 tail of the fifo is ready, and is removed from the fifo. If the 159 state is EGL_STREAM_STATE_OLD_FRAME_AVAILABLE_KHR then the fifo has 160 no ready image frames and the consumer consumes the same frame that 161 it most recently consumed. Otherwise there are no image frames 162 available to consume (behavior in this case is described in the 163 documentation for each type of consumer - see section "3.10.2 164 Connecting an EGLStream to a consumer"). 165 166 When EGL_STREAM_FIFO_SYNCHRONOUS_NV is EGL_FALSE, any consumer 167 operations which read from the image frame must implicitly wait for 168 any producer operations used to generate the image contents to 169 complete. Apart from the assumption that any such operations will 170 eventually finish, there are no guaranteed bounds on the time 171 required, and therefore no guaranteed bounds on when the consumer's 172 operations will complete. In cases where reusing a previous frame is 173 preferable to unknown latency between the time a consumer acquires a 174 new frame and the time its processing of that frame is done, 175 EGL_STREAM_FIFO_SYNCHRONOUS_NV should be set to EGL_TRUE. 176 177 If there is no new ready frame at the tail of the fifo when the 178 consumer is finished consuming an image frame then the consumer 179 holds on to the image frame in case it needs to be consumed again 180 later (this happens if the consumer wants to consume another image 181 frame before the producer has inserted a new image frame into the 182 fifo, or before any such frame has finished rendering in the case of 183 synchronous operation). In this case the state of the EGLStream 184 will be EGL_STREAM_STATE_OLD_FRAME_AVAILABLE_KHR until a new image 185 frame is ready (or until the state becomes 186 EGL_STREAM_STATE_DISCONNECTED_KHR). 187 188 The producer inserts image frames at the head of the fifo. If the 189 fifo is full (already contains <L> image frames, where <L> is the 190 value of the EGL_STREAM_FIFO_LENGTH_KHR attribute) then the producer 191 is stalled until the fifo is no longer full. When there is at 192 least one ready frame at the tail of the fifo, the EGLStream state 193 is EGL_STREAM_STATE_NEW_FRAME_AVAILABLE_KHR. 194 195Issues 196 197 None 198 199Revision History 200 201 #4 (October 27, 2016) Daniel Kartch 202 - Clean up for publication 203 204 #3 (September 30, 2015) Daniel Kartch 205 - Reserve enum. 206 207 #2 (March 30, 2015) Daniel Kartch 208 - Fix grammatical and typographical errors. 209 210 #1 (March 27, 2015) Daniel Kartch 211 - Initial draft 212