ARToolKit tutorial 1: First simple ARToolKit scene

Introduction

To demonstrate in detail how to develop an application, we will step through the source code for an existing example program: simpleLite. The source code for this program is found inside your ARToolKit installation in the directory examples/simpleLite/.

simpleLite screenshot

The file we will be looking at is simpleLite.c. This program simply consists of a main routine and several graphics drawing routines.

The functions which correspond to the six application steps previously described are shown in Table 1. The functions corresponding to steps 2 through 5 are called within the Idle() function.

The most important functions in the program related to AR are main, setupCamera, setupMarker, mainLoop, Display, and cleanup. In the remainder of this section we will explain the key pieces of code in these functions.

We will not cover every piece of code in simpleLite.c, but it is well commented and you should refer to the full code listing while following the text below.

One final piece of explanation before we begin.. in simpleLite, we use just one other libraruy, GLUT, to handle the interaction with the operating system. We use GLUT, the OpenGL utility toolkit, to do things like open a window, and handle keypresses. However, GLUT is not required, and can be replaced with any library you like, e.g. MFC on Windows, Cocoa on Mac OS X, or QT (cross platform). It is highly recommended that you become familiar with the basics of a GLUT-based OpenGL application before studying the code of simpleLite.c. The most effective way to do this is to read chapter 1 of the OpenGL Programming Guide, also known as the "Red Book". In particular, the hello.c sample code given in chapter 1 of the Red Book is the basis for the simpleLite.c code.

http://www.opengl.org/documentation/red_book/

main

The main routine of simpleLite performs a number of setup tasks for the applicaton. We will step through its code explaining the AR-specific functionality. The code in main() plus two setup functions called by main corresponds to step 1 in the table above.

The first piece of AR specific code is near the top of main, where we declare some variables that will be used to set up the application:

              char *cparam_name = "Data/camera_para.dat";

              char *vconf = "";

              char *patt_name  = "Data/patt.hiro";

In this block, we define the pathname of the camera parameter file the application will use (see Calibrating your camera), the video capture library configuration string (see Configuring video capture in ARToolKit Professional), and the name of the marker pattern file the application will load and try to recognise.

Next, we see the first AR-specific function call:

              // ----------------------------------------------------------------------------

              // Hardware setup.

              //

              if (!setupCamera(cparam_name, vconf, gARTThreshhold, &gARTCparam, &gARHandle, &gAR3DHandle)) {

                            fprintf(stderr, "main(): Unable to set up AR camera.\n");

                            exit(-1);

              }

<c>

setupCamera loads a file containing calibration parameters for a camera, opens a connection to the camera, sets some defaults (the binarization threshhold in this case) and starts grabbing frames. It records its settings into 3 variables which are passed in as parameters. In our case, we will store these parameters in global variables. setupCamera is explained more fully below.

The next piece of code opens up a window for us to draw into. This code uses GLUT to open the window. Later, we will install some event handlers for the window, to handle redrawing, resizing etc.

<c>

              // ----------------------------------------------------------------------------

              // Library setup.

              //

              // Set up GL context(s) for OpenGL to draw into.

              glutInitDisplayMode(GLUT_DOUBLE | GLUT_RGBA | GLUT_DEPTH);

              if (!prefWindowed) {

                            if (prefRefresh) sprintf(glutGamemode, "%ix%i:%...