Virtual Buffer Fundamentals

We'll begin with a review of some virtual buffer fundamentals. As we've already seen most of this material, we're pretty much just going to skim over it here.

Virtual buffers are blocks of memory that Fastgraph treats as off-screen drawing surfaces. An application may have up to 256 virtual buffers defined simultaneously. Each virtual buffer has its own independent clipping limits, which default to the entire virtual buffer. Any program that uses virtual buffers must initialize the virtual buffer environment by calling fg_vbinit() once, before it calls any other Fastgraph virtual buffer functions (we usually call fg_vbinit() in the program's WM_CREATE handler). The fg_vbinit() function has no parameters and no return value.

The fg_vballoc() function is the easiest way to create virtual buffers. By default, any virtual buffers created with fg_vballoc() will be 256-color virtual buffers, but fg_vballoc() can create high color and true color virtual buffers if you first call fg_vbdepth(). Virtual buffer memory is usually allocated from Windows' global heap. The amount of memory needed in bytes is equal to the number of bytes per pixel multiplied by the virtual buffer width multiplied by the virtual buffer height, plus up to 1,064 bytes for the virtual buffer's header and palette information. If necessary, fg_vballoc() will extend the specified virtual buffer width to a multiple of four bytes.

If you are not using Fastgraph's DirectX libraries, you can allocate the virtual buffer memory yourself and then use fg_vbdefine() to define a virtual buffer. Usually this memory is allocated dynamically with the Windows API macro GlobalAllocPtr(), the malloc() function from the C run-time library, or the C++ new[] operator. Like fg_vballoc(), the fg_vbdefine() function returns a handle by which the virtual buffer is referenced. For example, the following code creates a 640x480 virtual buffer with fg_vbdefine():

C/C++:

char *Buffer;
Buffer =(char *)GlobalAllocPtr(GMEM_MOVEABLE,fg_vbsize(640,480));
hVB = fg_vbdefine(Buffer,640,480);
fg_vbopen(hVB);
fg_vbcolors();

Delphi:

var
  hGlobal : THandle;
  Buffer : pointer;
begin
  hGlobal := GlobalAlloc(GHND,fg_vbsize(640,480));
  Buffer := GlobalLock(hGlobal);
  hVB := fg_vbdefine(Buffer,640,480);
  fg_vbopen(hVB);
  fg_vbcolors;

Visual Basic:

Dim Buffer() As Byte
ReDim Buffer(fg_vbsize(640, 480))
hVB = fg_vbdefine(Buffer(0), 640, 480)
Call fg_vbopen(hVB)
Call fg_vbcolors

Note how we use fg_vbsize() to calculate the total number of bytes required for the virtual buffer's drawing surface, header, and color table. Again, if you are using Fastgraph's DirectX libraries, you must use fg_vballoc() to create virtual buffers rather than fg_vbdefine().

Once a virtual buffer is defined, you can activate it with fg_vbopen(). It will remain the active virtual buffer until you call fg_vbclose(), or until you call fg_vbopen() to switch to another virtual buffer. After you open a 256-color virtual buffer for the first time, you must call fg_vbcolors() to associate the colors in the active logical palette with the virtual buffer. It is not necessary to call fg_vbcolors() with direct color virtual buffers, but it causes no harm.

Two of the more important virtual buffer functions are fg_vbpaste() and fg_vbscale(). These functions copy rectangular areas from the active virtual buffer to the client area. The fg_vbpaste() function performs a straight pixel copy, while fg_vbscale() scales the region to fit in the requested part of the client area. All the Fastgraph for Windows example programs call at least one of these two functions to display graphics in the client area, usually in the WM_PAINT message handler and possibly elsewhere too.

After you're finished with a virtual buffer, its memory may be released using fg_vbfree(). This usually happens in the WM_DESTROY message handler. You should use fg_vbfree() only with virtual buffers created with fg_vballoc() and not those created with fg_vbdefine(), and you cannot use it on the active virtual buffer. For virtual buffers created with fg_vbdefine(), free the memory using the complementary method of allocating the memory. That is, use GlobalFreePtr() if you allocated the memory with GlobalAllocPtr(), use free() if you used malloc(), or delete[] if you used new[].