bitmap(1X) bitmap(1X)NAME bitmap, bmtoa, atobm - edits and converts bitmaps SYNOPSIS bitmap [-help] [-display display] [-geometry geometry] [-nodashed] [-name variable] [-bw width] [-fn font] [-fg color] [-bg color] [-hl color] [-bd color] [-ms color] file size bmtoa [-chars cc] [file] atobm [-chars cc][-name variable] [-xhot horizontal-position] [-yhot vertical-position] [file] DESCRIPTION bitmap is a rudimentary editor for creating and editing a bitmap. A bitmap is a rectangular array of 0 and 1 bits that form an image. X uses bitmaps to define clipping re- gions, pointer shapes, icon shapes, and tile and stipple re- gions. When you run bitmap, it displays in a window a mag- nified version of a bitmap array. Each bit is represented by a square, and the magnified bitmap looks like a piece of graph paper with grid lines that form grid squares. You can then set, clear, or invert individual squares to create a graphic pattern. In addition, you can use menu items in the bitmap window to move or copy rectangular areas from one segment of the bitmap to another. The size argument specifies the size to use when creating a new bitmap. The default is 16 x 16 pixels. The size argu- ment is given in terms of two numbers separated by an x. The first number specifies the width of the bitmap in pixels; the second number specifies the height. Existing bitmaps are always edited at their current size. The output of the bitmap command is a C code fragment. By including this fragment in your client application, you can easily declare the size and contents of pointers, icons, and other bitmaps that your application uses. The C code frag- ment provides an array of bits as well as symbolic constants that give the height, width, and hotspot, if specified. bmtoa and atobm convert bitmap files (see ``File Format'' later in the ``Description' section) to and from ASCII strings. You can use the bmtoa command to convert bitmap files into arrays of characters for printing the image or including in text files. You can use the atobm command to convert strings back to bitmap format. Options The bitmap command accepts these options: November, 1990 1
bitmap(1X) bitmap(1X)-bd color Specifies the color of the window border. -bg color Specifies the color of the background. -bw width Specifies in pixels the width of the bitmap window border. -display display Specifies the server to use. See X(1X) for details. -fg color Specifies the color of the foreground. -fn font Specifies the font to use in the menu item buttons. -geometry geometry Specifies the placement and size of the bitmap win- dow on the screen. See X(1X) for details. -help Displays a summary of the command syntax. Any un- supported option also causes bitmap to display this summary. -hl color Specifies the color to use for highlighting. -name variable Specifies the variable name to use when writing out the bitmap file. The default is to use the base name of the file command-line argument. See ``File For- mat'' later in the ``Description'' section for de- tails about how the base name is determined. -nodashed Indicates that the grid lines in the magnified bit- map should not be drawn using dashed lines. Although dashed lines are more aesthetically pleas- ing than solid lines, on some servers they take sig- nificantly more time to produce. -ms color Specifies the color to be used for the pointer. The bmtoa converter accepts this option: -chars cc Specifies the pair of characters to use in the string version of the bitmap. The first character is 2 November, 1990
bitmap(1X) bitmap(1X)used for 0 bits and the second character is used for 1 bits. The default is to use a dash (-) for 0's and a number sign (#) for 1's. The atobm converter accepts these options: -chars cc Specifies the pair of characters to use when con- verting 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 a dash (-) for 0's and a number sign (#) for 1's. -name variable Specifies the variable name to be used when writing out the bitmap file. The default is to use the base name of the file command-line argument or leave it blank if the standard input is read. See ``File For- mat'' later in the ``Description'' section for de- tails about how the base name is determined. -xhot horizontal-position Specifies the X coordinate of the hotspot. Only po- sitive values are allowed. By default, no hotspot information is included. -yhot vertical-position Specifies the Y coordinate of the hotspot. Only po- sitive values are allowed. By default, no hotspot information is included. The bitmap window When you start bitmap, it first tries to read file as speci- fied on the command line. If file already exists, bitmap creates a window containing a grid of the appropriate dimen- sions. If file does not exist, bitmap creates a window for a bitmap of the size specified by size (for example, 7x9, or 13x21). If size is not specified either on the command line or by the Dimensions X default, bitmap uses a default of 16x16. The bitmap window has four areas. Magnified bitmap This area displays a magnified version of the bitmap being edited, and each bit looks like a square in a grid. Menu This area provides a set of menu items as buttons. Actual-size bitmap November, 1990 3
bitmap(1X) bitmap(1X)This area is the actual-size picture of the bitmap being edited. Inverted actual_size bitmap This area is a reverse-video version of the actual- size bitmap. Each time you alter the image in the magnified bitmap, the change is reflected in the two actual-size versions of the bitmap. If you use a window manager to make the bitmap window larger or smaller, the grid squares in the magnified bitmap correspondingly grow or shrink in size. Changing the bitmap You can set, clear, or invert grid squares by pointing to a single square or dragging across a group of squares while pressing one of the following: Mouse button 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. The equivalent button on a three-button mouse is the left button. LEFT ARROW key Inverts 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). The equivalent button on a three-button mouse is the middle button. RIGHT ARROW key Clears one or more squares. The corresponding bit or bits in the bitmap are turned off (set to 0) and the square or squares are cleared. The equivalent button on a three-button mouse is the right button. Set squares are filled and represent 1's in the bitmap; un- set squares are clear and represent 0's. You can also make many changes to the bitmap being edited by using the menu item buttons. For details, see the next sec- tion, ``Menu Items.'' Menu items To make defining shapes easier, bitmap provides a menu of 13 items for editing whole sections of the bitmap at once, 2 for manipulating a pointer's hotspot, and 2 for updating the bitmap file and quitting. Each menu item is in a button that you select to indicate the operation. To choose a menu item, position the pointer on its button and press the mouse but- 4 November, 1990
bitmap(1X) bitmap(1X)ton (or LEFT ARROW key or RIGHT ARROW key). This method is called point and click and is also used to click or select something on the screen If you choose a menu item to operate on a rectangular area of the bitmap, you must select the area after you choose the menu item. To select a rectangular area, move the pointer to the upper-left square of the desired area, press the mouse button (or LEFT ARROW key or RIGHT ARROW key), drag the pointer to the lower-right corner, and then release the mouse button (or key). You can cancel the menu item while you're dragging by pressing an unpressed LEFT ARROW or RIGHT ARROW key (or the unpressed mouse button if you're dragging with a key pressed). You can also cancel the menu item by dragging outside the grid area and releasing the mouse but- ton or key. If the bitmap is to be used for defining a pointer, one of the squares in the image may be designated as the hotspot. This determines where the pointer is actually pointing. For pointers with sharp tips (such as arrows or fingers), this is usually at the end of the tip; for symmetrical pointers (such as crosses or bullseyes), this is usually the center. See ``Set Hot Spot'' later in this section for details. These are the 17 menu items you can choose in the menu area. The discussion explains the use of the mouse button with these menu items, but you can also use the LEFT or RIGHT AR- ROW keys. Clear All Clears all squares in the bitmap. This operation is irreversible, so choose it with care. Set All Sets all squares in the bitmap. This operation is irreversible, so choose it with care. Invert All Inverts all squares in the bitmap. Any squares that were set are cleared, and any squares that were clear are set. Clear Area Clears a rectangular area of the bitmap. After you choose this menu item, the pointer changes to the shape of an ``upper-left corner''. Position the pointer over the actual upper-left corner of the area you want to clear, hold down the mouse button while dragging the pointer to the lower-right corner of the area to be cleared, and then release the mouse button. November, 1990 5
bitmap(1X) bitmap(1X)While you are holding down the mouse button, the selected area is covered with X's, and the pointer changes to a ``lower-right corner.'' Set Area Sets a rectangular area of the bitmap. You select the area the same way as described in the Clear Area menu item. Invert Area Inverts a rectangular area of the bitmap. You select the area the same way as described in the Clear Area command. Copy Area Copies a rectangular area from one part of the bit- map to another. First, select the rectangle to be copied in the same way as described in the Clear Area menu item. When you release the mouse button, the pointer changes to an ``upper-left corner''. When you again press the mouse button, a destination rectangle overlays the grid; moving the mouse moves this destination rectangle. The selected area is copied to the location of the destination rectangle when you release the mouse button. Move Area Works the same way as the Copy Area menu item, ex- cept that it clears the source rectangle after copy- ing to the destination. Overlay Area Works the same way as the Copy Area menu item, ex- cept that it does a binary OR of the source rectan- gle with the destination. Line Draws a line between two points. The pointer changes shape to indicate that you should point and click two endpoints to draw the line. Circle Sets the grid squares on the curve of a circle specified by a centerpoint and second point the determines the radius and consequently the curve. The pointer changes shape to indicate that you should point and click a square as the center of the circle and then point and click a square that deter- mines the radius. When you release the mouse button, bitmap draws the circle. Small circles may not look very round because of the size of the grid and the limits of working with discrete pixels. Filled Circle 6 November, 1990
bitmap(1X) bitmap(1X)Sets all the squares in a circle specified by a cen- terpoint and a second point that determines the ra- dius and consequently the curve. The pointer changes shape to indicate that you should point and click a square as the center of the circle and then point and click a square that determines the radius. When you release the mouse button, bitmap draws the cir- cle and all squares inside the circle are set. Flood Fill Sets all clear squares in an enclosed shape. The pointer changes shape to indicate that you should point and click on any clear square inside the shape to be filled. All clear squares that border horizon- tally or vertically with the selected square are set to the border of squares that define the enclosing shape. If the shape is not closed, the entire bit- map is filled. Set Hot Spot Designates a square in the bitmap as the hotspot for a pointer that the bitmap defines. When you choose Set Hot Spot the pointer changes shape to indicate that you should point and click the square that is to be the hotspot. Clear Hot Spot Removes any hotspot that was designated on the bit- map. Write Output Writes the current bitmap values to file, as speci- fied on the bitmap command line. If the filename already exists, the filename is first renamed to file~ (as with emacs and other text editors). If the renaming or the writing causes an error (such as Permission denied), a dialog box appears, asking if you would prefer to write the file to /tmp/file in- stead. If you click the Yes button, each subsequent time you choose Write Output bitmap writes to /tmp/file. See the next section, ``File Format'' for a description of the output file. Quit Causes bitmap to exit. If you have edited the bit- map and have not chosen Write Output, or if you have edited the bitmap since the last time you chose Write Output, a dialog box appears to ask if you want to save changes before quitting. Clicking the Yes button runs Write Output before bitmap exits, clicking the No button causes bitmap to exit without writing the changes, and clicking the Cancel button indicates that you decided not to quit after all. November, 1990 7
bitmap(1X) bitmap(1X)File format The Write Output menu item causes bitmaps to be stored as simple C program fragments that can be compiled into appli- cations, referenced by X Toolkit pixel map resources, mani- pulated by other applications (see xsetroot(1X)), or read by a library routine. The width and height of the bitmap as well as the hotspot, if specified, are written as preproces- sor symbols at the beginning of the file. The bitmap image is then written as an array of characters. Here is an exam- ple of a bitmap file whose image spells X11. #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 for the preprocessor symbols and the bits array is constructed from the base name of the file argument given on the command line. Any directories are stripped from the front of the filename and any suffix beginning with a period is stripped from the end. Any remaining nonalpha- betic characters are replaced with underscores. The name_x_hot and name_y_hot symbols are only present if a hotspot has been designated using the Set Hot Spot menu item. 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 leftmost 8 bits of the top line, and the last character holds the rightmost 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. You can see how this process works by splitting a row into words containing 8 bits each, reversing the bits in each word (because Arabic numbers have the significant digit on the right and images have the least significant bit on the left), and converting each word from a binary to a hexade- cimal number. The following description shows how the character array in the previous example of a bitmap file was generated. The array of 1's and 0's on the left represents a bitmap con- taining 5 rows and 11 columns that spells X11. To the right 8 November, 1990
bitmap(1X) bitmap(1X)is the same array split into 8-bit words, with each row pad- ded 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 array on the left. Interpreting each word as a hexadecimal number yields the array 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 and top to bottom. static char name_bits[] = { 0x91, 0x04, 0xca, 0x06, 0x84, 0x04, 0x8a, 0x04, 0x91, 0x04 }; Using bitmaps in applications The format of bitmap files is designed to make bitmap im- ages, including pointers, easy to use within X client appli- cations. You can use the following code to create a pointer from the 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 bitmap files and returning the data in the file, in bitmap format (single-plane pixel map for use with routines that require November, 1990 9
bitmap(1X) bitmap(1X)stipples), or in full-depth pixel map format (often used for window backgrounds and borders). Application programmers must understand the difference between bitmaps and pixel maps so that their programs function correctly on monochrome and color displays. For downward compatibility with X10, bitmap can read X10 bitmap format files. However, when bitmap writes out the file, it is in X11 format. X defaults The bitmap command uses the routine XGetDefault(3X) to read defaults, so its resource names are capitalized. Background Specifies the background color of the bitmap window. The 0 bits in the bitmap are also displayed in this color. The background option is useful only on color screens. The default value is white. BorderColor Specifies the border color of the bitmap window. This option is useful only on color screens. The default value is black. BorderWidth Specifies the border width of the bitmap window. The default value is 2. BodyFont Specifies the text font used to display text in the bitmap window. The default value is variable. Dashed Tells bitmap how to draw grid lines. If you specify off, bitmap draws the grid lines using a solid line; if you specify on, bitmap draws the grid lines using a dashed line. The default is on. Foreground Specifies the foreground color. The 1 bits in the bitmap are displayed in this color. This option is useful only on color screens. The default value is black. Highlight Specifies the highlight color. The bitmap command uses this color to isolate the hotspot and to indi- cate rectangular areas that are affected by the Move Area, Copy Area, Set Area, Clear Area, and Invert Area menu items. If a highlight color is not given, bitmap highlights by inverting. This option is use- ful only on color screens. 10 November, 1990
bitmap(1X) bitmap(1X)Mouse Specifies the color of the pointer. This option is useful only on color screens. The default value is black. Geometry Specifies the size and location of the bitmap win- dow. Dimensions Specifies the size to use when creating a new bit- map. Environment variables The bitmap command uses the following environment variables: DISPLAY Specifies the default host, display number, and screen. XENVIRONMENT Specifies the name of the defaults file to use. DIAGNOSTICS The following error messages can be displayed on the screen. Any of these conditions terminates bitmap before it can create its window. bitmap: could not connect to X server on host:display The display argument given on the command line or the DISPLAY environment variable has an invalid host name or display number, the host is down, the host is unreachable, the host is not running an X server, or the host is refusing connections. bitmap: no filename specified You started bitmap without any command-line arguments. You must give a filename as the first argument. bitmap: could not open file file for reading -- message The specified file exists but cannot be read, for the reason given in message (such as permission denied). bitmap: invalid dimensions string bitmap: dimensions must be positive The size command-line argument was not a valid dimension specification. November, 1990 11
bitmap(1X) bitmap(1X)bitmap: Bitmap file invalid The input file is not in the correct format; bitmap gave up when trying to read the specified data. The following message may be printed after bitmap creates its window: bitmap: Unrecognized variable name in file file This message indicates that bitmap encountered a variable ending in something other than _x_hot, _y_hot, _width, or _height while parsing the input file. It ignores this vari- able and continues parsing the file. The following messages indicate that a protocol error has occurred: bitmap: XError: message bitmap: XIOError There is a problem either with the X server or with the X library with which the application was compiled. One possi- bility is that server and the library are incompatible. If the server is not on the local host, this error may indicate a broken connection. LIMITATIONS Some command-line arguments are not consistent with other X applications. If you move the pointer too fast while holding the mouse button (or LEFT or RIGHT ARROW key) down, some squares might be ``missed.'' This is caused by X server constraints in the sample frequency of 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 after bit- map has started. There is no ``undo'' menu item. NOTES Copyright 1988, Massachusetts Institute of Technology. See X(1X) for a full statement of rights and permissions. Authors: Ron Newman, MIT Project Athena and Jim Fulton, MIT X Consortium 12 November, 1990
bitmap(1X) bitmap(1X)SEE ALSO X(1X) Xlib - C Language Interface, particularly the ``Manipulating Bitmaps'' section November, 1990 13