Introduction to oF, C++ and Xcode

This post is meant to provide instructions on getting started with oF, particularly with Xcode. It also provides an introduction to C++ to those coming from other programming languages (particularly Java/Processing and JavaScript).

The Mac environment and Xcode will mainly be used for the Multimedia Authoring course at Media Lab Helsinki (that this tutorial is meant to support). Participants on this course are required to have previous programming experience, such Java or ActionScript by participating on the Software Studies course. The Programming Interactivity book (Noble 2009), adopted for the course, was used as the main reference for this post.

About setting up openFrameworks (oF) with Xcode

• You can download openFrameworks from this website: http://www.openframeworks.cc/download
• Store it somewhere in your hard drive, probably in the Documents folder
  Try opening and running one of the included oF examples. Examples are located within the “app” folder. Within each example folder is the Xcode project file “openFrameworks.xcodeproj”. Open it with Xcode. Press “Build and Run” (Xcode 3) or “Run” (Xcode 4).
• You can terminate any running Xcode app by pressing “Esc”
• More detailed instructions can be found here:
  http://www.openframeworks.cc/setup/xcode

Getting started with C++

Moving on from Processing and JavaScript, which you have learnt on the Software Studies course), emphasizing the differences regarding languages such as Java and JavaScript:

• File structure:
  In C++, classes are saved in two file types: .cpp (as in “C Plus Plus”) and .h (“Header”).
  .h files contain import statements, the name of the class, extensions to the class, declarations of variables and methods.
  .cpp files contain the definitions of the variables and the methods.
• Public and private properties:
  A class has two basic kinds of properties – public and private. “Public ones are available to the outside world, which means that other classes can use those properties and methods. Private properties are not available to the outside world, only to methods and variables that are inside the class” (Noble 2009, p. 133)
  Example:
  class Parrot{
public:
//all public properties...
private:
//all private properties...
}

• Inheritance:
  “Inheritance means that a class you’re making extends another class, getting all of its variables and methods that have been marked public” (Noble 2009, p. 135)
  Example:
  class Parrot : public Bird{
• Initial statements in .h and .cpp
  The .h file starts with the #ifndef statement. This statement “tells the compiler that if it hasn’t defined something called” [the class name] “then it should go ahead and compile everything in here” (Noble 2009, p. 142). If it has, it doesn’t need to be compiled again, saving time [updated 11/2011: this is now achieved with the “#pragma once” command].
  Example for MyClass.h:
  #ifndef _MY_CLASS
#define _MY_CLASS
class MyClass{
...
#endif 
• The .cpp file starts by importing the header file:
  #include "MyClass.h"
• main() and Main.cpp
  “There is a rule in C++ that says you must have one file that has a method called main(). When your application is launched, this is the method that will be called, so it’s where all your initialization code goes. In an oF application, this is just creating an instance of your application and running it” (Noble 2009, p. 143)
• Pointers and references
  “The reference (…) is the location in memory where a variable is stored. Any variable’s address can be accessed using the reference operator (&).” Pointers “point at locations in memory” (Noble 2009, p. 146), for example: float * pointerToFloat. This is only needed when you go deeper into openFrameworks and C++.
• Main variable types
  bool (boolean), int (integer), long (for large integer values), float (floating-point), char (character), string (strings of characters)
• Methods (and static methods)
  Methods are defined taking into account its return type. For example:
  String myMethod(myParameter){
  A static method is “available without being called on an object” (Noble 2009, p. 158).
  For example: MyClass::myMethod(); instead of myObject.myMethod();. In the class definition, myMethod would be defined as this: static int myMethod();. The static keyword “marks it as being accessed from anywhere by using the name of the class, followed by two colons” (Noble 2009, p. 159).
• Debugging with printf statement
  printf can be used anywhere in the code by passing into it the variable name to find out the value of that variable at that point in time. It can take an unlimited number of parameters. It uses place holders such as %i for the values of variables.
  For example: printf("user name is: %s", user.username);.
  printf flags:
  c – character;
  d or i – signed decimal integer
  f – decimal floating point
  g – use the shorter of %e or %f
  s – string of characters
  u – unsigned decimal integer
  x – unsigned hexadecimal integer
  p – pointer address (Noble 2009, p. 185)

oF or Processing?

Joshua Noble (2009, p. 153) draws an interesting comparison between oF and Processing.

• Make a project visible on the Internet
  Use Processing(.js), this is much trickier to do with oF.
• Make a project that renders a lot of 3D graphics
  Use oF; this is where C++ really shines.
• Make a project that can run on many different computers without a lot of configuration
  Use Processing; this is rather tricky to do with oF.
• Make a project that uses a computer vision library liken OpenCV
  Use oF, Processing doesn’t communicate with a C++ library like OpenCV as easily as oF.
• Make a project that interfaces with the Arduino Controller
  Use either

In the openFrameworks wiki, there is an interesting post on oF for Processing users:
http://wiki.openframeworks.cc/index.php?title=OF_for_Processing_users

Getting started with oF

The oF installation contains the folders addons, apps and libs:

• addons – contributions from the oF community, covering many different topics; new additions coming up regularly
• apps – where your programs should be stored, and where examples can be found
• libs – where the main libraries of oF are stored, the core openFrameworks folder is also here
• openFrameworks – contains the core of oF, within the following folders: app, communication (useful for Arduino), events, graphics, sound, utils (math, time, core data types), video;
• ofBaseApp – “the app folder contains the header file for the ofBaseApp class which is the base program class of any oF program”, it “lets you easily toggle between full-screen and window views, set up code to handle mouse movements and keyboard presses, and integrate the simplified drawing routines with the graphics environment of your operating system” (Noble 2009, p. 161).
• xcode templates – Within the openFrameworks installation, you will also get Xcode templates for openFrameworks (currently not working with Xcode 4); installation varies depending on version, as Xcode library has been changing place; lately: Developer > Library > Xcode

“Your application” (testApp.h, testApp.cpp with main.cpp) “sits atop the openFrameworks libraries, which sit atop a series of third-party libraries” (such as openGL, GLUT, rtaudio…) (Noble 2009, p. 162).

Introduction to an oF application

Methods in the ofBaseApp class that appear in a default oF file:

• setup() – this method is called when the program first starts up, as in Processing; you should put here something that has to run only once or at the beginning; also if you are initializing variables.
• update() – it is called just before the draw() method; “you generally ant to put any data processing you need to do in the update() method so that you’re drawing with new data” (Noble 2009, p. 166).
• draw() – called when the program draws its graphics; “you should have drawing code only in your draw() method to keep your program running smoothly” (Noble 2009, p. 167).
• key, mouse and window methods – add code to handle these type of events to these methods.

References: Noble, J., 2009, Programming Interactivity, O’Reilly