The raster image - XbpBitmap() Foundation

A raster image (bitmap) contains graphic information in the form of pixels. All the pixels in a bitmap that are required to display the image are saved. The XbpBitmap class provides the ability to create and display bitmaps. Raster images saved in a file are connected to an executable file as a resource and can be identified, loaded and displayed using an XbpBitmap object based on the numeric resource ID. Using XbpBitmap objects in this way starts with the declaration of a bitmap file (BMP file) as a resource within an RC file. For example:

/* Type of resource    Resource ID     File name */ 
ICON                1       =      "\XPP\RESOURCE\XPPPMT.ICO" 
POINTER             2       =      "\XPP\RESOURCE\XPPPOINT.PTR" 

BITMAP              2000    =      "\XPP\BITMAP\PHOTO.BMP" 

If this resource file is compiled by the resource compiler and linked to the executable file, an XbpBitmap object can load and display the resource 2000. This is done in the following example:

PROCEDURE Main 
   LOCAL oBMP, oPS 

   SetColor( "N/W" ) 
   CLS 

   // get presentation space from XbpCrt window 
   oPS := SetAppWindow():presSpace() 

   // create XbpBitmap for this PS 
   oBMP:= XbpBitmap():new():create( oPS ) 

   // load bitmap 
   oBMP:load( NIL, 2000 ) 

   // display bitmap in the PS 
   oBMP:draw( oPS, {50,100} ) 

   WAIT 
RETURN 

Before an XbpBitmap object can be created, the presentation space and its device context must exist that will be used for output of the raster image. In the example, output occurs in the presentation space of an XbpCrt window and this represents the output device. The presentation space must be specified in the call to the method :create() which prepares the XbpBitmap object for the display on the screen. The raster image from the PHOTO.BMP file with the resource ID 2000 is then loaded using the method :load() and displayed in the presentation space of the window using :draw().

An XbpBitmap object is also used if a raster image is to be temporarily created in main memory. The methods :presSpace() and :make()are provided for this situation. An XbpBitmap object is associated with a presentation space using :presSpace(). Graphic output can then occur directly in the raster image, and is not visible on the screen. After an XbpBitmap object has received its own presentation space using the method :presSpace(), the size of the raster image must be specified using the method :make(). The memory for screen information (pixels) is then allocated. Graphic output can then occur in the presentation space of the bitmap.

The most important area for this use of XbpBitmap objects is in buffering graphic mode screen output. The entire display in a window or a section of a window can be stored as a raster image of an XbpBitmap object and redisplayed at a later time. Graphic information from the presentation space of a window is copied to the presentation space of an XbpBitmap object using the function GraBitBlt(). This is shown in the following example in the code for the user-defined function GraSaveScreen():

PROCEDURE Main 
   LOCAL oPS, oBitmap 

   // get presentation space from the XbpCrt window 
   oPS := SetAppWindow():presSpace() 

   // draw box 
   GraBox( oPS ,{10,10}, {100,100} ) 

   // save box 
   oBitmap := GraSaveScreen( oPS, {10,10}, {91,91} ) 

   // delete display in the window again 
   CLS 
   WAIT "Box is saved" 

   GraRestScreen( oPS, {10,10}, oBitmap ) 
   WAIT "Box is redisplayed" 
RETURN 

FUNCTION GraSaveScreen( oSourcePS, aPos, aSize ) 
   LOCAL oBitmap   := XbpBitmap():new():create( oSourcePS ) 
   LOCAL oTargetPS := XbpPresSpace():new():create() 
   LOCAL aSourceRect[4], aTargetRect 

   aSourceRect[1] := aSourceRect[3] := aPos[1] 
   aSourceRect[2] := aSourceRect[4] := aPos[2] 
   aSourceRect[3] += aSize[1] 
   aSourceRect[4] += aSize[2] 

   aTargetRect    := {0, 0, aSize[1], aSize[2]} 

   oBitmap:presSpace( oTargetPS ) 
   oBitmap:make( aSize[1], aSize[2] ) 

   GraBitBlt( oTargetPS, oSourcePS, aTargetRect, aSourceRect ) 
RETURN oBitmap 

The function GraSaveScreen() receives the presentation space of a window in the parameter oSourcePS. This contains the graphic information to be saved by copying it into the presentation space oTargetPS. An XbpBitmap object is created as an output device which is suitable for output on the screen (oSourcePS is passed to :create()). For the XbpBitmap object to be able to save graphic output, it needs its own presentation space, which is passed to the object using the method :presSpace(). The newly created presentation space is referenced by oTargetPS. The size of the raster image is specified in :make(). The size corresponds to the parameter aSize which defines the dimensions of the screen section to be saved in the x direction and y direction. Finally, the function GraBitBlt() copies the pixels from the presentation space of the window into the presentation space of the XbpBitmap object.

The user-defined function GraRestScreen() is used to redisplay the saved section of the screen. The raster image managed by an XbpBitmap object is redisplayed in the presentation space of a window. Calling the method :draw() is sufficient to accomplish this task:

FUNCTION GraRestScreen( oTargetPS, aPos, oBitmap ) 
   oBitmap:draw( oTargetPS, aPos ) 
RETURN NIL 

An XbpBitmap object needs a presentation space where the raster image managed by the object is output. When a bitmap is attached as a resource to an executable file, calling the method :load() is sufficient to allow display of the raster image. This method implicitly requests a presentation space for the XbpBitmap object. If, however, a raster image is to be created (during screen buffering, for example), the XbpBitmap object must have its own presentation space which is provided to the object by the method :presSpace(). This method must be executed before the call to :make(). :make() defines the dimensions for a raster image and the memory required to hold all the pixels of the raster image. The required memory can only be determined when a presentation space associated with a device context is provided.