Imagetool


Imagetool is a generalized image conversion program with support for some special ZDoom graphic formats. It can read images saved as ILBM, BMP, or PCX and convert them to ZDoom fonts and images. You can also reverse the conversion to produce a normal graphic file out of a ZDoom font or image, or you can just convert between standard image formats without using a ZDoom format at all.

In its simplest use, you provide Imagetool with a source graphic and a target on the command line, and it performs the conversion. It also supports scripting in order to automate multiple conversions.

To just convert a single file, it is probably easiest to not bother with scripting. For instance, to create the console font from the included confont.pcx, you would use the commandline:

imagetool confont confont.pcx confont.lmp

The second word, confont, tells Imagetool that you want to create a console font. The third word, confont.pcx, is the name of the image file that holds the font data, and the fourth word, confont.lmp is the name of the new file to write to disk.

Similarly, to create the big Doom font from the included bigfont.pcx, you would use the commandline:

imagetool font bigfont.pcx dbigfont.lmp

In this case, the type of file being created is font instead of confont, because normal fonts have fewer restrictions than console fonts.

The different file types that can be produced are confont, font, image, and xhair.

confont

This produces a file of type FON1.

The source image for a console font must have 256 characters of identical size arranged in a 16x16 grid. Palette entry 0 indicates transparency, palette entry 1 is the darkest color a character can have, and palette entry 255 is the lightest color. Values in between range between the two. The source image's palette is ignored when the font is created, so you should design the font with a palette like this to best visualize how it will appear in-game.

font

This produces a file of type FON2. Unlike FON1, this format supports custom palettes and characters of varying widths. You also don't need to supply a full 256 characters and, in fact, cannot do so without scripting.

The source image should have each character surrounded by a box made up of palette entry 255. Like confonts, palette entry 0 indicates transparency, but unlike confonts, all the other 254 colors in the source image's palette are used to colorize the font, so you can use any palette you want when designing the font.

When converting with the command line, the first character must be a space, and the box surrounding it must start in the upper-left corner of the source image. These restrictions are relaxed if you use scripting, which I will discuss later.

You can use this font (or a confont) with a ZDoom hudmessage by executing the ACS command setfont("fontname") first. The fontname passed to setfont should be the same as the font's lump name inside a wad. If you use a hudmessage color of CR_UNTRANSLATED, then the font will use the palette you designed it with. Otherwise, it will be recolored to a single hue of differing shades.

image

This produces a file of type IMGZ.

This just an image without any special features. Color 0 indicates transparency, and the source image's palette should match the palette of the game you intend to use the image with. You can use it for crosshairs and status bar graphics but not much else.

xhair

Xhair is identical to image, except it sets the image's origin to the center of the graphic if it doesn't specify its own origin. ILBM is the only supported graphic format that allows for specifying an image's origin, which is why xhair is provided as an alternative to image.

You can also write a normal graphic file by using pcx, bmp, or ilbm as the destination type instead of one of the four types listed above.

If you have some graphics that use palette entry 247 to indicate translucency (because most existing Doom tools treate 247 that way), you can use the -0 switch on the command line to swap colors 0 and 247 in the source image.

Scripting

To run a script with Imagetool, you start it with the command line

imagetool script <script file>

Script file> is a text file you create with Notepad or some other text editor and contains a list of commands that get processed in sequence. Each command ends with a semicolon. An example script that will create the big Doom font is:

    load "bigfont.pcx";
    font "dbigfont.lmp";

The available commands are:

transparentcolor <color>

This works like the -0 command line switch, except you can specify an instead of 247. The next image loaded will swap colors 0 and the one specified here.

load "image";

Before doing anything else, you must load an image. This command does that.

origin (x, y);

Sets the image's origin to the coordinate (x, y), overriding any origin that might have been stored with the image. This is only meaningful if you use the xhair or image commands, because those are the only commands that care about image origins.

image "file";

Creates an IMGZ file. If an origin was not previously specified, it will be set to (0, 0).

xhair "file";

Creates an IMGZ file. If an origin was not previously specified, it will be set to the center of the image -- (width/2, height/2).

confont "file";

Creates a FON1 file. The discussion of using confont from the command line also applies here.

font "file" [shading=type] [optional character ranges] ... ;

If you just use font "file"; this command behaves like the font command line described above. You can have more control over the process by specifying optional arguments after the filename.

To change how the font looks when colorized, you can add either

shading=normal
-or-
shading=console

to the line. For normal shading, the colors used range between a dark and light version of the selected color. For console shading, the colors used range between the selected color and white.

You can include multiple character ranges in a single image by adding them to the line too by writing them as:

x y start

X and Y are the coordinate of the first character in this range, and start is the first character in this range.

Suppose you have a font that just consists of numbers and uppercase letters, and the numbers start at (0,0) and the letters are at (0,50). You alse want them to be shaded using console-style shading instead of normal shading. You could use the following script to create this font:

load "myfont.bmp";
font "myfont.lmp"
    shading=console
    0 0 '1'
    0 50 'A';

Copyright 2001 Randy Heit
All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

  1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
  2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
  3. The name of the author may not be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.