This is what ATI (Really the old fgldriver) states in the readme for fglxgears demo.
It can also be found in the rpm,just unzip the fglrx_sample_source.tgz file and look at the fgl_glxgears README.
It would be nice for ATI to tidy this up, if it has been in what you call beta, it sure is taking a long time.
Heath.
Using Pixel Buffers with ATI Fire GL graphics boards under Linux/XFree86 4.X
ATI Research GmbH
Markus Neff
September 13, 2001
Latest Update: 2002-Oct-10
IMPORTANT NOTE:
This is a preliminary document which might differ in several cases from
the true capabilities and specific behaviour of the fglrx drivers.
It is provided as it is in order to give the developer a minimum guideline.
- Introduction / disclaimer
This document describes and specifies the API for using Pixel Buffers
(pbuffers) with the ATI Fire GL graphics boards under Linux/XFree86.
Please note that pbuffer support is still in an early beta stage. It may
contain bugs and some limitations that we - hopefully - can clear with the
next releases of the driver.
This pre-release represents the current direction of our pbuffer support
development under Linux/XFree86. To find out if we are on the right way, we
provide this “snapshot version” of our driver (and especially the pbuffer
support) “as is” - without any warranty of fitness for usage in a “production
environment”.
- Description of the “pbuffer API”
Pbuffer support was officially introduced in GLX 1.3 but Silicon Graphics,
Inc. has publicly released only the source code of GLX 1.2 so far. This is
included in XFree4.X. To provide pbuffer support to our customers, we decided
to partially emulate the behavior of GLX 1.3 on top of GLX 1.2. As soon as
the “real” GLX 1.3 API is available in XFree86, you can use the “genuine”
pbuffers of GLX 1.3 with our drivers. This will not require any changes in
your application code because the programmer has to use the same function
calls.
To use pbuffers, you need a custom version of “libGL.so.1.2” installed -
including our GLX 1.3 emulation code. Our driver installation tool will
automatically do that for you.
NOTE: Your application will report GLX version 1.2 on glXQueryVersion.
However, it is safe to call the GLX 1.3 functions as described below.
Now let’s talk about the emulated functions of GLX 1.3. First, I’ll name all
functions that are present in our emulation layer. Then I’ll describe where
they differ from the original functions. The pdf file “glx1.3.pdf”
(ftp://ftp.sgi.com/opengl/doc/opengl1.2/glx1.3.pdf) contains the original
GLX 1.3 specs. For general questions please refer to the related chapters
of that document.
2.1 Function specification
GLX 1.3 replaces the use of X Visuals for configuration management with the
use of GLXFBConfigs. For handling GLXFBConfigs, the following functions are
provided:
- glXGetFBConfigs
- glXChooseFBConfig
- glXGetFBConfigAttrib
- glXGetVisualFromFBConfig
All of these functions are implemented in our emulation. However, please use
these functions only to manage configurations for pbuffers. For example, if
you want to create a window with a certain GLXFBConfig, you can use
glXGetVisualFromFBConfig to get the respective XVisualInfo.
Creating contexts for use with pbuffers is similar: You get the XVisualInfo
by calling glXGetVisualFromFBConfig. Then you create the context with
glXCreateContext using exactly this XVisualInfo.
To create / destroy pbuffers, the following functions exist:
- glXCreatePbuffer
- glXDestroyPbuffer
In future releases, we may provide the calls glXCreateNewContext,
glXQueryDrawable and glXMakeContextCurrent. The latter would allow to specify
a different source for pixel data when assigning a context to be the current
context. Then you can, for example, transfer images from a pbuffer to an X
window calling glCopyPixles. As for now, you can only read the pixels from
one drawable to host memory (glReadPixels) and draw them to another drawable
(glDrawPixels).
2.2 Current limitations / deviations from GLX 1.3 specs
First, let me mention some general limitations:
- You should expect that you can create only a limited number of pbuffers.
If you try to create more pbuffers than the adapter is capable then
the call to glXCreatePbuffer will not succeed but raise an error.
- When you create a pbuffer, other applications can also make use of this
pbuffer, if they know its XID. But please note the following: Unlike
stated in GLX 1.3 spec, if one client destroys a pbuffer that is
current to any client, undefined behavior occurs. That's why the
programmer has to make sure that only unbound pbuffers are destroyed.
- If you use error handlers (XSetErrorHandler) to catch GLX protocol
errors, you need to change the error handler code to look for different
major/minor opcodes. This is because the pbuffer requests don't use the
GLX protocol.
- Some error codes are different from the error codes specified in the
GLX 1.3 specs. We try to fix this and the other issues.
Function glXChooseFBConfig:
- The following attributes can be specified in the attribute list but
they will be ignored: GLX_MAX_PUBUFFER_*
- Sample application
For a better understanding and for demonstration, a simple pbuffer example
program is provided with the drivers. If you start the program, you will see
a rotating cube. On each face of the cube, you can observe a changing texture
showing three rotating gear wheels. These texture images are generated by
rendering to a pbuffer and a subsequent call to glCopyTexImage2D.
By pressing the arrow keys, the position of the gear wheels relative to the
viewer can be changed.
The following command will compile the example:
gcc -o fgl_glxgears -Wall -I/usr/X11R6/include -L/usr/X11R6/lib -lGL -lGLU -lX11 -lm fgl_glxgears.c