Fastgraph 3D Tutorial

Appendix 3:
Absolute Beginners Guide to Programming with Fastgraph

Getting Started With Virtual Buffers

The first thing you need to understand to start programming with Fastgraph is how to use a virtual buffer. Virtual buffers are so basic to Fastgraph programming, that in fact all Fastgraph initialization relies upon initializing for virtual buffers. The function to initialize a virtual buffer is fg_vbinit(), which is usually on of the first Fastgraph function called in any program.

A virtual buffer can be thought of as a page, screen, surface, or whatever mental device is easiest for you to picture. It is simply a rectangular area that everything is drawn to before being copied (or blitted) to the computer screen.

A virtual buffer can be any size, but it is often convenient to make your virtual buffer the same size as your program's client area or if you have a borderless window (or a full screen application), the size of the screen.

Let's suppose we have a full-screen, borderless window that is 640x480. Then we can create a virtual buffer the same size. The virtual buffer will look like this:

Fig. 1.1 A virtual buffer.

The virtual buffer is referenced by coordinates that start at 0,0 in the upper left corner, and extend to width-1 on the right side and height-1 at the bottom. Any point in the virtual buffer can be read or written using its unique (x,y) coordinate.

Copying Between Virtual Buffers

It is often convenient to have two or more virtual buffers. That way, you can copy between them, or use one virtual buffer for storage and another virtual buffer to build your screen image, or blit a series of virtual buffers in sequence to create an animation. (There are more efficient ways to create animations, but that is one way to do it.) The easiest way to copy a rectangular area between two virtual buffers is to use fg_vbcopy()

Fig. 1.1 Using fg_vbcopy() to copy between virtual buffers.

Here is the C/C++ code to do the above operation:


   fg_vbcopy(x0,x1,y0,y1,x2,y2,buffer1,buffer2);

Notice that the first 4 parameters are the x's and y's of the source area. The next two parameters are the x and y coordinates of the lower left corner of the destination. The final two parameters are the "handles" of the virtual buffers, which are simply integer values that are assigned when the virtual buffers are created.

There has always been a bit of controversy about the order of the parameters in fg_vbcopy(), and some of the other Fastgraph blitting functions. The decision to define rectangular areas based on their sides (x,x,y,y) instead of their corners (x,y,x,y) goes back many years. Standards (and tastes) change, and personally, I wouldn't mind changing this one, but to do so would break everybody's Fastgraph code. So we stick to this convention for now.

Similarly, the convention of addressing the destination by its lower left corner instead of the upper left corner is a very old decision. Originally it had to do with objects are more commonly positioned according to their bottoms. Fonts line up at the bottom of each character, for example, and people walk on their feet regardless of how tall they are. Many years ago, this convention was common, and it has survived in Fastgraph until now.

What Else Can You Do With Virtual Buffers?

Just about anything, actually. Anything you want to draw (sprites, shapes, fonts, image files, etc.) can be drawn in a virtual buffer. Any special effects can be applied to a virtual buffer. 3D scenes can be rendered into a virtual buffer. The virtual buffer is the cornerstone of Fastgraph programming.

What makes a Fastgraph virtual buffer better than a DirectDraw surface? Nothing. In fact, they are exactly the same thing in Fastgraph's DirectX libraries. The main difference is not what a virtual buffer consists of, but what you can put into it. That's the beauty of Fastgraph -- we give you tons of ways of writing information to a virtual buffer.

Compiling and Linking

Our most commonly asked technical support question is: "Why am I getting an unresolved external error message?". The answer is, you are not linking properly with the Fastgraph library.

Linking techniques are discussed in detail in the Fastgraph manuals, but I will give you the short story here. You need to tell your compiler (actually your linker) where to look for the Fastgraph functions. How you do that depends on the compiler. Here are some examples:

Visual C++ IDE

In the IDE, go to Project|Settings. Click on "Link". Type in this file name at the end of the list of libraries: fgwvc32.lib for Fastgraph without DirectX, or fgwvc32d.lib for Fastgraph with DirectX. If you have installed Fastgraph correctly, this library will be found in your compiler's library subdirectory. On my system it is c:\Program Files\Microsoft Visual Studio\Vc98\Lib.

Borland C++Builder

In the IDE, go to Project|Add to Project. Select "Files of type: Library file (*.lib)". Click through the directories until you find fgbc32.lib (or fgbc32d.lib if you are using Fastgraph with DirectX). On my system the Fastgraph libraries can be found in c:\Program Files\Borland\CBuilder5\Lib.

Borland Delphi

Add the Unit File Name to the program's uses statement. Fastgraph's unit files for Delphi are called FGWIN.DCU for Fastgraph without DirectX, and FGWIND.DCU for Fastgraph with DirectX. These files must reside in either Delphi's library directory, or in the same directory as your source code file.

Other Compilers

See the Fastgraph manual for details on linking with other compilers (including Basic compilers), or command-line linking. The important thing to remember is, your compiler will not link with Fastgraph unless you tell it to! You can also check your compiler's documentation for linking instructions.

Still Stuck?

For more information about getting started with Fastgraph, along with sample programs and a complete reference manual, see the Fastgraph help file. If you want to talk about developing programs with Fastgraph, join the email discussion list, or the check out our web bbs.