BITMAP(1) USER COMMANDS BITMAP(1) NAME bitmap, bmtoa, atobm - bitmap editor and converter utilities for X SYNOPSIS bitmap [-options ...] _f_i_l_e_n_a_m_e _W_I_D_T_Hx_H_E_I_G_H_T bmtoa [-chars ...] [_f_i_l_e_n_a_m_e] atobm [-chars _c_c] [-name _v_a_r_i_a_b_l_e] [-xhot _n_u_m_b_e_r] [-yhot _n_u_m_b_e_r] [_f_i_l_e_n_a_m_e] DESCRIPTION The _b_i_t_m_a_p 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 _b_m_t_o_a and _a_t_o_b_m filters convert _b_i_t_m_a_p files (FILE FOR- MAT) to and from ASCII strings. They are most commonly used to quickly print out bitmaps and to generate versions for including in text. USAGE _B_i_t_m_a_p displays grid in which each square represents a sin- gle 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 nor- mally 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 _h_o_t_s_p_o_t. 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 _W_I_D_T_H_x_H_E_I_G_H_T argument gives the size to use when creat- ing a new bitmap (the default is 16x16). Existing bitmaps are always edited at their current size. If the _b_i_t_m_a_p window is resized by the window manager, the size of the squares in the grid will shrink or enlarge to X Version 11 Last change: Release 4 1 BITMAP(1) USER COMMANDS BITMAP(1) fit. OPTIONS _B_i_t_m_a_p accepts the following options: -help This option will cause a brief description of the allow- able options and parameters to be printed. -display _d_i_s_p_l_a_y This option specifies the name of the X server to used. -geometry _g_e_o_m_e_t_r_y This option specifies the placement and size of the bit- map 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 _v_a_r_i_a_b_l_e_n_a_m_e This option specifies the variable name to be used when writing out the bitmap file. The default is to use the basename of the _f_i_l_e_n_a_m_e command line argument. -bw _n_u_m_b_e_r This option specifies the border width in pixels of the main window. -fn _f_o_n_t This option specifies the font to be used in the but- tons. -fg _c_o_l_o_r This option specifies the color to be used for the fore- ground. -bg _c_o_l_o_r This option specifies the color to be used for the back- ground. -hl _c_o_l_o_r This option specifies the color to be used for highlighting. -bd _c_o_l_o_r This option specifies the color to be used for the win- dow border. -ms _c_o_l_o_r X Version 11 Last change: Release 4 2 BITMAP(1) USER COMMANDS BITMAP(1) This option specifies the color to be used for the pointer (mouse). _B_m_t_o_a accepts the following option: -chars _c_c This option 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's and sharp signs (#) for 1's. _A_t_o_b_m accepts the following options: -chars _c_c 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 char- acter represents a 1 bit. The default is to use dashes (-) for 0's and sharp signs (#) for 1's. -name _v_a_r_i_a_b_l_e This option specifies the variable name to be used when writing out the bitmap file. The default is to use the basename of the _f_i_l_e_n_a_m_e command line argument or leave it blank if the standard input is read. -xhot _n_u_m_b_e_r This option specifies the X coordinate of the hotspot. Only positive values are allowed. By default, no hotspot information is included. -yhot _n_u_m_b_e_r 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. Mul- tiple 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. _B_u_t_t_o_n _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. _B_u_t_t_o_n _2 X Version 11 Last change: Release 4 3 BITMAP(1) USER COMMANDS BITMAP(1) 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). _B_u_t_t_o_n _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 emptied. MENU COMMANDS To make defining shapes easier, _b_i_t_m_a_p 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 buttons 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. _C_l_e_a_r _A_l_l 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. _S_e_t _A_l_l 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. _I_n_v_e_r_t _A_l_l 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. _C_l_e_a_r _A_r_e_a 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. X Version 11 Last change: Release 4 4 BITMAP(1) USER COMMANDS BITMAP(1) _S_e_t _A_r_e_a 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 out- lined above. _I_n_v_e_r_t _A_r_e_a This command is used to inverted a region of the grid as if 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. _C_o_p_y _A_r_e_a 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. _M_o_v_e _A_r_e_a 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. _O_v_e_r_l_a_y _A_r_e_a 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. _L_i_n_e This command will set the squares in a line between two points. When this command is invoked, the cur- sor will change shape to indicate that the pointer should be clicked on the two end points of the X Version 11 Last change: Release 4 5 BITMAP(1) USER COMMANDS BITMAP(1) line. _C_i_r_c_l_e 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. _F_i_l_l_e_d _C_i_r_c_l_e This command will set all of the squares in a cir- cle 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. All squares side and including the circle are set. _F_l_o_o_d _F_i_l_l 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. _S_e_t _H_o_t _S_p_o_t 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. _C_l_e_a_r _H_o_t _S_p_o_t This command removes any designated hot spot from the bitmap. _W_r_i_t_e _O_u_t_p_u_t 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 _f_i_l_e_n_a_m_e~ 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 _b_i_t_m_a_p should use /_t_m_p/_f_i_l_e_n_a_m_e instead. X Version 11 Last change: Release 4 6 BITMAP(1) USER COMMANDS BITMAP(1) _Q_u_i_t This command causes _b_i_t_m_a_p to display a dialog box asking whether or not it should save the bitmap (if it has changed) and then exit. Answering _y_e_s is the same as invoking _W_r_i_t_e _O_u_t_p_u_t; _n_o causes _b_i_t_m_a_p to simply exit; and _c_a_n_c_e_l will abort the _Q_u_i_t com- mand so that more changes may be made. FILE FORMAT The _W_r_i_t_e _O_u_t_p_u_t 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 _x_s_e_t_r_o_o_t), 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 _f_i_l_e_n_a_m_e 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 _n_a_m_e__x__h_o_t and _n_a_m_e__y__h_o_t symbols will only be present if a hotspot has been desig- nated using the _S_e_t _H_o_t _S_p_o_t 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 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. X Version 11 Last change: Release 4 7 BITMAP(1) USER COMMANDS BITMAP(1) 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 _X_1_1. To its right is 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. Interpret- ing each word as 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 _b_m_t_o_a program may be used to convert _b_i_t_m_a_p files into arrays of characters for printing or including in text files. The _a_t_o_b_m program can be used to convert strings back to _b_i_t_m_a_p format. USING BITMAPS IN PROGRAMS The format of _b_i_t_m_a_p 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 _t_h_i_s._c_u_r_s_o_r and _t_h_i_s__m_a_s_k._c_u_r_s_o_r: #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, X Version 11 Last change: Release 4 8 BITMAP(1) USER COMMANDS BITMAP(1) foreground, background, this_x_hot, this_y_hot); Additional routines are available for reading in _b_i_t_m_a_p 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, _b_i_t_m_a_p will also accept X10 for- mat _b_i_t_m_a_p files. However, when the file is written out again it will be in X11 format X DEFAULTS _B_i_t_m_a_p 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 use- ful only on color displays. The default value is _w_h_i_t_e. BorderColor The border color. This option is useful only on color displays. The default value is _b_l_a_c_k. BorderWidth The border width. The default value is 2. BodyFont The text font. The default value is _v_a_r_i_a_b_l_e. Dashed If ``off'', then _b_i_t_m_a_p 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 _b_l_a_c_k. Highlight The highlight color. _b_i_t_m_a_p uses this color to show the hot spot and to indicate rectangular areas that will be affected by the _M_o_v_e _A_r_e_a, _C_o_p_y _A_r_e_a, _S_e_t _A_r_e_a, and _I_n_v_e_r_t _A_r_e_a commands. If a highlight color is not given, then _b_i_t_m_a_p will highlight by inverting. This option is useful only on color displays. X Version 11 Last change: Release 4 9 BITMAP(1) USER COMMANDS BITMAP(1) Mouse The pointer (mouse) cursor's color. This option is use- ful only on color displays. The default value is _b_l_a_c_k. Geometry The size and location of the bitmap window. Dimensions The _W_I_D_T_H_x_H_E_I_G_H_T to use when creating a new bitmap. SEE ALSO X(1), _X_l_i_b - _C _L_a_n_g_u_a_g_e _X _I_n_t_e_r_f_a_c_e (particularly the sec- tion on _M_a_n_i_p_u_l_a_t_i_n_g _B_i_t_m_a_p_s), _X_m_u_R_e_a_d_B_i_t_m_a_p_D_a_t_a_F_r_o_m_F_i_l_e 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 speci- fied on the command line. There is no way to change the size of the bitmap once the program has started. There is no _u_n_d_o command. COPYRIGHT Copyright 1988, Massachusetts Institute of Technology. See _X(_1) for a full statement of rights and permissions. AUTHOR _b_i_t_m_a_p by Ron Newman, MIT Project Athena; documentation, _b_m_t_o_a, and _a_t_o_b_m by Jim Fulton, MIT X Consortium. X Version 11 Last change: Release 4 10