Virtual whiteboard for sketching hand-drawn like diagrams
import rough from "roughjs/bin/rough";
import {
clamp,
type GlobalPoint,
isRightAngleRads,
lineSegment,
pointFrom,
pointRotateRads,
type Radians,
} from "@excalidraw/math";
import {
BOUND_TEXT_PADDING,
DEFAULT_REDUCED_GLOBAL_ALPHA,
ELEMENT_READY_TO_ERASE_OPACITY,
FRAME_STYLE,
DARK_THEME_FILTER,
MIME_TYPES,
THEME,
distance,
getFontString,
isRTL,
getVerticalOffset,
invariant,
applyDarkModeFilter,
isSafari,
STICKY_NOTE_EDGE_SHADOW_OPACITY,
STICKY_NOTE_EDGE_SHADOW_WIDTH,
STICKY_NOTE_FOOTER,
STICKY_NOTE_SHADOW_OPACITY,
DEFAULT_ZOOM,
} from "@excalidraw/common";
import type {
AppState,
StaticCanvasAppState,
Zoom,
InteractiveCanvasAppState,
ElementRenderOverrides,
} from "@excalidraw/excalidraw/types";
import type {
StaticCanvasRenderConfig,
RenderableElementsMap,
InteractiveCanvasRenderConfig,
} from "@excalidraw/excalidraw/scene/types";
import { getCreatePath, getRenderEnvironment } from "./renderEnvironment";
import { getElementAbsoluteCoords, getElementBounds } from "./bounds";
import { getUncroppedImageElement } from "./cropElement";
import { LinearElementEditor } from "./linearElementEditor";
import {
getBoundTextElement,
getContainerCoords,
getContainerElement,
getBoundTextMaxHeight,
getBoundTextMaxWidth,
} from "./textElement";
import { getLineHeightInPx } from "./textMeasurements";
import {
isTextElement,
isLinearElement,
isFreeDrawElement,
isInitializedImageElement,
isArrowElement,
hasBoundTextElement,
isMagicFrameElement,
isFrameLikeElement,
isImageElement,
} from "./typeChecks";
import { getContainingFrame } from "./frame";
import { getCornerRadius } from "./utils";
import { ShapeCache } from "./shape";
import {
getStickyNoteFooter,
getStickyNotePathCommands,
type StickyNotePathCommand,
} from "./stickyNote";
import type { RenderEnvironment } from "./renderEnvironment";
import type {
ExcalidrawElement,
ExcalidrawTextElement,
NonDeleted,
NonDeletedExcalidrawElement,
ExcalidrawFreeDrawElement,
ExcalidrawImageElement,
ExcalidrawTextElementWithContainer,
NonDeletedSceneElementsMap,
ElementsMap,
} from "./types";
import type { RoughCanvas } from "roughjs/bin/canvas";
const isPendingImageElement = (
element: ExcalidrawElement,
renderConfig: StaticCanvasRenderConfig,
) =>
isInitializedImageElement(element) &&
!renderConfig.imageCache.has(element.fileId);
const getCanvasPadding = (element: ExcalidrawElement) => {
switch (element.type) {
case "freedraw":
return element.strokeWidth * 12;
case "text":
return element.fontSize / 2;
case "arrow":
if (element.endArrowhead || element.endArrowhead) {
return 40;
}
return 20;
default:
return 20;
}
};
export type RenderPositionOffset = Readonly<{ x: number; y: number }>;
const ZERO_RENDER_OFFSET: RenderPositionOffset = { x: 0, y: 0 };
/** Bound labels follow their container; a label's own offset is ignored. */
export const getElementRenderOffset = (
element: ExcalidrawElement,
elementsMap: ElementsMap,
overrides: ElementRenderOverrides | undefined,
): RenderPositionOffset | undefined => {
const container = isTextElement(element)
? getContainerElement(element, elementsMap)
: null;
return overrides?.get((container ?? element).id)?.offset;
};
export const getRenderElementWithPositionOverride = <
TElement extends ExcalidrawElement,
>(
element: TElement,
positionOffset: RenderPositionOffset,
): TElement => {
if (positionOffset.x === 0 && positionOffset.y === 0) {
return element;
}
return {
...element,
x: element.x + positionOffset.x,
y: element.y + positionOffset.y,
} as TElement;
};
export type ElementRenderState = Readonly<{
/** Alpha including frame opacity and pending erasure; selection dimming is separate. */
opacity: number;
offset: RenderPositionOffset;
}>;
/** Resolve visual state at the drawing boundary, preserving document cache keys. */
export const resolveElementRenderState = (
element: ExcalidrawElement,
elementsMap: ElementsMap,
renderConfig: Pick<
StaticCanvasRenderConfig,
| "elementRenderOverrides"
| "elementsPendingErasure"
| "pendingFlowchartNodes"
>,
allElementsMap: ElementsMap = elementsMap,
): ElementRenderState => {
const {
elementRenderOverrides,
elementsPendingErasure,
pendingFlowchartNodes,
} = renderConfig;
const override = elementRenderOverrides?.get(element.id);
const containingFrame = getContainingFrame(element, elementsMap);
const frameOpacity = containingFrame
? clamp(
elementRenderOverrides?.get(containingFrame.id)?.opacity ??
containingFrame.opacity,
0,
100,
)
: 100;
// Frame and element alpha multiply (50% each produces 25%).
let opacity =
(frameOpacity * clamp(override?.opacity ?? element.opacity, 0, 100)) /
10000;
if (
elementsPendingErasure.has(element.id) ||
pendingFlowchartNodes?.some((node) => node.id === element.id) ||
(containingFrame && elementsPendingErasure.has(containingFrame.id))
) {
opacity *= ELEMENT_READY_TO_ERASE_OPACITY / 100;
}
const offset = getElementRenderOffset(
element,
allElementsMap,
elementRenderOverrides,
);
return { opacity, offset: offset ?? ZERO_RENDER_OFFSET };
};
export interface ExcalidrawElementWithCanvas {
element: ExcalidrawElement | ExcalidrawTextElement;
canvas: HTMLCanvasElement;
theme: AppState["theme"];
scale: number;
/** backing-store scale the bitmap was rasterized at, see StaticCanvasRenderConfig["scale"] */
deviceScale: number;
environment: RenderEnvironment;
zoomValue: AppState["zoom"]["value"];
canvasOffsetX: number;
canvasOffsetY: number;
imageCrop: ExcalidrawImageElement["crop"] | null;
containingFrameOpacity: number;
}
const cappedElementCanvasSize = (
element: NonDeletedExcalidrawElement,
elementsMap: ElementsMap,
zoom: Zoom,
/** backing-store scale, see StaticCanvasRenderConfig["scale"] */
deviceScale: number,
): {
width: number;
height: number;
scale: number;
} => {
// these limits are ballpark, they depend on specific browsers and device.
// We've chosen lower limits to be safe. We might want to change these limits
// based on browser/device type, if we get reports of low quality rendering
// on zoom.
//
// ~ safari mobile canvas area limit
const AREA_LIMIT = 16777216;
// ~ safari width/height limit based on developer.mozilla.org.
const WIDTH_HEIGHT_LIMIT = 32767;
const padding = getCanvasPadding(element);
const [x1, y1, x2, y2] = getElementAbsoluteCoords(element, elementsMap);
const elementWidth =
isLinearElement(element) || isFreeDrawElement(element)
? distance(x1, x2)
: element.width;
const elementHeight =
isLinearElement(element) || isFreeDrawElement(element)
? distance(y1, y2)
: element.height;
let width = elementWidth * deviceScale + padding * 2;
let height = elementHeight * deviceScale + padding * 2;
let scale: number = zoom.value;
// rescale to ensure width and height is within limits
if (
width * scale > WIDTH_HEIGHT_LIMIT ||
height * scale > WIDTH_HEIGHT_LIMIT
) {
scale = Math.min(WIDTH_HEIGHT_LIMIT / width, WIDTH_HEIGHT_LIMIT / height);
}
// rescale to ensure canvas area is within limits
if (width * height * scale * scale > AREA_LIMIT) {
scale = Math.sqrt(AREA_LIMIT / (width * height));
}
width = Math.floor(width * scale);
height = Math.floor(height * scale);
return { width, height, scale };
};
const generateElementCanvas = (
element: NonDeletedExcalidrawElement,
elementsMap: NonDeletedSceneElementsMap,
zoom: Zoom,
renderConfig: StaticCanvasRenderConfig,
appState: StaticCanvasAppState | InteractiveCanvasAppState,
): ExcalidrawElementWithCanvas | null => {
const environment = getRenderEnvironment(renderConfig.renderEnvironment);
const canvas = environment.createCanvas();
const context = canvas.getContext("2d")!;
const padding = getCanvasPadding(element);
const { width, height, scale } = cappedElementCanvasSize(
element,
elementsMap,
zoom,
renderConfig.scale,
);
if (!width || !height) {
return null;
}
canvas.width = width;
canvas.height = height;
let canvasOffsetX = -100;
let canvasOffsetY = 0;
if (isLinearElement(element) || isFreeDrawElement(element)) {
const [x1, y1] = getElementAbsoluteCoords(element, elementsMap);
canvasOffsetX =
element.x > x1 ? distance(element.x, x1) * renderConfig.scale * scale : 0;
canvasOffsetY =
element.y > y1 ? distance(element.y, y1) * renderConfig.scale * scale : 0;
context.translate(canvasOffsetX, canvasOffsetY);
}
context.save();
context.translate(padding * scale, padding * scale);
context.scale(renderConfig.scale * scale, renderConfig.scale * scale);
const rc = rough.canvas(canvas);
drawElementOnCanvas(element, rc, context, renderConfig);
context.restore();
return {
element,
canvas,
theme: appState.theme,
scale,
deviceScale: renderConfig.scale,
environment,
zoomValue: zoom.value,
canvasOffsetX,
canvasOffsetY,
containingFrameOpacity:
getContainingFrame(element, elementsMap)?.opacity || 100,
imageCrop: isImageElement(element) ? element.crop : null,
};
};
export const DEFAULT_LINK_SIZE = 14;
const IMAGE_PLACEHOLDER_SRC = `data:${MIME_TYPES.svg},${encodeURIComponent(
`<svg aria-hidden="true" focusable="false" data-prefix="fas" data-icon="image" class="svg-inline--fa fa-image fa-w-16" role="img" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512"><path fill="#888" d="M464 448H48c-26.51 0-48-21.49-48-48V112c0-26.51 21.49-48 48-48h416c26.51 0 48 21.49 48 48v288c0 26.51-21.49 48-48 48zM112 120c-30.928 0-56 25.072-56 56s25.072 56 56 56 56-25.072 56-56-25.072-56-56-56zM64 384h384V272l-87.515-87.515c-4.686-4.686-12.284-4.686-16.971 0L208 320l-55.515-55.515c-4.686-4.686-12.284-4.686-16.971 0L64 336v48z"></path></svg>`,
)}`;
const IMAGE_ERROR_PLACEHOLDER_SRC = `data:${
MIME_TYPES.svg
},${encodeURIComponent(
`<svg viewBox="0 0 668 668" xmlns="http://www.w3.org/2000/svg" xml:space="preserve" style="fill-rule:evenodd;clip-rule:evenodd;stroke-linejoin:round;stroke-miterlimit:2"><path d="M464 448H48c-26.51 0-48-21.49-48-48V112c0-26.51 21.49-48 48-48h416c26.51 0 48 21.49 48 48v288c0 26.51-21.49 48-48 48ZM112 120c-30.928 0-56 25.072-56 56s25.072 56 56 56 56-25.072 56-56-25.072-56-56-56ZM64 384h384V272l-87.515-87.515c-4.686-4.686-12.284-4.686-16.971 0L208 320l-55.515-55.515c-4.686-4.686-12.284-4.686-16.971 0L64 336v48Z" style="fill:#888;fill-rule:nonzero" transform="matrix(.81709 0 0 .81709 124.825 145.825)"/><path d="M256 8C119.034 8 8 119.033 8 256c0 136.967 111.034 248 248 248s248-111.034 248-248S392.967 8 256 8Zm130.108 117.892c65.448 65.448 70 165.481 20.677 235.637L150.47 105.216c70.204-49.356 170.226-44.735 235.638 20.676ZM125.892 386.108c-65.448-65.448-70-165.481-20.677-235.637L361.53 406.784c-70.203 49.356-170.226 44.736-235.638-20.676Z" style="fill:#888;fill-rule:nonzero" transform="matrix(.30366 0 0 .30366 506.822 60.065)"/></svg>`,
)}`;
/**
* Built lazily so that importing this module never touches `document`, and so
* that a custom render environment supplies the element.
*/
const getPlaceholderImg = (src: string, env: RenderEnvironment) => {
const img = env.createImage();
img.src = src;
return img;
};
const drawImagePlaceholder = (
element: ExcalidrawImageElement,
context: CanvasRenderingContext2D,
theme: StaticCanvasRenderConfig["theme"],
env: RenderEnvironment,
) => {
context.fillStyle = theme === THEME.DARK ? "#2E2E2E" : "#E7E7E7";
context.fillRect(0, 0, element.width, element.height);
const imageMinWidthOrHeight = Math.min(element.width, element.height);
const size = Math.min(
imageMinWidthOrHeight,
Math.min(imageMinWidthOrHeight * 0.4, 100),
);
context.drawImage(
getPlaceholderImg(
element.status === "error"
? IMAGE_ERROR_PLACEHOLDER_SRC
: IMAGE_PLACEHOLDER_SRC,
env,
),
element.width / 2 - size / 2,
element.height / 2 - size / 2,
size,
size,
);
};
const drawStickyNotePath = (
context: CanvasRenderingContext2D,
commands: StickyNotePathCommand[],
) => {
context.beginPath();
for (const command of commands) {
if (command.type === "move") {
context.moveTo(command.point.x, command.point.y);
} else if (command.type === "line") {
context.lineTo(command.point.x, command.point.y);
} else {
context.quadraticCurveTo(
command.control.x,
command.control.y,
command.point.x,
command.point.y,
);
}
}
context.closePath();
};
const fillStickyNoteShape = (
context: CanvasRenderingContext2D,
commands: StickyNotePathCommand[],
) => {
drawStickyNotePath(context, commands);
context.fill();
};
const strokeStickyNoteEdge = (
context: CanvasRenderingContext2D,
commands: StickyNotePathCommand[],
) => {
context.save();
drawStickyNotePath(context, commands);
context.clip();
context.lineWidth = STICKY_NOTE_EDGE_SHADOW_WIDTH * 2;
context.strokeStyle = `rgba(0, 0, 0, ${STICKY_NOTE_EDGE_SHADOW_OPACITY})`;
drawStickyNotePath(context, commands);
context.stroke();
context.restore();
};
/**
* `save()`s the context around `draw`, restoring it even when `draw` throws:
* the scene renderer logs a failing element and carries on, and the element
* mustn't leave its transforms and clips behind for the next one.
*/
export const withSavedContext = (
context: CanvasRenderingContext2D,
draw: () => void,
) => {
context.save();
try {
draw();
} finally {
context.restore();
}
};
const drawElementOnCanvas = (
element: NonDeletedExcalidrawElement,
rc: RoughCanvas,
context: CanvasRenderingContext2D,
renderConfig: StaticCanvasRenderConfig,
) => {
switch (element.type) {
case "stickynote": {
withSavedContext(context, () => {
context.fillStyle = `rgba(0, 0, 0, ${STICKY_NOTE_SHADOW_OPACITY})`;
fillStickyNoteShape(
context,
getStickyNotePathCommands(element, { shadow: true }),
);
const commands = getStickyNotePathCommands(element);
context.fillStyle = applyDarkModeFilter(
element.backgroundColor,
renderConfig.theme === THEME.DARK,
);
fillStickyNoteShape(context, commands);
strokeStickyNoteEdge(context, commands);
// the label is absolute, so this cached canvas only goes stale at a
// year boundary — and is regenerated on the next zoom, theme or
// element change anyway
const footer = getStickyNoteFooter(element);
if (footer) {
context.font = `${STICKY_NOTE_FOOTER.fontSize}px ${STICKY_NOTE_FOOTER.fontFamily}`;
context.textAlign = "right";
context.textBaseline = "alphabetic";
context.fillStyle = applyDarkModeFilter(
element.strokeColor,
renderConfig.theme === THEME.DARK,
);
context.globalAlpha *= STICKY_NOTE_FOOTER.opacity;
context.fillText(footer.text, footer.x, footer.y);
}
});
break;
}
case "rectangle":
case "iframe":
case "embeddable":
case "diamond":
case "ellipse": {
context.lineJoin = "round";
context.lineCap = "round";
rc.draw(ShapeCache.generateElementShape(element, renderConfig));
break;
}
case "arrow":
case "line": {
context.lineJoin = "round";
context.lineCap = "round";
ShapeCache.generateElementShape(element, renderConfig).forEach(
(shape) => {
rc.draw(shape);
},
);
break;
}
case "freedraw": {
// Draw directly to canvas
withSavedContext(context, () => {
const shapes = ShapeCache.generateElementShape(element, renderConfig);
const createPath = getCreatePath(renderConfig.renderEnvironment);
for (const shape of shapes) {
if (typeof shape === "string") {
context.fillStyle = applyDarkModeFilter(
element.strokeColor,
renderConfig.theme === THEME.DARK,
);
context.fill(createPath(shape));
} else {
rc.draw(shape);
}
}
});
break;
}
case "image": {
withSavedContext(context, () => {
const cacheEntry =
element.fileId !== null
? renderConfig.imageCache.get(element.fileId)
: null;
const img = isInitializedImageElement(element)
? cacheEntry?.image
: undefined;
if (img != null && !(img instanceof Promise)) {
if (element.roundness && context.roundRect) {
context.beginPath();
context.roundRect(
0,
0,
element.width,
element.height,
getCornerRadius(Math.min(element.width, element.height), element),
);
context.clip();
}
const { x, y, width, height } = element.crop
? element.crop
: {
x: 0,
y: 0,
width: img.naturalWidth,
height: img.naturalHeight,
};
const shouldInvertImage =
renderConfig.theme === THEME.DARK &&
cacheEntry?.mimeType === MIME_TYPES.svg;
if (shouldInvertImage && isSafari) {
const devicePixelRatio = renderConfig.scale || 1;
const tempCanvas = getRenderEnvironment(
renderConfig.renderEnvironment,
).createCanvas();
tempCanvas.width = element.width * devicePixelRatio;
tempCanvas.height = element.height * devicePixelRatio;
const tempContext = tempCanvas.getContext("2d");
if (tempContext) {
tempContext.scale(devicePixelRatio, devicePixelRatio);
tempContext.drawImage(
img,
x,
y,
width,
height,
0,
0,
element.width,
element.height,
);
const imageData = tempContext.getImageData(
0,
0,
tempCanvas.width,
tempCanvas.height,
);
const data = imageData.data;
for (let i = 0; i < data.length; i += 4) {
data[i] = 255 - data[i];
data[i + 1] = 255 - data[i + 1];
data[i + 2] = 255 - data[i + 2];
}
tempContext.putImageData(imageData, 0, 0);
context.drawImage(
tempCanvas,
0,
0,
tempCanvas.width,
tempCanvas.height,
0,
0,
element.width,
element.height,
);
}
} else {
if (shouldInvertImage) {
context.filter = DARK_THEME_FILTER;
}
context.drawImage(
img,
x,
y,
width,
height,
0 /* hardcoded for the selection box*/,
0,
element.width,
element.height,
);
}
} else {
drawImagePlaceholder(
element,
context,
renderConfig.theme,
getRenderEnvironment(renderConfig.renderEnvironment),
);
}
});
break;
}
default: {
if (isTextElement(element)) {
const rtl = isRTL(element.text);
// NOTE: `isConnected === false` rather than `!isConnected` -- a
// non-DOM canvas (node-canvas et al) has no such property, and must
// not be handed to `document.body`
const shouldTemporarilyAttach =
rtl &&
context.canvas.isConnected === false &&
typeof document !== "undefined";
if (shouldTemporarilyAttach) {
// to correctly render RTL text mixed with LTR, we have to append it
// to the DOM
document.body.appendChild(context.canvas);
}
if (typeof context.canvas.setAttribute === "function") {
context.canvas.setAttribute("dir", rtl ? "rtl" : "ltr");
}
withSavedContext(context, () => {
context.font = getFontString(element);
context.fillStyle = applyDarkModeFilter(
element.strokeColor,
renderConfig.theme === THEME.DARK,
);
context.textAlign = element.textAlign as CanvasTextAlign;
// Canvas does not support multiline text by default
const lines = element.text.replace(/\r\n?/g, "\n").split("\n");
const horizontalOffset =
element.textAlign === "center"
? element.width / 2
: element.textAlign === "right"
? element.width
: 0;
const lineHeightPx = getLineHeightInPx(
element.fontSize,
element.lineHeight,
);
const verticalOffset = getVerticalOffset(
element.fontFamily,
element.fontSize,
lineHeightPx,
);
for (let index = 0; index < lines.length; index++) {
context.fillText(
lines[index],
horizontalOffset,
index * lineHeightPx + verticalOffset,
);
}
});
if (shouldTemporarilyAttach) {
context.canvas.remove();
}
} else {
throw new Error(`Unimplemented type ${element.type}`);
}
}
}
};
export const elementWithCanvasCache = new WeakMap<
ExcalidrawElement,
ExcalidrawElementWithCanvas
>();
const generateElementWithCanvas = (
element: NonDeletedExcalidrawElement,
elementsMap: NonDeletedSceneElementsMap,
renderConfig: StaticCanvasRenderConfig,
appState: StaticCanvasAppState | InteractiveCanvasAppState,
) => {
const zoom: Zoom = renderConfig ? appState.zoom : DEFAULT_ZOOM;
const renderEnvironment = getRenderEnvironment(
renderConfig.renderEnvironment,
);
const prevElementWithCanvas = elementWithCanvasCache.get(element);
const shouldRegenerateBecauseZoom =
prevElementWithCanvas &&
prevElementWithCanvas.zoomValue !== zoom.value &&
!appState?.shouldCacheIgnoreZoom;
const imageCrop = isImageElement(element) ? element.crop : null;
const containingFrameOpacity =
getContainingFrame(element, elementsMap)?.opacity || 100;
if (
!prevElementWithCanvas ||
shouldRegenerateBecauseZoom ||
prevElementWithCanvas.theme !== appState.theme ||
prevElementWithCanvas.deviceScale !== renderConfig.scale ||
prevElementWithCanvas.environment !== renderEnvironment ||
prevElementWithCanvas.imageCrop !== imageCrop ||
prevElementWithCanvas.containingFrameOpacity !== containingFrameOpacity
) {
const elementWithCanvas = generateElementCanvas(
element,
elementsMap,
zoom,
renderConfig,
appState,
);
if (!elementWithCanvas) {
return null;
}
elementWithCanvasCache.set(element, elementWithCanvas);
return elementWithCanvas;
}
return prevElementWithCanvas;
};
/**
* Whether an element's cached bitmap may be laid on the device-pixel grid:
* unrotated or at a right angle, and not during a zoom gesture. The cached
* path disables smoothing for exactly these — a nearest-neighbor 1:1 blit is
* a pixel-exact copy, and rounding its origin keeps it off the half-pixel
* boundary where it tears — and every eligible blit is snapped. It is
* eligibility, not a guarantee of a 1:1 copy: freedraw is blitted with
* smoothing on, and a size-capped cache is rescaled; snapping is harmless
* for both.
*
* Not during a zoom gesture: the bitmaps stay at the old scale and are
* resampled, and blurry shapes look better on low resolution (while still
* zooming in) than sharp ones; snapping would only make elements twitch.
* Right angles qualify because smoothing can be off there without aliasing
* (for other angles it is terrible on Chromium); the right-angle test
* tolerates float arithmetic.
*/
const canSnapElement = (
element: ExcalidrawElement,
appState: StaticCanvasAppState | InteractiveCanvasAppState,
) =>
!appState?.shouldCacheIgnoreZoom &&
(!element.angle || isRightAngleRads(element.angle));
/**
* Breaks a `Math.round` tie at exactly half a device pixel the same way
* every frame. A label's offset from its container lands on one routinely
* (an odd scene offset at 150%), and the float noise of a fractional drag
* would otherwise flip it between the two neighbors.
*/
const SNAP_TIE_BIAS = 1e-6;
const drawElementFromCanvas = (
elementWithCanvas: ExcalidrawElementWithCanvas,
context: CanvasRenderingContext2D,
renderConfig: StaticCanvasRenderConfig,
appState: StaticCanvasAppState | InteractiveCanvasAppState,
allElementsMap: NonDeletedSceneElementsMap,
positionOffset: RenderPositionOffset,
) => {
const element = elementWithCanvas.element;
// the backing-store scale the cached bitmap was generated with
// (`generateElementCanvas`); the blit's size math needs the same one, so it
// is the render config's, not the owner window's
const devicePixelRatio = renderConfig.scale;
const padding = getCanvasPadding(element);
const [x1, y1, x2, y2] = getElementAbsoluteCoords(element, allElementsMap);
const cx =
((x1 + x2) / 2 + positionOffset.x + appState.scrollX) * devicePixelRatio;
const cy =
((y1 + y2) / 2 + positionOffset.y + appState.scrollY) * devicePixelRatio;
withSavedContext(context, () => {
context.scale(1 / devicePixelRatio, 1 / devicePixelRatio);
const boundTextElement = getBoundTextElement(element, allElementsMap);
if (isArrowElement(element) && boundTextElement) {
// punch the label "hole" by clipping the arrow's blit out of the label
// rect (even-odd) instead of baking a rotated arrow copy with a cleared
// hole into a separate (`maxDim`-squared!) canvas. The hole stays
// axis-aligned in scene space while the blit below rotates.
const [, , , , boundTextCx, boundTextCy] = getElementAbsoluteCoords(
boundTextElement,
allElementsMap,
);
// generously covers the arrow's blit at any rotation
const outerHalf =
Math.max(distance(x1, x2), distance(y1, y2)) * devicePixelRatio +
padding * 10;
context.beginPath();
context.rect(
cx - outerHalf,
cy - outerHalf,
outerHalf * 2,
outerHalf * 2,
);
context.rect(
(boundTextCx -
boundTextElement.width / 2 -
BOUND_TEXT_PADDING +
positionOffset.x +
appState.scrollX) *
devicePixelRatio,
(boundTextCy -
boundTextElement.height / 2 -
BOUND_TEXT_PADDING +
positionOffset.y +
appState.scrollY) *
devicePixelRatio,
(boundTextElement.width + BOUND_TEXT_PADDING * 2) * devicePixelRatio,
(boundTextElement.height + BOUND_TEXT_PADDING * 2) * devicePixelRatio,
);
context.clip("evenodd");
}
// we translate context to element center so that rotation and scale
// originates from the element center
context.translate(cx, cy);
context.rotate(element.angle);
if (
"scale" in elementWithCanvas.element &&
!isPendingImageElement(element, renderConfig)
) {
context.scale(
elementWithCanvas.element.scale[0],
elementWithCanvas.element.scale[1],
);
}
// revert afterwards we don't have account for it during drawing
context.translate(-cx, -cy);
// the blit origin, in the space the context is in here (scaled by
// canvas scale × zoom ÷ devicePixelRatio)
let drawX =
(x1 + positionOffset.x + appState.scrollX) * devicePixelRatio - padding;
let drawY =
(y1 + positionOffset.y + appState.scrollY) * devicePixelRatio - padding;
const transform = context.getTransform();
if (canSnapElement(element, appState)) {
// blit the cached bitmap on whole device pixels. Nearest-neighbor at a
// fractional offset is a pixel-exact copy shifted to the nearest pixel
// — except at an exact half pixel, where a GPU-accelerated canvas
// decides the rounding per scanline by float precision and a few rows
// sample the neighboring row: doubled or broken strokes, varying with
// scroll and position. A centered label lands on a half pixel
// routinely.
//
// Done by moving the transform's origin onto the rounded device
// position of the blit and drawing at (0, 0): the rotation, mirroring
// and scale stay in `a`–`d` (a right angle keeps its scale in `b`/`c`),
// and the origin is an exact integer even in the canvas's float32
// matrix. Rounding `drawX` itself only lands on device pixels at 100%
// zoom.
const { a, b, c, d, e, f } = transform;
const container = isTextElement(element)
? getContainerElement(element, allElementsMap)
: null;
// A bound label shares its unrotated container's offset and anchor.
// Other bitmaps anchor to themselves.
const anchor = container && !container.angle ? container : element;
const anchorCoords =
anchor === element
? null
: getElementAbsoluteCoords(anchor, allElementsMap);
const anchorSceneX = anchorCoords?.[0] ?? x1;
const anchorSceneY = anchorCoords?.[1] ?? y1;
const anchorPadding =
anchor === element ? padding : getCanvasPadding(anchor);
const anchorX =
(anchorSceneX + positionOffset.x + appState.scrollX) *
devicePixelRatio -
anchorPadding;
const anchorY =
(anchorSceneY + positionOffset.y + appState.scrollY) *
devicePixelRatio -
anchorPadding;
// Form the relative vector before introducing the scroll translation.
const dx =
(x1 - anchorSceneX) * devicePixelRatio + anchorPadding - padding;
const dy =
(y1 - anchorSceneY) * devicePixelRatio + anchorPadding - padding;
context.setTransform(
a,
b,
c,
d,
Math.round(a * anchorX + c * anchorY + e) +
Math.round(a * dx + c * dy + SNAP_TIE_BIAS),
Math.round(b * anchorX + d * anchorY + f) +
Math.round(b * dx + d * dy + SNAP_TIE_BIAS),
);
drawX = 0;
drawY = 0;
}
context.drawImage(
elementWithCanvas.canvas!,
drawX,
drawY,
elementWithCanvas.canvas!.width / elementWithCanvas.scale,
elementWithCanvas.canvas!.height / elementWithCanvas.scale,
);
context.setTransform(transform);
if (
import.meta.env.VITE_APP_DEBUG_ENABLE_TEXT_CONTAINER_BOUNDING_BOX ===
"true" &&
hasBoundTextElement(element)
) {
const textElement = getBoundTextElement(
element,
allElementsMap,
) as ExcalidrawTextElementWithContainer;
const coords = getContainerCoords(element);
context.strokeStyle = "#c92a2a";
context.lineWidth = 3;
context.strokeRect(
(coords.x + positionOffset.x + appState.scrollX) * devicePixelRatio,
(coords.y + positionOffset.y + appState.scrollY) * devicePixelRatio,
getBoundTextMaxWidth(element, textElement) * devicePixelRatio,
getBoundTextMaxHeight(element, textElement) * devicePixelRatio,
);
}
});
// Clear the nested element we appended to the DOM
};
export const renderSelectionElement = (
element: NonDeletedExcalidrawElement,
context: CanvasRenderingContext2D,
appState: InteractiveCanvasAppState,
selectionColor: InteractiveCanvasRenderConfig["selectionColor"],
) => {
context.save();
context.translate(element.x + appState.scrollX, element.y + appState.scrollY);
context.fillStyle = applyDarkModeFilter(
"rgba(0, 0, 200, 0.04)",
appState.theme === THEME.DARK,
);
// render from 0.5px offset to get 1px wide line
// https://stackoverflow.com/questions/7530593/html5-canvas-and-line-width/7531540#7531540
// TODO can be be improved by offseting to the negative when user selects
// from right to left
const offset = 0.5 / appState.zoom.value;
context.fillRect(offset, offset, element.width, element.height);
context.lineWidth = 1 / appState.zoom.value;
context.strokeStyle = selectionColor;
context.strokeRect(offset, offset, element.width, element.height);
context.restore();
};
export const renderElement = (
element: NonDeletedExcalidrawElement,
elementsMap: RenderableElementsMap,
allElementsMap: NonDeletedSceneElementsMap,
rc: RoughCanvas,
context: CanvasRenderingContext2D,
renderConfig: StaticCanvasRenderConfig,
appState: StaticCanvasAppState | InteractiveCanvasAppState,
renderState = resolveElementRenderState(
element,
elementsMap,
renderConfig,
allElementsMap,
),
) => {
const reduceAlphaForSelection =
appState.openDialog?.name === "elementLinkSelector" &&
!appState.selectedElementIds[element.id] &&
!appState.hoveredElementIds[element.id];
context.save();
context.globalAlpha =
renderState.opacity *
(reduceAlphaForSelection ? DEFAULT_REDUCED_GLOBAL_ALPHA : 1);
// Cached bitmaps apply the offset before pixel snapping. Moving it into
// the canvas transform first loses precision at half-device-pixel ties.
if (
(renderConfig.isExporting || isFrameLikeElement(element)) &&
(renderState.offset.x || renderState.offset.y)
) {
context.translate(renderState.offset.x, renderState.offset.y);
}
try {
drawElement(
element,
elementsMap,
allElementsMap,
rc,
context,
renderConfig,
appState,
renderState,
);
} finally {
context.restore();
}
};
const drawElement = (
element: NonDeletedExcalidrawElement,
elementsMap: RenderableElementsMap,
allElementsMap: NonDeletedSceneElementsMap,
rc: RoughCanvas,
context: CanvasRenderingContext2D,
renderConfig: StaticCanvasRenderConfig,
appState: StaticCanvasAppState | InteractiveCanvasAppState,
renderState: ElementRenderState,
) => {
switch (element.type) {
case "magicframe":
case "frame": {
if (appState.frameRendering.enabled && appState.frameRendering.outline) {
withSavedContext(context, () => {
context.translate(
element.x + appState.scrollX,
element.y + appState.scrollY,
);
context.fillStyle = "rgba(0, 0, 200, 0.04)";
context.lineWidth = FRAME_STYLE.strokeWidth / appState.zoom.value;
context.strokeStyle = applyDarkModeFilter(
FRAME_STYLE.strokeColor,
appState.theme === THEME.DARK,
);
// TODO change later to only affect AI frames
if (isMagicFrameElement(element)) {
context.strokeStyle =
appState.theme === THEME.LIGHT
? "#7affd7"
: applyDarkModeFilter("#1d8264");
}
if (FRAME_STYLE.radius && context.roundRect) {
context.beginPath();
context.roundRect(
0,
0,
element.width,
element.height,
FRAME_STYLE.radius / appState.zoom.value,
);
context.stroke();
context.closePath();
} else {
context.strokeRect(0, 0, element.width, element.height);
}
});
}
break;
}
case "freedraw": {
if (renderConfig.isExporting) {
const [x1, y1, x2, y2] = getElementAbsoluteCoords(element, elementsMap);
const cx = (x1 + x2) / 2 + appState.scrollX;
const cy = (y1 + y2) / 2 + appState.scrollY;
const shiftX = (x2 - x1) / 2 - (element.x - x1);
const shiftY = (y2 - y1) / 2 - (element.y - y1);
withSavedContext(context, () => {
context.translate(cx, cy);
context.rotate(element.angle);
context.translate(-shiftX, -shiftY);
drawElementOnCanvas(element, rc, context, renderConfig);
});
} else {
const elementWithCanvas = generateElementWithCanvas(
element,
allElementsMap,
renderConfig,
appState,
);
if (!elementWithCanvas) {
return;
}
drawElementFromCanvas(
elementWithCanvas,
context,
renderConfig,
appState,
allElementsMap,
renderState.offset,
);
}
break;
}
case "rectangle":
case "stickynote":
case "diamond":
case "ellipse":
case "line":
case "arrow":
case "image":
case "text":
case "iframe":
case "embeddable": {
if (renderConfig.isExporting) {
const [x1, y1, x2, y2] = getElementAbsoluteCoords(element, elementsMap);
const centerX = (x1 + x2) / 2;
const centerY = (y1 + y2) / 2;
const cx = centerX + appState.scrollX;
const cy = centerY + appState.scrollY;
let shiftX = (x2 - x1) / 2 - (element.x - x1);
let shiftY = (y2 - y1) / 2 - (element.y - y1);
if (isTextElement(element)) {
const container = getContainerElement(element, elementsMap);
if (isArrowElement(container)) {
const boundTextCoords =
LinearElementEditor.getBoundTextElementPosition(
container,
element as ExcalidrawTextElementWithContainer,
elementsMap,
);
shiftX = (x2 - x1) / 2 - (boundTextCoords.x - x1);
shiftY = (y2 - y1) / 2 - (boundTextCoords.y - y1);
}
}
withSavedContext(context, () => {
context.translate(cx, cy);
const boundTextElement = getBoundTextElement(element, elementsMap);
if (isArrowElement(element) && boundTextElement) {
// Draw arrow directly as vector (no temp-canvas bitmap blit which
// introduces resampling blur). The label "hole" is cut by clipping
// the arrow's own strokes out of the label rect (even-odd clip)
// so that elements rendered beneath the arrow keep showing through
// the gap.
shiftX = element.width / 2 - (element.x - x1);
shiftY = element.height / 2 - (element.y - y1);
const [, , , , boundTextCx, boundTextCy] = getElementAbsoluteCoords(
boundTextElement,
elementsMap,
);
const holeX =
boundTextCx -
centerX -
boundTextElement.width / 2 -
BOUND_TEXT_PADDING;
const holeY =
boundTextCy -
centerY -
boundTextElement.height / 2 -
BOUND_TEXT_PADDING;
const holeWidth = boundTextElement.width + BOUND_TEXT_PADDING * 2;
const holeHeight = boundTextElement.height + BOUND_TEXT_PADDING * 2;
// generously covers the arrow's painted extent at any rotation
// (the hole rect stays axis-aligned in scene space)
const outerHalf =
Math.max(distance(x1, x2), distance(y1, y2)) +
getCanvasPadding(element) * 10;
withSavedContext(context, () => {
context.beginPath();
context.rect(
-outerHalf,
-outerHalf,
outerHalf * 2,
outerHalf * 2,
);
context.rect(holeX, holeY, holeWidth, holeHeight);
context.clip("evenodd");
context.rotate(element.angle);
context.translate(-shiftX, -shiftY);
drawElementOnCanvas(element, rc, context, renderConfig);
});
} else {
context.rotate(element.angle);
if (element.type === "image") {
// note: scale must be applied *after* rotating
context.scale(element.scale[0], element.scale[1]);
}
context.translate(-shiftX, -shiftY);
drawElementOnCanvas(element, rc, context, renderConfig);
}
});
// not exporting → optimized rendering (cache & render from element
// canvases)
} else {
const elementWithCanvas = generateElementWithCanvas(
element,
allElementsMap,
renderConfig,
appState,
);
if (!elementWithCanvas) {
return;
}
const currentImageSmoothingStatus = context.imageSmoothingEnabled;
// see `canSnapElement` for why not during zoom gestures or at
// other angles
if (canSnapElement(element, appState)) {
// Disabling smoothing makes output much sharper, especially for
// text. Unless for non-right angles, where the aliasing is really
// terrible on Chromium.
//
// Note that `context.imageSmoothingQuality="high"` has almost
// zero effect.
//
context.imageSmoothingEnabled = false;
}
const uncroppedElementCanvas =
element.id === appState.croppingElementId &&
isImageElement(elementWithCanvas.element) &&
elementWithCanvas.element.crop !== null
? generateElementCanvas(
getUncroppedImageElement(
elementWithCanvas.element,
elementsMap,
) as NonDeleted<ExcalidrawImageElement>,
allElementsMap,
appState.zoom,
renderConfig,
appState,
)
: null;
if (uncroppedElementCanvas) {
// the crop editor shows the uncropped image, faded outside the
// crop: one bitmap, so cropping moves only the crop's edges over it
// (the cropped image's own bitmap snaps to whole pixels by its own
// corner, shifting the image by a pixel as that corner moves)
withSavedContext(context, () => {
context.globalAlpha = 0.1;
drawElementFromCanvas(
uncroppedElementCanvas,
context,
renderConfig,
appState,
allElementsMap,
// The crop editor's uncropped preview stays at document coordinates.
ZERO_RENDER_OFFSET,
);
});
const [x1, y1, x2, y2] = getElementAbsoluteCoords(
elementWithCanvas.element,
allElementsMap,
);
withSavedContext(context, () => {
// (built in the element's rotated box: save/restore leaves the path)
context.save();
context.translate(
(x1 + x2) / 2 + renderState.offset.x + appState.scrollX,
(y1 + y2) / 2 + renderState.offset.y + appState.scrollY,
);
context.rotate(elementWithCanvas.element.angle);
context.beginPath();
context.rect((x1 - x2) / 2, (y1 - y2) / 2, x2 - x1, y2 - y1);
context.restore();
context.clip();
drawElementFromCanvas(
uncroppedElementCanvas,
context,
renderConfig,
appState,
allElementsMap,
renderState.offset,
);
});
} else {
drawElementFromCanvas(
elementWithCanvas,
context,
renderConfig,
appState,
allElementsMap,
renderState.offset,
);
}
// reset
context.imageSmoothingEnabled = currentImageSmoothingStatus;
}
break;
}
default: {
// @ts-ignore
throw new Error(`Unimplemented type ${element.type}`);
}
}
};
export function getFreedrawOutlineAsSegments(
element: ExcalidrawFreeDrawElement,
points: [number, number][],
elementsMap: ElementsMap,
) {
const bounds = getElementBounds(
{
...element,
angle: 0 as Radians,
},
elementsMap,
);
const center = pointFrom<GlobalPoint>(
(bounds[0] + bounds[2]) / 2,
(bounds[1] + bounds[3]) / 2,
);
invariant(points.length >= 2, "Freepath outline must have at least 2 points");
return points.slice(2).reduce(
(acc, curr) => {
acc.push(
lineSegment<GlobalPoint>(
acc[acc.length - 1][1],
pointRotateRads(
pointFrom<GlobalPoint>(curr[0] + element.x, curr[1] + element.y),
center,
element.angle,
),
),
);
return acc;
},
[
lineSegment<GlobalPoint>(
pointRotateRads(
pointFrom<GlobalPoint>(
points[0][0] + element.x,
points[0][1] + element.y,
),
center,
element.angle,
),
pointRotateRads(
pointFrom<GlobalPoint>(
points[1][0] + element.x,
points[1][1] + element.y,
),
center,
element.angle,
),
),
],
);
}