Creating a Plugin

Creating a plugin for CamanJS is extremely simple. All plugins should be registered with Caman.Filter in order to work.

That being said, there are a few "rules" (so to speak), that must be followed in order to make sure everything works as expected. All plugins should be placed in the plugins directory provided with CamanJS in order to ensure compatibility with NodeJS.

Example Pixel-wise Plugin

This is a really simple example plugin that shows the basic plugin structure and requirements. In this example, the plugin iterates over every pixel in the image, and adjusts each one independently. This is the most popular type of plugin, and the easiest to understand.

// A simple filter that doesn't really do anything very useful,
// but that's ok. It's the details that count.
//
// The first argument is the name of the filter function, and the
// 2nd argument is the filter function itself.
Caman.Filter.register("crazyFilter", function (adjust) {
	// Here, you can do any calculations that need to be done prior
	// to using the plugin.
	adjust /= 100;
	
	/*
	 * Everything inside of the process() function will be run in a loop that
	 * iterates over every pixel in the image. The only argument is the 
	 * rgba values of the current pixel in the loop iteration. The `adjust`
	 * variable will be available to your process function thanks to closure.
	 *
	 * Important to note: we return the result of the process function, which
	 * makes sure subsequent filters work properly (chaining). We also name the function
	 * we pass to process() in the 1st argument because this helps CamanJS 
	 * identify it when it goes to render the function.
	 */
	return this.process("crazyFilter", function (rgba) {
		// Modify the current pixel
		rgba.r *= adjust;
		rgba.g += adjust * 100;
		rgba.b *= adjust / 2;
		
		// Here, we must return the rgba object, or else our changes will not be
		// saved and applied to the image data.
		return rgba;
	});
};

Example Convolution Matrix Plugin

CamanJS also offers functionality that lets you modify images based on a convolution matrix. If you have no idea what that means, I recommend that you read this article from the GIMP manual.

Below is an example plugin that uses a convolution matrix to modify the image:

// This is an actual filter from the blur plugin. It applies a
// simple radial blur to the image.
Caman.Filter.register("radialBlur", function () {
	// Of course, we can do some preprocessing here if needed.
	//
	// Instead of calling process(), we call processKernel().
	// The first argument is an arbitrary name that is used to
	// identify the filter. The 2nd argument is the matrix expressed
	// with a 1D array. It can be any size, as long as it is square and has
	// an odd number of elements.
	//
	// The 3rd and 4th arguments are optional. The 3rd argument lets you
	// specify the divisor and the 4rd argument is the bias. They are both
	// automatically calculated by default.
  return this.processKernel('Radial Blur', [
    0, 1, 0,
    1, 1, 1,
    0, 1, 0
  ]);
};

Example Advanced Plugin

Finally, if you want the most control over the canvas data, you can create a plugin that has to do some work manually. A good example of this is the Compound Blur plugin that applies gaussian-like blurs extremely fast using the StackBlur algorithm.

(function (Caman) {
	// This is a really short example of a plugin that doesn't do much
	// but gives you an idea of how to structure things.
	Caman.Plugin.register("awesomeSauce", function (options) {
		var width = this.dimensions.width;
		var height = this.dimensions.height;
		
		var pixels = this.pixelData;
		/* Do stuff with the pixels */
	};
	
	// Now we register a filter so we can call the plugin
	Caman.Filter.register("awesomeSauce", function (options) {
	 // Using processPlugin makes sure that the plugin is called
	 // with the correct context and data. This uses apply() behind
	 // the scenes, hence the [] to pass the options. You could also
	 // simply pass the arguments array.
	 return this.processPlugin("awesomeSauce", [options]);
	};
}(Caman));