Package ca.cgjennings.graphics.filters

Class AbstractPixelwiseFilter

java.lang.Object

ca.cgjennings.graphics.filters.AbstractImageFilter

ca.cgjennings.graphics.filters.AbstractPixelwiseFilter

All Implemented Interfaces:

java.awt.image.BufferedImageOp

Direct Known Subclasses:

AbstractFunctionFilter, AbstractTintingFilter, AlphaInversionFilter, AlphaStrengthenFilter, ChannelFunctionFilter, ChannelSwapFilter, ClearFilter, CloneFilter, ColorOverlayFilter, CompoundPixelwiseFilter, DarkMagicFilter, GammaCorrectionFilter, GreyscaleFilter, InversionFilter, SubstitutionFilter

public abstract class AbstractPixelwiseFilter
extends AbstractImageFilter

An abstract superclass for filters that work on a pixel-by-pixel basis, where the new value of a given pixel is independent of every other pixel and the location of the pixel in the image. For efficiency, the filtering method is called with arrays of ARGB values to filter rather than being called once for each pixel.

In-place filtering: Unless otherwise noted, filters based on this class support in-place filtering (the source and destination images can be the same).

Note: Concrete subclasses may override filter(java.awt.image.BufferedImage, java.awt.image.BufferedImage) in order to perform setup or cleanup steps before or after filtering begins, but should call the superclass to execute the filter. The superclass will automatically perform filtering in parallel on systems with multiple CPUs, and may also use other techniques to accelerate filtering.

Constructor Summary

Constructors

Constructor	Description
AbstractPixelwiseFilter()

Method Summary

Modifier and Type	Method	Description
void	filter(int[] argb)	Filters an array of raw pixel data in place.
java.awt.image.BufferedImage	filter(java.awt.image.BufferedImage src, java.awt.image.BufferedImage dest)
int	filterPixel(int argb)	Returns the result of applying the filter to a single ARGB pixel value.
abstract void	filterPixels(int[] argb, int start, int end)	This method is called with a block of ARGB values to be filtered.
protected float	workFactor()	Returns a factor representing the amount of work performed by this filter relative to a filter that simply copies the source image by reading and writing each pixel.

Methods inherited from class ca.cgjennings.graphics.filters.AbstractImageFilter

clamp, clamp, clamp, clampBoth, createCompatibleDestImage, fA, fB, fG, fR, getARGB, getARGB, getARGBSynch, getBounds2D, getPoint2D, getRenderingHints, iA, iB, iG, iR, setARGB, setARGB, setARGBSynch

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

AbstractPixelwiseFilter

public AbstractPixelwiseFilter()

Method Detail

filter

public java.awt.image.BufferedImage filter(java.awt.image.BufferedImage src,
                                           java.awt.image.BufferedImage dest)

filter

public void filter(int[] argb)

Filters an array of raw pixel data in place. This allows other filters that operate on arrays of pixel data to make use of the filter as part of their internal processing without the need to write data into a temporary image. Like the standard filter(java.awt.image.BufferedImage, java.awt.image.BufferedImage) method, this method will automatically perform filtering in parallel when appropriate.

Parameters:

argb - the ARGB pixel values to filter; the filtered results will overwrite these values

filterPixels

public abstract void filterPixels(int[] argb,
                                  int start,
                                  int end)

This method is called with a block of ARGB values to be filtered. Subclasses must override this method to implement the actual filtering algorithm by replacing each pixel value in the range argb[start] ... argb[end-1] with the filtered value.

Parameters:

argb - an array of pixel data to filter

start - the index of the first pixel to filter

end - the index of the last pixel to filter, plus one

filterPixel

public int filterPixel(int argb)

Returns the result of applying the filter to a single ARGB pixel value.

The base class implementation creates a singleton array containing the pixel value and passes this to filterPixels(int[], int, int), returning the result. Subclasses may wish override this to provide a more efficient implementation.

Parameters:

argb - the pixel value to filter

Returns:

the filtered pixel value

workFactor

protected float workFactor()

Returns a factor representing the amount of work performed by this filter relative to a filter that simply copies the source image by reading and writing each pixel. For example, a filter that implemented a 3x3 convolution might return the value 9. The work factor value helps determine when an image should be processed in parallel. (There is significant overhead involved in running a filter in parallel, so it is only worth doing if the image is relatively large or the amount of processing per pixel is relatively high.)

Note: The work factor may vary depending on the current filter settings.

Returns:

the approximate amount of work per pixel, relative to simply copying the pixel values