Support toBuffer("image/jpeg"), unify encoding configs

See updated Readme.md and CHANGELOG.md

Author: zbjornson

CHANGELOG.md

@@ -8,12 +8,43 @@ project adheres to [Semantic Versioning](http://semver.org/).
 2.0.0 (unreleased -- encompasses all alpha versions)
 ==================
 
+**Upgrading from 1.x**
+```js
+// (1) The quality argument for canvas.jpegStream now goes from 0 to 1 instead
+//     of from 0 to 100:
+canvas.jpegStream({quality: 50}) // old
+canvas.jpegStream({quality: 0.5}) // new
+
+// (2) The ZLIB compression level and PNG filter options for canvas.toBuffer are
+//     now named instead of positional arguments:
+canvas.toBuffer(undefined, 3, canvas.PNG_FILTER_NONE) // old
+canvas.toBuffer(undefined, {compressionLevel: 3, filters: canvas.PNG_FILTER_NONE}) // new
+// or specify the mime type explicitly:
+canvas.toBuffer("image/png", {compressionLevel: 3, filters: canvas.PNG_FILTER_NONE}) // new
+
+// (3) #2 also applies for canvas.pngStream, although these arguments were not
+//     documented:
+canvas.pngStream(3, canvas.PNG_FILTER_NONE) // old
+canvas.pngStream({compressionLevel: 3, filters: canvas.PNG_FILTER_NONE}) // new
+
+// (4) canvas.syncPNGStream() and canvas.syncJPEGStream() have been removed:
+canvas.syncPNGStream() // old
+canvas.pngStream() // new
+
+canvas.syncJPEGStream() // old
+canvas.jpegStream() // new
+```
+
 ### Breaking
  * Drop support for Node.js <4.x
- * Remove sync streams (bc53059). Note that all or most streams are still
-   synchronous to some degree; this change just removed `syncPNGStream` and
-   friends.
+ * Remove sync stream functions (bc53059). Note that most streams are still
+   synchronous (run in the main thread); this change just removed `syncPNGStream`
+   and `syncJPEGStream`.
  * Pango is now *required* on all platforms (7716ae4).
+ * Make the `quality` argument for JPEG output go from 0 to 1 to match HTML spec.
+ * Make the `compressionLevel` and `filters` arguments for `canvas.toBuffer()`
+   named instead of positional. Same for `canvas.pngStream()`, although these
+   arguments were not documented.
 
 ### Fixed
  * Prevent segfaults caused by loading invalid fonts (#1105)
@@ -32,8 +63,8 @@ project adheres to [Semantic Versioning](http://semver.org/).
 
 ### Added
  * Prebuilds (#992)
- * Support canvas.getContext("2d", {alpha: boolean}) and
-   canvas.getContext("2d", {pixelFormat: "..."})
+ * Support `canvas.getContext("2d", {alpha: boolean})` and
+   `canvas.getContext("2d", {pixelFormat: "..."})`
  * Support indexed PNG encoding.
  * Support `currentTransform` (d6714ee)
  * Export `CanvasGradient` (6a4c0ab)
@@ -45,6 +76,9 @@ project adheres to [Semantic Versioning](http://semver.org/).
  * Browser-compatible API (6a29a23)
  * Support for jpeg on Windows (42e9a74)
  * Support for backends (1a6dffe)
+ * Support for `canvas.toBuffer("image/jpeg")`
+ * Unified configuration options for `canvas.toBuffer()`, `canvas.pngStream()`
+   and `canvas.jpegStream()`
 
 1.6.x (unreleased)
 ==================

Readme.md

@@ -5,6 +5,9 @@
 ## This is the documentation for version 2.0.0-alpha
 Alpha versions of 2.0 can be installed using `npm install canvas@next`.
 
+See the [changelog](https://github.com/Automattic/node-canvas/blob/master/CHANGELOG.md)
+for a guide to upgrading from 1.x to 2.x.
+
 **For version 1.x documentation, see [the v1.x branch](https://github.com/Automattic/node-canvas/tree/v1.x)**
 
 -----
@@ -80,9 +83,11 @@ loadImage('examples/images/lime-cat.jpg').then((image) => {
 })
 ```
 
-## Non-Standard API
+## Non-Standard APIs
 
- node-canvas extends the canvas API to provide interfacing with node, for example streaming PNG data, converting to a `Buffer` instance, etc. Among the interfacing API, in some cases the drawing API has been extended for SSJS image manipulation / creation usage, however keep in mind these additions may fail to render properly within browsers.
+node-canvas implements the [HTML Canvas API](https://developer.mozilla.org/en-US/docs/Web/API/Canvas_API) as closely as possible.
+(See [Compatibility Status](https://github.com/Automattic/node-canvas/wiki/Compatibility-Status)
+for the current API compliance.) All non-standard APIs are documented below.
 
 ### Image#src=Buffer
 
@@ -125,84 +130,147 @@ img.dataMode = Image.MODE_MIME | Image.MODE_IMAGE; // Both are tracked
 
 If image data is not tracked, and the Image is drawn to an image rather than a PDF canvas, the output will be junk. Enabling mime data tracking has no benefits (only a slow down) unless you are generating a PDF.
 
-### Canvas#pngStream(options)
+### Canvas#toBuffer()
 
-  To create a `PNGStream` simply call `canvas.pngStream()`, and the stream will start to emit _data_ events, emitting _end_ when the data stream ends. If an exception occurs the _error_ event is emitted.
+Creates a [`Buffer`](https://nodejs.org/api/buffer.html) object representing the
+image contained in the canvas.
+
+> `canvas.toBuffer((err: Error|null, result: Buffer) => void[, mimeType[, config]]) => void`
+> `canvas.toBuffer([mimeType[, config]]) => Buffer`
+
+* **callback** If provided, the buffer will be provided in the callback instead
+  of being returned by the function. Invoked with an error as the first argument
+  if encoding failed, or the resulting buffer as the second argument if it
+  succeeded. Not supported for mimeType `raw` or for PDF or SVG canvases (there
+  is no async work to do in those cases). *Note*: Currently the callback
+  function is invoked synchronously for `image/jpeg`.
+* **mimeType** A string indicating the image format. Valid options are `image/png`,
+  `image/jpeg` (if node-canvas was built with JPEG support) and `raw` (unencoded
+  ARGB32 data in native-endian byte order, top-to-bottom). Defaults to
+  `image/png`. If the canvas is a PDF or SVG canvas, this argument is ignored
+  and a PDF or SVG is returend always.
+* **config**
+  * For `image/jpeg` an object specifying the quality (0 to 1), if progressive
+    compression should be used and/or if chroma subsampling should be used:
+    `{quality: 0.75, progressive: false, chromaSubsampling: true}`. All
+    properties are optional.
+  * For `image/png`, an object specifying the ZLIB compression level (between 0
+    and 9), the compression filter(s), the palette (indexed PNGs only) and/or
+    the background palette index (indexed PNGs only):
+    `{compressionLevel: 6, filters: canvas.PNG_ALL_FILTERS, palette: undefined, backgroundIndex: 0}`.
+    All properties are optional.
+
+**Return value**
+
+If no callback is provided, a [`Buffer`](https://nodejs.org/api/buffer.html).
+If a callback is provided, none.
+
+#### Examples
 
 ```javascript
-var fs = require('fs')
-  , out = fs.createWriteStream(__dirname + '/text.png')
-  , stream = canvas.pngStream();
+// Default: buf contains a PNG-encoded image
+const buf = canvas.toBuffer()
 
-stream.pipe(out);
+// PNG-encoded, zlib compression level 3 for faster compression but bigger files, no filtering
+const buf2 = canvas.toBuffer('image/png', {compressionLevel: 3, filters: canvas.PNG_FILTER_NONE})
 
-out.on('finish', function(){
-  console.log('The PNG file was created.');
-});
+// JPEG-encoded, 50% quality
+const buf3 = canvas.toBuffer('image/jpeg', {quality: 0.5})
+
+// Asynchronous PNG
+canvas.toBuffer((err, buf) => {
+  if (err) throw err; // encoding failed
+  // buf is PNG-encoded image
+})
+
+canvas.toBuffer((err, buf) => {
+  if (err) throw err; // encoding failed
+  // buf is JPEG-encoded image at 95% quality
+  // Note that this callback is currently called synchronously.
+}, 'image/jpeg', {quality: 0.95})
+
+// ARGB32 pixel values, native-endian
+const buf4 = canvas.toBuffer('raw')
+const {stride, width} = canvas
+// In memory, this is `canvas.height * canvas.stride` bytes long.
+// The top row of pixels, in ARGB order, left-to-right, is:
+const topPixelsARGBLeftToRight = buf4.slice(0, width * 4)
+// And the third row is:
+const row3 = buf4.slice(2 * stride, 2 * stride + width * 4)
+
+// SVG and PDF canvases ignore the mimeType argument
+const myCanvas = createCanvas(w, h, 'pdf')
+myCanvas.toBuffer() // returns a buffer containing a PDF-encoded canvas
+```
+
+### Canvas#pngStream(options)
+
+Creates a [`ReadableStream`](https://nodejs.org/api/stream.html#stream_class_stream_readable)
+that emits PNG-encoded data.
+
+> `canvas.pngStream([config]) => ReadableStream`
+
+* `config` An object specifying the ZLIB compression level (between 0 and 9),
+  the compression filter(s), the palette (indexed PNGs only) and/or the
+  background palette index (indexed PNGs only):
+  `{compressionLevel: 6, filters: canvas.PNG_ALL_FILTERS, palette: undefined, backgroundIndex: 0}`.
+  All properties are optional.
+
+#### Examples
+
+```javascript
+const fs = require('fs')
+const out = fs.createWriteStream(__dirname + '/test.png')
+const stream = canvas.pngStream()
+stream.pipe(out)
+out.on('finish', () =>  console.log('The PNG file was created.'))
 ```
 
 To encode indexed PNGs from canvases with `pixelFormat: 'A8'` or `'A1'`, provide an options object:
 
 ```js
-var palette = new Uint8ClampedArray([
+const palette = new Uint8ClampedArray([
   //r    g    b    a
     0,  50,  50, 255, // index 1
    10,  90,  90, 255, // index 2
   127, 127, 255, 255
   // ...
-]);
+])
 canvas.pngStream({
   palette: palette,
   backgroundIndex: 0 // optional, defaults to 0
 })
 ```
 
-### Canvas#jpegStream() and Canvas#syncJPEGStream()
-
-You can likewise create a `JPEGStream` by calling `canvas.jpegStream()` with
-some optional parameters; functionality is otherwise identical to
-`pngStream()`. See `examples/crop.js` for an example.
-
-_Note: At the moment, `jpegStream()` is the same as `syncJPEGStream()`, both
-are synchronous_
-
-```javascript
-var stream = canvas.jpegStream({
-    bufsize: 4096 // output buffer size in bytes, default: 4096
-  , quality: 75 // JPEG quality (0-100) default: 75
-  , progressive: false // true for progressive compression, default: false
-  , chromaSubsampling: true // false to disable 2x2 subsampling of the chroma components, default: true
-});
-```
-
-### Canvas#toBuffer()
+### Canvas#jpegStream()
 
-A call to `Canvas#toBuffer()` will return a node `Buffer` instance containing image data.
+Creates a [`ReadableStream`](https://nodejs.org/api/stream.html#stream_class_stream_readable)
+that emits JPEG-encoded data.
 
-```javascript
-// PNG Buffer, default settings
-var buf = canvas.toBuffer();
+_Note: At the moment, `jpegStream()` is synchronous under the hood. That is, it
+runs in the main thread, not in the libuv threadpool._
 
-// PNG Buffer, zlib compression level 3 (from 0-9), faster but bigger
-var buf2 = canvas.toBuffer(undefined, 3, canvas.PNG_FILTER_NONE);
+> `canvas.pngStream([config]) => ReadableStream`
 
-// ARGB32 Buffer, native-endian
-var buf3 = canvas.toBuffer('raw');
-var stride = canvas.stride;
-// In memory, this is `canvas.height * canvas.stride` bytes long.
-// The top row of pixels, in ARGB order, left-to-right, is:
-var topPixelsARGBLeftToRight = buf3.slice(0, canvas.width * 4);
-var row3 = buf3.slice(2 * canvas.stride, 2 * canvas.stride + canvas.width * 4);
-```
+* `config` an object specifying the quality (0 to 1), if progressive compression
+  should be used and/or if chroma subsampling should be used:
+  `{quality: 0.75, progressive: false, chromaSubsampling: true}`. All properties
+  are optional.
 
-### Canvas#toBuffer() async
-
-Optionally we may pass a callback function to `Canvas#toBuffer()`, and this process will be performed asynchronously, and will `callback(err, buf)`.
+#### Examples
 
 ```javascript
-canvas.toBuffer(function(err, buf){
-
-});
+const fs = require('fs')
+const out = fs.createWriteStream(__dirname + '/test.jpeg')
+const stream = canvas.jpegStream()
+stream.pipe(out)
+out.on('finish', () =>  console.log('The JPEG file was created.'))
+
+// Disable 2x2 chromaSubsampling for deeper colors and use a higher quality
+const stream = canvas.jpegStream({
+  quality: 95,
+  chromaSubsampling: false
+})
 ```
 
 ### Canvas#toDataURL() sync and async

lib/canvas.js

@@ -50,27 +50,32 @@ Canvas.prototype.getContext = function (contextType, contextAttributes) {
 /**
  * Create a `PNGStream` for `this` canvas.
  *
- * @param {Object} options
- * @param {Uint8ClampedArray} options.palette Provide for indexed PNG encoding.
- *   entries should be R-G-B-A values.
- * @param {Number} options.backgroundIndex Optional index of background color
+ * @param {Object} [options]
+ * @param {number} [options.compressionLevel] Number from 0 to 9 corresponding
+ *   to the ZLIB compression level. Defaults to 6.
+ * @param {number} [options.filters] Any bitwise combination of
+ *   `PNG_FILTER_NONE`, `PNG_FITLER_SUB`, `PNG_FILTER_UP`, `PNG_FILTER_AVG`,
+ *   `PNG_FILTER_PATETH`; or one of `PNG_ALL_FILTERS` or `PNG_NO_FILTERS`. These
+ *   specify which filters *may* be used by libpng. During encoding, libpng will
+ *   select the best filter from this list of allowed filters.
+ * @param {Uint8ClampedArray} [options.palette] Provide for indexed PNG
+ *   encoding. Entries should be R-G-B-A values.
+ * @param {number} [options.backgroundIndex] Optional index of background color
  *   for indexed PNGs. Defaults to 0.
  * @return {PNGStream}
- * @api public
+ * @public
  */
-
-Canvas.prototype.pngStream =
+Canvas.prototype.pngStream = 
 Canvas.prototype.createPNGStream = function(options){
-  return new PNGStream(this, false, options);
+  return new PNGStream(this, options);
 };
 
 /**
  * Create a `PDFStream` for `this` canvas.
  *
  * @return {PDFStream}
- * @api public
+ * @public
  */
-
 Canvas.prototype.pdfStream =
 Canvas.prototype.createPDFStream = function(){
   return new PDFStream(this);
@@ -79,33 +84,18 @@ Canvas.prototype.createPDFStream = function(){
 /**
  * Create a `JPEGStream` for `this` canvas.
  *
- * @param {Object} options
+ * @param {Object} [options]
+ * @param {number} [options.quality] Number from 0 to 1. Defaults to 0.75.
+ * @param {boolean|1|2} [options.chromaSubsampling] Enables 2x2 chroma
+ *   subsampling. `true` is equivalent to `2`, `false` is equivalent to `1`.
+ * @param {boolean} [options.progressive] Enables progressive encoding. Defautls
+ *   to false.
  * @return {JPEGStream}
- * @api public
+ * @public
  */
-
-Canvas.prototype.jpegStream =
+Canvas.prototype.jpegStream = 
 Canvas.prototype.createJPEGStream = function(options){
-  options = options || {};
-  // Don't allow the buffer size to exceed the size of the canvas (#674)
-  var maxBufSize = this.width * this.height * 4;
-  var clampedBufSize = Math.min(options.bufsize || 4096, maxBufSize);
-  var chromaFactor;
-  if (typeof options.chromaSubsampling === "number") {
-    // libjpeg-turbo seems to complain about values above 2, but hopefully this
-    // can be supported in the future. For now 1 and 2 are valid.
-    // https://github.com/Automattic/node-canvas/pull/1092#issuecomment-366558028
-    chromaFactor = options.chromaSubsampling;
-  } else {
-    chromaFactor = options.chromaSubsampling === false ? 1 : 2;
-  }
-  return new JPEGStream(this, {
-      bufsize: clampedBufSize
-    , quality: options.quality || 75
-    , progressive: options.progressive || false
-    , chromaHSampFactor: chromaFactor
-    , chromaVSampFactor: chromaFactor
-  });
+  return new JPEGStream(this, options);
 };
 
 /**