Add a README file

Documenting how to set LD_LIBRARY_PATH, GLAZE_WRAPPER, and GLAZE_LIBGL
for invoking Glaze. Also giving credit to Alexander Monakov for
teaching me how to ue ifuncs.

diff --git a/README b/README
new file mode 100644 (file)
index 0000000..485d4da
--- /dev/null
+++ b/README
@@ -0,0 +1,56 @@
+Glaze: A thin, flexible layer for wrapping OpenGL
+
+Glaze is a very thin layer intended to assist developers of
+OpenGL-wrapping libraries. The result of compiling Glaze is a tiny
+libGL.so library with a symbol for every possible GL and GLX function
+in the OpenGL API.
+
+Each symbol within the Glaze library is merely an "ifunc resolver"[*]
+which will resolve to a function in the wrapper library if one exists,
+or will otherwise resolve to a function in the underlying "real"
+OpenGL library.
+
+In order to use glaze, the following three environment variables
+should be set:
+
+    LD_LIBRARY_PATH
+
+       This should be set so that the directory containing Glaze's
+       libGL.so appears on the list earlier than any other OpenGL
+       library implementation. For example:
+
+           LD_LIBRARY_PATH=/home/user/src/glaze/lib64:${LD_LIBRARY_PATH}
+
+    GLAZE_WRAPPER
+
+       This should be set to the complete path to the library
+       containing some OpenGL wrapper functions. These functions must
+       manually call into the underlying OpenGL functions as
+       needed. An example of setting this variable is:
+
+           GLAZE_WRAPPER=/home/user/src/mywrapper/libGL.so
+
+    GLAZE_LIBGL
+
+       This should be set to the complete path to the "real",
+       underlying OpengL library implementation. For example:
+
+           GLAZE_LIBGL=/usr/lib/libGL.so
+
+For any questions or comments about Glaze, please feel free to email
+me:
+
+       Carl Worth <cworth@cworth.org>
+
+Credits: Many thanks to Alexander Monakov who gave me the idea for
+using "ifunc resolvers" for efficient wrapping of OpenGL functions,
+(and for patiently teaching me how they work). See Alexander's
+project, Primus, for the inspiration for Glaze:
+https://github.com/amonakov/primus
+
+[*] An "ifunc resolver" is a glibc mechanism for performing efficent,
+one-shot function resolutions. The first call to the function will
+invoke the resolver which has the job of returning the "real" function
+to call. At that point, the application PLTs will be updated with the
+returned function pointer so that all future calls will call the
+desired function without any subsequent overhead.
\ No newline at end of file