Mesa (master): st/egl_g3d: Improve comments to the native display interface .

[Chia-I Wu]

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

Author: Chia-I Wu <olvaffe at gmail.com>
Date:   Tue Jan 12 14:01:56 2010 +0800

st/egl_g3d: Improve comments to the native display interface.

Document the future of __GLcontextModes.  Improve the description of
surface validation and native_flush_frontbuffer.

---

 src/gallium/state_trackers/egl_g3d/common/native.h |   14 ++++++++++++--
 1 files changed, 12 insertions(+), 2 deletions(-)

diff --git a/src/gallium/state_trackers/egl_g3d/common/native.h b/src/gallium/state_trackers/egl_g3d/common/native.h
index 88d87c6..5ddcf67 100644
--- a/src/gallium/state_trackers/egl_g3d/common/native.h
+++ b/src/gallium/state_trackers/egl_g3d/common/native.h
@@ -64,8 +64,13 @@ struct native_surface {
    boolean (*flush_frontbuffer)(struct native_surface *nsurf);
 
    /**
-    * Validate the buffers of the surface.  Those not listed in the attachments
-    * will be destroyed.  The returned textures are owned by the caller.
+    * Validate the buffers of the surface.  The returned textures are owned by
+    * the caller.  It is possible that this function is called with textures,
+    * width, or height being NULL.
+    *
+    * If this function is called multiple times with different attachments,
+    * those not listed in the latest call might be destroyed.  This behavior
+    * might change in the future.
     */
    boolean (*validate)(struct native_surface *nsurf,
                        const enum native_attachment *natts,
@@ -80,6 +85,7 @@ struct native_surface {
 };
 
 struct native_config {
+   /* __GLcontextModes should go away some day */
    __GLcontextModes mode;
    enum pipe_format color_format;
    enum pipe_format depth_format;
@@ -197,6 +203,10 @@ struct native_display_modeset {
                       const struct native_mode *nmode);
 };
 
+/**
+ * This function is called when the native display wants to display the front
+ * buffer of the draw surface of the given context.
+ */
 typedef void (*native_flush_frontbuffer)(void *dummy,
                                          struct pipe_surface *surf,
                                          void *context_private);