1Name 2 3 KHR_wait_sync 4 5Name Strings 6 7 EGL_KHR_wait_sync 8 9Contributors 10 11 Jon Leech 12 Tom Cooksey 13 Alon Or-bach 14 15Contacts 16 17 Jon Leech (jon 'at' alumni.caltech.edu) 18 19Notice 20 21 Copyright (c) 2012-2014 The Khronos Group Inc. Copyright terms at 22 http://www.khronos.org/registry/speccopyright.html 23 24Status 25 26 Complete. 27 Approved by the Khronos Board of Promoters on October 26, 2012. 28 29Version 30 31 Version 7, March 12, 2014 32 33Number 34 35 EGL Extension #43 36 37Dependencies 38 39 EGL 1.1 is required. 40 41 EGL_KHR_fence_sync is required. 42 43 EGL_KHR_reusable_sync is affected by this extension. 44 45 This extension is written against the wording of the EGL 1.4 46 Specification. 47 48Overview 49 50 This extension adds the ability to wait for signaling of sync objects 51 in the server for a client API context, rather than in the application 52 thread bound to that context. This form of wait does not necessarily 53 block the application thread which issued the wait (unlike 54 eglClientWaitSyncKHR), so the application may continue to issue commands 55 to the client API context or perform other work in parallel, leading to 56 increased performance. The best performance is likely to be achieved by 57 implementations which can perform this new wait operation in GPU 58 hardware, although this is not required. 59 60New Types 61 62 None 63 64New Procedures and Functions 65 66 EGLint eglWaitSyncKHR( 67 EGLDisplay dpy, 68 EGLSyncKHR sync, 69 EGLint flags) 70 71New Tokens 72 73 None 74 75Changes to Chapter 3 of the EGL 1.4 Specification (EGL Functions and Errors) 76 77 Add to section 3.8.1 "Sync Objects" (as already modified 78 by EGL_KHR_fence_sync and/or EGL_KHR_reusable_sync): 79 80 Following the description of eglClientWaitSyncKHR, add: 81 82 "The command 83 84 EGLint eglWaitSyncKHR(EGLDisplay dpy, 85 EGLSyncKHR sync, 86 EGLint flags) 87 88 is similar to eglClientWaitSyncKHR, but instead of blocking and not 89 returning to the application until <sync> is signaled, eglWaitSyncKHR 90 returns immediately. On success, EGL_TRUE is returned, and the server 91 for the client API context [fn1] will block until <sync> is signaled 92 [fn2]. 93 [fn1 - the server may choose to wait either in the CPU executing 94 server-side code, or in the GPU hardware if it supports this 95 operation.] 96 [fn2 - eglWaitSyncKHR allows applications to continue to queue 97 commands from the application in anticipation of the sync being 98 signaled, potentially increasing parallelism between application, 99 client API server code, and the GPU. The server only blocks 100 execution of commands for the specific context on which 101 eglWaitSyncKHR was issued; other contexts implemented by the same 102 server are not affected.] 103 104 <sync> has the same meaning as for eglClientWaitSyncKHR. 105 106 <flags> must be 0. 107 108 Errors 109 ------ 110 eglWaitSyncKHR returns EGL_FALSE on failure and generates an error as 111 specified below, but does not cause the server for the client API 112 context to block. 113 114 * If the current context for the currently bound client API does not 115 support the client API extension indicating it can perform server 116 waits, an EGL_BAD_MATCH error is generated. 117 * If no context is current for the currently bound client API (i.e., 118 eglGetCurrentContext returns EGL_NO_CONTEXT), an EGL_BAD_MATCH error 119 is generated. 120 * If <dpy> does not match the EGLDisplay passed to eglCreateSyncKHR 121 when <sync> was created, the behavior is undefined. 122 * If <sync> is not a valid sync object for <dpy>, an EGL_BAD_PARAMETER 123 error is generated. 124 * If <flags> is not 0, an EGL_BAD_PARAMETER error is generated. 125 126 Each client API which supports eglWaitSyncKHR indicates this support in 127 the form of a client API extension. If the GL_OES_EGL_sync extension is 128 supported by any version of OpenGL ES, a server wait may be performed 129 when the currently bound API is OpenGL ES. If the VG_KHR_EGL_sync 130 extension is supported by OpenVG, a server wait may be performed when 131 the currently bound API is OpenVG." 132 133 Add new subsubsection following eglWaitSyncKHR: 134 135 "Multiple Waiters 136 ---------------- 137 138 It is possible for the application thread calling a client API to be 139 blocked on a sync object in a eglClientWaitSyncKHR command, the server 140 for that client API context to be blocked as the result of a previous 141 eglWaitSyncKHR command, and for additional eglWaitSyncKHR commands to be 142 queued in the server, all for a single sync object. When the sync object 143 is signaled in this situation, the client will be unblocked, the server 144 will be unblocked, and all such queued eglWaitSyncKHR commands will 145 continue immediately when they are reached. 146 147 Sync objects may be waited on or signaled from multiple contexts of 148 different client API types in multiple threads simultaneously, although 149 some client APIs may not support eglWaitSyncKHR. This support is 150 determined by client API-specific extensions." 151 152 Additions to the EGL_KHR_reusable_sync extension, modifying the description 153 of eglSignalSyncKHR to include both client and server syncs: 154 155 "... If as a result of calling eglSignalSyncKHR the status of <sync> 156 transitions from unsignaled to signaled, any eglClientWaitSyncKHR 157 * or eglWaitSyncKHR * 158 commands blocking on <sync> will unblock. ..." 159 160 Additions to the EGL_KHR_reusable_sync extension, modifying the description 161 of eglDestroySyncKHR to include both client and server syncs: 162 163 "... If any eglClientWaitSyncKHR 164 * or eglWaitSyncKHR * 165 commands are blocking on <sync> when eglDestroySyncKHR is called, they 166 will be woken up, as if <sync> were signaled." 167 168 169 Additions to the EGL_KHR_fence_sync extension, modifying the description 170 of eglCreateSyncKHR to include both client and server syncs: 171 172 "... causing any eglClientWaitSyncKHR 173 * or eglWaitSyncKHR * 174 commands (see below) blocking on <sync> to unblock ..." 175 176 Additions to the EGL_KHR_fence_sync extension, modifying the description 177 of eglDestroySyncKHR to include both client and server syncs: 178 179 "... If any eglClientWaitSyncKHR 180 * or eglWaitSyncKHR * 181 commands are blocking on <sync> when eglDestroySyncKHR is called, <sync> 182 is flagged for deletion and will be deleted when it is no longer 183 associated with any fence command and is no longer blocking any 184 eglClientWaitSyncKHR or eglWaitSyncKHR commands." 185 186 187Issues 188 189 1. Explain the key choices made in this extension. 190 191 RESPONSE: This extension has been written to behave as similarly as 192 possible to the glWaitSync functionality available in desktop OpenGL. 193 Server waits are functionality which was only available in GL syncs 194 until now. 195 196 In the interest of maintaining similarity with OpenGL sync objects, this 197 extension attempts to copy the glWaitSync functionality of OpenGL 198 wherever possible (both functionally and stylistically), only making 199 changes where needed to operate inside EGL (rather than a client API 200 context) and match EGL naming conventions. 201 202 2. Must all EGL client APIs support server waits? 203 204 PROPOSED: Only if the client APIs also support fence syncs, which also 205 interacts with the server for that client API. The same client API 206 extensions defining fence sync support (GL_OES_EGL_sync and 207 VG_KHR_EGL_sync) are used here to indicate server wait ability for those 208 client APIs. 209 210 Reusable syncs in EGL_KHR_reusable_sync do not have this dependency, 211 because it is (at least in principle) possible for eglClientWaitSyncKHR 212 to be performed entirely within the EGL implementation. However, 213 eglWaitSyncKHR requires cooperation of the client API, whether fence 214 syncs or reusable syncs are being waited upon. 215 216 It would be possible to completely decouple fence syncs and the ability 217 to do server waits, but this would require new client API extensions. 218 219 3. What is the relationship between EGL sync objects and OpenGL / OpenGL 220 ES sync objects? 221 222 RESPONSE: There is no direct relationship. GL and ES servers may not 223 even implement sync objects as defined by some versions of those APIs. 224 However, EGL sync objects are intended to be functionally equivalent to 225 GL sync objects, and the language describing them is drawn from the GL 226 specifications. Implementations supporting both forms of sync object 227 will probably use the same implementation internally. 228 229 4. Should eglWaitSyncKHR take a timeout as a parameter as its equivalent 230 in OpenGL / OpenGL ES and eglWaitClientKHR does? 231 232 PROPOSED: No. A timeout is of limited use to a well-behaved application. 233 If a timeout was added, the result of it expiring is likely to be a 234 corrupted output. Adding a timeout would likely necessitate a way to 235 query if the wait completed because the condition was signaled or 236 because of a timeout. There doesn't seem to be an obvious, elegant API 237 mechanism to do that. If a timeout is needed in the future, it can be 238 added via an additional extension with a new entry-point. 239 240 5. What happens if an application issues a server-side wait on a fence 241 which never gets signaled? 242 243 RESPONSE: Further rendering in the context which issued the server-side 244 wait will not progress. Any additional behavior is undefined and is 245 likely to be different depending on a particular implementation. Could 246 be handled in the same way as an extremely long-running GLSL shader. 247 248 6. Does this extension affect the destruction behavior? 249 250 RESOLVED: No. The behavior of eglDestroySyncKHR is determined by the type 251 of sync object, and is not affected by this extension. 252 253Revision History 254 255#7 (Alon Or-bach, March 12, 2014) 256 - Clarified that eglDestroySyncKHR behavior is set in 257 EGL_KHR_fence_sync / EGL_KHR_reusable_sync and is not modified by this 258 extension (bug 11458). 259#6 (Jon Leech, January 24, 2013) 260 - eglWaitSyncKHR causes a server wait in OpenGL ES when GL_OES_EGL_sync 261 is supported, not a client wait as formerly specified (Bug 9493). 262#5 (Jon Leech, October 31, 2012) 263 - Change return type of eglWaitSyncKHR in spec body to EGLint to match 264 New Functions section, and rearrange description of return type and 265 errors section for clarity. 266#4 (Tom Cooksey, August 16, 2012) 267 - Removed timeout parameter and text relating to it. Add issue 4 268 discussing timeout parameter. Add issue 5 explaining the behavior of 269 waiting on a never-signaled fence. Minor corrections to use US English. 270#3 (Jon Leech, June 26, 2012) 271 - Fix typos (bug 9137). 272#2 (Jon Leech, June 20, 2012) 273 - Clarifications and language cleanup (Bug 9137). Some paragraph 274 reflowing. Note that eglWaitSyncKHR only blocks the server for the 275 specific context on which the wait was issued. Add issue 3 discussing 276 relationship to GL/ES sync objects. 277#1 (Jon Leech, June 6, 2012) 278 - Initial draft branched from GL 4.x API spec language. 279