Mesa (master): docs: Update the developer section of egl.html.

[Chia-I Wu]

Module: Mesa
Branch: master
Commit: 14cbf324dc57f8caa4a61dff5146b43cfc42c834
URL:    http://cgit.freedesktop.org/mesa/mesa/commit/?id=14cbf324dc57f8caa4a61dff5146b43cfc42c834

Author: Chia-I Wu <olvaffe at gmail.com>
Date:   Wed Jan 27 23:18:22 2010 +0800

docs: Update the developer section of egl.html.

Mainly to add a subsection on the lifetime of display resources.

---

 docs/egl.html |   38 ++++++++++++++++++++++++++++++++++++--
 1 files changed, 36 insertions(+), 2 deletions(-)

diff --git a/docs/egl.html b/docs/egl.html
index 305e5f6..57b1d14 100644
--- a/docs/egl.html
+++ b/docs/egl.html
@@ -223,9 +223,43 @@ runtime.</p>
 
 <h2>Developers</h2>
 
-The sources of the main library and the classic drivers can be found at
+<p>The sources of the main library and the classic drivers can be found at
 <code>src/egl/</code>.  The sources of the <code>egl</code> state tracker can
-be found at <code>src/gallium/state_trackers/egl/</code>.
+be found at <code>src/gallium/state_trackers/egl/</code>.</p>
+
+<p>The suggested way to learn to write a EGL driver is to see how other drivers
+are written.  <code>egl_glx</code> should be a good reference.  It works in any
+environment that has GLX support, and it is simpler than most drivers.</p>
+
+<h3>Lifetime of Display Resources</h3>
+
+<p>Contexts and surfaces are examples of display resources.  They might live
+longer than the display that creates them.</p>
+
+<p>In EGL, when a display is terminated through <code>eglTerminate</code>, all
+display resources should be destroyed.  Similarly, when a thread is released
+throught <code>eglReleaseThread</code>, all current display resources should be
+released.  Another way to destory or release resources is through functions
+such as <code>eglDestroySurface</code> or <code>eglMakeCurrent</code>.</p>
+
+<p>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
+<code>eglIs<Resource>Bound</code> 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.</p>
+
+<p>The main library will mark destroyed current resources as unlinked.  In a
+driver's <code>MakeCurrent</code> callback,
+<code>eglIs<Resource>Linked</code> 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 <code>MakeCurrent</code> might be called with an
+uninitialized display.</p>
+
+<p>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.</p>
 
 <h3>TODOs</h3>