Class XbpBitmap() Foundation

Class function of the XbpBitmap class.

Description

The XbpBitmap class provides objects that can display and manage graphic images. Images that exist only in memory should be distinguished from those that are saved in a file. Bitmap files must be linked to the EXE file using the resource compiler in order for the bitmap to be loaded using the :load() method of the XbpBitmap object. The :make() method requests the required memory space for raster images that are created as bitmaps in memory.

The creation of an XbpBitmap object using the method :create()needs a presentation space to be specified that is already associated with an output device. This is generally the PS of the active window or a PS that is linked to a printer. Specifying the PS in the call to this method ensures that the XbpBitmap object is compatible with the corresponding PS and its output device. The image is displayed using the method :draw() that must specify the PS where the output is to take place.

Supported image formats

An XbpBitmap object is able to process and display not only raster images (bitmaps, BMP format) but also images stored in different graphics formats. In addition to BMP formats, GIF (Graphics Interchange Format), JPEG (Joined Photographic Experts Group) and PNG (Portable Network Graphics) images can be processed.

Transparency

XbpBitmap objects support several ways of achieving transparency in raster images:

Background masking (chroma keying)

This involves defining a key color for identifying the parts in the image which should be replaced with background information by the :draw() method. Image formats such as PNG or GIF support saving the key color along with the actual image data. In this case, the image will automatically be displayed transparent after it is loaded. The key color can also be application-supplied, for example, for using image formats which do not support transparency. See the method :getDefaultBgColor() for further information.

Per-pixel transparency (alpha channel)

In images using an alpha channel transparency information is saved for each pixel along with the pixel's color value. Per-pixel transparency is supported in PNG images with 32 bit color depth. See :hasAlphaChannel for further information.

Background masking (chroma keying) is not supported for images with an alpha channel. This means that the key color value in :transparentClr is ignored in this case.

Blending

This involves applying a constant opacity factor for the whole image during output. Blending is supported irrespective of whether transparent areas are defined in the image itself. See the member variable :transparency for information.

Class methods
:new()
Creates an instance of the XbpBitmap class.
Life cycle
:create()
Requests system resources for the XbpBitmap object.
:configure()
Reconfigures the XbpBitmap object after :create() has been executed.
:destroy()
Releases the system resources of the XbpBitmap object.
Runtime data
:bits
The number of bits per color.
:bufferOffset
Specifies the start of the raster image in the buffer.
:hasAlphaChannel
Specifies whether the image has an alpha channel.
:planes
Number of bit planes per pixel.
:transparency
Level of transparency to apply to the image.
:transparentClr
Transparent color in the image.
:xSize
The number of pixels in x direction (width).
:ySize
The number of pixels in y direction (height).
Manipulation
:draw()
Displays a bitmap.
:getColorTable()
Retrieves the color table of a bitmap.
:getDefaultBGColor()
Retrieves the default background color of a bitmap.
:getProperty()
Retrieves a property from an image.
:load()
Loads a bitmap from a resource file linked to the executable file.
:loadFile()
Loads an image file from disk
:make()
Requests memory for a new bitmap.
:presSpace()
Sets or returns the presentation space linked to the XbpBitmap object.
:saveFile()
Saves a bitmap image in a file.
:setBuffer()
Sets or returns the buffer containing the image data.
:setProperty()
Modifies a property of an image.
:getIPicture()
Returns the image as an IPicture automation object.
:setIPicture()
Initializes the bitmap through an IPicture automation object.
Examples
Declare, load and display a bitmap as a resource

// This example demonstrates the basic process of creating 
// bitmaps and displaying them in a window. The bitmap is 
// loaded and displayed using the resource ID 2000. At the 
// end of the example code, an example of a resource file 
// containing the bitmap as a resource is shown. 
PROCEDURE Main 
   LOCAL oBMP, oPS 

   SetColor( "N/W" ) 
   CLS 

   oPS := SetAppWindow():presSpace() 
   oBMP:= XbpBitmap():new():create( oPS ) 

   oBMP:load( NIL, 2000 ) 
   oBMP:draw( oPS, {50,50} ) 

   WAIT 

RETURN 

/* Resource file containing the bitmap declaration 
   TEST.ARC 
*/ 
   ICON     1     =  "XPPPMT.ICO" 
   POINTER  2     =  "XPPPOINT.PTR" 

   BITMAP   2000  =  "SHARK.BMP" 
Print bitmap

// This example demonstrates the process of how bitmaps can 
// be output to a printer. A presentation space that is linked 
// to a printer device context is created in the user defined 
// function PrinterPS(). The bitmap is scaled to fill the 
// entire paper size during printing. This means that the 
// printing takes some time. The bitmap is loaded and printed 
// using the resource ID 2000. 

#include "Gra.ch" 

PROCEDURE Main 
   LOCAL oPrinterPS, oBitmap, aRect, aSize 

   oPrinterPS := PrinterPS() 
   oBitmap    := XbpBitmap():new():create( oPrinterPS ) 

                                      // Determine paper size 
   aSize      := oPrinterPS:device():paperSize() 
   aRect      := { 0, 0, aSize[1], aSize[2] } 

   oBitmap:load( NIL, 2000 )          // Load bitmap 

   oPrinterPS:device():startDoc()     // Activate spooler 

   oBitmap:draw( oPrinterPS, aRect )  // Spool print job 

   oPrinterPS:device():endDoc()       // Close spooler 

   DestroyDevice( oPrinterPS )        // Release resources 
   oBitmap:destroy() 

RETURN 

// Create the presentation space for a printer 
FUNCTION PrinterPS() 
   LOCAL oPS, oDC := XbpPrinter():new():create() 

   oPS:=XbpPresSpace():new() 
   oPS:create( oDC, oDC:paperSize(), GRA_PU_LOMETRIC ) 
RETURN oPS 

// Release printer device context 
PROCEDURE DestroyDevice( oPS ) 
   LOCAL oDC := oPS:device() 

   IF .NOT. oDC == NIL 
      oPS:configure()          // Configure to release 
      oDC:destroy()            // device context from PS 
   ENDIF 
RETURN 
Save and restore screen in the graphics mode

// In the example, the two user defined functions 
// GraSaveScreen() and GraRestScreen() are programmed 
// that allow graphic displays in a window to be saved. 
// This is similar to the functions SaveScreen() and 
// RestScreen(). The Main procedure demonstrates the use 
// of these two functions by drawing a box, saving it, 
// and redisplaying it at 10 different places. 

PROCEDURE Main 
   LOCAL oBitmap, oPS 

   SetColor( "N/W" ) 
   CLS 
   oPS := SetAppWindow():presSpace() 

   GraBox( oPS, {10,10}, {100,100} ) 
   oBitmap := GraSaveScreen( oPS, {10,10}, {91,91} ) 

   WAIT "Box was saved in bitmap. Press any key..." 
   CLS 
   WAIT "Box will be redisplayed 10 times. Press any key..." 

   FOR i:=0 TO 9 
      GraRestScreen( oPS, {10+20*i,10+10*i}, oBitmap ) 
   NEXT 
   oBitmap:destroy() 

   WAIT "Done. Press any key..." 
RETURN 

// The function GraSaveScreen() creates a bitmap in memory 
// where the specified section of a window is copied. The 
// area to be saved is defined by the parameter aPos {nX,nY} 
// and aSize {nXsize, nYsize}. The presentation space 
// oSourcePS is the PS of a window and contains the screen 
// information to be saved. It is copied into oTargetPS using 
// GraBitBlt(). oTargetPS is the presentation space for the 
// bitmap and must be assigned to the XbpBitmap object before 
// the memory space for the raster image is requested using 
// :make(). 

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 GraRestScreen() redisplays a saved 
// section of screen. It just uses the :draw() method 

FUNCTION GraRestScreen( oTargetPS, aPos, oBitmap ) 
   oBitmap:draw( oTargetPS, aPos ) 
RETURN NIL 
Accessing image properties embedded in an image file

// This example loads a JPEG file from disk and displays 
// some properties such as the author and copyright information 
// from the image's meta data. 
#include "gra.ch" 

PROCEDURE Main 
   LOCAL oBitmap 
   LOCAL cFile 
   LOCAL cAuthor 
   LOCAL cTitle 
   LOCAL cSubject 
   LOCAL cCopyright 
   LOCAL oBmp 

   SetColor( "N/W" ) 
   CLS 

   // The JPEG file used in the example is loaded from 
   // the image collection installed with Xbase++. The 
   // corresponding directory is located using the 
   // XPPRESOURCE environment variable normally set by 
   // the installer. 
   cFile := GetImageDir() 
   IF Empty(cFile) 
      ? "Error - XPPRESOURCE env. variable must point to installed images!" 
      WAIT 
      QUIT 
   ENDIF 
   cFile += "\asky_fhd.jpg" 

   oBmp  := XbpBitmap():new():create() 
   IF !oBmp:loadFile(cFile) 
      WAIT "Error loading image. Please press a key." 
      QUIT 
   ENDIF 

   // Display a preview of the image for reference 
   oBmp:draw( , {300,20,600,280},,, GRA_BLT_BBO_IGNORE ) 

   // Read exemplary properties from the image and 
   // display them for demonstration purposes 
   cTitle     := Coalesce( oBmp:getProperty("System.Title"),     "(empty)" ) 
   cSubject   := Coalesce( oBmp:getProperty("System.Subject"),   "(empty)" ) 
   cAuthor    := Coalesce( oBmp:getProperty("System.Author"),    "(empty)" ) 
   cCopyright := Coalesce( oBmp:getProperty("System.Copyright"), "(empty)" ) 

   ? 
   ? "Title:     ", cTitle 
   ? "Subject:   ", cSubject 
   ? 
   ? "Author:    ", cAuthor 
   ? "Copyright: ", cCopyright 
   ? 

   WAIT "Done. Press any key..." 
RETURN 

// Get the directory containing the images installed with 
// Xbase++. 
FUNCTION GetImageDir() 
   LOCAL cEnv 
   LOCAL nIdx 
   LOCAL cTmp 
   LOCAL cRet := "" 

   cEnv := GetEnv( "XPPRESOURCE" ) 
   IF Empty(cEnv) 
      RETURN "" 
   ENDIF 

   // Extract the image directory from the list 
   // of semicolon-separated directories 
   DO WHILE Len(cEnv) > 0 
      nIdx := At( ";", cEnv ) 
      IF nIdx != 0 
         cTmp := Left( cEnv, nIdx -1 ) 
         cEnv := SubStr( cEnv, nIdx + 1) 
      ELSE 
         cTmp := cEnv 
         cEnv := "" 
      ENDIF 

      IF At("BITMAP", Upper(cTmp)) != 0 
         cRet := cTmp 
         EXIT 
      ENDIF 

      IF nIdx == 0 
         EXIT 
      ENDIF 
   ENDDO 
RETURN cRet 
Feedback

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.