(ret) = real_ ## function(__VA_ARGS__); \
} while (0);
+/* Execute a program (as specified with 'argc' and 'argv') with a
+ * wrapper library providing some substitute OpenGL functions.
+ *
+ * Here, 'wrapper' should be a loadable library providing one or more
+ * symbols in the OpenGL API. Glaze will arrange for those substitute
+ * functions to be called instead of the functions in the underlying
+ * OpenGL library. The functions may want to defer to the underlying
+ * OpenGL functions, which they can do by using the GLAZE_DEFER macro
+ * or by using glaze_lookup to obtain a function pointer to the
+ * underlying function.
+ *
+ * If 'wrapper' is not an absolute path, glaze_execute will attempt to
+ * find the library by searching in the following locations in order:
+ *
+ * 1. The same directory of the current executable, (as determined
+ * by /proc/self/exe).
+ *
+ * 2. All directories as searched by dlopen, (such as
+ * LD_LIBRARY_PATH, /etc/ld.so.cache, etc.)
+ *
+ * The behavior of glaze_execute can be influenced by the following
+ * environement variable:
+ *
+ * GLAZE_LIBGL Specifies the complete path to the library
+ * providing the underlying OpenGL implementation
+ * (libGL.so.1).
+ *
+ * In most cases, setting this variable is not
+ * necessary. If thisvariable is not set,
+ * glaze_execute will attempt to automatically find
+ * the correct libGL.so.1. It does this by executing
+ * a test program which loads libGL.so.1 and prints
+ * which file gets loaded. This guess may be
+ * incorrect if the program being executed by
+ * glaze_execute is actually a script which alters
+ * the LD_LIBRARY_PATH and causes a different
+ * libGL.so.1 to be loaded.
+ *
+ * If you are executing such a program, you can
+ * manually determine the correct libGL.so.1 and
+ * specifies its absolute path in this variable.
+ */
+void
+glaze_execute (int argc, char *argv[], const char *wrapper);
+
#endif /* GLAZE_H */