Class: Caman

Defined in: src/core/caman.coffee
Inherits: Module

Overview

Here it begins. Caman is defined. There are many different initialization for Caman, which are described on the Guides.

Initialization is tricky because we need to make sure everything we need is actually fully loaded in the DOM before proceeding. When initialized on an image, we need to make sure that the image is done loading before converting it to a canvas element and writing the pixel data. If we do this prematurely, the browser will throw a DOM Error, and chaos will ensue. In the event that we initialize Caman on a canvas element while specifying an image URL, we need to create a new image element, load the image, then continue with initialization.

The main goal for Caman was simplicity, so all of this is handled transparently to the end-user.

Property Summary

(Boolean) DEBUG

Debug mode enables console logging.

Class Method Summary

Instance Method Summary

Inherited Method Summary

Methods inherited from Module

.extends, .includes, .delegate, .aliasFunction, .aliasProperty, .included

Class Method Details

+ (String) toString()

Custom toString()

Returns:

  • (String) — Version and release information.

+ (String) getAttrId(canvas)

Get the ID assigned to this canvas by Caman.

Parameters:

  • canvas (DOMObject) — The canvas to inspect.

Returns:

  • (String) — The Caman ID associated with this canvas.

Constructor Details

- (Caman) Caman(initializer)
- (Caman) Caman(initializer, callback)
- (Caman) Caman(initializer, url)
- (Caman) Caman(initializer, url, callback)
- (Caman) Caman(file)
- (Caman) Caman(file, callback)

The Caman function. While technically a constructor, it was made to be called without the new keyword. Caman will figure it out.

Parameters:

  • initializer (DOMObject, String) — The DOM selector or DOM object to initialize.

Returns:

  • (Caman) — Initialized Caman instance.

Overloads:

- (Caman) Caman(initializer)

Initialize Caman without a callback.

- (Caman) Caman(initializer, callback)

Initialize Caman with a callback.

Parameters:

  • callback (Function) — Function to call once initialization completes.

- (Caman) Caman(initializer, url)

Initialize Caman with a URL to an image and no callback.

Parameters:

  • url (String) — URl to an image to draw to the canvas.

- (Caman) Caman(initializer, url, callback)

Initialize Caman with a canvas, URL to an image, and a callback.

Parameters:

  • url (String) — URl to an image to draw to the canvas.
  • callback (Function) — Function to call once initialization completes.

- (Caman) Caman(file)

NodeJS: Initialize Caman with a path to an image file and no callback.

Parameters:

  • file (String, File) — File object or path to image to read.

- (Caman) Caman(file, callback)

NodeJS: Initialize Caman with a file and a callback.

Parameters:

  • file (String, File) — File object or path to image to read.
  • callback (Function) — Function to call once initialization completes.

Instance Method Details

- (void) domIsLoaded(cb)

Checks to ensure the DOM is loaded. Ensures the callback is always fired, even if the DOM is already loaded before it's invoked. The callback is also always called asynchronously.

Parameters:

  • cb (Function) — The callback function to fire when the DOM is ready.

- (void) parseArguments(args)

Parses the arguments given to the Caman function, and sets the appropriate properties on this instance.

@params [Array] args Array of arguments passed to Caman.

- (void) setInitObject(obj)

Sets the initialization object for this instance.

Parameters:

  • obj (Object, String) — The initialization argument.

- (void) setup()

Begins the setup process, which differs depending on whether we're in NodeJS, or if an image or canvas object was provided.

- (void) initNode()

Initialization function for NodeJS.

- (void) initImage()

Initialization function for the browser and image objects.

- (void) initCanvas()

Initialization function for the browser and canvas objects.

- (void) imageAdjustments()

Automatically check for a HiDPI capable screen and swap out the image if possible. Also checks the image URL to see if it's a cross-domain request, and attempt to proxy the image. If a cross-origin type is configured, the proxy will be ignored.

- (void) waitForImageLoaded()

Utility function that fires Caman#imageLoaded once the image is finished loading.

- (Boolean) isImageLoaded()

Checks if the given image is finished loading.

Returns:

  • (Boolean) — Is the image loaded?

- (Number) imageWidth()

Internet Explorer has issues figuring out image dimensions when they aren't explicitly defined, apparently. We check the normal width/height properties first, but fall back to natural sizes if they are 0.

Returns:

  • (Number) — Width of the initialization image.

- (Number) imageHeight()

Returns:

  • (Number) — Height of the initialization image.

See also:

- (void) imageLoaded()

Function that is called once the initialization image is finished loading. We make sure that the canvas dimensions are properly set here.

- (void) finishInit()

Final step of initialization. We finish setting up our canvas element, and we draw the image to the canvas (if applicable).

- (void) reloadCanvasData()

If you have a separate context reference to this canvas outside of CamanJS and you make a change to the canvas outside of CamanJS, you will have to call this function to update our context reference to include those changes.

- (void) resetOriginalPixelData()

Reset the canvas pixels to the original state at initialization.

- (Boolean) hasId()

Does this instance have an ID assigned?

Returns:

  • (Boolean) — Existance of an ID.

- (void) assignId()

Assign a unique ID to this instance.

- (Boolean) hiDPIDisabled()

Is HiDPI support disabled via the HTML data attribute?

Returns:

  • Boolean

- (void) hiDPIAdjustments()

Perform HiDPI adjustments to the canvas. This consists of changing the scaling and the dimensions to match that of the display.

- (Number) hiDPIRatio()

Calculate the HiDPI ratio of this display based on the backing store and the pixel ratio.

Returns:

  • (Number) — The HiDPI pixel ratio.

- (Boolean) hiDPICapable()

Is this display HiDPI capable?

Returns:

  • Boolean

- (Boolean) needsHiDPISwap()

Do we need to perform an image swap with a HiDPI image?

Returns:

  • Boolean

- (String) hiDPIReplacement()

Gets the HiDPI replacement for the initialization image.

Returns:

  • (String) — URL to the HiDPI version.

- (void) replaceCanvas(newCanvas)

Replaces the current canvas with a new one, and properly updates all of the applicable references for this instance.

Parameters:

  • newCanvas (DOMObject) — The canvas to swap into this instance.

- (void) render(callback = function() {})

Begins the rendering process. This will execute all of the filter functions called either since initialization or the previous render.

Parameters:

  • callback (Function) — Function to call when rendering is finished.

- (void) revert(updateContext = true)

Reverts the canvas back to it's original state while maintaining any cropped or resized dimensions.

Parameters:

  • updateContext (Boolean) — Should we apply the reverted pixel data to the canvas context thus triggering a re-render by the browser?

- (void) reset()

Completely resets the canvas back to it's original state. Any size adjustments will also be reset.

- (Array) originalVisiblePixels()

Returns the original pixel data while maintaining any cropping or resizing that may have occured. Warning: this is currently in beta status.

Returns:

  • (Array) — Original pixel values still visible after cropping or resizing.

- (Caman) process(name, processFn)

Pushes the filter callback that modifies the RGBA object into the render queue.

Parameters:

  • name (String) — Name of the filter function.
  • processFn (Function) — The Filter function.

Returns:

- (Caman) processKernel(name, adjust, divisor = null, bias = 0)

Pushes the kernel into the render queue.

Parameters:

  • name (String) — The name of the kernel.
  • adjust (Array) — The convolution kernel represented as a 1D array.
  • divisor (Number) — The divisor for the convolution.
  • bias (Number) — The bias for the convolution.

Returns:

- (Caman) processPlugin(plugin, args)

Adds a standalone plugin into the render queue.

Parameters:

  • plugin (String) — Name of the plugin.
  • args (Array) — Array of arguments to pass to the plugin.

Returns:

- (Caman) newLayer(callback)

Pushes a new layer operation into the render queue and calls the layer callback.

Parameters:

  • callback (Function) — Function that is executed within the context of the layer. All filter and adjustment functions for the layer will be executed inside of this function.

Returns:

- (void) executeLayer(layer)

Pushes the layer context and moves to the next operation.

Parameters:

  • layer (Layer) — The layer to execute.

- (void) pushContext(layer)

Set all of the relevant data to the new layer.

Parameters:

  • layer (Layer) — The layer whose context we want to switch to.

- (void) popContext()

Restore the previous layer context.

- (void) applyCurrentLayer()

Applies the current layer to its parent layer.