WebRender in Firefox

The process of updating WebRender

This process 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 it 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.