Name KHR_display_reference Name Strings EGL_KHR_display_reference Contributors James Jones Daniel Kartch Contacts James Jones, NVIDIA (jajones 'at' nvidia.com) Status Complete Ratified by the Khronos Board of Promoters on March 31, 2017. Version Version 4 - March 15, 2018 Number EGL Extension #126 Extension Type EGL client extension Dependencies Written based on the wording of the EGL 1.5 specification. Requires EGL_EXT_platform_base or EGL 1.5 Interacts with EGL platform extensions. Interacts with the EGL_EXT_device_query extension. Overview The existing semantics of EGLDisplay object lifetimes work well for applications in which one module manages all EGL usage, and in which EGL displays are expected to remain available until application termination once they are instantiated. However, EGL does not provide reasonable semantics in the case where applications rely on toolkit libraries which use EGL independently from the application itself. This issue can be solved by adding a per-EGLDisplay reference counter which is incremented by eglInitialize calls. Resource destruction can then be deferred until a corresponding number of eglTerminate calls is made. However, switching to this behavior universally could cause backwards incompatibility problems with existing applications that assume a single eglTerminate will immediately free resources regardless of how many times the display has been initialized. We therefore must support both behaviors. A new attribute specified when the EGLDisplay is obtained will indicate whether or not reference counting is enabled. If an application requests the EGLDisplay multiple times with different values for this attribute, two separate displays will be returned. The one potential drawaback is that these displays will have independent resource spaces, so objects allocated from one cannot be used by the other. However, the goal here is to support modules that access EGL independently. In such a use case, they are not likely to need to share resources with another module, particularly one that uses a different method for accessing the display. New Types None New Functions EGLBoolean eglQueryDisplayAttribKHR(EGLDisplay dpy, EGLint name, EGLAttrib *value); New Tokens Accepted as an attribute in the parameter of eglGetPlatformDisplay and the parameter of eglQueryDisplayAttribKHR: EGL_TRACK_REFERENCES_KHR 0x3352 In section "3.2 Initialization": Remove the sentence in the description of eglGetPlatformDisplay indicating no valid attribute names are defined, and add the following: The EGL_TRACK_REFERENCES_KHR attribute may be set to EGL_TRUE or EGL_FALSE to indicate whether or not an EGLDisplay that tracks reference counts for eglInitialize and eglTerminate calls (as described below) is desired. If not specified, the default is platform dependent. Implementations are not required to support both EGL_TRUE and EGL_FALSE for this attribute. If separate successful calls are made to eglGetPlatformDisplay requesting default and non- default behavior for reference counting, two independent EGLDisplays will be returned. Also add to the Errors section: An EGL_BAD_ATTRIBUTE error is generated if the requested value for EGL_TRACK_REFERENCES_KHR is not supported. Replace the first sentence of the second paragraph of the description of eglInitialize with: When a previously uninitialized display is initialized, its reference count will be set to one. Initializing an already- initialized display is allowed, and will return EGL_TRUE and update the EGL version numbers, but has no other effect except to increment the display's reference count if its EGL_TRACK_REFERENCES_KHR attribute is EGL_TRUE. Insert after the declaration of eglTerminate: If the specified display's EGL_TRACK_REFERENCES_KHR attribute is EGL_FALSE, eglTerminate will immediately set its reference count to zero. Otherwise, its reference count will be decremented if it is above zero. When an initialized display's reference count reaches zero, termination will occur. Replace the second sentence of the last paragraph with: All displays start out uninitialized with a reference count of zero. Add to the end of section "3.3 EGL Queries". To query non-string attributes of an initialized display, use: EGLBoolean eglQueryDisplayAttribKHR(EGLDisplay dpy, EGLint name, EGLAttrib *value); On success, EGL_TRUE is returned, and the value of the attribute specified by is returned in the space pointed to by . On failure, EGL_FALSE is returned. An EGL_NOT_INITIALIZED error is generated if EGL is not initialized for . An EGL_BAD_ATTRIBUTE error is generated if is not a valid value. Currently, the only valid attribute name is EGL_TRACK_REFERENCES_KHR. Interactions with EGL_KHR_platform_android: If eglGetPlatformDisplay() is called with set to EGL_PLATFORM_ANDROID_KHR, the default value of EGL_TRACK_REFERENCES_KHR is EGL_TRUE. Interactions with EGL_EXT_platform_device, EGL_KHR_platform_gbm, EGL_KHR_platform_x11, and EGL_KHR_platform_wayland: If eglGetPlatformDisplay() is called with set to EGL_PLATFORM_DEVICE_EXT, EGL_PLATFORM_GBM_KHR, EGL_PLATFORM_X11_KHR, or EGL_PLATFORM_WAYLAND_KHR, the default value of EGL_TRACK_REFERENCES_KHR is EGL_FALSE. Interactions with EGL_EXT_device_query: The eglQueryDisplayAttribKHR function defined here is equivalent to eglQueryDisplayAttribEXT defined by EGL_EXT_device_query, and the attribute names supported are a superset of those provided by both extensions and any others which rely on them. Issues 1. What is the default value for EGL_TRACK_REFERENCES_KHR? RESOLUTION: For backwards compatibility reasons, the default value is platform-specific. The Android platform has historically implemented the behavior of EGL_TRACK_REFERENCES_KHR = EGL_TRUE, while other platforms defaulted to the opposite behavior. Application components capable of supporting either behavior will be able to query the value to determine how to proceed. 2. Should the value of EGL_TRACK_REFERENCES_KHR affect whether eglGetPlatformDisplay returns a new display handle or an existing one given otherwise identical parameters? RESOLUTION: Yes. For any given combination of platform display handle and other attributes, calling eglGetPlatformDisplay with different values for EGL_TRACK_REFERENCES_KHR will result in two different EGLDisplay handles being returned. Resources created with respect to one of these EGLDisplays will not be accessible to the other. This restriction is unlikely to cause issues, because the reference counting is added primarily to support independent toolkits. Application components which independently initialize and terminate the display are not likely to share resources, particularly if they use different methods for that initialization. 3. Should the new display attribute be queryable? RESOLUTION: Yes. Not all implemenations will support both TRUE and FALSE for this attribute. Application components capable of supporting either value will allow the default to be chosen, and then query the value to determine how to handle termination. 4. Should implementations which support this extension be required to support both TRUE and FALSE for the attribute? RESOLUTION: No. Lack of refcounting in the core specification is considered by many to be a flaw, and some implementations/platforms will choose to always provide refcounting behavior. This technically makes them non-compliant. The addition of this extension should allow that deviation. Revision History #4 (March 15, 2018) Jon Leech - Change extension number from 118 to 126 to avoid an accidental collision. #3 (January 12, 2017) Daniel Kartch - Change to KHR. - Allocate enum value. #2 (November 15, 2016) Daniel Kartch - Full termination portion split off into separate extension EGL_XXX_full_termination. - Update reference counting to have separate EGLDisplays for the same native display, one with reference counting and one without. - Add query function to determine attribute value. #1 (October 28, 2014) James Jones - Initial draft as EGL_XXX_display_reference