CCGLTouch: iOS wrapper for Cinder

There is a brand new, dedicated home for this wrapper: cocoacid.org/ios. This page here stays for the sake of SEO and social networking, but it's not maintained any more, please browse to the new page!

This wrapper eases the use of Cinder within a typical Cocoa project. Thus allowing C++/Obj-C creative coders to build iOS (iPhone, iPad) apps showing several "Cinder sketches" in tabs or SplitView configurations, and using UISlider's, UISwitch's, etc. to control them.

Latest update: 10/09/2012
Latest features added:
BSD License: it is now BSD Licensed, to make things easier if you're willing to make commercial stuff with it
Cinder 0.84: support for the latest stable release
OpenGL multi-threading: support was added for OpenGL's sharegroups, that allow parallel OpenGL threads to draw to the same scene
Anti-aliasing: you can now set an option at setup to use Apple's brew of Multi-Sample Anti-Aliasing (MSAA) rendering for OpenGL
Saving to photo album: added an OpenGL frame capture method to the CCGLTouchCore classes to allow saving to the iDevice's photo album
Video capture example: also added an example that does "video capture" of the OpenGL frames, straight to your photo album if you will
Using photos from album & camera as OpenGL textures: and an example showing how to use pictures from the iDevice's photo album, or directly from the camera within the app (launched as a modal view)

Launching an example project

Download the CCGLTouch examples package. Unzip the file and place the "CCGLTouch" you obtain inside of your Cinder folder, at the same level as the "samples", "blocks", "lib"... Within CCGLTouchBasic, open CCGLTouchBasic.xcodeproj and run it in the iPhone Simulator or on a device: the project should build and the CCGLTouchBasic app should launch. A colorful cube should rotate and look somewhat similar to the third iPhone sim pic above.

If the project build failed, then the linking is probably not right. That's probably because the CCGLTouch folder you've just unzipped is not placed at the root of your Cinder folder. If you keep experiencing problems with linking, check the User-defined build settings of the project and change the CINDER_PATH value until it all connects properly. Please report any other issue in the comments section below!

Using the templates

These XCode templates provide starting points for "CCGLTouch flavored" applications. The basic template features a colored cube and a UISlider to control the size of the cube. Download them here.

To install the templates, first navigate to XCode within the Applications folder on your Mac, right-click on it and select Show Package Contents from the context menu. Then take a deep breath, and place the templates' *.xctemplate folders inside of /Contents/Developer/Platforms/iPhoneOS.platform/Developer/Library/Xcode/ Templates/Project Templates/Application, besides "Cocoa Touch Application.xctemplate", "Cocoa Touch Familied Application.xctemplate", etc.

Then launch XCode, create a new project and select the template of your choice from the iOS > Application menu displayed in the dialog box.

Make sure to save the project inside of a folder placed at the root of your Cinder folder, besides the "samples", "lib", "boost" folders. Typically a folder named "CCGLTouch" where all the examples sit... If you decide to do otherwise, you'll have to change the User-Defined CINDER_PATH setting of the project's target to comply with the relative location of the project you've just created.

A brief note about which files are there, why they're there, and what you can do with them

First, unfold all the groups in the project's hierarchy in order to get something similar to the image on the left.

In order to use the Cinder framework within a typical XCode project, it is necessary to go around the application building process that magically happens when rendering a Cinder project. This is what MyAppDelegate and the ViewController(s) are here for. The AppDelegate generates a view that is of MyCCGLView class type, and is controlled by the MyViewController.

The MyCCGLView class may bear any name you like. That is where you're going to write what's being drawn in the view. But it must inherit from the CCGLTouchView class whose .h and .mm you will find under the "CCGLTouchCore" group. Everything in that CCGLTouchCore group should remain intact unless you want to implement new functions, or tweak the defaults... at your convenience.

Finally the MyViewController class, whose .h and .mm you will find in the MyClasses group, is the place where all the Interface Builder buttons, sliders, etc. that you've added in the MyViewController.xib are being connected to the MyCinderGLView that you're controlling with them. Obviously, when using several CCGLTouchView's in the same project, all of these assets (MyCCGLView.h, MyViewController.h, MyViewController.xib) are multiplied by as many views as you'll want to use. For a simple example, check out the "CCGLTouchTabs" sample included in the package.

What examples are there ?

Apart from the CCGLTouchBasic example described up there, 8 other projects are available in the example package:

  • CCGLTouchMayaCam is equivalent to CCGLTouchBasic, except for its single-touch controlled camera.
  • CCGLTouchTabs features 2 independent CCGLTouchView's, each being shipped with their own UISlider.
  • For CCGLTouchAccelerometer, you'll have to connect a device, either iPhone or iPad, if you want to be able to test the accelerometer functionnality. This example relates heavily on the iPhoneAccelerometer sample that ships with Cinder.
  • CCGLTouchMultitouch is a CocoaTouch-revamped edition of Cinder's MultiTouchBasic. It features a UISwitch that lets the user turn on/off the yellow circle located under the fingers.
  • CCGLTouchSplitView is an iPad specific example, that illustrates of the SplitView on that platform, bearing a UITableView as the "root view", that has influence over the "detail view" (in our case, the place where Cinder does its magic).
  • CCGLTouchFrameCapture shows how to use the CCGLTouchCore-included method for capturing the current OpenGL frame and saving it to the photo album right away
  • CCGLTouchFrames2Video provides a method and all the necessary Framework includes for saving the OpenGL's scene to a video on the iDevice (typically within the photo album)
  • CCGLTouchPhotoPicker shows how to use pictures coming from the device's photo album or directly from the photo camera (hence launching & using it first within the CCGLTouch app)