path: root/devtools/server/actors/highlighters/utils/canvas.js

/* This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */

"use strict";

const {
  apply,
  getNodeTransformationMatrix,
  getWritingModeMatrix,
  identity,
  isIdentity,
  multiply,
  scale,
  translate,
} = require("resource://devtools/shared/layout/dom-matrix-2d.js");
const {
  getCurrentZoom,
  getViewportDimensions,
} = require("resource://devtools/shared/layout/utils.js");
const {
  getComputedStyle,
} = require("resource://devtools/server/actors/highlighters/utils/markup.js");

// A set of utility functions for highlighters that render their content to a <canvas>
// element.

// We create a <canvas> element that has always 4096x4096 physical pixels, to displays
// our grid's overlay.
// Then, we move the element around when needed, to give the perception that it always
// covers the screen (See bug 1345434).
//
// This canvas size value is the safest we can use because most GPUs can handle it.
// It's also far from the maximum canvas memory allocation limit (4096x4096x4 is
// 67.108.864 bytes, where the limit is 500.000.000 bytes, see
// gfx_max_alloc_size in modules/libpref/init/StaticPrefList.yaml.
//
// Note:
// Once bug 1232491 lands, we could try to refactor this code to use the values from
// the displayport API instead.
//
// Using a fixed value should also solve bug 1348293.
const CANVAS_SIZE = 4096;

// The default color used for the canvas' font, fill and stroke colors.
const DEFAULT_COLOR = "#9400FF";

/**
 * Draws a rect to the context given and applies a transformation matrix if passed.
 * The coordinates are the start and end points of the rectangle's diagonal.
 *
 * @param  {CanvasRenderingContext2D} ctx
 *         The 2D canvas context.
 * @param  {Number} x1
 *         The x-axis coordinate of the rectangle's diagonal start point.
 * @param  {Number} y1
 *         The y-axis coordinate of the rectangle's diagonal start point.
 * @param  {Number} x2
 *         The x-axis coordinate of the rectangle's diagonal end point.
 * @param  {Number} y2
 *         The y-axis coordinate of the rectangle's diagonal end point.
 * @param  {Array} [matrix=identity()]
 *         The transformation matrix to apply.
 */
function clearRect(ctx, x1, y1, x2, y2, matrix = identity()) {
  const p = getPointsFromDiagonal(x1, y1, x2, y2, matrix);

  // We are creating a clipping path and want it removed after we clear it's
  // contents so we need to save the context.
  ctx.save();

  // Create a path to be cleared.
  ctx.beginPath();
  ctx.moveTo(Math.round(p[0].x), Math.round(p[0].y));
  ctx.lineTo(Math.round(p[1].x), Math.round(p[1].y));
  ctx.lineTo(Math.round(p[2].x), Math.round(p[2].y));
  ctx.lineTo(Math.round(p[3].x), Math.round(p[3].y));
  ctx.closePath();

  // Restrict future drawing to the inside of the path.
  ctx.clip();

  // Clear any transforms applied to the canvas so that clearRect() really does
  // clear everything.
  ctx.setTransform(1, 0, 0, 1, 0, 0);

  // Clear the contents of our clipped path by attempting to clear the canvas.
  ctx.clearRect(0, 0, CANVAS_SIZE, CANVAS_SIZE);

  // Restore the context to the state it was before changing transforms and
  // adding clipping paths.
  ctx.restore();
}

/**
 * Draws an arrow-bubble rectangle in the provided canvas context.
 *
 * @param  {CanvasRenderingContext2D} ctx
 *         The 2D canvas context.
 * @param  {Number} x
 *         The x-axis origin of the rectangle.
 * @param  {Number} y
 *         The y-axis origin of the rectangle.
 * @param  {Number} width
 *         The width of the rectangle.
 * @param  {Number} height
 *         The height of the rectangle.
 * @param  {Number} radius
 *         The radius of the rounding.
 * @param  {Number} margin
 *         The distance of the origin point from the pointer.
 * @param  {Number} arrowSize
 *         The size of the arrow.
 * @param  {String} alignment
 *         The alignment of the rectangle in relation to its position to the grid.
 */
function drawBubbleRect(
  ctx,
  x,
  y,
  width,
  height,
  radius,
  margin,
  arrowSize,
  alignment
) {
  let angle = 0;

  if (alignment === "bottom") {
    angle = 180;
  } else if (alignment === "right") {
    angle = 90;
    [width, height] = [height, width];
  } else if (alignment === "left") {
    [width, height] = [height, width];
    angle = 270;
  }

  const originX = x;
  const originY = y;

  ctx.save();
  ctx.translate(originX, originY);
  ctx.rotate(angle * (Math.PI / 180));
  ctx.translate(-originX, -originY);
  ctx.translate(-width / 2, -height - arrowSize - margin);

  // The contour of the bubble is drawn with a path. The canvas context will have taken
  // care of transforming the coordinates before calling the function, so we just always
  // draw with the arrow pointing down. The top edge has rounded corners too.
  ctx.beginPath();
  // Start at the top/left corner (below the rounded corner).
  ctx.moveTo(x, y + radius);
  // Go down.
  ctx.lineTo(x, y + height);
  // Go down and the right, to draw the first half of the arrow tip.
  ctx.lineTo(x + width / 2, y + height + arrowSize);
  // Go back up and to the right, to draw the second half of the arrow tip.
  ctx.lineTo(x + width, y + height);
  // Go up to just below the top/right rounded corner.
  ctx.lineTo(x + width, y + radius);
  // Draw the top/right rounded corner.
  ctx.arcTo(x + width, y, x + width - radius, y, radius);
  // Go to the left.
  ctx.lineTo(x + radius, y);
  // Draw the top/left rounded corner.
  ctx.arcTo(x, y, x, y + radius, radius);

  ctx.stroke();
  ctx.fill();

  ctx.restore();
}

/**
 * Draws a line to the context given and applies a transformation matrix if passed.
 *
 * @param  {CanvasRenderingContext2D} ctx
 *         The 2D canvas context.
 * @param  {Number} x1
 *         The x-axis of the coordinate for the begin of the line.
 * @param  {Number} y1
 *         The y-axis of the coordinate for the begin of the line.
 * @param  {Number} x2
 *         The x-axis of the coordinate for the end of the line.
 * @param  {Number} y2
 *         The y-axis of the coordinate for the end of the line.
 * @param  {Object} [options]
 *         The options object.
 * @param  {Array} [options.matrix=identity()]
 *         The transformation matrix to apply.
 * @param  {Array} [options.extendToBoundaries]
 *         If set, the line will be extended to reach the boundaries specified.
 */
function drawLine(ctx, x1, y1, x2, y2, options) {
  const matrix = options.matrix || identity();

  const p1 = apply(matrix, [x1, y1]);
  const p2 = apply(matrix, [x2, y2]);

  x1 = p1[0];
  y1 = p1[1];
  x2 = p2[0];
  y2 = p2[1];

  if (options.extendToBoundaries) {
    if (p1[1] === p2[1]) {
      x1 = options.extendToBoundaries[0];
      x2 = options.extendToBoundaries[2];
    } else {
      y1 = options.extendToBoundaries[1];
      x1 = ((p2[0] - p1[0]) * (y1 - p1[1])) / (p2[1] - p1[1]) + p1[0];
      y2 = options.extendToBoundaries[3];
      x2 = ((p2[0] - p1[0]) * (y2 - p1[1])) / (p2[1] - p1[1]) + p1[0];
    }
  }

  ctx.beginPath();
  ctx.moveTo(Math.round(x1), Math.round(y1));
  ctx.lineTo(Math.round(x2), Math.round(y2));
}

/**
 * Draws a rect to the context given and applies a transformation matrix if passed.
 * The coordinates are the start and end points of the rectangle's diagonal.
 *
 * @param  {CanvasRenderingContext2D} ctx
 *         The 2D canvas context.
 * @param  {Number} x1
 *         The x-axis coordinate of the rectangle's diagonal start point.
 * @param  {Number} y1
 *         The y-axis coordinate of the rectangle's diagonal start point.
 * @param  {Number} x2
 *         The x-axis coordinate of the rectangle's diagonal end point.
 * @param  {Number} y2
 *         The y-axis coordinate of the rectangle's diagonal end point.
 * @param  {Array} [matrix=identity()]
 *         The transformation matrix to apply.
 */
function drawRect(ctx, x1, y1, x2, y2, matrix = identity()) {
  const p = getPointsFromDiagonal(x1, y1, x2, y2, matrix);

  ctx.beginPath();
  ctx.moveTo(Math.round(p[0].x), Math.round(p[0].y));
  ctx.lineTo(Math.round(p[1].x), Math.round(p[1].y));
  ctx.lineTo(Math.round(p[2].x), Math.round(p[2].y));
  ctx.lineTo(Math.round(p[3].x), Math.round(p[3].y));
  ctx.closePath();
}

/**
 * Draws a rounded rectangle in the provided canvas context.
 *
 * @param  {CanvasRenderingContext2D} ctx
 *         The 2D canvas context.
 * @param  {Number} x
 *         The x-axis origin of the rectangle.
 * @param  {Number} y
 *         The y-axis origin of the rectangle.
 * @param  {Number} width
 *         The width of the rectangle.
 * @param  {Number} height
 *         The height of the rectangle.
 * @param  {Number} radius
 *         The radius of the rounding.
 */
function drawRoundedRect(ctx, x, y, width, height, radius) {
  ctx.beginPath();
  ctx.moveTo(x, y + radius);
  ctx.lineTo(x, y + height - radius);
  ctx.arcTo(x, y + height, x + radius, y + height, radius);
  ctx.lineTo(x + width - radius, y + height);
  ctx.arcTo(x + width, y + height, x + width, y + height - radius, radius);
  ctx.lineTo(x + width, y + radius);
  ctx.arcTo(x + width, y, x + width - radius, y, radius);
  ctx.lineTo(x + radius, y);
  ctx.arcTo(x, y, x, y + radius, radius);
  ctx.stroke();
  ctx.fill();
}

/**
 * Given an array of four points and returns a DOMRect-like object representing the
 * boundaries defined by the four points.
 *
 * @param  {Array} points
 *         An array with 4 pointer objects {x, y} representing the box quads.
 * @return {Object} DOMRect-like object of the 4 points.
 */
function getBoundsFromPoints(points) {
  const bounds = {};

  bounds.left = Math.min(points[0].x, points[1].x, points[2].x, points[3].x);
  bounds.right = Math.max(points[0].x, points[1].x, points[2].x, points[3].x);
  bounds.top = Math.min(points[0].y, points[1].y, points[2].y, points[3].y);
  bounds.bottom = Math.max(points[0].y, points[1].y, points[2].y, points[3].y);

  bounds.x = bounds.left;
  bounds.y = bounds.top;
  bounds.width = bounds.right - bounds.left;
  bounds.height = bounds.bottom - bounds.top;

  return bounds;
}

/**
 * Returns the current matrices for both canvas drawing and SVG taking into account the
 * following transformations, in this order:
 *   1. The scale given by the display pixel ratio.
 *   2. The translation to the top left corner of the element.
 *   3. The scale given by the current zoom.
 *   4. The translation given by the top and left padding of the element.
 *   5. Any CSS transformation applied directly to the element (only 2D
 *      transformation; the 3D transformation are flattened, see `dom-matrix-2d` module
 *      for further details.)
 *   6. Rotate, translate, and reflect as needed to match the writing mode and text
 *      direction of the element.
 *
 *  The transformations of the element's ancestors are not currently computed (see
 *  bug 1355675).
 *
 * @param  {Element} element
 *         The current element.
 * @param  {Window} window
 *         The window object.
 * @param  {Object} [options.ignoreWritingModeAndTextDirection=false]
 *                  Avoid transforming the current matrix to match the text direction
 *                  and writing mode.
 * @return {Object} An object with the following properties:
 *         - {Array} currentMatrix
 *           The current matrix.
 *         - {Boolean} hasNodeTransformations
 *           true if the node has transformed and false otherwise.
 */
function getCurrentMatrix(
  element,
  window,
  { ignoreWritingModeAndTextDirection } = {}
) {
  const computedStyle = getComputedStyle(element);

  const paddingTop = parseFloat(computedStyle.paddingTop);
  const paddingRight = parseFloat(computedStyle.paddingRight);
  const paddingBottom = parseFloat(computedStyle.paddingBottom);
  const paddingLeft = parseFloat(computedStyle.paddingLeft);
  const borderTop = parseFloat(computedStyle.borderTopWidth);
  const borderRight = parseFloat(computedStyle.borderRightWidth);
  const borderBottom = parseFloat(computedStyle.borderBottomWidth);
  const borderLeft = parseFloat(computedStyle.borderLeftWidth);

  const nodeMatrix = getNodeTransformationMatrix(
    element,
    window.document.documentElement
  );

  let currentMatrix = identity();
  let hasNodeTransformations = false;

  // Scale based on the device pixel ratio.
  currentMatrix = multiply(currentMatrix, scale(window.devicePixelRatio));

  // Apply the current node's transformation matrix, relative to the inspected window's
  // root element, but only if it's not a identity matrix.
  if (isIdentity(nodeMatrix)) {
    hasNodeTransformations = false;
  } else {
    currentMatrix = multiply(currentMatrix, nodeMatrix);
    hasNodeTransformations = true;
  }

  // Translate the origin based on the node's padding and border values.
  currentMatrix = multiply(
    currentMatrix,
    translate(paddingLeft + borderLeft, paddingTop + borderTop)
  );

  // Adjust as needed to match the writing mode and text direction of the element.
  const size = {
    width:
      element.offsetWidth -
      borderLeft -
      borderRight -
      paddingLeft -
      paddingRight,
    height:
      element.offsetHeight -
      borderTop -
      borderBottom -
      paddingTop -
      paddingBottom,
  };

  if (!ignoreWritingModeAndTextDirection) {
    const writingModeMatrix = getWritingModeMatrix(size, computedStyle);
    if (!isIdentity(writingModeMatrix)) {
      currentMatrix = multiply(currentMatrix, writingModeMatrix);
    }
  }

  return { currentMatrix, hasNodeTransformations };
}

/**
 * Given an array of four points, returns a string represent a path description.
 *
 * @param  {Array} points
 *         An array with 4 pointer objects {x, y} representing the box quads.
 * @return {String} a Path Description that can be used in svg's <path> element.
 */
function getPathDescriptionFromPoints(points) {
  return (
    "M" +
    points[0].x +
    "," +
    points[0].y +
    " " +
    "L" +
    points[1].x +
    "," +
    points[1].y +
    " " +
    "L" +
    points[2].x +
    "," +
    points[2].y +
    " " +
    "L" +
    points[3].x +
    "," +
    points[3].y
  );
}

/**
 * Given the rectangle's diagonal start and end coordinates, returns an array containing
 * the four coordinates of a rectangle. If a matrix is provided, applies the matrix
 * function to each of the coordinates' value.
 *
 * @param  {Number} x1
 *         The x-axis coordinate of the rectangle's diagonal start point.
 * @param  {Number} y1
 *         The y-axis coordinate of the rectangle's diagonal start point.
 * @param  {Number} x2
 *         The x-axis coordinate of the rectangle's diagonal end point.
 * @param  {Number} y2
 *         The y-axis coordinate of the rectangle's diagonal end point.
 * @param  {Array} [matrix=identity()]
 *         A transformation matrix to apply.
 * @return {Array} the four coordinate points of the given rectangle transformed by the
 * matrix given.
 */
function getPointsFromDiagonal(x1, y1, x2, y2, matrix = identity()) {
  return [
    [x1, y1],
    [x2, y1],
    [x2, y2],
    [x1, y2],
  ].map(point => {
    const transformedPoint = apply(matrix, point);

    return { x: transformedPoint[0], y: transformedPoint[1] };
  });
}

/**
 * Updates the <canvas> element's style in accordance with the current window's
 * device pixel ratio, and the position calculated in `getCanvasPosition`. It also
 * clears the drawing context. This is called on canvas update after a scroll event where
 * `getCanvasPosition` updates the new canvasPosition.
 *
 * @param  {Canvas} canvas
 *         The <canvas> element.
 * @param  {Object} canvasPosition
 *         A pointer object {x, y} representing the <canvas> position to the top left
 *         corner of the page.
 * @param  {Number} devicePixelRatio
 *         The device pixel ratio.
 * @param  {Window} [options.zoomWindow]
 *         Optional window object used to calculate zoom (default = undefined).
 */
function updateCanvasElement(
  canvas,
  canvasPosition,
  devicePixelRatio,
  { zoomWindow } = {}
) {
  let { x, y } = canvasPosition;
  const size = CANVAS_SIZE / devicePixelRatio;

  if (zoomWindow) {
    const zoom = getCurrentZoom(zoomWindow);
    x *= zoom;
    y *= zoom;
  }

  // Resize the canvas taking the dpr into account so as to have crisp lines, and
  // translating it to give the perception that it always covers the viewport.
  canvas.setAttribute(
    "style",
    `width: ${size}px; height: ${size}px; transform: translate(${x}px, ${y}px);`
  );
  canvas.getCanvasContext("2d").clearRect(0, 0, CANVAS_SIZE, CANVAS_SIZE);
}

/**
 * Calculates and returns the <canvas>'s position in accordance with the page's scroll,
 * document's size, canvas size, and viewport's size. This is called when a page's scroll
 * is detected.
 *
 * @param  {Object} canvasPosition
 *         A pointer object {x, y} representing the <canvas> position to the top left
 *         corner of the page.
 * @param  {Object} scrollPosition
 *         A pointer object {x, y} representing the window's pageXOffset and pageYOffset.
 * @param  {Window} window
 *         The window object.
 * @param  {Object} windowDimensions
 *         An object {width, height} representing the window's dimensions for the
 *         `window` given.
 * @return {Boolean} true if the <canvas> position was updated and false otherwise.
 */
function updateCanvasPosition(
  canvasPosition,
  scrollPosition,
  window,
  windowDimensions
) {
  let { x: canvasX, y: canvasY } = canvasPosition;
  const { x: scrollX, y: scrollY } = scrollPosition;
  const cssCanvasSize = CANVAS_SIZE / window.devicePixelRatio;
  const viewportSize = getViewportDimensions(window);
  const { height, width } = windowDimensions;
  const canvasWidth = cssCanvasSize;
  const canvasHeight = cssCanvasSize;
  let hasUpdated = false;

  // Those values indicates the relative horizontal and vertical space the page can
  // scroll before we have to reposition the <canvas>; they're 1/4 of the delta between
  // the canvas' size and the viewport's size: that's because we want to consider both
  // sides (top/bottom, left/right; so 1/2 for each side) and also we don't want to
  // shown the edges of the canvas in case of fast scrolling (to avoid showing undraw
  // areas, therefore another 1/2 here).
  const bufferSizeX = (canvasWidth - viewportSize.width) >> 2;
  const bufferSizeY = (canvasHeight - viewportSize.height) >> 2;

  // Defines the boundaries for the canvas.
  const leftBoundary = 0;
  const rightBoundary = width - canvasWidth;
  const topBoundary = 0;
  const bottomBoundary = height - canvasHeight;

  // Defines the thresholds that triggers the canvas' position to be updated.
  const leftThreshold = scrollX - bufferSizeX;
  const rightThreshold =
    scrollX - canvasWidth + viewportSize.width + bufferSizeX;
  const topThreshold = scrollY - bufferSizeY;
  const bottomThreshold =
    scrollY - canvasHeight + viewportSize.height + bufferSizeY;

  if (canvasX < rightBoundary && canvasX < rightThreshold) {
    canvasX = Math.min(leftThreshold, rightBoundary);
    hasUpdated = true;
  } else if (canvasX > leftBoundary && canvasX > leftThreshold) {
    canvasX = Math.max(rightThreshold, leftBoundary);
    hasUpdated = true;
  }

  if (canvasY < bottomBoundary && canvasY < bottomThreshold) {
    canvasY = Math.min(topThreshold, bottomBoundary);
    hasUpdated = true;
  } else if (canvasY > topBoundary && canvasY > topThreshold) {
    canvasY = Math.max(bottomThreshold, topBoundary);
    hasUpdated = true;
  }

  // Update the canvas position with the calculated canvasX and canvasY positions.
  canvasPosition.x = canvasX;
  canvasPosition.y = canvasY;

  return hasUpdated;
}

exports.CANVAS_SIZE = CANVAS_SIZE;
exports.DEFAULT_COLOR = DEFAULT_COLOR;
exports.clearRect = clearRect;
exports.drawBubbleRect = drawBubbleRect;
exports.drawLine = drawLine;
exports.drawRect = drawRect;
exports.drawRoundedRect = drawRoundedRect;
exports.getBoundsFromPoints = getBoundsFromPoints;
exports.getCurrentMatrix = getCurrentMatrix;
exports.getPathDescriptionFromPoints = getPathDescriptionFromPoints;
exports.getPointsFromDiagonal = getPointsFromDiagonal;
exports.updateCanvasElement = updateCanvasElement;
exports.updateCanvasPosition = updateCanvasPosition;