1 /* Copyright © 2013, Intel Corporation
3 * Permission is hereby granted, free of charge, to any person obtaining a copy
4 * of this software and associated documentation files (the "Software"), to deal
5 * in the Software without restriction, including without limitation the rights
6 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
7 * copies of the Software, and to permit persons to whom the Software is
8 * furnished to do so, subject to the following conditions:
10 * The above copyright notice and this permission notice shall be included in
11 * all copies or substantial portions of the Software.
13 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
14 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
15 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
16 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
17 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
18 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
25 /* Perform dynamic lookup of 'function' within the library specified
26 * by the GLAZE_LIBGL environment variable.
29 glaze_lookup (char *function);
31 /* A helper macro for glaze-using wrappers to defer an operation to
32 * the "real" underlying OpenGL function.
34 * The underlying function to be called will be obtained by calling
35 * glaze_lookup. This lookup will be cached in a local variable
36 * (defined by this macro) named real_<function>.
38 * NOTE: This macro can only be used a single time within any
39 * function, (due to the locally-defined variable). If this is
40 * inadequate, callers can instead call glaze_lookup manually.
42 #define GLAZE_DEFER(function,...) do { \
43 static typeof(&function) real_ ## function; \
44 if (! real_ ## function) \
45 real_ ## function = glaze_lookup (#function); \
46 real_ ## function(__VA_ARGS__); \
49 /* As GLAZE_DEFER, but also set 'ret' to the value returned by the
50 * underlying "real" function. */
51 #define GLAZE_DEFER_WITH_RETURN(ret, function,...) do { \
52 static typeof(&function) real_ ## function; \
53 if (! real_ ## function) \
54 real_ ## function = glaze_lookup (#function); \
55 (ret) = real_ ## function(__VA_ARGS__); \
58 /* Execute a program (as specified with 'argc' and 'argv') with a
59 * wrapper library providing some substitute OpenGL functions.
61 * Here, 'wrapper' should be a loadable library providing one or more
62 * symbols in the OpenGL API. Glaze will arrange for those substitute
63 * functions to be called instead of the functions in the underlying
64 * OpenGL library. The functions may want to defer to the underlying
65 * OpenGL functions, which they can do by using the GLAZE_DEFER macro
66 * or by using glaze_lookup to obtain a function pointer to the
67 * underlying function.
69 * If 'wrapper' is not an absolute path, glaze_execute will attempt to
70 * find the library by searching in the following locations in order:
72 * 1. The same directory of the current executable, (as determined
75 * 2. All directories as searched by dlopen, (such as
76 * LD_LIBRARY_PATH, /etc/ld.so.cache, etc.)
78 * The behavior of glaze_execute can be influenced by the following
79 * environement variable:
81 * GLAZE_LIBGL Specifies the complete path to the library
82 * providing the underlying OpenGL implementation
85 * In most cases, setting this variable is not
86 * necessary. If thisvariable is not set,
87 * glaze_execute will attempt to automatically find
88 * the correct libGL.so.1. It does this by executing
89 * a test program which loads libGL.so.1 and prints
90 * which file gets loaded. This guess may be
91 * incorrect if the program being executed by
92 * glaze_execute is actually a script which alters
93 * the LD_LIBRARY_PATH and causes a different
94 * libGL.so.1 to be loaded.
96 * If you are executing such a program, you can
97 * manually determine the correct libGL.so.1 and
98 * specifies its absolute path in this variable.
101 glaze_execute (int argc, char *argv[], const char *wrapper);
103 /* Register a callback function to be called when the first GL
104 * function, (not glX function) is called.
106 * It's common for Glaze-using libraries to need to do some
107 * initialization that can only be done once a valid OpenGL context is
108 * initialized. For example, the library may need to query what kind
109 * of context has been created.
111 * This function can be used for this purpose. It arranges for a
112 * function in the wrapper library to be called immediately before the
113 * first call to an OpenGL function by the application. Note that any
114 * window-system-sepecific function calls (such as glX functions) are
115 * not considered "an OpenGL function" for this purpose.
117 * The 'function_name' argument here should be the name of an exported
118 * function in the wrapper library passed to glaze_exectute, (or
119 * specified in the GLAZE_WRAPPER variable). The function must have a
120 * return type of void and must accept no arguments, so should have a
123 * void function (void);
126 glaze_set_first_gl_call_callback (const char *function_name);