Platform/GFX/APZ

Introduction

The Async Pan/Zoom module (APZ)¹ is a platform component that allows panning and zooming to be performed asynchronously (on the compositor thread rather than the main thead).

For zooming, this means that the APZ reacts to a pinch gesture immediately and instructs the compositor to scale the already-rendered layers at whatever resolution they have been rendered (so e.g. text becomes more blurry as you zoom in), and meanwhile sends a request to Gecko to re-render the content at a new resolution (with sharp text and all).

For panning, this means that the APZ asks Gecko to render a portion of a scrollable layer, called the "display port", that's larger than the visible portion. It then reacts to a pan gesture immediately, asking the compositor to render a different portion of the displayport (or, if the displayport is not large enough to cover the new visible region, then nothing in the portions it doesn't cover), and meanwhile sends a request to Gecko to render a new displayport. (The displayport can also be used when zooming out causes more content of a scrollable layer to be shown than before.)

_{1. This module used to be called Async Pan/Zoom Controller (APZC), but this was changed to avoid confusion because there is a class called AsyncPanZoomController of which there are now multiple instances.}

Supported platforms

The APZ module is currently enabled on B2G and Metro. Fennec has a Java implementation of asynchronous panning and zooming, but the plan is to port Fennec to use the APZ module as well.

The APZ module relies on OMTC, so a prerequisite for porting it to a platform is for OMTC to work on that platform.

AsyncPanZoomControllers

Inside the APZ module, every scrollable layer has an AsyncPanZoomController (APZC). Scrollable layers roughly correspond to the root document, documents in iframes, and overflow:scroll divs. See OMTC for more information about layers.

The APZCs are arranged in a tree whose structure reflects the structure of the layer tree containing the layers that they correspond to, except that the APZC tree only has nodes for scrollable layers, while the layer tree has nodes for all layers. The APZC tree is managed by a class called APZCTreeManager. The APZCTreeManager is the interface through which the outside world interacts with the APZ module - there is no access to the APZCs directly, but the APZCTreeManage provides methods that operate on a specific APZC in the tree.

Interactions with other components

The APZ interacts with the following other platform components:

Widget code

The widget code is a platform-specific component of a browser implementation that interfaces with the native widget implementation. It corresponds roughly to the following pieces of code:

• On B2G: RenderFrameParent/RenderFrameChild and TabParent/TabChild
• On Metro: MetroWidget and MetroInput
• On Fennec (which doesn't use the APZ yet): GeckoAppShell and GeckoLayerClient, which communicate with native code via the AndroidBridge.

The widget code interacts with the APZ in the following ways:

Gecko

GeckoContentController

Main APZ projects on the horizon

• Make APZ work well for Metro - bug 886321
• Implement support for Fennec-like dynamic toolbar on B2G - bug 860812
• Improve hit detection for the different touch-sensitive regions - bug 928833
• Switch Fennec over from the Java version to the C++ APZ - bug 776030