Mastering openFrameworks: Creative Coding Demystified

openFrameworks has the following architectural specifics:

Such specifics determine cases when you should and should not use openFrameworks for a project development.

You definitely can employ openFrameworks when:

Maybe you should not use openFrameworks when:

Within Windows 7 and 8 there are two choices of programming environments: Microsoft Visual Studio and Code::Blocks. Microsoft Visual Studio is one of the most popular environments in the world. It is very mature and stable. Many libraries (included and not included in openFrameworks) are adopted for Visual Studio. So if you are a novice in C++ programming, but you know that you need to link additional libraries in your project, Visual Studio is the best option for you.

Code::Blocks is a more lightweight environment and some developers prefer to use it. If you are a novice and just want to play with openFrameworks in simple projects, you should probably to do it with Code::Blocks.

This folder contains simple examples covering almost all the aspects of openFrameworks, sorted by the following topics:

Though most of the topics will be covered in this book, we highly recommend that you run and see as many examples of the code as you can. It is very helpful for dipping into the openFrameworks world.

This is a folder, in which all your projects should live. More specifically, you should place the projects inside some subfolder of the apps folder. By now this folder contains the myApps folder, and you can use it for your projects. Also you can create new folders, like Performances2014, and place corresponding projects there.

Note, if you will try to compile a project placed outside a subfolder of the apps folder, the compiler can give an error that it can not find the openFrameworks library.

This folder contains addons. These are the extensions of the basic openFrameworks capabilities. When you need to add some extension to openFrameworks, you will install it into this folder. We discuss the addons in detail in Appendix A, Working with Addons.

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.

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.

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.

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:

Let's consider these functions in detail.

The easiest way to start your own project is to just copy some existing examples (or your own project) into the apps/myApps folder, or any other subfolder of the apps folder. Then rename the folder as you want (for example, to myInteractiveWall), and open the project using your developing environment. Now you can change the code, and run the project.

This way, almost all the examples in the book are made from the emptyExample project, located in the examples/empty folder.

Such an approach is indeed very easy. Also, it is especially useful for working with some complicated addons such as ofxOpenNI (see Chapter 10, Using Depth Cameras, for more information on this addon). Namely, you can have difficulties with linking such addons by yourself or with projectGenerator. In this case, just start your project from the existing working addon's example.

You can create a new project using the Project Generator wizard, located in the projectGenerator folder. It lets you specify the project's name, its folder, and the list of addons needed in the project.

Such a way is simple too, and it is especially useful when you start a new project, which needs to use many addons. Manual linking of addons can take much time, and Project Generator does it automatically for you. For further details see the Using Project Generator section in Appendix A, Working with Addons.

In our opinion, using Project Generator just for creating projects with proper names is not so important, because you can rename the project by yourself using the development environment. So, we use this wizard just for linking addons to new projects.

Now we are ready to create our first project with openFrameworks.