Version 1 (modified by, 10 years ago) (diff)



This is a proposal for unifying the various bits of scale and zoom logic for different WebKit ports - things in here are not necessarily true for every port at this time

This pages describes several of the scaling and zooming concepts in WebKit. The exact details and terminology differ from port to port, but some concepts are common.


  • CSS pixel - the unit '1px' in CSS, basis of most other CSS units of length. Also known as a layout pixel. Represented in WebCore by the LayoutUnit type.
  • Logical pixel - also known sometimes as "UI pixel" or "device-independent pixel".
  • Physical pixel - represents one unit of display on the physical display. Also known as device-dependent pixel.
  • CSS viewport - dimensions of the CSS initial containing block.
  • Virtual viewport - visible region of the screen when using zoom gestures.

Types of scales and zooms

WebKit supports (at least) the following types of zooms and scales:

Name Ratio Changes viewport size (in logical pixels) | Exposed directly to web content
Device Scale Physical pixel : Logical pixel No Yes - window.devicePixelRatio, CSS media queries
Page scale Logical pixel : CSS pixel No No
Page zoom Logical pixel : CSS pixel Yes No
Text zoom Specified font size : Actual font size No No
CSS/SVG scale transform Local coordinate space No Yes

Device scale

Device scale is a property of the physical display that the web content is being rendered into. This could be a monitor, projector, print media, etc. The device scale can change for a given Page, for instance if the window containing the Page is moved to a different monitor or if the user switches from using a monitor to using a projector. The device scale typically does not change as a result of the user interacting with the web page. When the device scale changes, a browser implementation may wish to re-rasterize the content at the new scale in order to render vector content more sharply. The size of the viewport and the layout of the page do not change if the device scale factor changes. Web pages may use window.devicePixelRatio and CSS media queries to provide different content, such as higher-resolution image assets, for high-DPI devices.

Page scale

Page scale is used to implement zooming gestures. This is typically done in conjunction with using a porthole/virtual viewport model where the viewport that the user sees is a subset of the viewport as exposed to the web page. Page scale effects the virtual viewport, not the CSS viewport, so layout is generally speaking not impacted by a changing page scale. Fixed position elements are an exception to this - they are often rooted to the virtual viewport and not the CSS viewport. This behavior is not well defined and there are many behavior differences between different ports.

Page zoom

Page zoom is used to implement browser zoom functionality present in many desktop browsers. A page zoom factor of 120% means that one CSS pixel occupies 1.2 logical/UI pixels. Changing the page zoom factor typically does not change the logical size of the viewport, meaning that with a page zoom greater than one the viewport is effectively smaller in terms of CSS pixels. Because of this, changing the page zoom factor typically changes the layout of a page significantly.

Text zoom

Text zoom is also used to implement browser zoom functionality, either in conjunction with or instead of page zoom. The text zoom factor modifies the actual text size used on the page.

CSS / SVG scale transforms

CSS and SVG both expose transform functionality that can cause parts of the page to be scaled.