opengl/specs/EGL_ANDROID_native_fence_sync.txt

   1 Name
   2
   3     ANDROID_native_fence_sync
   4
   5 Name Strings
   6
   7     EGL_ANDROID_native_fence_sync
   8
   9 Contributors
  10
  11     Jamie Gennis
  12
  13 Contact
  14
  15     Jamie Gennis, Google Inc. (jgennis 'at' google.com)
  16
  17 Status
  18
  19     Complete
  20
  21 Version
  22
  23     Version 3, September 4, 2012
  24
  25 Number
  26
  27     EGL Extension #50
  28
  29 Dependencies
  30
  31     Requires EGL 1.1
  32
  33     This extension is written against the wording of the EGL 1.2 Specification
  34
  35     EGL_KHR_fence_sync is required.
  36
  37 Overview
  38
  39     This extension enables the creation of EGL fence sync objects that are
  40     associated with a native synchronization fence object that is referenced
  41     using a file descriptor.  These EGL fence sync objects have nearly
  42     identical semantics to those defined by the KHR_fence_sync extension,
  43     except that they have an additional attribute storing the file descriptor
  44     referring to the native fence object.
  45
  46     This extension assumes the existence of a native fence synchronization
  47     object that behaves similarly to an EGL fence sync object.  These native
  48     objects must have a signal status like that of an EGLSyncKHR object that
  49     indicates whether the fence has ever been signaled.  Once signaled the
  50     native object's signal status may not change again.
  51
  52 New Types
  53
  54     None.
  55
  56 New Procedures and Functions
  57
  58     EGLint eglDupNativeFenceFDANDROID(
  59                         EGLDisplay dpy,
  60                         EGLSyncKHR);
  61
  62 New Tokens
  63
  64     Accepted by the <type> parameter of eglCreateSyncKHR, and returned
  65     in <value> when eglGetSyncAttribKHR is called with <attribute>
  66     EGL_SYNC_TYPE_KHR:
  67
  68     EGL_SYNC_NATIVE_FENCE_ANDROID          0x3144
  69
  70     Accepted by the <attrib_list> parameter of eglCreateSyncKHR:
  71
  72     EGL_SYNC_NATIVE_FENCE_FD_ANDROID       0x3145
  73
  74     Accepted by the <attrib_list> parameter of eglCreateSyncKHR, and returned
  75     by eglDupNativeFenceFDANDROID in the event of an error:
  76
  77     EGL_NO_NATIVE_FENCE_FD_ANDROID         -1
  78
  79     Returned in <value> when eglGetSyncAttribKHR is called with <attribute>
  80     EGL_SYNC_CONDITION_KHR:
  81
  82     EGL_SYNC_NATIVE_FENCE_SIGNALED_ANDROID 0x3146
  83
  84 Changes to Chapter 3 of the EGL 1.2 Specification (EGL Functions and Errors)
  85
  86     Add the following after the sixth paragraph of Section 3.8.1 (Sync
  87     Objects), added by KHR_fence_sync
  88
  89     "If <type> is EGL_SYNC_NATIVE_FENCE_ANDROID, an EGL native fence sync
  90     object is created. In this case the EGL_SYNC_NATIVE_FENCE_FD_ANDROID
  91     attribute may optionally be specified. If this attribute is specified, it
  92     must be set to either a file descriptor that refers to a native fence
  93     object or to the value EGL_NO_NATIVE_FENCE_FD_ANDROID.
  94
  95     The default values for the EGL native fence sync object attributes are as
  96     follows:
  97
  98       Attribute Name                     Initial Attribute Value(s)
  99       ---------------                    --------------------------
 100       EGL_SYNC_TYPE_KHR                  EGL_SYNC_NATIVE_FENCE_ANDROID
 101       EGL_SYNC_STATUS_KHR                EGL_UNSIGNALED_KHR
 102       EGL_SYNC_CONDITION_KHR             EGL_SYNC_PRIOR_COMMANDS_COMPLETE_KHR
 103       EGL_SYNC_NATIVE_FENCE_FD_ANDROID   EGL_NO_NATIVE_FENCE_FD_ANDROID
 104
 105     If the EGL_SYNC_NATIVE_FENCE_FD_ANDROID attribute is not
 106     EGL_NO_NATIVE_FENCE_FD_ANDROID then the EGL_SYNC_CONDITION_KHR attribute is
 107     set to EGL_SYNC_NATIVE_FENCE_SIGNALED_ANDROID and the EGL_SYNC_STATUS_KHR
 108     attribute is set to reflect the signal status of the native fence object.
 109     Additionally, the EGL implementation assumes ownership of the file
 110     descriptor, so the caller must not use it after calling eglCreateSyncKHR."
 111
 112     Modify Section 3.8.1 (Sync Objects), added by KHR_fence_sync, starting at
 113     the seventh paragraph
 114
 115     "When a fence sync object is created or when an EGL native fence sync
 116     object is created with the EGL_SYNC_NATIVE_FENCE_FD_ANDROID attribute set
 117     to EGL_NO_NATIVE_FENCE_FD_ANDROID, eglCreateSyncKHR also inserts a fence
 118     command into the command stream of the bound client API's current context
 119     (i.e., the context returned by eglGetCurrentContext), and associates it
 120     with the newly created sync object.
 121
 122     After associating the fence command with an EGL native fence sync object,
 123     the next Flush() operation performed by the current client API causes a
 124     new native fence object to be created, and the
 125     EGL_SYNC_NATIVE_FENCE_ANDROID attribute of the EGL native fence object is
 126     set to a file descriptor that refers to the new native fence object. This
 127     new native fence object is signaled when the EGL native fence sync object
 128     is signaled.
 129
 130     When the condition of the sync object is satisfied by the fence command,
 131     the sync is signaled by the associated client API context, causing any
 132     eglClientWaitSyncKHR commands (see below) blocking on <sync> to unblock.
 133     If the sync object is an EGL native fence sync object then the native
 134     fence object is also signaled when the condition is satisfied. The
 135     EGL_SYNC_PRIOR_COMMANDS_COMPLETE_KHR condition is satisfied by completion
 136     of the fence command corresponding to the sync object and all preceding
 137     commands in the associated client API context's command stream. The sync
 138     object will not be signaled until all effects from these commands on the
 139     client API's internal and framebuffer state are fully realized. No other
 140     state is affected by execution of the fence command.
 141
 142     The EGL_SYNC_NATIVE_FENCE_SIGNALED_ANDROID condition is satisfied by the
 143     signaling of the native fence object referred to by the
 144     EGL_SYNC_NATIVE_FENCE_FD_ANDROID attribute. When this happens any
 145     eglClientWaitSyncKHR commands blocking on <sync> unblock."
 146
 147     Modify the list of eglCreateSyncKHR errors in Section 3.8.1 (Sync Objects),
 148     added by KHR_fence_sync
 149
 150     "Errors
 151     ------
 152
 153       * If <dpy> is not the name of a valid, initialized EGLDisplay,
 154         EGL_NO_SYNC_KHR is returned and an EGL_BAD_DISPLAY error is
 155         generated.
 156       * If <type> is EGL_SYNC_FENCE_KHR and <attrib_list> is neither NULL nor
 157         empty (containing only EGL_NONE), EGL_NO_SYNC_KHR is returned and an
 158         EGL_BAD_ATTRIBUTE error is generated.
 159       * If <type> is EGL_SYNC_NATIVE_FENCE_ANDROID and <attrib_list> contains
 160         an attribute other than EGL_SYNC_NATIVE_FENCE_FD_ANDROID,
 161         EGL_NO_SYNC_KHR is returned and an EGL_BAD_ATTRIBUTE error is
 162         generated.
 163       * If <type> is not a supported type of sync object,
 164         EGL_NO_SYNC_KHR is returned and an EGL_BAD_ATTRIBUTE error is
 165         generated.
 166       * If <type> is EGL_SYNC_FENCE_KHR or EGL_SYNC_NATIVE_FENCE_ANDROID and
 167         no context is current for the bound API (i.e., eglGetCurrentContext
 168         returns EGL_NO_CONTEXT), EGL_NO_SYNC_KHR is returned and an
 169         EGL_BAD_MATCH error is generated.
 170       * If <type> is EGL_SYNC_FENCE_KHR or EGL_SYNC_NATIVE_FENCE_ANDROID and
 171         <dpy> does not match the EGLDisplay of the currently bound context for
 172         the currently bound client API (the EGLDisplay returned by
 173         eglGetCurrentDisplay()) then EGL_NO_SYNC_KHR is returned and an
 174         EGL_BAD_MATCH error is generated.
 175       * If <type> is EGL_SYNC_FENCE_KHR or EGL_SYNC_NATIVE_FENCE_ANDROID and
 176         the currently bound client API does not support the client API
 177         extension indicating it can place fence commands, then EGL_NO_SYNC_KHR
 178         is returned and an EGL_BAD_MATCH error is generated."
 179
 180     Modify table 3.cc in Section 3.8.1 (Sync Objects), added by KHR_fence_sync
 181
 182     "
 183     Attribute                          Description                Supported Sync Objects
 184     -----------------                  -----------------------    ----------------------
 185     EGL_SYNC_TYPE_KHR                  Type of the sync object    All
 186     EGL_SYNC_STATUS_KHR                Status of the sync object  All
 187     EGL_SYNC_CONDITION_KHR             Signaling condition        EGL_SYNC_FENCE_KHR and
 188                                                                   EGL_SYNC_NATIVE_FENCE_ANDROID only
 189     "
 190
 191     Modify the second paragraph description of eglDestroySyncKHR in Section
 192     3.8.1 (Sync Objects), added by KHR_fence_sync
 193
 194     "If no errors are generated, EGL_TRUE is returned, and <sync> will no
 195     longer be the handle of a valid sync object.  Additionally, if <sync> is an
 196     EGL native fence sync object and the EGL_SYNC_NATIVE_FENCE_FD_ANDROID
 197     attribute is not EGL_NO_NATIVE_FENCE_FD_ANDROID then that file descriptor
 198     is closed."
 199
 200     Add the following after the last paragraph of Section 3.8.1 (Sync
 201     Objects), added by KHR_fence_sync
 202
 203     The command
 204
 205         EGLint eglDupNativeFenceFDANDROID(
 206                             EGLDisplay dpy,
 207                             EGLSyncKHR sync);
 208
 209     duplicates the file descriptor stored in the
 210     EGL_SYNC_NATIVE_FENCE_FD_ANDROID attribute of an EGL native fence sync
 211     object and returns the new file descriptor.
 212
 213     Errors
 214     ------
 215
 216       * If <sync> is not a valid sync object for <dpy>,
 217         EGL_NO_NATIVE_FENCE_FD_ANDROID is returned and an EGL_BAD_PARAMETER
 218         error is generated.
 219       * If the EGL_SYNC_NATIVE_FENCE_FD_ANDROID attribute of <sync> is
 220         EGL_NO_NATIVE_FENCE_FD_ANDROID, EGL_NO_NATIVE_FENCE_FD_ANDROID is
 221         returned and an EGL_BAD_PARAMETER error is generated.
 222       * If <dpy> does not match the display passed to eglCreateSyncKHR
 223         when <sync> was created, the behaviour is undefined."
 224
 225 Issues
 226
 227     1. Should EGLSyncKHR objects that wrap native fence objects use the
 228     EGL_SYNC_FENCE_KHR type?
 229
 230     RESOLVED: A new sync object type will be added.
 231
 232     We don't want to require all EGL fence sync objects to wrap native fence
 233     objects, so we need some way to tell the EGL implementation at sync object
 234     creation whether the sync object should support querying the native fence
 235     FD attribute. We could do this with either a new sync object type or with a
 236     boolean attribute. It might be nice to pick up future signaling conditions
 237     that might be added for fence sync objects, but there may be things that
 238     get added that don't make sense in the context of native fence objects.
 239
 240     2. Who is responsible for dup'ing the native fence file descriptors?
 241
 242     RESOLVED: Whenever a file descriptor is passed into or returned from an
 243     EGL call in this extension, ownership of that file descriptor is
 244     transfered. The recipient of the file descriptor must close it when it is
 245     no longer needed, and the provider of the file descriptor must dup it
 246     before providing it if they require continued use of the native fence.
 247
 248     3. Can the EGL_SYNC_NATIVE_FENCE_FD_ANDROID attribute be queried?
 249
 250     RESOLVED: No.
 251
 252     Returning the file descriptor owned by the EGL implementation would
 253     violate the file descriptor ownership rule described in issue #2. Having
 254     eglGetSyncAttribKHR return a different (dup'd) file descriptor each time
 255     it's called seems wrong, so a new function was added to explicitly dup the
 256     file descriptor.
 257
 258     That said, the attribute is useful both as a way to pass an existing file
 259     descriptor to eglCreateSyncKHR and as a way to describe the subsequent
 260     behavior of EGL native fence sync objects, so it is left as an attribute
 261     for which the value cannot be queried.
 262
 263 Revision History
 264
 265 #3 (Jamie Gennis, September 4, 2012)
 266     - Reworded the extension to refer to "native fence" objects rather than
 267     "Android fence" objects.
 268     - Added a paragraph to the overview that describes assumptions about the
 269     native fence sync objects.
 270
 271 #2 (Jamie Gennis, July 23, 2012)
 272     - Changed the file descriptor ownership transferring behavior.
 273     - Added the eglDupAndroidFenceFDANDROID function.
 274     - Removed EGL_SYNC_NATIVE_FENCE_FD_ANDROID from the table of gettable
 275     attributes.
 276     - Added language specifying that a native Android fence is created at the
 277     flush following the creation of an EGL Android fence sync object that is
 278     not passed an existing native fence.
 279
 280 #1 (Jamie Gennis, May 29, 2012)
 281     - Initial draft.