org.jdesktop.swingx.graphics
Class BlendComposite

java.lang.Object
  org.jdesktop.swingx.graphics.BlendComposite

All Implemented Interfaces:

Composite

public final class BlendComposite
extends Object
implements Composite

A blend composite defines the rule according to which a drawing primitive (known as the source) is mixed with existing graphics (know as the destination.)

BlendComposite is an implementation of the Composite interface and must therefore be set as a state on a Graphics2D surface.

Please refer to Graphics2D.setComposite(java.awt.Composite) for more information on how to use this class with a graphics surface.

Blending Modes

This class offers a certain number of blending modes, or compositing rules. These rules are inspired from graphics editing software packages, like Adobe Photoshop or The GIMP.

Given the wide variety of implemented blending modes and the difficulty to describe them with words, please refer to those tools to visually see the result of these blending modes.

Opacity

Each blending mode has an associated opacity, defined as a float value between 0.0 and 1.0. Changing the opacity controls the force with which the compositing operation is applied. For instance, a composite with an opacity of 0.0 will not draw the source onto the destination. With an opacity of 1.0, the source will be fully drawn onto the destination, according to the selected blending mode rule.

The opacity, or alpha value, is used by the composite instance to mutiply the alpha value of each pixel of the source when being composited over the destination.

Creating a Blend Composite

Blend composites can be created in various manners:

• Use one of the pre-defined instance. Example: BlendComposite.Average.
• Derive one of the pre-defined instances by calling derive(float) or derive(BlendingMode). Deriving allows you to change either the opacity or the blending mode. Example: BlendComposite.Average.derive(0.5f).
• Use a factory method: getInstance(BlendingMode) or getInstance(BlendingMode, float).

Implementation Caveat

TThe blending mode SoftLight has not been implemented yet.

See Also:

BlendComposite.BlendingMode, Graphics2D, Composite, AlphaComposite

Nested Class Summary

static class

BlendComposite.BlendingMode A blending mode defines the compositing rule of a BlendComposite.

Field Summary

static BlendComposite	Add
static BlendComposite	Average
static BlendComposite	Blue
static BlendComposite	Color
static BlendComposite	ColorBurn
static BlendComposite	ColorDodge
static BlendComposite	Darken
static BlendComposite	Difference
static BlendComposite	Exclusion
static BlendComposite	Freeze
static BlendComposite	Glow
static BlendComposite	Green
static BlendComposite	HardLight
static BlendComposite	Heat
static BlendComposite	Hue
static BlendComposite	InverseColorBurn
static BlendComposite	InverseColorDodge
static BlendComposite	Lighten
static BlendComposite	Luminosity
static BlendComposite	Multiply
static BlendComposite	Negation
static BlendComposite	Overlay
static BlendComposite	Red
static BlendComposite	Reflect
static BlendComposite	Saturation
static BlendComposite	Screen
static BlendComposite	SoftBurn
static BlendComposite	SoftDodge
static BlendComposite	SoftLight
static BlendComposite	Stamp
static BlendComposite	Subtract

Method Summary

CompositeContext	createContext(ColorModel srcColorModel, ColorModel dstColorModel, RenderingHints hints) Creates a context containing state that is used to perform the compositing operation.
BlendComposite	derive(BlendComposite.BlendingMode mode) Returns a BlendComposite object that uses the specified blending mode and this object's alpha value.
BlendComposite	derive(float alpha) Returns a BlendComposite object that uses the specified opacity, or alpha, and this object's blending mode.
boolean	equals(Object obj) Indicates whether some other object is "equal to" this one.
float	getAlpha() Returns the opacity of this composite.
static BlendComposite	getInstance(BlendComposite.BlendingMode mode) Creates a new composite based on the blending mode passed as a parameter.
static BlendComposite	getInstance(BlendComposite.BlendingMode mode, float alpha) Creates a new composite based on the blending mode and opacity passed as parameters.
BlendComposite.BlendingMode	getMode() Returns the blending mode of this composite.
int	hashCode() Returns a hash code value for the object.

Methods inherited from class java.lang.Object

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

Field Detail

Average

public static final BlendComposite Average

Multiply

public static final BlendComposite Multiply

Screen

public static final BlendComposite Screen

Darken

public static final BlendComposite Darken

Lighten

public static final BlendComposite Lighten

Overlay

public static final BlendComposite Overlay

HardLight

public static final BlendComposite HardLight

SoftLight

public static final BlendComposite SoftLight

Difference

public static final BlendComposite Difference

Negation

public static final BlendComposite Negation

Exclusion

public static final BlendComposite Exclusion

ColorDodge

public static final BlendComposite ColorDodge

InverseColorDodge

public static final BlendComposite InverseColorDodge

SoftDodge

public static final BlendComposite SoftDodge

ColorBurn

public static final BlendComposite ColorBurn

InverseColorBurn

public static final BlendComposite InverseColorBurn

SoftBurn

public static final BlendComposite SoftBurn

Reflect

public static final BlendComposite Reflect

Glow

public static final BlendComposite Glow

Freeze

public static final BlendComposite Freeze

Heat

public static final BlendComposite Heat

Add

public static final BlendComposite Add

Subtract

public static final BlendComposite Subtract

Stamp

public static final BlendComposite Stamp

Red

public static final BlendComposite Red

Green

public static final BlendComposite Green

Blue

public static final BlendComposite Blue

Hue

public static final BlendComposite Hue

Saturation

public static final BlendComposite Saturation

Color

public static final BlendComposite Color

Luminosity

public static final BlendComposite Luminosity

Method Detail

getInstance

public static BlendComposite getInstance(BlendComposite.BlendingMode mode)

Creates a new composite based on the blending mode passed as a parameter. A default opacity of 1.0 is applied.

Parameters:

mode - the blending mode defining the compositing rule

Returns:

a new BlendComposite based on the selected blending mode, with an opacity of 1.0

getInstance

public static BlendComposite getInstance(BlendComposite.BlendingMode mode,
                                         float alpha)

Creates a new composite based on the blending mode and opacity passed as parameters. The opacity must be a value between 0.0 and 1.0.

Parameters:

mode - the blending mode defining the compositing rule

alpha - the constant alpha to be multiplied with the alpha of the source. alpha must be a floating point between 0.0 and 1.0.

Returns:

a new BlendComposite based on the selected blending mode and opacity

Throws:

IllegalArgumentException - if the opacity is less than 0.0 or greater than 1.0

derive

public BlendComposite derive(BlendComposite.BlendingMode mode)

Returns a BlendComposite object that uses the specified blending mode and this object's alpha value. If the newly specified blending mode is the same as this object's, this object is returned.

Parameters:

mode - the blending mode defining the compositing rule

Returns:

a BlendComposite object derived from this object, that uses the specified blending mode

derive

public BlendComposite derive(float alpha)

Returns a BlendComposite object that uses the specified opacity, or alpha, and this object's blending mode. If the newly specified opacity is the same as this object's, this object is returned.

Parameters:

alpha - the constant alpha to be multiplied with the alpha of the source. alpha must be a floating point between 0.0 and 1.0.

Returns:

a BlendComposite object derived from this object, that uses the specified blending mode

Throws:

IllegalArgumentException - if the opacity is less than 0.0 or greater than 1.0

getAlpha

public float getAlpha()

Returns the opacity of this composite. If no opacity has been defined, 1.0 is returned.

Returns:

the alpha value, or opacity, of this object

getMode

public BlendComposite.BlendingMode getMode()

Returns the blending mode of this composite.

Returns:

the blending mode used by this object

hashCode

public int hashCode()

Returns a hash code value for the object. This method is supported for the benefit of hashtables such as those provided by java.util.Hashtable.

The general contract of hashCode is:

• Whenever it is invoked on the same object more than once during an execution of a Java application, the hashCode method must consistently return the same integer, provided no information used in equals comparisons on the object is modified. This integer need not remain consistent from one execution of an application to another execution of the same application.
• If two objects are equal according to the equals(Object) method, then calling the hashCode method on each of the two objects must produce the same integer result.
• It is not required that if two objects are unequal according to the Object.equals(java.lang.Object) method, then calling the hashCode method on each of the two objects must produce distinct integer results. However, the programmer should be aware that producing distinct integer results for unequal objects may improve the performance of hashtables.

As much as is reasonably practical, the hashCode method defined by class Object does return distinct integers for distinct objects. (This is typically implemented by converting the internal address of the object into an integer, but this implementation technique is not required by the Java^TM programming language.)

Overrides:

hashCode in class Object

Returns:

a hash code value for this object.

See Also:

Object.equals(java.lang.Object), Hashtable

equals

public boolean equals(Object obj)

Indicates whether some other object is "equal to" this one.

The equals method implements an equivalence relation on non-null object references:

• It is reflexive: for any non-null reference value x, x.equals(x) should return true.
• It is symmetric: for any non-null reference values x and y, x.equals(y) should return true if and only if y.equals(x) returns true.
• It is transitive: for any non-null reference values x, y, and z, if x.equals(y) returns true and y.equals(z) returns true, then x.equals(z) should return true.
• It is consistent: for any non-null reference values x and y, multiple invocations of x.equals(y) consistently return true or consistently return false, provided no information used in equals comparisons on the objects is modified.
• For any non-null reference value x, x.equals(null) should return false.

The equals method for class Object implements the most discriminating possible equivalence relation on objects; that is, for any non-null reference values x and y, this method returns true if and only if x and y refer to the same object (x == y has the value true).

Note that it is generally necessary to override the hashCode method whenever this method is overridden, so as to maintain the general contract for the hashCode method, which states that equal objects must have equal hash codes.

Overrides:

equals in class Object

Parameters:

obj - the reference object with which to compare.

Returns:

true if this object is the same as the obj argument; false otherwise.

See Also:

Object.hashCode(), Hashtable

createContext

public CompositeContext createContext(ColorModel srcColorModel,
                                      ColorModel dstColorModel,
                                      RenderingHints hints)

Creates a context containing state that is used to perform the compositing operation. In a multi-threaded environment, several contexts can exist simultaneously for a single Composite object.

Specified by:

createContext in interface Composite

Parameters:

srcColorModel - the ColorModel of the source

dstColorModel - the ColorModel of the destination

hints - the hint that the context object uses to choose between rendering alternatives

Returns:

the CompositeContext object used to perform the compositing operation.