gmf_copy_plane()

GMF_$COPY_PLANE                   Domain/OS                    GMF_$COPY_PLANE


NAME
     gmf_$copy_plane - copy a bitmap plane to a GMF

SYNOPSIS (C)
     #include <apollo/base.h>
     #include <apollo/gmf.h>

     void gmf_$copy_plane(
          ios_$id_t &stream_id,
          boolean &black_or_white,
          short &bpi,
          void *&plane_ptr,
          short &x_dimension,
          short &y_dimension,
          short &wpl,
          status_$t *status)

SYNOPSIS (Pascal)
     %include '/sys/ins/base.ins.pas';
     %include '/sys/ins/gmf.ins.pas';

     procedure gmf_$copy_plane(
          in sid: ios_$id_t;
          in black_or_white: boolean;
          in bpi: integer;
          in plane_ptr: univ gmf_$memory_ptr_t;
          in x_dimension: integer;
          in y_dimension: integer;
          in wpl: integer;
          out status: status_$t);

SYNOPSIS (FORTRAN)
     %include '/sys/ins/base.ins.ftn'
     %include '/sys/ins/gmf.ins.ftn'

           integer*4 status
           integer*2 stream_id, bpi, x_dimension, y_dimension
           integer*2 wpl, bits(65535)
           logical black_or_white

           integer*4 plane_ptr
           pointer /plane_ptr/ bits

           call gmf_$copy_plane(stream_id, black_or_white, bpi, plane_ptr,
          &                     x_dimension, y_dimension, wpl, status)

DESCRIPTION
     Gmf_$copy_plane copies a bitmap plane, specified by plane_ptr,
     x_dimension, and y_dimension, into the GMF open on stream_id.  The actual
     size of an image as it would appear on a display can be preserved with
     the proper bpi setting.

     stream_id
          The stream ID of the GMF to store the image in.

     black_or_white
          A Boolean value indicating whether bits with the value 1 are black
          or white.  A value of true means "1" bits are black and "0" bits are
          white.  A value of false means "1" bits are white and "0" bits are
          black.  In the GMF, "1" bits are assumed to mean black.  Conse-
          quently, if black_or_white is false, the copied bit values are
          inverted.

     bpi  The number of bits per inch in the image to be saved.  Bpi is usu-
          ally used to specify the resolution of the display, and thus defines
          the size the image would have if displayed so that a later reading
          of the GMF can restore the image in its proper size.  If bpi is
          nonzero, the device reading the GMF contents can average or interpo-
          late the data to render an image that is as close as possible to the
          size defined by bpi, x_dimension, and y_dimension.  If bpi is 0, the
          size of the saved image is undefined, and an output device will use
          one dot to represent each bit from the saved image, regardless of
          the resulting size of the image.

     plane_ptr
          A pointer to the upper left corner of the bitmap to be stored, usu-
          ally obtained by calling gpr_$inq_bitmap_pointer.

     x_dimension
          The width of the bitmap, or the number of bits in the x-dimension,
          to be stored in the GMF.

     y_dimension
          The height of the bitmap, or the number of bits in the y-dimension,
          to be stored in the GMF.

     wpl  The number of 16-bit words in the bitmap per scan line of the
          display hardware.

     status
          The completion status.

NOTES
     Gmf_$copy_plane is a special case of gmf_$copy_subplane in that it lacks
     arguments for offsetting the display pointer.
Museum
