WebRender in Firefox

The process of updating WebRender

The process of updating WebRender is described in README.webrender in mozilla-central.

Create a YAML testcase from an HTML testcase as rendered in Firefox

There is an environment variable for Firefox called ENABLE_WR_RECORDING which will cause Firefox to create binary recording files in the directory that you started Firefox from. These binary recordings can be converted into YAML frames using wrench.

1. Start Firefox with ENABLE_WR_RECORDING=1, e.g.

   $ ENABLE_WR_RECORDING=1 mach run -P your-firefox-profile-that-has-webrender-enabled

2. Open the website or testcase that you're interested in.
3. Close Firefox.
4. Locate the binary recording file. There's one per window, the filename has the pattern wr-record-<window number>.bin.
5. Go to your clone of the webrender repository, or create a clone of it if you don't have one.
6. Check out the revision of webrender that your Firefox is based on. This revision is recorded in the last line of gfx/doc/README.webrender in your Firefox checkout. (This is necessary because the binary recording format is unstable.)
7. Go to the wrench directory in your webrender checkout, and run the following command:

   $ cargo run --release -- --save yaml replay /path/to/wr-record-1.bin

8. This might take a few minutes to compile.
9. A window will open, and it will display the contents of the Firefox window that was recorded.
10. Press the right arrow key until you see the frame that you're interested in. You can step forwards and backwards using the arrow keys (stepping backwards will show a warning).
11. Press the escape key in order to close the wrench viewer, or step forwards until the end of the recording and watch wrench panic.
12. Now there is a directory called yaml_frames inside the wrench directory that you're in. The yaml_frames directory contains one frame-<framenumber>.yml file per frame, and a res directory which contains image and font files.
13. You can display just the frame that you care about using

    $ cargo run --release -- show yaml_frames/frame-14.yaml

14. If the frame is rendered with the wrong scale, try passing -p 1 or -p 2 to the command, e.g.

    $ cargo run --release -- -p 1 show yaml_frames/frame-14.yaml

Gather the resource files for one specific frame

If you've followed the steps above, and you end up with a YAML testcase that requires external resources (fonts or images), you may want to create a zip file that contains the YAML file along with just the required resources. You could go through the YAML by hand and find out which resource files you need, but there's a slightly easier way using the --list-resources argument of the show command:

$ cargo run --release -- show --list-resources yaml_frames/frame-14.yaml

This will dump out the names of required external resource files to the console. Now you can do some more manual work to actually copy those files over to a separate directory which you then zip up.

It would be nice to have a command that automatically creates such a packaged zip file for a given frame, but such a command doesn't exist yet.

Test shader changes in Firefox without recompiling

Firefox supports an environment variable called WR_RESOURCE_PATH which can be set to a path.

This allows easier testing of shader changes. If you point this environment variable at your gfx/webrender/res/ directory, the shaders will be read from that directory when Firefox is launched, so you can test shader changes just by restarting Firefox and don't need to recompile.

Create a Capture of Firefox

TL;DR:

• CTRL+SHIFT+3
• wrench load path/to/wr-capture (which should have been dropped in your working directory)

Captures are a more complete replayable dump of WebRender's state than a recording. They include the current "scene", which is the complete tree of display lists for the window (in RON); and the current "frame", which is a dump of WebRender's backend state when rendering that scene. The significance of this is that it makes it more likely to reproduce stateful bugs in WebRender.

To create a capture, simply press CTRL+SHIFT+3 in any Firefox running WebRender. It's recommended that you do this from an instance of Firefox that was launched from the terminal, as the dump will be placed in the current working directory, which may not be a writeable location if launched graphically.

If this works, you should see "Capturing WR state to: wr-capture" in your terminal, and a directory called wr-capture should now be in your working directory. The three most interesting files in this directory will be:

• scene-xxx-yyy.ron -- a captured scene (tree of display lists)
• frame-xxx-yyy.ron -- the frame for that scene (dump of backend state)
• wr.txt -- contains which version of WebRender produced the capture (git commit SHA)

There may be multiple scenes/frames if you had multiple windows open (these instructions will assume there's only one).

To replay the capture, checkout WebRender at the commit in wr.txt, and pass the wr-capture directory to wrench:

$ cd wrench
$ git checkout "$(cat path/to/wr-capture/wr.txt)"
$ cargo run --release -- load path/to/wr-capture/

By default, wrench will ignore the scene and skip directly to the frame. If you wish to make changes to the scene to reduce a bug (which is much easier than editing the frame), simply rename or delete the frame.ron so that wrench won't find it, at which point it will fallback to using the scene.ron file.

Use the WebRender Debugger

This section is mostly copied from webrender/debugger/README.md which may be more up to date

WebRender has a live web-based debugger!

In the Gecko source tree, open gfx/webrender_bindings/Cargo.toml in a text editor.

Add features = ['debugger'] to the end of the file (in the dependencies.webrender section).

Vendor the rust dependencies locally for the debugger (we don't want these committed to the repo): ./mach vendor rust

Now, build and run firefox as usual.

Finally, open your browser and open the debugger/index.html file found in the WebRender repo. Click Connect and the debugger will attempt to connect to WR via websocket.