X-Git-Url: https://git.cworth.org/git?p=glaze;a=blobdiff_plain;f=glaze.h;h=198ec5b797b4ff9cf8167b625d1c529628de5ef6;hp=9a9115a3a516e33189f737f82f5f2fe1998cd62f;hb=HEAD;hpb=cec0694a7f219bd3590e6a04beba34ca45539540

diff --git a/glaze.h b/glaze.h
index 9a9115a..198ec5b 100644
--- a/glaze.h
+++ b/glaze.h
@@ -55,4 +55,74 @@ glaze_lookup (char *function);
 	(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);
+
+/* Register a callback function to be called when the first GL
+ * function, (not glX function) is called.
+ *
+ * It's common for Glaze-using libraries to need to do some
+ * initialization that can only be done once a valid OpenGL context is
+ * initialized. For example, the library may need to query what kind
+ * of context has been created.
+ *
+ * This function can be used for this purpose. It arranges for a
+ * function in the wrapper library to be called immediately before the
+ * first call to an OpenGL function by the application. Note that any
+ * window-system-sepecific function calls (such as glX functions) are
+ * not considered "an OpenGL function" for this purpose.
+ *
+ * The 'function_name' argument here should be the name of an exported
+ * function in the wrapper library passed to glaze_exectute, (or
+ * specified in the GLAZE_WRAPPER variable). The function must have a
+ * return type of void and must accept no arguments, so should have a
+ * signature such as:
+ *
+ *	void function (void);
+ */
+void
+glaze_set_first_gl_call_callback (const char *function_name);
+
 #endif /* GLAZE_H */