tor-browser

canvas.js (20377B)

---

/* 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;