Mesa (master): mesa/main: Add comments to mfeatures.h.

[Brian Paul]

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

Author: Chia-I Wu <olvaffe at gmail.com>
Date:   Mon Sep  7 17:51:33 2009 +0800

mesa/main: Add comments to mfeatures.h.

The comments document the conventions that a feature may follow.

---

 src/mesa/main/mfeatures.h |   32 ++++++++++++++++++++++++++++++++
 1 files changed, 32 insertions(+), 0 deletions(-)

diff --git a/src/mesa/main/mfeatures.h b/src/mesa/main/mfeatures.h
index e23cdb1..6318934 100644
--- a/src/mesa/main/mfeatures.h
+++ b/src/mesa/main/mfeatures.h
@@ -36,6 +36,38 @@
 #define _HAVE_FULL_GL 1
 #endif
 
+/* assert that a feature is disabled and should never be used */
+#define ASSERT_NO_FEATURE() ASSERT(0)
+
+/**
+ * A feature can be anything.  But most of them share certain characteristics.
+ *
+ * When a feature defines driver entries, they can be initialized by
+ *   _MESA_INIT_<FEATURE>_FUNCTIONS
+ *
+ * When a feature defines vtxfmt entries, they can be initialized and
+ * installed by
+ *   _MESA_INIT_<FEATURE>_VTXFMT
+ *   _mesa_install_<feature>_vtxfmt
+ *
+ * When a feature defines dispatch entries, they are initialized by
+ *   _mesa_init_<feature>_dispatch
+ *
+ * When a feature has states, they are initialized and freed by
+ *   _mesa_init_<feature>
+ *   _mesa_free_<feature>_data
+ *
+ * Except for states, the others compile to no-op when a feature is disabled.
+ *
+ * The GLAPIENTRYs and helper functions defined by a feature should also
+ * compile to no-op when it is disabled.  But to save typings and to catch
+ * bugs, some of them may be unavailable, or compile to ASSERT_NO_FEATURE()
+ * when the feature is disabled.
+ *
+ * A feature following the conventions may be used without knowing if it is
+ * enabled or not.
+ */
+
 #define FEATURE_accum  _HAVE_FULL_GL
 #define FEATURE_attrib_stack  _HAVE_FULL_GL
 #define FEATURE_colortable  _HAVE_FULL_GL