


      COPYBITS(3X)               (Bull-SPS9)               COPYBITS(3X)



      NAME
           CopyBits - bit-oriented block transfer (BitBlt)

      SYNTAX
           #include <sys/graf.h>

           CopyBits (rOp)
           struct RasterOp *rOp;

      DESCRIPTION
           The CopyBits fuction provides pixel-level graphics
           operations for the Bull-SPS9 Monochrome Display.  It is used
           to create bitmap images in the calling process' own address
           space, a part of which is mapped to the display screen as
           described in the Bull-SPS9 Multi-Window Display Management
           Guide.

           Rectangular areas of arbitrary size can be filled with
           black, white, and halftone patterns.  Text, in various
           typefaces or fonts, can be copied from stored images of the
           individual characters.  Line-drawing and arbitrary graphics
           are created by repeated calls of the basic functions.

           The CopyBits operation is modelled after the BitBlt (bit-
           oriented block transfer) operation found in Smalltalk
           (Goldberg and Robson, Smalltalk-80: The Language and its
           Implementation, Addison-Wesley, 1983).

           A two-dimensional pixel image is represented by a data
           structure called a Form, whose definition is given in the
           include file as:

                struct Form {
                        int width;
                        int height;
                        unsigned int *bits;
                };

           A Form has height and width, measured in bits, and a pointer
           to an array of 32-bit words that contains a bitmap.  The
           bitmap is a pattern of ones and zeros that indicate the
           black and white pixels of the image being represented.  The
           height and width impose two-dimensional ordering on the
           otherwise unstructured bitmap data.

           A new Form is usually created by allocating an integral
           number of words to contain the bits needed for the desired
           height and width, and placing a pointer to those words in
           the structure.  A Form might also be initialized with the
           width and height of the display screen, and contain the
           starting address in virtual memory of the display bitmap.
           There is no difference between manipulating images



      Page 1                                         (73 A2 02MTA REV1)






      COPYBITS(3X)               (Bull-SPS9)               COPYBITS(3X)



           internally and manipulating images that are mapped to the
           display screen.

           Bitmaps are allocated with an integral number of 32-bit
           words for each row of pixels.  This row size is referred to
           as the ``raster'' width.  The integral word constraint on
           the raster size is related to the hardware organization of
           memory and the efficiency of processing 32 bits at a time.
           This facilitates movement from one row to the next, both
           during the hardware scanning of the display screen memory
           and during the operation of the CopyBits function.  While
           this organization is significant for allocation purposes, it
           is encapsulated so that none of the higher-level callers of
           CopyBits need be concerned with the issue of word size.

           Locations within a Form are designated using a two-
           dimensional coordinate system relative to the top left
           corner of the image rectangle.  X increases to the right and
           Y increases down, consistent with the display device raster
           scanning, and with the layout of text on a page.

           Two structures, defined in the include file, are often used
           when dealing with bitmap images:

                struct Point {
                        int x;
                        int y;
                };

                struct Rectangle {
                        struct Point origin;
                        struct Point extent;
                };

           A Point contains x and y coordinate values that refer to a
           pixel location with a Form.  A Rectangle contains two Points
           (the origin is the top left corner and the extent is the
           width and height) that define a rectangular area within a
           Form.

           The CopyBits operation involves a source Form and a
           destination Form.  For example, the source may be a set of
           character glyphs packed together horizontally as in a bit-
           matrix font(4).  The destination might be the display
           bitmap.  Pixels are copied out of the source and stored into
           the destination.  The width and height of the transfer
           correspond to the character size.  The source coordinates
           give the character's location in the font, and the
           destination coordinates specify the position on the display
           where the copy will appear.

           A clipping rectangle is specified which limits the region of



      Page 2                                         (73 A2 02MTA REV1)






      COPYBITS(3X)               (Bull-SPS9)               COPYBITS(3X)



           the destination that can be affected by the operation,
           independent from the other destination parameters.  Often it
           is desirable to display a partial view of a larger image,
           and the clipping rectangle ensures that all picture elements
           fall inside the bounds of the view.  Pixels that would have
           been placed outside the clipping rectangle are not
           transferred.

           Occasionally it is desirable to fill areas with a regular
           pattern that gives the effect of a gray halftone or texture.
           The CopyBits operation allows a third Form to be specified
           containing the desired pattern, and is referred to as the
           mask.  The mask Form must have a width and height of exactly
           32 bits.  When halftoning is specified, this pattern is
           replicated every 32 bits horizontally and vertically over
           the entire destination.

           There are four possible ways to supply pixels from the
           source and mask Forms, depending on which Forms are used in
           the operation.  To exclude use of a Form parameter, set the
           bits field within the Form to a pointer value 0:

                1) no source, no mask - supplies solid black
                2) source only - supplies source pixels
                3) mask only - supplies halftone pattern
                4) source AND mask - supplies source pixels logically masked by halftone pattern

           There are 16 possible rules for combining each source
           element S (taken as the result of any halftone masking) with
           the corresponding destination element D to produce the new
           destination element D'.  Each rule must specify a white (0)
           or black (1) result bit for each of the four cases of the
           source being white or black, and the destination being white
           or black.  The following list gives the integer rule, the
           name from the include file, and the Boolean operation:

                 0  WHITing         D' = 0
                 1  ANDing          D' = S AND D
                 2  SANDNOTDing     D' = S AND NOT D
                 3  STORing         D' = S
                 4  NOTSANDDing     D' = NOT S AND D
                 5  NoOPing         D' = D
                 6  XORing          D' = S XOR D
                 7  ORing      D' = S OR D
                 8  NORing          D' = NOT S AND NOT D
                 9  NXORing         D' = NOT S XOR D
                10  NOTing          D' = NOT D
                11  SORNOTDing D' = S OR NOT D
                12  NOTSing         D' = NOT S
                13  NOTSORDing D' = NOT S OR D
                14  NANDing         D' = NOT S OR NOT D
                15  BLACKing        D' = 1



      Page 3                                         (73 A2 02MTA REV1)






      COPYBITS(3X)               (Bull-SPS9)               COPYBITS(3X)



           The CopyBits function is called with a pointer to a RasterOp
           structure which contains the parameters to the operation, as
           defined in the include file:

           struct RasterOp {
                struct Form destForm;         /* destination Form into which bits will be stored */
                struct Form sourceForm;  /* a Form from which bits will be copies */
                struct Form maskForm;         /* a Form containing a halftone pattern */
                int rule;           /* (least significant 4 bits used) specifies the
                                      Boolean rule for combining corresponding bits of
                                      the source and destination */
                int destX;               /* X and Y coordinates of top left corner of rect- */
                int destY;                 angular subregion to be filled in destination form */
                int width;               /* width and height of rectangular subregion in
                int height;                destination form to be filled */
                int clipX;               /* Top left corner, width, and height of a
                int clipY;                 rectangular area which restricts
                int clipWidth;             the affected region
                int clipHeight;                 of the destination form */
                int sourceX;             /* Top left corner of the rectangular subregion
                int sourceY;               to be copied from the source form */
           };

           Parameter-passing efficiency is gained by using only a
           single pointer to a structure containing the needed
           parameters for each CopyBits operation.  In addition, the
           state held in the RasterOp structure allows multiple
           operations in a related context to be performed without
           having to repeat all the initialization of parameters.  For
           example, when displaying many lines of text, the destination
           Form and clipping rectangle will not change from one
           character operation to another.

      FILES
           /usr/lib/libgraf.a

      SEE ALSO
           graf(3X), Bull-SPS9 Multi-Window Display Management Guide

















      Page 4                                         (73 A2 02MTA REV1)



