Merge branch 'master' of https://github.com/openframeworks/ofBook

.gitignore

@@ -6,3 +6,18 @@ ofBook.pdf
 
 web/_site
 *.orig
+
+.DS_Store
+.AppleDouble
+.LSOverride
+
+# Icon must ends with two \r.
+Icon
+
+
+# Thumbnails
+._*
+
+# Files that might appear on external disk
+.Spotlight-V100
+.Trashes

01_intro/chapter.md

@@ -55,9 +55,114 @@ We try to organize and support the community developing addons through the http:
 The driving philosophy behind openFrameworks is "do it with others" (DIWO). We love do it yourself (DIY) culture, which has been heavily promoted and facilitated by the rise of tutorial website like Instructables or Make. But we're also excited about the idea of "making socially" ("with others"). We practice DIWO through workshops, developer conferences, hackathons/labs, knitting circles and meetups in person, and online in the form of mailing lists, forum posts, and so on. We even have a gang sign. Because if you have a gang, you have to have a gang sign. The most important thing we want to stress is that you are not alone, that there's a great group of people out there learning, teaching, hacking, making and exploring the creative side of code.
 
 ## OF structure
+
+The most important thing to understand about OF is that is that it has been designed to be a self contained structure.  You download OF from the website, and that version of OF can go anywhere on your hard drive.   You shouldn't mix different versions of OF and while older project might work in newer versions of OF, that's not always a gaurentee, especially if there's been a major release. 
+
+Because OF can go anywhere on your hard drive, all the internal links are relative.  A project file, for example, looks to `../../../libs` rather then a fixed path like `C:Documents and Settings\OF` (on windows) or `/Users/name/Desktop/OF` (on linux / osx).  This means that you have to be extra special extremely careful about the depth that a project is away from the root of the OF folder.  This is one of the most common mistakes beginners make, they have a project that they either move to shallow or too deeply, or they find other peoples code but don't put it in the right spot.  I simply can't stress this point enough: project files have relative paths.  It's sweet, because it means you can share projects easily (it doesn't have a fixed path with your name on it, for example) and you can move the whole OF folder around, but it still trips many beginners up.  
+
+
+
+**[NOTE: I think below here belongs in Roy's chapter.... this chapter is more historical and conceptual, these are more practical]**
+
+
+
 ## project generator
+
+OF now ships with a simple project generator which is really useful for making new projects.  One of the larger challenges has always been making a new project and this tool takes a template and modifies it, chaning the name to a new name that you choose and even allowing you to add addons, additional libraries that come with OF or that you can download.  It allows you to pick where you want the project to go, and while we've structured all the examples to be a certain distance away from the root, you can change the height using this tool.  It's designed to make it easy / trivial to start sketching in code, without worrying too much about making a new project.  In the past we've always recommend that you copy an old project and rename it, but this is a more civilized approach to making projects. 
+
+
 ## .h and .cpp
+
+In OF (which is C++) you'll see .cpp and .h files (they are sometimes labeled as cxx or hpp files, respectively).  The h files are the header files and cpp files are the implementation files.  Header files are definitions -- they show what's going to be in the code and implementation files are the actual steps.  One anology is like a book, the header file is like the the table of contents of the book and describes the layout of the book and the implementation files are like the chapters, where the book is written.  Another analogy is a recipe, where you have the list of ingedients (header files) and the actual steps (implementation files).   It's useful to know about this split as a lot of modern languages don't have this split.  
+
+**MORE**
+
 ## setup/update/draw
-## first project a circle moving in the screen
-## scary things in OF code (#ifdefs pragma once...)
+
+OF runs in a kind of game loop model - where we get you a context to draw into and try to run as fast as we can and repetedly draw.  There are 3 main functions that you'll see a majority of the code in (as well as the event functions like mousePressed, keyPressed, etc) 
+
+* setup()
+* update()
+* draw()
+
+Setup gets called once, at the first moment we have a window context and it's a good place for initializing variables and loading in files.   Update and draw get called repeatedly.  Update is for doing non visual changes, such as altering variables or performing analysis, draw is where we do any drawing.   The order they get called in is: 
+
+setup->update->draw->update->draw->.....
+
+Folks coming from processing, where there is just setup() and draw() often times wonder why we have two functions that repeat instead of one.  There's a couple of reasons: 
+
+* Drawing in opengl is asynchronous, meaing after you fire off a bunch of commands to draw, they can be running in the background and return control back to your app.  If you seperate out your drawing code from your non drawing code there's a potential your code will be faster.
+* it's useful for debugging.  If you want to know why your code is running slow, now you can comment out the drawing and see if the visual representation that's slow or the updating. 
+
 ## preprocessor/compiler/linker
+
+When you write code, your end goal is a compiled application - an .exe or .app that you can click on an run.  The job of the compiler is to make that executable for you, to turn text into compiled binary files. It's a 3 step process, and it's useful to know what's happening, especially since you can have errors at different steps along the way.  Most IDEs output out a very length file of the compiling, and this can be really useful if you are posting to the forums, for example.  Once you understand the process of how projects come to be, it can be easier to isolate errors.  Nothing is as frustrating or daunting as looking at 500+ errors in a project when you go to compile, but when you notice that there's a missing include, it's clear why and usually one thing will fix many of the problems. 
+
+### preprocess
+
+The first step is that a preprocessor modifies the text files themselves.  When you see the # symbol, that's a preprocessor operation.  The most common preprocessor statement you'll see is: 
+
+`#include "xxxxx.h"`
+
+which actually means, take the content of this file and put it right here.  **[NOTE: more on "" vs <> ]**  You'll also see things like: 
+
+`#define PI 3.1428`
+
+This means, when you see the word PI in the code, change it to this variable.  This isn't a variable, this is literally modifying text. 
+
+Another common preprocessor step is asking a question. you can say things like: 
+
+	#ifdef windows
+		#include "windows.h"
+	#else
+	 	#include "nonWindows.h"
+	#endif
+
+As you can imagine this is increadibly useful for cross platform compilcation.  If you want to see preprocessor craziness, look at ofConstants.h. 
+
+One common error you'll have in the preprocess phase is a file not found error, if you include a file like
+
+	#include "opencv.h"
+
+and it can't find the file, you will get an error at the preprocessing stage. The way to fix this is to add header search paths, basically the places (folders) the IDE goes to look for a file.  This is a common error when using a new library and one of the things the project generator is deisgned to help with when adding an addon. 
+
+**[more on ofMain.h]**
+
+### compile
+
+Once the text has been modified, the job of the compiler is simply to take .cpp files and turn them into object code.  It's taking the text and turning it into machine language instructions (also referred to as assembly).  It doesn't touch the h files at all, it only thinks about .cpp files.  In the previous phase the .cpp file has all the h files it uses added to it recursively. 
+
+This recursive h inclusion  is one reason while you will see include guards on the top of h files.  They will either look like:
+
+	#ifndef SOMEWORD
+	#define SOMEWORD
+	...
+	#endif
+
+or the more modern 
+
+	#pragma once
+
+This is because if a file is included twice into a .cpp file the compiler could be confused.  If it's sees the same definition twice, like: 
+
+	float position;
+	float position;
+
+it will not know which one is which.  The include guard prevents the file from being included twice. 
+
+there are plenty of errors that can happen at compile time -- using a variable that you haven't defined for example.  The compiler will stop when it hits an error and the IDEs are designed to make it easy for you to see where the errors are and fix them.  
+
+The compilers job in life is to take the .cpp files and turn them into .o files.  These are individual object files that it will compbine in the next phase, linking. 
+
+### link
+
+Finally, after we have a bunch of object files, our job is to link them into one thing -- in our case an application (alternatively, compilers can compile code into a library, for example).  This is what the linker does.  As you can imagine, there are jumps from one thing to another.  For example, in ofApp you could call a graphics call from ofGraphics: 
+
+	void ofApp::draw(){
+		ofCircle(100,100,20);
+	}
+
+This code is calling a function in another object.  The linker figures out the links from object to object (in this case between ofApp.o and ofGraphics.o) and links them together into one file. 
+
+In addition to header search paths, there are also setting in the IDE for dealing with linker paths and libraries to link against.  A common error you might see is a link error, where the code in your project compiles fine, but it's having trouble linking because some object is missing.  For example, if you forget to include a .cpp file from the source code, the other code will comiple fine, but when the linker goes to make that jump, it can't find where to jump to.  Linker errors are described as "undefined reference" errors and occur at the end of the compile process. 
+