KHR_display_reference

EGL_KHR_display_reference

James Jones
Daniel Kartch

James Jones,  NVIDIA  (jajones 'at' nvidia.com)

Complete
Ratified by the Khronos Board of Promoters on March 31, 2017.

Version 4 - March 15, 2018

EGL Extension #126

EGL client extension

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.

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.

None

EGLBoolean eglQueryDisplayAttribKHR(EGLDisplay dpy,
                                    EGLint name,
                                    EGLAttrib *value);

Accepted as an attribute in the <attrib_list> parameter of
eglGetPlatformDisplay and the <name> parameter of
eglQueryDisplayAttribKHR:

    EGL_TRACK_REFERENCES_KHR                         0x3352

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.

An EGL_BAD_ATTRIBUTE error is generated if the requested value for
EGL_TRACK_REFERENCES_KHR is not supported.

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.

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.

All displays start out uninitialized with a reference count of zero.

    EGLBoolean eglQueryDisplayAttribKHR(EGLDisplay dpy,
                                        EGLint name,
                                        EGLAttrib *value);

On success, EGL_TRUE is returned, and the value of the attribute
specified by <name> is returned in the space pointed to by <value>.

On failure, EGL_FALSE is returned.  An EGL_NOT_INITIALIZED error
is generated if EGL is not initialized for <dpy>.  An
EGL_BAD_ATTRIBUTE error is generated if <name> is not a valid
value. Currently, the only valid attribute name is
EGL_TRACK_REFERENCES_KHR.

If eglGetPlatformDisplay() is called with <platform> set to
EGL_PLATFORM_ANDROID_KHR, the default value of
EGL_TRACK_REFERENCES_KHR is EGL_TRUE.

If eglGetPlatformDisplay() is called with <platform> 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.

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.

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.

#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