Tinting modified the original image by adusting its hue, saturation, and brightness. Hue refers to the colour of the image pixels. The change in hue is expressed as an anglular distance around a colour wheel. (So, shifting the hue by 180 degrees would change the colour to its complementary colour, on the opposite side of the colour wheel.) Saturation describes the purity of the image pixels. The lower the saturation, the more grayish and washed out the colour appears. A saturation of 0 results in a shade of grey; a saturation of 1 results in the purest possible expression of the hue. The saturation adjustment for tinting is expressed as a scaling factor, a multiplier that is applied to the original value. Brightness describes how light or dark the image appears. A brightness of 0 results in a completely black image. A brightness of 1 results in the brightest possible colour within the limitations of the hue and saturation. Like saturation, the brightness adjustment for tinting is expressed as a scaling factor.
The hue angle is measured using a scale in which 1 is equal to 360 degrees (a full circle). Values will normally range from -0.5 to +0.5 (-180 to +180 degrees), but values outside of this range are acceptable. A value of 0 leaves the original hue unchanged.
The saturation and brightness values are factors multiplied against the saturation and brightness of the source pixel. Factors less than 0 are treated as 0. Factors may be more than 1 (100%). If the scaled value for a given pixel is more than 1, it is clamped at 1 in the result.
If using an HSBPanel, it will always provide a hue between -0.5 and +0.5, and saturation and brightness values between 0 and 1. Depending on the saturation and brightness of the source image, you may wish to scale those values up or down before passing them to the TintCache. Otherwise, using the panel it will only be possible to decrease the brightness and saturation (or keep it the same). For example, if you wanted the maximum brightness scale to be 1.2 (120%), multiply the value returned from the HSBPanel by 1.2. When choosing the default brightness, use 1/1.2 if you want the default settings to work out to the original image (1/1.2 * 1.2 = 1).
For convenience, the class TintFilter.ScaledTintFilter can perform scaling for you:
// scale saturation to 120%, brightness to 200% var f = new TintFilter.ScaledTintFilter( h, s, b, 1.2, 2.0 );A ScaledTintFilter gets and sets factors between 0 and 1 as usual, but internally applies the requested scaling factors.
To create a new tint cache, you must pass in a new instance of the tinting filter class that you wish to use (typically an instance of TintFilter).
For example:
// during setup: var frontTinter = new TintCache( new TintFilter() ); frontTinter.setImage( frontImage ); // ... // during drawing: frontTinter.setFactors( hueShift, saturationScale, brightnessScale ); var tintedImage = frontTinter.getTintedImage();
| image | a BufferedImage that will be tinted using the tinting filter |
| hue | the hue adjustment; the exact effect depends on the filter used |
| saturation | the saturation adjustment; the exact effect depends on the filter used |
| brightness | the brightness adjustment; the exact effect depends on the filter used |
If the current source image data has been modified by writing to the image (for example, if you used as the destination image for some other filtering operation), then you should force any cached result to be cleared before calling this method. An example:
var tc = new TintCache( new TintFilter() ); tc.setFactors( -0.25, 1, 0.8 ); tc.setImage( source ); // ... var tinted = TintCache.getTintedImage(); var g = source.createGraphics(); try { // ... // modify the pixels in "source" // ... } finally { g.dispose(); } // force clearing cached results before getting tinted version // of the modified source image: tc.setImage( null ); tc.setImage( source ); tinted = TintCache.getTintedImage();
returns a tinted version of the source image