openFrameworks app utilities
Copyright (c) Dan Wilcox 2011-2023
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++.
This project has been supported by the CMU Frank-Ratchey STUDIO for Creative Inquiry and the DU Emergent Digital Practices Program.
ofxAppUtils is a set of utilities for openFrameworks application development including:
- ofxApp: an ofBaseApp/ofxiPhoneApp extension with optional screen scaling transformer & scene manager
- 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
- ofxMovingAverage: a simple linear moving average
- 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.
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/.
The master branch of ofxAppUtils will work with the current stable version of openFrameworks and can be considered relatively stable.
Previous versions are tagged using Semantic Versioning with the updates to newer versions of openFrameworks noted in the changelog, CHANGES.txt. You can select the tag in the Github "Current Branch" menu or clone and check it out using git.
If you want to use ofxAppUtils with a previous version of openFrameworks, checkout the corresponding version tag after cloning:
git clone git://github.com/danomatika/ofxAppUtils.git
cd ofxAppUtils
git checkout 0.5.0
You may also need the following addon dependencies:
- ofxGui: included with openFrameworks
To enable the ofxGui transformer panel, include ofxTransformerPanel.h, create an "ofxTransformerPanel" object, and set the transformer in ofxTransformerPanel::setup().
The example projects are in the appUtilsExample & appUtilsIOSExample folders.
Project files for the examples are not included so you will need to generate the project files for your operating system and development environment using the OF ProjectGenerator which is included with the openFrameworks distribution.
To (re)generate project files for an existing project:
- Click the "Import" button in the ProjectGenerator
- Navigate to the project's parent folder ie. "ofxAppUtils", select the base folder for the example project ie. "appUtilsExample", and click the Open button
- Click the "Update" button
If everything went Ok, you should now be able to open the generated project and build/run the example.
Open the Xcode project, select the appUtilsExample-Debug scheme, and hit "Run".
Open the QT Creator project file and/or build the example with the Makefile.
To build and run via Makefile on the terminal:
make
make run
Open the Visual Studio project, build and run.
Select ofxAppUtils and other addons used by your project from the available addons in the ProjectGenerator, select the parent folder of your project, and set the exact name of the existing project in the text box. This will overwrite the existing project files with new ones that now include ofxAppUtils.
Note: you will lose any custom settings you've added manually to your 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
- 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:
- ofxGui
- Make sure to remove any of the example folders in the Xcode project tree for any of the addons you've added manually
Edit addons.make in your project folder and add the following line to the end of the file:
ofxAppUtils
- 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 search paths:
- add to the search paths in Configuration Properties->C/C++->General->Additonal Include Directories:
..\\..\\..\\addons\ofxAppUtils\src
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 ofApp.h
class ofApp : public ofBaseApp {
// becomes
class ofApp : public ofxApp {
- You need to run your app with the app utils in main.cpp
ofRunApp(new ofApp());
// becomes
ofRunAppWithAppUtils(new ofApp());
That's it. Check the example ofApp::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.
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().
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.