From 14cbf324dc57f8caa4a61dff5146b43cfc42c834 Mon Sep 17 00:00:00 2001 From: Chia-I Wu Date: Wed, 27 Jan 2010 23:18:22 +0800 Subject: docs: Update the developer section of egl.html. Mainly to add a subsection on the lifetime of display resources. --- docs/egl.html | 38 ++++++++++++++++++++++++++++++++++++-- 1 file changed, 36 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/egl.html b/docs/egl.html index 305e5f6eab..57b1d1488a 100644 --- a/docs/egl.html +++ b/docs/egl.html @@ -223,9 +223,43 @@ runtime.

Developers

-The sources of the main library and the classic drivers can be found at +

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

TODOs

-- cgit v1.2.3