mapbox/mapbox-gl-js

Make "devicePixelRatio" user-configurable

Open

#1953 opened on Jan 20, 2016

View on GitHub
 (15 comments) (14 reactions) (0 assignees)JavaScript (10,532 stars) (2,203 forks)batch import
feature :green_apple:good first issueperformance :zap:

Description

Hey,

Summary:

On (mobile) devices with very high ppi, render at a lower resolution than the device's native ppi and upscale it.

Long story:

Mapbox-gl-js fares very well on iOS devices performance wise (with #1606).

The story is a bit different on Android devices.

The most interesting findings we've had so far is that a Samsung Galaxy S3 (Released March 2013) is roughly 10% slower FPS wise than a Samsung Galaxy S6 (Released Q2 2015) under similar circumstances.

The GL draw calls take roughly equal time on the S3 and S6, despite a much faster CPU and GPU on the S6. The reason for the S6's lack of performance over the S3 seems to be the newer device's PPI. The S6 has a PPI of 577 vs 306 for the S3, and as a ref, 326 for iPhone 6.

This pattern repeats itself for almost all new Android devices, and the race is still going to 800 ppi and beyond. Android screen resolution is often 'unnecessary' high, which in turn leads to poor web-gl performance.

It is possible to downscale the rendering of mapbox-gl-js in html/css without touching the internal js code, but it also requires highjacking the touch / mouse handlers and scale down symbols and text in the style to make it work properly. We're following this approach, and do downscaling to an effective 326 ppi on any device with a higher native ppi. In the case of the S6, we're seeing an effective 3.5x increase in performance without any notices from users.

This workaround is probably outside the scope of your average mapbox-gl-js user. For gl-js not to be a performance hog on mobile (android) devices by default, device PPI should probably be handled.

Contributor guide

Tech stack
javascript
Domain
performancefrontend
Issue type
feature
DifficultyEstimated implementation difficulty for a new contributor, from 1 for very small changes to 5 for expert-level work.
4
Estimated timeA rough time range for an experienced contributor to investigate, implement, test, and prepare a pull request.
over 1 week
Activity statusHow available the issue appears right now: fresh, active, stale, blocked, or waiting on maintainer input.
stale
ClarityHow clearly the issue explains the expected change, acceptance criteria, and next step.
mostly clear
Prerequisites
Familiarity with mapbox gl js codebaseUnderstanding of devicePixelRatioWebGL basics
Newbie friendlinessA 1-100 score estimating how approachable this issue is for first-time contributors.
15
Research direction
The issue requests making devicePixelRatio user configurable to improve performance on high PPI Android devices. Currently, mapbox gl js uses window.devicePixelRatio to set the canvas resolution. Research how this value is used in the rendering pipeline, e.g., in src/render/ or src/source/ files. Look at issue #1606 for related performance improvements. The proposed solution could involve adding an option to override devicePixelRatio with a user provided value, similar to how other options are passed to the Map constructor. The workaround described involves CSS scaling and touch handler adjustments, which could serve as a reference for implementation.