Create blank image (width, height, channels, background) #470

lib/constructor.js

@@ -54,16 +54,35 @@ let versions = {
  *   });
  * readableStream.pipe(transformer).pipe(writableStream);
  *
+ * @example
+ * // Create a blank 300x200 PNG image of semi-transluent red pixels
+ * sharp(null, {
+ *   create: {
+ *     width: 300,
+ *     height: 200,
+ *     channels: 4,
+ *     background: { r: 255, g: 0, b: 0, alpha: 128 }
+ *   }
+ * })
+ * .png()
+ * .toBuffer()
+ * .then( ... );
+ *
  * @param {(Buffer|String)} [input] - if present, can be
  *  a Buffer containing JPEG, PNG, WebP, GIF, SVG, TIFF or raw pixel image data, or
  *  a String containing the path to an JPEG, PNG, WebP, GIF, SVG or TIFF image file.
  *  JPEG, PNG, WebP, GIF, SVG, TIFF or raw pixel image data can be streamed into the object when null or undefined.
  * @param {Object} [options] - if present, is an Object with optional attributes.
  * @param {Number} [options.density=72] - integral number representing the DPI for vector images.
- * @param {Object} [options.raw] - describes raw pixel image data. See `raw()` for pixel ordering.
+ * @param {Object} [options.raw] - describes raw pixel input image data. See `raw()` for pixel ordering.
  * @param {Number} [options.raw.width]
  * @param {Number} [options.raw.height]
- * @param {Number} [options.raw.channels]
+ * @param {Number} [options.raw.channels] - 1-4
+ * @param {Object} [options.create] - describes a new image to be created.
+ * @param {Number} [options.create.width]
+ * @param {Number} [options.create.height]
+ * @param {Number} [options.create.channels] - 3-4
+ * @param {String|Object} [options.create.background] - parsed by the [color](https://www.npmjs.org/package/color) module to extract values for red, green, blue and alpha.
  * @returns {Sharp}
  * @throws {Error} Invalid parameters
  */