Package ca.cgjennings.graphics.filters

Class BlurFilter

java.lang.Object

ca.cgjennings.graphics.filters.AbstractImageFilter

ca.cgjennings.graphics.filters.BlurFilter

All Implemented Interfaces:

java.awt.image.BufferedImageOp

Direct Known Subclasses:

BloomFilter

public class BlurFilter
extends AbstractImageFilter

A filter that performs a fast box blur operation. The operation is equivalent to convolving with a kernel where each element has a value equal to the inverse of the kernel size (a box blur).

An option is provided to repeat the blurring process in-place. Successive box blurs approximate the effect of a GaussianBlurFilter, but require significantly less time as long as the number of iterations is small.

The filter allows setting separate vertical and horizontal radii. The radii define the width and height of a rectangle (box) that determines the extent of the blur effect. The value of each pixel after filtering is determined by centering the pixel within the box and then computing the average value of all of the pixels within the box. By setting different values for the horizontal and vertical radius, it is possible to achieve various special effects, such as simulated motion blur.

In-place filtering: This class supports in-place filtering (the source and destination images can be the same).

Since:

3.0

Author:

Chris Jennings

See Also:

GaussianBlurFilter

Constructor Summary

Constructors

Constructor	Description
BlurFilter()	Creates a blur filter with a radius of 3.
BlurFilter(int radius, int iterations)	Creates a blur filter with equal horizontal and vertical radii.
BlurFilter(int horzRadius, int vertRadius, int iterations)	Creates a blur filter with the specified radii.

Method Summary

Modifier and Type	Method	Description
java.awt.image.BufferedImage	filter(java.awt.image.BufferedImage src, java.awt.image.BufferedImage dst)	Blurs the source image and places the result in a destination image.
int	getHorizontalRadius()	Returns the current horizontal blur radius.
int	getIterations()	Returns the number of times that the blurring operation will be repeated during filtering.
int	getVerticalRadius()	Returns the current vertical blur radius.
boolean	isPremultiplied()	Returns true if automatic premultiplication is enabled (the default).
void	setHorizontalRadius(int hRadius)	Sets the horizontal radius of the blur effect.
void	setIterations(int iterations)	Sets the number of times that the blurring operation should be repeated.
void	setPremultiplied(boolean enable)	Sets whether pixel data will be processed with a premultiplied alpha channel.
void	setRadius(int radius)	Sets the blur radius of the filter.
void	setVerticalRadius(int vRadius)	Sets the vertical radius of the blur effect.

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

BlurFilter

public BlurFilter()

Creates a blur filter with a radius of 3.

BlurFilter

public BlurFilter(int radius,
                  int iterations)

Creates a blur filter with equal horizontal and vertical radii.

Parameters:

radius - the radius of the blur

iterations - the number of times to repeat the blur

Throws:

java.lang.IllegalArgumentException - if radiusor iterations is negative

BlurFilter

public BlurFilter(int horzRadius,
                  int vertRadius,
                  int iterations)

Creates a blur filter with the specified radii.

Parameters:

horzRadius - the radius of the blur

vertRadius - the radius of the blur

iterations - the number of times to repeat the blur

Throws:

java.lang.IllegalArgumentException - if either radius or iterations is negative

Method Detail

setIterations

public final void setIterations(int iterations)

Sets the number of times that the blurring operation should be repeated. (The number of iterations may be 0, in which case no blurring will actually occur.) Repeated blurring will produce successively closer approximations of a Gaussian blur (but typically requires much less time).

Parameters:

iterations - the number of times to apply the blur filter

Throws:

java.lang.IllegalArgumentException - if the number of iterations is negative

getIterations

public final int getIterations()

Returns the number of times that the blurring operation will be repeated during filtering. This value may be 0, but cannot be negative.

Returns:

the number of times the blur effect is applied

setHorizontalRadius

public final void setHorizontalRadius(int hRadius)

Sets the horizontal radius of the blur effect. The filter box will have a width of twice this radius, plus one.

Parameters:

hRadius - the non-negative horizontal blur radius

Throws:

java.lang.IllegalArgumentException - if hRadius is negative

getHorizontalRadius

public final int getHorizontalRadius()

Returns the current horizontal blur radius.

Returns:

the non-negative horizontal blur radius

setVerticalRadius

public final void setVerticalRadius(int vRadius)

Sets the vertical radius of the blur effect. The filter box will have a height of twice this radius, plus one.

Parameters:

vRadius - the non-negative vertical blur radius

Throws:

java.lang.IllegalArgumentException - if vRadius is negative

getVerticalRadius

public final int getVerticalRadius()

Returns the current vertical blur radius.

Returns:

the non-negative vertical blur radius

setRadius

public final void setRadius(int radius)

Sets the blur radius of the filter. This is a convenience method that sets both the horizontal and vertical radii to the same value.

Parameters:

radius - the non-negative blur radius

Throws:

java.lang.IllegalArgumentException - if radius is negative

setPremultiplied

public final void setPremultiplied(boolean enable)

Sets whether pixel data will be processed with a premultiplied alpha channel. Setting this to true (the default) can avoid a common artifact that appears when transparent pixels are a very different colour than surrounding translucent or opaque pixels. The artifact manifests as a fringe of the non-matching colour(s) around the edges of the non-transparent parts of the image. Although premultiplication avoids this artifact, it also increases processing time and decreases colour accuracy.

Parameters:

enable - if true, pixel values will be premultiplied by their alpha value before processing, and unpremultiplied afterward

isPremultiplied

public final boolean isPremultiplied()

Returns true if automatic premultiplication is enabled (the default).

Returns:

true if pixel values will be premultiplied by their alpha value before processing, and unpremultiplied afterward

See Also:

setPremultiplied(boolean)

filter

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

Blurs the source image and places the result in a destination image. The destination image may be null, in which case a compatible image is created automatically. It may also be the source image, in which case the original image data is replaced by the result.

Parameters:

src - the source image to blur

dst - the destination image to copy the result to, or null

Returns:

the destination image