An Introduction to Virtual Buffers

In our first Fastgraph for Windows example, we introduced the concept of virtual buffers and briefly illustrated how to set up a virtual buffer, display its contents in the window's client area, and release the virtual buffer memory when the program exits. We'll now take a more in-depth look at the Fastgraph functions that perform these tasks.

Virtual buffers are blocks of memory that serve as off-screen drawing surfaces. All Fastgraph functions that perform graphics operations either write to a virtual buffer, copy data between virtual buffers, or display the contents of a virtual buffer in the client area. An application may have up to 256 virtual buffers defined at the same time. Before working with virtual buffers, programs must call fg_vbinit() to initialize Fastgraph's virtual buffer environment. This function has no parameters and is usually called in the program's WM_CREATE message handler. In Fastgraph's native libraries, fg_vbinit() always returns zero.

The easiest way to create a virtual buffer is with the fg_vballoc() function. Its two parameters specify the virtual buffer width and height in pixels, and its return value indicates whether or not the virtual buffer was created successfully. If successful, fg_vballoc() returns a handle by which the virtual buffer is referenced (between 0 and 255). The possible error return values are -1 (virtual buffer table full) or -2 (cannot allocate memory for the virtual buffer). By default, fg_vballoc() creates 256-color (8 bits per pixel) virtual buffers, but we can also use fg_vbdepth() to create high color and true color virtual buffers.

Each row of pixels in a virtual buffer must be aligned on a four-byte boundary. This means fg_vballoc() will extend the width parameter, if necessary, to a multiple of four bytes. For instance, if we tell fg_vballoc() to create a 101x101 256-color virtual buffer, we will actually get a 104x101 buffer. Similarly, telling fg_vballoc() to create a 101x101 high color virtual buffer results in a 102x101 buffer (102 high color pixels = 204 bytes).

Most Fastgraph functions operate on a virtual buffer called the active virtual buffer. The fg_vbopen() function makes a virtual buffer the active virtual buffer. Its only parameter is a virtual buffer handle returned by fg_vballoc(), and its return value will be zero if the virtual buffer was opened successfully. The possible error return values are -1 (invalid virtual buffer handle) or -2 (no virtual buffer defined for the specified handle). The virtual buffer will remain the active virtual buffer until you call fg_vbclose(), or until you call fg_vbopen() with a different virtual buffer handle.

After you open a 256-color virtual buffer for the first time, you must call fg_vbcolors() to associate the active logical palette colors with the virtual buffer. For high color and true color virtual buffers, calling fg_vbcolors() causes no harm but is not necessary. In our first example, we created the default logical palette with fg_defpal().

As a review, here's how we initialized the virtual buffer environment, created a 640x480 virtual buffer, and made it the active virtual buffer in the WM_CREATE message handler of our first example program:

C/C++:

fg_vbinit();
hVB = fg_vballoc(640,480);
fg_vbopen(hVB);
fg_vbcolors();

Delphi:

fg_vbinit;
hVB := fg_vballoc(640,480);
fg_vbopen(hVB);
fg_vbcolors;

Visual Basic:

Call fg_vbinit
hVB = fg_vballoc(640, 480)
Call fg_vbopen(hVB)
Call fg_vbcolors

Once you've created an image in a virtual buffer, chances are you'll want to display it. Fastgraph provides two functions, fg_vbpaste() and fg_vbscale(), for this purpose. More precisely, these functions copy any rectangular subset of the active virtual buffer to the specified position in the window's client area. The difference between the functions is that fg_vbpaste() performs a one-to-one pixel copy from the virtual buffer to the client area, while fg_vbscale() scales the requested virtual buffer region to fit the requested client region. A program's WM_PAINT message handler will often call fg_vbpaste() or fg_vbscale(). As you might think, pasting is more useful (and slightly more efficient) with a fixed-size window, or when the window serves as a viewport into a larger background. Scaling is more useful when you want the virtual buffer contents to fill the client area, regardless of the window's size.

The fg_vbpaste() function has six parameters. The first four define the horizontal and vertical extremes of the source region to copy from the virtual buffer. The last two define the destination position in the client area. The region copied from the virtual buffer will be displayed with its lower left corner at the specified destination position. For example,

C/C++ and Delphi:

fg_vbpaste(0,639,0,479,0,479);

Visual Basic:

Call fg_vbpaste(0, 639, 0, 479, 0, 479)

copies the active 640x480 virtual buffer to the upper left 640x480 pixels of the client area.

The fg_vbscale() function has eight parameters. The first four define the source region extremes as in fg_vbpaste(). The last four define the destination extremes in the client area; usually these will be equal to the client area limits. Assuming cxClient and cyClient respectively contain the horizontal and vertical dimensions of the client area (see the WM_SIZE message handler), the call

C/C++:

fg_vbscale(0,639,0,479,0,cxClient-1,0,cyClient-1);

Visual Basic:

Call fg_vbscale(0,639,0,479,0,cxClient-1,0,cyClient-1)

will scale the active 640x480 virtual buffer to fill the entire client area. The client area may be smaller, the same size as, or larger than the virtual buffer size.

Before a program exits, it must call fg_vbfree() to release the memory associated with each virtual buffer the program creates. This function's only parameter is the virtual buffer handle, and it has no return value. You can instead free all virtual buffers by passing fg_vbfree() any negative number as the handle. Because you cannot release the active virtual buffer's memory, the program must first call fg_vbclose() to close the active virtual buffer. Finally, the program must call fg_vbfin() to terminate virtual buffer processing. These tasks are usually done in the program's WM_DESTROY message handler, as was done in our first example:

C/C++:

fg_vbclose();
fg_vbfree(hVB);
fg_vbfin();

Delphi:

fg_vbclose;
fg_vbfree(hVB);
fg_vbfin;

Visual Basic:

Call fg_vbclose
Call fg_vbfree(hVB)
Call fg_vbfin

Virtual buffers are an integral part of developing any Fastgraph for Windows program, so it's especially important to understand the concepts presented in this section. We'll see them over and over in the remaining example programs.