OpenGL

= OpenGL =

OpenGL is the de facto standard API for modern 3D graphics on GNU/Linux, UNIX, Mac OS X, and most any other operating system that provides a way for folks to use 3D graphics on a computer. The only exception is MS, who uses their own closed, proprietary system called Direct3D (part of DirectX), although they do also offer some support for OpenGL. The whole point of OpenGL is to provide a standard interface to 3D graphics hardware for application programmers -- and of course, this provides users with a fast, standard 3D graphics subsystem on which to run all their favorite 3D graphics software.

If you are using a program that quickly draws 3D graphics, it probably requires OpenGL to be installed on your system. If you're writing a program that needs to quickly draw 3D graphics (like a game or a 3D modeler), you very likely want to use OpenGL, so you can simply specify locations of virtual objects in a virtual 3D scene and let OpenGL do all the rendering for you.

The OpenGL specification was originally developed by SGI, and they also wrote the first implementation. There are implementations for many platforms, including Linux, MacOS and MS Windows.

OpenGL is an open spec, so anyone may implement it -- though, they may not call it "OpenGL" unless it passes certain compliance tests (and someone pays various fees). This is why Mesa isn't called something like "MesaGL" or "Mesa OpenGL" or somesuch. (More on Mesa later -- keep reading. :)

The official page with the specification can be found here.

= 3d hardware acceleration = OpenGL rendering can be accelerated by using special features on videocards. Most recent videocards support this. This requires support in the openGL library and the videocard driver. In Linux this is mostly done by using DRI. Only for Nvidia videocards this is done differently, Nvidia provide their own drivers which don't use DRI, but use their own closed-source replacement interface.

See the videocard specific notes section for more info on which cards support this under linux. = OpenGL on Linux = Since OpenGL is a specification of an API, there are of course different implementations of it. There is an open source one that comes with standard XFree86 called mesa3D. Also the proprietary drivers from Nvidia and ATI come with their own optimized implementation. The library that contains the implementations is normally called libGL.so (with symlinks to a versioned name).

= Implementations =

Mesa3D
The most common library implementation for Linux is provided by the Mesa 3D graphics library. It's an Open Source library which follows the OpenGL API, but Mesa doesn't have a license to call itself officially OpenGL. The latest version of Mesa (7.x) now supports the OpenGL 2.1 API. Also note that Mesa doesn't only support Linux+X11, it can be used on a whole range of other platforms.

Mesa3D supports full software rendering, but also 3D hardware accelerated rendering on Linux through the use of DRI. It will fallback on software rendering if the card's driver don't support a certain hardware function.

Proprietary implementations

 * Nvidia makes drivers for Linux for their whole range of 3d videocards, which include their own OpenGL library. See below.
 * ATI also makes their own drivers for Radeon 8500 and above based cards. These also include their own OpenGL lib.

= Installation and configuration in XFree86 = The following information only applies to XFree86 4.x.x versions. Most Linux distributions install XFree86 with mesa and hw 3d acceleration enabled.

To check if 3D hardware acceleration is working for openGL, you can use the following command: glxinfo | grep rendering This should output "direct rendering: Yes".

If it gives the same but then with "No", hardware 3d acceleration is disabled and all rendering will be done on the CPU ('software' rendering).

See the Troubleshooting section for some help if this happens. If it's a "Yes", you can test if OpenGL works with a simple 3d application that comes with XFree86: glxgears It will output a framerate, but it's not a good benchmark. It depends largely on the screen and window size, background processes and CPU. For a better benchmark use a 3d game (see Gaming). Quake 3 Arena demos are often used for this. Or use a special openGL benchmarking program like SPECviewperf.

Troubleshooting 3D hw accel
The Nvidia drivers are a bit different from the rest, see Installing_NVIDIA_drivers and the included README file.

For the other cards it's almost the same for each of them, they all use DRI. First a general troubleshooting will be given, this applies mainly to the opensource drivers that come with XFree86. After this some come sections with some notes for specific videocard drivers.

The 'ingredients' that are needed are:
 * Some configuration of the XF86Config file
 * A kernel module/driver (called a Direct Rendering Manager module)
 * A XFree86 driver
 * A OpenGL library

XFree86 configuration
A couple of extra things are needed in the configuration file of XFree86 to enable DRI. (See XF86Config for basic info on this file). Most XFree86 installs already have all these options configured, just check it to make sure they are. First in the 'Module' Section: Both of these are needed: Load "dri" Load "glx" ( Load "GLcore" insn't really needed, it's for remote indirect rendering but doesn't do any harm if it is enabled). Secondly, a 'DRI' section is needed which configures the permissions of who can access the direct rendering. Example section: Section "DRI" Group "video" Mode   0660 EndSection Which configures it to be only readable and writable by users in the 'video' group. To allow access to everybody, just only put the Mode line in it, with 0666.

Kernel module
The Linux kernel comes with DRI support for most videocards. Most distributions include all these as modules with their kernel. They are named after the videocard chip. For AGP cards it's also important to enable AGP support in the kernel, this module is called 'agpgart' in 2.4.x kernels and for 2.6 kernels the agp driver has been split into chipset specific drivers, the module that needs to be loaded would be called ' -agp' (which should automatically load the general 'agpgart' module. If you compile a kernel yourself, these module can be found in the section 'Device Drivers' -> 'Character Devices' -> 'Direct Rendering Manager' -> and the the name of the videocard. Current supported videocards in recent kernels are: 3dfx voodoo banshee/3, ATI rage 128, ATI Radeon, Matrox g200/g400, SiS AGP can also be found under 'Charcter Devices'.

First try if your AGP works by loading the module and checking the kernel log messages (normally done with dmesg) for confirmation that it's been loaded correctly without any errors. It should output some line starting with 'agpgart:'. Test the same with the videocard DRM modules, these should output a line starting with '[drm]' to the kernel log.

Of course these can also be built-in the kernel, then just check for these messages in the bootup messages.

XFree86 driver
This driver should come with your XFree86 install. It supports hw 3D acceleration of all the cards that also have a kernel module. To check if it's working check the XFree86 log file (normally in /var/log/XFree86.0.log). You should be looking for a line that says something like: (0): Direct Rendering enabled If it says disabled, check everything above this line for errors (lines starting with '(EE)' ).

OpenGL library
The last thing to check is the openGL library, it needs to be one that supports DRI. It should have come with your XFree86 install. To check if 3D hardware acceleration is working for the library, you can use the following command:

glxinfo | grep rendering

This should output "direct rendering: Yes".

If it's a 'No' you can check the following things:

Rerun glxinfo with debugging output: in a bash shell this can be done by running: LIBGL_DEBUG=verbose glxinfo This should give some extra info at the top of the output (note that it's send to stderr not stdin). Common error that is shows is some 'permission denied' messages on the drm device. This is often caused by not having loaded the the drm kernel module for you videocard (or you tried loading it, but it failed with some error message in the kernel log). It can also because by the persmissions set on the drm device. The latter can be configured in the 'DRI' section of the XF86Config (see XFree86 configuration section above and also the manual page for that config file). Another common error is having multiple libGL library files installed on the system (often caused by installing different drivers and XFree86 versions on top of a current XFree86 install). Check to which libGL glxinfo is linked with: ldd `which glxinfo` This should output a list of libraries this command uses. Look for a line similar to this one: libGL.so.1 => /usr/X11R6/lib/libGL.so.1 (0x400a2000) Now check the file that it's pointing to (this of often a symlink itself, keep following it until you reach the real file). You need to make sure this libGL library matches your XFree86 version or your card driver. Also check your system of more (non-symlink) libGL files. It often happens that there is one in /usr/lib and another in /usr/X11R6/lib. There should only be one real file, the rest should all be symlinks pointing the the corrent one.

Videocard specific notes
Note, see the DRI website for current information as to which hardware is supported.

3dfx
3dfx Voodoo3 and Banshee cards are supported with the DRI drivers that come with XFree86. Important note: These cards only support 3d hardware acceleration at 16bpp, so make sure X is configured to use that depth. These cards also require the Glide library version 3 to be installed. (The DRI drivers use this library). This library is available in most distributions, but make sure you've got the version compiled for voodoo3 support (it can also be compiled for voodoo1/2 support).

For voodoo1/2 it's a bit different to get OpenGL working with hardware acceleration. There aren't any DRI drivers for these, you need to have the Glide library installed for these. If you then want to use OpenGL apps, you need a specially compiled version of the Mesa3D library that uses glide to do OpenGL.

ATI
There are 2 choices for drivers for ATI cards:

Open source XFree86 (version 4.x.x. and up): these support the rage, rage 128 and Radeon based cards. 3D hardware acceleration (through DRI) is supported for most rage and rage 128 cards. But for the radeon range only for the 7000 to 9200 versions.

The proprietary ATI drivers: these support the following cards: Radeon 8500 and above (including the mobility 9000 and 9600) and FireGL 8700, 8800, E1, E2, X1, X2, Z1, T2, Mobility FireGL T2 Third party build cards based on these chipsets are also supported. Hardware 3d acceleration is supported for all these cards. These drivers can be downloaded from ATI's website here. These compile and install a kernel module called 'fglrx' and also install (overwrite) the libGL library with their own version.

Offtopic note: tv-out is supported in the proprietary drivers, but to use the tv-out/tv-in functions of the ATI cards (specially the All-in-Wonder series) see the GATOS drivers at http://gatos.sourceforge.net/

Intel
The Intel integrated video chipsets (i810 and i830 based cards) are supported with 3d acceleration.

NVidia
Driver for all Nvidia cards are available here. See NVIDIA graphics drivers for information about installing them. The README that comes with the drivers has more detailed information.

Matrox
For certain extra features to work, the Matrox cards need a closed-source binary library, the drivers with this can be downloaded from http://www.matrox.com. These come with installation instructions, but it's pretty similar to what's mentioned above. The g400 is a well-supported card.

S3
S3 Savage based drivers aren't in current XFree86 release, see DRI project for more info on these. Same thing goes for s3Virge based cards.

SIS
SIS 3d acceleration is only supported in recent versions, these aren't included in the latest XFree86 version yet. See http://www.winischhofer.net/linuxsisvga.shtml for more information on these.

VIA
The drivers for VIA integrated video chipsets aren't included in the latest release of XFree86, see http://www.viaarena.com/?PageID=325 for more info on these.

= OpenGL without X = OpenGL itself does not depend on, or use X. The GLX X extension is actually used to create and setup a OpenGL context that will output to a X window.

Outside of X, DirectFB can make use of OpenGL, as well as the Linux framebuffer with the he Mesa fbdev/DRI drivers from the Mesa3D project, and Scitech SNAP/MGL.

= Developing with OpenGL =

Documentation

 * The OpenGL Programming Guide a.k.a. The red book
 * The OpenGL Reference Manual a.k.a. The Bluebook
 * Official specifications

Toolkits
OpenGL only deals with the 3D rendering, so some GUI toolkit is needed to create the GUI window (or fullscreen) and create the OpenGL context. Example of windowing toolkits that support an OpenGL context:


 * glut -- Simple/basic (multi-platform) windowing toolkit, mainly aimed at learning OpenGL and not a full featured toolkit.
 * fltk -- Supports OpenGL through the Fl_Gl_Window class
 * GtkGLExt -- Extend GTK with OpenGL support (allows using openGL on any GTK widget)
 * GtkGLArea -- A GTK widget giving a OpenGL context
 * SDL -- Also supports creating an OpenGL window
 * Qt -- The QTGLWidget openGL widget.
 * WxWidgets - The wxGLCanvas widget
 * AllegroGL -- library to use OpenGL with allegro

Other language bindings
There are also many OpenGL bindings for other languages (apart from C/C++), some of them are:
 * Java
 * JOGL -- developed by SUN and SGI
 * GL4Java
 * python
 * pyOPenGL

Libraries on top of OpenGL

 * SGI Open Inventor
 * SGI OpenGL Performer
 * Open Scene Graph
 * Crystal Space -- open source 3D engine (http://crystal.sourceforge.net/)

= Related information = The open source drivers that support hardware 3d acceleration are developed by the DRI project. Snapshots of the latest experimental drivers can also be found there.