adamk
April 29th, 2007, 04:21 PM
This is not intended to be a complete trouble shooting guide. For that, please check out the troubleshooting section of the wiki (http://wiki.beryl-project.org/wiki/Main_Page). This is also not intended to be a guide on how to setup beryl (for that, also check out the wiki). This is intended to be a short document listing the most common questions and problems I've encountered on this forum. If you have a question you think should be added (or have a correction to something I've written since, God knows, I'm certainly not 100% correct), please e-mail me: adamk at voicenet.com. Make sure you include the phrase 'beryl faq' in the subject line of the e-mail, or it may accidentally get tagged as spam. If I think it's appropriate, I'll add the question.
I'd like to thank any number of individuals who have suggested questions for this document, provided answers, or simply hung out on #beryl and provided help to those who need it (coz and crdlb come to mind :-) ).
I wouldn't mind seeing this stickied, if a moderator thinks it's really helpful.
A HTML version of this document can be found at http://68.45.180.45/Unofficial_Beryl_FAQ2.html
* What do I need to run beryl?
For nVidia, you should always use the latest drivers from nvidia.com. Any drivers in the 1.0-9*** range will provide Composite. GLX_EXT_texture_from_pixmap is supported in those 9*** releases via direct rendering and AIGLX (you are free to use AIGLX if you like, though it is unnecessary). For GeForce FX cards and up, the latest drivers currently available are 1.0-9755. For earlier cards, please check with the README for legacy driver release 1.0-9631 (http://us.download.nvidia.com/XFree86/L ... dix-a.html) to see if your card is supported by that release. If your card is only supported by the other legacy driver (1.0-7184) you will have to use download and configure XGL to get beryl to run. Please note, however, that I have yet to hear from anyone with such a card who has managed to get beryl working.
For first and second generation Radeon cards (radeon 7000 through radeon 9250), you will need to use the open source 2D/3D drivers (which should have been installed by your distribution), and at least Xorg 7.1.1 with AIGLX and Composite enabled (keeping reading this FAQ to see how to configure xorg for Composite and AIGLX).
For 3rd and 4th generation radeon cards (radeon 9550 through the X850), you can either use the fglrx driver from ATI (the latest is 8.35.5 available here: http://ati.amd.com/support/drivers/linu ... adeon.html ) or you can use the open source driver with AIGLX. Though the Xpress 200 chipset is supported by the 2D open source driver, the open source 3D driver is not supported due to a lack of information on the memory controller. As a result, you must use fglrx + XGL on the Xpress chipsets.
For 5th and 6th generation radeon cards, you must use fglrx + XGL.
For Intel cards, you will need to use the open source drivers from Xorg 7.1.1 (or newer) and have Composite and AIGLX enabled in your xorg.conf file.
In all cases, Xorg 7.1 or higher is recommended.
* What is XGL?
XGL is an X server that is rendered via your video cards OpenGL drivers. On some cards, where Composite and the GLX_EXT_texture_from_pixmap opengl extension are not supported by your 3D drivers, XGL is the only way to use beryl and/or compiz. XGL will provide all the necessary extensions required by beryl. It first requires that you have your 3D drivers already setup and working with a normal non-XGL server. You must have Direct Rendering already working for XGL and beryl to work properly together. The setup and configuration of XGL varies from distribution to distribution. With Ubuntu/Edgy, for example, you must create an Xgl.desktop file under /usr/share/xsessions. This file will contain an Exec line (among others) that points to a script which will first launch the XGL server (usually as display :1) and then launch gnome/kde/xfce4 on that particular server. When you login to your system via the display manager (gdm, kdm, etc.), you will select the Xgl session, and this session will launch the XGL server and then your desktop environment. Please read http://en.wikipedia.org/wiki/XGL for more information about XGL. To setup XGL on your machine, you will have to locate the XGL package from your distribution, and read any provided documentation on howto set up the XGL server.
At the present moment, XGL is required for any ATI radeon card unsupported by the open source 3D drivers (so any fifth or sixth generation radeon card). Various other cards that have 3D drivers but don't support the GLX_EXT_texture_from_pixmap extension will also require XGL.
* What is AIGLX?
AIGLX is an acronym for Accelerated Indirect GLX. It adds hardware accelerated indirect GLX rendering capabilities to the Xorg and DRI drivers. Remote opengl clients can now be fully hardware accelerated over the GLX protocol (previously, this was not possible with the open source drivers). This also allowed for the inclusion of the GLX_EXT_texture_from_pixmap opengl extension, a requirement for beryl and compiz. AIGLX is currently supported on the open source radeon and intel drivers included in Xorg 7.1.1 and up. Accelerated indirect rendering has been supported on the nvidia drivers since the beginning, but the GLX_EXT_texture_from_pixmap extension was not added to the nvidia drivers till 1.0-9625. Please read http://en.wikipedia.org/wiki/Aiglx for more information.
* How do I configure Xorg to enable AIGLX and Composite?
Make sure you have these three lines in your xorg.conf file:
Section "Extensions"
Option "Composite" "True"
EndSection
In the ServerLayout section of your xorg.conf file, make sure you have:
Option "AIGLX" "true"
* I have beryl installed, but when I select beryl from the beryl icon in my system tray, nothing happens (or my current window manager vanishes). What's wrong?
Bring up a terminal and run:
$ beryl --replace &
beryl will run a series of tests and, if they all pass, it will attempt to launch itself. If it fails, make sure you are prepared to paste the output from that command when you ask for help.
* I think I have everything setup properly, but I get an error message saying:
Checking for XComposite extension : failed
If you're using any of the open source drivers, or if you're using the nvidia drivers, make sure you have Composite enabled in your xorg.conf file. If you're using the fglrx drivers from ATI, you must disable Composite in order to allow Direct Rendering. You must then download and configure XGL per your distributions instructions. If you're still think you have Composite setup properly in your config file, please post your full /var/log/Xorg.0.log file when asking for help.
* I'm using the latest nvidia drivers, and everything works fine for a while but suddenly new windows that pop up are all black.
There is a bug in the nvidia drivers that cause this to happen with the driver runs out of video memory. nvidia has acknowledged this driver bug, and is working on a fix. They have not yet given a time table for fixing this bug. In the mean time, you can try disabling various beryl plugins, or using XGL. There has been some discussion about this bug here: http://www.nvnews.net/vbulletin/showthread.php?t=84562
You can typically avoid this bug by using the copy rendering path or the AIGLX rendering platform
* I have no window deocorations (or window titles).
If you're using an nvidia card, make sure you are running at 24 bit color depth (DefaultDepth should be set to '24' in the Screen section of your xorg.conf file) and that you have the following line in either the Screen or Device section of your xorg.conf file:
Option "AddARGBGLXVisuals" "true"
You can do this with recent versions of the nvidia driver by bringing up a terminal and typing:
$ sudo nvidia-xconfig --add-argb-glx-visuals -d 24
If you do have your xorg.conf file setup properly, or your not using an nvidia card, try selecting "Reload Window Decorator" in the beryl manager icon in your system tray. If that fails, please try launching emerald (or aquamarine or heliodor) from a terminal with:
$ emerald --replace &
Check the error message and, if necessary, post it on the forums for help.
* What's the difference between heliodor, aquamarine, and emerald.
heliodor is a window decorator for beryl which uses metacity themes
aquamarine is a window decorator for beryl which uses kde themes.
emerald is a window decorator for beryl (the standard beryl decorator), which uses it's own themes.
* I have 0.2.0 or 0.2.1 installed. Where are the Desktop Wall and the Vidcap plugins?
It was not included in those releases. You will either need to download and compile bery from source or find packages for your distribution that includes that plugin.
* I'm hitting the keybinding for the water effects, but it's not working.
Your video card drivers must support pixel shaders. Specifically, the GL_ARB_fragment_program extension. Check 'glxinfo' for this particular extension.
There is also a bug when using beryl with Xorg 7.1.1 with the open source drivers that do support this extension. For some reason, beryl is unable to see this extension, and the water effects are disabled. This has been fixed in Xorg 7.2.
* Why can't I get direct rendering when using beryl.
If you're using XGL, this is expected behaviour. XGL does not provide Direct Rendering (though it does require direct rendering on the non-XGL server in order to work properly). Depending on how your X server is setup, you may still be able to use the non-XGL server in order to run OpenGL applications with direct rendering (usually by doing something like 'DISPLAY=:0 doom3').
* Why are OpenGL applications so slow under beryl.
Beryl (and Xgl) use a lot of GPU resources. This may have a significant impact on other OpenGL applications.
* When I use beryl+AIGLX, play a video file, and move the window for the video, the window moves but it is black till I finish moving the video. Then the content of the video continues to play in the new location of the window. Why won't the video content move with the window?
I believe this is due to the fact that the X server is not processing the video. Instead, it's getting written directly to the location of the window by the video card. Till you actually release the window, the video card still believes that the window is located in the original position. I have found that, with mplayer, using the x11 video output device with the -zoom option works very well.
* When I launch beryl, I get 'Xlib: extension "GLX" missing on display ":0.0"'
Make sure you have the following line in the Module section of your xorg.conf file:
Load "glx"
If you have that, and you are using the drivers from nvidia, please make sure that your xorg.conf file is actually setup to use the 'nvidia' driver rather than the 'nv' driver. There should be a line in your Xorg.0.log file that says '(II) Module nvidia: vendor="NVIDIA Corporation"'
* I've upgraded to Feisty, I'm using XGL, and now beryl won't work for me.
For some reason, the beryl maintainer for Feisty decided not to included the beryl-xgl binary in their beryl-core package in the universe repository. If you are using the fglrx drivers, you can get beryl to load, however, by doing the following in a terminal:
$ LD_PRELOAD=/usr/lib/fglrx/libGL.so.1.2.xlibmesa beryl --replace &
Likewise, with the nvidia drivers, there is a similar /usr/lib/nvidia/libGL* file which you can preload.
You can then put this into a script called /usr/bin/beryl-xgl (which you will also need to make executable). The script would be:
#!/bin/sh
LD_PRELOAD=/usr/lib/fglrx/libGL.so.1.2.xlibmesa beryl $@ &
You can also switch to the ubuntu.beryl-project.org repository. It is:
deb http://ubuntu.beryl-project.org feisty main
deb-src http://ubuntu.beryl-project.org feisty main
This is version 0.2.0 instead of 0.2.1 (which is what is available in the Feisty universe repo), but there is no difference between the two.
* How do I know what version I'm using? My splash screen says I'm using 0.2.0 rc3, but I think I have 0.2.0 or 0.2.1 installed.
The splash screen was not updated. You can find out the correct version by typing 'beryl --version' in a terminal.
* I've tried everything, but beryl won't work.
Please check the Troubleshooting section of the beryl wiki to see if you can locate your problem and a possible fix (http://wiki.beryl-project.org/wiki/Main_Page). If you are unable to find information to resolve your problem, please post your full /var/log/Xorg.0.log file and the output from 'beryl --replace &'. When asking for help, be as specific about your problem as possible (ie. "Help, beryl won't work. What do I do?" is not going to help us help you). Please also let us know what, if anything, you've already tried.
I'd like to thank any number of individuals who have suggested questions for this document, provided answers, or simply hung out on #beryl and provided help to those who need it (coz and crdlb come to mind :-) ).
I wouldn't mind seeing this stickied, if a moderator thinks it's really helpful.
A HTML version of this document can be found at http://68.45.180.45/Unofficial_Beryl_FAQ2.html
* What do I need to run beryl?
For nVidia, you should always use the latest drivers from nvidia.com. Any drivers in the 1.0-9*** range will provide Composite. GLX_EXT_texture_from_pixmap is supported in those 9*** releases via direct rendering and AIGLX (you are free to use AIGLX if you like, though it is unnecessary). For GeForce FX cards and up, the latest drivers currently available are 1.0-9755. For earlier cards, please check with the README for legacy driver release 1.0-9631 (http://us.download.nvidia.com/XFree86/L ... dix-a.html) to see if your card is supported by that release. If your card is only supported by the other legacy driver (1.0-7184) you will have to use download and configure XGL to get beryl to run. Please note, however, that I have yet to hear from anyone with such a card who has managed to get beryl working.
For first and second generation Radeon cards (radeon 7000 through radeon 9250), you will need to use the open source 2D/3D drivers (which should have been installed by your distribution), and at least Xorg 7.1.1 with AIGLX and Composite enabled (keeping reading this FAQ to see how to configure xorg for Composite and AIGLX).
For 3rd and 4th generation radeon cards (radeon 9550 through the X850), you can either use the fglrx driver from ATI (the latest is 8.35.5 available here: http://ati.amd.com/support/drivers/linu ... adeon.html ) or you can use the open source driver with AIGLX. Though the Xpress 200 chipset is supported by the 2D open source driver, the open source 3D driver is not supported due to a lack of information on the memory controller. As a result, you must use fglrx + XGL on the Xpress chipsets.
For 5th and 6th generation radeon cards, you must use fglrx + XGL.
For Intel cards, you will need to use the open source drivers from Xorg 7.1.1 (or newer) and have Composite and AIGLX enabled in your xorg.conf file.
In all cases, Xorg 7.1 or higher is recommended.
* What is XGL?
XGL is an X server that is rendered via your video cards OpenGL drivers. On some cards, where Composite and the GLX_EXT_texture_from_pixmap opengl extension are not supported by your 3D drivers, XGL is the only way to use beryl and/or compiz. XGL will provide all the necessary extensions required by beryl. It first requires that you have your 3D drivers already setup and working with a normal non-XGL server. You must have Direct Rendering already working for XGL and beryl to work properly together. The setup and configuration of XGL varies from distribution to distribution. With Ubuntu/Edgy, for example, you must create an Xgl.desktop file under /usr/share/xsessions. This file will contain an Exec line (among others) that points to a script which will first launch the XGL server (usually as display :1) and then launch gnome/kde/xfce4 on that particular server. When you login to your system via the display manager (gdm, kdm, etc.), you will select the Xgl session, and this session will launch the XGL server and then your desktop environment. Please read http://en.wikipedia.org/wiki/XGL for more information about XGL. To setup XGL on your machine, you will have to locate the XGL package from your distribution, and read any provided documentation on howto set up the XGL server.
At the present moment, XGL is required for any ATI radeon card unsupported by the open source 3D drivers (so any fifth or sixth generation radeon card). Various other cards that have 3D drivers but don't support the GLX_EXT_texture_from_pixmap extension will also require XGL.
* What is AIGLX?
AIGLX is an acronym for Accelerated Indirect GLX. It adds hardware accelerated indirect GLX rendering capabilities to the Xorg and DRI drivers. Remote opengl clients can now be fully hardware accelerated over the GLX protocol (previously, this was not possible with the open source drivers). This also allowed for the inclusion of the GLX_EXT_texture_from_pixmap opengl extension, a requirement for beryl and compiz. AIGLX is currently supported on the open source radeon and intel drivers included in Xorg 7.1.1 and up. Accelerated indirect rendering has been supported on the nvidia drivers since the beginning, but the GLX_EXT_texture_from_pixmap extension was not added to the nvidia drivers till 1.0-9625. Please read http://en.wikipedia.org/wiki/Aiglx for more information.
* How do I configure Xorg to enable AIGLX and Composite?
Make sure you have these three lines in your xorg.conf file:
Section "Extensions"
Option "Composite" "True"
EndSection
In the ServerLayout section of your xorg.conf file, make sure you have:
Option "AIGLX" "true"
* I have beryl installed, but when I select beryl from the beryl icon in my system tray, nothing happens (or my current window manager vanishes). What's wrong?
Bring up a terminal and run:
$ beryl --replace &
beryl will run a series of tests and, if they all pass, it will attempt to launch itself. If it fails, make sure you are prepared to paste the output from that command when you ask for help.
* I think I have everything setup properly, but I get an error message saying:
Checking for XComposite extension : failed
If you're using any of the open source drivers, or if you're using the nvidia drivers, make sure you have Composite enabled in your xorg.conf file. If you're using the fglrx drivers from ATI, you must disable Composite in order to allow Direct Rendering. You must then download and configure XGL per your distributions instructions. If you're still think you have Composite setup properly in your config file, please post your full /var/log/Xorg.0.log file when asking for help.
* I'm using the latest nvidia drivers, and everything works fine for a while but suddenly new windows that pop up are all black.
There is a bug in the nvidia drivers that cause this to happen with the driver runs out of video memory. nvidia has acknowledged this driver bug, and is working on a fix. They have not yet given a time table for fixing this bug. In the mean time, you can try disabling various beryl plugins, or using XGL. There has been some discussion about this bug here: http://www.nvnews.net/vbulletin/showthread.php?t=84562
You can typically avoid this bug by using the copy rendering path or the AIGLX rendering platform
* I have no window deocorations (or window titles).
If you're using an nvidia card, make sure you are running at 24 bit color depth (DefaultDepth should be set to '24' in the Screen section of your xorg.conf file) and that you have the following line in either the Screen or Device section of your xorg.conf file:
Option "AddARGBGLXVisuals" "true"
You can do this with recent versions of the nvidia driver by bringing up a terminal and typing:
$ sudo nvidia-xconfig --add-argb-glx-visuals -d 24
If you do have your xorg.conf file setup properly, or your not using an nvidia card, try selecting "Reload Window Decorator" in the beryl manager icon in your system tray. If that fails, please try launching emerald (or aquamarine or heliodor) from a terminal with:
$ emerald --replace &
Check the error message and, if necessary, post it on the forums for help.
* What's the difference between heliodor, aquamarine, and emerald.
heliodor is a window decorator for beryl which uses metacity themes
aquamarine is a window decorator for beryl which uses kde themes.
emerald is a window decorator for beryl (the standard beryl decorator), which uses it's own themes.
* I have 0.2.0 or 0.2.1 installed. Where are the Desktop Wall and the Vidcap plugins?
It was not included in those releases. You will either need to download and compile bery from source or find packages for your distribution that includes that plugin.
* I'm hitting the keybinding for the water effects, but it's not working.
Your video card drivers must support pixel shaders. Specifically, the GL_ARB_fragment_program extension. Check 'glxinfo' for this particular extension.
There is also a bug when using beryl with Xorg 7.1.1 with the open source drivers that do support this extension. For some reason, beryl is unable to see this extension, and the water effects are disabled. This has been fixed in Xorg 7.2.
* Why can't I get direct rendering when using beryl.
If you're using XGL, this is expected behaviour. XGL does not provide Direct Rendering (though it does require direct rendering on the non-XGL server in order to work properly). Depending on how your X server is setup, you may still be able to use the non-XGL server in order to run OpenGL applications with direct rendering (usually by doing something like 'DISPLAY=:0 doom3').
* Why are OpenGL applications so slow under beryl.
Beryl (and Xgl) use a lot of GPU resources. This may have a significant impact on other OpenGL applications.
* When I use beryl+AIGLX, play a video file, and move the window for the video, the window moves but it is black till I finish moving the video. Then the content of the video continues to play in the new location of the window. Why won't the video content move with the window?
I believe this is due to the fact that the X server is not processing the video. Instead, it's getting written directly to the location of the window by the video card. Till you actually release the window, the video card still believes that the window is located in the original position. I have found that, with mplayer, using the x11 video output device with the -zoom option works very well.
* When I launch beryl, I get 'Xlib: extension "GLX" missing on display ":0.0"'
Make sure you have the following line in the Module section of your xorg.conf file:
Load "glx"
If you have that, and you are using the drivers from nvidia, please make sure that your xorg.conf file is actually setup to use the 'nvidia' driver rather than the 'nv' driver. There should be a line in your Xorg.0.log file that says '(II) Module nvidia: vendor="NVIDIA Corporation"'
* I've upgraded to Feisty, I'm using XGL, and now beryl won't work for me.
For some reason, the beryl maintainer for Feisty decided not to included the beryl-xgl binary in their beryl-core package in the universe repository. If you are using the fglrx drivers, you can get beryl to load, however, by doing the following in a terminal:
$ LD_PRELOAD=/usr/lib/fglrx/libGL.so.1.2.xlibmesa beryl --replace &
Likewise, with the nvidia drivers, there is a similar /usr/lib/nvidia/libGL* file which you can preload.
You can then put this into a script called /usr/bin/beryl-xgl (which you will also need to make executable). The script would be:
#!/bin/sh
LD_PRELOAD=/usr/lib/fglrx/libGL.so.1.2.xlibmesa beryl $@ &
You can also switch to the ubuntu.beryl-project.org repository. It is:
deb http://ubuntu.beryl-project.org feisty main
deb-src http://ubuntu.beryl-project.org feisty main
This is version 0.2.0 instead of 0.2.1 (which is what is available in the Feisty universe repo), but there is no difference between the two.
* How do I know what version I'm using? My splash screen says I'm using 0.2.0 rc3, but I think I have 0.2.0 or 0.2.1 installed.
The splash screen was not updated. You can find out the correct version by typing 'beryl --version' in a terminal.
* I've tried everything, but beryl won't work.
Please check the Troubleshooting section of the beryl wiki to see if you can locate your problem and a possible fix (http://wiki.beryl-project.org/wiki/Main_Page). If you are unable to find information to resolve your problem, please post your full /var/log/Xorg.0.log file and the output from 'beryl --replace &'. When asking for help, be as specific about your problem as possible (ie. "Help, beryl won't work. What do I do?" is not going to help us help you). Please also let us know what, if anything, you've already tried.