LuaAPI/gui

Image Path Functions provide a simple method for WML coders to alter the way their specified images will be displayed in the game. All of the function parameters are included at the end of an image path and should not contain any spaces or special characters (other than those specified here).

If you need to practice it without having to reload all WML, you can use an add-on named Image loading tester. It is available on the 1.9, 1.10, 1.11, 1.12 and 1.14 add-on servers.

All functions are applied in left-to-right order, with the exception of RC(), TC() and PAL() which are applied always before any other functions. Standard team coloring for a unit is applied after all custom RC(), TC() and PAL() functions but before any other functions. That is, stuff like

"units/elves-wood/fighter.png~CROP(20,20,40,40)~CROP(10,10,10,10)"

would result in taking a crop to a 40x40 rectangle whose top-left corner is x=20, y=20; and then taking a crop from that rectangle with x=10, y=10, w=10, h=10. The result is the area x=30, y=30, w=10, h=10 from the original graphic.

Changing the colors

BLEND: Color-blend function

Blends the image with the given color to produce a more controlled tinting effect than color-shifting, independently of the image's contents.

~BLEND(r,g,b,o)

The color is defined by the r, g, and b parameters (integers ranging from 0 to 255). The o (opacity) parameter controls the amount by which the given color will be blended into the image, and may be specified either as a factor from 0.0 to 1.0, or percentage up to 100%. Thus, ~BLEND(r,g,b,0.5) and ~BLEND(r,g,b,50%) are equivalent.

BW: Black and White function

(Version 1.13.1 and later only) May be used to convert the image to pure black and white, without grey pixels.

~BW(threshold)

• threshold: a value between 0 and 255 (both limits included). All pixels are converted as greyscale first, and if their average value is greater than the threshold they become white, otherwise they become black.

CS: Color-shift function

Performs simple per-channel color shifts by adding the arguments to the respective color channels.

Multi-channel: ~CS(r,g,b) Single-channel: ~R(v), ~G(v), ~B(v)

The multichannel syntax assumes all arguments are set to zero initially, so one can use, e.g. ~CS(2,4) to add +2 and +4 units to the red and green channels respectively, leaving the blue channel intact. Arguments may be negative to diminish a channel's value; this can be used to change an image's brightness. Checks for out-of-range arguments or results (less than 0 or greater than 255) are made, so the resultant values are truncated if necessary.

The single channel syntax behaves exactly the same, except that only single-channel modifications are made per function. However, one can stack them to produce the same behavior as ~CS(), e.g. ~R(r)~G(g)~B(b), but that tends to be just a performance loss.

GS: Greyscale function

May be used to greyscale the image (turn to black and white)

~GS( )

L: Lightmap color-shift function

Performs per-pixel and per-channel color shifts using another image (a "lightmap") as source, allowing to create textured light effects.

~L(lightmap)

For each pixel of the original image, it checks the RGB values from the corresponding pixel of the lightmap, slightly transform them, then add these values to the original pixel.

The transformation involved is done to convert the (0,255) spectrum to (-255,255), allowing to add or subtract color. The formula is (x-128)*2, which means that 0 gives -256, 128 gives 0 and 255 gives 254. So, the no-effect lightmap is a fully grey image (RGB = 128,128,128) and any non-grey pixel will shift the colors of the original.

Note that the lightmap will be scaled to the same dimensions as the original image.

NEG: Negative function

(Version 1.13.0 and later only) Also known as invert, it negates all the RGB values of the image, giving it an effect similar to a photographic negative.

~NEG( )

Inverts the image, giving it an effect like a photographic negative.

(Version 1.13.1 and later only) ~NEG( threshold )

If a channel has a value greater than the threshold, the channel will be inverted, performing an effect known as solarization. Threshold must be between -1 and 255, with -1 equivalent to full inversion and 255 as no-op value.

(Version 1.13.1 and later only) ~NEG( threshold_red, threshold_green, threshold_blue )

If a channel has a value greater than the corresponding threshold, the channel will be inverted. Each threshold must be between -1 and 255, with -1 equivalent to full inversion and 255 as no-op value.

PAL: Palette-switch function

May be used to change colors in an image following the specifications of a source and target (new) palette.

~PAL( source color palette > target color palette )

• source color palette - the first parameter is a source color palette, such as magenta. Do not surround this parameter with quotes.
• target color palette - the new palette to take the place of the source colors in the image.

A color palette can be either the attribute name from [color_palette] (like magenta) or a comma separated list of hex color values.

RC: Re-Color function

May be used to change some colors in an image. It is possible to use RC more than once on the same image, with different source palettes.

~RC( source color palette > destination color range )

source color palette

The first parameter is a set of colors, usually the magenta palette. Do not surround this parameter with quotes. The three standard palettes are:

• magenta - the 19 colors described in Team_Color_Shifting
• ellipse_red - all 255 colors with RGB value (n,0,0)
• flag_green - all 255 colors with RGB value (0,n,0)

The palette can also be given inline as a set of hexadecimal RGB values.

The named palettes are defined using the [color_palette] tag, and you can also define your own custom color palette using that tag.

Warning: the RC function will also accept (and not give a warning about) red, green and any other defined [color_range]; however the set of RGB values for those aren't guaranteed. Using red instead of ellipse_red might be equivalent to the palette 030000,060000,0a0000,...,ff0000,ff0a0a,...,fff0f0.

destination color range

This is the second parameter, signifying the ID of a color range defined in the file data/core/team-colors.cfg (or it may be a custom ID for a color range defined locally). You can also define a custom color range inline (the rgb key from GameConfigWML#Color_Palettes; note that RC does not use the fourth color for anything).

For this destination color range, using red or green makes sense.

Example

In the following example, the magenta regions in an elvish captain's image are turned a healthy shade of green:

 [message]
     speaker=narrator
     image=units/elves-wood/captain.png~RC(magenta>green)
     message=_ "Now I am on the green team."
 [/message]

The following example replaces a few of the magenta pixels with green ones:

 misc/orb.png~RC(690039,c30074,ec008c > 007f00,00ff00,000000,000000)

The IDs of the color ranges may be the lowercased English name of the palette's base color (e.g. 'red', 'brown', etc.). They may also be numeric color indices from the palette WML included with the game, but this is not recommended.

SEPIA: Sepia function

(Version 1.13.0 and later only) May be used to give to the image a sepia tint (like in old pictures).

~SEPIA()

SWAP: Channel Swap function

(Version 1.13.1 and later only) May be used to swap the RGBA channels of an image.

~SWAP( r, g, b ) ~SWAP( r, g, b, a )

• r, g, b, a: each of these arguments may have a value equal to red, green, blue or alpha. The RGBA channels of the original image will be exchanged accordingly (for example, ~SWAP(blue,green,red) swaps the blue and red channels).

TC: Team-Color function

In Wesnoth version 1.2, the only Image Path Function was ~TC(), which took two comma-separated parameters: the team number and the source color palette. The valid values for both of these parameters are defined in the file data/team-colors.cfg

~TC( team number , source color palette )

• team number - this is the first parameter, a number 1-9 signifying the team number of a unit. Number 1 typically means the red team, 2 typically means the blue team, and so on (unless the scenario color settings for any side have been altered).
• source color palette - the second parameter is a source color palette, usually magenta. Do not surround this parameter with quotes.

Transformations

FL: Flip function

May be used to flip an image horizontally and/or vertically.

~FL( optional argument list )

• vertical - if the string "vert" is found anywhere in the argument list, the image will be flipped vertically.
• horizontal - if the string "horiz" is found anywhere in the argument list, the image will be flipped horizontally.
• if the argument list is empty, the image will only be flipped horizontally.

ROTATE: Rotate function

May be used to rotate an image.

~ROTATE( degrees )

• degrees - The number of degrees by which the image will be rotated. Positive numbers indicate clockwise rotation, while negative numbers indicate counter-clockwise. (Zero indicates no rotation.)

If the number of degrees is omitted, a quarter turn (90 degrees) clockwise is assumed.

SCALE: Image-scaling function

Scales a graphic up or down.

~SCALE( new_width, new_height )

The new_width and new_height parameters are taken as the image's original width or height, respectively, if one of them happens to be zero. Negative values are treated in the same way, but an error is printed in stderr. This uses the bilinear interpolation algorithm.

SCALE_INTO function

(Version 1.13.5 and later only)

Similar to SCALE, but preserves aspect aspect ratio, scaling to the minimum extent required to fit into the specified area. The resulting image will have the specified width or the specified height, but not necessarily both.

SCALE_SHARP function

(Version 1.13.0 and later only)

Scales functions using a nearest neighbor algorithm. Specify width and height. (It has the same syntax as ~SCALE.)

~SCALE_SHARP(200,300)

SCALE_INTO_SHARP function

(Version 1.13.5 and later only)

Like SCALE_INTO, but uses nearest neighbor algorithm instead of bilinear interpolation.

XBRZ function

(Version 1.13.0 and later only)

Scales functions using the XBRZ algorithm. You may scale things up either 2x, 3x, 4x, or 5x. The scaling tries to preserve the pixel art nature.

~XBRZ(n)

Cut-paste-extend

BLIT: Blit function

Blit (superimpose) the parameter image on the main image. Example: peasant.png~BLIT(hat.png,30,10)

~BLIT(src,x,y)

• src: an image file used as source for the blit, other image path functions can be used there.
• x,y: top-left corner coordinates where to blit. If missing assume (0,0).

CROP: Crop function

Extracts a rectangular section of an image file.

~CROP(x,y,width,height)

• x,y: top-left corner coordinates for the rectangular section extracted. Must be greater or equal than zero, and inside the image's bounds.
• width: width of the selected region. Must be less than or equal to the original image's width, and must not be negative.
• height: height of the selected region. Must be less than or equal to the original image's height, and must not be negative.

CROP_TRANSPARENCY

(Version 1.17.26 and later only) Removes any transparent padding from around an image.

~CROP_TRANSPARENCY()

PAD: Pad function

(Version 1.19.17 and later only) Extends side(s) of an image with transparent pixels.

~PAD(..)

• called with a single number like ~PAD(10) and it will add a 10 pixel padding to every side.
• called with keys (top, t, right, r, bottom, b, left, l) like ~PAD(bottom=10, t=5) and it will pad those sides by that much.

Can be used to create a fake offset by padding one side of an image in order to push it in the opposite direction.

MASK: Mask function

Remove parts of the main image using the parameter image as a mask. Example: grass.png~MASK(circle.png) will give a circle of grass.

~MASK(mask,x,y)

• mask: an image file used as mask, other image path functions can be used there.
• x,y: top-left corner coordinates where to put the mask. Parts ouside of the mask are considered transparent. If missing assume (0,0).

Only the alpha channel of the mask is used and each alpha value will be the maximum alpha of the resulting image. This means that the fully-transparent parts of the mask will erase the corresponding parts of the image, but also that a semi-transparent mask will create a semi-transparent image.

Opacity

ADJUST_ALPHA

(Version 1.13.? and later only)

Alters the alpha of the image according to a WFL formula. The formula must output an integer from 0 to 255 giving the alpha across the canvas. It is evaluated for every pixel and may use the following variables: x, y, red, green, blue, alpha, width, height. (Version 1.15.0 and later only) The variables u and v are also supported now, evaluating to normalized texture coordinates (in the range 0..1); these are equivalent to x/width and y/height respectively.

~ADJUST_ALPHA(formula).

The context object for the formula is a pixel object.

O: Opacity modifying function

Changes an image's opacity at render time.

~O( factor or percentage% )

If the argument includes the percentage symbol (%), it will be treated as a percentage of full (real) opacity; an image will be displayed at its native opacity with ~O(100%).

Without the percentage symbol, the argument is assumed to be a factor by which the image's native opacity should be multiplied. Thus, ~O(0.5) and ~O(50%) are equivalent forms of specifying to reduce an image's opacity by half.

PLOT_ALPHA

(Version 1.13.0 and later only)

At each pixel, the color is replaced with a grey-tone reflecting the alpha value at that pixel, and the new image is fully opaque. Useful for plotting the alpha to help debug an IPF or inspect a sprite.

~PLOT_ALPHA()

WIPE_ALPHA

(Version 1.13.0 and later only)

At each pixel, the alpha value is discarded and the pixel is made fully opaque. Useful again for diagnostics.

~WIPE_ALPHA()

Background coloring function

Sets the color of all the (semi-)transparent pixels of the image.

~BG(r,g,b)

Miscellaneous

BL: Blurring function

Blurs a graphic at render time using the same algorithm used for in-game dialogs.

~BL( radius )

CHAN: General function

(Version 1.13.7 and later only)

This function allows you to do pretty much anything. It takes up to four comma-separated formulas, one each for the red, green, blue, and alpha channels. Each formula functions exactly the same as the formula for ADJUST_ALPHA, but the output integer is used for the corresponding channel rather than always the alpha channel. Do not surround the formula in $(...), since that will erase the self variable.

~CHAN(formula, formula, formula)

The context object for each of the formulas is a pixel object with the following properties:

• x, y: coordinates of the pixel, from the top left
• u, v: (Version 1.15.0 and later only) normalized coordinates in the range [0,1]
• width, height: size of the image canvas
• red, green, blue, alpha: components of the pixel colour

DARKEN: Removed function

(Version 1.13.7 and later only) This function has been removed. Use a ~BLIT(misc/tod-dark.png) call instead.

Puts a time-of-day schedule overlay (misc/tod-dark.png) on the image, which must be large enough to accommodate it.

~DARKEN()

BRIGHTEN: Removed function

(Version 1.13.7 and later only) This function has been removed. Use a ~BLIT(misc/tod-bright.png) call instead.

Puts a time-of-day schedule overlay (misc/tod-bright.png) on the image, which must be large enough to accommodate it.

~BRIGHTEN()

NOP: Null function

Does nothing.

~NOP()

Pseudo IPFs

The following functions are ignored by the IPF image modification module, but used by other Wesnoth components. They only work in special areas.

NO_TOD_SHIFT: Disabling ToD

(Version 1.13.8 and later only)

This is used by the terrain renderer and prevents terrain and item images from being affected by ToD lighting. This is in particular useful when placing unit images as items, as they will look the same as when placed as unit.

~NO_TOD_SHIFT()

RIGHT: Display portraits on the right

(Version 1.5.8 and later only)

This is used by the [message] interface action and can be used to show a portrait on the right side of the screen.

~RIGHT()

Creating an image file from IPFs

The big advantage of Image Path Functions is that they allow you to alter an image without needing a new image file. However, you can also save the result into a new image file using Wesnoth's command line option --render-image'.

Assuming you find a way to open your computer's terminal:

wesnoth --render-image "units/human-peasants/ruffian.png~RC(magenta>green)~BLIT(units/human-peasants/woodsman.png~RC(magenta>lightblue),18,12)" /tmp/new_image_file.png

Or on Windows:

"C:\Path\to\Battle for Wesnoth\wesnoth.exe" --render-image "units/human-peasants/ruffian.png~RC(magenta>green)~BLIT(units/human-peasants/woodsman.png~RC(magenta>lightblue),18,12)" new_image_file.png

Use cases include:

• Experimenting with Image Path Functions. If none of the images are from an add-on, adding --noaddons will speed this up.
• If a new Image Path Function is added to the development version of Wesnoth, add-ons for older Wesnoth versions can use a generated image instead.
• In case you want to use this anywhere out of Wesnoth. On a website, in Project Haldric, …

See Also

• FancyAddonIcons - Tips and tricks for advanced Image Path Function manipulation
• DataURI - An image path may also contain the image directly, as a Base64 encoded string
• Wespal - Tool to preview unit recoloring. Covers the effects of the RC, TC and PAL functions.
• src/image_modifications.cpp - file where IPFs are implemented