Platform/GFX/Quantum Render

What is it

The goal of the Quantum Render project is to take the WebRender compositor in Servo and embed it in Firefox. It will replace Gecko's existing compositor, interfacing with Gecko's main-thread layout code. As WebRender is written in Rust and uses a very different design approach, we expect to get stability and performance benefits from this switch.

Vital stats

Canonical code repository: https://hg.mozilla.org/projects/graphics
Git mirror: https://github.com/mozilla/gecko-projects/tree/graphics
TreeHerder: https://treeherder.mozilla.org/#/jobs?repo=graphics
Bugzilla Component: Core :: Graphics: WebRender
Tracking metabug: bug 1311790
Mailing list: dev-tech-gfx@lists.mozilla.org
IRC channel: #gfx
Project owner: Milan Srekovic

Getting the code

Using mercurial

To clone the repo from scratch, run this:

 hg clone https://hg.mozilla.org/projects/graphics

Or if you have an existing mozilla repo, add this to your .hgrc file:

 [paths]
 graphics = ssh://hg.mozilla.org/projects/graphics/

and pull using `hg pull graphics`

Using git

See the README at https://github.com/mozilla/gecko-projects, use "graphics" as the BRANCH

Build instructions

Once you have the code, see the README.webrender file in the root directory for build instructions. This can also be seen online at https://hg.mozilla.org/projects/graphics/file/tip/README.webrender

Understanding the code

A good overview of WebRender and what it is can be found in this blog post.

If you are familiar with the way Gecko normally works, the Quantum Render changes should be relatively straightforward. Instead of using a ClientLayerManager, we create a WebRenderLayerManager instance. This layer manager creates its own layer instances, and when those layers have their Render() function called, they generate WebRender-specific commands. These commands are sent over the PWebRenderBridge IPDL channel, which is conceptually similar to PLayerTransaction in Gecko. The commands are received in WebRenderBridgeParent which interprets the messages, and talks to the core WebRender library using the API in webrender.h. The API is implemented in the webrender_bindings crate, which is written in Rust.

Committing changes

The process for making changes is very similar to that for integration branches like inbound. File a bug in the WebRender component, attach patches, get review, push to the graphics repo. However, we also allow using an "accelerated" workflow which allows us to move faster by commiting first and getting review afterwards. This is done using a Phabricator instance to track unreviewed commits. See the sections below on setting up an account on Phabricator. Commits that require post-landing review must be committed with the special syntax "r=gfx?". This will allow any graphics team member to do the review. If you would like to get a review from a specific individual (and try to avoid this as much as possible) you can use their nick instead of "gfx" (e.g. "r=kats?" to get review from kats).

Create a Phabricator account

Go to https://gfx.tacowolf.com and sign up with your @mozilla.com address. (Currently having a mozilla.com address is a requirement, but if you don't have one and wish to contribute to the project contact us in #gfx and we can relax this requirement.)

Once you have an account, please add yourself to the "Graphics Team" group. You can do this by going to the Graphics Team object page, clicking on the "View All" button in the Members panel on the right-hand side, and using the link in the right-hand panel to join the group.

To avoid getting unnecessary notification emails, it's a good idea to go the settings page, go to your personal settings, and under the "Email Delivery" section, change the "Self Actions" option to "Disable Self Action Mail".

Create a herald rule for post-commit reviews

There is a rule set up so that any commits that contain r=gfx? in the commit message will automatically get flagged for audit by anybody in the graphics team. In addition to this, you should set up an individual rule for yourself. You can do this as follows:

• On the main phabricator page, click on "Applications" in the left navbar, then go to the "Herald" aplication
• Click on "Create Herald Rule"
• Pick "Commits" and continue
• Pick "Personal" and continue
• Give the rule a name like "my reviews", set the condition to be when "commit message" "contains" "r=mynick?" (replace mynick with your nick), and set the action to "Add me as an auditor"
• Save the rule

You can modify the condition accordingly if you have multiple nicks that people might use when flagging you as a reviewer.

Doing audits

If you go to the phabricator main page and click on "audits" on the left navbar, you will see the audits for which you or Graphics Team are an auditor. You should review these things, assuming you didn't author the patch.

When auditing, you can enter comments by clicking on the line number, and final comments in the "Creative Accounting" box at the bottom of the page. For granting r+, select "Accept Commit" as the action from the dropdown. You can also add specific people as auditors, etc.

Sheriffing

Currently the graphics repo is self-managed - that is, the graphics team members are responsible for doing their own sheriffing, backing out of commits, merges, etc. Currently the graphics branch is NOT being merged to m-c; however, we are regularly merging from m-c to the graphics branch (see section below). In particular this means that QuantumRender-specific changes should land on the graphics branch and not on other integration branches.

We do have a pulsebot instance watching commits to the graphics repo, and it will automatically close the associated bug with a comment pointing to the commits. It will also report commits to #gfx.

Merging from mozilla-central

The following commands (on a m-c mercurial clone which has the graphics repo as an additional upstream path) will do a merge from m-c:

  hg update graphics       # switch to graphics branch
  hg pull -u graphics      # get latest graphics changesets
  hg pull central          # get latest m-c changesets
  hg merge central         # perform a merge. you may get prompted to resolve conflicts in this step
  hg commit -m "Merge m-c to graphics"  # commit the merge
  mach build               # ensure that the merge builds properly
  hg push graphics -r tip  # push the merge

Automation

The graphics branch currently runs all the usual tests (i.e. jobs that are run on mozilla-central) on each push. In addition, it also runs some new jobs specific to the Quantum Render code. Specifically, it runs 64-bit build jobs with --enable-webrender set, for Linux, OS X, and Windows. Both debug and opt builds are created. These can be seen on the graphics TreeHerder page in their own rows labelled with "qr" or "QuantumRender". The Linux QR builds also runs some reftest jobs - see the next section for details on this.

Reftests

Many of the existing gecko reftests (over 13000 of them) are passing with Quantum Render. However, there are still around 700 failing reftests. These are listed in this Google sheet. You're welcome to work on getting these passing - please follow the procedure below:

• Identify a single reftest you wish to work on. Try to pick one that sounds unrelated to other reftests that people are working on, because often one patch will fix multiple related reftests.
• File a bug for that reftest, and mark it as blocking bug 1322815 (webrender-reftests).
• Update the Google sheet with the bug number and your name.
• Work on the fix. The best way to do this is to remove the fails-if or skip-if annotation in your local checkout and run the reftest. Debug and fix as needed. Note that you can likely work on the bug on Windows/OS X locally, but we only run the tests on Linux in automation. So for best results, prefer working on Linux locally when possible.
• If you need to do try pushes, use syntax "try: -b do -p linux64-qr -u all[linux64-qr] -t none". You should do at least one try push after writing your fix to verify it works in automation, as well as to identify any other tests that are fixed by your patch. Make sure to update the annotations for all newly-passing tests as part of your final commit. Try not to introduce regressions, although breaking a small number of tests to make a larger number pass might be acceptable.
• Land your fix with pre- or post-review as appropriate.

Further reading

There is more information at the following locations:

• https://public.etherpad-mozilla.org/p/gfx