pixelworks

⚙ pixelworks

Utilities for working with ImageData in Workers.

Install

The pixelworks package is meant to be used in a browser with a CommonJS module loader (e.g. Browserify or Webpack). Add it as a dependency to your project with npm:

npm install pixelworks

Use

var pixelworks = require('pixelworks');

The package also comes with a standalone build in the dist directory that can be added to a page with a script tag. If a module loader is not present, this script will make a global pixelworks object available.

API

new Processor(options)

A processor runs pixel or image operations in workers.

var processor = new pixelworks.Processor(options);

Supported options

• imageOps : boolean - By default, operations will be called for each pixel. By setting imageOps: true, operations will be called with an ImageData object.

• operations : Array - Operations are functions that process input data and return output data. Operations are called with two arguments: an array of inputs, and a user storage object. By default, operations will be called for each pixel in the input data, and the first argument is an array of input pixels (each a [R, G, B, A] array). If imageOps is false, the first argument will be an array of ImageData objects. The second object is the user storage object passed to the process method.

Operations return processed output data. For pixel-wise operations, this must be an array of output pixels (each a [R, G, B, A] array). For image operations, this must be an array of ImageData objects. The return from one operation is passed as input to the next, so the operations serve as a data pipeline.

Because operations run in workers, they must only operate on the arguments they are given.

• threads : number - Pixel-wise operations can be run in parallel in multiple worker threads. By default, a single worker thread is created for running operations. Setting threads: 2 would process half of the input pixels in one thread and half in another. For image type operations, threads cannot be greater than 1. If you want to force operations to run in the main (UI) thread, set threads: 0.

• queue : number - Maximum queue length. This limits the number of pending workers when process is called multiple times before work completes. If you want to call process many times (in response to user generated events for example), set queue: 1, and only one worker will be pending at a time.

processor.process(inputs, meta, callback)

Run operations on an array of input image data.

• inputs : Array.<ImageData> - Array of pixels or image data (depending on the operation type).
• meta : Object - A user data object. This is passed to all operations and must be serializable.
• callback : function(Error, ImageData, Object) - Called when work completes. The first argument is any error. The second is the ImageData generated by operations. The third is the user data object. When process is called repeatedly, a queue of pending workers will be generated. If this queue exceeds the maximum queue length, workers will be removed from the queue and the callback will be called with null for the second ImageData argument.

processor.destroy()

Stop responding to any completed work and destroy the processor.