HandlingHighDPI

Handling High DPI (Retina) displays in WebGL

There are an increasing number of devices on the market that have displays with very high pixel densities (DPI), such as the Macbook Pro with Retina display. WebGL applications can take advantage of the higher resolution these devices provide but doing so requires some code changes to the application itself. Fortunately these changes are minor and generally non-disruptive, which makes it easy to prepare your WebGL code for these new devices.

You can see a demo highlighting the difference accounting for High DPI displays can make at this location. (The two meshes will only appear different on a high DPI display.)

Resizing the Canvas

It's important to note that canvas elements, like most graphics elements, have 2 sizes.

• the size they are displayed in the page
• the size of their content

For a canvas element, the size of the content or drawingBuffer is determined by the width and height attributes of the canvas. The display size is determined by the CSS attributes applied to the canvas. For example:

<canvas width="111" height="222" style="width: 333px; height: 444px;"></canvas>

Defines a canvas that has a drawingBuffer, its content, of size 111x222 pixels but is displayed at 333x444 CSS pixels.

On High DPI displays browsers will automatically upscale the canvas content to ensure that it appears the right size on screen. In the case of WebGL content, this causes the canvas to render at its usual resolution and then upscale to fit the canvas's display size. The practical effect of this is that an unmodified WebGL application may appear to be rendering at a lower-than-native resolution, which can introduce aliasing.

To find out what size the canvas is being displayed at in device pixels, you can use a ResizeObserver.

<style>
 #theCanvas {
    width: 50%;
    height: 50%;
}
<style>
<canvas id="theCanvas"></canvas>
<script>

function main() {
  const canvas = document.getElementById("theCanvas");
  const observer = new ResizeObserver(resizeTheCanvasToDisplaySize)
  observer.observe(canvas);

  function resizeTheCanvasToDisplaySize(entries) {
    cont entry = entries[0];
    let width;
    let height;
    if (entry.devicePixelContentBoxSize) {
      width = entry.devicePixelContentBoxSize[0].inlineSize;
      height = entry.devicePixelContentBoxSize[0].blockSize;
    } else if (entry.contentBoxSize) {
      // fallback for Safari that will not always be correct
      width = Math.round(entry.contentBoxSize[0].inlineSize * devicePixelRatio);
      height = Math.round(entry.contentBoxSize[0].blockSize * devicePixelRatio);
    }
    canvas.width = width;
    canvas.height = height;
  }
</script>

Handling Input

It's important to note that even though the resolution of the canvas has increased other values provided by the DOM will not adjust accordingly. A good example is mouse or touch input. Coordinates are still delivered in terms of CSS pixels, and thus must be transformed if you need them to line up exactly with the resized canvas pixels. You also need to keep in mind that the canvas position will still be reported in CSS pixels, so adjustments to account for element offsets should not use the devicePixelRatio.

canvas.addEventListener("mousemove", function(e) {
   const canvasX = e.offsetX * canvas.width / canvas.offsetWidth;
   const canvasY = e.offsetY * canvas.height / canvas.offsetHeight;
   // Perform some operation with the transformed coordinates
}, false);

Rationale

Why doesn't the browser automatically make the drawingBuffer the size needed so that 1 pixel in the drawingBuffer equals 1 pixel displayed? The reason is the WebGL API has several features which are always in device pixels. If the browser automatically created a drawingBuffer of a different size than requested many programs would break.

Examples include but are not limited to lineWidth, scissor, viewport, gl_PointSize, gl_FragCoord, copyTexImage2D, and copyTexSubImage2D.