mirror of
https://gitee.com/openharmony/third_party_mesa3d
synced 2024-11-23 07:19:50 +00:00
aea456776c
This reference was left over when the envvar was removed.
Fixes: 231ccb6100 ("docs: Remove no-longer-accurate text about the xlib driver")
Reviewed-by: Yonggang Luo <luoyonggang@gmail.com>
Part-of: <https://gitlab.freedesktop.org/mesa/mesa/-/merge_requests/19593>
(cherry picked from commit 9bfa939a5e6377efe7b610dd9b6846edeb0fdafc)
173 lines
6.2 KiB
ReStructuredText
173 lines
6.2 KiB
ReStructuredText
Xlib Software Driver
|
|
====================
|
|
|
|
Mesa's Xlib driver provides an emulation of the GLX interface so that
|
|
OpenGL programs which use the GLX API can render to any X display, even
|
|
those that don't support the GLX extension. Effectively, the Xlib driver
|
|
converts all OpenGL rendering into Xlib calls.
|
|
|
|
The Xlib driver is the oldest Mesa driver and the most mature of Mesa's
|
|
software-only drivers.
|
|
|
|
Since the Xlib driver *emulates* the GLX extension, it's not totally
|
|
conformant with a true GLX implementation. The differences are fairly
|
|
obscure, however.
|
|
|
|
The unique features of the Xlib driver follows.
|
|
|
|
X Visual Selection
|
|
------------------
|
|
|
|
Mesa supports RGB(A) rendering into TrueColor and DirectColor visuals, for
|
|
any depth with a corresponding renderable OpenGL texture format.
|
|
|
|
The glXChooseVisual function tries to choose the best X visual for the
|
|
given attribute list. However, if this doesn't suit your needs you can
|
|
force Mesa to use any X visual you want (any supported by your X server
|
|
that is) by setting the **MESA_RGB_VISUAL** environment variable. When
|
|
a visual is requested, glXChooseVisual will first look if the
|
|
MESA_RGB_VISUAL variable is defined. If so, it will try to use the
|
|
specified visual.
|
|
|
|
The format of accepted values is: ``visual-class depth``
|
|
|
|
Here are some examples:
|
|
|
|
::
|
|
|
|
using csh:
|
|
% setenv MESA_RGB_VISUAL "TrueColor 8" // 8-bit TrueColor
|
|
% setenv MESA_RGB_VISUAL "DirectColor 30" // 30-bit DirectColor
|
|
|
|
using bash:
|
|
$ export MESA_RGB_VISUAL="TrueColor 8"
|
|
$ export MESA_RGB_VISUAL="DirectColor 30"
|
|
|
|
Double Buffering
|
|
----------------
|
|
|
|
Mesa can use either an X Pixmap or XImage as the back color buffer when
|
|
in double-buffer mode. The default is to use an XImage. The
|
|
**MESA_BACK_BUFFER** environment variable can override this. The valid
|
|
values for **MESA_BACK_BUFFER** are: **Pixmap** and **XImage** (only the
|
|
first letter is checked, case doesn't matter).
|
|
|
|
Using XImage is almost always faster than a Pixmap since it resides in
|
|
the application's address space. When glXSwapBuffers() is called,
|
|
XPutImage() or XShmPutImage() is used to transfer the XImage to the
|
|
on-screen window.
|
|
|
|
A Pixmap may be faster when doing remote rendering of a simple scene.
|
|
Some OpenGL features will be very slow with a Pixmap (for example,
|
|
blending will require a round-trip message for pixel readback.)
|
|
|
|
Experiment with the MESA_BACK_BUFFER variable to see which is faster for
|
|
your application.
|
|
|
|
Colormaps
|
|
---------
|
|
|
|
When using Mesa directly or with GLX, it's up to the application writer
|
|
to create a window with an appropriate colormap. The GLUT toolkit tries
|
|
to minimize colormap *flashing* by sharing colormaps when possible.
|
|
Specifically, if the visual and depth of the window matches that of the
|
|
root window, the root window's colormap will be shared by the Mesa
|
|
window. Otherwise, a new, private colormap will be allocated.
|
|
|
|
When sharing the root colormap, Mesa may be unable to allocate the
|
|
colors it needs, resulting in poor color quality. This can happen when a
|
|
large number of colorcells in the root colormap are already allocated.
|
|
|
|
Overlay Planes
|
|
--------------
|
|
|
|
Hardware overlay planes are supported by the Xlib driver. To determine
|
|
if your X server has overlay support you can test for the
|
|
SERVER_OVERLAY_VISUALS property:
|
|
|
|
.. code-block:: console
|
|
|
|
xprop -root | grep SERVER_OVERLAY_VISUALS
|
|
|
|
|
|
Extensions
|
|
----------
|
|
|
|
The following Mesa-specific extensions are implemented in the Xlib
|
|
driver.
|
|
|
|
GLX_MESA_pixmap_colormap
|
|
~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
This extension adds the GLX function:
|
|
|
|
.. code-block:: c
|
|
|
|
GLXPixmap glXCreateGLXPixmapMESA( Display *dpy, XVisualInfo *visual,
|
|
Pixmap pixmap, Colormap cmap )
|
|
|
|
It is an alternative to the standard glXCreateGLXPixmap() function.
|
|
Since Mesa supports RGB rendering into any X visual, not just True-
|
|
Color or DirectColor, Mesa needs colormap information to convert RGB
|
|
values into pixel values. An X window carries this information but a
|
|
pixmap does not. This function associates a colormap to a GLX pixmap.
|
|
See the xdemos/glxpixmap.c file for an example of how to use this
|
|
extension.
|
|
|
|
`GLX_MESA_pixmap_colormap
|
|
specification <specs/MESA_pixmap_colormap.spec>`__
|
|
|
|
GLX_MESA_release_buffers
|
|
~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
Mesa associates a set of ancillary (depth, accumulation, stencil and
|
|
alpha) buffers with each X window it draws into. These ancillary buffers
|
|
are allocated for each X window the first time the X window is passed to
|
|
glXMakeCurrent(). Mesa, however, can't detect when an X window has been
|
|
destroyed in order to free the ancillary buffers.
|
|
|
|
The best it can do is to check for recently destroyed windows whenever
|
|
the client calls the glXCreateContext() or glXDestroyContext()
|
|
functions. This may not be sufficient in all situations though.
|
|
|
|
The GLX_MESA_release_buffers extension allows a client to explicitly
|
|
deallocate the ancillary buffers by calling glxReleaseBuffersMESA() just
|
|
before an X window is destroyed. For example:
|
|
|
|
.. code-block:: c
|
|
|
|
#ifdef GLX_MESA_release_buffers
|
|
glXReleaseBuffersMESA( dpy, window );
|
|
#endif
|
|
XDestroyWindow( dpy, window );
|
|
|
|
`GLX_MESA_release_buffers
|
|
specification <specs/MESA_release_buffers.spec>`__
|
|
|
|
This extension was added in Mesa 2.0.
|
|
|
|
GLX_MESA_copy_sub_buffer
|
|
~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
This extension adds the glXCopySubBufferMESA() function. It works like
|
|
glXSwapBuffers() but only copies a sub-region of the window instead of
|
|
the whole window.
|
|
|
|
`GLX_MESA_copy_sub_buffer
|
|
specification <specs/MESA_copy_sub_buffer.spec>`__
|
|
|
|
This extension was added in Mesa 2.6
|
|
|
|
Summary of X-related environment variables
|
|
------------------------------------------
|
|
|
|
+-----------------------------+--------------------------------------+
|
|
| Environment variable | Description |
|
|
+=============================+======================================+
|
|
| :envvar:`MESA_RGB_VISUAL` | specifies the X visual and depth for |
|
|
| | RGB mode (X only) |
|
|
+-----------------------------+--------------------------------------+
|
|
| :envvar:`MESA_BACK_BUFFER` | specifies how to implement the back |
|
|
| | color buffer (X only) |
|
|
+-----------------------------+--------------------------------------+
|