Your first project

In this tutorial we will set up a basic application that creates a blank window and terminates when the close button of the window is pressed. This can be considered the minimal application for using Pascal3D. It is assumed that you have basic knowledge of Lazarus and Free Pascal.

Preparing the project and main unit

As a base we create a new empty project by clicking File->New->Simple Program. We then add a new unit to the program and add the following units to the uses clause of the main unit. We don't necessarily need an extra unit but it facilates clarity of the code.

Hint

Don't forget to add the pascal3d package to the dependencies of your project in the Lazarus project inspector.

unit MainUnit;

{$mode objfpc}{$H+}

interface

uses
  Classes,
  SysUtils,

  p3d.events,
  p3d.core;

...

Next we need to define our application class. We therefore inherit our class from TP3DApplication. For now it is just the empty class but in another step we are going to change this.

...
type

  { TMyApplication }

  TMyApplication = class ( TP3DApplication )
  end;


var
  MyApplication: TMyApplication = nil;
...

In our main program we create our instance of our defined application. It will also set the global variable P3DApplication in p3d.events that is used by the p3d units. In the loaded units are some other global variables that need to be initialized before you can use them. This is automatically done when creating the application, so this should usually be the first step. With a call of Run we enter the main loop that is executed until a quit event is triggered by the user or the OS. Finally after the application has terminated we are freeing it. If we execute the program now it starts up and quickly terminates. That is because we do not have a main window.

program CreateWindow;

uses
  MainUnit,
  SysUtils;

begin
  MyApplication:= TMyApplication.Create();
  MyApplication.Run;
  FreeAndNil( MyApplication );
end.

Creating the window

So before running the app we need to create a main window. This can be done by the following line. The MyApplication.Windows parameter determines the owner of the Window. This owner will automatically free the window when the application object is destroyed. MyApplication.Windows should hold all windows used in our application. It is possible to have more than one window. The main window is the first window created and if that is set to nil (e.g. because it is destroyed) the application will exit the main loop.

TP3DWindow.Create( MyApplication.Windows );

For the sake of cleanliness of the code we put this in a separate init procedure and not in the main program. TP3DApplication provides various hooks for interaction with the application (e.g. initialization, finalization, input). For that purpose we override the Initialize method in our application class. This is where all the steps necessary to prepare the application before running it should go (eg. creation of a window or loading of assets). We do not need to call this function manually because it is automatically called after creating the application.

We can change the title and the resolution of the window as shown in the code below. It is also possible to switch to full screen mode.

unit MainUnit;

{$mode objfpc}{$H+}

interface

uses
  Classes,
  SysUtils,

  p3d.events,
  p3d.core;

type

  { TMyApplication }

  TMyApplication = class ( TP3DApplication )
    public
      procedure Initialize; override; // Override the Initialize procedure
                                      // for initialization of your window
                                      // and all your assets
  end;


var
  MyApplication: TMyApplication = nil;

implementation

{ TMyApplication }

procedure TMyApplication.Initialize;
begin
  inherited Initialize;
  TP3DWindow.Create( Windows ); // Create the main window. Note that
                                // this is freed automatically when
                                // the application terminates
  MainWindow.Title:= 'My first Pascal3D application'; // Set the title
  MainWindow.Width:= 800; // Set the resolution
  MainWindow.Height:= 600;
  // Uncomment if you want full screen mode
  // Exit the application with Alt + F4 / Command + Q
  //MainWindow.FullScreen:= True;
end;

end.

Now if we run the code only a blank window is shown. If it is closed the application terminates. In the next tutorials we are going to extend this.