Navigate to examples/graphicsExample and double-click on "graphicsExample.xcodeproj".

You should see a window that looks something like this:

You’ll notice a big "Run" button at the top left side of the screen. In XCode 3, it is called "Build & Run". That will run the currently active target. But you might find that, by default, the active target is the openFrameworks library, which, by itself, doesn’t do anything. What we want to run is "graphicsExample" program. So if you see this:

Click and drag down so that it looks like this:

Now click "Run!" You should see this:

The circle orange circle should constantly change its diameter, the rectangles should be drawn randomly, the upper red bar should fade and the lines should change smoothness. Press Escape or Apple Q to exit out of the program.

Now you should open and run all of the other examples.

Open Code::Blocks. The default screen should look like this:

Click on either "Open an existing project" or press Ctrl O to open a file browser. Now navigate to the openFrameworks example directory and into the graphics/graphicsExample folder. Make sure our view has "All files ." selected. Open the "graphicsExample.workspace" (not the graphicsExample.cbp, which is a Code::Blocks project).

The workspace is needed so that the compiler can find all relevant libraries. If the workspace is not loaded, the environment will lack crucial information for creating the final executable file. After the workspace is loaded successfully,

you can press the little gear button at the top or press Ctrl F9 to build (compile) the project. You can run the project by pressing the little green triangle button or press Ctrl F10. You can combine both steps later on by pressing F9. The result should look like this:

The circle orange circle should constantly change its diameter, the rectangles should be drawn randomly, the upper red bar should fade and the lines should change smoothness. Press Escape or Apple Q to exit out of the program.

You don’t actually need an IDE to build the oF examples since all tools necessary can be run from the command-line. To build an example open a terminal window and change to where you unpacked openFrameworks. From there change into a directory of the examples e.g. "graphicsExample":

Now run

to build and execute the code. In the end you should see the same with the methods pointed out above.

The circle orange circle should constantly change its diameter, the rectangles should be drawn randomly, the upper red bar should fade and the lines should change smoothness. You can close this example by pressing Escape or Apple Q. If you run

, everything you build will be removed and the directory will be cleaned out. This is useful when you make changes and ensure that an new build does not reuse any parts compiled previously.

So it’s finally time to start looking at some code. The first thing you need to do is open up a project in XCode. I’m going to assume that we are working with "myFirstProject" inside the workspace "myApps" from the last section. When you first open it up, take a look in the Navigator View (the panel on the far left of XCode) and click the disclosure triangle like this:

1. Click the disclosure triangle next to "MyFirstProject"

2. Click the disclosure triangle next to "src"

3. Click on testApp.cpp

testApp.cpp is going to become your very good friend over the next few tutorials. In the Editor Window, you should see something that starts like this:

So what is going on here?

In a lot of ways, testApp.cpp is like hello.cpp, the file that we wrote in the Introduction. It’s a plain text file that contains C source code. The difference now is that we are editing it through our IDE, so there is some really nice syntax highlighting that will hopefully make it easier to make sense of the code, and it will be a lot easier to compile and run when we want to.

On a very basic level, what you see here is a bunch of empty functions. A function is a set of instructions that make up part of a larger program. Just in the snippet of code above, there are 4 functions: setup, update, draw, and keyPressed. Each of the functions is followed by a set of curly brackets ({}). What usually goes inside of these curly brackets are the instructions (assigning values to variables, loops, and calls to other functions) that make up the functions.

If you refer back to the Q&A "What is a software framework?" in the introduction, the film production company analogy is particularly useful at this point. What you are looking at in testApp.cpp is how openFrameworks has provided all of the infrastructure and logistical details. Now it’s your job to define what happens. You do this by putting code into the functions in testApp.cpp

These functions will be called by openFrameworks at different points during the execution of your program. Let’s take a look at a few of them.

setup

This function is called (i.e.: any code that you’ve put inside the curly brackets runs) at the very beginning of the life of your application, before your program window opens. So, let’s say, for instance, you wanted to set the size of the window. You probably want this to happen before the window actually opens, so setup would be a good place for that.

update, draw

After the setup function runs, the update and draw functions begin a loop that continues until your program ends. So, after setup() runs, update() runs, then draw(), then update(), then draw(), etc. and by default, this happens as fast as your computer can handle. update() is typically used for updating the state of your program (i.e.: changing the value of variables), while draw() is used to actually draw things into your window.

keyPressed, keyReleased, mouseMoved, mouseDragged, mousePressed, mouseReleased, windowResized, gotMessage, dragEvent

Unlike the previous three functions, these functions are called only when a user does something. Can you guess what?

But enough with the reading. Let’s see these things in action.

We will start by drawing a simple circle in our gray window using the ofCircle function. Type ofCircle(200, 200, 60); on the blank line inside the draw() function so that your draw function look like this:

Now run your program. You should see something like:

Congratulations! You just made something appear on the screen! It’s all downhill from here.

But what did we just do?

ofCircle is a function that comes with openFrameworks (hence the of prefix). You can invoke the ofCircle function inside your draw function as many times as you’d like. The numbers inside of the parenthesis after ofCircle are called arguments. They determine exactly what the function does. They answer the questions: "okay, you want to draw a circle, but where? and how big?" Functions can take any number of arguments, always separated by commas, but ofCircle takes 3: an x coordinate, a y coordinate, and a radius. There are a few things you need to know to make sense of these arguments:

1. All measurements in openFrameworks are in pixels. By saying that our circle has a radius of 60, that means that it will take up PI*60² pixels total.

2. This may seem obvious, but the coordinates refer to the center of the circle. Other shapes (such as rectangles) use the upper left corner.

3. The "origin" of the coordinate system is in the upper left of the window. So, our circle appears 200 pixels from the left side of the screen, and 300 pixels from the top.

If you hadn’t just read about it here, you could have found information about ofCircle on the openFrameworks documentation page, which you will be using more as we move on.

Your circle is great, but kind of boring. What if we want to introduce some color to our application? To do that, we need the the ofSetColor function. Try adding ofSetColor(255, 0, 255); right above the ofCircle line, so that your draw function looks like this:

Now try running your application.

Similar to ofCircle, the ofSetColor function takes 3 arguments, but the numbers have very different meanings. If you look at the documentation for ofSetColor, you’ll notice that they arguments actually represent the red, green, and blue values for the color that you want to use, on a scale of 0-255. The red, green and blue make up the RGB color model or color space. So when we typed ofSetColor(255, 0, 255);, we were saying "until further notice, draw everything with 100% red, 0 green, and 100% blue."

This last point is important: when we call "ofSetColor", it’s like picking a crayon out of a box. Everything that gets drawn after that (below that line of code) will be drawn in that color until we call ofSetColor again. So if we want to draw another circle on the screen, we could simply call the ofCircle function again:

But if we wanted that circle to be a different color, we would have to call ofSetColor again:

Of course, oF can draw more than circles.

1. ofRect draws a rectangle. arguments are (x, y, width, height)

2. ofTriangle draws a triangle. arguments are the coordinates of the three points: (x1, y1, x2, y2, x3, y3)

3. ofLine draws a line. arguments are the start coordinate and the end coordinate (x1, y1, x2, y2)

4. ofEllipse arguments are: (x, y, width, height)

5. ofCurve Draws a curve from point (x1, y1) to point (x2, y2). The curve is shaped by the two control points (x0,y0) and (x3,y3).

Drawing static shapes is great, but what if we want our shapes to move around the screen?

We mentioned earlier that the draw() function is called repeatedly after the program is started. This is very important because it is how we achieve animation in openFrameworks. It might be a little unintuitive if you are used to Flash or even something like stop-frame animation, where you can add something to a "stage" and then re-position it as needed. This is not how openFrameworks (or most computer animation) works. Actually, openFrameworks is more like traditional (we’re talking old-school Disney/Bambi) animation, where we must redraw the frame completely every single "frame". In the parlance of openFrameworks, every time the draw() function is called is one "frame". So, in actuality, when you run the program above and see your purple circle, what you are actually looking at is the circle being drawn, then cleared (a single frame), and then drawn, then cleared, repeatedly. It’s just happening so fast that it appears to stay where it is.

In the example above, when we draw our circle, we use two numbers to tell the ofCircle function where to draw the circle within the window. So it follows that, if we want the circle to appear to move, we need to change these numbers over time. Perhaps the first time draw() happens, the circle is drawn at (200, 300), but in the next time, we want it to be one pixel to the right (201, 300), and then another pixel to the right (202, 300), and so on.

In C , and in programming in general, whenever you have a value that you want to change, you create a "variable". Variables come in different shapes and sizes depending on what they represent, such as decimal numbers, whole numbers, a letter, or a bunch of letters. In this case, we want to create variables that can stand in for coordinates in our ofCircle function, so we will use 2 ints.

Put this at the top of your testApp.cpp, right under the #include line, so that your file starts like this:

In those 2 new lines of code, we "declared" 2 new variables: one called myCircleX and one called myCircleY. You could actually name them whatever you want (within reason), but it’s a good idea to name them something that is related to how they will be used. We also said that these variables will be used to hold whole-number integer values, or ints. Declaring a variable is an important and necessary step. It’s like telling your application "okay, I’m going to need to store a number that might change."

The next thing we need to do is give those variables a starting value. We know that the endgame here is to have these variables change over time. But before we can change them, we need to give them an initial value. In other words, before our circle starts moving, where will it appear?

In a previous section, we learned that the setup() function gets called once when the application launches, and then never called again. This sounds like it could be useful for giving our variables some initial values. So in your setup() function, add the following lines.

Perfect! So, to recap, we now have 2 variables, myCircleX, and myCircleY, and we have just "initialized" them, or populated with an "initial" value. Notice that, just like any mathematical equation, we use the equals sign (=) to assign the number 300 to myCircleX. In C parlance, the equals sign is known as the "assignment operator", because it’s used to assign a value to a variable. The "assignment" always flows from right to left; that is, the value that is being assigned is on the right and thing that is receiving the assignment is on the left.

Now we can edit our ofCircle call a bit :

Notice that we are still passing 3 arguments to the ofCircle function. But now, instead of the old "hard-coded" (200, 300) values that we can’t change, we are letting the variables that we made stand in.

If you run your app now, you shouldn’t notice any change. That’s because we haven’t gotten around to changing the variables yet. So let’s do it.

Let’s edit our draw function a little so that it looks like this:

In this new line, we are using the "assignment operator" again, just like in the setup function. In English, that line would say "take the value of myCircleX plus one, and assign that to myCircleX". In other words, we are incrementing myCircleX by 1. C provides a shortcut for the common task of incrementing a variable: myCircleX ; This is extremely common, so let’s actually change our code to use this handy shortcut:

becomes

If you run your program now, you should see your circle move off the screen to the right! Animation!

There is just one thing we need to fix before moving on to more pressing aesthetic concerns. If you read back through the descriptions of what the update() and draw() functions are supposed to be used for, you’ll notice that the draw function is for drawing (so far, so good), but the update() function is where we are supposed to take care of updating variables. There are some very good reasons for this that we will get into later, but for now, let’s move the line we just wrote to the update function. So, your update and draw functions should look like this:

You shouldn’t notice any difference in terms of functionality, but it’s a good habit to get into.

One thing you may notice about your awesome moving circle is that it starts off kind of slow and then speeds away. This is actually caused by the framerate of your application, which is slow at first while the application fires up, but then gets super fast. As mentioned before, framerate refers to the rate at which the draw/update loop executes. Add this little line of code to the bottom of your draw() function to be able to see your framerate in the upper left corner of your window:

Most likely, it says something very close to 1000fps. That means that your circle is being drawn close to one thousand times per second. If you were to fire up tons of other applications on your computer and start rendering a huge video, you’d notice this framerate drops. The fact is that your application is simply trying to run as fast as it possibly can.

In the interest of having a smoother, more predictable kind of animation, we will lower the framerate to something more reasonable, like 60. In order to do this, we will put a new line into our setup() function.

Add that and then run your program. You will notice that the circle moves considerably slower. Using this function is not a guarantee of 60 frames per second, but it is a guarantee that your framerate won’t be any higher than that. And unless you have a really old computer, or your processor is already extremely taxed by some other program, it should have no problem running consistently at 60fps while doing something a simple as drawing a moving circle.

Let’s have one final adventure with our purple circle before saying goodbye. Our application is still a little disappointing because once our circle leaves the screen on the right, it’s gone forever. Let’s fix that problem by making the circle re-appear on the left side after leaving on the right: the Pacman Effect.

Before we write any code, let’s think about what this is going to mean in terms of the variables that we have. In the current state, we have myCircleX acting as the x coordinate for our circle, and it is being incrementing by 1 (or 4, if you followed the tip above) every frame. By default, an openFrameworks window is 1024x768. So, one way we could achieve the Pacman Effect is to reset myCircleX back to 300 once it goes beyond 1024.

How can we do this? We know that we are supposed to do any variable updating in the update() function, so let’s start there. We also know that we only want to reset myCircleX if it has gone above 1024. So for that, we use the if statement.

This code says:

• increment myCircleX by one.

• test if myCircleX is greater than 1024

• only if that test turns out to be true, set myCircleX back to 300;

The easiest way to quickly see how these functions work is to print a message to the console. Remember when we printed "Hello, World!" to the console in the introduction? We did that using a C thing called "cout" (pronounced c out). The syntax for using it is a bit weird because it’s not technically a function (it’s actually an object, which we will talk more about in later chapters), but if you can get beyond the syntax, it’s actually very useful for debugging.

But first: you may be asking yourself: how will we see text output? We are dealing with a GUI interface now. Luckily, XCode/Code::Blocks provides a window where we can see anything text that your program outputs (also known as stdout).

So start by going to View→Debug Area→Activate Console, or press apple shift C when using XCode. Code::Blocks automatically opens a console window when you press F9 (to build and run your program).

You should see a panel like this appear at the bottom of your XCode window

Excellent! Your output will appear in the pane on the right. Now we will add some code to our key functions that will print stuff to the console:

As I mentioned before, the syntax for cout is a little strange and, frankly, way beyond the scope of this chapter. In C parlance, cout represents the "standard output stream", and without worrying too much about what that means, "stream" is a nice way to think about it. If you look at the line of code within keyPressed, it appears that there is a "stream" of data flowing into the "cout". First we send in the string "keyPressed " down the stream, then we send in a variable: key. Finally, we send endl down the stream. endl simply tells the console to go to the next line.

The key variable represents the key that was pressed or released. More about this in a bit.

Let’s give it a try. Launch your program and type some keys. I will type "qwerty". You should see something like this in the console:

Don’t worry about the crap at the beginning — that’s added by the debugger.

The fact that the key is supplied as an int may seem a bit strange. Perhaps you were expecting a string or a char? In fact, what this number represents is the ASCII code for the key pressed. Check out this table:

On the right of each column in red, you will see a key on your keyboard. Under the corresponding "Dec" (decimal=base 10) column, you will see the number that you will receive in the key functions.

Fantastic. But presumably we want to do more with the key presses than print to the console. Let’s use the keys to move a ball around on the screen.

Start by adding two variables to your testApp and using them to draw a circle, just like we did in the Adding Movement section:

In the Adding Movement section, we used variables so that we could have the circle move by itself. The difference this time is that we want the ball to move in response to our keyboard input. This means that we need to modify the values of the variables depending on which keys are pressed rather than incrementing it automatically every frame. So it follows that we need to change the value of myCircleX and myCircleY in keyPressed() (or keyReleased() — it’s up to you!) instead of update().

Let’s use a typical computer game keyboard scheme: say we want the ball to move up when we press w, to the left when we press a, down when we press s, and right when we press d. We could start by looking up the ASCII values and finding that the values are 119, 97, 115, and 100, respectively. Next, we think about what "up", "down", "left" and "right" mean in terms of our variables: myCircleX and myCircleY. What we end up with is:

As we discovered, any time any key is pressed, the keyPressed() function is called. However, we want to be more selective than that. We want to be able to make certain things happen when the w key is pressed, and other things happen when the a key is pressed, etc. So, we need to add some if statements. When the keyPressed function is called, the first thing that happens is we test if key is equal to 119.

Notice the double equals sign. This signifies that we are performing a comparison rather than an assignment. In other words, we don’t want to assign the value 119 to the variable key, we want to test whether key is equal to 119. If this turns out to be true, then the code inside the curly brackets immediately following the if() is executed.

Your challenge is to complete the function to respond to the s and d keys.

mouseMoved: 627, 500
mouseMoved: 619, 500
mouseMoved: 610, 500

...

mouseMoved: 426, 473
mouseMoved: 426, 476
mouseMoved: 427, 478
mousePressed: 426, 478 button: 0
mouseDragged: 427, 477 button: 0

...

mouseDragged: 548, 411 button: 0
mouseDragged: 547, 411 button: 0
mouseDragged: 546, 411 button: 0
mouseReleased: 546, 411 button: 0
mouseMoved: 544, 411
mouseMoved: 543, 411
mousePressed: 543, 411 button: 0
mouseDragged: 542, 411 button: 0

...

mouseDragged: 433, 396 button: 0
mouseDragged: 433, 377 button: 0
mouseReleased: 433, 377 button: 0
mouseMoved: 434, 370
mouseMoved: 433, 367

So now we know how to make something happen when the user does any mouse business. But printing to the console is hardly the kind of interaction we want. When it comes to interacting with GUI applications, the mouse is used in a variety of ways: simple clicking, double-clicking, dragging, hovering, gestures, etc. One very basic interaction is "user clicks on something, something happens." Let’s see how we might accomplish this.

Suppose, for instance, that we wanted our trusty circle to expand whenever the user clicks on it. Let’s start by setting up a new project called MouseInteraction2. It will start out very similar to our MouseInteraction project:

As you can see, we have added a new variable called myCircleRadius. It should be clear that, if we want the circle to grow, all we have to do is increase myCircleRadius. The trick will be to determine when this should happen.

It’s clear that it has something to do with the mousePressed function that we just discovered above. We know that mousePressed is called every time the user clicks the mouse, so if we simply drop myCircleRadius ; into the mousePressed function, we would be half way there. Try this out.

You should find that the circle grows every time you click the mouse, regardless of whether or not your clicked inside the circle. But our challenge is to only grow the circle when the use clicks inside of it. So how might we go about this?

Well, luckily we are dealing with a circle, which will make it significantly easier. Because if we can determine the distance between the center of the circle and the location of the mouse click, we can compare this distance to the radius, and if it is less than the radius, then the click was inside the circle. Take a look at the diagrams:

We know that the radius of the circle = 300, and we know that the mouse click is 230 pixels away from the center of the circle. So, was the mouse click inside the circle?

In this case, we know that the mouse click was 90 pixels from the center of the circle, so the click was clearly inside the circle.

So how do we measure this distance? openFrameworks provides a function called ofDist([x1], [y1], [x2], [y2]) that will save us from doing any basic trigonometry. All we have to do is give it our two coordinates.

The cout will allow us to check what kind of values we are getting from ofDist. Run your program now. Click around the screen and see what kind of values get printed in your console.

So the only thing left to do is compare myCircleRadius to distance, and we can do this using a simple if statement.

This code says "first calculate the distance between the center of the circle and the mouse click. Then compare distance to myCircleRadius. If (and only if) distance is LESS THAN myCircleRadius, increment myCircleRadius by 1."

Et voila! You are interacting with graphics!

In the "Adding Movement" section, we introduced the idea of using variables to represent values that change over the course of your program. We used 2 integers, or *int*s - int myCircleX and int myCircleY - to represent the location of a circle. When you declare a variable as an int, you are telling the computer "I only intend to put whole numbers into this variable." This made sense in our example because we were moving a circle by a single pixel, so we didn’t need to worry about fractions.

But there will be times when you do need to have a variable that can hold a fraction, or something completely different, such as letters, words, even a location in memory. There are variable types for each of these situations. Here is a short list of some of them from cplusplus.com

So, as you can see, our basic integer takes up 4 bytes in memory. This is a finite amount of memory, and therefore there is limited (but pretty huge!) range of values that it can hold: namely, -2,147,483,648 to 2,147,483,647. If you need to store higher (or lower) numbers, you’d have to use a long int, which (contrary to the diagram) can go up to 9,223,372,036,854,775,807 and down to -9,223,372,036,854,775,808.

It may be unintuitive to make such distinctions when dealing with variables. A number is a number, right? Why differentiate between a decimal number and a whole number? The reason has to do with how values are stored in your computer’s memory. Ultimately, by giving the programmer the responsibility of declaring what range and precision their variables need, the program can run that much more efficiently.

There is one important kind of variable that is not covered in this chart: string. A string can hold a sequence of characters. …​ more to come …​

Loops are perhaps one of the most important things to be comfortable with as a programmer. They are, arguably, the main advantage of using a computer: doing something over and over again very rapidly is the definition of what a computer is good at. There are a few different kinds of loops, and it is important to be familiar with all of them.

Suppose you want to a circle every 20 pixels across your window. One option would be to copy and paste ofCircle commands like this:

That would be over 50 lines of code - ugh. And what if you decided you wanted them every 30 pixels instead of every 20 pixels? You’d have to go back and edit each line of code. And what if the size of your window changed? This is clearly unacceptable. Consider this code:

In some ways, this is even worse. We’ve turned one line of code per circle into 2 lines of code per circle. However, there is one very important difference: in this case, the 2 lines are identical every time. We have "abstracted" the task — that is, we have taken out the specifics and made it into a more general form.

So now, all that’s left to do is to tell the computer to do those 2 lines of code a bunch of times instead of us pasting it in ourselves. This is where loops come in.

Another strength of computers is that they are encyclopedic: that is, they can keep track of a huge number of things at a time. Suppose we want to draw six thousand moving particles? We know from the loop section that it is trivial to do something over and over again, but so far, we have only used loops to achieve a relatively consistent pattern. If we want do draw tons of particles, each with their own position, things get a little more complicated.

Technically this works, but we have only drawn 3 circles, and already the code is getting unwieldy. We want to draw 1000! We clearly have a bunch of variables that are used in very similar ways. Why not group, say, all of the x coordinates into a single set, and all of the y coordinates, etc.?

These sets are called arrays. Check out the following code:

As you can see, we’ve replaced int circle1x, int circle2x, and int circle3x with simply int circleX[3]. Now circleX is an "array" that can hold up to 3 integers, rather than just 1. Read a little further, and you will see that, in order to assign a value to one of the ints in the array, you use the square brackets, like this: circleX[0] = 50;

Down in the draw function, you can see that we use the same syntax to use the values that we have previously assigned to a particular slot in the array.

But this is still kind of a mess. One sign that you might not be utilizing loops as much as possible is if you see patterns in your code — that is, similar sequences of code over and over again. So let’s try to clean this up even more using some for loops.

Now, instead of putting hard-coded numbers between the square brackets, we use the i variable of our for loop.

In the examples above you had blocks of code enclosed in curly braces. To compose some more abstract functionality you also group instructions and call this group my a name. Look at the following example:

Here you see the definition of a function. A function is a named group of instruction which might take some input in the form of variables and might return some output. It might also be called a subroutine, depending on the context. Line 1 shows what is called the signature of a function. It first names the type of the data returned. Void means no data will be returned, int means a whole number gets returned, and so on. The return data type is followed by the name of the function ("drawStar") and finally a list of arguments. The list of arguments first states the data type (e.g. "int") and then a variable name (e.g. "xpos"). The argument variables are visible by their name inside the function body (aka. the curly braces), but not outside. The following code should make these concepts more clear.

The function "add2" takes an integer as an argument ("number") and adds two to it. This value gets returned by the "return" statement. A "void" function (usually) does not have a return statement. The variable "number" can be seen and accessed inside the "add2" function, but not the inside the "other" function. When calling the "add2" function, the value of "ivalue" (4) gets copied over into "number". Then "add2" is executed and the return value (4 2 = 6) calculated. This is then passed back add assigned to "ivalue".

There are other noteworthy things about the "drawStar" function. As you can see in the source, a function can have its own variables (like "useInner"), which only exist inside the function body. A function can call other functions, as demonstrated with "ofBeginShape()", "ofDegToRad()" and so on. The line 7 is an abbreviated if statement. A more recognizable way to write it is:

This abbreviated syntax might be useful if each alternative consists of only one statement to be executed, but is also easy to overlook when trying to find bugs (programming errors) in a program. The more verbose version is easier to spot and understand. It also is easier to extend if needed.

All the concepts introduced should give you the basic tools to study and understand the example code provided. We covered a lot of ground, so go and poke at the other examples!