---
name: "wml::des::imgbg"
section: "3"
platform: "linux"
package: "wml"
version: "2.32.0~ds1-1"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/wml::des::imgbg"
---

# wml::des::imgbg(3)

Background Images

## NAME

wml::des::imgbg - Background Images

## SYNOPSIS

```
 #use wml::des::imgbg
 <: $file = &imgbg($base, $direction, $content, $pixels, $format); :>
 <body ... background=<imgbg [attributes]> ...>
```

## DESCRIPTION

The usual purpose of this tag is to create a PNG or GIF image containing a background image and to expand to its filename. Its contents is specified via the `"content"` attribute by use of size/color pairs.

## ATTRIBUTES

- "base"

  Usually the created images are named *imgbg-xxxxxx.png* where `"xxxxxx"` is the content id of the image. When you use a `"base=foo"` attribute, then the resulting files are named *foo.imgbg-xxxxxx.png*.  Actually you can even use a complete filename including a directory prefix, i.e. when you use `"base=../../common/foo"` attribute, then the images are created as *../../common/foo.imgbg-xxxxxx.png*.

  And for most flexibility when no base is specified and the variable `"BGIMG_BASE"` is defined (usually from within a *.wmlrc* file via `"-DBGIMG_BASE~path/to/imgbg/dir/base"`) it is used.  Use this feature to redirect the created images to a particular directory.

  You may also use the variable `"IMAGE_BASE"` which defines in a single line all base names for images generated by WML.

- "format"

  By default, GIF images are generated. This attribute lets you use an alternate image format (actually only PNG and GIF are recognized). You may also change the default format with the variable `"IMAGE_FORMAT"`.

- "direction"

  Specifies the color change direction of the image: \`\``"h"`'' for horizontal (default) or \`\``"v"`'' for vertical.

- "pixels"

  Size of the image in the other direction, 1 by default.

- "content"

  This is a comma-separated list of size/color specifications \`\`*pixels*`":#"`*rrggbb*`":#"`*rrggbb*`":"`*slices*''

  The last two arguments are optional, only present for gradient images. In this case, a linear gradient line is drawn from color 1 to color 2, with *slices* different colors.

  To get a background with two columns, a black one with 150 point in size and a white one which fills the rest of the page use \`\``"150:#000000,1200:#ffffff"`''.

## AUTHORS

```
 Ralf S. Engelschall
 rse@engelschall.com
 www.engelschall.com
 Denis Barbier
 barbier@engelschall.com
```

## REQUIRES

```
 Internal: P1, P2, P3
```

## SEE ALSO

HTML \<`"body"`\> tag.