1 2 3 4Introduction 5------------ 6 7This document describes the implementation of the XFree86 4.0 libGL.so 8library defined by the Linux/OpenGL Base specification found at 9http://reality.sgi.com/opengl/linux/linuxbase.html. 10 11The documentation is divided into two sections: 12 User's Guide 13 Driver Developer's Guide 14 15Author: Brian Paul ([email protected]) 16Date: February 2000 17 18 19 20User's Guide 21------------ 22 23Using libGL.so 24 25The libGL.so library defines the gl- and glX-prefixed functions needed to 26run OpenGL programs. OpenGL client applications should link with the 27-lGL option to use it. 28 29libGL.so serves two primary functions: GLX protocol generation for indirect 30rendering and loading/management of hardware drivers for direct rendering. 31 32When libGL.so initializes itself it uses the DRI to determine the 33appropriate hardware driver for each screen on the local X display. 34The hardware drivers are expected to be in the /usr/X11R6/lib/modules/dri/ 35directory. Drivers are named with the convention <name>_dri.so where 36<name> is a driver such as "radeon", "i965", "nouveau", etc. 37 38The LIBGL_DRIVERS_DIR environment variable may be used to specify a 39different DRI modules directory, overriding /usr/X11R6/lib/modules/dri/. 40This environment variable is ignored in setuid programs for security 41reasons. 42 43When libGL.so is unable to locate appropriate hardware drivers it will 44fall back to using indirect GLX rendering. 45 46To aid in solving problems, libGL.so will print diagnostic messages to 47stderr if the LIBGL_DEBUG environment variable is defined. 48 49libGL.so is thread safe. The overhead of thread safety for common, 50single-thread clients is negligible. However, the overhead of thread 51safety for multi-threaded clients is significant. Each GL API call 52requires two calls to pthread_get_specific() which can noticeably 53impact performance. Warning: libGL.so is thread safe but individual 54DRI drivers may not be. Please consult the documentation for a driver 55to learn if it is thread safe. 56 57 58 59Indirect Rendering 60 61You can force indirect rendering mode by setting the LIBGL_ALWAYS_INDIRECT 62environment variable to `true`. Hardware acceleration will not be used. 63 64 65 66libGL.so Extensibility 67 68libGL.so is designed to be extended without upgrading. That is, 69drivers may install new OpenGL extension functions into libGL.so 70without requiring libGL.so to be replaced. Clients of libGL.so should 71use the glXGetProcAddressEXT() function to obtain the address of 72functions by name. For more details of GLX_ARB_get_proc_address see 73http://oss.sgi.com/projects/ogl-sample/registry/ARB/get_proc_address.spec 74 75libGL.so is also designed with flexibility such that it may be used 76with many generations of hardware drivers to come. 77 78 79 80 81Driver Developer's Guide 82------------------------ 83 84This section describes the requirements to make an XFree86 4.0 85libGL.so-compatible hardware driver. It is not intended for end 86users of libGL.so. 87 88The gl_x86_asm.py and assyntax.h files implement x86-optimized dispatch 89of GL functions. They are not required; C-based dispatch can be used 90instead, with a slight performance penalty. 91 92 93 94Driver loading and binding 95 96When libGL.so initializes itself (via the __glXInitialize function) a 97call is made to driCreateDisplay(). This function uses DRI facilities 98to determine the driver file appropriate for each screen on the local 99display. Each screen's driver is then opened with dlopen() and asked 100for its __driCreateScreen() function. The pointers to the __driCreateScreen() 101functions are kept in an array, indexed by screen number, in the 102__DRIdisplayRec struct. 103 104When a driver's __driCreateScreen() function is called, it must initialize 105a __DRIscreenRec struct. This struct acts as the root of a tree of 106function pointers which are called to create and destroy contexts and 107drawables and perform all the operations needed by the GLX interface. 108See the xc/lib/GL/glx/glxclient.h file for details. 109 110 111 112Dynamic Extension Function Registration 113 114In order to provide forward compatibility with future drivers, libGL.so 115allows drivers to register new OpenGL extension functions which weren't 116known when libGL.so was built. 117 118The register_extensions() function in xc/lib/GL/dri/dri_glx.c is called 119as soon as libGL.so is loaded. This is done with gcc's constructor 120attribute. This mechanism will likely have to be changed for other compilers. 121 122register_extensions() loops over all local displays and screens, determines 123the DRI driver for each, and calls the driver's __driRegisterExtensions() 124function, if present. 125 126The __driRegisterExtensions() function can add new entrypoints to libGL 127by calling: 128 129 GLboolean _glapi_add_entrypoint(const char *funcName, GLuint offset) 130 131The parameters are the name of the function (such as "glFoobarEXT") and the 132offset of the dispatch slot in the API dispatch table. The return value 133indicates success (GL_TRUE) or failure (GL_FALSE). 134 135_glapi_add_entrypoint() will synthesize entrypoint code in assembly 136language. Assembly languages is required since parameter passing 137can't be handled correctly using a C-based solution. 138 139The address of the new entrypoint is obtained by calling the 140glXGetProcAddressARB() function. 141 142The dispatch offset number MUST be a number allocated by SGI in the same 143manner in which new GL_* constants are allocated. Using an arbitrary 144offset number will result in many problems. 145 146 147 148Dispatch Management 149 150When a GL context is made current, the driver must install its dispatch 151table as the current dispatch table. This is done by calling 152 153 void _glapi_set_dispatch(struct _glapi_table *dispatch); 154 155This will install the named dispatch table for the calling thread. 156The current dispatch table for a thread can be obtained by calling 157 158 struct _glapi_table *_glapi_get_dispatch(void); 159 160For higher performance in the common single-thread case, the global 161variable _glapi_Dispatch will point to the current dispatch table. 162This variable will be NULL when in multi-thread mode. 163 164 165 166Context Management 167 168libGL.so uses the XFree86 xthreads package to manage a thread-specific 169current context pointer. See __glXGet/SetCurrentContext() in glext.c 170 171Drivers may use the _glapi_set/get_context() functions to maintain 172a private thread-specific context pointer. 173 174