BITMAP(1) 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 1-bits and 0-
bits. Bitmaps are used in X for defining clipping
regions, cursor shapes, icon shapes, and tile and
stipple patterns.
The bmtoa and atobm filters convert bitmap files to and
from ASCII strings. (See FILE FORMAT.) They are most
commonly used to quickly print out bitmaps and to
generate versions for including in text.
USAGE
bitmap displays a grid in which each square represents
a single bit in the picture being edited. Squares can
be set, cleared, or inverted directly with the buttons
on the pointer; a menu of higher level operations (such
as `line' and `circle') is provided to the side of the
grid. Actual size versions of the bitmap as it would
appear normally and inverted appear below the menu.
If the bitmap is to be used for defining a cursor, one
of the squares in the image may be designated as the
hotspot. This determines the pixel of the cursor that
is actually doing the pointing. For a cursor with a
sharp tip (an arrow or a finger), the hotspot is
usually at that tip; for a symmetrical cursor, it would
be 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 may be used in
creating cursors, icons, and tiles.
The WIDTHxHEIGHT argument gives the size to use when
creating a new bitmap (the default is 16x16). Existing
bitmaps are always edited at their current size.
- 1 -
BITMAP(1) BITMAP(1)
If the bitmap window is resized by the window manager,
the size of the squares in the grid will shrink or
enlarge to fit. There is no way to specify the size of
the squares; only resizing the window will change the
size.
OPTIONS
bitmap accepts the following options:
-help
causes a brief description of the allowable options
and parameters to be printed.
-display display
specifies the name of the X server to used.
-geometry geometry
specifies the placement and size of the bitmap
window on the screen.
-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, on some
servers they are significantly slower.
-name variablename
specifies the internal variable name to be used
when writing out the bitmap file. This variable
name is used to refer to the bitmap when it is
compiled into a C program. The default variable
name is the basename of the filename command-line
argument. See the FILE FORMAT section for more
information.
-bw number
specifies the border width in pixels of the main
window (certain window managers will override this
option).
-fn font
specifies the font to be used in the buttons.
-fg color
specifies the color to be used for the foreground.
-bg color
specifies the color to be used for the background.
-hl color
specifies the color to be used for highlighting.
- 2 -
BITMAP(1) BITMAP(1)
-bd color
specifies the color to be used for the window
border.
-ms color
specifies the color to be used for the pointer
(mouse).
bmtoa accepts the following option:
-chars cc
specifies the pair of characters to use in the
string version of the bitmap. The first character
is used for 0-bits and the second character is used
for 1-bits. The default is to use dashes (-) for
0-bits and sharp signs (#) for 1-bits.
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
is to use dashes (-) for 0-bits and sharp signs (#)
for 1-bits.
-name variable
specifies the variable name to be used when writing
out the bitmap file. The default is to use the
basename of the filename command line argument or
leave it blank if the standard input is read.
-xhot number
specifies the X coordinate of the hotspot. Only
positive values are allowed. By default, no
hotspot information is included.
-yhot number
specifies the Y coordinate of the hotspot. Only
positive values are allowed. By default, no
hotspot information is included.
CHANGING GRID SQUARES
Grid squares may be set, cleared, or inverted by
pointing to them and clicking one of the buttons
indicated below. Multiple squares can be changed at
once by holding the button down and dragging the cursor
across them. Set squares are filled and represent 1-
bits in the bitmap; clear squares are empty and
represent 0-bits.
- 3 -
BITMAP(1) BITMAP(1)
Button 1
used to set 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
used to invert one or more squares. The
corresponding bit or bits in the bitmap are flipped
(1-bits become 0-bits and 0-bits become 1-bits).
Button 3
used to clear one or more 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. These areas are selected after the
command button is pressed by moving the cursor to the
upper left square of the desired area, pressing a
pointer button, dragging the cursor to the lower right
hand corner (with the button still pressed) , and then
releasing the button. The command may be aborted by
pressing any other button while dragging or by
releasing outside the grid.
To invoke a command, move the pointer over that command
button, and click any button on the mouse.
Clear All
used to clear all of the bits in the bitmap as if
Button 3 had been dragged through every square in
the grid. It cannot be undone.
Set All
used to set all of the bits in the bitmap as if
Button 1 had been dragged through every square in
the grid. It cannot be undone.
Invert All
used to invert all of the bits in the bitmap as if
Button 2 had been dragged through every square in
the grid.
- 4 -
BITMAP(1) BITMAP(1)
Clear Area
used to clear a region of the grid as if Button 3
had been dragged through each of the squares in the
region. The cursor will change shape to indicate
that the area to be cleared should be selected as
outlined above.
Set Area
used to set a region of the grid as if Button 1 had
been dragged through each of the squares in the
region. The cursor will change shape to indicate
that the area to be set should be selected as
outlined above.
Invert Area
used to inverted a region of the grid as if Button
2 had been dragged through each of the squares in
the region. The cursor will change shape to
indicate that the area to be inverted should be
selected as outlined above.
Copy Area
used to copy a region of the grid from one location
to another. The cursor will change shape to
indicate that the area to be copied should be
selected as outlined above. The cursor should then
be clicked on the square to which the upper left
hand corner of the region should be copied.
Move Area
used to move a region of the grid from one location
to another. The cursor will change shape to
indicate that the area to be moved should be
selected as outlined above. The cursor should then
be clicked on the square to which the upper left
hand corner of the region should be moved. Any
squares in the region's old position that are not
also in the new position are cleared.
Overlay Area
used to copy all of the set squares in a region of
the grid from one location to another. The cursor
will change shape to indicate that the area to be
copied should be selected as outlined above. The
cursor should then be clicked on the square to
which the upper left hand corner of the region
should be overlaid. Only the squares that are set
in the region will be touched in the new location.
Line
sets the squares in a line between two points. The
cursor will change shape to indicate that the
- 5 -
BITMAP(1) BITMAP(1)
pointer should be clicked 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. The cursor will change
shape to indicate that the pointer should be
clicked on the center of the circle and then over 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. The cursor will
change shape to indicate that the pointer should be
clicked on the center of the circle and then over a
point on the curve. All squares inside and
including the circle are set.
Flood Fill
sets all clear squares in an enclosed shape. The
cursor will change shape to indicate that the
pointer should be clicked 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 the shape is not closed, the entire grid
will be filled. This operation cannot be undone.
Set Hot Spot
designates one square in the grid as the hot spot,
if this bitmap is used for defining a cursor. The
cursor will change, indicating that the pointer
should be clicked on the square 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 representing the
bitmap to the filename specified on the command
line. If the file already exists, the original
file will be renamed to filename before the new
~
file is created. If an error occurs in either the
renaming or the writing of the bitmap file, a
dialog box will appear asking whether bitmap should
use /tmp/filename instead.
Quit
causes bitmap to display a dialog box that asks
- 6 -
BITMAP(1) BITMAP(1)
whether or not it should save the bitmap (if it has
changed), and then exit. Clicking on yes is the
same as invoking Write Output; clicking on no
causes bitmap to simply exit; and clicking on
cancel will abort the Quit command so that more
changes can be made.
- 7 -
BITMAP(1) BITMAP(1)
FILE FORMAT
The Write Output command stores bitmaps as simple C
program fragments that can be compiled into programs,
referred to by X Toolkit pixmap resources, manipulated
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 to 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 name_x_hot and name_y_hot symbols
will only be present if a hotspot has been designated
using the Set Hot Spot command.
Each character in the 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 leftmost 8 bits
of top line, and the last characters holds the right
most 8 bits (including padding) of the bottom line.
Within each character, the leftmost bit in the bitmap
is the least significant bit in the character.
This process can be demonstrated visually by splitting
a row into words containing 8 bits each, reversing the
bits in each word (since Arabic numbers have the
significant digit on the right and images have the
least significant bit on the left), and translating
each word from binary to hexadecimal.
- 8 -
BITMAP(1) BITMAP(1)
In the following example, the array of 1-bits and 0-
bits on the left represents a bitmap containing 5 rows
and 11 columns that spells X11. To its right is the
same array split into 8-bit words with each row padded
with 0-bits 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. Interpreting each word as a hexadecimal 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 may be used to convert bitmap files
into arrays of characters for printing or including in
text files. The atobm program can be used to convert
strings back to bitmap format.
USING BITMAPS IN PROGRAMS
The format of bitmap files is designed to make bitmaps
and cursors easy to use within X programs. The
following code could be used to create a cursor from
bitmaps defined in this.cursor and this_mask.cursor:
#include "this.cursor"
#include "this_mask.cursor"
- 9 -
BITMAP(1) BITMAP(1)
XColor foreground, background;
/* fill in foreground and background color
structures */
Pixmap source = XCreateBitmapFromData (display,
drawable, this_bits, this_width, this_height);
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). Application 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 will also accept X10
format bitmap files. However, when the file is written
out again it will be in X11 format.
X DEFAULTS
bitmap uses the following resources:
Background
The window's background color. Bits which are 0 in
the bitmap are displayed in this color. The
default value is white.
BorderColor
The border color. The default value is black.
BorderWidth
The border width. The default value is 2.
BodyFont
The text font. The default value is fixed.
Foreground
The foreground color. Bits which are 1 in the
bitmap are displayed in this color. The default
value is black.
Highlight
The highlight color. bitmap uses this color to
show the hot spot and to indicate rectangular areas
that will be affected by the Move Area, Copy Area,
Set Area, and Invert Area commands. If a
- 10 -
BITMAP(1) BITMAP(1)
highlight color is not given, then bitmap will
highlight by inverting.
Mouse
The pointer (mouse) cursor's color. The default
value is black.
Geometry
The size and location of the bitmap window.
Dimensions
The WIDTHxHEIGHT to use when creating a new bitmap.
SPECIAL CONSIDERATIONS
bitmap uses XAllocColorCells() to allocate writable
colorcells. If the default colormap runs out of
writable cells, bitmap will obtain a new, writable,
colormap and request that the window-manager install
it. In most circumstances no visible change occurs,
but sometimes a perceptible colormap change is noticed
when the pointer is moved into the main bitmap window.
The reallocation is usually unnecessary, unless you are
running two or more bitmaps on a single display, or
unless you are running another client that uses
XAllocColorCells().
BUGS
The old command line arguments are not consistent with
other X programs.
If you move the pointer too fast while holding a
pointer button down, some squares may be missed. This
is caused by limitations in how frequently the X server
can sample the pointer location.
There is no way to write to a file other than the one
specified on the command line.
There is no way to change the size of the bitmap once
the program has started.
There is no undo command.
AUTHOR
bitmap by Ron Newman, MIT Project Athena;
documentation, bmtoa, and atobm by Jim Fulton, MIT X
Consortium.
- 11 -