linux-opengl-abi-proposal.txt

New Linux OpenGL ABI Proposal

Background

    The current Linux OpenGL ABI [1] (the "2000 Linux OpenGL ABI") is over
    a decade old, and the industry has advanced significantly since then:

    * EGL has emerged as a compelling alternative window system binding,
      for use both within and without the X Window System.

    * The OpenGL API has evolved, reducing pressure, in modern usage, on
      OpenGL API call overhead.

    * One of the major short comings of the current ABI is that it does
      not allow multiple vendors' implementations to coexist on the file
      system.  Each vendor provides libGL.so.1; this can lead to library
      collisions and installation fights.  Each Linux distributor has
      been forced to invent its own library search path mechanism to
      resolve these conflicts.

    * In OpenGL 3.1, portions of the OpenGL API were removed (with some
      vendors continuing to provide the removed portions, via the
      ARB_compatibility extension).  A new Linux OpenGL ABI should
      potentially give vendors the option to not provide those entry
      points.

Requirements

    * This document proposes a new Linux ABI for OpenGL, OpenGL ES, GLX,
      and EGL on desktop Linux systems.  While this is hopefully
      useful for other UNIX and UNIX-like platforms, none are called
      out explicitly.  Further, this document does not try to standardize
      with Android or embedded Linux sorts of scenarios.

    * This document defines two ABIs:

        * The ABI between applications and a vendor-independent layer.

        * The ABI between a vendor-independent layer and a vendor
          implementation.

    * The existing ABI to applications must be preserved, though perhaps
      marked deprecated.  I.e., /usr/lib/libGL.so.1 must continue to
      exist for the foreseeable future, and continue to provide the
      entry points and semantics guaranteed by the 2000 Linux OpenGL ABI.
      How libGL.so.1 is implemented, and how vendor implementations fit
      into libGL.so.1, could change relative to the 2000 Linux OpenGL ABI.

    * Whatever minimum versions of OpenGL, OpenGL ES, EGL, and GLX are
      established by this standardization document, vendors must be allowed
      to provide extensions and newer API versions, beyond what is defined
      in this standard.

    * Multiple vendors' implementations must be able to coexist on the
      filesystem without distribution-specific "alternatives"-style selection.

    * It would be nice, from a design standpoint, to allow multiple vendor
      implementations to co-exist within the same process, and for the API
      library to dispatch to the current vendor library with per-context
      granularity.

Glossary

    * API Library: The vendor-neutral library that contains the API entry
      points.  In most cases, this should be fairly thin and simply dispatch
      to the vendor implementation.

    * Vendor Library: The vendor-provided library that provides the actual
      implementation.  The vendor libraries get enumerated, selected, and loaded
      by the API libraries.

    * Window system API: one of EGL or GLX.  Conceivably other window system
      APIs could be added in the future.

    * Client API: any rendering API that is used with a window system
      API.  OpenGL, OpenGL ES, OpenVG, etc.

Libraries

    The libraries to be provided are:

    * libGL.so.1
        * This would be a vendor-neutral API library.
        * Provides symbols for all OpenGL 1.2 entry points (as per [1]).
        * Provides symbols for all GLX 1.3 entry points (as per [1]).
        * Provides symbols for all OpenGL or GLX extension entry points
          currently provided by all vendors' libGL.so.1 libraries.
          I.e., this needs to provide the union of entry points that
          all vendors' libGL.so.1 libraries provide today, in order to
          be truly backwards compatible.
        * For libGL.so.1 entry points that are provided by libGLX.so.1
          or libOpenGL.so.1, libGL.so.1 would use ELF DT_FILTERing (see
          [2] and the GNU ld(1) man page) to route the entry point to
          libGLX.so.1 or libOpenGL.so.1.
        * For libGL.so.1 entry points that are not provided by libGLX.so.1
          or libOpenGL.so.1, libGL.so.1 would call libGLX.so.1's
          glXGetProcAddress to get the entry point.

    * libOpenGL.so.1
        * Provides symbols for all entry points in OpenGL 4.4, plus all
          entry points in the GL_ARB_compatibility extension.
        * Vendors can provide additional OpenGL entry points that can be
          retrieved via {egl,glX}GetProcAddress.
        * No EGL or GLX entry points are provided by this library; it
          is expected that libOpenGL.so.1 would be used in conjunction
          with one of the Window system libraries (libGLX.so.1 or
          libEGL.so.1).
        * Provides a mechanism for vendor libraries to install a dispatch table.
        * Provides a mechanism for vendor libraries to report their
          GetProcAddress-able functions.

    * libGLESv1_CM.so.1:
        * Provides symbols for all OpenGL ES 1 common profile entry points.

    * libGLESv2.so.1:
        * Provides symbols for all OpenGL ES 2 and 3 entry points.

    * libEGL.so.1
        * Provides symbols for all EGL 1.4 entry points.
        * Loads and dispatches to one or more vendor libraries.

    * libGLX.so.1
        * Provides symbols for all GLX 1.4 entry points.
        * Provides symbols for the GLX_ARB_create_context_profile extension.
        * Loads and dispatches to one or more vendor libraries.

    * libEGL_${VENDOR}.so.1
        * Provides a function that libEGL.so.1 can call to initialize and
          get the EGL dispatch table.
        * Expected to pull in the vendor's implementation of all the client
          APIs it supports, and register with the appropriate API library at
          MakeCurrent time.  The client API is specified by the application
          via eglBindAPI().
        * Must not export symbols with names that collide with the namespace
          of EGL (^egl.*) or OpenGL (^gl.*).

    * libGLX_${VENDOR}.so.1
        * Provides a function that libGLX.so.1 can call to initialize and
          get the GLX dispatch table.
        * Expected to pull in the vendor's implementation of the OpenGL
          client API, and register with libOpenGL.so.1 at MakeCurrent time.
        * Must not export symbols with names that collide with the namespace
          of GLX (^glX.*) or OpenGL (^gl.*).

    For more background, see [3].

    API libraries (i.e., everything other than the vendor libraries)
    are expected to change infrequently.  For maintenance reasons, they
    should be as simple/thin as reasonable and dispatch to vendors for as
    much as possible.  While Khronos members would author and maintain
    the API libraries, the source to them would presumably be hosted by
    Khronos, available to the general public.  We would recommend to Linux
    distributions to package the API libraries separately from vendor
    libraries (i.e., in separate packages from Mesa, NVIDIA, AMD, etc).

GLX

    The GLX API library should allow for a different vendor library per
    X screen, and dispatch to the correct vendor as early as possible
    (though, see Issue (9)).

    GLX 1.4 entry points fall into one of several categories:

    (1) Entry points that take an X Display pointer and an X screen number
        (or, an object, such as a GLXContext or GLXDrawable, that implies
        an X screen).  E.g.,

            Bool glXMakeCurrent(Display *dpy,
                                GLXDrawable drawable,
                                GLXContext ctx);

        Such functions could be implemented by dispatching to the appropriate
        vendor library based on Display and screen.

    (2) Entry points that operate on the current context.  E.g.,

            void glXWaitGL(void);

        Such functions could be implemented by dispatching to the appropriate
        vendor library based on the context of the current thread.

    (3) Entry points that are vendor-independent and return current state.
        E.g.,

            GLXContext glXGetCurrentContext(void);

        Such functions could be implemented entirely within the GLX
        API library.

    (4) "Special functions":

            void *glXGetProcAddress(const GLubyte *procName);
            const char *glXGetClientString(Display *dpy, int name);

        glXGetClientString() is addressed in the Issues section, and
        glXGetProcAddress is addressed in the Dispatching section.

    There would be an X protocol-based mechanism to map an X Display
    pointer and screen number to GLX vendor library, presumably using
    something like the existing X_DRI2Connect/DRI2DriverVDPAU request.
    This would be used similarly to how VDPAU determines the vendor
    library to load (see [4]).

    At MakeCurrent time, the vendor library would call a function in
    libOpenGL.so.1 to register its dispatch table.

EGL

    Similar to GLX, EGL API entry points fall into one of several categories:

    (1) Entry points that take an EGLDisplay.  E.g.,

            EGLSurface eglCreateWindowSurface(EGLDisplay dpy,
                                              EGLConfig config,
                                              EGLNativeWindowType win,
                                              const EGLint *attrib_list);

        Such functions could be implemented by dispatching to the appropriate
        vendor library based on EGLDisplay.

    (2) Entry points that operate on the current context.  E.g.,

            EGLBoolean eglWaitGL(void);

        Such functions could be implemented by dispatching to the appropriate
        vendor library based on the context of the current thread.

    (3) Entry points that are vendor-independent and return current state.  E.g.,

            EGLContext eglGetCurrentContext(void);

        Such functions could be implemented entirely within the EGL API library.

    (4) "Special functions":

            EGLDisplay eglGetDisplay(EGLNativeDisplayType display_id);
            EGLBoolean eglInitialize(EGLDisplay dpy, EGLint *major, EGLint *minor);
            void *eglGetProcAddress(const char *procname);

    The general dispatching approach in EGL would be the same as described
    above for GLX.  The vendor selection, done during eglInitialize(),
    would be more sophisticated than the GLX equivalent.

    The Mesa EGL implementation appears to be almost exactly this.

Dispatching

    All client API library (OpenGL, OpenGL ES) entry points are
    context-dependent.  All the entry points provided by these libraries
    would retrieve the current dispatch table from TLS and jump to the
    vendor implementation.

    There are two categories of client API library entry points:

    (1) A fixed list of entry points that all vendors must provide per
        this document.

    (2) A dynamic list of entry points (for extensions, newer versions
        of OpenGL, etc) which would only be accessible to applications via
        {glX,egl}GetProcAddress.  This list will vary by vendor.

    For category (1), the vendor would just provide an array of function
    pointers as the dispatch table.  The ABI standard would define a
    dispatch table index to each entry point in this category.  The ABI
    library would need to provide a function to the vendor library that
    allowed the vendor to change the dispatch table pointer.

    For category (2), since GetProcAddress is context-independent, the
    API library would need to provide the union of entry points for all
    vendor implementations.  It seems like this could be handled in
    several different ways:

    Option (a): Define the possible list, or at least the indices,
    statically: make the dispatch table for category (2) fixed size,
    and have some sort of centralized registry to manage indices into
    the dispatch table.  Allocation into this table could be handled in
    a way similar to OpenGL enum assignment (see [5]).

        Pros:
            * Easier for vendors to define this dispatch table statically
              at compile time.
        Cons:
            * Need to coordinate for dispatch table index assignment.
            * As more entry points are added, a fixed size would
              eventually be exhausted.
            * Potentially large and sparse dispatch tables would be
              inefficient for memory usage.

    Option (b): At run time, the API library could:
        * Get the list of GetProcAddress-able functions from each
          vendor library.
        * Build the union of GetProcAddress-able functions.
        * Assign dispatch table indices for each function.
        * Tell the vendor libraries what dispatch table index was
          assigned for each of their functions.

        Pros:
            * Flexible to handle an arbitrary number of functions.
        Cons:
            * Vendors have to build their dispatch tables at run time
              to accommodate the dynamically assigned dispatch table indices.
            * Need to query all vendor libraries upfront; this seems a
              little unfortunate, since there potentially could be many
              vendor implementations on the file system, and only a few
              are likely to be used within the context of any one process.

    Option (c): Return entry points for all GetProcAddress'ed strings.  In this
        model, the API library would use logic like this:

        * Does a dispatch function already exist for the string passed
          into GetProcAddress?  If so, return that.
        * Else, online generate a dispatch function for the given string.
          Default the dispatch table to a noop function.
        * At MakeCurrent time, the vendor library would provide all
          the strings/function pointers that it supports and the API
          library would need to plug those vendor functions into the
          online-generated entry points.  I.e., effectively "lazily
          resolve" at MakeCurrent time.

        Pros:
            * Does not require loading vendor libraries before the vendor
              library would be otherwise needed.
        Cons:
            * Some complexity at MakeCurrent time to map the
              GetProcAddress'ed entry points to the vendor functions.
            * This would break apps who determine if a feature is
              available via GetProcAddress (though such apps are broken:
              they are supposed to check the extension string, per [6]).

Example Control Flow

    Scenario 1: Application links against libGLX.so.1 and libOpenGL.so.1:

        * libOpenGL.so.1's entry points default to a dispatch table filled
          with noop functions.
        * The application calls any GLX entry point; libGLX.so.1 queries
          the X server for the vendor name to use with each X screen (a).
        * When the application calls an entry point that should be
          dispatched to the vendor, libGLX.so.1 searches defined search
          paths to find the correct vendor library.
        * libGLX.so.1 loads the vendor library and gets its table of GLX
          dispatch functions.
        * libGLX.so.1 dispatches to the vendor library for appropriate GLX
          entry points (b).
        * The application calls MakeCurrent, which gets dispatched to the
          vendor library.
        * The vendor library's MakeCurrent calls libOpenGL.so.1 to plug
          its dispatch table(s) into TLS (c).
        * The application calls OpenGL entry points in libOpenGL.so.1;
          these dispatch to the vendor library (d).

           ┏━━━━━━━━━━━━━┓
        ┌──┃ application ┃            ┏━━━━━━━━━━━━━━━━━━┓
        │  ┗━━━━━━━━━━━━━┛ ┌───(a)───▶┃ X server         ┃
        │     │            │          ┗━━━━━━━━━━━━━━━━━━┛
        │     ▼            │
        │  ┏━━━━━━━━━━━━━━━━┓         ┏━━━━━━━━━━━━━━━━━━┓
        │  ┃ libGLX.so.1    ┃───(b)──▶┃ libGLX_VENDOR.so ┃──▶ ...
        │  ┗━━━━━━━━━━━━━━━━┛         ┗━━━━━━━━━━━━━━━━━━┛
        │                              |       ▲
        │  ┏━━━━━━━━━━━━━━━━┓◀───(c)───┘       │
        └─▶┃ libOpenGL.so.1 ┃────────(d)───────┘
           ┗━━━━━━━━━━━━━━━━┛


    Scenario 2: Application links against libEGL.so.1 and libOpenGL.so.1:

        * libOpenGL.so.1's entry points default to a dispatch table filled
          with noop functions.
        * The application calls eglInitialize(); the EGL API library uses
          configuration magic to select the appropriate vendor driver.
        * libEGL.so.1 loads the vendor library and gets its table of EGL
          dispatch functions.
        * libEGL.so.1 dispatches to the vendor library for appropriate EGL
          entry points (a).
        * The application calls MakeCurrent, which gets dispatched to
          the vendor library.
        * The vendor library's MakeCurrent calls libOpenGL.so.1 to plug
          its dispatch table(s) into TLS (b).
        * The application calls OpenGL entry points in libOpenGL.so.1;
          these dispatch to the vendor library (c).

           ┏━━━━━━━━━━━━━┓
        ┌──┃ application ┃
        │  ┗━━━━━━━━━━━━━┛
        │     │
        │     ▼
        │  ┏━━━━━━━━━━━━━━━━┓         ┏━━━━━━━━━━━━━━━━━━┓
        │  ┃ libEGL.so.1    ┃───(a)──▶┃ libEGL_VENDOR.so ┃──▶ ...
        │  ┗━━━━━━━━━━━━━━━━┛         ┗━━━━━━━━━━━━━━━━━━┛
        │                              |       ▲
        │  ┏━━━━━━━━━━━━━━━━┓◀───(b)───┘       │
        └─▶┃ libOpenGL.so.1 ┃────────(c)───────┘
           ┗━━━━━━━━━━━━━━━━┛


    Scenario 3: Application links against libGL.so.1

        * This should be the same as the libGLX.so.1 + libOpenGL.so.1
          scenario (Scenario 1), possibly using ELF DT_FILTER [2] to
          cause libGL.so.1's symbols to be resolved by libOpenGL.so.1
          and libGLX.so.1.

           ┏━━━━━━━━━━━━━┓
           ┃ application ┃
           ┗━━━━━━━━━━━━━┛
              │
              ▼
           ┏━━━━━━━━━━━━━┓
        ┌──┃ libGL.so.1  ┃            ┏━━━━━━━━━━━━━━━━━━┓
        │  ┗━━━━━━━━━━━━━┛ ┌───(a)───▶┃ X server         ┃
        │     │            │          ┗━━━━━━━━━━━━━━━━━━┛
        │     ▼            │
        │  ┏━━━━━━━━━━━━━━━━┓         ┏━━━━━━━━━━━━━━━━━━┓
        │  ┃ libGLX.so.1    ┃───(b)──▶┃ libGLX_VENDOR.so ┃──▶ ...
        │  ┗━━━━━━━━━━━━━━━━┛         ┗━━━━━━━━━━━━━━━━━━┛
        │                              |       ▲
        │  ┏━━━━━━━━━━━━━━━━┓◀───(c)───┘       │
        └─▶┃ libOpenGL.so.1 ┃────────(d)───────┘
           ┗━━━━━━━━━━━━━━━━┛

Issues

    (1) Should this document mandate particular filesystem paths for
        any of the libraries?

        As long as the API libraries are in the link-time and load-time
        search paths, leaving API library path up to distributions seems
        acceptable.  But we ought to standardize where vendor libraries
        should get installed (since they might be installed by the vendor,
        rather than the distribution).

    (2) glXGetClientString() is vendor-specific, but does not take a
        screen argument (though it does take a Display pointer).  How should
        it be implemented?

        PROPOSED: The best libGLX.so.1 can do is probably the following:
        * Enumerate all of the X screens on the X server.
        * Query the vendor for each X screen.
        * Get the client string for each vendor.
        * Take the union of client strings across all vendors.

    (3) How should Window System (GLX,EGL) API functions work with
        {glX,egl}GetProcAddress?  GetProcAddress is supposed to return
        context-independent functions.  For client-API functions,
        dispatching can always be done based on the current context,
        but window system layer functions must be dispatched differently
        depending on the arguments they take.  It isn't clear how to
        dispatch a window system layer function without knowledge of
        its parameters.

        It seems like the vendors providing a GetProcAddress-able GLX/EGL
        function are the only ones who would know how to interpret its
        arguments in order to dispatch it.  So, maybe each vendor should
        provide a "dispatch" function for each GLX/EGL extension function
        they provide.  This dispatch function could be responsible
        for interpreting the arguments to select which vendor should
        get called.

    (4) What dispatching model should be used for GetProcAddress-able
        entry points?

        PROPOSED: Option (c) from the Dispatching section: online generate
        entry points for every string passed to GetProcAddress, and map
        to the actual vendor's functions at MakeCurrent time.

    (5) Even in this day and age, some important OpenGL applications still
        use immediate mode OpenGL in very API-heavy ways.  In such cases,
        even just minimal dispatching overhead has a significant impact
        on performance.  How can we mitigate the performance impact in
        such scenarios?

        PROPOSED: Accept the performance penalty.  All vendors on Linux
        will be similarly impacted, so no one should be at a competitive
        disadvantage.  The API libraries should provide mechanisms
        to replace the dispatch table pointer, so vendors can still
        dynamically change their per-thread dispatch table at run time,
        so optimizations built on swapping dispatch tables based on GL
        state are still possible.

    (6) How should libEGL.so select the vendor?

        Mesa's EGL implementation seems like at least a good starting
        point for these heuristics.

    (7) Multiple client API libraries (libOpenGL.so.1, libGLESv2.so.1,
        etc) provide symbols with the same name.  It is conceivable that
        a single process may have multiple libraries loaded (either
        explicitly loaded by an application, or chains of library
        dependencies cause multiple of these libraries to be loaded).
        How should symbol collisions be resolved?

        PROPOSED: In the implementation of the API libraries, the entry
        points should be provided by a common backend library.  In this
        way, all the client API libraries get routed through the same
        set of entry points, so it shouldn't matter which library's
        symbols get selected by the loader.

        Note this scheme likely does not allow one thread to be
        simultaneously current to both EGL+GLESv2 and GLX+OpenGL.

        Alternatively, ELF symbol versioning could be used to distinguish
        between symbols of the same name in each of the client API
        libraries.  See "Maintaining APIs and ABIs" in Ulrich Drepper's
        DSO Howto [7].  I've coded up a demonstration of how that might
        work here: [8].

    (8) How should OpenGL deprecation impact the Linux OpenGL ABI?

        PROPOSED: libOpenGL.so.1 exposes symbols for OpenGL 4.4 and
        the OpenGL ARB_compatibility extension.  Vendors are free to
        implement only earlier versions of OpenGL, and/or not implement
        the ARB_compatibility extension.  However, the vendor library
        will still need to register functions for all of those entry
        points; any unimplemented entry points could be noops.

        Splitting up entry points into different libOpenGLvXY.so.1
        libraries was considered, but this seemed complicated, and at
        odds with the goal of minimizing maintenance burden for the
        API libraries.

    (9) How should server-side GLX be handled with multiple vendors?
        X extensions are registered with server, not screen, scope.
        Thus, there is not a good way for different vendors to provide
        their server-side GLX implementation per-screen.

        EGL, because it does not define any X server extension, may be
        an easier way to allow multiple vendors to execute simultaneously
        on different X screens.

        It seems conceivable that a vendor neutral GLX server module
        could be defined, which would dispatch to vendors' server-side
        GLX implementations with X screen granularity.

        However, that standardization effort is deferred for now: this
        proposal is already large enough.  Plus, with the growing interest
        in EGL, there may not be sufficient motivation to standardize
        server-side GLX multi-vendor support.

        It still seems prudent to design the client-side libGLX.so.1
        API library to allow multiple simultaneous vendors.

    (10) How should any of the vendor selection mechanisms in libEGL.so.1
        or libGLX.so.1 interact with Dave Airlie's Prime work?

    (11) It would be nice to standardize pkg-config files.  What should
        that look like?

        Maybe the standardization there is easy with this proposal,
        because the application-visible libraries would all be
        vendor-neutral, and thus different vendors wouldn't provide
        conflicting pkg-configs.

        Maybe pkg-config should also be the mechanism for telling vendor
        installers where to place vendor libraries (Issue 1)?

    (12) OpenGL header files should be standardized and recommended.

References

    [1] http://www.opengl.org/registry/ABI/
    [2] http://docs.oracle.com/cd/E23824_01/html/819-0690/chapter4-4.html
    [3] http://www.khronos.org/registry/implementers_guide.html
    [4] http://cgit.freedesktop.org/~aplattner/libvdpau/
    [5] http://www.opengl.org/registry/doc/enums.html
    [6] http://www.opengl.org/registry/doc/rules.html#using
    [7] http://www.akkadia.org/drepper/dsohowto.pdf
    [8] http://github.com/aritger/libgl-elf-tricks-demo

Revision History

    #1 September 12, 2012: aritger
        - initial version
    #2 September 14, 2012: aritger
        - add note on pkg-config (krh)
        - add question about whether GLX and EGL can be current to the
          same thread at the same time (rmorell, jajones)
        - add possible solution to Issue 3 (dispatching of GLX/EGL
          GetProcAddress'ed functions)
    #3 April 23, 2013: aritger
        - fix a few typos and grammar issues
        - remove explicit references to 2012; just call this "new"
          instead, since there isn't a firm date when this ABI would be
          finalized and deployed
        - add an issue for standardizing OpenGL header files
        - add diagrams to the scenarios in the Example Control Flow
    #4 September 20, 2013: aritger
        - Expand the libGL.so.1 description, to firm up the backwards 
          compatibility plan.
        - As a strawman, propose that libOpenGL.so.1 will export all 
          OpenGL 4.4 + ARB_compatibility symbols.
        - Comment on Issue (5), performance penalty of dispatching.
        - Expand on Issue (7), symbol collisions between client APIs.
        - Comment on Issue (8), interaction with OpenGL deprecation.