From ada46053a4b37967cc53355b9baf712aa5a8bafd Mon Sep 17 00:00:00 2001 From: Chia-I Wu Date: Thu, 21 Jan 2010 15:29:14 +0800 Subject: [PATCH] docs: Add documentation for EGL. This is a short guide to EGL. The drivers that are to be removed soon are not mentioned in the guide. --- docs/egl.html | 224 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 224 insertions(+) create mode 100644 docs/egl.html diff --git a/docs/egl.html b/docs/egl.html new file mode 100644 index 00000000000..ccc233fca98 --- /dev/null +++ b/docs/egl.html @@ -0,0 +1,224 @@ + + +Mesa EGL + + + + + +

Mesa 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/.

+ +

The Mesa's implementation of EGL uses a driver architecture. The main +library (libEGL) is window system neutral. It provides the EGL +API entry points and helper functions for use by the drivers. Drivers are +dynamically loaded by the main library and most of the EGL API calls are +directly dispatched to the drivers.

+ +

The driver in use decides the window system to support. For drivers that +support hardware rendering, there are usually multiple drivers supporting the +same window system. Each one of of them supports a certain range of graphics +cards.

+ +

Build EGL

+ +

+
Run configure with the desired state trackers and and enable +the Gallium driver for your hardware. For example
+ +
```
+  $ ./configure --with-state-trackers=egl_g3d,es,vega --enable-gallium-intel
+
```
+ +
The main library will be enabled by default. The egl_g3d state +tracker is needed by a number of EGL drivers. EGL drivers will be covered +later. The es state tracker provides OpenGL ES 1.x +and 2.x and the vega state tracker provides OpenVG +1.x.
+
Build and install Mesa as usual.

+ +

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

+ +

Configure Options

+ +

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

+ +

--enable-egl + +
By default, EGL is enabled. When disabled, the main library and the drivers +will not be built.
+ +
--with-egl-displays + +
List the window system(s) to support. It is by default x11, +which supports the X Window System. Its argument is a comma separated string +like, for example, --with-egl-displays=x11,kms. Because an EGL +driver decides which window system to support, this example will enable two +(sets of) EGL drivers. One supports the X window system and the other supports +bare KMS (kernel modesetting).
+ +
--with-state-trackers + +
The argument is a comma separated string. It is usually used to specify the +rendering APIs, like OpenGL ES or OpenVG, to build. But it should be noted +that a number of EGL drivers depend on the egl_g3d state tracker. +They will not be built without the egl_g3d state +tracker.
+ +

+ +

OpenGL

+ +

The OpenGL state tracker is not built in the above example. It should be +noted that the classic libGL is not a state tracker and cannot be +used with EGL (unless the EGL driver in use is egl_glx). To build +the OpenGL state tracker, one may append glx to +--with-state-trackers and manually build +src/gallium/winsys/xlib/.

+ +

Use EGL

+ +

The demos for OpenGL ES and OpenVG can be found in progs/es1/, +progs/es2/ and progs/openvg/. You can use them to +test your build. For example,

+ +

+  $ cd progs/es1/xegl
+  $ make
+  $ ./torus
+

+ +

Environment Variables

+ +

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

+ +

EGL_DRIVER + +
This variable forces the specified EGL driver to be loaded. It comes in +handy when one wants to test a specific driver.
+ +
EGL_DISPLAY + +
When EGL_DRIVER is not set, the main library loads all +EGL drivers that support a certain window system. EGL_DISPLAY can +be used to specify the window system and the valid values are, for example, +x11 or kms. When the variable is not set, the main +library defaults the value to the first window system listed in +--with-egl-displays at configuration time. + +
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

+ +

There are two categories of EGL drivers: Gallium and classic.

+ +

Gallium EGL drivers supports all rendering APIs specified in EGL 1.4. The +support for optional EGL functions and EGL extensions is usually more complete +than the classic ones. These drivers depend on the egl_g3d state +tracker to build. The available drivers are

+ +

egl_<dpy>_i915
egl_<dpy>_i965
egl_<dpy>_radeon
egl_<dpy>_nouveau
egl_<dpy>_vmwgfx

+ +

<dpy> is given by --with-egl-displays at +configuration time. There will be one EGL driver for each combination of the +displays listed and the hardware drivers enabled.

+ +

Classic EGL drivers, on the other hand, supports only OpenGL as its +rendering API. They can be found under src/egl/drivers/. There +are 3 of them

+ +

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.
+
egl_xdri + +
This driver supports the X Window System as its window system. It functions +as a DRI driver loader. Unlike egl_glx, it has no dependency on +libGL. It talks to the X server directly using DRI or DRI2 +protocols. It also talks minimal GLX protocol for things like available +visuals or fbconfigs. With direct access to the DRI drivers, it has the +potential to support more EGL functions that are not possible with +egl_glx
+ +
egl_dri + +
This driver lacks maintenance and does not build. It is similiar +to egl_xdri in that it functions as a DRI driver loader. But +unlike egl_xdri, it supports Linux framebuffer devices as its +window system and supports EGL_MESA_screen_surface extension. It loads only +DRI1 drivers. As DRI1 drivers is phasing out, it might be better to rewrite +the driver to support KMS and DRI2.
+ +

+ +

To use the classic drivers, one must manually set EGL_DRIVER at +runtime.

+ +

Developers

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

TODOs

+ +

Thread safety
Pass the conformance tests
Better automatic driver selection: EGL_DISPLAY loads all +drivers and might eat too much memory.

+ + + -- 2.30.2