Function GraBitBlt() | Xbase++

Copies section of a raster image into a presentation space (bit-blitting).

GraBitBlt( [<oTargetPS>], ;
           [<oSourcePS>], ;
           <aTargetRect>, ;
           <aSourceRect>, ;
           [<nRasterOP>], ;
           [<nCompress>]  ) --> lSuccess

The optional argument <oTargetPS> specifies a presentation space into which a raster image (bitmap) is copied. If <oTargetPS> is NIL, the image is copied into the current window.

The optional argument <oSourcePS> specifies a presentation space from which a raster image is copied. If <oSourcePS> is NIL, the image is copied from the current window.

<aTargetRect> := { <nX1>, <nY1>, <nX2>, <nY2> }

<aTargetRect> identifies a rectangular area into which the raster image is copied. <nX1> and <nY1> indicate the point at the lower left corner. <nX2> and <nY2> designate the upper right corner of the area. The coordinates must always be given in pixels which means that the result of the operation is device dependent.

<aSourceRect> := { <nX1>, <nY1> [,<nX2>, <nY2>] }

<aSourceRect> identifies the rectangular area from which the raster image is copied. <nX1> and <nY1> indicate the point at the lower left corner. <nX2> and <nY2> designate the upper right corner of the area. The coordinates <nX2> and <nY2> are optional. If they are not specified, the area copied is exactly as large as the area of <aTargetRect>.

The parameter <nRasterOP> uses only constants defined in GRA.CH. These begin with GRA_BLT_ROP_ and determine which of the various raster operations are performed during the copying of the raster image. The default value is GRA_BLT_ROP_SRCCOPY, which copies the raster image without modification from <oSourcePS> to <oTargetPS>.

The parameter <nCompress> has meaning only when the area <aTargetRect> is smaller than <aSourceRect>. Only #define constants from GRA.CH are used. These begin with GRA_BLT_ROP_and set the mode for the compression or reduction of a raster image. Pixels are lost during the reduction and <nCompress> specifies the mode used to determine which pixels are saved and which are discarded. The default value is GRA_BLT_BBO_OR. For color raster images, the default compression mode should be changed to GRA_BLT_BBO_IGNORE.

The return value of GraBitBlt() is .T. (true) if the raster image was copied from the specified area in <oSourcePS> to <oTargetPS>, otherwise it is .F. (false). If the return value is equal to .F., the cause of the error can be determined using GraError().

The function GraBitBlt() is an efficient function for copying raster images (bitmaps). Unlike a vector image which consists of vector-based shapes, a raster image contains all the pixels that make up the image.

GraBitBlt() operations are very fast. Using GraBitBlt(), sections of raster images (bitmaps) are copied, enlargements and reductions are produced and multiple copies of a raster image are displayed very quickly. For example, a window background might be filled with a fill pattern defined in a bitmap file and copied repeatedly to fill the window.

Raster images cannot be scaled without loss of information. Enlarging a bitmap causes individual pixels to be expanded, which introduces jagged edges that become more pronounced with increasing scale factors. Similarly, reducing an image in size causes pixels to be eliminated and hence color information to be lost. GraBitBlt() supports several modes which affect the way eliminated pixels are treated during image reduction. The desired compression mode is selected using the <nCompress> parameter.

The function GraBitBlt() can copy a raster image within a single presentation space or from one presentation space into another. If, for example, the second presentation space <oTarget> is associated with a printer, raster images are printed using GraBitBlt(). More information on the display and output of raster images is found with the class XbpBitmap().

A raster image can only be transferred from a presentation space associated with a device that supports reading raster data. If a presentation space associated with a printer device context is specified in parameter <oSourcePS>, the resulting image will be blank. Similarly, the image transferred from a micro presentation space may be clipped if only parts of the corresponding window are currently visible. More information can be found in section in the Graphics output devices.

Copying bitmaps


// In the example a simple drawing is displayed. It is 
// copied three times by GraBitBlt(), demonstrating different 
// variations of the function. 

#include "Gra.ch" 

PROCEDURE Main 
   LOCAL aAttrArc, aAttrBox 
   LOCAL nX0 , nY0 , nX1, nY1, nX2, nY2, nRadius 

   SetColor("N/W")                     // fill window with pale gray 
   CLS 

   aAttrBox := ARRAY( GRA_AA_COUNT )   // attributes for rectangle 
   aAttrBox[ GRA_AA_SYMBOL ] := GRA_SYM_DIAG2 
   aAttrBox[ GRA_AA_COLOR  ] := GRA_CLR_RED 

   aAttrArc := ARRAY( GRA_AA_COUNT )   // attributes for circle 
   aAttrArc[ GRA_AA_SYMBOL ] := GRA_SYM_DENSE3 
   aAttrArc[ GRA_AA_COLOR  ] := GRA_CLR_BLUE 

   nRadius :=  40                      // radius 
   nX0     :=  20                      // lower left corner 
   nY0     := 140 
   nX1     :=  90                      // upper right corner 
   nY1     := 240                      // and circle center point 
   nX2     := nX1 + nRadius            // upper right corner 
   nY2     := nY1 + nRadius            // for copying area 

   GraSetAttrArea( NIL, aAttrBox )     // draw rectangle 
   GraBox( NIL, {nX0, nY0}, {nX1, nY1}, GRA_OUTLINEFILL ) 

   GraSetAttrArea( NIL, aAttrArc )     // draw circle 
   GraArc( NIL, {nX1,nY1}, nRadius,,,, GRA_OUTLINEFILL  ) 

   GraBitBlt( , , { nX0+150, nY0, ;    // copy 1:1 
                    nX2+150, nY2 }, ; 
                  { nX0, nY0 } ) 

   GraBitBlt( , , { nX0+300, nY0, ;    // copy 1:1.2 
                    INT(1.2*nX2) + 300, INT(1.2*nY2) }, ; 
                  { nX0, nY0, nX2, nY2 } ) 

   GraBitBlt( , , { nX0+450, nY0, ;    // copy 1:0.8 
                    INT(0.8*nX2)+450, INT(0.8*nY2) }, ; 
                  { nX0, nY0, nX2, nY2 } ) 

   Inkey(0)                            // wait for key press 
RETURN

If you see anything in the documentation that is not correct, does not match your experience with the particular feature or requires further clarification, please use this form to report a documentation issue.

Function GraBitBlt() Foundation