bitmap(1) X Version 11 (28 October 1988) bitmap(1)
NAME
bitmap, bmtoa, atobm - bitmap editor and converter utilities
for X
SYNOPSIS
bitmap [-options ...] filename WIDTHxHEIGHT
bmtoa [-chars ...] [filename]
atobm [-chars cc] [-name variable] [-xhot number]
[-yhot number] [filename]
DESCRIPTION
The bitmap program is a rudimentary tool for creating or
editing rectangular images made up of 1s and 0s. You can
use bitmaps to define clipping regions, cursor shapes, icon
shapes, and tile and stipple patterns.
The bmtoa and atobm filters convert bitmap files (FILE
FORMAT) to and from ASCII strings. Their most common use is
to quickly print out bitmaps and generate versions for
including in text.
USAGE
When you run bitmap, a magnified grid of the bitmap prints
on your screen. Each square in the grid represents a single
bit in the picture. You can set, clear, or directly invert
squares with the buttons on your mouse. You can also use the
menu that appears next to the bitmap grid. This menu offers
higher level operations such as Line and Filled Circle.
Actual size versions of the bitmap appear below the menu, so
you can see what it looks like normally and inverted.
If you plan to use the bitmap for defining a cursor, you can
designate one of the squares in the grid to be the hotspot.
This determines where the cursor is actually pointing. For
cursors with sharp tips (such as arrows or fingers), this is
usually at the end of the tip; for symmetric cursors (such
as crosses or bull's-eyes), this is usually at the center.
Bitmaps are stored as small C code fragments suitable for
including in applications. They provide an array of bits as
well as symbolic constants giving the width, height, and
hotspot (if specified) that can be used in creating cursors,
icons, and tiles.
The WIDTHxHEIGHT option specifies the size to use when
creating a new bitmap (the default is 16x16). Existing
bitmaps are always edited at their current size.
If you resize the bitmap window with the window manager, the
squares in the grid shrink or enlarge to fit the new window.
Page 1 (printed 10/4/89)
bitmap(1) X Version 11 (28 October 1988) bitmap(1)
OPTIONS
The bitmap editor accepts the following options:
-help
Prints a brief description of the options to bitmap.
-display display
Specifies the X server.
-geometry geometry
Specifies the placement and size of the bitmap window on
the screen. See X(1) for details.
-nodashed
Indicates that the grid lines in the work area should
not be drawn using dashed lines. Although dashed lines
are prettier than solid lines, they are significantly
slower on some servers.
-name variablename
Specifies the variable name to be used when writing out
the bitmap file. The default is to use the base name of
the filename command-line argument.
-bw number
Specifies the width of the main window border in pixels.
The default is 2.
-fn font
Specifies the font for the buttons.
-fg color
Specifies the foreground color. The default is "black."
-bg color
Specifies the background color. The default is "white."
-hl color
Specifies the color for highlighting. The default is
"black."
-bd color
Specifies the color for the window border.
-ms color
Specifies the color for the pointer (mouse cursor). The
default is black. This option may not work on some
servers.
bmtoa accepts the following option:
-chars cc
Page 2 (printed 10/4/89)
bitmap(1) X Version 11 (28 October 1988) bitmap(1)
Specifies the pair of characters to use in the string
version of the bitmap. The first character represents 0
bits and the second character represents 1 bits. The
default uses dashes (-) for 0s and sharp signs (#) for
1s.
atobm accepts the following options:
-chars cc
Specifies the pair of characters to use when converting
string bitmaps into arrays of numbers. The first
character represents a 0 bit and the second character
represents a 1 bit. The default uses dashes (-) for 0s
and sharp signs (#) for 1s.
-name variable
Specifies the variable name to be used when writing out
the bitmap file. The default uses the base name of the
filename command-line option or leaves it blank if
standard input is read.
-xhot number
Specifies the X coordinate of the hotspot. Only postive
values are allowed. By default, no hotspot information
is included.
-yhot number
Specifies the Y coordinate of the hotspot. Only postive
values are allowed. By default, no hotspot information
is included.
CHANGING GRID SQUARES
You can set, clear, or invert grid squares by pointing to
them and clicking one of the mouse buttons indicated below.
You can change multiple squares at once by holding the
button down and dragging the pointer across them. Set
squares are filled and represent 1s in the bitmap; clear
squares are empty and represent 0s.
Button 1
This button (usually left-most on the mouse) sets one or
more squares. The corresponding bit or bits in the
bitmap are turned on (set to 1) and the square or
squares are filled.
Button 2
This button (usually in the middle) inverts one or more
squares. The corresponding bit or bits in the bitmap
are flipped (1s become 0s and 0s become 1s).
Button 3
This button (usually on the right) clears one or more
Page 3 (printed 10/4/89)
bitmap(1) X Version 11 (28 October 1988) bitmap(1)
squares. The corresponding bit or bits in the bitmap
are turned off (set to 0) and the square or squares are
emptied.
MENU COMMANDS
To make defining shapes easier, bitmap provides 13 commands
for drawing whole sections of the grid at once, 2 commands
for manipulating the hotspot, and 2 commands for updating
the bitmap file and exiting. A command button for each of
these operations is located to the right of the grid.
Several of the commands operate on rectangular portions of
the grid. When you invoke these commands, the pointer
changes shape, indicating that you should select the area
you want to change. To select an area, move the pointer to
the upper left square of the desired area, press a mouse
button, drag the pointer to the lower right hand corner
(with the button still pressed), and release the button.
You can abort the command by pressing any other button while
dragging or by releasing outside the grid.
To invoke a command, move the pointer over that command and
click any button.
Clear All
Clears all of the bits in the bitmap as if Button 3 had
been dragged through every square in the grid. You
cannot undo this command.
Set All
Sets all of the bits in the bitmap as if Button 1 had
been dragged through every square in the grid. You
cannot undo this command.
Invert All
Inverts all of the bits in the bitmap as if Button 2 had
been dragged through every square in the grid.
Clear Area
Clears a region of the grid as if Button 3 had been
dragged through each of the squares in the region.
Set Area
Sets a region of the grid as if Button 1 had been
dragged through each of the squares in the region.
Invert Area
Inverts a region of the grid as if Button 2 had been
dragged through each of the squares in the region.
Copy Area
Copies a region of the grid from one location to
Page 4 (printed 10/4/89)
bitmap(1) X Version 11 (28 October 1988) bitmap(1)
another.
Move Area
Moves a region of the grid from one location to another.
This command clears any squares in the region's old
position that are not also in the new position.
Overlay Area
Copies all of the set squares in a region of the grid
from one location to another. Click the cursor on the
square where you want to overlay the the upper left hand
corner of the region. Only the squares that are set in
the region are touched in the new location.
Line
Sets the squares in a line between two points. Click the
mouse on the two end points of the line.
Circle
Sets the squares on a circle specified by a center and a
point on the curve. Small circles may not look very
round because of the size of the grid and the limits of
having to work with discrete pixels.
Filled Circle
Sets all of the squares in a circle specified by a
center and a point on the curve. Click the mouse on the
center of the circle and then over a point on the curve.
All squares side and including the circle are set.
Flood Fill
Sets all clear squares in an enclosed shape. Click the
mouse on any empty square inside the shape to be filled.
All empty squares that border horizontally or vertically
with the indicated square are set out to the enclosing
shape. If you do not close the shape, the entire grid
is filled.
Set Hot Spot
Designates one square in the grid as the hot spot (for
defining a cursor). Click the mouse on the square you
want to contain the hot spot.
Clear Hot Spot
Removes any designated hot spot from the bitmap.
Write Output
Writes a small fragment of C code that represents the
bitmap to the filename you specify on the command line.
If the file already exists, the original file is renamed
to filename~ before the new file is created. If an
error occurs in either the renaming or the writing of
Page 5 (printed 10/4/89)
bitmap(1) X Version 11 (28 October 1988) bitmap(1)
the bitmap file, a dialog box appears asking whether or
not bitmap should use /tmp/filename instead.
Quit
Displays a dialog box asking whether or not it should
save the bitmap (if it has changed) and then exits.
Answering yes is the same as invoking Write Output; no
causes bitmap to simply exit; and cancel aborts the Quit
command so that you can make more changes.
FILE FORMAT
The Write Output command stores bitmaps as simple C program
fragments that you can compile into programs, refer to by X
Toolkit pixmap resources, manipulate by other programs (see
xsetroot), or read in using utility routines in the various
programming libraries. The width and height of the bitmap
as well as the hotspot, if specified, are written as
preprocessor symbols at the start of the file. The bitmap
image is then written out as an array of characters:
#define name_width 11
#define name_height 5
#define name_x_hot 5
#define name_y_hot 2
static char name_bits[] = {
0x91, 0x04, 0xca, 0x06, 0x84,
0x04, 0x8a, 0x04, 0x91, 0x04
};
The name prefix to the preprocessor symbols and the bits
array is constructed from the filename argument given on the
command line. Any directories are stripped off the front of
the name and any suffix beginning with a period is stripped
off the end. Any remaining non-alphabetic characters are
replaced with underscores. The namexhot and nameyhot
symbols are only present if a hotspot has been designated
using the Set Hot Spot command or if you have specified the
-name option.
Each character in the array contains 8 bits from one row of
the image (rows are padded out at the end to a multiple of 8
to make this possible). Rows are written out from left to
right and top to bottom. The first character of the array
holds the left-most 8 bits of the top line, and the last
characters holds the right-most 8 bits (including padding)
of the bottom line. Within each character, the left-most
bit in the bitmap is the least signficant bit.
This process can be demonstrated visually by splitting a row
into words containing 8 bits each, reversing the bits of
each word (since Arabic numbers have the significant digit
Page 6 (printed 10/4/89)
bitmap(1) X Version 11 (28 October 1988) bitmap(1)
on the right and images have the least significant bit on
the left), and translating each word from binary to
hexidecimal.
In the following example, the array of 1s and 0s on the left
represents a bitmap containing 5 rows and 11 columns that
spells X11. To its right is is the same array split into
8-bit words with each row padded with 0s so that it is a
multiple of 8 in length (16):
10001001001 10001001 00100000
01010011011 01010011 01100000
00100001001 00100001 00100000
01010001001 01010001 00100000
10001001001 10001001 00100000
Reversing the bits in each word of the padded, split version
of the bitmap yields the left hand figure below.
Interpretting each word as a hexidecimal number yields the
array of numbers on the right:
10010001 00000100 0x91 0x04
11001010 00000110 0xca 0x06
10000100 00000100 0x84 0x04
10001010 00000100 0x8a 0x04
10010001 00000100 0x91 0x04
The character array can then be generated by reading each row
from left to right, top to bottom:
static char name_bits[] = {
0x91, 0x04, 0xca, 0x06, 0x84,
0x04, 0x8a, 0x04, 0x91, 0x04
};
The bmtoa program can convert bitmap files into arrays of
characters for printing or including in text files. The atobm
program can convert strings back to bitmap format.
USING BITMAPS IN PROGRAMS
The bitmap file format is designed to make bitmaps and
cursors easy to use within X programs. You could use the
following code to create a cursor from bitmaps defined in
this.cursor and thismask.cursor:
#include "this.cursor"
#include "this_mask.cursor"
XColor foreground, background;
/* fill in foreground and background color structures */
Pixmap source = XCreateBitmapFromData (display, drawable,
this_bits, this_width, this_height);
Page 7 (printed 10/4/89)
bitmap(1) X Version 11 (28 October 1988) bitmap(1)
Pixmap mask = XCreateBitmapFromData (display, drawable,
this_mask_bits, this_mask_width, this_mask_height);
Cursor cursor = XCreatePixmapCursor (display, source, mask,
foreground, background, this_x_hot, this_y_hot);
Additional routines are available for reading in bitmap
files and returning the data in the file, in Bitmap
(single-plane Pixmap for use with routines that require
stipples), or full depth Pixmaps (often used for window
backgrounds and borders). Applications writers should be
careful to understand the difference between Bitmaps and
Pixmaps so that their programs function correctly on color
and monochrome displays.
For backward compatibility, bitmap also accepts X10 format
bitmap files. However, when the file is written out again
it is in X11 format
X DEFAULTS
Background
The window's background color. 0 bits are displayed in
this color. This option is useful only on color
displays. The default value is "white."
BorderColor
The border color. This option is useful only on color
displays. The default value is "black."
BorderWidth
The border width. The default value is 2.
BodyFont
The text font. The default value is "variable."
Foreground
The foreground color. 1 bits are displayed in this
color. This option is useful only on color displays.
The default value is "black."
Highlight
The highlight color. bitmap uses this color to show the
hot spot and indicate rectangular areas that are
affected by the Move Area, Copy Area, Set Area, and
Invert Area commands. If you do not specify a
highlight color, bitmap highlights by inverting. This
option is useful only on color displays.
Mouse
The mouse cursor's color. This option is useful only on
color displays. The default value is "black."
Geometry
Page 8 (printed 10/4/89)
bitmap(1) X Version 11 (28 October 1988) bitmap(1)
The size and location of the bitmap window.
Dimensions
The WIDTHxHEIGHT to use when creating a new bitmap.
SEE ALSO
X(1)
Xlib - C Language X Interface (particularly the section on
Manipulating Bitmaps),
LIMITATIONS
If you move the mouse too fast while holding a mouse button
down, some squares may be "missed." This happens because
the server can only sample so many pointer locations.
COPYRIGHT
Copyright 1988, Massachusetts Institute of Technology.
See X(1) for a full statement of rights and permissions.
AUTHOR
bitmap by Ron Newman, MIT Project Athena; documentation,
bmtoa, and atobm by Jim Fulton, MIT X Consortium.
Page 9 (printed 10/4/89)