Code structure of a project

Source codes of an openFrameworks' project are placed in the project's src folder and consist of at least three files: main.cpp, testApp.h, and testApp.cpp.

Note

Remember the following convention: if some function or class name begins with of, it means that it belongs to openFrameworks. Examples are ofPoint, ofImage, and ofSetColor(). (If some name begins with ofx, it means that it is part of some openFrameworks addon, for example, ofxXmlSettings.)

main.cpp

In C++ language specification each project must have a .cpp file with the defined main() function. This function is an entry point for an operating system to start the application. In openFrameworks, the main() function is contained in the main.cpp file. The most important line of the function is the following:

ofSetupOpenGL( &window, 1024, 768, OF_WINDOW );

This ofSetupOpenGL() function calling instructs openFrameworks that you need to create a window for visual output with the width 1024 and height 768 pixels. The last parameter OF_WINDOW means that you need to create a window, which the user can move and resize on the desktop screen. If you specify the last parameters as OF_FULLSCREEN, the project will run at full screen—such a mode is important for many projects.

For example, if you need to show your project on the full screen with dimensions 1920 x 1024 pixels, you can do it by replacing the ofSetupOpenGL() call with the following line:

ofSetupOpenGL( &window, 1920, 1024, OF_FULLSCREEN );

Normally you need not change the main.cpp file at all, because the settings of screen size can be done in the testApp.cpp text, which we consider now.

Tip

Be careful! Inside the main() function most of the openFrameworks objects such as ofImage do not work properly, because paths and other variables are not set yet. So, indeed, in most cases you should keep main.cpp untouched and do all you need in testApp.cpp.

testApp.h

This file begins with #pragma once. This is a compiler directive, which should be present at the beginning of all the .h files. The next line is #include "ofMain.h". It includes openFrameworks' core classes and functions. After this, the code contains declaration of the testApp class, which is inherited from the openFrameworks' ofBaseApp class:

#pragma once

#include "ofMain.h"

class testApp : public ofBaseApp{
public:
  //openFrameworks' standard functions declarations
  void setup();
  void update();
  void draw();

  //...

  //Declarations of custom objects for the project
  ofEasyCam cam;      
  ofMesh mesh;
  ofImage img;
};

The testApp class contains a number of functions, setup(), update(), draw(), and some others. These are the functions required for your project to work. They are defined in the ofBaseApp class and called by openFrameworks. (The linking of the testApp class to the openFrameworks engine is done within the main() function. Its last line creates an object of this class and links it to the window, controlled by openFrameworks.) We will describe the meaning of the functions in the next section.

In the end of the class definition you will see declarations of the cam, mesh, and img objects. These are custom objects defined just in this example. In your own projects, you should add declarations of your objects here too.

Note

For simplicity you can declare objects right in the testApp.cpp file, but be careful, objects of some classes like ofEasyCam, ofThread, and ofxTCPServer will not work properly and can cause the application to crash if defined as static variables not belonging to the testApp class. The reason is that openFrameworks performs some actions before the testApp class' object is created, and such classes rely on this. Note that in some examples of the book we sometimes use such declarations for simple types (float, int, ofPoint, ofImage, and others).

Let's sum up: when creating your own project you should keep declarations of the setup(), update(), draw() functions, and others untouched, and also add your objects' and functions' declarations, which are needed for your project.

testApp.cpp

The testApp.cpp file contains definitions of all functions, declared in testApp.h. Let's explain the standard functions of the testApp class.

The most important functions are setup(), update(), and draw(). setup() is called first, and then update() and draw() are called in an infinite cycle, until the user presses the Esc key to close the project:

Note

Besides pressing Esc, to finish the projects' execution, the user can just close the projects' window.

If you need the project to terminate itself, call the OF_EXIT_APP( val ) function with some integer value val.

Let's consider these functions in detail.

setup()

The setup() function is called by openFrameworks just once, at the start of the project. This is the best place for setting screen parameters such as refresh rate, load images and videos, and start processes like camera grabbing.

The typical functions for controlling screen parameters are the following:

• ofSetFrameRate( rate ): This parameter sets the frame rate of screen refresh equal to the value rate of type int. Also, it controls the rate of calling update() and draw(). The typical value is 60, which corresponds to the frame rate of most TVs and projectors. The default value is zero, which means that the frame rate is as large as possible (in some cases it is unwanted).

• ofSetVerticalSync( v ): This parameter enables or disables synchronization of screen refresh with the video card's physical refresh, with v of type bool. Enabling this mode improves the quality of a fast-moving object's rendering, but slightly decreases the performance. By default the synchronization is enabled.

• ofSetFullscreen( v ): This parameter enables or disables full screen mode, with v of type bool.

• ofSetWindowShape( w, h ): This parameter sets the size of the output window so that the drawing area will have size width w and height h pixels.

Note that you can call these functions from other functions of the testApp class too.

update()

This function is called by openFrameworks right after the setup() call. This is the place where all computations should be performed, like changing positions of objects, analyzing data from cameras, and network exchange.

Tip

Also, drawing into offscreen buffers (FBOs) can be done here.

draw()

This function is called by openFrameworks after update(). All drawing functions should be placed here. After draw(), openFrameworks again calls update(), so we obtain a cycle of the update() and draw() methods.

The typical drawing functions are as follows:

• ofSetBackground( r, g, b ), where r, g, and b are integer values from 0 to 255, specifying red, green, and blue components of screen background

• ofSetColor( r, g, b ) sets the drawing color

• ofLine( x1, y1, x2, y2 ) draws a line segment connecting points (x1, y1) and (x2, y2)

Other functions

The testApp.cpp file contains definitions of other functions, declared in testApp.h. These are event-driven functions; openFrameworks calls them when some event occurs, like mouse moving or keyboard pressing. Some of the most important functions are the following:

• The keyPressed( key ) and keyReleased( key ) functions are called by openFrameworks when some key is pressed or released. Here key is an int value, which can be compared with char values like 'a', and with constants denoting special keys like OF_KEY_RETURN for the Return (Enter) key, OF_KEY_LEFT for the left cursor key, and so on. See the full list of special keys constants in the libs/openFrameworks/utils/ofConstants.h file.

• The mouseMoved( x, y ) function is called when the mouse is moved over the project's window without pressing any keys. Here x and y are the mouse pointer coordinates in pixels, with the center of the coordinates in the top-left corner of the window.

• The mouseReleased( x, y, button ), mouseDragged( x, y, button ), and mousePressed( x, y, button ) functions are called when a mouse button is pressed, when the mouse is moving, and when the mouse button is released, respectively. Here button equals to 0, 1, and 2 for left, center, and right mouse buttons respectively.

• The windowResized( w, h ) function is called when the size of the window is changed by the user or by calling the ofSetWindowShape() function. Here w and h are equal to the current width and height of the window.

Now we will discuss the ways for creating a new openFrameworks project.