js-draw 0.23.0 → 0.24.0

package/src/rendering/Display.ts

@@ -0,0 +1,248 @@
+import AbstractRenderer from './renderers/AbstractRenderer';
+import CanvasRenderer from './renderers/CanvasRenderer';
+import { Editor } from '../Editor';
+import { EditorEventType } from '../types';
+import DummyRenderer from './renderers/DummyRenderer';
+import { Point2, Vec2 } from '../math/Vec2';
+import RenderingCache from './caching/RenderingCache';
+import TextOnlyRenderer from './renderers/TextOnlyRenderer';
+import Color4 from '../Color4';
+
+export enum RenderingMode {
+	DummyRenderer,
+	CanvasRenderer,
+	// SVGRenderer is not supported by the main display
+}
+
+/**
+ * Handles `HTMLCanvasElement`s (or other drawing surfaces if being used) used to display the editor's contents.
+ *
+ * @example
+ * ```
+ * const editor = new Editor(document.body);
+ * const w = editor.display.width;
+ * const h = editor.display.height;
+ * const center = Vec2.of(w / 2, h / 2);
+ * const colorAtCenter = editor.display.getColorAt(center);
+ * ```
+ */
+export default class Display {
+	private dryInkRenderer: AbstractRenderer;
+	private wetInkRenderer: AbstractRenderer;
+	private textRenderer: TextOnlyRenderer;
+	private textRerenderOutput: HTMLElement|null = null;
+	private cache: RenderingCache;
+	private resizeSurfacesCallback?: ()=> void;
+	private flattenCallback?: ()=> void;
+
+	/** @internal */
+	public constructor(
+		private editor: Editor, mode: RenderingMode, private parent: HTMLElement|null
+	) {
+		if (mode === RenderingMode.CanvasRenderer) {
+			this.initializeCanvasRendering();
+		} else if (mode === RenderingMode.DummyRenderer) {
+			this.dryInkRenderer = new DummyRenderer(editor.viewport);
+			this.wetInkRenderer = new DummyRenderer(editor.viewport);
+		} else {
+			throw new Error(`Unknown rendering mode, ${mode}!`);
+		}
+
+		this.textRenderer = new TextOnlyRenderer(editor.viewport, editor.localization);
+		this.initializeTextRendering();
+
+		const cacheBlockResolution = Vec2.of(600, 600);
+		this.cache = new RenderingCache({
+			createRenderer: () => {
+				if (mode === RenderingMode.DummyRenderer) {
+					return new DummyRenderer(editor.viewport);
+				} else if (mode !== RenderingMode.CanvasRenderer) {
+					throw new Error('Unspported rendering mode');
+				}
+
+				// Make the canvas slightly larger than each cache block to prevent
+				// seams.
+				const canvas = document.createElement('canvas');
+				canvas.width = cacheBlockResolution.x + 1;
+				canvas.height = cacheBlockResolution.y + 1;
+				const ctx = canvas.getContext('2d');
+
+				return new CanvasRenderer(ctx!, editor.viewport);
+			},
+			isOfCorrectType: (renderer) => {
+				return this.dryInkRenderer.canRenderFromWithoutDataLoss(renderer);
+			},
+			blockResolution: cacheBlockResolution,
+			cacheSize: 600 * 600 * 4 * 90,
+			maxScale: 1.3,
+
+			// Require about 20 strokes with 4 parts each to cache an image in one of the
+			// parts of the cache grid.
+			minProportionalRenderTimePerCache: 20 * 4,
+
+			// Require about 105 strokes with 4 parts each to use the cache at all.
+			minProportionalRenderTimeToUseCache: 105 * 4,
+		});
+
+		this.editor.notifier.on(EditorEventType.DisplayResized, event => {
+			if (event.kind !== EditorEventType.DisplayResized) {
+				throw new Error('Mismatched event.kinds!');
+			}
+
+			this.resizeSurfacesCallback?.();
+		});
+	}
+
+	/**
+	 * @returns the visible width of the display (e.g. how much
+	 * space the display's element takes up in the x direction
+	 * in the DOM).
+	 */
+	public get width(): number {
+		return this.dryInkRenderer.displaySize().x;
+	}
+
+	public get height(): number {
+		return this.dryInkRenderer.displaySize().y;
+	}
+
+	/** @internal */
+	public getCache() {
+		return this.cache;
+	}
+
+	/**
+	 * @returns the color at the given point on the dry ink renderer, or `null` if `screenPos`
+	 * 	is not on the display.
+	 */
+	public getColorAt = (_screenPos: Point2): Color4|null => {
+		return null;
+	};
+
+	private initializeCanvasRendering() {
+		const dryInkCanvas = document.createElement('canvas');
+		const wetInkCanvas = document.createElement('canvas');
+		const dryInkCtx = dryInkCanvas.getContext('2d')!;
+		const wetInkCtx = wetInkCanvas.getContext('2d')!;
+
+		this.dryInkRenderer = new CanvasRenderer(dryInkCtx, this.editor.viewport);
+		this.wetInkRenderer = new CanvasRenderer(wetInkCtx, this.editor.viewport);
+
+		dryInkCanvas.className = 'dryInkCanvas';
+		wetInkCanvas.className = 'wetInkCanvas';
+
+		if (this.parent) {
+			this.parent.appendChild(dryInkCanvas);
+			this.parent.appendChild(wetInkCanvas);
+		}
+
+		this.resizeSurfacesCallback = () => {
+			const hasSizeMismatch = (canvas: HTMLCanvasElement): boolean => {
+				return canvas.clientHeight !== canvas.height || canvas.clientWidth !== canvas.width;
+			};
+
+			// Ensure that the drawing surfaces sizes match the
+			// canvas' sizes to prevent stretching.
+			if (hasSizeMismatch(dryInkCanvas) || hasSizeMismatch(wetInkCanvas)) {
+				dryInkCanvas.width = dryInkCanvas.clientWidth;
+				dryInkCanvas.height = dryInkCanvas.clientHeight;
+				wetInkCanvas.width = wetInkCanvas.clientWidth;
+				wetInkCanvas.height = wetInkCanvas.clientHeight;
+
+				this.editor.notifier.dispatch(EditorEventType.DisplayResized, {
+					kind: EditorEventType.DisplayResized,
+					newSize: Vec2.of(
+						this.width,
+						this.height,
+					),
+				});
+			}
+		};
+		this.resizeSurfacesCallback();
+
+		this.flattenCallback = () => {
+			dryInkCtx.drawImage(wetInkCanvas, 0, 0);
+		};
+
+		this.getColorAt = (screenPos: Point2) => {
+			const pixel = dryInkCtx.getImageData(screenPos.x, screenPos.y, 1, 1);
+			const data = pixel?.data;
+
+			if (data) {
+				const color = Color4.ofRGBA(data[0] / 255, data[1] / 255, data[2] / 255, data[3] / 255);
+				return color;
+			}
+			return null;
+		};
+	}
+
+	private initializeTextRendering() {
+		const textRendererOutputContainer = document.createElement('div');
+		textRendererOutputContainer.classList.add('textRendererOutputContainer');
+
+		const rerenderButton = document.createElement('button');
+		rerenderButton.classList.add('rerenderButton');
+		rerenderButton.innerText = this.editor.localization.rerenderAsText;
+
+		this.textRerenderOutput = document.createElement('div');
+		this.textRerenderOutput.setAttribute('aria-live', 'polite');
+
+		rerenderButton.onclick = () => {
+			this.rerenderAsText();
+		};
+
+		textRendererOutputContainer.replaceChildren(rerenderButton, this.textRerenderOutput);
+		this.editor.createHTMLOverlay(textRendererOutputContainer);
+	}
+
+	/**
+	 * Rerenders the text-based display.
+	 * The text-based display is intended for screen readers and can be navigated to by pressing `tab`.
+	 */
+	public rerenderAsText() {
+		this.textRenderer.clear();
+		this.editor.image.render(this.textRenderer, this.editor.viewport);
+
+		if (this.textRerenderOutput) {
+			this.textRerenderOutput.innerText = this.textRenderer.getDescription();
+		}
+	}
+
+	/**
+	 * Clears the main drawing surface and otherwise prepares for a rerender.
+	 *
+	 * @returns the dry ink renderer.
+	 */
+	public startRerender(): AbstractRenderer {
+		this.resizeSurfacesCallback?.();
+		this.dryInkRenderer.clear();
+
+		return this.dryInkRenderer;
+	}
+
+	/**
+	 * If `draftMode`, the dry ink renderer is configured to render
+	 * low-quality output.
+	 */
+	public setDraftMode(draftMode: boolean) {
+		this.dryInkRenderer.setDraftMode(draftMode);
+	}
+
+	/** @internal */
+	public getDryInkRenderer(): AbstractRenderer {
+		return this.dryInkRenderer;
+	}
+
+	/**
+	 * @returns The renderer used for showing action previews (e.g. an unfinished stroke).
+	 * The `wetInkRenderer`'s surface is stacked above the `dryInkRenderer`'s.
+	 */
+	public getWetInkRenderer(): AbstractRenderer {
+		return this.wetInkRenderer;
+	}
+
+	/** Re-renders the contents of the wetInkRenderer onto the dryInkRenderer. */
+	public flatten() {
+		this.flattenCallback?.();
+	}
+}

package/src/rendering/RenderingStyle.test.ts

@@ -0,0 +1,68 @@
+
+import Color4 from '../Color4';
+import RenderingStyle, { styleFromJSON, stylesEqual, styleToJSON } from './RenderingStyle';
+
+
+describe('RenderingStyle', () => {
+	it('identical styles should be equal', () => {
+		const redFill: RenderingStyle = {
+			fill: Color4.red,
+		};
+		expect(stylesEqual(redFill, redFill)).toBe(true);
+		expect(stylesEqual(
+			{ fill: Color4.ofRGB(1, 0, 0.3), },
+			{ fill: Color4.ofRGB(1, 0, 0.3), },
+		)).toBe(true);
+		expect(stylesEqual(
+			{ fill: Color4.red },
+			{ fill: Color4.blue },
+		)).toBe(false);
+
+		expect(stylesEqual(
+			{ fill: Color4.red, stroke: { width: 1, color: Color4.red }},
+			{ fill: Color4.red },
+		)).toBe(false);
+		expect(stylesEqual(
+			{ fill: Color4.red, stroke: { width: 1, color: Color4.red }},
+			{ fill: Color4.red, stroke: { width: 1, color: Color4.blue }},
+		)).toBe(false);
+		expect(stylesEqual(
+			{ fill: Color4.red, stroke: { width: 1, color: Color4.red }},
+			{ fill: Color4.red, stroke: { width: 1, color: Color4.red }},
+		)).toBe(true);
+		expect(stylesEqual(
+			{ fill: Color4.red, stroke: { width: 1, color: Color4.red }},
+			{ fill: Color4.red, stroke: { width: 2, color: Color4.red }},
+		)).toBe(false);
+	});
+
+	it('styles should be convertable to JSON', () => {
+		expect(styleToJSON({
+			fill: Color4.red,
+		})).toMatchObject({
+			fill: '#ff0000',
+			stroke: undefined,
+		});
+
+		expect(styleToJSON({
+			fill: Color4.blue,
+			stroke: {
+				width: 4,
+				color: Color4.red,
+			}
+		})).toMatchObject({
+			fill: '#0000ff',
+			stroke: {
+				width: 4,
+				color: '#ff0000'
+			},
+		});
+	});
+
+	it('JSON should be convertable into styles', () => {
+		const redFillJSON = { fill: '#ff0000', };
+		const redFillBlueStrokeJSON = { fill: '#ff0000', stroke: { width: 4, color: '#0000ff' }};
+		expect(styleToJSON(styleFromJSON(redFillJSON))).toMatchObject(redFillJSON);
+		expect(styleToJSON(styleFromJSON(redFillBlueStrokeJSON))).toMatchObject(redFillBlueStrokeJSON);
+	});
+});

package/src/rendering/RenderingStyle.ts

@@ -0,0 +1,55 @@
+import Color4 from '../Color4';
+
+interface RenderingStyle {
+	readonly fill: Color4;
+	readonly stroke?: {
+		readonly color: Color4;
+		readonly width: number;
+	};
+}
+
+export default RenderingStyle;
+
+export const cloneStyle = (style: RenderingStyle) => {
+	return {
+		fill: style.fill,
+		stroke: style.stroke ? {
+			...style.stroke
+		} : undefined,
+	};
+};
+
+export const stylesEqual = (a: RenderingStyle, b: RenderingStyle): boolean => {
+	const result = a === b || (a.fill.eq(b.fill)
+		&& (a.stroke == undefined) === (b.stroke == undefined)
+		&& (a.stroke?.color?.eq(b.stroke?.color) ?? true)
+		&& a.stroke?.width === b.stroke?.width);
+
+	// Map undefined/null -> false
+	return result ?? false;
+};
+
+// Returns an object that can be converted to a JSON string with
+// JSON.stringify.
+export const styleToJSON = (style: RenderingStyle) => {
+	const stroke = !style.stroke ? undefined : {
+		color: style.stroke.color.toHexString(),
+		width: style.stroke.width,
+	};
+
+	return {
+		fill: style.fill.toHexString(),
+		stroke,
+	};
+};
+
+export const styleFromJSON = (json: Record<string, any>) => {
+	const stroke = json.stroke ? {
+		color: Color4.fromHex(json.stroke.color),
+		width: json.stroke.width,
+	} : undefined;
+	return {
+		fill: Color4.fromHex(json.fill),
+		stroke,
+	};
+};

package/src/rendering/TextRenderingStyle.ts

@@ -0,0 +1,55 @@
+import RenderingStyle, { cloneStyle, styleFromJSON, styleToJSON } from './RenderingStyle';
+
+export interface TextRenderingStyle {
+	readonly size: number;
+
+	/** Name of the font. */
+	readonly fontFamily: string;
+
+	/** For example, `bold`. Like CSS `font-weight`. */
+	readonly fontWeight?: string;
+
+	/** For example, `italic`. Like CSS `font-style`. */
+	readonly fontStyle?: string;
+
+	readonly fontVariant?: string;
+
+	/** Fill and stroke of the text. */
+	readonly renderingStyle: RenderingStyle;
+}
+
+export default TextRenderingStyle;
+
+export const cloneTextStyle = (style: TextRenderingStyle) => {
+	return {
+		...style,
+		renderingStyle: cloneStyle(style.renderingStyle),
+	};
+};
+
+export const textStyleFromJSON = (json: any) => {
+	if (typeof json === 'string') {
+		json = JSON.parse(json);
+	}
+
+	if (typeof(json.fontFamily) !== 'string') {
+		throw new Error('Serialized textStyle missing string fontFamily attribute!');
+	}
+
+	const style: TextRenderingStyle = {
+		renderingStyle: styleFromJSON(json.renderingStyle),
+		size: json.size,
+		fontWeight: json.fontWeight,
+		fontVariant: json.fontVariant,
+		fontFamily: json.fontFamily,
+	};
+
+	return style;
+};
+
+export const textStyleToJSON = (style: TextRenderingStyle) => {
+	return {
+		...style,
+		renderingStyle: styleToJSON(style.renderingStyle),
+	};
+};

package/src/rendering/caching/CacheRecord.test.ts

@@ -0,0 +1,49 @@
+/* @jest-environment jsdom */
+
+import Rect2 from '../../math/shapes/Rect2';
+import { Vec2 } from '../../math/Vec2';
+import CacheRecord from './CacheRecord';
+import { createCache } from './testUtils';
+
+describe('CacheRecord', () => {
+	describe('should map points in the cache renderer\'s region to the cache renderer', () => {
+		const blockResolution = Vec2.of(500, 500);
+		const { cache } = createCache(undefined, {
+			blockResolution,
+		});
+		const state = cache['sharedState'];
+
+		const record = new CacheRecord(() => {}, state);
+
+		describe('region has top left at (0, 0)', () => {
+			it('region as big as the cache block', () => {
+				const transform = record.getTransform(
+					new Rect2(0, 0, 500, 500)
+				);
+				expect(transform.transformVec2(Vec2.unitX)).toMatchObject(Vec2.unitX);
+				expect(transform.transformVec2(Vec2.unitY)).toMatchObject(Vec2.unitY);
+			});
+
+			it('region twice as big as cache block', () => {
+				const transform = record.getTransform(
+					new Rect2(0, 0, 1000, 1000)
+				);
+
+				// A size-one vector on the screen corresponds to a size 1/2 vector on the
+				// cached surface.
+				expect(transform.transformVec2(Vec2.unitX)).toMatchObject(Vec2.of(0.5, 0));
+				expect(transform.transformVec2(Vec2.unitY)).toMatchObject(Vec2.of(0, 0.5));
+			});
+		});
+
+		describe('region has top left at (100, 100)', () => {
+			it('region as big as the cache block', () => {
+				const transform = record.getTransform(
+					new Rect2(100, 100, 500, 500)
+				);
+				expect(transform.transformVec2(Vec2.of(100, 100))).toMatchObject(Vec2.zero);
+				expect(transform.transformVec2(Vec2.of(500, 500))).toMatchObject(Vec2.of(400, 400));
+			});
+		});
+	});
+});

package/src/rendering/caching/CacheRecord.ts

@@ -0,0 +1,77 @@
+import Mat33 from '../../math/Mat33';
+import Rect2 from '../../math/shapes/Rect2';
+import AbstractRenderer from '../renderers/AbstractRenderer';
+import { BeforeDeallocCallback, CacheState } from './types';
+
+// Represents a cached renderer/canvas
+// This is not a [CacheNode] -- it handles cached renderers and does not have sub-renderers.
+
+export default class CacheRecord {
+	private renderer: AbstractRenderer;
+	private lastUsedCycle: number;
+	private allocd: boolean = false;
+
+	// For debugging
+	public allocCount: number = 0;
+
+	public constructor(
+		private onBeforeDeallocCallback: BeforeDeallocCallback|null,
+		private cacheState: CacheState,
+	) {
+		this.renderer = cacheState.props.createRenderer();
+		this.lastUsedCycle = -1;
+		this.allocd = true;
+	}
+
+	public startRender(): AbstractRenderer {
+		this.lastUsedCycle = this.cacheState.currentRenderingCycle;
+		if (!this.allocd) {
+			throw new Error('Only alloc\'d canvases can be rendered to');
+		}
+		return this.renderer;
+	}
+
+	public dealloc() {
+		this.onBeforeDeallocCallback?.();
+		this.allocd = false;
+		this.onBeforeDeallocCallback = null;
+		this.lastUsedCycle = 0;
+	}
+
+	public isAllocd() {
+		return this.allocd;
+	}
+
+	public realloc(newDeallocCallback: BeforeDeallocCallback) {
+		if (this.allocd) {
+			this.dealloc();
+		}
+		this.allocd = true;
+		this.onBeforeDeallocCallback = newDeallocCallback;
+		this.lastUsedCycle = this.cacheState.currentRenderingCycle;
+		this.allocCount ++;
+	}
+
+	public getLastUsedCycle(): number {
+		return this.lastUsedCycle;
+	}
+
+	// Returns the transformation that maps [drawTo] to this' renderable region
+	// (i.e. a [cacheProps.blockResolution]-sized rectangle with top left at (0, 0))
+	public getTransform(drawTo: Rect2): Mat33 {
+		const transform = Mat33.scaling2D(
+			this.cacheState.props.blockResolution.x / drawTo.size.x
+		).rightMul(
+			Mat33.translation(drawTo.topLeft.times(-1))
+		);
+
+		return transform;
+	}
+
+	public setRenderingRegion(drawTo: Rect2) {
+		this.renderer.setTransform(
+			// Invert to map objects instead of the viewport
+			this.getTransform(drawTo)
+		);
+	}
+}

package/src/rendering/caching/CacheRecordManager.ts

@@ -0,0 +1,71 @@
+import { BeforeDeallocCallback, CacheProps, CacheState } from './types';
+import CacheRecord from './CacheRecord';
+import Rect2 from '../../math/shapes/Rect2';
+
+const debugMode = false;
+
+export class CacheRecordManager {
+	// Fixed-size array: Cache blocks are assigned indicies into [cachedCanvases].
+	private cacheRecords: CacheRecord[] = [];
+	private maxCanvases: number;
+	private cacheState: CacheState;
+
+	public constructor(cacheProps: CacheProps) {
+		this.maxCanvases = Math.ceil(
+			// Assuming four components per pixel:
+			cacheProps.cacheSize / 4 / cacheProps.blockResolution.x / cacheProps.blockResolution.y
+		);
+	}
+
+	public setSharedState(state: CacheState) {
+		this.cacheState = state;
+	}
+
+	public allocCanvas(drawTo: Rect2, onDealloc: BeforeDeallocCallback): CacheRecord {
+		if (this.cacheRecords.length < this.maxCanvases) {
+			const record: CacheRecord = new CacheRecord(
+				onDealloc,
+				this.cacheState,
+			);
+			record.setRenderingRegion(drawTo);
+			this.cacheRecords.push(record);
+
+			if (debugMode) {
+				console.log('[Cache] Cache spaces used: ', this.cacheRecords.length, ' of ', this.maxCanvases);
+			}
+
+			return record;
+		} else {
+			const lru = this.getLeastRecentlyUsedRecord()!;
+
+			if (debugMode) {
+				console.log(
+					'[Cache] Re-alloc. Times allocated: ', lru.allocCount,
+					'\nLast used cycle: ', lru.getLastUsedCycle(),
+					'\nCurrent cycle: ', this.cacheState.currentRenderingCycle
+				);
+			}
+
+			lru.realloc(onDealloc);
+			lru.setRenderingRegion(drawTo);
+
+			if (debugMode) {
+				console.log(
+					'[Cache] Now re-alloc\'d. Last used cycle: ', lru.getLastUsedCycle()
+				);
+				console.assert(
+					lru['cacheState'] === this.cacheState,
+					'[Cache] Unequal cache states! cacheState should be a shared object!'
+				);
+			}
+
+			return lru;
+		}
+	}
+
+	// Returns null if there are no cache records. Returns an unalloc'd record if one exists.
+	private getLeastRecentlyUsedRecord(): CacheRecord|null {
+		this.cacheRecords.sort((a, b) => a.getLastUsedCycle() - b.getLastUsedCycle());
+		return this.cacheRecords[0];
+	}
+}

package/src/rendering/caching/RenderingCache.test.ts

@@ -0,0 +1,44 @@
+/* @jest-environment jsdom */
+
+import DummyRenderer from '../renderers/DummyRenderer';
+import { createCache } from './testUtils';
+import Stroke from '../../components/Stroke';
+import Path from '../../math/shapes/Path';
+import Color4 from '../../Color4';
+import EditorImage from '../../EditorImage';
+import Viewport from '../../Viewport';
+import Mat33 from '../../math/Mat33';
+
+describe('RenderingCache', () => {
+	const testPath = Path.fromString('M0,0 l100,500 l-20,20 L-100,-100');
+	const testStroke = new Stroke([ testPath.toRenderable({ fill: Color4.purple }) ]);
+
+	it('should create a root node large enough to contain the viewport', () => {
+		let lastRenderer: DummyRenderer|null = null;
+		let allocdRenderers: number = 0;
+
+		const { editor, cache } = createCache((renderer) => {
+			allocdRenderers ++;
+			lastRenderer = renderer;
+		});
+		const screenRenderer = editor.display.getDryInkRenderer() as DummyRenderer;
+
+		// No objects: Should not create a renderer.
+		expect(lastRenderer).toBeNull();
+		editor.image.renderWithCache(screenRenderer, cache, editor.viewport);
+		expect(lastRenderer).toBeNull();
+
+		editor.dispatch(EditorImage.addElement(testStroke));
+		editor.image.renderWithCache(screenRenderer, cache, editor.viewport);
+
+		expect(allocdRenderers).toBeGreaterThanOrEqual(1);
+		expect(lastRenderer).not.toBeNull();
+		expect(lastRenderer!.renderedPathCount).toBe(1);
+
+		editor.dispatch(Viewport.transformBy(Mat33.scaling2D(0.1)));
+		editor.image.renderWithCache(screenRenderer, cache, editor.viewport);
+		expect(allocdRenderers).toBe(1);
+		expect(lastRenderer!.renderedPathCount).toBe(1);
+		expect(screenRenderer.renderedPathCount).toBeGreaterThanOrEqual(1);
+	});
+});