First: Delphi

Delphi programs consist of a project source code (dpr) file, one or more source code unit (pas) files, and other files that you probably won't edit directly. The project source contains the main program, which is created automatically and usually does nothing more than call the application's CreateForm() and Run() methods. Unit source code files contain the program's functions, procedures, and event handlers. Delphi's visual environment and class library handle many of the traditional Windows programming details such as setting up the window class, the window procedure, and the message loop.

Here is the Delphi project source code file for our first example program:

{*****************************************************************************
*                                                                            *
*  First.dpr                                                                 *
*  FirstU.pas                                                                *
*                                                                            *
*  This is the first Fastgraph for Windows example program. It demonstrates  *
*  tasks common to most Fastgraph for Windows programs and serves as a       *
*  template for building the other examples.                                 *
*                                                                            *
*****************************************************************************}
program First;
uses
  Forms,
  FirstU in 'FirstU.pas' {Form1};
{$R *.RES}
begin
  Application.CreateForm(TForm1, Form1);
  Application.Run;
end.

Note how the project file's uses statement references the FirstU unit source code file, which is shown here:

{*****************************************************************************
*                                                                            *
*  First.dpr                                                                 *
*  FirstU.pas                                                                *
*                                                                            *
*  This is the first Fastgraph for Windows example program. It demonstrates  *
*  tasks common to most Fastgraph for Windows programs and serves as a       *
*  template for building the other examples.                                 *
*                                                                            *
*****************************************************************************}
unit FirstU;
interface
uses
  SysUtils, WinTypes, WinProcs, Messages, Classes, Graphics, Controls,
  Forms, Dialogs, FGWin;
type
  TForm1 = class(TForm)
    procedure AppOnActivate(Sender: TObject);
    procedure FormActivate(Sender: TObject);
    procedure FormCreate(Sender: TObject);
    procedure FormPaint(Sender: TObject);
    procedure FormResize(Sender: TObject);
    procedure FormDestroy(Sender: TObject);
  end;
var
  Form1: TForm1;
implementation
{$R *.DFM}
var
  dc : hDC;
  hPal : hPalette;
  hVB : integer;
  cxClient, cyClient : integer;
procedure TForm1.AppOnActivate(Sender: TObject);
begin
  fg_realize(hPal);
  Invalidate;
end;
procedure TForm1.FormActivate(Sender: TObject);
begin
  fg_realize(hPal);
end;
procedure TForm1.FormCreate(Sender: TObject);
begin
  dc := GetDC(Form1.Handle);
  fg_setdc(dc);
  hPal := fg_defpal;
  fg_realize(hPal);
  fg_vbinit;
  hVB := fg_vballoc(640,480);
  fg_vbopen(hVB);
  fg_vbcolors;
  fg_setcolor(19);
  fg_fillpage;
  Application.OnActivate := AppOnActivate;
end;
procedure TForm1.FormPaint(Sender: TObject);
begin
  fg_vbscale(0,fg_getmaxx,0,fg_getmaxy,0,cxClient-1,0,cyClient-1);
end;
procedure TForm1.FormResize(Sender: TObject);
begin
  cxClient := ClientWidth;
  cyClient := ClientHeight;
  Invalidate;
end;
procedure TForm1.FormDestroy(Sender: TObject);
begin
  fg_vbclose;
  fg_vbfree(hVB);
  fg_vbfin;
  DeleteObject(hPal);
  ReleaseDC(Form1.Handle,dc);
end;
end.

First, let's look at the unit file's uses statement. The Delphi IDE automatically provides the names of the first nine units (SysUtils, WinTypes, and so forth). We added the FGWin unit file name to this list. If we wanted to use Fastgraph's DirectX unit file, we would specify FGWinD instead of FGWin in the uses statement.

The FirstU unit is essentially made up of event-handling procedures that provide our first look at some Fastgraph functions. Note that our program does not explicitly call the event procedures. Instead, they are called by Delphi's class library in response to Windows events such as creating or resizing the window (these procedures are analogous to the traditional WindowProc() message handlers). Our program includes event handlers for the form's OnCreate, OnPaint, OnResize, and OnDestroy events, and for the application's OnActivate event. You can use Delphi's Object Inspector to generate code templates for the form event handlers, but you must manually add the code and declarations for application event handlers.

An OnCreate event occurs when the form is first created during program execution. This event occurs once per program instance and is analogous to the WM_CREATE Windows message. Hence, it is a good place for any application-specific initialization code. Our OnCreate handler is in the FormCreate() procedure and first calls the Windows API function GetDC() to obtain a device context to the form's client area. It then calls fg_setdc() to make the device context available to other Fastgraph functions:

dc := GetDC(Form1.Handle);
fg_setdc(dc);

Next, it creates and realizes the default logical palette:

hPal := fg_defpal;
fg_realize(hPal);

The OnCreate handler then initializes Fastgraph's virtual buffer environment, creates a 640x480 virtual buffer and makes it the active virtual buffer, and assigns the logical palette colors to the virtual buffer:

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

Next, we fill the virtual buffer with blue pixels (color 19 is blue when using Fastgraph's default 256-color virtual buffers with the default logical palette):

fg_setcolor(19);
fg_fillpage;

The last thing the OnCreate event handler does is set up the pointer to the application's OnActivate handler:

Application.OnActivate := AppOnActivate;

The application's OnActivate handler (which has a different purpose than the form's OnActivate handler) executes when the program gains the input focus. This happens when control shifts from another Windows application to our program, so it is thus analogous to the WM_SETFOCUS Windows message. Our OnActivate handler is in the AppOnActivate() procedure and first calls fg_realize() to activate the program's logical palette (in case another program has changed the logical palette colors). It then calls Delphi's Invalidate() function to force an OnPaint event to redraw the form's client area. This sequence is typical of OnActivate event handlers in Fastgraph programs.

An OnPaint event occurs when the form's client area must be repainted; it is analogous to the WM_PAINT Windows message. Our OnPaint handler is in the FormPaint() procedure and just calls fg_vbscale() to display the contents of the 640x480 virtual buffer scaled to the size of the form's client area. This sequence is typical of OnPaint event handlers in Fastgraph programs.

You can remove the OnActivate event handler by calling fg_realize() before fg_vbscale() in the OnPaint handler. While this eliminates the work of manually creating an application event handler, it introduces overhead in OnPaint because it must realize the logical palette every time the form is repainted. This wouldn't be noticeable in a simple program like our first example. However, in games or other applications where we frequently update the form (and hence frequently execute the OnPaint handler), we recommend using a separate OnActivate handler that realizes the logical palette only when needed.

An OnResize event occurs whenever the size of the form changes, and also upon creation of a form. It is analogous to the WM_SIZE Windows message. Our OnResize handler is in the FormResize() procedure and simply saves the new width and height of the client area (in pixels) in the variables cxClient and cyClient. These quantities are passed to fg_vbscale() in the OnPaint event handler.

An OnDestroy event occurs after removing a form and often signals a program exit; it is analogous to the WM_DESTROY Windows message. Our OnDestroy handler is in the FormDestroy() procedure and first closes the virtual buffer, releases its memory, and terminates virtual buffer processing:

fg_vbclose;
fg_vbfree(hVB);
fg_vbfin;

It then calls two Windows API functions to delete the logical palette created with fg_defpal() and release the device context created with GetDC():

DeleteObject(hPal);
ReleaseDC(Form1.Handle,dc);

Each Delphi example supplied with Fastgraph consists of six files comprising a Delphi project. The unit source code (pas) and graphical form (dfm) files will have the same name as the Fastgraph example, but with the letter "U" appended to the file name. For example, the six files for the First example project are:

In general, we'll only be working with the unit source code file for each project, as it contains the event handling procedures. We'll let Delphi's visual programming environment handle the maintenance of the other files. For more information about these files, please consult your Delphi manuals.