ofxAppUtils

OpenFrameworks app utilities

Copyright (c) Dan Wilcox 2011-2013

BSD Simplified License.

For information on usage and redistribution, and for a DISCLAIMER OF ALL WARRANTIES, see the file, "LICENSE.txt," in this distribution.

See Documentation on Github and the OpenFrameworks Forum post.

OpenFrameworks is a cross platform open source toolkit for creative coding in C++.

http://www.openframeworks.cc/

Description

ofxAppUtils is a set of utilities for OpenFrameworks application development including:

• ofxApp: an ofBaseApp/ofxiPhoneApp extension with built in screen scaling, projection mapping transforms, quad warping, and an optional ofxControlPanel
• ofxScene: a mini ofBaseApp/ofxiPhoneApp for writing stand alone scenes
• ofxSceneManager: handles a list of scenes using a std::map
• ofxTransformer: open gl transformer for origin translation, screen scaling, mirroring, and quad warping
• ofxQuadWarper: an open gl matrix quad warper (useful for oblique projection mapping)
• ofxTimer: a simple millis-based timer
• ofxParticle: a simple time-based particle base class
• ofxParticleSystem: an auto manager for ofxParticles
• ofxBitmapString: a stream interface for ofDrawBitmapString

All ofBaseApp & ofxiOSApp callbacks are handled down to the scene level.

Installation

To use ofxAppUtils, first you need to download and install Open Frameworks. ofxAppUtils is currently developed against the latest stable version of Open Frameworks on github.

To get a copy of the repository you can download the source from http://github.com/danomatika/ofxAppUtils/zipball/master or, alternatively, you can use git clone:

git clone git://github.com/danomatika/ofxAppUtils.git

The addon should sit in openFrameworks/addons/ofxAppUtils/.

Dependencies

You will may also need the following addon dependencies:

• ofxXmlSettings: included with OpenFrameworks (optional)
• ofxControlPanel: https://github.com/kylemcdonald/ofxControlPanel (optional, also requires ofxXmlSettings)

To enable the control panel (and ofxControlPanel dependency), define OFX_APP_UTILS_USE_CONTROL_PANEL in your CFLAGS.

To disable the xml transform load/save (and ofxXmlSettings dependency), define OFX_APP_UTILS_NO_XML in your CFLAGS.

For Xcode, see the example project Project.xcconfig files on how to set the defines.

Running the Example Project

The example projects are in the appUtilsExample & appUtilsIOSExample folders.

OSX

Open the Xcode project, select the appUtilsExample-Debug scheme, and hit "Run".

Linux

Open the Code::Blocks .cbp and hit F9 to build. Optionally, you can build the example with the Makefile.

To build and run it on the terminal:

make
make run

Windows

An example Visual Studio solution as well as a Codeblocks workspace are included.

Adding ofxAppUtils to an Existing Project

Note: These instructions are for manually adding ofxAppUtils to an existing project. You do not need to follow these steps if you use the ProjecGenerator app, except for adding the OFX_APP_UTILS defines.

If you want to add ofxAppUtils to another project, you need to make sure you include the src folders:

openFrameworks/addons/ofxAppUtils/src

Xcode

• create a new group "ofxAppUtils"
• drag these directories from ofxAppUtils into this new group: ofxAppUtils/src
• you also need to add the following addon dependencies (if you're using them) in a similar manner:
  • ofxControlPanel
  • ofxXmlSettings
• make sure to remove any of the example folders in the Xcode project tree for any of the addons you've added manually
• add defines to the project C++FLAGS if you want to disable the control panel and/or xml saving:
  • Select the Project -> Build Settings -> Other C++ Flags
  • add the following to enable the control panel:

    -DOFX_APP_UTILS_USE_CONTROL_PANEL
    

  • add the following to disable transform xml saving:

    -DOFX_APP_UTILS_NO_XML
    

On iOS you will probably don't want to enable the control panel via the OFX_APP_UTILS_USE_CONTROL_PANEL define as it doesn't really work with touch screens.

For Linux (Makefiles & Codeblocks):

• edit addons.make in your project folder and add the following line to the end of the file:

  ofxAppUtils

• edit config.make in your project folder and update the USER_CFLAGS line:
  • if you want to enable the control panel:

    USER_CFLAGS = -DOFX_APP_UTILS_USE_CONTROL_PANEL
    

  • if you want to disable the transform xml saving:

    USER_CFLAGS = -DOFX_APP_UTILS_NO_XML
    

For Codeblocks (Win):

• add the ofxAppUtils sources to the project:
  • right-click on your project in the project tree
  • select "Add Files Recursively ..."
  • navigate and choose the ofxAppUtils/src folder
• add defines, search paths, and libraries to link:
  • right-click on your project in the project tree
  • select "Build options..."
  • make sure the project name is selected in the tree (not release or debug)
  • select the "Compiler settings" tab
    • add the following to the "#defines" tab if you want to enable the control panel:

    OFX_APP_UTILS_USE_CONTROL_PANEL
    

  • add the following to the "#defines" tab if you want to disable the transform xml saving:

    OFX_APP_UTILS_NO_XML
    

  • select the "Search directories" tab, click add the search paths:

    ..\\..\\..\addons\ofxAppUtils\src
    

For Visual Studio:

• drag the ofxApputils/src folder onto the project tree
• right click on the project in the project tree and select Properties
• set the Configuration to All Configurations
• add the defines and searhc paths:
  • add the following to Configuration Properties->C/C++->Preprocessor->Preprocessor Definitions:
    • enable the control panel:

    OFX_APP_UTILS_USE_CONTROL_PANEL
    

    • disable the transform xml saving:

    OFX_APP_UTILS_NO_XML
    

  • add to the search paths in Configuration Properties->C/C++->General->Additonal INclude DIrectories:

  ..\\..\\..\\addons\ofxAppUtils\src
  

Extending Your BaseApp

There are two changes you need to make to extend your app with the ofApputils ofxApp class which handles all the automagic:

• your base app needs to inherit from ofxApp in your testApp.h

class testApp : public ofBaseApp { 
// becomes
class testApp : public ofxApp { 

• you need to run your app with the app utils in main.cpp

ofRunApp(new testApp());
// becomes
ofRunAppWithAppUtils(new testApp());

That's it. Check the example testApp::setup() for more info on startup settings.

Note: this is completely optional. You can always handle the transforms etc yourself using an ofxTransformer instance, etc.

ofxGetAppPtr

Internally, calling ofRunAppWithAppUtils actually creates a wrapper ofBaseApp which then runs the given ofxApp. As a result, calling ofGetAppPtr() does not work correctly as it returns a pointer to the wrapper and not the app itself.

In order to fix this, there is a new function added with ofxAppUtils called ofxGetAppPtr() (note the "x") which returns the correct pointer. If you are porting existing code, make sure to change any ofGetAppPtr() calls to ofxGetAppPtr().

DEVELOPING

You can help develop ofxAppUtils on GitHub: https://github.com/danomatika/ofxAppUtils

Create an account, clone or fork the repo, then request a push/merge.

If you find any bugs or suggestions please log them to GitHub as well.