From a9e36696837b2c31ecee4017a0adffbd987c1eff Mon Sep 17 00:00:00 2001 From: Kristian Høgsberg Date: Thu, 25 Feb 2010 16:17:04 -0500 Subject: Remove remaining miniglx references --- docs/MiniGLX.html | 534 ------------------------------------------------------ 1 file changed, 534 deletions(-) delete mode 100644 docs/MiniGLX.html (limited to 'docs') diff --git a/docs/MiniGLX.html b/docs/MiniGLX.html deleted file mode 100644 index e7ebae68519..00000000000 --- a/docs/MiniGLX.html +++ /dev/null @@ -1,534 +0,0 @@ - - - - Mini GLX Specification - - -

-
Mini GLX Specification
-

-

-
Tungsten Graphics, Inc.
-
-January 20, 2003
-
-
-

-

Copyright © 2002-2003 by Tungsten Graphics, Inc., Cedar Park, -Texas. All Rights Reserved.
-
-Permission is granted to make and distribute verbatim copies of this -document provided the copyright notice and this permission notice are -preserved on all copies.
-
-

-

1. Introduction

-

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:

- - - - - - - - - - - - - - - - - - - -
ResourceData type
pixel formatsX Visual and XVisualInfo
drawing surfacesX Window or GLXDrawable
rendering contextsGLXContext
-

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:

-
- 
GLXContext glXCreateContext(Display *dpy, XVisualInfo *visInfo, GLXContext shareList, Bool direct)
-
-

The parameters are as follows:

-
-
-
dpy
-
The display handle as returned by XOpenDisplay.
-
visInfo
-
The visual as returned by glXChooseVisual.
-
shareList
-
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:

-
- 
Bool glXMakeCurrent(Display *dpy, GLXDrawable drawable, GLXContext ctx)
-
-

The parameters are as follows:

-
-
-
dpy
-
The display handle, as returned by XOpenDisplay.
-
drawable
-
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:

-
- 
void glXSwapBuffers(Display *dpy, GLXDrawable drawable)
-
-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:

-
- 
void glXDestroyContext(Display *dpy, GLXContext ctx)
-
-

3.7.2 Releasing Windows

-

A window may be destroyed by calling XDestroyWindow:

-
- 
void XDestroyWindow(Display *dpy, Window window)
-
-

3.7.3 Releasing Visuals

-

An XVisualInfo object may be freed by calling XFree:

-
- 
void XFree(void *data)
-
-

3.7.4 Releasing Colormaps

-

A colormap may be freed by calling XFreeColormap:

-
- 
void XFreeColormap(Display *dpy, Colormap colormap)
-
-

3.7.4 Releasing Display Resources

-

When the application is about to exit, the resources associated with -the graphics system can be released by calling XCloseDisplay:

-
- 
void XCloseDisplay(Display *dpy)
-
-

The display handle becomes invalid at this point.
-
-

-

3.8 Query Functions

-

3.8.1 Querying Available Visuals

-A list of all available visuals can be obtained with the XGetVisualInfo -function:
-
-
XVisualInfo -*XGetVisualInfo(Display *dpy, long vinfo_mask, XVisualInfo -*vinfo_template, int *nitems_return)
-
-
-The parameters are as follows:
-
-
-
dpy
-
The display handle, as returned by XOpenDisplay.
-
vinfo_mask
-
A bitmask indicating which fields of the vinfo_template are to -be matched.  The value must be VisualScreenMask.
-
vinfo_template
-
A template whose fields indicate which visual attributes must -be matched by the results.  The screen field of this structure must -be zero.
-
nitems_return
-
Returns the number of visuals returned.
-
-
-The return value is the address of an array of all available visuals.
-
-An example of using XGetVisualInfo to get all available visuals follows:
-
-
XVisualInfo visTemplate, *results;
-int numVisuals;
-Display *dpy = XOpenDisplay(NULL);
-visTemplate.screen = 0;
-results = XGetVisualInfo(dpy, VisualScreenMask, &visTemplate, -&numVisuals);
-
-
-

3.8.2 Querying Visual Attributes

-

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 */

#include <stdio.h>
#include <stdlib.h>
#include <GL/gl.h>

#if USE_MINIGLX
#include <GL/miniglx.h>
#else
#include <GL/glx.h>
#include <X11/Xlib.h>
#endif

/*
 * Create a simple double-buffered RGBA window.
 */
static Window
MakeWindow(Display * dpy, unsigned int width, unsigned int height)
{
   int visAttributes[] = {
      GLX_RGBA,
      GLX_RED_SIZE, 1,
      GLX_GREEN_SIZE, 1,
      GLX_BLUE_SIZE, 1,
      GLX_DOUBLEBUFFER,
      None
   };
   XSetWindowAttributes attr;
   unsigned long attrMask;
   Window root;
   Window win;
   GLXContext ctx;
   XVisualInfo *visinfo;

   root = RootWindow(dpy, 0);

   /* Choose GLX visual / pixel format */
   visinfo = glXChooseVisual(dpy, 0, visAttributes);
   if (!visinfo) {
      printf("Error: couldn't get an RGB, Double-buffered visual\n");
      exit(1);
   }

   /* Create the window */
   attr.background_pixel = 0;
   attr.border_pixel = 0;
   attr.colormap = XCreateColormap(dpy, root, visinfo->visual, AllocNone);
   attrMask = CWBackPixel | CWBorderPixel | CWColormap;
   win = XCreateWindow(dpy, root, 0, 0, width, height,
		       0, visinfo->depth, InputOutput,
		       visinfo->visual, attrMask, &attr);
   if (!win) {
      printf("Error: XCreateWindow failed\n");
      exit(1);
   }

   /* Display the window */
   XMapWindow(dpy, win);

   /* Create GLX rendering context */
   ctx = glXCreateContext(dpy, visinfo, NULL, True);
   if (!ctx) {
      printf("Error: glXCreateContext failed\n");
      exit(1);
   }

   /* Bind the rendering context and window */
   glXMakeCurrent(dpy, win, ctx);

   return win;
}


/*
 * Draw a few frames of a rotating square.
 */
static void
DrawFrames(Display * dpy, Window win)
{
   int angle;
   glShadeModel(GL_FLAT);
   glClearColor(0.5, 0.5, 0.5, 1.0);
   for (angle = 0; angle < 360; angle += 10) {
      glClear(GL_COLOR_BUFFER_BIT);
      glColor3f(1.0, 1.0, 0.0);
      glPushMatrix();
      glRotatef(angle, 0, 0, 1);
      glRectf(-0.8, -0.8, 0.8, 0.8);
      glPopMatrix();
      glXSwapBuffers(dpy, win);
   }
}


int
main(int argc, char *argv[])
{
   Display *dpy;
   Window win;

   dpy = XOpenDisplay(NULL);
   if (!dpy) {
      printf("Error: XOpenDisplay failed\n");
      return 1;
   }

   win = MakeWindow(dpy, 300, 300);

   DrawFrames(dpy, win);

   return 0;
}
-
- - -- cgit v1.2.3