Miniwindows in MUSHclient - Blending images

Written by Nick Gammon - July 2008. Updated September 2010.

On this page:

WindowBlendImage
Normal
Average
Interpolate
Dissolve

See also:

Introduction to blending

Blending is a way of loading an image on top of an existing portion of a miniwindow (or all of it). You can specify two things when blending:

The blend mode - this specifies the mathematical operation which is performed to merge the two layers together (the base layer and the new image). The various operations have widely different effects, including lightening, darkening, and other merging effects.
An opacity amount - this specifies the opacity of the blend layer - that is, the amount to which it affects the original layer. This is a floating-point value between 0 and 1, where 0 is no effect, and 1 is the blend effect is applied 100%.

Blending the image

Before images can be blended to the miniwindow, the image must be "loaded". See Getting started with images - loading the image for how to do this.

WindowBlendImage function prototype:


long WindowBlendImage(BSTR Name, BSTR ImageId, long Left, long Top, long Right, long Bottom, short Mode, double Opacity, long SrcLeft, long SrcTop, long SrcRight, long SrcBottom);

This blends the specified image into the miniwindow, on top of the specified rectangle.

Name - the name of an existing miniwindow.
ImageId - an image id that you have previously loaded.
Left, Top, Right, Bottom - describes the destination rectangle. The blend image is merged with the contents of this rectangle to produce the blended result.

Mode - the blending method. Click on the links to see a description and example of each mode.

Value	Purpose	Lua symbol
1	Normal	miniwin.blend_normal
2	Average	miniwin.blend_average
3	Interpolate	miniwin.blend_interpolate
4	Dissolve	miniwin.blend_dissolve
5	Darken	miniwin.blend_darken
6	Multiply	miniwin.blend_multiply
7	Colour Burn	miniwin.blend_colour_burn
8	Linear Burn	miniwin.blend_linear_burn
9	Inverse Colour Burn	miniwin.blend_inverse_colour_burn
10	Subtract	miniwin.blend_subtract
11	Lighten	miniwin.blend_lighten
12	Screen	miniwin.blend_screen
13	Colour Dodge	miniwin.blend_colour_dodge
14	Linear Dodge	miniwin.blend_linear_dodge
15	Inverse Colour Dodge	miniwin.blend_inverse_colour_dodge
16	Add	miniwin.blend_add
17	Overlay	miniwin.blend_overlay
18	Soft Light	miniwin.blend_soft_light
19	Hard Light	miniwin.blend_hard_light
20	Vivid Light	miniwin.blend_vivid_light
21	Linear Light	miniwin.blend_linear_light
22	Pin Light	miniwin.blend_pin_light
23	Hard Mix	miniwin.blend_hard_mix
24	Difference	miniwin.blend_difference
25	Exclusion	miniwin.blend_exclusion
26	Reflect	miniwin.blend_reflect
27	Glow	miniwin.blend_glow
28	Freeze	miniwin.blend_freeze
29	Heat	miniwin.blend_heat
30	Negation	miniwin.blend_negation
31	Phoenix	miniwin.blend_phoenix
32	Stamp	miniwin.blend_stamp
33	Xor	miniwin.blend_xor
34	And	miniwin.blend_and
35	Or	miniwin.blend_or
36	Red	miniwin.blend_red
37	Green	miniwin.blend_green
38	Blue	miniwin.blend_blue
39	Yellow	miniwin.blend_yellow
40	Cyan	miniwin.blend_cyan
41	Magenta	miniwin.blend_magenta
42	Green limited by red	miniwin.blend_green_limited_by_red
43	Green limited by blue	miniwin.blend_green_limited_by_blue
44	Green limited by average of red and blue	miniwin.blend_green_limited_by_average_of_red_and_blue
45	Blue limited by red	miniwin.blend_blue_limited_by_red
46	Blue limited by green	miniwin.blend_blue_limited_by_green
47	Blue limited by average of red and green	miniwin.blend_blue_limited_by_average_of_red_and_green
48	Red limited by green	miniwin.blend_red_limited_by_green
49	Red limited by blue	miniwin.blend_red_limited_by_blue
50	Red limited by average of green and blue	miniwin.blend_red_limited_by_average_of_green_and_blue
51	Red only	miniwin.blend_red_only
52	Green only	miniwin.blend_green_only
53	Blue only	miniwin.blend_blue_only
54	Discard red	miniwin.blend_discard_red
55	Discard green	miniwin.blend_discard_green
56	Discard blue	miniwin.blend_discard_blue
57	All red	miniwin.blend_all_red
58	All green	miniwin.blend_all_green
59	All blue	miniwin.blend_all_blue
60	Hue mode	miniwin.blend_hue_mode
61	Saturation mode	miniwin.blend_saturation_mode
62	Colour mode	miniwin.blend_colour_mode
63	Luminance mode	miniwin.blend_luminance_mode
64	HSL	miniwin.blend_hsl

Opacity - the amount of opacity, between 0 and 1 (floating-point number). An opacity of 0 means you will not see the blend image. An opacity of 1 means the blend is fully applied. An opacity of 0.5 means the blended images is merged 50% with the original contents of the miniwindow.
SrcLeft, SrcTop, SrcRight, SrcBottom - the source rectangle in the original image (use 0,0,0,0 to get the whole image). Negative numbers for the SrcRight and SrcBottom parameters represent an offset from the bottom or right edge.
When blending, whichever rectangle is smaller is the one used for the width and height of the operation (the destination rectangle or the source rectangle).

Example of blending an image


WindowBlendImage (win, "im", 0, 0, 0, 0, miniwin.blend_normal, 0.5)  --normal mode at 50% opacity

Base image (in miniwindow)	Blend image (mentioned in WindowBlendImage)

Normal mode is a straight copy of each pixel from the blend to the base layer. If opacity is 100% then you will only see the blend image. The only point of using normal mode is if you have the opacity at less than 100%.

25% opacity

50% opacity

75% opacity

In these examples you can see how increasing the opacity makes more and more of the blended image appear on top of the base image. Note that the base "image" doesn't have to be literally a picture, it is whatever text, shapes or other graphics are in the destination rectangle in the miniwindow.

Commutative modes

Some blend modes are commutative - that is, blending A on top of B is the same as B on top of A. The descriptions for the various modes will mention when a mode is commutative. Multiply mode is an example of a commutative mode, because the pixel values are multiplied together, and A x B is the same as B x A.

Performance considerations

Blending images tends to be computation-expensive. For example, for a 600 x 600 pixel image, the program has to apply a calculation to 600 x 600 x 3 bytes (one for each of red, green and blue), which would be 1,080,000 calculations. There are more calculations needed if you specify an opacity other than 1, as it needs to merge the computed image back on top of the base image. Suggested techniques for keeping things moving quickly are:

Keep blending to as small a size rectangle as possible. For example, don't needlessly blend a lot of "white space" around the part you are interested in. Keep the borders tight.
Use an opacity of 1.0 (100%) if possible, otherwise a further calculation is needed for each pixel to merge the blended image with the base image, with the correct opacity.
Some blending operations are slower than others. If there are two that give similar results, and one is noted to be faster, choose the faster one.
If possible, blend once, and use the blended image many times. As you can use miniwindows as image sources for other miniwindows, consider setting up a blended image once, and then just copying it in when needed (eg. draw an elaborate background once, and then just copy in the result when needed).

Some simple modes

Average mode (2)

Average mode is the same as normal mode with 50% opacity. Effectively, it is an average of both images.

This mode is commutative (base and blend layer can be swapped).

Interpolate mode (3)

This is similar to average mode, but has better contrast. It uses a cosine calculation for its calculations and is likely to be slower than average mode.

This mode is commutative (base and blend layer can be swapped).

Dissolve mode (4)

This randomly chooses pixels from the base layer or the blend layer, giving a rather strange speckled look. The number of pixels chosen is controlled by the opacity, at 100% opacity you would only see the blend layer. The example below shows dissolve mode at 50% opacity (an opacity parameter of 0.5):

Further reference

I got some inspiration and formulae from the Pegtop.net - Blend Modes series of web pages. There is a lengthy description there of the various modes, along with some of the mathematics behind them.

I got quite a few of the C formulae from Photoshop Blend Mode Math web page.

Both of those pages have example images and examples of various blend modes in operation.

Examples on this page

The examples on this page are taken from Fields of gold... by Spiralz, and Thanks to solea by jam343. These are licensed for royalty-free use under the Attribution 2.5 Generic License. They were obtained from the web site http://www.everystockphoto.com/.

Some ideas and descriptions were adapated from the Pegtop.net Blend Modes article.