W3cubDocs

/Web APIs

Ink API

Experimental: This is an experimental technology
Check the Browser compatibility table carefully before using this in production.

The Ink API allows browsers to directly make use of available OS-level compositors when drawing pen strokes in an inking app feature, thereby reducing latency and increasing performance.

Concepts and usage

Inking on the web refers to app features that involve using pointer events to draw a smooth pen stroke — for example, a drawing app or document signing feature.

Pointers events are usually sent first to the browser process, which then forwards these events to the JavaScript event loop to execute the associated handler functions and render the result in the app. The time delay between the start and finish of this process can be significant, resulting in latency between the user initiating drawing (for example, with a stylus or mouse), and the stroke showing up on the screen.

The Ink API significantly reduces this latency by allowing browsers to bypass the JavaScript event loop entirely. Where possible, browsers will pass such rendering instructions directly to OS-level compositors. If the underlying operating system does not have a specialized OS-level compositor to use for this purpose, browsers will use their own optimized rendering code. This is not as powerful as a compositor, but it still confers some improvements.

Note: Compositors are part of the rendering machinery that draws the UI to the screen in a browser or operating system. See Inside look at modern web browser (part 3) for some interesting insights into how a compositor functions inside a web browser.

The entry point is the Navigator.ink property, which returns an Ink object for the current document. The Ink.requestPresenter() method returns a Promise that fulfills with an InkPresenter object instance. This instructs the OS-level compositor to render ink strokes between pointer event dispatches in the next available frame in each case.

Interfaces

Ink

Provides access to InkPresenter objects for the application to use to render the strokes.

InkPresenter

Instructs the OS-level compositor to render ink strokes between pointer event dispatches.

Extensions to other interfaces

Navigator.ink Read only Experimental

Returns an Ink object for the current document.

Examples

Drawing an ink trail

In this example, we draw a trail onto a 2D canvas. Near the start of the code, we call Ink.requestPresenter(), passing it the canvas as the presentation area for it to take care of and storing the promise it returns in the presenter variable.

Later on, in the pointermove event listener, the new position of the trailhead is drawn onto the canvas each time the event fires. In addition, the InkPresenter object returned when the presenter promise fulfills has its updateInkTrailStartPoint() method invoked; this is passed:

  • The last trusted pointer event representing the rendering point for the current frame.
  • A style object containing color and diameter settings.

The result is that a delegated ink trail is drawn ahead of the default browser rendering on the app's behalf, in the specified style, until the next time it receives a pointermove event.

HTML

html

<canvas id="canvas"></canvas>
<div id="div">Delegated ink trail should match the color of this div.</div>

CSS

css

div {
  background-color: rgba(0, 255, 0, 1);
  position: fixed;
  top: 1rem;
  left: 1rem;
}

JavaScript

js

const ctx = canvas.getContext("2d");
const presenter = navigator.ink.requestPresenter({ presentationArea: canvas });
let move_cnt = 0;
let style = { color: "rgba(0, 255, 0, 1)", diameter: 10 };

function getRandomInt(min, max) {
  min = Math.ceil(min);
  max = Math.floor(max);
  return Math.floor(Math.random() * (max - min + 1)) + min;
}

canvas.addEventListener("pointermove", async (evt) => {
  const pointSize = 10;
  ctx.fillStyle = style.color;
  ctx.fillRect(evt.pageX, evt.pageY, pointSize, pointSize);
  if (move_cnt == 20) {
    const r = getRandomInt(0, 255);
    const g = getRandomInt(0, 255);
    const b = getRandomInt(0, 255);

    style = { color: `rgba(${r}, ${g}, ${b}, 1)`, diameter: 10 };
    move_cnt = 0;
    document.getElementById(
      "div",
    ).style.backgroundColor = `rgba(${r}, ${g}, ${b}, 0.6)`;
  }
  move_cnt += 1;
  await presenter.updateInkTrailStartPoint(evt, style);
});

window.addEventListener("pointerdown", () => {
  ctx.clearRect(0, 0, ctx.canvas.width, ctx.canvas.height);
});

canvas.width = window.innerWidth;
canvas.height = window.innerHeight;

Result

Specifications

Specification
Ink API
# ink-interface

Browser compatibility

Desktop Mobile
Chrome Edge Firefox Internet Explorer Opera Safari WebView Android Chrome Android Firefox for Android Opera Android Safari on IOS Samsung Internet
Ink_API 94 93 No No 80 No 94 94 No 66 No 17.0
requestPresenter 94 93 No No 80 No 94 94 No 66 No 17.0

See also

© 2005–2023 MDN contributors.
Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later.
https://developer.mozilla.org/en-US/docs/Web/API/Ink_API