Render 2D canvas content at large coordinates with ease.
When rendering 2D canvas content at large coordinates, you may experience issues with precision. For example, drawing a horizontal line from (100_000_000, 0.5)
to (100_000_001, 0.5)
may render a diagonal line, or no line at all.
Far Canvas is a wrapper around the HTML5 2D canvas API that avoids precision issues at large coordinates.
Far Canvas now supports all Canvas 2D transform operations! When running in a modern browser or environment with full Canvas 2D support, far-canvas will automatically use a Transform-Aware implementation that:
- ✅ Supports
translate()
,rotate()
,scale()
,transform()
,setTransform()
, andresetTransform()
- ✅ Supports
getTransform()
to retrieve the current transformation matrix - ✅ Leverages hardware-accelerated native Canvas transforms for better performance
- ✅ Maintains the same precision guarantees for large coordinates
- ✅ Falls back gracefully to coordinate transformation when transforms aren't available
import { far } from "@nextml/far-canvas";
const canvas = document.getElementById("myCanvas");
const ctx = far(canvas, {
x: 100_000_000, // Render with huge coordinate offset
y: 100_000_000,
scale: 2,
}).getContext("2d");
// All transform operations now work!
ctx.save();
ctx.translate(50, 50);
ctx.rotate(Math.PI / 4);
ctx.scale(1.5, 1.5);
ctx.fillRect(-25, -25, 50, 50);
ctx.restore();
// Draw at world coordinates - far-canvas handles the offset
ctx.fillStyle = "red";
ctx.fillRect(100_000_000, 100_000_000, 100, 100);
import { far } from "@nextml/far-canvas";
const canvas = document.getElementById("myCanvas");
const myFarCanvas = far(canvas, {
x: 100_000_000,
y: 0,
scale: 2,
});
const context = myFarCanvas.getContext("2d");
// This will be a horizontal line!
context.strokeStyle = "red";
context.beginPath();
context.moveTo(100_000_000, 0.5);
context.lineTo(100_000_001, 0.5);
context.stroke();
npm install @nextml/far-canvas
Creates a far canvas instance. Options are:
x
: The x offset to apply to all drawing operations (default: 0)y
: The y offset to apply to all drawing operations (default: 0)scale
: The scale to apply to all drawing operations (default: 1)
The far canvas instance has a single method:
getContext( '2d' )
: Returns aFarCanvasRenderingContext2D
The far canvas rendering context implements the full CanvasRenderingContext2D
interface, with the following additions:
clearCanvas()
: Clears the entire canvas (ignoring any transforms)canvasDimensions
: Returns the dimensions of the canvas in the far coordinate system
When transform support is available (modern browsers), all transform methods work as expected. In fallback mode, the following methods will throw an error:
translate()
,rotate()
,scale()
,transform()
,setTransform()
,resetTransform()
,getTransform()
Far Canvas uses two approaches depending on the environment:
Uses Canvas 2D's native transform matrix to efficiently handle large coordinate offsets:
- Applies a hybrid approach: coordinate transformation for far-canvas offset, native transforms for user operations
- All drawing operations transform coordinates in JavaScript to avoid precision issues
- Leverages hardware acceleration for user transforms when available
- Supports all transform operations seamlessly
Falls back to coordinate transformation:
- Intercepts all drawing calls and transforms coordinates before passing to the underlying context
- Ensures compatibility with older browsers or limited Canvas implementations
- Transform operations are not supported in this mode
The appropriate mode is automatically selected based on feature detection.
Apache-2.0