From 807c6931fe683fd844ceec1b023232181e6aae03 Mon Sep 17 00:00:00 2001 From: marha Date: Tue, 28 Dec 2010 16:10:20 +0000 Subject: xserver and mesa git update 28-12-2010 --- mesalib/docs/egl.html | 631 ++++++++++++++++++++++++++------------------------ 1 file changed, 323 insertions(+), 308 deletions(-) (limited to 'mesalib/docs/egl.html') diff --git a/mesalib/docs/egl.html b/mesalib/docs/egl.html index d38f2dd7b..28ade1567 100644 --- a/mesalib/docs/egl.html +++ b/mesalib/docs/egl.html @@ -1,308 +1,323 @@ - - -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 --enable-gles-overlay --with-state-trackers=egl,vega --enable-gallium-intel
-
    - -

    The main library and OpenGL is enabled by default. The first option enables -OpenGL ES 1.x and 2.x. The egl state -tracker is needed by a number of EGL drivers. EGL drivers will be covered -later. 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, -libGL, 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

- - - -

Use EGL

- -

Demos

- -

There are demos for the client APIs supported by EGL. They can be found in -mesa/demos repository.

- -

Environment Variables

- -

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

- - - -

EGL Drivers

- - - -

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

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

+ +

Build EGL

+ +
    +
  1. +

    Run configure with the desired client APIs and enable +the driver for your hardware. For example

    + +
    +  $ ./configure --enable-gles2 --enable-openvg --enable-gallium-nouveau
+
    + +

    The main library and OpenGL is enabled by default. The first option above +enables OpenGL ES 2.x. The second option enables +OpenVG.

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

In the given example, it will build and install libEGL, +libGL, 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

+ + + +

Use EGL

+ +

Demos

+ +

There are demos for the client APIs supported by EGL. They can be found in +mesa/demos repository.

+ +

Environment Variables

+ +

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

+ + + +

EGL Drivers

+ + + +

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.

+ +

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