Fennec/NativeUI/Viewport

Viewport handling

Definitions

The list of viewport properties are as follows, along with the coordinate system they are represented in Java.

• offset - This is the x and y in device pixels of the pixel in the top-left corner of the user-visible display (in this case device pixels is the same as zoom-multiplied CSS pixels, and so the x and y will grow as the user zooms).
• size - This is the width and height in device pixels of the user-visible display area, and is unaffected by zooming.
• zoom - This is the zoom factor at which the page is shown to the user (> 1.0 means page elements are rendered large).
• page size - This is the width and height in device pixels of the content (as with offset, this will grow as the user zooms because it is CSS pixels multiplied by zoom).
• display port margins - This is the left, top, right, and bottom margins in device pixels around the user-visible display that we should paint as a buffer. These are in device pixels and are unaffected by zooming.

Documents are defined as follows:

• The "content document" of a tab refers to the document attached to the content window of that tab.
• The "displayed document" of a tab refers to the document to which user-visible content of a tab belongs. This may be different from the content document during page load, and we assume that there is no upper bound on how long they are different for.
• The "active tab" refers to the XUL browser element that is topmost in the browser.xul deck.
• The "browser content document" refers to the content document of the active tab.
• The "browser displayed document" refers to the document that is currently visible to the user. This may be different from the displayed document of the active tab during tab switch, and we assume that there is no upper bound on how long they are different for.

Threads

• The gecko thread. Gecko runs on this thread, as does anything in browser.js. "Messages" sent from browser.js to Java are synchronous JNI calls and also run on the gecko thread.
• The Java UI thread. Java receives UI events on this thread. When this results in messages to Gecko, those messages are queued on the Gecko event queue and handled asynchronously on the Gecko thread.
• The compositor thread. The compositor runs on this thread. This thread can make JNI calls to Java which will also run on the compositor thread.

Rules

• Java must maintain one set of properties (offset, size, zoom, page size, and display port margins). The compositor must query this metrics object on every frame.
• When the browser displayed document changes (e.g. tab switch, page load), java must be told of updated viewport properties (offset, zoom, page size) via the compositor when the first frame of the new content is composited.
• When the composition-related properties (offset, zoom, page size) of the selected tab change without the document changing, java must be told synchronously from browser.js.
• When the user performs pan/zoom actions, Java should send updated properties (offset, zoom, display port margins) to browser.js. (These may be throttled, such as when we know the newly visible area is still inside the previously-painted region, or in the middle of a pinch zoom.)
• browser.js must ignore viewport-dependent events (including clicks, double-taps, and viewport updates) from java during the period where the browser content document is different from the browser displayed document. Java may still update its own viewport properties for the compositor's benefit.
• If the viewport size changes, Java must first send a resize notification. browser.js must, upon processing the resize, synchronously notify Java of receiving this event, along with any updated properties (offset, zoom, page size). While processing this event (still on the gecko thread), Java may recalculate properties (offset, zoom, display port margins) and must queue an event back on the gecko thread with the new properties. Drawing must be suppressed between the handling of the initial resize notification and handling of the final property update event.

Implementation Assertions

• The firstPaint flag on the presShell is set by browser.js if and only if the next draw will be of a different document than the previous draw was. It is cleared as close to the composition of that draw as possible.