GPR_$SELECT_DISPLAY_BUFFER        GPR Calls         GPR_$SELECT_DISPLAY_BUFFER


NAME
     gpr_$select_display_buffer - switches the buffers in a double buffering
     program.

FORMAT
     gpr_$select_display_buffer (display_desc, option_desc, option_val,
                                 option, status)

DESCRIPTION
     This routine switches the buffers in a double buffering program.  The
     gpr_$select_display_buffer call performs two separate actions.  First, it
     lets you choose the bitmap (primary or buffer) to display.  Second, it
     lets you take action on the bitmap that doesn't get displayed.  Use
     display_desc to choose the bitmaps to display.  Use option_desc,
     option_val and option to take action on the bitmap that doesn't get
     displayed.

   Input Parameters
     display_desc
          The descriptor of the bitmap you want displayed in
          gpr_$bitmap_desc_t format.  This is a 4-byte integer.  You must
          specify the descriptor of either the primary bitmap or the buffer
          bitmap.

     option_desc
          The descriptor of the "other" bitmap in gpr_$bitmap_desc_t format.
          This is a 4-byte integer.  You must specify the descriptor of either
          the primary bitmap or the buffer bitmap, whichever one you did not
          specify in display_desc.  That is, if display_desc contains the
          descriptor of the primary bitmap, then you must set option_desc
          equal to the descriptor of the buffer bitmap, and vice-versa.  If
          you set the option parameter equal to gpr_$undisturbed_buffer, then
          the system ignores the value of option_desc.

     option_val
          The color value that the bitmap specified in option_desc should be
          cleared to.  The color value is a 4-byte integer.  This parameter
          only has meaning if you set option (the next parameter) to
          gpr_$clear_buffer.  If option is set to some other value, then the
          system ignores option_val.

     option
          The action to take on the bitmap specified by option_desc in
          gpr_$double_buffer_option_t format.  This is a 2-byte integer.  Pos-
          sible values for this parameter are:

          gpr_$clear_buffer
               gpr sets every pixel in the bitmap to the color specified by
               option_val.

          gpr_$undisturbed_buffer
               gpr does not change the value of any pixel in the specified
               bitmap.

          gpr_$copy_buffer
               gpr copies the value of every pixel in the display_desc bitmap
               to every pixel in the option_desc bitmap.  Use this option for
               incremental rendering.


   Output Parameters
     status
          Completion status, in status_$t format.

SEE ALSO
     gpr_$allocate_buffer, gpr_$copy_buffer.

NOTES
     Use gpr_$copy_buffer when you want to build a figure based on the  previ-
     ous figure.  It is a very useful option for animation.

     You must create a buffer bitmap with the gpr_$allocate_buffer call before
     calling gpr_$select_display_buffer.

     This call only switches the pixels inside the  clip  window.   The  other
     pixels  are unaffected by the gpr_$select_display_buffer call.  Thus with
     clipping active, the screen can simultaneously display portions from both
     bitmaps.

     This call only works on devices that support double buffering.