BITMAP(1) X Version 11 BITMAP(1)
Release 4
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's and 0's. 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 (FILE FORMAT) to and
from ASCII strings. They are most commonly used to quickly print out
bitmaps and to generate versions for including in text.
USAGE
Bitmap displays 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 and a menu of higher level
operations such as draw line and fill 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 images may be designated as 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 bullseyes), 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
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.
If the bitmap window is resized by the window manager, the size of the
squares in the grid will shrink or enlarge to fit.
OPTIONS
Hewlett-Packard Company - 1 - X11 Release 4 Nov 1991
BITMAP(1) X Version 11 BITMAP(1)
Release 4
Bitmap accepts the following options:
-help
This option will cause a brief description of the allowable
options and parameters to be printed.
-display display
This option specifies the name of the X server to used.
-geometry geometry
This option specifies the placement and size of the bitmap window
on the screen. See X for details.
-nodashed
This option 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
This option 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.
-bw number
This option specifies the border width in pixels of the main
window.
-fn font
This option specifies the font to be used in the buttons.
-fg color
This option specifies the color to be used for the foreground.
-bg color
This option specifies the color to be used for the background.
-hl color
This option specifies the color to be used for highlighting.
-bd color
This option specifies the color to be used for the window border.
-ms color
This option specifies the color to be used for the pointer
(mouse).
Bmtoa accepts the following option:
-chars cc
This option specifies the pair of characters to use in the string
Hewlett-Packard Company - 2 - X11 Release 4 Nov 1991
BITMAP(1) X Version 11 BITMAP(1)
Release 4
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's and sharp signs (#) for 1's.
Atobm accepts the following options:
-chars cc
This option 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's and sharp signs
(#) for 1's.
-name variable
This option 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
This option specifies the X coordinate of the hotspot. Only
positive values are allowed. By default, no hotspot information
is included.
-yhot number
This option 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's in the bitmap;
clear squares are empty and represent 0's.
Button 1
This button (usually leftmost on the pointer) is 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
This button (usually in the middle) is used to invert one or
more squares. The corresponding bit or bits in the bitmap
are flipped (1's become 0's and 0's become 1's).
Button 3
This button (usually on the right) is 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
Hewlett-Packard Company - 3 - X11 Release 4 Nov 1991
BITMAP(1) X Version 11 BITMAP(1)
Release 4
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 and click any
button.
Clear All
This command is 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
This command is 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
This command is used to invert all of the bits in the bitmap
as if Button 2 had been dragged through every square in the
grid.
Clear Area
This command is used to clear a region of the grid as if
Button 3 had been dragged through each of the squares in the
region. When this command is invoked, the cursor will change
shape to indicate that the area to be cleared should be
selected as outlined above.
Set Area
This command is used to set a region of the grid as if Button
1 had been dragged through each of the squares in the region.
When this command is invoked, the cursor will change shape to
indicate that the area to be set should be selected as
outlined above.
Invert Area
This command is used to inverted a region of the grid as if
Hewlett-Packard Company - 4 - X11 Release 4 Nov 1991
BITMAP(1) X Version 11 BITMAP(1)
Release 4
Button 2 had been dragged through each of the squares in the
region. When this command is invoked, the cursor will change
shape to indicate that the area to be inverted should be
selected as outlined above.
Copy Area
This command is used to copy a region of the grid from one
location to another. When this command is invoked, 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
This command is used to move a region of the grid from one
location to another. When this command is invoked, 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 aren't also in the new
position are cleared.
Overlay Area
This command is used to copy all of the set squares in a
region of the grid from one location to another. When this
command is invoked, 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
This command will set the squares in a line between two
points. When this command is invoked, the cursor will change
shape to indicate that the pointer should be clicked on the
two end points of the line.
Circle
This command will set the squares on a circle specified by a
center and a point on the curve. When this command is
invoked, 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
This command will set all of the squares in a circle
specified by a center and a point on the curve. When this
Hewlett-Packard Company - 5 - X11 Release 4 Nov 1991
BITMAP(1) X Version 11 BITMAP(1)
Release 4
command is invoked, 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 side
and including the circle are set.
Flood Fill
This command will set all clear squares in an enclosed shape.
When this command is invoked, 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.
Set Hot Spot
This command designates one square in the grid as the hot
spot if this bitmap to be used for defining a cursor. When
the command is invoked, the cursor will change indicating
that the pointer should be clicked on the square to contain
the hot spot.
Clear Hot Spot
This command removes any designated hot spot from the bitmap.
Write Output
This command 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 or not bitmap should
use /tmp/filename instead.
Quit
This command causes bitmap to display a dialog box asking
whether or not it should save the bitmap (if it has changed)
and then exit. Answering yes is the same as invoking Write
Output; no causes bitmap to simply exit; and cancel will
abort the Quit command so that more changes may be made.
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
Hewlett-Packard Company - 6 - X11 Release 4 Nov 1991
BITMAP(1) X Version 11 BITMAP(1)
Release 4
#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
is 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.
In the following example, the array of 1's and 0's 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's 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
Hewlett-Packard Company - 7 - X11 Release 4 Nov 1991
BITMAP(1) X Version 11 BITMAP(1)
Release 4
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"
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). 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 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. This option is useful only on color
displays. The default value is white.
Hewlett-Packard Company - 8 - X11 Release 4 Nov 1991
BITMAP(1) X Version 11 BITMAP(1)
Release 4
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.
Dashed
If ``off'', then bitmap will draw the grid lines with solid lines.
The default is ``on''.
Foreground
The foreground color. Bits which are 1 in the bitmap 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 to indicate rectangular areas that will be affected by the
Move Area, Copy Area, Set Area, and Invert Area commands. If a
highlight color is not given, then bitmap will highlight by
inverting. This option is useful only on color displays.
Mouse
The pointer (mouse) cursor's color. This option is useful only on
color displays. The default value is black.
Geometry
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), XmuReadBitmapDataFromFile
BUGS
The old command line arguments aren't 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.
Hewlett-Packard Company - 9 - X11 Release 4 Nov 1991
BITMAP(1) X Version 11 BITMAP(1)
Release 4
There is no way to change the size of the bitmap once the program has
started.
There is no undo command.
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.
Hewlett-Packard Company - 10 - X11 Release 4 Nov 1991