The Mini GLX interface facilitates OpenGL rendering on embedded
-devices. The interface is a subset of the GLX interface, plus a minimal
-set of Xlib-like functions.
-
Programs written to the Mini GLX specification should run unchanged
-on systems with the X Window System and the GLX extension. The intention
-is to allow flexibility for prototyping and testing.
-
This document serves as both the reference guide and programming
-guide for Mini GLX.
-
-
-
2. Mini GLX Concepts
-
The OpenGL specification does not describe how OpenGL rendering
-contexts and drawing surfaces (i.e. the frame buffer) are created and
-managed. Rather, this is handled by an OpenGL window system interface,
-such as Mini GLX.
-
There are three main datatypes or resources managed by Mini GLX. The
-resources and their corresponding GLX or Xlib data types are:
-
-
-
-
Resource
-
Data type
-
-
-
pixel formats
-
X Visual and XVisualInfo
-
-
-
drawing surfaces
-
X Window or GLXDrawable
-
-
-
rendering contexts
-
GLXContext
-
-
-
-
Pixel formats or X Visuals describe the per-pixel attributes of the
-frame buffer. For example, bits per color component, Z buffer size,
-stencil size, TrueColor vs PseudoColor, etc.
-
Drawing surfaces or X Windows typically describe a spatial
-allocation of the frame buffer (i.e. the position and size of a
-rectangular region of pixels). Since MiniGLX doesn't really support a
-window system, the window is effectively the entire frame buffer.
-
A rendering context represents the current OpenGL state such as
-current drawing color, line width, blending mode, texture parameters,
-etc. Several rendering contexts can be created but only one can be in
-use at any given time.
-
The Mini GLX interface provides all the functions needed for
-choosing pixel formats, create drawing surfaces, creating rendering
-contexts and binding rendering contexts to drawing surfaces.
-
-
-
3. Using Mini GLX
-
To use the Mini GLX interface in your application, include the
-GL/miniglx.h header file at compile time:
-
#include <GL/miniglx.h>
-
-Applications should link with libGL.so (i.e. gcc
-myprogram.o -lGL -o myprogram). libGL.so implements the
-MiniGLX API functions and, in turn, loads a hardware-specific device
-driver (such as radeon_dri.so) at runtime. The
-environment variable LIBGL_DRIVERS_PATH should name the
-directory where these modules are located.
-
-The remainder of this section describes the MiniGLX API functions.
-
-
3.1 Initialization
-
The XOpenDisplay function is used to initialize the graphics system:
-
-
Display *XOpenDisplay(const char *displayname)
-
-
The displayName parameter is currently ignored in Mini
-GLX. It is recommended that NULL be passed as thedisplayName
-parameter.
-
If XOpenDisplay is able to initialize the graphics system a pointer
-to a Display will be returned. Otherwise, NULL will be returned.
-
3.2 Choosing a Visual
-
A visual (i.e. pixel format) must be chosen before a drawing surface
-or rendering context can be created. This is done with the
-glXChooseVisual function:
-
-
XVisualInfo *glXChooseVisual(Display *dpy, int screen, const int *attribList)
-
-
dpy is a pointer to the display returned by
-XOpenDisplay.
-
screen is currently ignored by Mini GLX and should be
-zero.
-
attribList is a list of GLX attributes which describe
-the desired pixel format. It is terminated by the token None.
-The attributes are as follows:
-
-
-
GLX_USE_GL
-
This attribute should always be present in order to maintain
-compatibility with GLX.
-
GLX_RGBA
-
If present, only RGBA pixel formats will be considered.
-Otherwise, only color index formats are considered.
-
GLX_DOUBLEBUFFER
-
if present, only double-buffered pixel formats will be chosen.
-
GLX_RED_SIZE n
-
Must be followed by a non-negative integer indicating the
-minimum number of bits per red pixel component that is acceptable.
-
GLX_GREEN_SIZE n
-
Must be followed by a non-negative integer indicating the
-minimum number of bits per green pixel component that is acceptable.
-
GLX_BLUE_SIZE n
-
Must be followed by a non-negative integer indicating the
-minimum number of bits per blue pixel component that is acceptable.
-
GLX_ALPHA_SIZE n
-
Must be followed by a non-negative integer indicating the
-minimum number of bits per alpha pixel component that is acceptable.
-
GLX_STENCIL_SIZE n
-
Must be followed by a non-negative integer indicating the
-minimum number of bits per stencil value that is acceptable.
-
None
-
This token is used to terminate the attribute list.
-
-
-
glXChooseVisual will return a pointer to an XVisualInfo object which
-most closely matches the requirements of the attribute list. If there
-is no visual which matches the request, NULL will be returned.
-
Note that visuals with accumulation buffers and depth buffers are
-not available.
-
-
-
3.3 Creating a Drawing Surface
-
Drawing surfaces are created as X windows. For Mini GLX,
-windows are full-screen; they cover the entire frame buffer.
- Also, Mini GLX imposes a limit of one window. A second window
-cannot be created until the first one is destroyed.
-
3.3.1 Window Creation
-
The XCreateWindow function is used to create a drawing surface:
-
-
Window XCreateWindow( Display *display, Window parent, int x, int y, unsigned int width, unsigned int height, unsigned int borderWidth, int depth, unsigned int class, Visual *visual, unsigned long valuemask, XSetWindowAttributes *attributes )
-
-
The parameters are as follows:
-
-
-
display
-
A Display pointer, as returned by XOpenDisplay.
-
parent
-
The parent window for the new window. For Mini GLX, this
-should beRootWindow(dpy, 0).
-
x, y
-
The position of the window. For Mini GLX, both values should
-be zero.
-
width, height
-
The size of the window. For Mini GLX, this specifies the
-desired screen size such as 1024, 768 or 1280, 1024.
-
borderWidth
-
This parameter should be zero.
-
depth
-
The pixel depth for the window. For Mini GLX this should be
-the depth found in the XVisualInfo object returned by glxChooseVisual.
-
class
-
The window class. For Mini GLX this value should be InputOutput.
-
visual
-
This parameter should be the visual field of the XVisualInfo
-object returned by glxChooseVisual.
-
valuemask
-
This parameter indicates which fields of the XSetWindowAttributes
-are to be used. For Mini GLX this is typically the bitmaskCWBackPixel
-| CWBorderPixel | CWColormap.
-
attributes
-
Initial window attributes. Of the fields in the XSetWindowAttributes
-structure, thebackground_pixel, border_pixel
-and colormap fields should be set. See the discussion
-below regarding colormaps.
-
-
-
XCreateWindow will return a window handle if it succeeds
-or zero if it fails.
-
3.3.2 Window Mapping
-
To display the window the XMapWindow function must be called:
-
-
void XMapWindow(Display *dpy, Window w)
-
-
This function does nothing in Mini GLX but is required for Xlib/GLX
-compatibility
-
3.3.3 Colormaps
-
-
Xlib requires specification of a colormap when creating a window.
- For purposes of interoperability, Mini GLX requires this as well,
-though the colormap is not actually used. The XCreateColormap
-function is used to create a colormap:
-
Colormap XCreateColormap(Display *dpy, Window window,
-Visual *visual, int alloc)
-
-
The parameters are as follows:
-
-
-
-
dpy
-
The display handle as returned by XOpenDisplay.
-
window
-
This parameter is ignored by Mini GLX but should be the value
-returned by the RootWindow(dpy, 0) macro.
-
-
visual
-
This parameter is ignored by Mini GLX but should be the visual
-field of the XVisualInfo object returned by glXChooseVisual.
-
alloc
-
This parameter is ignored by Mini GLX but should be set to AllocNone.
-
-
-
-
3.4 Creating a Rendering Context
-
An OpenGL rendering context is created with the glXCreateContext
-function:
If non-zero, texture objects and display lists are shared with
-the named rendering context. If zero, texture objects and display lists
-will (initially) be private to this context. They may be shared when a
-subsequent context is created.
-
direct
-
Specifies whether direct or indirect rendering is desired. For
-Mini GLX this value is ignored but it should be set to True.
-
-
-
glXCreateContext will return a GLXContext handle if it
-succeeds or zero if it fails due to invalid parameter or insufficient
-resources.
-
-
-
3.5 Binding a Rendering Context
-
The final step before beginning OpenGL rendering is to bind (i.e.
-activate) a rendering context and drawing surface with the
-glXMakeCurrent function:
The window or drawable to bind to the rendering context. This
-should be the value returned by XCreateWindow.
-
ctx
-
The rendering context to bind, as returned by glXCreateContext.
-
-
-
If glXMakeCurrent succeeds True is returned. Otherwise False is
-returned to indicate an invalid display, window or context parameter.
-
After the rendering context has been bound to the drawing surface
-OpenGL rendering can begin.
-
The current rendering context may be unbound by calling
-glXMakeCurrent with the window and context parameters set to zero.
-
An application may create any number of rendering contexts and bind
-them as needed. Note that binding a rendering context is generally not a
-light-weight operation. Most simple OpenGL applications create
-only one rendering context.
-
-
-
3.6 Color Buffer Swapping
-
A double buffered window has two color buffers: a front buffer and a
-back buffer. Normally, rendering is directed to the back buffer while
-the front buffer is displayed. When rendering of a frame is finished
-the front and back buffers are swapped to provide the illusion of
-instanteous screen updates.
-
The color buffers for a particular window (i.e. drawable) may be
-swapped with the glXSwapBuffers command:
-Any pending rendering commands will be completed before the buffer swap
-takes place.
-
-Calling glXSwapBuffers on a window which is single-buffered has no
-effect.
-
-
3.7 Releasing Resources
-
3.7.1 Releasing Rendering Contexts
-
A rendering context may be destroyed by calling glXDestroyContext:
The GLX attributes of an X visual may be queried with the
-glXGetConfig function:
-
-
int glXGetConfig(Display *dpy, XVisualInfo *vis, int attribute, int *value)
-
-
The parameters are as follows:
-
-
-
dpy
-
The display handle, as returned by XOpenDisplay.
-
vis
-
The visual, as returned by glXChooseVisual.
-
attribute
-
The attribute to query. The attributes are listed below.
-
value
-
Pointer to an integer in which the result of the query will be
-stored.
-
-
-
The return value will be zero if no error occurs.
- GLX_INVALID_ATTRIBUTE will be returned if the attribute
-parameter is invalid. GLX_BAD_VISUAL will be returned
-if the XVisualInfo parameter is invalid.
-
The following attributes may be queried:
-
-
-
GLX_USE_GL
-
The result will be True or False to
-indicate if OpenGL rendering is supported with the visual. Mini GLX
-always return True.
-
GLX_RGBA
-
The result will be True for RGBA visuals or False
-for color index visuals.
-
GLX_DOUBLEBUFFER
-
The result will be True if the visual has two
-color buffers or False if the visual has one color buffer.
-
GLX_RED_SIZE
-
The result will be the number of red bits per pixel.
-
GLX_GREEN_SIZE
-
The result will be the number of green bits per pixel.
-
GLX_BLUE_SIZE
-
The result will be the number of blue bits per pixel.
-
GLX_ALPHA_SIZE
-
The result will be the number of alpha bits per pixel.
-
GLX_DEPTH_SIZE
-
The result will be the number of bits per Z value.
-
GLX_STENCIL_SIZE
-
The result will be the number of bits per stencil value.
-
-
-
-
-
3.8.3 Querying the Current Rendering Context
-
The current rendering context can be queried with
-glXGetCurrentContext:
-
-
GLXContext glXGetCurrentContext(void)
-
-
Zero will be returned if no context is currently bound.
-
-
-
3.8.4 Querying the Current Drawable
-
The current drawable (i.e. window or drawing surface) can be queried
-with glXGetCurrentDrawable:
-
-
GLXDrawable glXGetCurrentDrawable(void)
-
-
Zero will be returned if no drawable is currently bound.
-
-
-
3.8.5 Function Address Queries
-
The glXGetProcAddress function will return the address of any
-available OpenGL or Mini GLX function:
-
-
void *glXGetProcAddress(const GLubyte *procName)
-
-
If procName is a valid function name, a pointer to that
-function will be returned. Otherwise, NULL will be returned.
-
The purpose of glXGetProcAddress is to facilitate using future
-extensions to OpenGL or Mini GLX. If a future version of the library
-adds new extension functions they'll be accessible via
-glXGetProcAddress. The alternative is to hard-code calls to the new
-functions in the application but doing so will prevent linking the
-application with older versions of the library.
-
-
-
3.9 Versioning
-The Mini GLX version can be queried at run time with glXQueryVersion:
-
-
Bool glXQueryVersion(Display *dpy, int *major, int *minor)
-
-
major will be set to the major version number andminor
-will be set to the minor version number.True will be
-returned if the function succeeds. False will be returned
-if the function fails due to invalid parameters. The dpy
-argument is currently ignored, but should be the value returned by
-XOpenDisplay.
-
At compile time, the Mini GLX interface version can be tested with
-the MINI_GLX_VERSION_1_x preprocessor tokens. For example, if
-version 1.0 of Mini GLX is supported, then MINI_GLX_VERSION_1_0
-will be defined. If version 1.1 of Mini GLX is supported, then
-MINI_GLX_VERSION_1_1 will be defined.
-
At the time of writing the current Mini GLX version is 1.0.
-
-
-
4.0 Interoperability with GLX and Xlib
-While Mini GLX strives to be compatible with GLX and Xlib there are
-some unavoidable differences which must be taken into consideration.
-
4.1 Public vs Private Structures
-The structure of many X data types is public. For example, the Display
-data type is defined as a structure in /usr/include/X11/Xlib.h and
-programmers may access any fields of that structure at will. Mini
-GLX also defines a Display data type but its fields are hidden and not
-visiblein miniglx.h. Duplicating the Xlib
-declaration for the Display data type in minigl.h would
-require defining a large number of other superfluous Xlib datatypes.
-
-Mini GLX users are discouraged from directly accessing the fields of
-Xlib data types to maximize portability - though this is unavoidable to
-some extent. For example, the XVisualInfo and XSetWindowAtttributes
-data types must be completely public.
-
4.2 Macros
-In some cases, Xlib defines macros which are meant to be used instead
-of direct structure accesses. For example, the RootWindow(dpy,
-screen) macro returns the root window for a given screen on a
-given display. Unfortunately, macros do nothing to aid in ABI
-compatibility since they are resolved at compile time instead of at
-link/run time.
-
-Mini GLX also defines a RootWindow macro since it's
-essential for creating windows. But the implementation of this
-macro by Xlib and Mini GLX is completely different.
-
4.3 Summary
-Because Xlib and Mini GLX define data types and macros differently,
-Mini GLX applications must be recompiled when retargeting Mini GLX or
-native Xlib/GLX. That is, applications can't simply be re-linked
-because of ABI incompatibilities.
-
-Nevertheless, the fact that Mini GLX programs can be recompiled for
-Xlib and GLX increases portability and flexibility for testing and
-prototyping.
-
-
5.0 Example Program
-
This section shows an example program which uses the Mini GLX
-interface. The program simply draws several frames of a rotating square.
-
-
The program may be compiled for use with Xlib/GLX or Mini GLX by
-setting the USE_MINIGLX token to 0 or 1, respectively.
- Note that the only difference is the header files which are
-included.
-
-
-
#define USE_MINIGLX 1 /* 1 = use Mini GLX, 0 = use Xlib/GLX */
-
-
-
diff --git a/docs/README.D3D b/docs/README.D3D
deleted file mode 100644
index b41fcb62085..00000000000
--- a/docs/README.D3D
+++ /dev/null
@@ -1,124 +0,0 @@
-
- DirectX 6 Driver for Mesa 3.0
-
-
-This software is distributed under the terms of the GNU Library
-General Public License, see the LICENSE file for details.
-
-
-
-What do you need ?
-------------------
-
- - A PC with a DirectX 6 video driver installed.
-
- - Mesa 3.0
-
- - The 3Dfx Glide library 2.3 or later for your OS (the 2.4 works fine).
- The Voodoo2 requires the Glide library 2.51. The Glide 3.0 is not
- compatible with the Glide 2.x so it doesn't work with the current
- version of the driver;
-
- - Visual C++ 5.0 is only compiler test but others should be ok with
- changes to the makefiles (CFLAGS/LFLAGS).
-
- - DirectX 6 SDK (was a MS download but not sure if still available).
-
- - SoftIce or another debugger that will get DPF's is nice.
-
-
-Tested on:
-----------
- Windows 95
- Windows 98
- Windows NT 5.0 (beta 2)
-
-
-What is able to do ?
---------------------
-
- - the driver will try and use DirectX to rasterize the OpenGL primitives
- that are sent to the driver. The driver will fall back to SW if the rendering
- context is too big. The fallback to SW still uses DirectDraw. If the driver
- fails to support and operation (accum, stencil, etc) then it will try and get
- Mesa to render it in SW. DirectX 6 features that are unsupported by the
- installed DirectX 6 driver will be mapped to some other best fit feature.
-
-
-How to compile:
----------------
-
- These instructions assume you have Visual C++ installed.
-
- You might need to increase you enviroment space. You can do this by
- adding the following statement to you config.sys.
-
- shell=C:\COMMAND.COM C:\ /p /e:8198
-
- Next setup you compiler enviroment by running vcvars32.bat in the Visual C++
- 'bin' directoy.
-
- c:\DevStudio\VC\bin\vcvars32.bat
-
- Modify the D3D makefile to point at your SDK install. Example has the SDK
- installed on my 'f' drive in the root.
-
- file: \Mesa-3.0\src\makefile.d3d
-
- SDKROOT=f:\mssdk
-
- Now you can simply make the project. If you look in the makefile you can see
- I have some different targets like 'install'.
-
- nmake /f makefile.d3d
-
-
-FAQ:
-----
-
- 1) I don't think the driver is using my DirectX driver.
-
- This maybe true as the current version will only select the Primary D3D driver
- installed. If you 3D card is the secondary (3dfx) then your out of luck for this
- release.
-
- 2) The driver seems like its not HW accelerated.
-
- If you have a video card with limited memory then you might want to try and
- change your destop resolution to a low setting (640x480x16) so that the 3D part
- of the card has more resources. Remeber the driver can't make the card better...
-
- 3) Nothing works.
-
- Make sure you have a DirectX '6' driver installed. Check you driver docs for this
- info or use the SDK info utilities.
- The final 'dll' is named opengl32.dll and is either in the same directory as the
- OpenGL program or in your system directory (x:\windows\system or x:\winnt\system32).
- Check your destop resolution. Most DirectX 6 drivers will only support 16bit and
- 32bit color depth. To find out for sure you can check the DirectX Info Viewer in
- the SDK.
-
-
- 4) Rendering doesn't look right.
-
- Sometimes this is because the card doesn't support a feature that that is required.
- This is usually due to unsupported alpha functions (test/blend) or texture mapping.
- Some cards suffer from too small of an alpha channel. The driver does its best to
- fallback on unsupported features. This is not to say the driver may not have a bug(s).
-
- 5) Textures look bad.
-
- No mipmapping in this release.
-
-
-Thanks to:
-----------
-
-Brian Paul
-
-
-
-
-Leigh McRae (leigh@altsoftware.com)
-February 9, 1999
-
diff --git a/docs/README.directfb b/docs/README.directfb
deleted file mode 100644
index d66ca8d3caa..00000000000
--- a/docs/README.directfb
+++ /dev/null
@@ -1,29 +0,0 @@
-
- Mesa DirectFB Information
-
-
-Requirements
-============
-
- To build Mesa with DirectFB (DirectFBGL) support you need:
- - DirectFB at least 1.0.0 (http://directfb.org)
- - pkg-config at least 0.9 (http://pkgconfig.sf.net)
-
-
-Installation
-============
- Run
-
- make linux-directfb
-
- to build Mesa and DirectFBGL module,
-
- make install
-
- to install OpenGL libraries and
-
- cd src/mesa/drivers/directfb ; make install
-
- to install DirectFBGL module in the proper location.
- Actually, that last command may not be needed. Please provide feedback.
-
diff --git a/docs/contents.html b/docs/contents.html
index f0646ffb402..cca20ecaae8 100644
--- a/docs/contents.html
+++ b/docs/contents.html
@@ -92,7 +92,6 @@ a:visited {