cunev-skia-canvas

---

---

Skia Canvas is a browser-less implementation of the HTML Canvas drawing API for Node.js. It is based on Google’s Skia graphics engine and, accordingly, produces very similar results to Chrome’s element. The library is well suited for use on desktop machines where you can render hardware-accelerated graphics to a window and on the server where it can output a variety of image formats.

While the primary goal of this project is to provide a reliable emulation of the standard API according to the spec, it also extends it in a number of areas to take greater advantage of Skia's advanced graphical features and provide a more expressive coding environment.

In particular, Skia Canvas:

- is fast and compact since rendering takes place on the GPU and all the heavy lifting is done by native code written in Rust and C++
- can render to [windows][window] using an OS-native graphics pipeline and provides a browser-like [UI event][win_bind] framework
- generates images in both raster (JPEG, PNG, & WEBP) and vector (PDF & SVG) formats
- can save images to [files][saveAs], return them as [Buffers][toBuffer], or encode [dataURL][toDataURL_ext] strings
- uses native threads in a [user-configurable][multithreading] worker pool for asynchronous rendering and file I/O
- can create [multiple ‘pages’][newPage] on a given canvas and then [output][saveAs] them as a single, multi-page PDF or an image-sequence saved to multiple files
- can [simplify][p2d_simplify], [blunt][p2d_round], [combine][bool-ops], [excerpt][p2d_trim], and [atomize][p2d_points] bézier paths using efficient boolean operations or point-by-point [interpolation][p2d_interpolate]
- provides [3D perspective][createProjection()] transformations in addition to [scaling][scale()], [rotation][rotate()], and [translation][translate()]
- can fill shapes with vector-based [Textures][createTexture()] in addition to bitmap-based [Patterns][createPattern()] and supports line-drawing with custom [markers][lineDashMarker]
- supports the full set of [CSS filter][filter] image processing operators
- offers rich typographic control including:
- multi-line, [word-wrapped][textwrap] text
- line-by-line [text metrics][c2d_measuretext]
- small-caps, ligatures, and other opentype features accessible using standard [font-variant][fontvariant] syntax
- proportional [letter-spacing][letterSpacing], [word-spacing][wordSpacing], and [leading][c2d_font]
- support for [variable fonts][VariableFonts] and transparent mapping of weight values
- use of non-system fonts [loaded][fontlibrary-use] from local files

Installation

If you’re running on a supported platform, installation should be as simple as:
``bash
npm install skia-canvas
`

This will download a pre-compiled library from the project’s most recent release.

Platform Support

The underlying Rust library uses [N-API][node_napi] v8 which allows it to run on Node.js versions:
- v12.22+
- v14.17+
- v15.12+
- v16.0.0 and later

Pre-compiled binaries are available for:

- Linux (x64 & arm64)
- macOS (x64 & Apple silicon)
- Windows (x64)

Nearly everything you need is statically linked into the library. A notable exception is the Fontconfig library which must be installed separately if you’re running on Linux.

Running in Docker

The library is compatible with Linux systems using glibc 2.28 or later as well as Alpine Linux (x64 & arm64) and the musl C library it favors. In both cases, Fontconfig must be installed on the system for skia-canvas to operate correctly.

If you are setting up a Dockerfile that uses node as its basis, the simplest approach is to set your FROM image to one of the (Debian-derived) defaults like node:lts, node:18, node:16, node:14-buster, node:12-buster, node:bullseye, node:buster, or simply:
`dockerfile
FROM node
`

You can also use the ‘slim’ image if you manually install fontconfig:

`dockerfile
FROM node:slim
RUN apt-get update && apt-get install -y -q --no-install-recommends libfontconfig1
`

If you wish to use Alpine as the underlying distribution, you can start with something along the lines of:

`dockerfile
FROM node:alpine
RUN apk update && apk add fontconfig
`

Compiling from Source

If prebuilt binaries aren’t available for your system you’ll need to compile the portions of this library that directly interface with Skia.

Start by installing:

1. The Rust compiler and cargo package manager using rustup
2. A C compiler toolchain (either LLVM/Clang or MSVC)
4. Python 3 (used by Skia's build process)
3. The Ninja build system
5. On Linux: Fontconfig and OpenSSL

Detailed instructions for setting up these dependencies on different operating systems can be found in the ‘Building’ section of the Rust Skia documentation. Once all the necessary compilers and libraries are present, running npm run build will give you a usable library (after a fairly lengthy compilation process).

Multithreading

When rendering canvases in the background (e.g., by using the asynchronous [saveAs][saveAs] or [toBuffer][toBuffer] methods), tasks are spawned in a thread pool managed by the [rayon][rayon] library. By default it will create up to as many threads as your CPU has cores. You can see this default value by inspecting any [Canvas][canvas] object's [engine.threads][engine] property. If you wish to override this default, you can set the SKIA_CANVAS_THREADS environment variable to your preferred value.

For example, you can limit your asynchronous processing to two simultaneous tasks by running your script with:
`bash
SKIA_CANVAS_THREADS=2 node my-canvas-script.js
`

Example Usage

$3

`js
import {Canvas} from 'skia-canvas'

let canvas = new Canvas(400, 400),
ctx = canvas.getContext("2d"),
{width, height} = canvas;

let sweep = ctx.createConicGradient(Math.PI * 1.2, width/2, height/2)
sweep.addColorStop(0, "red")
sweep.addColorStop(0.25, "orange")
sweep.addColorStop(0.5, "yellow")
sweep.addColorStop(0.75, "green")
sweep.addColorStop(1, "red")
ctx.strokeStyle = sweep
ctx.lineWidth = 100
ctx.strokeRect(100,100, 200,200)

// render to multiple destinations using a background thread
async function render(){
// save a ‘retina’ image...
await canvas.saveAs("rainbox.png", {density:2})
// ...or use a shorthand for canvas.toBuffer("png")
let pngData = await canvas.png
// ...or embed it in a string
let pngEmbed =
}
render()

// ...or save the file synchronously from the main thread
canvas.saveAsSync("rainbox.pdf")
`

$3

`js
import {Canvas} from 'skia-canvas'

let canvas = new Canvas(400, 400),
ctx = canvas.getContext("2d"),
{width, height} = canvas

for (const color of ['orange', 'yellow', 'green', 'skyblue', 'purple']){
ctx = canvas.newPage()
ctx.fillStyle = color
ctx.fillRect(0,0, width, height)
ctx.fillStyle = 'white'
ctx.arc(width/2, height/2, 40, 0, 2 * Math.PI)
ctx.fill()
}

async function render(){
// save to a multi-page PDF file
await canvas.saveAs("all-pages.pdf")

// save to files named page-01.png, page-02.png, etc.
await canvas.saveAs("page-{2}.png")
}
render()
`

$3

`js
import {Window} from 'skia-canvas'

let win = new Window(300, 300)
win.title = "Canvas Window"
win.on("draw", e => {
let ctx = e.target.canvas.getContext("2d")
ctx.lineWidth = 25 + 25 * Math.cos(e.frame / 10)
ctx.beginPath()
ctx.arc(150, 150, 50, 0, 2 * Math.PI)
ctx.stroke()

ctx.beginPath()
ctx.arc(150, 150, 10, 0, 2 * Math.PI)
ctx.stroke()
ctx.fill()
})
``

Acknowledgements

This project is deeply indebted to the work of the Rust Skia project whose Skia bindings provide a safe and idiomatic interface to the mess of C++ that lies underneath. Many thanks to the developers of node-canvas for their terrific set of unit tests. In the absence of an Acid Test for canvas, these routines were invaluable.

$3

- @mpaparno contributed support for SVG rendering, raw image-buffer handling, WEBP import/export and numerous bugfixes
- @Salmondx & @ggolda developed the initial Raw image loading & rendering routines
- @lucasmerlin helped get GPU rendering working on Vulkan
- @cprecioso & @saantonandre corrected and expanded upon the TypeScript type definitions
- @meihuanyu contributed filter & path rendering fixes

Copyright

© 2020–2024 Samizdat Drafting Co.

[bool-ops]: https://skia-canvas.org/api/path2d#complement-difference-intersect-union-and-xor
[c2d_font]: https://skia-canvas.org/api/context#font
[c2d_measuretext]: https://skia-canvas.org/api/context#measuretext
[canvas]: https://skia-canvas.org/api/canvas
[createProjection()]: https://skia-canvas.org/api/context#createprojection
[createTexture()]: https://skia-canvas.org/api/context#createtexture
[engine]: https://skia-canvas.org/api/canvas#engine
[fontlibrary-use]: https://skia-canvas.org/api/font-library#use
[fontvariant]: https://skia-canvas.org/api/context#fontvariant
[lineDashMarker]: https://skia-canvas.org/api/context#linedashmarker
[newPage]: https://skia-canvas.org/api/canvas#newpage
[p2d_interpolate]: https://skia-canvas.org/api/path2d#interpolate
[p2d_points]: https://skia-canvas.org/api/path2d#points
[p2d_round]: https://skia-canvas.org/api/path2d#round
[p2d_simplify]: https://skia-canvas.org/api/path2d#simplify
[p2d_trim]: https://skia-canvas.org/api/path2d#trim
[saveAs]: https://skia-canvas.org/api/canvas#saveas
[textwrap]: https://skia-canvas.org/api/context#textwrap
[toBuffer]: https://skia-canvas.org/api/canvas#tobuffer
[toDataURL_ext]: https://skia-canvas.org/api/canvas#todataurl
[win_bind]: https://skia-canvas.org/api/window#on--off--once
[window]: https://skia-canvas.org/api/window
[multithreading]: https://skia-canvas.org/getting-started#multithreading
[node_napi]: https://nodejs.org/api/n-api.html#node-api-version-matrix
[rayon]: https://crates.io/crates/rayon
[VariableFonts]: https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Fonts/Variable_Fonts_Guide
[filter]: https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/filter
[letterSpacing]: https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/letterSpacing
[wordSpacing]: https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/wordSpacing
[createPattern()]: https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/createPattern
[rotate()]: https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/rotate
[scale()]: https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/scale
[translate()]: https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/translate