1Name 2 3 NV_stream_sync 4 5Name Strings 6 7 EGL_NV_stream_sync 8 9Contributors 10 11 Acorn Pooley 12 Marcus Lorentzon 13 14Contacts 15 16 Ian Stewart, NVIDIA (istewart 'at' nvidia.com) 17 18Status 19 20 Complete 21 22Version 23 24 Version 6, June 5, 2012 25 26Number 27 28 EGL Extension #56 29 30Dependencies 31 32 Requires EGL 1.2. 33 Requires EGL_KHR_stream extension 34 Requires EGL_KHR_reusable_sync 35 36 This extension is written based on the wording of the EGL 1.2 37 specification. 38 39Overview 40 41 This extension defines a new type of reusable sync object. This 42 sync object will be signaled each time a new image frame becomes 43 available in an EGLStream for the consumer to consume. 44 45New functions 46 47 EGLSyncKHR eglCreateStreamSyncNV( 48 EGLDisplay dpy, 49 EGLStreamKHR stream, 50 EGLenum type, 51 const EGLint *attrib_list); 52 53New Tokens 54 55 Accepted by the <type> parameter of eglCreateSyncKHR, and returned 56 in <value> when eglGetSyncAttribKHR is called with <attribute> 57 EGL_SYNC_TYPE_KHR: 58 59 EGL_SYNC_NEW_FRAME_NV 0x321F 60 61 62Add a new paragraph to section "3.8.1 Sync Objects" in the 63EGL_KHR_reusable_sync extension, just before the paragraph that 64mentions the eglClientWaitSyncKHR function: 65 66 The command 67 68 EGLSyncKHR eglCreateStreamSyncNV( 69 EGLDisplay dpy, 70 EGLStreamKHR stream, 71 EGLenum type, 72 const EGLint *attrib_list); 73 74 creates a sync object of the specified <type> associated with the 75 specified display <dpy> and the specified EGLStream <stream>, and 76 returns a handle to the new object. <attrib_list> is an 77 attribute-value list specifying other attributes of the sync 78 object, terminated by an attribute entry EGL_NONE. Attributes not 79 specified in the list will be assigned their default values. The 80 state of <stream> must not be EGL_STREAM_STATE_CREATED_KHR or 81 EGL_STREAM_STATE_DISCONNECTED_KHR. 82 83 If <type> is EGL_SYNC_NEW_FRAME_NV, a stream-new-frame reusable 84 sync object is created. In this case <attrib_list> must be NULL or 85 empty (containing only EGL_NONE). Attributes of the reusable 86 stream-new-frame sync object are set as follows: 87 88 Attribute Name Initial Attribute Value(s) 89 --------------- -------------------------- 90 EGL_SYNC_TYPE_KHR EGL_SYNC_NEW_FRAME_NV 91 EGL_SYNC_STATUS_KHR EGL_UNSIGNALED_KHR 92 93 Any time the state of <stream> transitions to 94 EGL_STREAM_STATE_NEW_FRAME_AVAILABLE_KHR (from any other state), 95 the returned stream-new-frame reusable sync object is signaled. 96 (This effectively means the sync object will become signaled 97 whenever the producer inserts a new image frame into the 98 EGLStream.) 99 100 EGL does not automatically unsignal the stream-new-frame reusable 101 sync object. Generally applications will want to unsignal the 102 sync object after it has been signaled so that the availability 103 of the next frame can 104 be detected. 105 106 Errors 107 ------ 108 109 * If <dpy> is not the name of a valid, initialized EGLDisplay, 110 EGL_NO_SYNC_KHR is returned and an EGL_BAD_DISPLAY error is 111 generated. 112 * If <attrib_list> is neither NULL nor empty (containing only 113 EGL_NONE), EGL_NO_SYNC_KHR is returned and an EGL_BAD_ATTRIBUTE 114 error is generated. 115 * If <stream> is not a valid EGLStream created for <dpy>, 116 EGL_NO_SYNC_KHR is returned and an EGL_BAD_STREAM error is 117 generated. 118 * If <stream>'s state is EGL_STREAM_STATE_CREATED_KHR or 119 EGL_STREAM_STATE_DISCONNECTED_KHR then EGL_NO_SYNC_KHR is 120 returned and an EGL_BAD_ACCESS error is generated. 121 * If a sync object of <type> has already been created for 122 <stream> (and not destroyed), EGL_NO_SYNC_KHR is returned and 123 an EGL_BAD_ACCESS error is generated. 124 * If <type> is not a supported type of stream sync object, 125 EGL_NO_SYNC_KHR is returned and an EGL_BAD_ATTRIBUTE error is 126 generated. 127 128Issues 129 1. Is this extension useful, or does the built in blocking 130 behavior of the consumer described by the 131 EGL_NV_stream_consumer_gltexture extension render this 132 un-useful? 133 134 RESOLVED: Yes. It is useful to have a thread waiting on the 135 signal. 136 137 2. Does EGL automatically unsignal the sync object? 138 139 RESOLVED: No. After the sync object has been signaled, it is 140 up to the application to unsignal it before waiting on it 141 again. It is important to check for the availability of 142 another frame by querying EGL_PRODUCER_FRAME_KHR after 143 unsignaling the sync object and before waiting on the sync 144 object to prevent a race condition. This can be done using 145 the following code: 146 147 void ConsumeFrames(EGLDisplay dpy, EGLStreamKHR stream) 148 { 149 EGLuint64KHR last_frame = 0; 150 EGLuint64KHR new_frame = 0; 151 EGLSyncKHR sync; 152 153 sync = eglCreateStreamSyncNV(dpy, 154 stream, 155 EGL_SYNC_NEW_FRAME_NV, 156 0); 157 158 for(;;) { 159 eglSignalSyncKHR(dpy, sync, EGL_UNSIGNALED_KHR); 160 eglQueryStreamu64KHR(dpy, 161 stream, 162 EGL_PRODUCER_FRAME_KHR, 163 &new_frame); 164 if (new_frame != last_frame) { 165 last_frame = new_frame; 166 ConsumeNewFrame(stream); 167 } else { 168 eglClientWaitSyncKHR(dpy, sync, 0, EGL_FOREVER_KHR); 169 } 170 } 171 } 172 173Revision History 174 175 #7 (July 10, 2013) Jon Leech 176 - Fix spelling of 'signalled' -> 'signaled' and assign extension 177 number for publication. 178 179 #6 (June 5, 2012) Acorn Pooley 180 - Add error if stream is in state EGL_STREAM_STATE_CREATED_KHR 181 or EGL_STREAM_STATE_DISCONNECTED_KHR when sync is created. 182 183 #5 (September 30, 2011) Acorn Pooley 184 - Change eglCreateStreamSyncKHR to eglCreateStreamSyncNV 185 186 #4 (September 28, 2011) Acorn Pooley 187 - Add issue 2 188 - Fix return type of eglCreateStreamSyncNV 189 190 #3 (September 27, 2011) Acorn Pooley 191 - Assign enum values (bug 8064) 192 193 #2 (July 6, 2011) Acorn Pooley 194 - Rename EGL_KHR_image_stream to EGL_KHR_stream 195 196 #1 (June 30, 2011) Acorn Pooley 197 - Initial draft 198 199