{"id":13721013,"url":"https://github.com/NVIDIA/eglexternalplatform","last_synced_at":"2025-05-07T13:31:17.907Z","repository":{"id":66147191,"uuid":"76882392","full_name":"NVIDIA/eglexternalplatform","owner":"NVIDIA","description":"The EGL External Platform interface","archived":false,"fork":false,"pushed_at":"2024-09-05T12:57:19.000Z","size":19,"stargazers_count":69,"open_issues_count":1,"forks_count":11,"subscribers_count":18,"default_branch":"master","last_synced_at":"2024-11-12T07:50:31.017Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/NVIDIA.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"COPYING","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2016-12-19T17:25:09.000Z","updated_at":"2024-10-11T09:17:16.000Z","dependencies_parsed_at":null,"dependency_job_id":"91eb43fd-3095-4e0c-a719-76376fe7219e","html_url":"https://github.com/NVIDIA/eglexternalplatform","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NVIDIA%2Feglexternalplatform","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NVIDIA%2Feglexternalplatform/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NVIDIA%2Feglexternalplatform/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NVIDIA%2Feglexternalplatform/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/NVIDIA","download_url":"https://codeload.github.com/NVIDIA/eglexternalplatform/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":224604702,"owners_count":17339187,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-03T01:01:11.290Z","updated_at":"2024-11-14T10:30:54.103Z","avatar_url":"https://github.com/NVIDIA.png","language":"C","funding_links":[],"categories":["Wayland Tools","Tools"],"sub_categories":["Interfaces","Mesh networks"],"readme":"EGL External Platform Interface\n===============================\n\nOverview\n--------\n\nThis is a work-in-progress specification of the EGL External Platform interface\nfor writing EGL platforms and their interactions with modern window systems on\ntop of existing low-level EGL platform implementations. This keeps window system\nimplementation specifics out of EGL drivers by using application-facing EGL\nfunctions.\n\nExamples of low-level EGL platforms are `EGL_EXT_platform_device` or\n`EGL_MESA_platform_surfaceless`.\n\n\nInstalling the interface\n------------------------\n\nThis is a headers-only specification of the interface.\n\nA `meson.build` file is included, which will install the header files and\ngenerate a matching pkg-config file.\n\nAlternately, `meson.build` has the necessary `override_dependency` call to work\nas a Meson subproject.\n\nDefinitions\n-----------\n\nThe following terms are used throughout this README file:\n\n * *EGL driver*\n\n   An implementation of the full EGL API, either as a vendor library loaded by\n   GLVND, or as a standalone library linked against by applications.\n\n * *EGL platform*\n\n   A rendering system an EGL driver can support at runtime. An EGL platform may\n   refer to a window system (e.g. X11, Wayland) or a headless rendering platform\n   (e.g. EGLDevice, GBM).\n\n   See section *2.1 \"Native Platforms and Rendering APIs\"* of the EGL 1.5\n   specification, or *EGL_EXT_platform_base* extension.\n\n * *EGL platform library*\n\n   An implementation of a single EGL External Platform interface on top of\n   interfaces provided by an EGL driver.\n\n * *EGL entrypoint layer*\n\n   Thin layer sitting on top of an EGL driver internal implementation that will\n   dispatch calls coming from applications (or GLVND) to either an EGL platform\n   library or the EGL driver itself.\n\n * *EGL External Platform interface*\n\n   Set of functions, hooks, and data structures definitions an EGL entrypoint\n   layer will use to interact with EGL platform libraries.\n\n * *EGL external \u0026 internal object handle*\n\n   An external object handle refers to the EGL object handle given to the\n   application. These may be provided by either an EGL platform library or the\n   EGL driver, depending on what platform the object belongs to.\n\n   In turn, an internal object handle refers to the EGL object handle that only\n   the EGL driver internal implementation understands.\n\n\nInterface walk-through\n----------------------\n\nAll functions and hooks of an EGL platform library are made available either as\nan exports table or dynamically loaded hooks to the EGL entrypoint layer. A\nspecial entry point `loadEGLExternalPlatform()` function must be used to load\nall exports and data of a given EGL platform library.\n\n`loadEGLExternalPlatform()` takes *major* and *minor* numbers corresponding to\nthe version of the EGL External Platform interface the EGL entrypoint layer will\nuse to interact with the loaded platform. This provides a means for both the\ninterface and EGL platform libraries to evolve separately in a backwards\ncompatible way.\n\nDifferent types of functions and hooks are defined and described below. Unless\notherwise specified, the following functions are made available as an exports\ntable to the EGL entrypoint layer:\n\n * *Pure EGL hooks*\n\n   They are intended to be used in replacement of application-facing EGL\n   functions. Pure EGL hooks are not provided as entries of the external exports\n   table, but are retrieved dynamically with the 'getHookAddress()' export. An\n   EGL platform library can provide a hook for most of the application-facing\n   functions the EGL entrypoint layer is aware of.\n\n   Examples of these are, among others, hooks for\n   `eglCreatePlatformWindowSurface()` or `eglSwapBuffers()`.\n\n * *Derivatives of EGL functions*\n\n   These are variations of application-facing EGL functions that may require\n   extra parameters or will have a sligthly different behavior in order to help\n   the EGL entrypoint layer operate in presence of EGL platform libraries.\n\n   An example of these is `queryString()` which is symmetric to\n   `eglQueryString()`, but a new EGLExtPlatformString enum is given for the\n   string name instead. It helps `eglQueryString()` to return the appropriate\n   extension string depending on what EGL platform libraries are available, for\n   instance.\n\n * *External object validation functions*\n\n   The goal of this type of function is to help the EGL entrypoint layer to\n   determine which EGL platform library should handle which calls when opaque\n   native resources are given.\n\n   An example of these functions is `isValidNativeDisplay()`, which helps\n   `eglGetDisplay()`.\n\n * *External -\u003e Internal object translation functions*\n\n   Whenever non-externally implemented EGL functions are called, translation\n   from external (EGL platform library) object handles to internal (EGL driver)\n   ones is required.\n\n   `getInternalHandle()` returns the EGL internal handle of a given external\n   object.\n\n * *Callbacks*\n\n   Sometimes, there might be operations that require execution of\n   non-application-facing code within the EGL platform library. The EGL External\n   Platform interface provides a means for registering callbacks in such cases.\n\n   Unlike the previously described functions, which are implemented by an EGL\n   platform library and made available to the EGL entrypoint layer, these\n   callbacks allow the latter to register EGL driver functions with the former.\n\n   An example of these is the `eglSetError()` callback that allows EGL platform\n   libraries to set EGL error codes to be queried by the application in case of\n   failure.\n\nMore detailed information of every symbol the EGL External Platform interface\ndefines can be found in the `interface/eglexternalplatform.h` file.\n\n\nInteractions with the EGL driver\n--------------------------------\n\nDiscovery and registration of EGL platform libraries is the EGL entrypoint\nlayer's responsibility. What discovery method to use is specific to each\nimplementation, but it is advisable to use something portable and fully\nconfigurable (see JSON-based vendor libraries loader in GLVND).\n\nThe initial interaction of an EGL entrypoint layer with an EGL platform library\nhappens with `loadEGLExternalPlatform()`. This function allows to retrieve both\nthe exports table and data such as the platform enumeration value. It also\nprovides a means for the EGL entrypoint layer to pass in an EGL driver imports\nstructure such that EGL platform libraries can fetch any driver methods they may\nrequire to use.\n\n`loadEGLExternalPlatform()` takes *major* and *minor* numbers corresponding to\nthe version of the EGL External Platform interface the EGL entrypoint layer will\nuse. The EGL platform library must then check those numbers against the\ninterface version it implements, and return the appropriate exports and data\n(or fail if versions are not compatible).\n\nEGL platform libraries may initialize their own private platform data\nstructure at load time to be given to the EGL entrypoint layer. The EGL\nentrypoint layer will in turn pass the structure to all export and hook\nfunctions which take another platform's EGLDisplay, or which do not take an\nEGLDisplay as input (client extensions).\n\nAll EGLDisplay creation operations will be forwarded to the EGL platform library\n`getPlatformDisplay()` export. This gives the EGL entrypoint layer the ability\nto track which EGLDisplay belongs to which platform in order to dispatch\nsubsequent functions.\n\nAll EGLSurface creation operations will also be forwarded to the appropriate EGL\nplatform library hooks. They are required to be externally implemented for\napplications to be able to present buffers onto a surface.\n\nAny other EGL object creation operation can be also hooked, but the internal\nhandle must be always returned.\n\nNote that, by design, all object creation operations must be hooked for objects\nthat are currently required to be externally backed (EGLDisplay and EGLSurface).\n\nSome functions need to be handled by a particular EGL platform library, but\neither do not take an EGLDisplay handle or take an EGLDisplay handle that\nbelongs to a different platform. These functions will require special handling,\nwhich will be defined on a case-by-case basis. For example, `eglGetDisplay()`\nuses the `isValidNativeDisplay()` export in order to determine what EGL platform\nlibrary to use, and then the `getPlatformDisplay()` export to actually create\nthe display.\n\nThe following diagram illustrates the control flow between an application,\nthe EGL driver, and two different EGL platform libraries:\n\n    +-------------------------------+\n    |                               |\n    |         Application           |\n    |                               |\n    +--------------+----------------+\n                   |\n                   |\n    +--------------|----------------+\n    |              |                |       +------------------------+\n    |  EGL driver  |                |       |                        |\n    |              |                |  +----\u003e EGL platform library A +-----+\n    |  +-----------v-------------+  |  |    |                        |     |\n    |  |                         |  |  |    +------------------------+     |\n    |  |  EGL entrypoint layer   +-----+                                   |\n    |  |                         |  |  |    +------------------------+     |\n    |  +-----------+-------------+  |  |    |                        |     |\n    |              |                |  +----\u003e EGL platform library B +--+  |\n    |              |                |       |                        |  |  |\n    |  +-----------v-------------+  |       +------------------------+  |  |\n    |  |                         |  |                                   |  |\n    |  |                         |  |                                   |  |\n    |  |                         \u003c--------------------------------------+  |\n    |  |   EGL driver internal   |  |                                      |\n    |  |                         |  |                                      |\n    |  |                         \u003c-----------------------------------------+\n    |  |                         |  |\n    |  +-------------------------+  |\n    |                               |\n    +-------------------------------+\n\n\nSample code\n-----------\n\nIn order to illustrate how to use the EGL External Platform interface, a few\nfiles with sample code can be found under the 'samples' folder:\n\n * 'samples/sample-egl-server.c':\n\n    Sample code for a display server working on top of the EGLStream family of\n    extensions.\n\n * 'samples/sample-egl-client.c':\n\n    Sample code for an EGL application that would run on Foo window system.\n\n * 'samples/libsample-egl-platform.c':\n\n    Sample code for an EGL External Platform implementation that would add\n    EGL_PLATFORM_SAMPLE support on top of EGLStream family of extensions.\n\nNote that these source files are incomplete, and are not intended to be used\nas-is.\n\nAlso, the NVIDIA Wayland implementation can be found at:\n\nhttps://github.com/NVIDIA/egl-wayland\n\n\nAcknowledgements\n----------------\n\nThanks to James Jones for the original implementation of the Wayland external\nplatform that led to the design of the EGL External Platform infrastructure.\n\n\n### EGL External Platform interface ###\n\nThe EGL External Platform interface itself is licensed as follows:\n\n    Copyright (c) 2016, NVIDIA CORPORATION. All rights reserved.\n\n    Permission is hereby granted, free of charge, to any person obtaining a\n    copy of this software and associated documentation files (the \"Software\"),\n    to deal in the Software without restriction, including without limitation\n    the rights to use, copy, modify, merge, publish, distribute, sublicense,\n    and/or sell copies of the Software, and to permit persons to whom the\n    Software is furnished to do so, subject to the following conditions:\n\n    The above copyright notice and this permission notice shall be included in\n    all copies or substantial portions of the Software.\n\n    THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL\n    THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING\n    FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER\n    DEALINGS IN THE SOFTWARE.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FNVIDIA%2Feglexternalplatform","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FNVIDIA%2Feglexternalplatform","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FNVIDIA%2Feglexternalplatform/lists"}