skia-canvas 0.9.24 → 0.9.28

package/CHANGELOG.md

@@ -0,0 +1,195 @@
+# Changelog
+
+<!-- ## 🥚 ⟩ [Unreleased]  -->
+
+## 📦 ⟩ [v0.9.28] ⟩ Jan 12, 2022
+
+### New Features
+- Added TypeScript definitions for extensions to the DOM spec (contributed by [@cprecioso](https://github.com/cprecioso))
+- Added 3D-perspective transformations via the new [createProjection()](https://github.com/samizdatco/skia-canvas#createprojectionquad-basis) context method
+- Colors can now use the [hwb()](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value/hwb()) model
+
+### Breaking Changes
+- The **Canvas** [`.async`](https://github.com/samizdatco/skia-canvas#async) property has been **deprecated** and will be removed in a future release. 
+  - The `saveAs`, `toBuffer`, and `toDataURL` methods will now be async-only (likewise the [shorthand properties](https://github.com/samizdatco/skia-canvas#pdf-svg-jpg-and-png)).
+  - Use their synchronous counterparts (`saveAsSync`, `toBufferSync`, and `toDataURLSync`) if you want to block execution while exporting images.
+- The [ImageData](https://developer.mozilla.org/en-US/docs/Web/API/ImageData/ImageData) constructor now orders its arguments properly: the optional buffer/array argument now comes first
+
+### Bugfixes
+- Fixed a stack overflow that was occurring when images became too deeply nested for the default deallocator to handle (primarily due to many thousands of image exports from the same canvas)
+- The `source-in`, `source-out`, `destination-atop`, and `copy` composite operations now work correctly for paths rather than rendering shapes without color (contributed by [@meihuanyu](https://github.com/meihuanyu))
+- Shape primitives now behave consistently with browsers when being added to a non-empty path:
+  - `rect()` now issues an initial `moveTo` rather than extending the path, then leaves the ‘current’ point in its upper left corner
+  - `ellipse()` extends the current path rather than implicitly closing it (contributed by [@meihuanyu](https://github.com/meihuanyu))
+  - `arc()` also extends the current path rather than closing it
+
+### Misc. Improvements
+- Upgraded Skia to milestone 96
+- Added workflow for creating docker build environments
+
+
+## 📦 ⟩ [v0.9.27] ⟩ Oct 23, 2021
+ 
+### New Features
+- Added pre-compiled binaries for Alpine Linux using the [musl](https://musl.libc.org) C library
+
+
+## 📦 ⟩ [v0.9.26] ⟩ Oct 18, 2021
+
+### New Features
+- Added pre-compiled binaries for 32-bit and 64-bit ARM on Linux (a.k.a. Raspberry Pi)
+
+### Bugfixes
+- Windows text rendering has been restored after failing due to changes involving the `icudtl.dat` file
+- `FontLibrary.use` now reports an error if the specified font file doesn't exist 
+- Fixed a crash that could result from calling `measureText` with various unicode escapes
+
+### Misc. Improvements
+- Upgraded Skia to milestone 94
+- Now embedding a more recent version of the FreeType library on Linux with support for more font formats
+
+
+## 📦 ⟩ [v0.9.25] ⟩ Aug 22, 2021
+
+### Bugfixes
+- Improved image scaling when a larger image is being shrunk down to a smaller size via [`drawImage()`](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/drawImage)
+- modified [`imageSmoothingQuality`](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/imageSmoothingQuality) settings to provide a more meaningful range across `low`, `medium`, and `high`
+- [`measureText()`](https://github.com/samizdatco/skia-canvas#measuretextstr-width) now returns correct metrics regardless of current `textAlign` setting
+- Rolled back `icudtl.dat` changes on Windows (which suppressed the misleading warning message but required running as Administrator)
+
+### Misc. Improvements
+- Now using [Neon](https://github.com/neon-bindings/neon) v0.9 (with enhanced async event scheduling)
+
+
+## 📦 ⟩ [v0.9.24] ⟩ Aug 18, 2021
+
+### New Features
+- **Path2D** objects now have a read/write [`d`](https://github.com/samizdatco/skia-canvas/#d) property with an [SVG representation](https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/d#path_commands) of the path’s contours and an [`unwind()`](https://github.com/samizdatco/skia-canvas/#unwind) method for converting from even-odd to non-zero winding rules
+- The [`createTexture()`](https://github.com/samizdatco/skia-canvas#createtexturespacing-path-line-color-angle-offset0) context method returns **CanvasTexture** objects which can be assigned to `fillStyle` or `strokeStyle`
+- Textures draw either a parallel-lines pattern or one derived from the provided **Path2D** object and positioning parameters
+- The marker used when `setLineDash` is active can now be customized by assigning a **Path2D** to the context’s [`lineDashMarker`](https://github.com/samizdatco/skia-canvas#linedashmarker) property (default dashing can be restored by assigning `null`)
+- The marker’s orientation & shape relative to the path being stroked can be controlled by the [`lineDashFit`](https://github.com/samizdatco/skia-canvas#linedashfit) property which defaults to `"turn"` but can be set to `"move"` (which preserves orientation) or `"follow"` (which distorts the marker’s shape to match the contour)
+
+### Bugfixes
+
+- Removed use of the `??` operator which is unavailable prior to Node 14
+- Prevented a spurious warning on windows incorrectly claiming that the `icudtl.dat` file could not be found
+
+### Misc. Improvements
+
+- The **Path2D** [`simplify()`](https://github.com/samizdatco/skia-canvas/#simplifyrulenonzero) method now takes an optional fill-rule argument
+- Added support for versions of macOS starting with 10.13 (High Sierra)
+
+
+## 📦 ⟩ [v0.9.23] ⟩ Jul 12, 2021
+
+### New Features
+
+- [Conic béziers][conic_bezier] can now be drawn to the context or a Path2D with the [`conicCurveTo()`][conic_curveto] method
+- Text can be converted to a Path2D using the context’s new [`outlineText()`][outline_text] method
+- Path2D objects can now report back on their internal geometry with:
+    - the [`edges`][edges] property which contains an array of line-drawing commands describing the path’s individual contours
+    - the [`contains()`][contains] method which tests whether a given point is on/within the path
+    - the [`points()`][points] method which returns an array of `[x, y]` pairs at the requested spacing along the curve’s periphery
+- A modified copy of a source Path2D can now be created using:
+    - [`offset()`][offset] or [`transform()`][transform] to shift position or apply a DOMMatrix respectively
+    - [`jitter()`][jitter] to break the path into smaller sections and apply random noise to the segments’ positions
+    - [`round()`][round] to round off every sharp corner in a path to a particular radius
+    - [`trim()`][trim] to select a percentage-based subsection of the path
+- Two similar paths can be ‘tweened’ into a proportional combination of their coordinates using the [`interpolate()`][interpolate] method
+
+### Bugfixes
+
+- Passing a Path2D argument to the `fill()` or `stroke()` method no longer disturbs the context’s ‘current’ path (if one has been created using `beginPath()`)
+- The `filter` property will now accept percentage values greater than 999%
+
+### Misc. Improvements
+
+- The `newPage()` and `saveAs()` methods now work in the browser, including the ability to save image sequences to a zip archive. The browser’s canvas is still doing all the drawing however, so file export formats will be limited to PNG and JPEG and none of the other Skia-specific extensions will be available.
+- The file-export methods now accept a [`matte`][matte] value in their options object which can be used to set the background color for any portions of the canvas that were left semi-transparent 
+- Canvas dimensions are no longer rounded-off to integer values (at least until a bitmap needs to be generated for export)
+- Linux builds will now run on some older systems going back to glibc 2.24
+
+[conic_bezier]: https://docs.microsoft.com/en-us/xamarin/xamarin-forms/user-interface/graphics/skiasharp/curves/beziers#the-conic-bézier-curve
+[conic_curveto]: https://github.com/samizdatco/skia-canvas#coniccurvetocpx-cpy-x-y-weight
+[outline_text]: https://github.com/samizdatco/skia-canvas#outlinetextstr
+[matte]: https://github.com/samizdatco/skia-canvas#matte
+
+[edges]: https://github.com/samizdatco/skia-canvas#edges
+[contains]: https://github.com/samizdatco/skia-canvas#containsx-y
+[points]: https://github.com/samizdatco/skia-canvas#pointsstep1
+[offset]: https://github.com/samizdatco/skia-canvas#offsetdx-dy
+[transform]: https://github.com/samizdatco/skia-canvas#transformmatrix-or-transforma-b-c-d-e-f
+
+[interpolate]: https://github.com/samizdatco/skia-canvas#interpolateotherpath-weight
+[jitter]: https://github.com/samizdatco/skia-canvas#jittersegmentlength-amount-seed0
+[round]: https://github.com/samizdatco/skia-canvas#roundradius
+[simplify]: https://github.com/samizdatco/skia-canvas#simplify
+[trim]: https://github.com/samizdatco/skia-canvas#trimstart-end-inverted
+
+
+## 📦 ⟩ [v0.9.22] ⟩ Jun 09, 2021
+
+### New Features
+
+- Rasterization and file i/o are now handled asynchronously in a background thread. See the discussion of Canvas’s new [`async`](https://github.com/samizdatco/skia-canvas#async) property for details.
+- Output files can now be generated at pixel-ratios > 1 for High-DPI screens. `SaveAs` and the other canvas output functions all accept an optional [`density`](https://github.com/samizdatco/skia-canvas#density) argument which is an integer ≥1 and will upscale the image accordingly. The density can also be passed using the `filename` argument by ending the name with an ‘@’ suffix like `some-image@2x.png`. 
+- SVG exports can optionally convert text to paths by setting the [`outline`](https://github.com/samizdatco/skia-canvas#outline) argument to `true`.
+
+### Breaking Changes
+
+- The canvas functions dealing with rasterization (`toBuffer`, `toDataURL`, `png`, `jpg`, `pdf`, and `svg`) and file i/o (`saveAs`) are now asynchronous and return `Promise` objects. The old, synchronous behavior is still available on a canvas-by-canvas basis by setting its `async` property to `false`.
+- The optional `quality` argument accepted by the output methods is now a float in the range 0–1 rather than an integer from 0–100. This is consistent with the [encoderOptions](https://developer.mozilla.org/en-US/docs/Web/API/HTMLCanvasElement/toDataURL) arg in the spec. Quality now defaults to 0.92 (again, as per the spec) rather than lossless.
+
+### Bugfixes
+
+- `measureText` was reporting zero when asked to measure a string that was entirely made of whitespace. This is still the case for ‘blank‘ lines when `textWrap` is set to `true` but in the default, single-line mode the metrics will now report the width of the whitespace.
+-  Changed the way text rendering was staged so that SVG exports didn’t *entirely omit(!)* text from their output. As a result, `Context2D`s now use an external `Typesetter` struct to manage layout and rendering.
+
+
+## 📦 ⟩ [v0.9.21] ⟩ May 22, 2021
+
+### New Features
+  - Now runs on Windows and Apple Silicon Macs.
+  - Precompiled binaries support Node 10, 12, 14+.
+  - Image objects can be initialized from PNG, JPEG, GIF, BMP, or ICO data.
+  - Path2D objects can now be combined using [boolean operators](https://github.com/samizdatco/skia-canvas/#complement-difference-intersect-union-and-xor) and can measure their own [bounding boxes](https://github.com/samizdatco/skia-canvas/#bounds).
+  - Context objects now support [`createConicGradient()`](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/createConicGradient).
+  - Image objects now return a promise from their [`decode()`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement/decode) method allowing for async loading without the [`loadImage`](https://github.com/samizdatco/skia-canvas/#loadimage) helper.
+
+### Bugfixes
+  - Calling `drawImage` with a `Canvas` object as the argument now uses a Skia `Pict` rather than a  `Drawable` as the interchange format, meaning it can actually respect the canvas's current `globalAlpha` and `globalCompositeOperation` state (fixed #6).
+  - Improved some spurious error messages when trying to generate a graphics file from a canvas whose width and/or height was set to zero (fixed #5).
+  - `CanvasPattern`s now respect the `imageSmoothingEnabled` setting
+  - The `counterclockwise` arg to `ellipse` and `arc` is now correctly treated as optional.
+
+### Misc. Improvements
+  - Made the `console.log` representations of the canvas-related objects friendlier.
+  - Added new test suites for `Path2D`, `Image`, and `Canvas`’s format support.
+  - Created [workflows](https://github.com/samizdatco/skia-canvas/tree/master/.github/workflows) to automate precompiled binary builds, testing, and npm package updating.
+
+
+## 📦 ⟩ [v0.9.20] ⟩ Mar 27, 2021
+
+### Bugfixes
+  - The `loadImage` helper can now handle `Buffer` arguments
+
+### Misc. Improvements
+  - Improved documentation of compilation steps and use of line height with `ctx.font`
+
+
+## 📦 ⟩ [v0.9.19] ⟩ Aug 30, 2020
+
+**Initial public release** 🎉
+
+[unreleased]: https://github.com/samizdatco/skia-canvas/compare/v0.9.28...HEAD
+[v0.9.28]: https://github.com/samizdatco/skia-canvas/compare/v0.9.27...v0.9.28
+[v0.9.27]: https://github.com/samizdatco/skia-canvas/compare/v0.9.26...v0.9.27
+[v0.9.26]: https://github.com/samizdatco/skia-canvas/compare/v0.9.25...v0.9.26
+[v0.9.25]: https://github.com/samizdatco/skia-canvas/compare/v0.9.24...v0.9.25
+[v0.9.24]: https://github.com/samizdatco/skia-canvas/compare/v0.9.23...v0.9.24
+[v0.9.23]: https://github.com/samizdatco/skia-canvas/compare/v0.9.22...v0.9.23
+[v0.9.22]: https://github.com/samizdatco/skia-canvas/compare/v0.9.21...v0.9.22
+[v0.9.21]: https://github.com/samizdatco/skia-canvas/compare/v0.9.20...v0.9.21
+[v0.9.20]: https://github.com/samizdatco/skia-canvas/compare/v0.9.19...v0.9.20
+[v0.9.19]: https://github.com/samizdatco/skia-canvas/compare/v0.9.15...v0.9.19

package/README.md

@@ -9,9 +9,10 @@ In particular, Skia Canvas:
   - is fast and compact since all the heavy lifting is done by native code written in Rust and C++
   - can generate output in both raster (JPEG & PNG) and vector (PDF & SVG) image formats
   - can save images to [files][saveAs], return them as [Buffers][toBuffer], or encode [dataURL][toDataURL_ext] strings
-  - uses native threads and [EventQueues](https://docs.rs/neon/0.8.3-napi/neon/event/struct.EventQueue.html) for asynchronous rendering and file I/O
+  - uses native threads and [channels](https://docs.rs/neon/0.9.0/neon/event/struct.Channel.html) 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](https://www.youtube.com/watch?v=OmfliNQsk88) boolean operations or point-by-point [interpolation][p2d_interpolate]
+  - can apply [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]
   - fully supports the [CSS filter effects][filter] image processing operators
   - offers rich typographic control including:
@@ -24,45 +25,6 @@ In particular, Skia Canvas:
     - use of non-system fonts [loaded](#usefamilyname-fontpaths) from local files
 
 
-### Basic Usage
-```js
-const {Canvas, loadImage} = require('skia-canvas'),
-      rand = n => Math.floor(n * Math.random());
-
-let canvas = new Canvas(600, 600),
-    ctx = canvas.getContext("2d"),
-    {width, height} = canvas;
-
-// draw a sea of blurred dots filling the canvas
-ctx.filter = 'blur(12px) hue-rotate(20deg)'
-for (let i=0; i<800; i++){
-  ctx.fillStyle = `hsl(${rand(40)}deg, 80%, 50%)`
-  ctx.beginPath()
-  ctx.arc(rand(width), rand(height), rand(20)+5, 0, 2*Math.PI)
-  ctx.fill()
-}
-
-// mask all of the dots that don't overlap with the text
-ctx.filter = 'none'
-ctx.globalCompositeOperation = 'destination-in'
-ctx.font='italic 480px Times, DejaVu Serif'
-ctx.textAlign = 'center'
-ctx.textBaseline = 'top'
-ctx.fillText('¶', width/2, 0)
-
-// draw a background behind the clipped text
-ctx.globalCompositeOperation = 'destination-over'
-ctx.fillStyle = '#182927'
-ctx.fillRect(0,0, width,height)
-
-// save the graphic...
-canvas.saveAs("pilcrow.png")
-// ...or use a shorthand for canvas.toBuffer("png")
-fs.writeFileSync("pilcrow.png", canvas.png)
-// ...or embed it in a string
-console.log(`<img src="${canvas.toDataURL("png")}">`)
-```
-
 ## Installation
 
 If you’re running on a supported platform, installation should be as simple as:
@@ -72,13 +34,6 @@ $ npm install skia-canvas
 
 This will download a pre-compiled library from the project’s most recent [release](https://github.com/samizdatco/skia-canvas/releases).
 
-### Dependencies
-
-Nearly everything you need is statically linked into the library.
-
-A notable exception is the [Fontconfig](https://www.freedesktop.org/wiki/Software/fontconfig/) library (and its associated [FreeType](https://www.freetype.org) renderer) which must be installed separately if you’re running on Linux.
-
-
 ### Platform Support
 
 The underlying Rust library uses [N-API](https://nodejs.org/api/n-api.html) v6 which allows it to run on Node.js versions:
@@ -88,13 +43,18 @@ The underlying Rust library uses [N-API](https://nodejs.org/api/n-api.html) v6 w
 
 Pre-compiled binaries are available for:
 
-  - Linux (x86)
-  - macOS (x86 & Apple silicon)
-  - Windows (x86)
+  - Linux (x64, arm64, & armhf)
+  - macOS (x64 & Apple silicon)
+  - Windows (x64)
+
+Nearly everything you need is statically linked into the library. A notable exception is the [Fontconfig](https://www.freedesktop.org/wiki/Software/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.24 or later. Currently the `rust-skia` library [will not compile](https://github.com/rust-skia/rust-skia/issues/356) against the [musl](https://musl.libc.org) library used by Alpine Linux—though this may change in the future. For now, if you are setting up a [Dockerfile](https://nodejs.org/en/docs/guides/nodejs-docker-webapp/) that uses [`node`](https://hub.docker.com/_/node) as its basis, you’ll want to set your `FROM` image to one of the (Debian-derived) defaults like `node:16`, `node:14`, `node:12`, `node:buster`, `node:stretch`, or simply:
+The library is compatible with Linux systems using [glibc](https://www.gnu.org/software/libc/) 2.24 or later as well as Alpine Linux (x64) and the [musl](https://musl.libc.org) 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](https://nodejs.org/en/docs/guides/nodejs-docker-webapp/) that uses [`node`](https://hub.docker.com/_/node) as its basis, the simplest approach is to set your `FROM` image to one of the (Debian-derived) defaults like `node:16`, `node:14`, `node:12`, `node:buster`, `node:stretch`, or simply:
 ```dockerfile
 FROM node
 ```
@@ -103,7 +63,14 @@ 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 
+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
@@ -115,10 +82,57 @@ Start by installing:
   1. The [Rust compiler](https://www.rust-lang.org/tools/install) and cargo package manager using [`rustup`](https://rust-lang.github.io/rustup/)
   2. A C compiler toolchain like LLVM/Clang or MSVC
   3. Python 2.7 (used by Skia's [build process](https://skia.org/docs/user/build/))
-  4. On Linux: Fontconfig, OpenSSL, X11, and Mesa
+  4. On Linux: Fontconfig and OpenSSL
 
 [Detailed instructions](https://github.com/rust-skia/rust-skia#building) 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).
 
+## Example Usage
+```js
+const {Canvas, loadImage} = require('skia-canvas'),
+      rand = n => Math.floor(n * Math.random()),
+      fs = require('fs')
+
+let canvas = new Canvas(600, 600),
+    ctx = canvas.getContext("2d"),
+    {width, height} = canvas;
+
+// draw a sea of blurred dots filling the canvas
+ctx.filter = 'blur(12px) hue-rotate(20deg)'
+for (let i=0; i<800; i++){
+  ctx.fillStyle = `hsl(${rand(40)}deg, 80%, 50%)`
+  ctx.beginPath()
+  ctx.arc(rand(width), rand(height), rand(20)+5, 0, 2*Math.PI)
+  ctx.fill()
+}
+
+// mask all of the dots that don't overlap with the text
+ctx.filter = 'none'
+ctx.globalCompositeOperation = 'destination-in'
+ctx.font='italic 480px Times, DejaVu Serif'
+ctx.textAlign = 'center'
+ctx.textBaseline = 'top'
+ctx.fillText('¶', width/2, 0)
+
+// draw a background behind the clipped text
+ctx.globalCompositeOperation = 'destination-over'
+ctx.fillStyle = '#182927'
+ctx.fillRect(0,0, width,height)
+
+// render to files using a background thread
+async function render(){
+  // save the graphic...
+  await canvas.saveAs("pilcrow.png")
+  // ...or use a shorthand for canvas.toBuffer("png")
+  let pngData = await canvas.png
+  // ...or embed it in a string
+  console.log(`<img src="${await canvas.toDataURL("png")}">`)
+}
+render()
+
+// ...or save the file synchronously from the main thread
+canvas.saveAsSync("pilcrow.png")
+```
+
 
 
 # API Documentation
@@ -149,22 +163,22 @@ The Canvas object is a stand-in for the HTML `<canvas>` element. It defines imag
 
 | Image Dimensions             | Rendering Contexts            | Output                                           |
 | --                           | --                            | --                                               |
-| [**width**][canvas_width]    | [**pages**][canvas_pages] ⚡  | [**async**][canvas_async]  ⚡                    |
+| [**width**][canvas_width]    | [**pages**][canvas_pages] ⚡  | ~~[**async**][canvas_async]~~  ⚡                    |
 | [**height**][canvas_height]  | [getContext()][getContext]    | [**pdf**, **png**, **svg**, **jpg**][shorthands] ⚡ |
-|                              | [newPage()][newPage] ⚡       | [saveAs()][saveAs] ⚡                            |
-|                              |                               | [toBuffer()][toBuffer] ⚡                        |
-|                              |                               | [toDataURL()][toDataURL_mdn] [⚡][toDataURL_ext] |
+|                              | [newPage()][newPage] ⚡       | [saveAs()][saveAs] / [saveAsSync()][saveAs] ⚡                            |
+|                              |                               | [toBuffer()][toBuffer] / [toBufferSync()][toBuffer] ⚡                        |
+|                              |                               | [toDataURL()][toDataURL_ext] / [toDataURLSync()][toDataURL_ext] ⚡ |
 
 [canvas_width]: https://developer.mozilla.org/en-US/docs/Web/API/HTMLCanvasElement/width
 [canvas_height]: https://developer.mozilla.org/en-US/docs/Web/API/HTMLCanvasElement/height
 [canvas_async]: #async
 [canvas_pages]: #pages
 [getContext]: https://developer.mozilla.org/en-US/docs/Web/API/HTMLCanvasElement/getContext
-[saveAs]: #saveasfilename-page-format-density1-quality092-outlinefalse
-[toBuffer]: #tobufferformat-page-density-quality-outline
+[saveAs]: #saveasfilename-page-format-matte-density1-quality092-outlinefalse
+[toBuffer]: #tobufferformat-page-matte-density-quality-outline
 [newPage]: #newpagewidth-height
 [toDataURL_mdn]: https://developer.mozilla.org/en-US/docs/Web/API/HTMLCanvasElement/toDataURL
-[toDataURL_ext]: #todataurlformat-page-density-quality-outline
+[toDataURL_ext]: #todataurlformat-page-matte-density-quality-outline
 [shorthands]: #pdf-svg-jpg-and-png
 
 #### Creating new `Canvas` objects
@@ -176,21 +190,24 @@ let defaultCanvas = new Canvas() // without arguments, defaults to 300 × 150 px
 let squareCanvas = new Canvas(512, 512) // creates a 512 px square
 ```
 
-##### PROPERTIES
-
-#### `.async`
+#### Saving graphics to files, buffers, and strings
 
-When the canvas renders images and writes them to disk, it does so in a background thread so as not to block execution within your script. As a result you’ll generally want to deal with the canvas from within an `async` function and be sure to use the `await` keyword when accessing any of its output methods or shorthand properties:
+When the canvas renders images and writes them to disk, it does so in a background thread so as not to block execution within your script. As a result you’ll generally want to deal with the canvas from within an `async` function and be sure to use the `await` keyword when accessing any of its output methods or shorthand properties (all of which return Promises):
   - [`saveAs()`][saveAs]
   - [`toBuffer()`][toBuffer]
   - [`toDataURL()`][toDataURL_ext]
   - [`.pdf`, `.svg`, `.jpg`, and `.png`][shorthands]
 
-In cases where this is not the desired behavior, you can switch these methods into a synchronous mode for a particular canvas by setting its `async` property to `false`. For instance, both of the example functions below will generate PNG & PDF from the canvas, though the first will be more efficient (particularly for parallel contexts like request-handlers in an HTTP server or batch exports):
-```js
 
+In cases where this is not the desired behavior, you can use the synchronous equivalents for the primary export functions. They accept identical arguments to their async versions but block execution and return their values synchronously rather than wrapped in Promises. Also note that the [shorthand properties][shorthands] do not have synchronous versions:
+- [`saveAsSync()`][saveAs]
+- [`toBufferSync()`][toBuffer]
+- [`toDataURLSync()`][toDataURL_ext]
+
+For instance, both of the example functions below will generate PNG & PDF from the canvas, though the first will be more efficient (particularly for parallel contexts like request-handlers in an HTTP server or batch exports):
+
+```js
 let canvas = new Canvas()
-console.log(canvas.async) // -> true by default
 
 async function normal(){
   let pngURL = await canvas.toDataURL("png")
@@ -198,14 +215,16 @@ async function normal(){
 }
 
 function synchronous(){
-  canvas.async = false // switch into synchronous mode
-  let pngURL = canvas.toDataURL("png")
-  let pdfBuffer = canvas.pdf
+  let pngURL = canvas.toDataURLSync("png")
+  let pdfBuffer = canvas.toBufferSync("pdf")
 }
 ```
 
+##### PROPERTIES
 
+#### ~~`.async`~~
 
+**The async property has been deprecated** and will be removed in a future release. Use the [`saveAsSync()`][saveAs], [`toBufferSync()`][toBuffer], and [`toDataURLSync()`][toDataURL_ext] methods if the default, asynchronous versions aren't to your liking.
 
 #### `.pages`
 
@@ -234,6 +253,10 @@ An integer can optionally be placed between the braces to indicate the number of
 ##### page
 The optional `page` argument accepts an integer that allows for the individual selection of pages in a multi-page canvas. Note that page indexing starts with page 1 **not** 0. The page value can also be negative, counting from the end of the canvas’s `.pages` array. For instance, `.saveAs("currentPage.png", {page:-1})` is equivalent to omitting `page` since they both yield the canvas’s most recently added page.
 
+##### format
+
+The image format to generate, specified either as a mime-type string or file extension. The `format` argument will take precedence over the type specified through the `filename` argument’s extension, but is primarily useful when generating a file whose name cannot end with an extension for other reasons.
+
 ##### matte
 The optional `matte` argument accepts a color-string specifying the background that should be drawn *behind* the canvas in the exported image. Any transparent portions of the image will be filled with the matte color.
 
@@ -251,11 +274,11 @@ The `quality` option is a number between 0 and 1.0 that controls the level of JP
 ##### outline
 When generating SVG output containing text, you have two options for how to handle the fonts that were used. By default, SVG files will contain `<text>` elements that refer to the fonts by name in the embedded stylesheet. This requires that viewers of the SVG have the same fonts available on their system (or accessible as webfonts). Setting the optional `outline` argument to `true` will trace all the letterforms and ‘burn’ them into the file as bézier paths. This will result in a much larger file (and one in which the original text strings will be unrecoverable), but it will be viewable regardless of the specifics of the system it’s displayed on.
 
-#### `toBuffer(format, {page, density, quality, outline})`
+#### `toBuffer(format, {page, matte, density, quality, outline})`
 
 Node [`Buffer`][Buffer] objects containing various image formats can be created by passing either a format string like `"svg"` or a mime-type like `"image/svg+xml"`. An ‘@’ suffix can be added to the format string to specify a pixel-density (for instance, `"jpg@2x"`). The optional arguments behave the same as in the `saveAs` method.
 
-#### `toDataURL(format, {page, density, quality, outline})`
+#### `toDataURL(format, {page, matte, density, quality, outline})`
 
 This method accepts the same arguments and behaves similarly to `.toBuffer`. However instead of returning a Buffer, it returns a string of the form `"data:<mime-type>;base64,<image-data>"` which can be used as a `src` attribute in `<img>` tags, embedded into CSS, etc.
 
@@ -265,17 +288,32 @@ This method accepts the same arguments and behaves similarly to `.toBuffer`. How
 Most of your interaction with the canvas will actually be directed toward its ‘rendering context’, a supporting object you can acquire by calling the canvas’s [getContext()](https://developer.mozilla.org/en-US/docs/Web/API/HTMLCanvasElement/getContext) and [newPage()][newPage] methods.
 
 
-| Canvas State                             | Drawing                                      | Pattern & Color                                   | Line Style                              | Transform                                |
-|------------------------------------------|----------------------------------------------|---------------------------------------------------|-----------------------------------------|------------------------------------------|
-| [**canvas**][canvas_attr] ⧸[⚡](#canvas) | [clearRect()][clearRect()]                   | [**fillStyle**][fillStyle]                        | [**lineCap**][lineCap]                  | [**currentTransform**][currentTransform] |
-| [beginPath()][beginPath()]               | [fillRect()][fillRect()]                     | [**strokeStyle**][strokeStyle]                    | [**lineDashFit** ⚡][lineDashFit]       | [getTransform()][getTransform()]         |
-| [isPointInPath()][isPointInPath()]       | [strokeRect()][strokeRect()]                 | [createConicGradient()][createConicGradient()]    | [**lineDashMarker** ⚡][lineDashMarker] | [setTransform()][setTransform()]         |
-| [isPointInStroke()][isPointInStroke()]   | [fillText()][fillText()] ⧸[⚡][drawText]     | [createLinearGradient()][createLinearGradient()]  | [**lineDashOffset**][lineDashOffset]    | [resetTransform()][resetTransform()]     |
-| [save()][save()]                         | [strokeText()][strokeText()] ⧸[⚡][drawText] | [createRadialGradient()][createRadialGradient()]  | [**lineJoin**][lineJoin]                | [transform()][transform()]               |
-| [restore()][restore()]                   | [fill()][fill()]                             | [createPattern()][createPattern()]                | [**lineWidth**][lineWidth]              | [translate()][translate()]               |
-| [clip()][clip()]                         | [stroke()][stroke()]                         | [createTexture() ⚡][createTexture()]             | [**miterLimit**][miterLimit]            | [rotate()][rotate()]                     |
-|                                          |                                              |                                                   | [getLineDash()][getLineDash()]          | [scale()][scale()]                       |
-|                                          |                                              |                                                   | [setLineDash()][setLineDash()]          |                                          |
+| Canvas State                             | Drawing                                      | Pattern & Color                                   | Line Style                              | Transform                                   |
+|------------------------------------------|----------------------------------------------|---------------------------------------------------|-----------------------------------------|---------------------------------------------|
+| [**canvas**][canvas_attr] ⧸[⚡](#canvas) | [clearRect()][clearRect()]                   | [**fillStyle**][fillStyle]                        | [**lineCap**][lineCap]                  | [**currentTransform**][currentTransform]    |
+| [beginPath()][beginPath()]               | [fillRect()][fillRect()]                     | [**strokeStyle**][strokeStyle]                    | [**lineDashFit** ⚡][lineDashFit]       | [createProjection() ⚡][createProjection()] |
+| [isPointInPath()][isPointInPath()]       | [strokeRect()][strokeRect()]                 | [createConicGradient()][createConicGradient()]    | [**lineDashMarker** ⚡][lineDashMarker] | [getTransform()][getTransform()]            |
+| [isPointInStroke()][isPointInStroke()]   | [fillText()][fillText()] ⧸[⚡][drawText]     | [createLinearGradient()][createLinearGradient()]  | [**lineDashOffset**][lineDashOffset]    | [setTransform()][setTransform()]            |
+| [save()][save()]                         | [strokeText()][strokeText()] ⧸[⚡][drawText] | [createRadialGradient()][createRadialGradient()]  | [**lineJoin**][lineJoin]                | [resetTransform()][resetTransform()]        |
+| [restore()][restore()]                   | [fill()][fill()]                             | [createPattern()][createPattern()]                | [**lineWidth**][lineWidth]              | [transform()][transform()]                  |
+| [clip()][clip()]                         | [stroke()][stroke()]                         | [createTexture() ⚡][createTexture()]             | [**miterLimit**][miterLimit]            | [translate()][translate()]                  |
+|                                          |                                              |                                                   | [getLineDash()][getLineDash()]          | [rotate()][rotate()]                        |
+|                                          |                                              |                                                   | [setLineDash()][setLineDash()]          | [scale()][scale()]                          |
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
 
 
 | Bezier Paths                             | Typography                                                  | Images                                             | Compositing Effects                                      |
@@ -375,11 +413,76 @@ The `lineDashFit` attribute can be set to `"move"`, `"turn"`, or `"follow"` and
 
 Adds a line segment connecting the current point to (*x, y*) but curving toward the control point (*cpx, cpy*) along the way. The `weight` argument controls how close the curve will come to the control point. If the weight is `0`, the result will be a straight line from the current point to (*x, y*). With a weight of `1.0`, the function is equivalent to calling `quadraticCurveTo()`. Weights greater than `1.0` will pull the line segment ever closer to the control point.
 
+#### `createProjection(quad, [basis])`
+
+This method returns a [DOMMatrix][DOMMatrix] object which can be used to simulate perspective effects or other distortions in which the four corners of the canvas are mapped to an arbitrary quadrilateral (four sided polygon). The matrix must be passed to the context's [setTransform][setTransform()] method for it take effect.
+
+##### `quad`
+
+The `quad` argument defines the **target** of the transformation. It specifies four points that establish where the four corners of the source coordinate space will be positioned within the viewport. If these points form a polygon other than a rectangle, lines drawn along the x & y axes of the source space will no longer be perpendicular—trapezoids allow for ‘vanishing point’ effects and parallelograms create ‘skew’.
+
+The geometry of the quadrilateral should be described as an Array of either 8 or 4 numbers specifying an arbitrary polygon or rectangle respectively:
+
+```js
+[x1, y1, x2, y2, x3, y3, x4, y4] // four corner points
+[left, top, right, bottom] // four edges of a rectangle
+
+// internal arrays for grouping are also allowed
+[[x1, y1], [x2, y2], [x3, y3], [x4, y4]] 
+```
+
+##### `basis`
+   
+The optional `basis` argument defines the **source** quadrilateral whose corners will be mapped to the positions defined by `quad`. If no `basis` is specified, the canvas's bounding box will be used (i.e., the rectangle from ⟨`0`, `0`⟩ to ⟨`canvas.width`, `canvas.height`⟩). Note that drawing commands that go outside of the `basis` region may well be visible—it only establishes the geometry of the projection, not the [clipping][clip()] path.
+
+The `basis` polygon can be described using 2, 4, or 8 numbers, using the canvas dimensions to fill in the unspecified coordinates:
+```js
+[width, height] // rectangle from ⟨0, 0⟩ to ⟨width, height⟩
+[left, top, right, bottom] // four edges of a rectangle
+[x1, y1, x2, y2, x3, y3, x4, y4] // four corner points
+```
+
+----
+
+The projection matrix will apply to all types of drawing: shapes, images, and text. This example transforms a white box and red `"@"` character into a trapezoid bounded by the vertical midline of the canvas and its left and right edges. Since no `basis` argument is provided, it will default to using the current canvas bounds as the rectangle to be mapped onto that trapezoid. 
+
+```js
+let canvas = new Canvas(512, 512),
+    ctx = canvas.getContext("2d"),
+    {width:w, height:h} = canvas;
+ctx.font = '900 480px Times'
+ctx.textAlign = 'center'
+ctx.fillStyle = '#aaa'
+ctx.fillRect(0, 0, w, h)
+
+let quad = [
+  w*.33, h/2,  // upper left
+  w*.66, h/2,  // upper right
+  w,     h*.9, // bottom right
+  0,     h*.9, // bottom left
+]
+
+let matrix = ctx.createProjection(quad) // use default basis
+ctx.setTransform(matrix)
+
+ctx.fillStyle = 'white'
+ctx.fillRect(10, 10, w-20, h-20)
+
+ctx.fillStyle = '#900'
+ctx.fillText("@", w/2, h-40)
+
+```
+
+The results below show the image generated when the `createProjection()` call is omitted entirely, called (as above) with just a `quad` argument, or called with two different values for the optional `basis` argument:
+
+![Paths and text with a perspective transform](/test/assets/path/projection@2x.png)
+
+
 #### `createTexture(spacing, {path, line, color, angle, offset=0})`
 
 The `createTexture()` method returns a `CanvasTexture` object that can be assigned to the context’s `strokeStyle` or `fillStyle` property. Similar to a `CanvasPattern`, a `CanvasTexture` defines a repeating pattern that will be drawn instead of a flat color, but textures define their content using *vectors* rather than bitmaps.
 
-Textures can be based on a user-provided Path2D object or will draw a stripe pattern of parallel lines if a path isn’t provided. 
+Textures can be based on a user-provided Path2D object or will draw a stripe pattern of parallel lines if a path isn’t provided.
 
 ##### `spacing`
 
@@ -816,6 +919,7 @@ Many thanks to the [`node-canvas`](https://github.com/Automattic/node-canvas) de
 [conicCurveTo]: #coniccurvetocpx-cpy-x-y-weight
 [outlineText()]: #outlinetextstr
 [createTexture()]: #createtexturespacing-path-line-color-angle-offset0
+[createProjection()]: #createprojectionquad-basis
 [lineDashMarker]: #linedashmarker
 [lineDashFit]: #linedashfit