Mesa EGL

EGL

The current version of EGL in Mesa implements EGL 1.4. More information about EGL can be found at - -http://www.khronos.org/egl/.

+ +https://www.khronos.org/egl/.

The Mesa's implementation of EGL uses a driver architecture. The main library (libEGL) is window system neutral. It provides the EGL @@ -25,16 +33,21 @@ directly dispatched to the drivers.

-
Run configure with the desired client APIs and enable -the driver for your hardware. For example
+
Configure your build with the desired client APIs and enable +the driver for your hardware. For example:
```
-  $ ./configure --enable-gles2 --enable-openvg --enable-gallium-nouveau
+$ meson configure \
+        -D egl=true \
+        -D gles1=true \
+        -D gles2=true \
+        -D dri-drivers=... \
+        -D gallium-drivers=...
 
```
-
The main library and OpenGL is enabled by default. The first option above -enables OpenGL ES 2.x. The second option enables -OpenVG.
+
The main library and OpenGL is enabled by default. The first two options +above enables OpenGL ES 1.x and 2.x. The last two +options enables the listed classic and Gallium drivers respectively.

OpenGL ES 2.x

In the given example, it will build and install libEGL, -libGL, libGLESv1_CM, libGLESv2, -libOpenVG, and one or more EGL drivers.

+libGL, libGLESv1_CM, libGLESv2, and one +or more EGL drivers.

Configure Options

There are several options that control the build of EGL at configuration time

--enable-egl +
+
-D egl=true
+

By default, EGL is enabled. When disabled, the main library and the drivers will not be built.
-
--with-egl-driver-dir - -
The directory EGL drivers should be installed to. If not specified, EGL -drivers will be installed to ${libdir}/egl.
- -
--with-egl-platforms +
-D platforms=...
+

List the platforms (window systems) to support. Its argument is a comma -seprated string such as --with-egl-platforms=x11,drm. It decides +separated string such as -D platforms=x11,drm. It decides the platforms a driver may support. The first listed platform is also used by -the main library to decide the native platform: the platform the EGL native -types such as EGLNativeDisplayType or -EGLNativeWindowType defined for.
+the main library to decide the native platform.

The available platforms are x11, drm, -fbdev, and gdi. The gdi platform can -only be built with SCons. Unless for special needs, the build system should +wayland, surfaceless, android, +and haiku. +The android platform can either be built as a system +component, part of AOSP, using Android.mk files, or +cross-compiled using appropriate options. +Unless for special needs, the build system should select the right platforms automatically.
-
--enable-gles1 and --enable-gles2 +
-D gles1=true and -D gles2=true
+

These options enable OpenGL ES support in OpenGL. The result is one big internal library that supports multiple APIs.
-
--enable-gles-overlay - -
This option enables OpenGL ES as separate internal libraries. This is an -alternative approach to enable OpenGL ES.
- -
This is only supported by egl_gallium. For systems using DRI -drivers, --enable-gles1 and --enable-gles2 are -suggested instead as all drivers will benefit.
+ -
--enable-openvg +
-D shared-glapi=true
+
-
OpenVG must be explicitly enabled by this option.
- -

By default, libGL has its own copy of libglapi. +This options makes libGL use the shared libglapi. This +is required if applications mix OpenGL and OpenGL ES.

--enable-gallium-egl - -
Explicitly enable or disable egl_gallium.
- -

Use EGL

@@ -125,69 +122,37 @@ mesa/demos repository.

There are several environment variables that control the behavior of EGL at runtime

EGL_DRIVERS_PATH - -
By default, the main library will look for drivers in the directory where -the drivers are installed to. This variable specifies a list of -colon-separated directories where the main library will look for drivers, in -addition to the default directory. This variable is ignored for setuid/setgid -binaries.
- -
This variable is usually set to test an uninstalled build. For example, one -may set
- -
```
-  $ export LD_LIBRARY_PATH=$mesa/lib
-  $ export EGL_DRIVERS_PATH=$mesa/lib/egl
-
```
- -
to test a build without installation
- -
EGL_DRIVER - -
This variable specifies a full path to an EGL driver and it forces the -specified EGL driver to be loaded. It comes in handy when one wants to test a -specific driver. This variable is ignored for setuid/setgid binaries.
- -
EGL_PLATFORM +
+
EGL_PLATFORM
+

This variable specifies the native platform. The valid values are the same -as those for --with-egl-platforms. When the variable is not set, +as those for -D platforms=.... When the variable is not set, the main library uses the first platform listed in ---with-egl-platforms as the native platform.
+-D platforms=... as the native platform.

Extensions like EGL_MESA_drm_display define new functions to create displays for non-native platforms. These extensions are usually used by applications that support non-native platforms. Setting this variable is probably required only for some of the demos found in mesa/demo repository.
-
EGL_LOG_LEVEL +
EGL_LOG_LEVEL
+

This changes the log level of the main library and the drivers. The valid values are: debug, info, warning, and fatal.
-
EGL_SOFTWARE - -
For drivers that support both hardware and software rendering, setting this -variable to true forces the use of software rendering.
- -

+ +

EGL Drivers

egl_dri2 +
+
egl_dri2
+

This driver supports both x11 and drm platforms. It functions as a DRI driver loader. For x11 support, it talks to @@ -195,53 +160,18 @@ the X server directly using (XCB-)DRI2 protocol.

This driver can share DRI drivers with libGL.
-
egl_gallium - -
This driver is based on Gallium3D. It supports all rendering APIs and -hardwares supported by Gallium3D. It is the only driver that supports OpenVG. -The supported platforms are X11, DRM, FBDEV, and GDI.
- -
This driver comes with its own hardware drivers -(pipe_<hw>) and client API modules -(st_<api>).
- -
egl_glx - -
This driver provides a wrapper to GLX. It uses exclusively GLX to implement -the EGL API. It supports both direct and indirect rendering when the GLX does. -It is accelerated when the GLX is. As such, it cannot provide functions that -is not available in GLX or GLX extensions.
-

+ +

Packaging

The ABI between the main library and its drivers are not stable. Nor is -there a plan to stabilize it at the moment. Of the EGL drivers, -egl_gallium has its own hardware drivers and client API modules. -They are considered internal to egl_gallium and there is also no -stable ABI between them. These should be kept in mind when packaging for -distribution.

- -

Generally, egl_dri2 is preferred over egl_gallium -when the system already has DRI drivers. As egl_gallium is loaded -before egl_dri2 when both are available, egl_gallium -may either be disabled with --disable-gallium-egl or packaged -separately.

+there a plan to stabilize it at the moment.

Developers

The sources of the main library and the classic drivers can be found at -src/egl/. The sources of the egl state tracker can -be found at src/gallium/state_trackers/egl/.

- -

The suggested way to learn to write a EGL driver is to see how other drivers -are written. egl_glx should be a good reference. It works in any -environment that has GLX support, and it is simpler than most drivers.

The sources of the main library and drivers can be found at +src/egl/.

Lifetime of Display Resources

@@ -250,8 +180,8 @@ longer than the display that creates them.

In EGL, when a display is terminated through eglTerminate, all display resources should be destroyed. Similarly, when a thread is released -throught eglReleaseThread, all current display resources should be -released. Another way to destory or release resources is through functions +through eglReleaseThread, all current display resources should be +released. Another way to destroy or release resources is through functions such as eglDestroySurface or eglMakeCurrent.

When a resource that is current to some thread is destroyed, the resource @@ -317,17 +247,6 @@ not be called with the sample display at the same time. If a driver has access to an EGLDisplay without going through the EGL APIs, the driver should as well lock the display before using it. -

TODOs

- -

Pass the conformance tests
Mixed use of OpenGL, OpenGL ES 1.1, and OpenGL ES 2.0 is supported. But -which one of libGL.so, libGLESv1_CM.so, and -libGLESv2.so should an application link to? Bad things may happen -when, say, an application is linked to libGLESv2.so and -libcairo, which is linked to libGL.so instead.

- +