Matchbook Example "Game", 2x iOS and 2x Android clients

Matchbook is a lightweight and platform-agnostic matchmaking solution, intended for use in mobile applications (think games that require near-real-time, relatively-low-latency, persistent communications between two or more client devices).

At its core is a server component, which provides a JSON-based webservice allowing clients to find, create, and join matches. The server also acts as a proxy/relay when necessary, allowing client devices to tunnel through any firewalls that might exist between them.

In addition to the server component, Matchbook includes prebuilt SDK’s for both Java and Objective-C. These SDK’s are intended to support the development of native applications that make use of the Matchbook webservice on Android and iOS devices, respectively.

I could go on at length, but it’s simpler to just link to the project on Github (Matchbook is open-source, and permissively licensed, naturally):

https://github.com/adam-roth/matchbook

Note that Google is currently building comparable functionality into Google Play, although their realtime communications API is currently only available on Android (iOS support is under development).

And although Apple already has realtime and turn-based gaming API’s for iOS, they natually have no intention of inviting Android devices to the party. Ever.

So let the record show that Matchbook got there first.

Personally I’ve never been entirely happy with the implementation provided by Apple, and in particular their decision to build their API around NSData instead of NSString. Granted there’s probably a reason why Apple chose to go that route, and also a reason why they didn’t bother to provide convenience methods that allow people to work with whichever type they prefer. But as far as I’m concerned, JSON is a textual/non-binary data format, so therefore the natural iOS data structure to use for outputting and inputting JSON data is an NSString. Using NSData instead is counter-intuitive, and clunky as a result.

So because of that clunkiness, I’ve stuck with the tried and true SBJson library, even though the author of that library himself recommends just using Apple’s implementation. This preference is largely based around the very helpful (and also very deprecated) ‘NSObject+SBJson‘ category that is included in the library. This category imbues objects with a couple of very convenient methods:

- (NSString*)JSONRepresentation;
- (id)JSONValue;

These methods can be used to turn an appropriate object (i.e. an NSArray or an NSDictionary) into a JSON string, and to turn a JSON string back into a proper object, respectively. No parameters, no options, no boxing to or unboxing from NSData; just a simple API that is basically just ‘[thing turnIntoJson];‘ and ‘[json turnBackIntoThing];‘. It doesn’t get much more convenient than that.

And that was all well and good, until I wanted to build a framework which internally used SBJson, and then use that framework within a project that also needs to make its own use of SBJson. Linker hell was the result. And long story short, I decided that it would be faster to build a shim around Apple’s JSON API to preserve the convenience I’m after than it would be to appease the linker gods.

So in case anyone else has been avoiding Apple’s JSON implementation because it’s too clunky to work with (or too painful to migrate away from SBJson), here’s my 5-minute shim:

NSObject+SimpleJson.h

#import <Foundation/Foundation.h>

@interface NSObject (SimpleJson)

- (NSString *)JSONRepresentation;  //turns an object into a JSON string
- (id)JSONValue;                           //turns a JSON string back into an object

@end

NSObject+SimpleJson.m

#import "NSObject+SimpleJson.h"

@implementation NSObject (SimpleJson)

- (NSString*)JSONRepresentation {
    //write ourself to a JSON string; only works if we're a type that 'NSJSONSerialization' supports
    NSError* error = nil;
    NSData* tempData = [NSJSONSerialization dataWithJSONObject:self options:kNilOptions error:&error];
    if (error) {
        return nil;
    }
    
    return [[NSString alloc] initWithData:tempData encoding:NSUTF8StringEncoding];
}


- (id) JSONValue {
    //converts from a string back into a proper object; only works if we're an NSString or NSData instance
    if (! [self isKindOfClass:[NSString class]] && ! [self isKindOfClass:[NSData class]]) {
        return nil;
    }
    
    NSData* jsonData = nil;
    if ([self isKindOfClass:[NSData class]]) {
        jsonData = (NSData*)self;
    }
    else {
        //we must be an NSString
        jsonData = [((NSString*)self) dataUsingEncoding:NSUTF8StringEncoding];
    }
    
    return [NSJSONSerialization JSONObjectWithData:jsonData options:kNilOptions error:nil];
}

@end

If you have code that uses SBJson’s ‘NSObject+SBJson‘ category, the above category should be drop-in compatible. And just as importantly (in my case) does not invoke linker hell when used as part of an iOS framework.

Note that the above code assumes you are using ARC. If not, you’ll want to add an ‘autorelease‘ call in there.

window.pointsAround = function(centerLat, centerLng, radius, numInterpolations) {
    var result = [];

    //do annoying trig maths to work out the delta in latitude between our start and end points
    var targetD = radius;          //km
    var fractionalDistance = (targetD / radiusOfEarth) / 2;
    var sqrtA = Math.sin(fractionalDistance);
    var a = sqrtA * sqrtA;
    var sinHalfDLat = Math.sqrt(a);
    var dLat = Math.asin(sinHalfDLat) * 2;
    var dLatDegrees = degrees(dLat);
    
    var minLat = centerLat - dLatDegrees;              //furthest valid latitude above the origin
    var maxLat = centerLat + dLatDegrees;            //furthest valid latitude below the origin
    
    var centerLatRadians = radians(centerLat); 
    
    //topmost and bottommost points in the circle
    result.push({lat: minLat, lng: centerLng});
    result.push({lat: maxLat, lng: centerLng});
    
    //step from minLat to maxLat, interpolating coordinates that lie upon the circle
    numInterpolations = numInterpolations ? numInterpolations : 360;
    var step = (maxLat - minLat) / (numInterpolations / 2.0);
    for (var count = 0; count < (numInterpolations / 2) - 1; count++) {
        minLat += step;
        var minLatRadians = radians(minLat);
        dLat = radians(centerLat - minLat);
        
        //more annoying trig to work out the delta in longitude for our interpolated coordinate
        var dLon = 2 * Math.asin(Math.sqrt((a - (Math.sin(dLat/2) * Math.sin(dLat/2))) / (Math.cos(minLatRadians) * Math.cos(centerLatRadians))));
        var dLonDegrees = degrees(dLon);
        
        var newLng = centerLng + dLonDegrees;
        var deltaLng = newLng - centerLng;
        result.push({lat: minLat, lng: newLng});
        result.push({lat: minLat, lng: centerLng - deltaLng});
    }
    
    return result;
};

This code works out the northernmost and southernmost points that are the specified distance away from the given centerpoint. It then steps between the minimum and maximum latitude of these two points, interpolating the appropriate longitudinal value(s) to satisfy the equidistant constraint. The total number of coordinates returned can be controlled using the optional ‘numInterpolations‘ parameter. When not specified a total of 360 points will be returned by default, because that is a nice, round number.

If you use something like the following code to plot some points on a map:

window.map = new GMap2(document.getElementById("mapDiv"));
    var centerPoint = new GLatLng(37.4419, -122.1419);
    map.setCenter(centerPoint, 8);
    map.addControl(new GLargeMapControl3D());
    map.addControl(new GMapTypeControl());
    
    var marker = new GMarker(centerPoint);
    var markerText = "Center @ 37.4419, -122.1419";
    GEvent.addListener(marker, "click", markerClickHandler(marker, markerText));
    map.addOverlay(marker);
    
    var points = pointsAround(37.4419, -122.1419, 50);
    for (var index = 0; index < points.length; index++) {
        var point = points[index];
        var latlng = new GLatLng(point.lat, point.lng);
        marker = new GMarker(latlng);
        markerText = "Marker @ " + point.lat + ", " + point.lng;
        GEvent.addListener(marker, "click", markerClickHandler(marker, markerText));
        map.addOverlay(marker);
    }

…you will get a nice circle of points around the hard-coded centerpoint. You can see a working example of this here: http://jsfiddle.net/HmchC/27/.

Previously if you wanted a free/open-source crash reporting framework for iOS your options were basically limited to QuincyKit, which is a serviceable but basic solution. Sadly, the backing architecture used by the QuincyKit server is not well designed and scales very poorly with the number of crash reports in the system. Once you have around 5,000 you’ll notice the server slowing down significantly, and go much beyond 10,000 that and the system grinds to an unusable halt. With a day or so of database and code refactoring, these scalability issues can be resolved, creating a system performant enough to track millions of error logs or more. But that’s a subject for another time. The point for today is that despite its basic level of functionality and flawed server architecture, there are a few key areas in which QuincyKit blows the default implementation of Jira Mobile Connect out of the water:

1. Automatic grouping of crash reports.
2. Automatic symbolication of error logs.

If you have any experience whatsoever with supporting multiple high-volume iOS applications you will instantly realize that these are features that you want. They might even be features that you want more than annotated screenshots, audio feedback, user chat, or seamless integration with Jira and all the awesomeness that Jira brings. In short, Jira Mobile Connect’s lack of support for these two key features may cause serious developers to pass it over in favor of other solutions.

Without grouping every single crash will be creating a new ticket in Jira that you need to track and resolve. Multiple instances of the same crash will have to be manually flagged as duplicates within Jira. And without symbolication trying to actually map back from an error log to the line of code that caused it is an exercise in futility, or at best, tedium.

In any case, rather than abandon the excellent potential shown by Jira Mobile Connect I decided that instead I would attempt to patch it up and add the missing features myself. It’s all open-source code, after-all, and if the tangled mess of PHP that is QuincyKit server can provide these features then they can’t be that difficult to implement. Unfortunately I had to change too many files in too many different places to show the code here, but if you want the short version of it I was able to implement both grouping and symbolication, and you’re welcome to view the complete diffs on bitbucket:

https://bitbucket.org/aroth_iapps/jiraconnect-ios-iapps/compare/..atlassian/jiraconnect-ios (client/native iOS code)
https://bitbucket.org/aroth_iapps/jiraconnect-jiraplugin-iapps/compare/..atlassian/jiraconnect-jiraplugin (server/Java code)

One interesting side-effect of adding groups was that it became possible for multiple client UID’s to be associated with a single Jira ticket. This had an important implication for feedback notifications/chat in that the reference implementation allowed only a single UID to be associated with each Jira ticket. Since the UID is used for determining what notifications/updates to send to the native client, this restricted update notifications to a single user per ticket. Not too useful if you have a common crash that thousands of users have experienced. The implementation above extends the data model to allow multiple UID’s to be stored against a single Jira ticket, allowing each UID to be updated when new feedback is posted by the developer on a ticket. In essence, implementing grouping also required the implementation of group feedback/chat.

There is one caveat with my server implementation, in that it assumes the existence of the ‘symbolicatecrash‘ utility on the system’s runtime PATH. This means that it will only work if your Jira server is hosted on a Mac, with the proper XCode developer tools installed (and with your application’s .app and .dSYM files copied to the local filesystem). This is of course a requirement regardless if you want automatic symbolication to work on any sort of system; somewhere there needs to be a Mac with ‘symbolicatecrash‘ available. In any case, it is a fairly simple matter to either turn this off or otherwise make it more intelligent, if your Jira server is incapable of running ‘symbolicatecrash‘.

Also note that the native iOS code has been restructured to build a universal iOS framework as opposed to an architecture-specific static library. This is done using Karl Stenerud’s excellent XCode4 Project Template. You will need to install this template in order to actually build the modified code. Or you can just refactor it back to build a static library again, but why would you want to do that?

When using the iOS framework, be aware that you will need to set the ‘-all_load‘ linker flag and also include all the images and nibs in the framework’s ‘/Resources‘ folder as part of your build. You will probably also want to include the ‘JMCLocalizable.strings‘ file in the same folder as well, to provide proper text and labels on Jira Mobile Connect’s UI elements.

Regardless, if you do a lot of iOS development and are already using Jira (like you should be) then I encourage you to check this out. This is the Jira Mobile Connect plugin, now with automatic grouping and error log symbolication.

Well Wikipedia doesn’t provide this information directly, but interestingly enough Wikipedia does in fact keep all the historical data necessary to answer this question. Thanks to Chrome’s awesome JavaScript console (and the fact that Wikipedia uses jQuery on all of its pages) it is a very simple matter to extract this historical information in a format that is easy to work with later. The following code will do the trick:

var result = []; 
jQuery.each($(".filehistory a[href$=5day.gif]"), function(){
    result.push(this.href)
}); 
result;

This simply constructs an array containing the URL’s of every historical forecast/storm track graphic (ordered by date from newest to oldest) and outputs it to the console. We can then copy/paste the console output to wherever we like, such as jsFiddle for instance. Combine this with some basic HTML structure:

<div class="title">
    Hurricane Irene Animated Forecast Map
</div>
<img id="display" src="http://fcf.teambeachbody.com/fcf/images/spinner5.gif" />
<div id="status">
    (<span id="numLoaded"></span> of <span id="total"></span> frames loaded)
</div>

…and some simple JavaScript to handle the actual rendering:

document.getElementById("numLoaded").innerHTML = "0";
document.getElementById("total").innerHTML = data.length;

//preload all the images so that they are cached for the animation
window.imagesLoaded = 0;
for (var index = data.length - 1; index >= 0; index--) {
    var node = document.createElement("img");
    node.style.display = "none";
    document.body.appendChild(node);
    $(node).bind('load', function() {  
        window.imagesLoaded++;  
    });
    $(node).attr('src', data[index]);
    //node.src = data[index];
}

//run the animation
window.currentImage = data.length - 1;
window.updateAnimation = function() {
    if (window.imagesLoaded < data.length) {
        //keep waiting
        document.getElementById("numLoaded").innerHTML = window.imagesLoaded;
        return;
    }
    $("#status").hide();
    document.getElementById("display").src = data[currentImage];
    currentImage--;
    if (currentImage < 0) {
        currentImage = data.length - 1;
    }
};

setInterval(updateAnimation, 200);

…and you get an animated map of the entire forecast history, including the actual storm track. The result looks something like this:

Not too bad for a few dozen lines of code and about 30 minutes worth of effort. You can also access a full-scale, editable version of this animated storm history here.

So what does this say about the accuracy of the hurricane forecasting for Irene? Personally I think it shows that the forecasts are pretty damn accurate. In fact, if you focus just on the solid white portion of the predicted storm track it appears that the storm never deviates from its forecast path. It’s only when looking at the dashed white portion of the forecast that any significant deviation can be noted. And the dashed white portion indicates forecasts that are more than 72 hours in the future.

Of course we should always be working to improve our ability to predict and forecast these things, but I have to think that being able to accurately predict a storm’s movement for up to 72 hours into the future is adequate for most purposes.

But sadly, Prototype decided to use ‘$()‘ as the name of their alias. And even worse, other frameworks have followed in this pattern, adding their own dollar functions that have semantics that can be completely different from the original ‘$()‘ introduced by Prototype. Consider jQuery, which introduces its own version of ‘$()‘ which can be used to find (and wrap and clone) elements in the DOM by a number of different criteria, but which sadly fails miserably when given a string containing a literal element id. This creates a lovely situation where now the developer cannot even guess at what ‘$()‘ is actually doing without first checking to see which framework is being used by the code. It also means that any code that was written using Prototype’s ‘$()‘ will be broken by including jQuery (and vice-versa).

“But that’s what ‘jQuery.noConflict()‘ is for”, you say. But you miss the point. It shouldn’t be necessary for ‘jQuery.noConflict()‘ to exist in the first place. If the jQuery developers hadn’t decided that it would be cute to define their own version of ‘$()‘, then jQuery would never conflict with anything except possibly an older version of jQuery. The thing that really baffles me is how so many developers (obviously talented developers, at that, considering the work that goes into something like Prototype or jQuery) can all decide that it is a good idea to try to lay claim to a name that exists in the global scope. Granted JavaScript does not have any concept of a proper namespace, but if jQuery limited itself to only setting properties on an object named “jQuery” and Prototype did the same on an object named “Prototype” and so on, the current JavaScript landscape would look ever so much more sane.

And of course, this says nothing of the ‘$$()‘ and ‘$F()‘ functions that were also introduced by Prototype (and the ‘$E()’ and ‘$ES()’ functions inexplicibly introduced by MooTools) and whose names are so semantically worthless that a developer has no hope of inferring their function without consulting the reference documentation. Which again can only be accomplished after checking the entire codebase to determine which framework it is that is defining these functions with its woefully awful naming convention.

If the developers of Prototype, jQuery, Mootools, and the like wanted to turn JavaScript into an unreadable and unmaintainable mess of a language like Perl, then I applaud them for their efforts. But if not then I call them all out on their atrocious naming convention and design decisions. There is no excuse for this nonsense. If you’re building a JavaScript library or framework, then pick a reasonable “namespace” to use for it. This namespace should be the only thing that you bind in the global scope. Everything else that is part of your library should be bound as a property inside of this namespace. And there should be no automatic creation of shorthand aliases in the global scope.

I don’t think this is too much to ask. And of course, any developer that wants to use a global shorthand alias can always do:

window.$J = jQuery;
window.$P = Prototype.$;  //or:  window.$P = document.getElementById;

It takes all of one line of code to set up an alias. But when you start doing this automatically for everyone that uses your framework you create nothing but problems. Especially when you jump on the bandwagon and choose the same crappy shorthand alias names that other frameworks are already using.

There is absolutely no reason why multiple JavaScript frameworks should all be competing over the same terrible function names. This isn’t a contest to see who can break the most legacy code, or who can come up with the most obtuse API. They do have such contests if you are interested in such a thing, but this is not one of them. The only thing accomplished by parading the dollar sign around as an example of a well-chosen function name is an increased brittleness in the code that glues together the majority of our modern websites. It muddies semantics, and creates cases where completely unrelated libraries are not easily compatible with each other, and where simply importing a new library can cause existing code to break. Even worse, some novice developers get the wrong idea from all those dollar signs flying around think that they need to (or should) prefix all of their function names with “$”. So let’s put this bad practice to bed before it’s too late.

So please, can well all stop writing frameworks that give people the impression that calling a function “$”, “$$”, “$ES”, or “$anything” is a good idea? Is it so difficult to choose a reasonable namespace, minimize the number of things that you declare in the global scope, and allow the developer to define a global shorthand alias for this-or-that utility function if they decide they want to? I think not.

Also note that the method described in the other article for getting your hands on an instance of ‘Unsafe‘ no longer works. Using the latest JDK, the following code will not work (you’ll get compiler errors for even trying to import sun.misc.Unsafe):

private static Unsafe getUnsafeInstance() throws SecurityException, NoSuchFieldException, IllegalArgumentException,
    IllegalAccessException {
    Field theUnsafeInstance = Unsafe.class.getDeclaredField("theUnsafe");
    theUnsafeInstance.setAccessible(true);
    return (Unsafe) theUnsafeInstance.get(Unsafe.class);
 }

Here is a variant that still works:

	public static Object getUnsafe() {
		try {
			Class unsafeClass = Class.forName("sun.misc.Unsafe");
			Field unsafeField = unsafeClass.getDeclaredField("theUnsafe");
			unsafeField.setAccessible(true);
			Object unsafeObj = unsafeField.get(unsafeClass);
			
			return unsafeObj;
		}
		catch (Exception e) {
			return null;//UNSAFE_ERROR_CODE;
		}
	}

Note that as importing sun.misc.Unsafe now causes a compiler error, it is only possible to return an Object reference to the ‘Unsafe‘ instance. This means that any method that you want to call on it must be done through reflection, which is tedious at best. Luckily, I’ve taken care of this tedious bit for you, and created a wrapper that provides the same public API as sun.misc.Unsafe and uses reflection to delegate method calls to the real ‘Unsafe‘ instance. The source code for this utility is quite long and not very interesting, so I’m not going to post it here. Instead you can use this direct link to download a copy.

Here is a simple example of how to use this class to perform some basic tasks:

		System.out.println("Testing sun.misc.Unsafe...");
		double[] averages = {-777.0, -777.0, -777.0};
		UnsafeUtil util = new UnsafeUtil();
		System.out.println("addressSize=" + util.addressSize() + ", pageSize=" + util.pageSize());
		
		long memPointer = util.allocateMemory(1024);
		long memPointer2 = util.allocateMemory(1024);
		System.out.println("1K memory blocks at addresses:  " + memPointer + ", " + memPointer2);
		
		//valid copy
		util.copyMemory(memPointer, memPointer2, 1024);
		
		//invalid copy
		//util.copyMemory(memPointer, memPointer2, 1024000);
		
		int result = util.getLoadAverage(averages, 1);
		System.out.println("getLoadAverage:  Result=" + result + ", averages=" + averages[0] + ", " + averages[1] + ", " + averages[2]);

Do note that if you uncomment the “invalid copy” line then running this code will very likely crash your JVM. As noted above, you should use this utility with caution, particularly if you are running it in an environment shared by other Java code.

And why do all this when Sun (now Oracle) clearly does not want people mucking around with this class? Because ultimately power belongs in the hands of developers. All developers, not just the select few chosen to work on privileged system code.

But suffice to say, if you want to install the Adobe AIR runtime on an emulated Android device for testing or development purposes without having to wade through a ton of fuss and nonsense, you have two basic options. The first is described briefly here, and basically involves installing the latest Flash/Flex/AIR SDK from the official website and then grabbing the AIR runtime package from ‘<AIR_SDK_ROOT>/runtimes/air/android/emulator/Runtime.apk‘. This file is the AIR runtime that must be installed on the emulator for any apps built with Adobe AIR to function. And this method works fine if you don’t mind downloading and installing the entire AIR SDK (90 MB) just to grab this one file.

You other option is to use this direct link to download just the AIR runtime package (6.1 MB). Note that this is version 2.7 of the AIR runtime, and has been tested with an emulator running Android 3.1 only. I cannot vouch for it working with any other configurations.

In either case, once you have gotten a hold of the the runtime .apk file, installing it on your emulator is a relatively simple process. All you need is the ‘adb‘ utility that is included in the “Android SDK Platform Tools” package (note that this package is not the same as the similarly named “Android SDK Tools” package). If you don’t have this package installed yet, then use your Android configuration manager to install it. Then simply navigate to ‘<ANDROID_SDK_ROOT>/platform-tools‘ and run the following command (while your Android emulator is running):

adb install /path/to/your/AIR/runtime.apk

This will install the AIR runtime on your emulated device, and you can now install and run AIR-based Android apps on your emulator. Quite simple, really. Which only doubles my confusion with respect to why this simple process seems to be so poorly documented online.

https://github.com/kstenerud/iOS-Universal-Framework

This project provides a single installation shell script that will add a new Project Template to XCode, one that can be used to build universal iOS frameworks. Now this wouldn’t be a big deal (and in all rights, shouldn’t be a big deal), if not for the fact that for some unspecified and frustrating reason, XCode has no built-in ability to create such frameworks. This means that up until recently if you had an iOS library that you wanted to use across many projects, or that you wanted to distribute for other developers to use in their projects, you had only a few not-very-good options:

• Include your source code in every project that uses your library (increased compilation time, hooray!).
• Build two library versions, one for armv6/armv7 and one for x86.
• Screw with the linker to manually create a “fat” library.
• Use the Bundle Hack and hope that it works.

It’s worth noting here that the first three options listed above do nothing to help with the management of any shared header files needed to actually make use of the library code. The fourth option does allow you to include public headers in your build artifact, but the setup to do so is tedious, and the entire thing is basically a giant hack besides. None of these options are really very convenient or useful from the developer’s point of view.

What developers really need, what they should have access to, and what XCode should have supported at least since the release of iOS 4.0, is the ability to build true universal iOS frameworks that are “real” frameworks in the same sense that UIKit and CoreGraphics are real frameworks. And that’s exactly what the iOS-Universal-Framework project gives you. Just install it and you get a handy XCode Project Template that can be used to build a universal iOS framework. This lets you build real iOS frameworks that include libraries for both x86 and armv6/armv7 in a single package, automatically bundled with your public header files. You (or anyone else) can then use the generated framework inside of other projects in the same way as any other iOS framework; just add it to your “Link With Binary Libraries” build phase, and away you go.

All told, the iOS-Universal-Framework Project Template is great and works exactly as advertised. Just install it and you’re good to go. I’ve only come across one minor caveat worth mentioning, which is that although the template does correctly produce a universal iOS framework, the build product shown in XCode will actually point to an architecture-specific version of the framework. In order to find the correct, universal framework it is necessary to do a “Show in Finder” on the build product shown in XCode (or otherwise navigate to your project output directory), and then go up a level (or two) in the filesystem to find the folder that contains the universal version of the framework (edit: as per Karl’s comment below, this has now been fixed. Hooray!).

Apart from that minor annoyance this little XCode extension is really quite excellent, and I encourage you to give it a try. My personal thanks to Karl Stenerud for putting this together.

Recently I returned to this bit of code, and the ability to record live video of an application is theoretical no longer. To get straight to the point, here is the revised code:

//
//ScreenCaptureView.h
//
#import <UIKit/UIKit.h>
#import <AVFoundation/AVFoundation.h>

/**
 * Delegate protocol.  Implement this if you want to receive a notification when the
 * view completes a recording.
 *
 * When a recording is completed, the ScreenCaptureView will notify the delegate, passing
 * it the path to the created recording file if the recording was successful, or a value
 * of nil if the recording failed/could not be saved.
 */
@protocol ScreenCaptureViewDelegate <NSObject>
- (void) recordingFinished:(NSString*)outputPathOrNil;
@end


/**
 * ScreenCaptureView, a UIView subclass that periodically samples its current display
 * and stores it as a UIImage available through the 'currentScreen' property.  The
 * sample/update rate can be configured (within reason) by setting the 'frameRate'
 * property.
 *
 * This class can also be used to record real-time video of its subviews, using the
 * 'startRecording' and 'stopRecording' methods.  A new recording will overwrite any
 * previously made recording file, so if you want to create multiple recordings per
 * session (or across multiple sessions) then it is your responsibility to copy/back-up
 * the recording output file after each session.
 *
 * To use this class, you must link against the following frameworks:
 *
 *  - AssetsLibrary
 *  - AVFoundation
 *  - CoreGraphics
 *  - CoreMedia
 *  - CoreVideo
 *  - QuartzCore
 *
 */

@interface ScreenCaptureView : UIView {
   //video writing
   AVAssetWriter *videoWriter;
   AVAssetWriterInput *videoWriterInput;
   AVAssetWriterInputPixelBufferAdaptor *avAdaptor;

   //recording state
   BOOL _recording;
   NSDate* startedAt;
   void* bitmapData;
}

//for recording video
- (bool) startRecording;
- (void) stopRecording;

//for accessing the current screen and adjusting the capture rate, etc.
@property(retain) UIImage* currentScreen;
@property(assign) float frameRate;
@property(nonatomic, assign) id<ScreenCaptureViewDelegate> delegate;

@end



//
//ScreenCaptureView.m
//
#import "ScreenCaptureView.h"
#import <QuartzCore/QuartzCore.h>
#import <MobileCoreServices/UTCoreTypes.h>
#import <AssetsLibrary/AssetsLibrary.h>

@interface ScreenCaptureView(Private)
- (void) writeVideoFrameAtTime:(CMTime)time;
@end


@implementation ScreenCaptureView

@synthesize currentScreen, frameRate, delegate;

- (void) initialize {
   // Initialization code
   self.clearsContextBeforeDrawing = YES;
   self.currentScreen = nil;
   self.frameRate = 10.0f;     //10 frames per seconds
   _recording = false;
   videoWriter = nil;
   videoWriterInput = nil;
   avAdaptor = nil;
   startedAt = nil;
   bitmapData = NULL;
}

- (id) initWithCoder:(NSCoder *)aDecoder {
   self = [super initWithCoder:aDecoder];
   if (self) {
       [self initialize];
   }
   return self;
}

- (id) init {
   self = [super init];
   if (self) {
       [self initialize];
   }
   return self;
}

- (id)initWithFrame:(CGRect)frame {
   self = [super initWithFrame:frame];
   if (self) {
       [self initialize];
   }
   return self;
}

- (CGContextRef) createBitmapContextOfSize:(CGSize) size {
   CGContextRef    context = NULL;
   CGColorSpaceRef colorSpace;
   int             bitmapByteCount;
   int             bitmapBytesPerRow;

   bitmapBytesPerRow   = (size.width * 4);
   bitmapByteCount     = (bitmapBytesPerRow * size.height);
   colorSpace = CGColorSpaceCreateDeviceRGB();
   if (bitmapData != NULL) {
       free(bitmapData);
   }
   bitmapData = malloc( bitmapByteCount );
   if (bitmapData == NULL) {
       fprintf (stderr, "Memory not allocated!");
       return NULL;
   }

   context = CGBitmapContextCreate (bitmapData,
                                    size.width,
                                    size.height,
                                    8,      // bits per component
                                    bitmapBytesPerRow,
                                    colorSpace,
                                    kCGImageAlphaNoneSkipFirst);

   CGContextSetAllowsAntialiasing(context,NO);
   if (context== NULL) {
       free (bitmapData);
       fprintf (stderr, "Context not created!");
       return NULL;
   }
   CGColorSpaceRelease( colorSpace );

   return context;
}


//static int frameCount = 0;            //debugging
- (void) drawRect:(CGRect)rect {
   NSDate* start = [NSDate date];
   CGContextRef context = [self createBitmapContextOfSize:self.frame.size];
   
   //not sure why this is necessary...image renders upside-down and mirrored
   CGAffineTransform flipVertical = CGAffineTransformMake(1, 0, 0, -1, 0, self.frame.size.height);
   CGContextConcatCTM(context, flipVertical);

   [self.layer renderInContext:context];
   
   CGImageRef cgImage = CGBitmapContextCreateImage(context);
   UIImage* background = [UIImage imageWithCGImage: cgImage];
   CGImageRelease(cgImage);
   
   self.currentScreen = background;

   //debugging
   //if (frameCount < 40) {
   //      NSString* filename = [NSString stringWithFormat:@"Documents/frame_%d.png", frameCount];
   //      NSString* pngPath = [NSHomeDirectory() stringByAppendingPathComponent:filename];
   //      [UIImagePNGRepresentation(self.currentScreen) writeToFile: pngPath atomically: YES];
   //      frameCount++;
   //}

   //NOTE:  to record a scrollview while it is scrolling you need to implement your UIScrollViewDelegate such that it calls
   //       'setNeedsDisplay' on the ScreenCaptureView.
   if (_recording) {
       float millisElapsed = [[NSDate date] timeIntervalSinceDate:startedAt] * 1000.0;
       [self writeVideoFrameAtTime:CMTimeMake((int)millisElapsed, 1000)];
   }

   float processingSeconds = [[NSDate date] timeIntervalSinceDate:start];
   float delayRemaining = (1.0 / self.frameRate) - processingSeconds;

   CGContextRelease(context);

   //redraw at the specified framerate
   [self performSelector:@selector(setNeedsDisplay) withObject:nil afterDelay:delayRemaining > 0.0 ? delayRemaining : 0.01];   
}

- (void) cleanupWriter {
   [avAdaptor release];
   avAdaptor = nil;
   
   [videoWriterInput release];
   videoWriterInput = nil;
   
   [videoWriter release];
   videoWriter = nil;
   
   [startedAt release];
   startedAt = nil;

   if (bitmapData != NULL) {
       free(bitmapData);
       bitmapData = NULL;
   }
}

- (void)dealloc {
   [self cleanupWriter];
   [super dealloc];
}

- (NSURL*) tempFileURL {
   NSString* outputPath = [[NSString alloc] initWithFormat:@"%@/%@", [NSSearchPathForDirectoriesInDomains(NSDocumentDirectory, NSUserDomainMask, YES) objectAtIndex:0], @"output.mp4"];
   NSURL* outputURL = [[NSURL alloc] initFileURLWithPath:outputPath];
   NSFileManager* fileManager = [NSFileManager defaultManager];
   if ([fileManager fileExistsAtPath:outputPath]) {
       NSError* error;
       if ([fileManager removeItemAtPath:outputPath error:&error] == NO) {
           NSLog(@"Could not delete old recording file at path:  %@", outputPath);
       }
   }

   [outputPath release];
   return [outputURL autorelease];
}

-(BOOL) setUpWriter {
   NSError* error = nil;
   videoWriter = [[AVAssetWriter alloc] initWithURL:[self tempFileURL] fileType:AVFileTypeQuickTimeMovie error:&error];
   NSParameterAssert(videoWriter);

   //Configure video
   NSDictionary* videoCompressionProps = [NSDictionary dictionaryWithObjectsAndKeys:
                                          [NSNumber numberWithDouble:1024.0*1024.0], AVVideoAverageBitRateKey,
                                          nil ];

   NSDictionary* videoSettings = [NSDictionary dictionaryWithObjectsAndKeys:
                                  AVVideoCodecH264, AVVideoCodecKey,
                                  [NSNumber numberWithInt:self.frame.size.width], AVVideoWidthKey,
                                  [NSNumber numberWithInt:self.frame.size.height], AVVideoHeightKey,
                                  videoCompressionProps, AVVideoCompressionPropertiesKey,
                                  nil];

   videoWriterInput = [[AVAssetWriterInput assetWriterInputWithMediaType:AVMediaTypeVideo outputSettings:videoSettings] retain];

   NSParameterAssert(videoWriterInput);
   videoWriterInput.expectsMediaDataInRealTime = YES;
   NSDictionary* bufferAttributes = [NSDictionary dictionaryWithObjectsAndKeys: 
                                     [NSNumber numberWithInt:kCVPixelFormatType_32ARGB], kCVPixelBufferPixelFormatTypeKey, nil];

   avAdaptor = [[AVAssetWriterInputPixelBufferAdaptor assetWriterInputPixelBufferAdaptorWithAssetWriterInput:videoWriterInput sourcePixelBufferAttributes:bufferAttributes] retain];

   //add input
   [videoWriter addInput:videoWriterInput];
   [videoWriter startWriting];
   [videoWriter startSessionAtSourceTime:CMTimeMake(0, 1000)];

   return YES;
}



- (void) completeRecordingSession {
   NSAutoreleasePool* pool = [[NSAutoreleasePool alloc] init];

   [videoWriterInput markAsFinished];
   
   // Wait for the video
   int status = videoWriter.status;
   while (status == AVAssetWriterStatusUnknown) {
       NSLog(@"Waiting...");
       [NSThread sleepForTimeInterval:0.5f];
       status = videoWriter.status;
   }

   @synchronized(self) {
       BOOL success = [videoWriter finishWriting];
       if (!success) {
           NSLog(@"finishWriting returned NO");
       }

       [self cleanupWriter];

       id delegateObj = self.delegate;
       NSString *outputPath = [[NSString alloc] initWithFormat:@"%@/%@", [NSSearchPathForDirectoriesInDomains(NSDocumentDirectory, NSUserDomainMask, YES) objectAtIndex:0], @"output.mp4"];
       NSURL *outputURL = [[NSURL alloc] initFileURLWithPath:outputPath];

       NSLog(@"Completed recording, file is stored at:  %@", outputURL);
       if ([delegateObj respondsToSelector:@selector(recordingFinished:)]) {
           [delegateObj performSelectorOnMainThread:@selector(recordingFinished:) withObject:(success ? outputURL : nil) waitUntilDone:YES];
       }

       [outputPath release];
       [outputURL release];
   }

   [pool drain];
}



- (bool) startRecording {
   bool result = NO;
   @synchronized(self) {
       if (! _recording) {
           result = [self setUpWriter];
           startedAt = [[NSDate date] retain];
           _recording = true;
       }
   }

   return result;
}

- (void) stopRecording {
   @synchronized(self) {
       if (_recording) {
           _recording = false;
           [self completeRecordingSession];
       }
   }
}

-(void) writeVideoFrameAtTime:(CMTime)time {
   if (![videoWriterInput isReadyForMoreMediaData]) {
       NSLog(@"Not ready for video data");
   }
   else {
       @synchronized (self) {
           UIImage* newFrame = [self.currentScreen retain];
           CVPixelBufferRef pixelBuffer = NULL;
           CGImageRef cgImage = CGImageCreateCopy([newFrame CGImage]);
           CFDataRef image = CGDataProviderCopyData(CGImageGetDataProvider(cgImage));

           int status = CVPixelBufferPoolCreatePixelBuffer(kCFAllocatorDefault, avAdaptor.pixelBufferPool, &pixelBuffer);
           if(status != 0){
               //could not get a buffer from the pool
               NSLog(@"Error creating pixel buffer:  status=%d", status);
           }
                       // set image data into pixel buffer
           CVPixelBufferLockBaseAddress( pixelBuffer, 0 );
           uint8_t* destPixels = CVPixelBufferGetBaseAddress(pixelBuffer);
           CFDataGetBytes(image, CFRangeMake(0, CFDataGetLength(image)), destPixels);  //XXX:  will work if the pixel buffer is contiguous and has the same bytesPerRow as the input data

           if(status == 0){
               BOOL success = [avAdaptor appendPixelBuffer:pixelBuffer withPresentationTime:time];
               if (!success)
                   NSLog(@"Warning:  Unable to write buffer to video");
           }

           //clean up
           [newFrame release];
           CVPixelBufferUnlockBaseAddress( pixelBuffer, 0 );
           CVPixelBufferRelease( pixelBuffer );        
           CFRelease(image);
           CGImageRelease(cgImage);
       }

   }

}

@end

This class will let you record high-quality video of any other view in your application. To use it, simply set it up as the superview of the UIView(s) that you want to record, add a reference to it in your corresponding UIViewController (using Interface Builder or whatever your preferred method happens to be), and then call ‘startRecording‘ when you are ready to start recording video. When you’ve recorded enough, call ‘stopRecording‘ to complete the process. You will get a nice .mp4 file stored under your application’s ‘Documents’ directory that you can copy off or do whatever else you want with.

Note that if you want to record a UIScrollView while it is scrolling, you will need to implement your UIScrollViewDelegate such that it calls ‘setNeedsDisplay‘ on the ScreenCaptureView while the scroll-view is scrolling. For instance:

- (void) scrollViewDidScroll: (UIScrollView*)scrollView {
       [captureView setNeedsDisplay];
}

I haven’t tested this code on a physical device yet, but there’s no reason why it should not work on any device that includes H.264 video codec support (iPhone 3GS and later). However, given the amount of drawing that it does, it’s safe to say that the more horsepower behind it, the better.

Here is a rather unimpressive 30-second recording of a UITableView that I created using this class (if your browser doesn’t support HTML5, use the link below):

Example iPhone Recording

Lastly, I haven’t tested this class with any OpenGL-based subviews, so I can’t say if it will work in that case. If you try it in this configuration, please feel free to reply with your results.

Update

For anyone looking for a working example, you can download this sample project. This project simply creates a 30-second recording of a ‘UITableView‘.