1Name 2 3 KHR_display_reference 4 5Name Strings 6 7 EGL_KHR_display_reference 8 9Contributors 10 11 James Jones 12 Daniel Kartch 13 14Contacts 15 16 James Jones, NVIDIA (jajones 'at' nvidia.com) 17 18Status 19 20 Complete 21 Ratified by the Khronos Board of Promoters on March 31, 2017. 22 23Version 24 25 Version 4 - March 15, 2018 26 27Number 28 29 EGL Extension #126 30 31Extension Type 32 33 EGL client extension 34 35Dependencies 36 37 Written based on the wording of the EGL 1.5 specification. 38 39 Requires EGL_EXT_platform_base or EGL 1.5 40 41 Interacts with EGL platform extensions. 42 43 Interacts with the EGL_EXT_device_query extension. 44 45Overview 46 47 The existing semantics of EGLDisplay object lifetimes work well for 48 applications in which one module manages all EGL usage, and in which 49 EGL displays are expected to remain available until application 50 termination once they are instantiated. However, EGL does not 51 provide reasonable semantics in the case where applications rely on 52 toolkit libraries which use EGL independently from the application 53 itself. 54 55 This issue can be solved by adding a per-EGLDisplay reference 56 counter which is incremented by eglInitialize calls. Resource 57 destruction can then be deferred until a corresponding number of 58 eglTerminate calls is made. However, switching to this behavior 59 universally could cause backwards incompatibility problems with 60 existing applications that assume a single eglTerminate will 61 immediately free resources regardless of how many times the display 62 has been initialized. 63 64 We therefore must support both behaviors. A new attribute specified 65 when the EGLDisplay is obtained will indicate whether or not 66 reference counting is enabled. If an application requests the 67 EGLDisplay multiple times with different values for this attribute, 68 two separate displays will be returned. The one potential drawaback 69 is that these displays will have independent resource spaces, so 70 objects allocated from one cannot be used by the other. However, the 71 goal here is to support modules that access EGL independently. In 72 such a use case, they are not likely to need to share resources with 73 another module, particularly one that uses a different method for 74 accessing the display. 75 76New Types 77 78 None 79 80New Functions 81 82 EGLBoolean eglQueryDisplayAttribKHR(EGLDisplay dpy, 83 EGLint name, 84 EGLAttrib *value); 85 86New Tokens 87 88 Accepted as an attribute in the <attrib_list> parameter of 89 eglGetPlatformDisplay and the <name> parameter of 90 eglQueryDisplayAttribKHR: 91 92 EGL_TRACK_REFERENCES_KHR 0x3352 93 94In section "3.2 Initialization": 95 96Remove the sentence in the description of eglGetPlatformDisplay 97indicating no valid attribute names are defined, and add the following: 98 99 The EGL_TRACK_REFERENCES_KHR attribute may be set to EGL_TRUE or 100 EGL_FALSE to indicate whether or not an EGLDisplay that tracks 101 reference counts for eglInitialize and eglTerminate calls (as 102 described below) is desired. If not specified, the default is 103 platform dependent. Implementations are not required to support both 104 EGL_TRUE and EGL_FALSE for this attribute. If separate successful 105 calls are made to eglGetPlatformDisplay requesting default and non- 106 default behavior for reference counting, two independent EGLDisplays 107 will be returned. 108 109Also add to the Errors section: 110 111 An EGL_BAD_ATTRIBUTE error is generated if the requested value for 112 EGL_TRACK_REFERENCES_KHR is not supported. 113 114Replace the first sentence of the second paragraph of the description of 115eglInitialize with: 116 117 When a previously uninitialized display is initialized, its 118 reference count will be set to one. Initializing an already- 119 initialized display is allowed, and will return EGL_TRUE and update 120 the EGL version numbers, but has no other effect except to increment 121 the display's reference count if its EGL_TRACK_REFERENCES_KHR 122 attribute is EGL_TRUE. 123 124Insert after the declaration of eglTerminate: 125 126 If the specified display's EGL_TRACK_REFERENCES_KHR attribute is 127 EGL_FALSE, eglTerminate will immediately set its reference count 128 to zero. Otherwise, its reference count will be decremented if it 129 is above zero. When an initialized display's reference count reaches 130 zero, termination will occur. 131 132Replace the second sentence of the last paragraph with: 133 134 All displays start out uninitialized with a reference count of zero. 135 136Add to the end of section "3.3 EGL Queries". 137 138 To query non-string attributes of an initialized display, use: 139 140 EGLBoolean eglQueryDisplayAttribKHR(EGLDisplay dpy, 141 EGLint name, 142 EGLAttrib *value); 143 144 On success, EGL_TRUE is returned, and the value of the attribute 145 specified by <name> is returned in the space pointed to by <value>. 146 147 On failure, EGL_FALSE is returned. An EGL_NOT_INITIALIZED error 148 is generated if EGL is not initialized for <dpy>. An 149 EGL_BAD_ATTRIBUTE error is generated if <name> is not a valid 150 value. Currently, the only valid attribute name is 151 EGL_TRACK_REFERENCES_KHR. 152 153Interactions with EGL_KHR_platform_android: 154 155 If eglGetPlatformDisplay() is called with <platform> set to 156 EGL_PLATFORM_ANDROID_KHR, the default value of 157 EGL_TRACK_REFERENCES_KHR is EGL_TRUE. 158 159Interactions with EGL_EXT_platform_device, EGL_KHR_platform_gbm, 160EGL_KHR_platform_x11, and EGL_KHR_platform_wayland: 161 162 If eglGetPlatformDisplay() is called with <platform> set to 163 EGL_PLATFORM_DEVICE_EXT, EGL_PLATFORM_GBM_KHR, EGL_PLATFORM_X11_KHR, 164 or EGL_PLATFORM_WAYLAND_KHR, the default value of 165 EGL_TRACK_REFERENCES_KHR is EGL_FALSE. 166 167Interactions with EGL_EXT_device_query: 168 169 The eglQueryDisplayAttribKHR function defined here is equivalent to 170 eglQueryDisplayAttribEXT defined by EGL_EXT_device_query, and the 171 attribute names supported are a superset of those provided by both 172 extensions and any others which rely on them. 173 174Issues 175 176 1. What is the default value for EGL_TRACK_REFERENCES_KHR? 177 178 RESOLUTION: For backwards compatibility reasons, the default 179 value is platform-specific. The Android platform has 180 historically implemented the behavior of 181 EGL_TRACK_REFERENCES_KHR = EGL_TRUE, while other platforms 182 defaulted to the opposite behavior. Application components 183 capable of supporting either behavior will be able to query 184 the value to determine how to proceed. 185 186 2. Should the value of EGL_TRACK_REFERENCES_KHR affect whether 187 eglGetPlatformDisplay returns a new display handle or an 188 existing one given otherwise identical parameters? 189 190 RESOLUTION: Yes. For any given combination of platform display 191 handle and other attributes, calling eglGetPlatformDisplay 192 with different values for EGL_TRACK_REFERENCES_KHR will result 193 in two different EGLDisplay handles being returned. 194 195 Resources created with respect to one of these EGLDisplays will 196 not be accessible to the other. This restriction is unlikely to 197 cause issues, because the reference counting is added primarily 198 to support independent toolkits. Application components which 199 independently initialize and terminate the display are not 200 likely to share resources, particularly if they use different 201 methods for that initialization. 202 203 3. Should the new display attribute be queryable? 204 205 RESOLUTION: Yes. Not all implemenations will support both TRUE 206 and FALSE for this attribute. Application components capable of 207 supporting either value will allow the default to be chosen, and 208 then query the value to determine how to handle termination. 209 210 4. Should implementations which support this extension be required 211 to support both TRUE and FALSE for the attribute? 212 213 RESOLUTION: No. Lack of refcounting in the core specification is 214 considered by many to be a flaw, and some implementations/platforms 215 will choose to always provide refcounting behavior. This technically 216 makes them non-compliant. The addition of this extension should allow 217 that deviation. 218 219Revision History 220 221 #4 (March 15, 2018) Jon Leech 222 223 - Change extension number from 118 to 126 to avoid an accidental 224 collision. 225 226 #3 (January 12, 2017) Daniel Kartch 227 228 - Change to KHR. 229 - Allocate enum value. 230 231 #2 (November 15, 2016) Daniel Kartch 232 233 - Full termination portion split off into separate extension 234 EGL_XXX_full_termination. 235 - Update reference counting to have separate EGLDisplays for 236 the same native display, one with reference counting and 237 one without. 238 - Add query function to determine attribute value. 239 240 #1 (October 28, 2014) James Jones 241 242 - Initial draft as EGL_XXX_display_reference 243