From 29b86f9852b2b7ecc31cdfee56679537e40bc6e2 Mon Sep 17 00:00:00 2001 From: marha Date: Mon, 12 Apr 2010 09:53:17 +0000 Subject: svn merge -r524:HEAD "^/branches/released" . --- mesalib/docs/egl.html | 324 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 324 insertions(+) create mode 100644 mesalib/docs/egl.html (limited to 'mesalib/docs/egl.html') diff --git a/mesalib/docs/egl.html b/mesalib/docs/egl.html new file mode 100644 index 000000000..55907f6cf --- /dev/null +++ b/mesalib/docs/egl.html @@ -0,0 +1,324 @@ + + +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

+ +
    +
  1. +

    Run configure with the desired state trackers and enable +the Gallium driver for your hardware. For example

    + +
    +  $ ./configure --with-state-trackers=egl,es,vega --enable-gallium-{swrast,intel}
+
    + +

    The main library will be enabled by default. The egl 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.

    +
    2. + +
  2. Build and install Mesa as usual.
    3. +
+ +

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

+ + + +

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 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 state +tracker to build. The available drivers are

+ + + +

<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

+ + + +

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

+ +

Lifetime of Display Resources

+ +

Contexts and surfaces are examples of display resources. They might live +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 +such as eglDestroySurface or eglMakeCurrent.

+ +

When a resource that is current to some thread is destroyed, the resource +should not be destroyed immediately. EGL requires the resource to live until +it is no longer current. A driver usually calls +eglIs<Resource>Bound to check if a resource is bound +(current) to any thread in the destroy callbacks. If it is still bound, the +resource is not destroyed.

+ +

The main library will mark destroyed current resources as unlinked. In a +driver's MakeCurrent callback, +eglIs<Resource>Linked can then be called to check if a newly +released resource is linked to a display. If it is not, the last reference to +the resource is removed and the driver should destroy the resource. But it +should be careful here because MakeCurrent might be called with an +uninitialized display.

+ +

This is the only mechanism provided by the main library to help manage the +resources. The drivers are responsible to the correct behavior as defined by +EGL.

+ +

EGL_RENDER_BUFFER

+ +

In EGL, the color buffer a context should try to render to is decided by the +binding surface. It should try to render to the front buffer if the binding +surface has EGL_RENDER_BUFFER set to +EGL_SINGLE_BUFFER; If the same context is later bound to a +surface with EGL_RENDER_BUFFER set to +EGL_BACK_BUFFER, the context should try to render to the back +buffer. However, the context is allowed to make the final decision as to which +color buffer it wants to or is able to render to.

+ +

For pbuffer surfaces, the render buffer is always +EGL_BACK_BUFFER. And for pixmap surfaces, the render buffer is +always EGL_SINGLE_BUFFER. Unlike window surfaces, EGL spec +requires their EGL_RENDER_BUFFER values to be honored. As a +result, a driver should never set EGL_PIXMAP_BIT or +EGL_PBUFFER_BIT bits of a config if the contexts created with the +config won't be able to honor the EGL_RENDER_BUFFER of pixmap or +pbuffer surfaces.

+ +

It should also be noted that pixmap and pbuffer surfaces are assumed to be +single-buffered, in that eglSwapBuffers has no effect on them. It +is desirable that a driver allocates a private color buffer for each pbuffer +surface created. If the window system the driver supports has native pbuffers, +or if the native pixmaps have more than one color buffers, the driver should +carefully attach the native color buffers to the EGL surfaces, re-route them if +required.

+ +

There is no defined behavior as to, for example, how +glDrawBuffer interacts with EGL_RENDER_BUFFER. Right +now, it is desired that the draw buffer in a client API be fixed for pixmap and +pbuffer surfaces. Therefore, the driver is responsible to guarantee that the +client API renders to the specified render buffer for pixmap and pbuffer +surfaces.

+ +

EGLDisplay Mutex

+ +The EGLDisplay will be locked before calling any of the dispatch +functions (well, except for GetProcAddress which does not take an +EGLDisplay). This guarantees that the same dispatch function will +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

+ + + + + -- cgit v1.2.3