Graphic Operations
There are three general kinds of graphic tasks programmers use in their programs - drawing shapes, displaying images and printing text.

The PowerBASIC graphics capabilities supporting these features can be categorized as follows. With a few exceptions, all of these statements begin with the word GRAPHIC, such as "GRAPHIC WINDOW". Exceptions include RGB, BRG, and all of the ImageList statements.

Here is a categorized list of the Graphic statements.

Graphics Statements - Overview Diagram
The following picture shows how the various PowerBASIC statements interact to support the overall graphics capabilities.

This page covers the details of working with graphics, but this graphic gives a look ahead at what will be covered. Click on the image for a larger version.

The three possible graphic targets are in dark blue. The top arrow gives the commands that control selection of a graphic target. The yellow circles represent the commands which can load graphics into the targets - from files, resources, imagelists, or other targets. The light blue circlels are the two ways to extract bitmap information. The light green boxes represent various commands that can be used on various graphic targets.

Once you've read through this page, the graphic will serve as a mental reference on how all the various statement play together.

Canvas
Graphics (drawing primitives, images, and printed text) require a canvas - a place to put the displayed content. PowerBASIC allows three locations where graphics may be placed - graphics windows, memory bitmaps, and the graphic control.

Selecting a Canvas
The various GRAPHIC statements work on a "graphic target". Although an application can have many canvases, only one at a time can be designated as the graphic target. All GRAPHICS statements will then apply to the target canvas until another canvas is selected.

There are two PowerBASIC statements which handle graphic target designation: 

    GRAPHIC ATTACH - designates the graphic target
    GRAPHIC DETACH - removes current target from use with GRAPHIC statements

Once a GRAPHIC DETACH is completed, further GRAPHIC commands are ignored until another target is selected.

Drawing - Shapes
PowerBASIC provides several statements which allow easy creation of drawing primitives - basic shapes that can be used to make more complex graphics. This includes the ability to set individual points (pixels) on graphic targets. 

    GRAPHIC Arc         GRAPHIC Pie 
    GRAPHIC Box         GRAPHIC Point (pixel)
    GRAPHIC Ellipse     GRAPHIC Polygon
    GRAPHIC Line        GRAPHIC Polyline

Examples of using these drawing statements is provided in the reference table at the bottom of this page.

The Ellipse can be used to draw an ellipse or a circle. The box can be drawn with square or rounded corners.

Drawing Operation Coordinates
All of the shape drawing commands require definition of where the graphical operation will take place. GRAPHIC operations use either a starting point (x,y coordinates called the POS) or a pair of (x,y) coordinates to bound the drawing operation.

Images
PowerBASIC provides built-in support for only two types of image formats - bitmaps (*.bmp) and icons (*.ico). As was discussed earlier, images can be placed in three basic places - controls, graphic window, and memory bitmaps. Once an image is placed in any of these locations, the images can easily be manipulated or transferred between graphic targets, imagelists, and other controls which support images.

An application could also programmatically create a bitmap, such as by creating a bitmap structure and manipulating the individual bits of the bitmap. In particular, PowerBASIC supports two very useful functions which give the programmer direct access to individual pixels within an image. 

    GRAPHIC GET BITS - gets image from graphic target and 
                     - places into a dynamic string
    GRAPHIC SET BITS - returns image string to graphic target

The dynamic string structure is simply a series of 4-bytes for each bit within the bitmap, plus a leading eight bits to give the width and height of the bitmap. This structure can easily be created or manipulated programmatically. The PowerBASIC CVL function converts 4-byte strings to long integers (color values), and the MKL$ function converts long integers to 4-byte strings.

ImageList Data Structure
As was noted above, PowerBASIC supports the creation of an array of bitmaps called an imagelist. Normal array functions do not apply to an imagelist. Instead, access to the images contained in the imagelist use special IMAGELIST statements. Imagelists can contain bitmaps or icons, but not both.

The advantage of using an imagelist is in the ease and speed of accessing images. Imagelists can be used as the source of an image for any graphic target.

To create an empty ImageList, use one of the following commands. 

    IMAGELIST NEW BITMAP   'creates new IMAGELIST structure (bitmaps only)
    IMAGELIST NEW ICON     'creates new IMAGELIST structure (icons only)

The two statements above create an empty imagelist structure, to which images must be added using one of the following: 

    IMAGELIST ADD BITMAP   'add bitmap to the IMAGELIST
    IMAGELIST ADD ICON     'adds icon to the IMAGELIST
    IMAGELIST ADD MASKED   'bitmap is added to the icon IMAGELIST

With the IMAGELIST ADD MASKED command, PowerBASIC provides a way to use a bitmap as an icon, with the additional feature of selecting a transparency color.

Finally, IMAGELISTs can be managed using one of the following commands. 

    IMAGELIST GET COUNT    'number of images in the IMAGELIST
    IMAGELIST KILL         'destroys the specified IMAGELIST
    IMAGELIST SET OVERLAY  'declares an image as an overlay

Assigning Images to Graphic Targets
Once a graphic target has been selected, the commands to place an image in the target can be characterized by the source of the image.

Here are the four basic GRAPHIC commands which place an image into a graphic target. A fifth command is also listed, showing how to clear the image. 

    GRAPHIC Render    - from a file (*.bmp or *.pbr)
    GRAPHIC ImageList - from an imagelist structure (see next section)
    GRAPHIC Copy      - from a graphic target (control, bitmap, window)
    GRAPHIC Stretch   - from a graphic target (control, bitmap, window)

    GRAPHIC Clear     - applies to graphic targets (control, bitmap, window)

Colors
PowerBASIC supports a 24-bit (3 byte), hexadecimal color numbering scheme. A color number is created by simply concatenating the hexadecimal values of the separate red, green, and blue values as shown in the following example. 

    red&   = &HFF
    green& = &H08
    blue&  = &HD4

    BGRcolor& = &HD408FF      'PowerBASIC standard B+G+R nomenclature
    RGBcolor& = &HFF08D4      'note 1st and 3rd bytes are reversed

The PowerBASIC choice of BGR was made in support of Windows API which deal with Device Independent Bitmaps (DIB), which require a BGR color number.

To support other API which require an RGB color number, PowerBASIC provides the BGR and RGB functions, each of which return the appropriate color number - either from the r, g, and b values, or from the opposite color number format.

Here are examples for each. 

    RGBcolor& = RGB(red&, green&, blue&)
    RGBcolor& = RGB(BGRColor&)

    BGRcolor& = BGR(red&, green&, blue&)
    BGRcolor$ = BGR(RGBColor&)

KeyBoard Statements
The PowerBASIC GRAPHIC statement also supports the following keyboard capabilities. These 

    GRAPHIC INKEY$ - read keyboard character
    GRAPHIC INPUT - read data from keyboard
    GRAPHIC INSTAT - tests whether keyboard character is ready
    GRAPHIC INPUT FLUSH - write all buffered keyboard data
    GRAPHIC LINE INPUT - read entire line from keyboard
    GRAPHIC WAITKEY$ - wait for keyboard character

These are discussed more fully in the keyboard tutorial section.

Graphic Command Summary
Here's a summary of the PowerBASIC statements available to display graphics. Most, if not all, were discussed earlier on this page.

Graphic Function Reference
Here's a quick reference of the available graphic functions, in alphabetical order.

If you have any suggestions or corrections, please let me know.