diff options
| -rw-r--r-- | Makefile.am | 1 | ||||
| -rw-r--r-- | specs/GL/libGL.txt | 197 |
2 files changed, 0 insertions, 198 deletions
diff --git a/Makefile.am b/Makefile.am index d91f9a7..fc2b54e 100644 --- a/Makefile.am +++ b/Makefile.am @@ -35,7 +35,6 @@ EXTRA_DIST = \ specs/BDF/fig2.ps \ specs/CTEXT/ctext.tbl.ms \ specs/FSProtocol/protocol.ms \ - specs/GL/libGL.txt \ specs/ICCCM/icccm.ms \ specs/ICCCM/indexmacros.t \ specs/ICE/ICElib.ms \ diff --git a/specs/GL/libGL.txt b/specs/GL/libGL.txt deleted file mode 100644 index cb98840..0000000 --- a/specs/GL/libGL.txt +++ /dev/null @@ -1,197 +0,0 @@ - - - -Introduction ------------- - -This document describes the implementation of the XFree86 4.0 libGL.so -library defined by the Linux/OpenGL Base specification found at -http://reality.sgi.com/opengl/linux/linuxbase.html. - -The documentation is divided into two sections: - User's Guide - Driver Developer's Guide - -Author: Brian Paul (brian@precisioninsight.com) -Date: February 2000 - - - -User's Guide ------------- - -Using libGL.so - -The libGL.so library defines the gl- and glX-prefixed functions needed to -run OpenGL programs. OpenGL client applications should link with the --lGL option to use it. - -libGL.so serves two primary functions: GLX protocol generation for indirect -rendering and loading/management of hardware drivers for direct rendering. - -When libGL.so initializes itself it uses the DRI to determine the -appropriate hardware driver for each screen on the local X display. -The hardware drivers are expected to be in the /usr/X11R6/lib/modules/dri/ -directory. Drivers are named with the convention <name>_dri.so where -<name> is a driver such as "tdfx", "i810", "gamma", etc. - -The LIBGL_DRIVERS_DIR environment variable may be used to specify a -different DRI modules directory, overriding /usr/X11R6/lib/modules/dri/. -This environment variable is ignored in setuid programs for security -reasons. - -When libGL.so is unable to locate appropriate hardware drivers it will -fall back to using indirect GLX rendering. - -To aid in solving problems, libGL.so will print diagnostic messages to -stderr if the LIBGL_DEBUG environment variable is defined. - -libGL.so is thread safe. The overhead of thread safety for common, -single-thread clients is negligible. However, the overhead of thread -safety for multi-threaded clients is significant. Each GL API call -requires two calls to pthread_get_specific() which can noticably -impact performance. Warning: libGL.so is thread safe but individual -DRI drivers may not be. Please consult the documentation for a driver -to learn if it is thread safe. - - - -Indirect Rendering - -You can force indirect rendering mode by setting the LIBGL_ALWAYS_INDIRECT -environment variable. Hardware acceleration will not be used. - - - -libGL.so Extensibility - -libGL.so is designed to be extended without upgrading. That is, -drivers may install new OpenGL extension functions into libGL.so -without requiring libGL.so to be replaced. Clients of libGL.so should -use the glXGetProcAddressEXT() function to obtain the address of -functions by name. For more details of GLX_ARB_get_proc_address see -http://oss.sgi.com/projects/ogl-sample/registry/ARB/get_proc_address.spec - -libGL.so is also designed with flexibility such that it may be used -with many generations of hardware drivers to come. - - - - -Driver Developer's Guide ------------------------- - -This section describes the requirements to make an XFree86 4.0 -libGL.so-compatible hardware driver. It is not intended for end -users of libGL.so. - - -XFree86 source files - -libGL.so is built inside XFree86 with sources found in xc/lib/GL/. -Specifically, libGL.so is built from: - - xc/lib/GL/glx/*.c - xc/lib/dri/XF86dri.c - xc/lib/dri/dri_glx.c - xc/lib/GL/mesa/src/glapi.c - xc/lib/GL/mesa/src/glapitemp.h - xc/lib/GL/mesa/src/glapitable.h - xc/lib/GL/mesa/src/glapioffsets.h - xc/lib/GL/mesa/src/glapinoop.c - xc/lib/GL/mesa/src/glheader.h - xc/lib/GL/mesa/src/glthread.c - xc/lib/GL/mesa/src/glthread.h - xc/lib/GL/mesa/src/X86/glapi_x86.S - xc/lib/GL/mesa/src/X86/assyntax.h - -Understand that the mesa/src/gl*.[ch] files are not tied to Mesa. They -have no dependencies on the rest of Mesa and are designed to be reusable -in a number of projects. - -The glapi_x86.X and assyntax.h files implement x86-optimized dispatch -of GL functions. They are not required; C-based dispatch can be used -instead, with a slight performance penalty. - - - -Driver loading and binding - -When libGL.so initializes itself (via the __glXInitialize function) a -call is made to driCreateDisplay(). This function uses DRI facilities -to determine the driver file appropriate for each screen on the local -display. Each screen's driver is then opened with dlopen() and asked -for its __driCreateScreen() function. The pointers to the __driCreateScreen() -functions are kept in an array, indexed by screen number, in the -__DRIdisplayRec struct. - -When a driver's __driCreateScreen() function is called, it must initialize -a __DRIscreenRec struct. This struct acts as the root of a tree of -function pointers which are called to create and destroy contexts and -drawables and perform all the operations needed by the GLX interface. -See the xc/lib/GL/glx/glxclient.h file for details. - - - -Dynamic Extension Function Registration - -In order to provide forward compatibility with future drivers, libGL.so -allows drivers to register new OpenGL extension functions which weren't -known when libGL.so was built. - -The register_extensions() function in xc/lib/GL/dri/dri_glx.c is called -as soon as libGL.so is loaded. This is done with gcc's constructor -attribute. This mechanism will likely have to be changed for other compilers. - -register_extensions() loops over all local displays and screens, determines -the DRI driver for each, and calls the driver's __driRegisterExtensions() -function, if present. - -The __driRegisterExtensions() function can add new entrypoints to libGL -by calling: - - GLboolean _glapi_add_entrypoint(const char *funcName, GLuint offset) - -The parameters are the name of the function (such as "glFoobarEXT") and the -offset of the dispatch slot in the API dispatch table. The return value -indicates success (GL_TRUE) or failure (GL_FALSE). - -_glapi_add_entrypoint() will synthesize entrypoint code in assembly -language. Assembly languages is required since parameter passing -can't be handled correctly using a C-based solution. - -The address of the new entrypoint is obtained by calling the -glXGetProcAddressARB() function. - -The dispatch offset number MUST be a number allocated by SGI in the same -manner in which new GL_* constants are allocated. Using an arbitrary -offset number will result in many problems. - - - -Dispatch Management - -When a GL context is made current, the driver must install its dispatch -table as the current dispatch table. This is done by calling - - void _glapi_set_dispatch(struct _glapi_table *dispatch); - -This will install the named dispatch table for the calling thread. -The current dispatch table for a thread can be obtained by calling - - struct _glapi_table *_glapi_get_dispatch(void); - -For higher performance in the common single-thread case, the global -variable _glapi_Dispatch will point to the current dispatch table. -This variable will be NULL when in multi-thread mode. - - - -Context Management - -libGL.so uses the XFree86 xthreads package to manage a thread-specific -current context pointer. See __glXGet/SetCurrentContext() in glext.c - -Drivers may use the _glapi_set/get_context() functions to maintain -a private thread-specific context pointer. - |