The Fatted Calf/The Fatted Calf.iso/Applications/Audio/Patchmix/XWindowsSource/bitmap/bitmap.man

Text File | 1992-03-28 | 18.9 KB | 659 lines

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



Sun Release 3.2 Last change: 28 October 1988 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



Sun Release 3.2 Last change: 28 October 1988 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 postive 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 postive 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



Sun Release 3.2 Last change: 28 October 1988 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.



Sun Release 3.2 Last change: 28 October 1988 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



Sun Release 3.2 Last change: 28 October 1988 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.



Sun Release 3.2 Last change: 28 October 1988 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 namewidth 11
 #define nameheight 5
 #define namexhot 5
 #define nameyhot 2

 static char namebits[] = {
 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 signficant 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 hexidecimal.




Sun Release 3.2 Last change: 28 October 1988 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-
 ting each word as 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 namebits[] = {
 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 "thismask.cursor"

 XColor foreground, background;
 /* fill in foreground and background color structures */
 Pixmap source = XCreateBitmapFromData (display, drawable,
 thisbits, thiswidth, thisheight);
 Pixmap mask = XCreateBitmapFromData (display, drawable,
 thismaskbits, thismaskwidth, thismaskheight);
 Cursor cursor = XCreatePixmapCursor (display, source, mask,



Sun Release 3.2 Last change: 28 October 1988 8






BITMAP(1) USER COMMANDS BITMAP(1)



 foreground, background, thisxhot, thisyhot);


 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.

 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.

 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.





Sun Release 3.2 Last change: 28 October 1988 9






BITMAP(1) USER COMMANDS BITMAP(1)



 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.





















Sun Release 3.2 Last change: 28 October 1988 10