How to help testing off-main-thread compositing
I have been asked several times on irc and Bugzilla about how to help getting off-main-thread compositing (OMTC) ready to be turned on by default (especially by Linux users). It is awesome to hear from such people and yes, you can help. This blog post is about reporting bugs for off-main-thread compositing, a feature that works very well on Firefox for Android and Firefox OS but is in development on Linux and Mac, and not yet started on Windows. On this specific topic, you can help us if you are using Linux or Mac. I will give informations about testing on Windows when the Windows implementation is ready, which should happen soon.
If you are asking “how can I help?”, it most likely means that you are not familiar with Firefox’s source code, and it is all right. We need a lot of testing. Since OMTC uses hardware acceleration, it is subject to driver bugs and problems can vary from one machine to another. We need people to test and give us feedbacks about their experience using OMTC:
- is it improving/regressing your user experience? In what ways?
- do you see rendering bugs when OMTC? If so, on which web pages?
- is it crashing?
- most likely the experience will be less smooth at this point, since we have not played with optimizing OMTC on desktop platforms yet. However if it turns out to be faster it’s worth.
Of course, it is also possible to help us by writing code, and some community members do help us this way, but this is not the topic of this post. If you’re interested you can check out https://wiki.mozilla.org/Platform/GFX/Contribute.
Setup a testing profile in Firefox nightly
OMTC is changing a lot, so we need feedbacks from people using nightly builds of Firefox (no need to build it from source, you can download Firefox Nightly from here: http://nightly.mozilla.org/ )
First, create a separate profile. A profile contains your preferences, and we are about to try experimental features, so you don’t want to break your default profile, so we will make sure you can try the fancy stuff without breaking your normal user experience.
open a terminal and go to the directory containing Firefox Nightly.
./firefox --no-remote -P
This will open the profile manager. from there you can create a new profile. You will have to give it a name, I will assume you named it “testing”, but if you give it a different name, just remember to put the name you choose in place of testing in the following instructions. Do not tick the “Don’t ask at startup” option because it would set it as your default profile which you don’t want until you are sure that it will not break.
We will now make sure that hardware acceleration is available by typing about:config in the address bar, and setting the following preferences to “true”:
Then create a new window by detaching a tab or pressing ctrl+n.
You should see one or two pink counters appear on the top left of every new window. The content of the counters is not interesting to us in this case, but the presence of the counter means that layers acceleration is enabled and used.
If the pink counter did not appear, it means that Firefox could not enable layers acceleration, which I think is pretty rare. At this point you can’t help us testing OMTC yet (until we implement OMTC on top of non-accelerated layers), sorry… But there may be other areas you can test and give us feedbacks on! You can connect to the #developers and/or #gfx channels at irc.mozilla.org with an irc client and tell us that you want to help testing new features, and I am sure someone will be thrilled to hear that!
Back to testing OMTC:
you just checked that layers acceleration works. It does. Sweet. Keep layers acceleration enabled and if you are on linux close Firefox.
Now there are two scenarios:
- you are using Linux:
you need to set an environment variable before running Nightly. This is the most annoying part. in your terminal, in the directory containing Firefox Nightly, type the following command:
start firefox again by entering in your terminal
./firefox --no-remote -p testing
- you are using OS X
- no need to set an environment vairable. start firefox with the testing profile by typing ./firefox –no-remote -p testing if you closed it, and set the preference layers.offmainthreadcomposition.enabled in about:config to “true”.
You are now running off-main-thread compositing \o/
Before you start playing around, also set to “true” the following preferences in about:config
The inital setup was a bit tedious but you will not have to repeat all the steps every time. all the options that you have set in about:config are stored in the testing profile, so you will not have to re do these steps.
If you are on linux you will, however, have to set the environment variable MOZ_USE_OMTC each time. I recommend not to place the command for the environment variable in your bashrc/zshrc/etc. because if your non-testing instances of Firefox see this environment variable, they will try to enable OMTC, and you don’t want to risk breaking your non-testing instances.
When you want to run your testing instance of firefox, run
./firefox --no-remote -p testing
from a terminal in the directory containing Firefox Nigthly.
Now let’s test.
Browse the web, use your browser like you normally would, think of whether your experience is better or worse than before, and what exactly is better or worse.
Report the bugs.
To report problems, please use https://bugzilla.mozilla.org
Create a bug in the product “Core” and the component Graphics: Layers.
In the “CC:” field, add “:nical, :BenWa, :bjacob” without the quotes, so that I, and a few others from the gfx team, receive notifications about the bug.
In the “Blocks:” field, put “722012″ without quotes, if you are using Linux, or “756601″ if you are using OS X. This will tell us that there is a dependency between OMTC Linux/Mac and the bug you found, maximizing the chances that we see your bug in the first place and that we will see it when we are looking for bugs related to OMTC.
When you fill in the description of the bug, try to give us as many informations as you can. We are interested in what OS you use, which version, what graphics card you have…
If you are on linux, type
in a terminal and copy-paste the result of this command in the description of the bug. glxinfo provides with informations about your graphics card, the version of its pilots and what are the capabilities of hardware acceleration on your machine, which is helpful for us to diagnose the problems.
Think of a bug in Bugzilla has anything that is misbehaving compared to the stable version of Firefox. If the page is not rendered correctly, or firefox is crashing, or some things like scrolling getting slow… Anything that represents a regression compared to stable Firefox is a bug for OMTC.
If you are familiar with tools like gdb, providing us with a backtrace of the crash if you find one is extremely helpful.
to run firefox inside gdb, you can type:
gdb --args ./firefox --no-remote -p testing
then type r and press enter.
If firefox crashes while running in gdb, you can get the backtrace by typing bt and pressing enter. Then you just have to copy-paste the backtrace in the description of the bug.
If you need help
I just wrote a lot of things in here, and it may be confusing. I don’t want to scare you away, so don’t hesitate to ask me questions on the #gfx irc channel at irc.mozilla.org. My nick name on irc is nical, and I’ll do my best to help you if I am around when you ask. Note that I also speak French, in case you are a French speaker and not at ease with conversing in English.
Thank you to all the people who have proposed to help us. The making of Firefox does not only involve only Mozilla’s staff. Firefox is the making of its entire community without which it would not nearly be as awesome as it is today.