X Window System User's Guide for X11 R3 and R4 of the X Window System

6

Graphics Utilities

This chapter describes how to use the major graphics clients included with X, notably the bitmap editor.

In This Chapter:

Creating Icons and Other Bitmaps

Bitmap Editing Commands

Pointer Commands

Bitmap Command Boxes

Acting on the Entire Grid: Clear All, Set All, Invert All

Acting on an Area: Clear Area, Set Area, Invert Area

Copy Area, Move Area, Overlay Area

Drawing: Line, Circle, Filled Circle

Filling in a Shape: Flood Fill

Hot Spots: Set Hot Spot, Clear Hot Spot

Saving and Quitting: Write Output, Quit

Creating a Bitmap from a Cursor

Magnifying Portions of the Screen: xmag

Quitting xmag

What xmag Shows You

Dynamically Choosing a Different Source Area

6

Graphics Utilities

The standard release of X includes four utilities to help you create bitmap images: bitmap, bmtoa, atobm, and xmag. The most powerful and useful of these clients is bitmap, a program that lets you create and edit bitmap files. The following sections include detailed instructions for using the bitmap client.

The bmtoa and atobm clients are programs that convert bitmaps to arrays (of ASCII characters) and arrays to bitmaps. They are used to facilitate printing and file manipulation and can help you convert a font character to a bitmap.

In a sense, the xmag client is a desk accessory for graphics programs. This client is used to magnify a portion of the screen, assisting you in creating images with a graphics editor, such as bitmap.

Creating Icons and Other Bitmaps

The bitmap program allows you to create and edit small bitmaps. A bitmap is a grid of pixels, or picture elements, each of which is white, black, or, in the case of color displays, a color. You can use bitmap to create backgrounds, icons, and pointers.

At this point in X Window System development, bitmap is primarily a programming tool for application developers. However, several applications allow you to design your own icon or background pattern with bitmap, save it in a bitmap file, and specify that filename on the command line.* For example, xsetroot (described in Chapter 11, Setup Clients) allows you to specify a bitmap that will be used as the background pattern for the root window.

To invoke bitmap, type:

% bitmap filename &

An upper-left corner cursor appears on the screen for you to interactively place the bitmap window, shown in Figure 6-1.

Figure 6-1. Bitmap window

The window that bitmap creates has three sections:

1.   The largest section is the checkerboard grid, which is a magnified version of the bitmap you are editing. The default-size grid is 16×16. If this grid isn’t large enough for comfortable editing, resize the window. Each square on the grid will be enlarged proportionally.

2.   On the right-hand side of the window is a list of commands in command boxes that you can invoke with any mouse button.

3.   Beneath the commands is an actual-size picture of the bitmap you are editing; below this is an inverted version of the same bitmap. Each time the grid changes, the same change occurs in the actual-size bitmap and its inverse.

If you want to edit in a grid of different proportions than the default-size 16×16 grid, you can specify WIDTHxHEIGHT on the command line, after filename. For example, to create a grid double the size of the default, enter:

% bitmap filename 32x32 &

Figure 6-2 shows a 40×40 grid with a bitmap we created of Gumby©. We think it makes a fun root window pattern. (See the discussion of xsetroot in Chapter 11, Setup Clients, for instructions on specifying a bitmap as your root window pattern.)

Figure 6-2. Gumby bitmap

Figure 6-2 shows our own rendition of Gumby, created using various bitmap editing commands. The standard cursor font also contains a Gumby character. (You can specify the Gumby cursor as the xterm window pointer, as described in Chapter 9. Setting Resources. or as the root window pointer using the xsetroot client, as described in Chapter 11, Setup Clients.) Later in this chapter, we’ll show you how to convert the Gumby character of the cursor font to a bitmap file, using the atobm client.

Bitmap Editing Commands

You can create and edit a bitmap using a combination of pointer commands and commands that appear in boxes on the right-hand side of the window. The pointer commands work on one square of the grid at a time, while the command boxes can work on the entire grid or a specified area.

Pointer Commands

When the pointer is in the checkerboard grid, each mouse button has a different effect upon the single square under the pointer. You can hold down a mouse button and drag the pointer to effect several squares in a row.

left button	Changes a grid square to the foreground color and sets the corresponding bitmap bit to 1. (On a monochrome display, background color means white and foreground color means black.)
middle button	Inverts a grid square, changing its color and inverting its bitmap bit.
right button	Changes a grid square to the background color and sets the corresponding bitmap bit to 0.

Bitmap Command Boxes

To invoke any bitmap command, move the pointer to the appropriate command box and click any button. bitmap does not have an Undo command. Once you have made a change, you cannot retrieve the original.

Acting on the Entire Grid: Clear All, Set All, Invert All

To Clear All, Set All, or Invert All, click on the appropriate command box.

Clear All

Changes all the grid squares to the background color and sets all bitmap bits to 0.

Figure 6-3. Clearing all

Set All

Changes all the grid squares to the foreground color and sets all bitmap bits to 1.

Figure 6-4. Setting all

Invert All

Inverts all the grid squares and bitmap bits, as if you had pressed the middle button over each square.

Figure 6-5. Inverting all

Acting on an Area: Clear Area, Set Area, Invert Area

Clear Area	Clears a rectangular area of the grid, i.e., changes it to the background color, and sets the corresponding bitmap bits to 0.
Set Area	Changes a rectangular area of the grid to the foreground color and sets the corresponding bitmap bits to 1.
Invert Area	Changes a rectangular area of the grid from the background color to the foreground color or the foreground color to the background color.

Figure 6-6. Selecting an area to clear, set, or invert

The procedure to act on an area is as follows:

1.   Click the pointer over the command (Clear Area, Set Area, or Invert Area). The pointer turns into an upper-left corner.

2.   Move the pointer over the upper-left corner of the area you want to clear, set, or invert. Press and hold any button. The pointer changes to a lower-right corner.

3.   Move the pointer to the lower-right corner of the area you want to act on. X’s cover the rectangular area as you move the pointer. Release the button.

If the pointer has changed to a lower-right corner and you wish to abort the command without inverting an area, either click another button, move the pointer outside the grid, or move the pointer above or to the left of the upper-left corner.

Copy Area, Move Area, Overlay Area

Copy Area	Copies a rectangular area from one part of the grid to another.
Move Area	Moves a rectangular area from one part of the grid to another.
Overlay Area	Lays a rectangular area from one part of the grid over a rectangular area in another part of the grid. Overlay is not a pixel-for-pixel replacement, but those pixels that are clear (bitmap bits set to 0) allow those pixels that are set (bitmap bits set to 1) to show through the overlay.

Figure 6-7. Selecting an area to copy, move, or overlay

The procedure to Copy Area, Move Area, or Overlay Area is as follows:

1.   Click the pointer over the command (Copy Area, Move Area, or Overlay Area). The pointer turns into an upper-left corner.

2.   Move the pointer over the upper-left corner of the area you want to copy, move, or overlay. Press and hold any button. The pointer changes to a lower-right corner.

3.   Move the pointer to the lower-right corner of the area you want to act on. X’s cover the rectangular area as you move the pointer. Release the button. The pointer changes to an upper-left corner.

4.   Move the pointer to the desired location and click any button.

OR:

Press and hold any button to see the outline of the destination rectangle, move the pointer to the desired location, then release the button.

5.   To cancel an overlay, copy, or move command, move the pointer outside the grid and release the button.

Drawing: Line, Circle, Filled Circle

When you use a drawing command, the drawing is always done in the foreground color.

Line	Draws a line between any two points you select.
Circle	Draws a circle. You specify the center and the radius.
Filled Circle	Draws a filled circle. You specify the center and the radius.

Figure 6-8. Selecting center and radius of circle

To draw a line or circle:

1.   Click the pointer over the command Line, Circle, or Filled Circle. The pointer changes to the dot cursor shape (•).

2.   Move the pointer to the first point of the line or to the center of the circle. Click any button. An X fills the square which is the starting point of the line or center of the circle.

3.   Move the pointer to the end point of the line or to the outside circumference of the circle. Click any button. The graphic is drawn.

Filling In a Shape: Flood Fill

Flood Fill

Fills all clear squares in a closed shape.

To fill a shape:

1.   Click the pointer over the command Flood Fill. The pointer changes to the dot cursor shape (•).

2.   Move the pointer into the shape you want to fill.

3.   Click on any clear square inside the closed shape and all clear squares are filled out to the shape’s border. If the shape is not closed, the entire grid will be filled.

Hot Spots: Set Hot Spot, Clear Hot Spot

Set Hot Spot	Designates a point on the bitmap as the hot spot. If a program is using your bitmap as a pointer, the hot spot indicates which point on the bitmap will track the actual location of the pointer. For instance, if your pointer is an arrow, the hot spot should be the tip of the arrow; if your pointer is a cross, the hot spot should be that point at which the perpendicular lines intersect.
Clear Hot Spot	Removes a hot spot defined on this bitmap.

To set or clear a hot spot:

1.   Click the pointer over Set Hot Spot or Clear Hot Spot.

2.   Move the pointer to the location of the hot spot. Click any button. When a hot spot is active a diamond (⋄) appears in the square.

Saving and Quitting: Write Output, Quit

Write Output

Writes the current bitmap value to the file specified in the command line. If the file already exists, the original file is first renamed to filename~. If either the renaming or the writing causes an error (e.g., permission denied), a dialog box appears, asking if you want to write the file /tmp/filename instead. If you click Yes, all future Write Output commands in the current bitmap editing session write to /tmp/filename. See the bitmap reference page in Part Three of this guide for information on the format of the output file.

Quit

Terminates bitmap. If you have edited the bitmap and have not invoked Write Output, or you have edited it since the last time you invoked Write Output, a dialog box appears, asking if you want to save changes before quitting. Yes does a Write Output before terminating; No just tenninates, losing the edits; Cancel means you decided not to tenninate after all. You can also tenninate bitmap by typing Control-C or q anywhere in the window. If you have edited the bitmap and have not invoked Write Output, a dialog window appears, asking if you want to save changes before quitting.

Figure 6-9. Bitmap window with quit dialog box

Creating a Bitmap from a Cursor

The atobm and bmtoa clients allow you to convert arrays (of ASCII characters) to bitmap files and to convert bitmap files to arrays. These clients are commonly used to facilitate printing: a bitmap file that is converted to ASCII text can be printed more readily and can also be included in standard ASCII text files. Once converted to ASCII, bitmap files can also be more quickly copied or mailed to other directories or systems, where they can be used in ASCII format or converted back to bitmap format.

Among their uses, the bmtoa and atobm utilities make it possible to convert a character from a font, such as the cursor font, to the bitmap file format. Once converted, the file can be edited using the bitmap client, and used as you would any other bitmap file: specified as the root window pattern (with xsetroot), etc.

When a bitmap file is converted to ASCII text, it is in the form of an array consisting of two types of characters. (An array is a number of elements arranged in rows and columns; it is sometimes called a matrix.) One character represents set or filled squares of the bitmap (bitmap bit 1) and the other character represents empty squares (bitmap bit 0). By default, the number sign character (#) represents filled squares and the hyphen (–) represents empty squares. Figure 6-10 shows the British pound sign character of the 9×15 font (in the misc directory) as an array of these ASCII symbols.

Figure 6-10. ASCII array representing the pound sign

As you can see, the array is a perfect rectangle. In a sense, the array is very similar to the bitmap grid. (You can edit or create the array using an ASCII text editor, so long as you use the standard two characters and keep the array rectangular.)

To convert the Gumby character of the cursor font to a bitmap, the first thing you must do is display the cursor font as ASCII text. This can be done with the showsnf client, which allows you to display the contents of a font file (with a .snf extension). The -g option specifies that arrays of all the characters in the font be displayed as well.

To display the cursor font with each character represented as an array, use showsnf, with the font filename as an argument, and redirect output to a file called /tmp/cursor.array:

% showsnf -g /usr/lib/X11/fonts/misc/cursor.snf > /tmp/cursor.array

The cursor.array file contains information about the font and an array for each character. Using your ASCII text editing program, edit the file, writing the Gumby array to another file called /tmp/gumby.array. The Gumby array is pictured in Figure 6-11.

Figure 6-11. /tmp/gumby.array

You can then use the atobm client to convert this array to a bitmap. Use the gumby.array file as an argument and redirect the output to a bitmap file:

% atobm /tmp/gumby.array > /tmp/gumby.bitmap

Figure 6-12 shows the Gumby bitmap. As you can see from the bitmap, the Gumby character of the cursor font is considerably smaller than the Gumby we created (Figure 6-2) with bitmap.

If you want, you can then edit the gumby.bitmap file using the bitmap client.

If you specify the bitmap as the root window pattern, you’ll notice that there is virtually no space between the Gum by figures. This is because the array file had no extra hyphens (representing empty bitmap squares) padding it. If you want, you can add some hyphens to the gumby.array file (keeping the image symmetrical) and then use atobm to create a more padded version of the bitmap. Figure 6-13 shows the gumby.array file after being padded with hyphens.

See the bitmap reference page in Part Three of this guide for more information on the atobm and bmtoa conversion clients.

Figure 6-12. Bitmap of the Gumby cursor

Figure 6-13. gumby.array padded by hyphens

Magnifying Portions of the Screen: xmag

The xmag client enables you to magnify a portion of the screen. The close-up look xmag affords can assist you in creating and editing bitmaps and other graphic images.

xmag is primarily a tool for application developers using sophisticated graphics programs. But you could also use xmag in concert with the bitmap client. For instance, say you’re running a program that creates a special image on the root window and you’d like to create a bitmap file of a part of that image. You can display a magnification of the image you want with xmag, and try to recreate the image by editing in an open bitmap window.

If you invoke xmag without options, you can interactively choose the area to be magnified (the source area) and position the magnified image on your screen. At the command line, type:

% xmag &

The pointer changes to a small cross (the crosshair cursor) in the center of a small, hollow square with a wavering border. (By default, the square is 64 pixels on each side.) Move the crosshair cursor, placing the square over the area you want to magnify, and click the first mouse button.

The crosshair changes to an upper-left corner cursor, and the hollow square becomes enlarged to the size of the magnified image. (By default, the image is magnified five times.) Move the upper-left corner cursor, positioning the square where you want the magnified image. Again click the first mouse button and the xmag window containing the magnified bitmap image is displayed, as shown in Figure 6-14.

If you are using a window manager that provides titlebars, such as twm, the title string “Magnifying Glass” will be displayed in the xmag window titlebar. This is the default title string of the application.*

The default-size xmag window shows an area 64 pixels square, magnified five times. This magnification enables you to see the individual pixels, which are represented by squares of the same color as the corresponding pixels in the source image.

Rather than use the default source area and magnification, you can specify other values on the command line. See the xmag reference page in Part Three of this guide for a complete list of options.

Figure 6-14. xmag window displaying magnified screen area

Quitting xmag

To exit the program, type q, Q, or Control-C in the xmag window.

What xmag Shows You

xmag enables you to determine the x and y coordinates, bitmap bit setting, and RGB color value of every pixel in the xmag window. (See Chapter 8, Command Line Options, for a discussion of the RGB color model.) If you move the pointer into the xmag window, the cursor becomes an arrow. Point the arrow at one of the magnified pixels and press and hold down the first mouse button. Across the top edge of the window, a banner displays information about the pixel, as shown in Figure 6-15.

Figure 6-15. Displaying pixel statistics with xmag

The banner displays the following information about the specified pixel:

•   The x and y coordinates relative to the window. The default xmag window is, in effect, a grid of 64 squares on each side. Therefore, each pixel has x,y coordinates between 0,0 and 63,63.

•   The bitmap bit setting. This is either 0, if the pixel is in the background color, or 1, if the pixel is in the foreground color.

•   The RGB value. This is a 16-bit value. The RGB specification is in three parts (of four hexadecimal digits each), corresponding to the three primaries in the RGB color model.

If you are trying to create a graphic image on a grid (such as the bitmap client provides), the x and y coordinates of each pixel can be especially useful. Also, the 16-bit RGB value specifies the color of each pixel with incredible precision. Depending on the number of colors available on your display, you can learn to use RGB values to specify an enormous range of colors.

xmag provides these pixel statistics dynamically. If you continue to hold down the first mouse button and drag the pointer across the window, the banner will display values for each pixel as the pointer indicates it.

Note that if you select a pixel near the top edge of the window, the banner will appear across the bottom edge. Otherwise, the banner would obscure the pixel you are pointing at.

Dynamically Choosing a Different Source Area

If you want to magnify another portion of the screen using the same source area size and magnification, you do not have to start xmag again. Simply move the pointer into the xmag window and click the second or third mouse button, or press the space bar. The magnified image disappears and again the cursor becomes a crosshair surrounded by a hollow square. Move the crosshair cursor, placing the square over the new source area you want to magnify, and click any mouse button. The magnified image is immediately displayed in the location you placed the first image.

You can select any number of source areas during a single xmag session.

_______________
*There are many bitmaps included in the X distribution. These can be found in the directory /usr/include/X11/bitmaps. Samples are shown in Appendix G, Standard Bitmaps.

*Applications written using the X Toolkit allow you to change the title string. See the section “Title and Name” in Chapter 8. Command Line Options, for details. The xmag client was not written using the X Toolkit and provides no method for changing the title string.