Have you ever wanted to demo your apps on the big screen, just like Steve Jobs does in his famous keynote speeches? Up until recently, this wasn’t possible to do without jailbreaking your iPhone. Starting in iPhone OS 3.2 and iOS 4.0+, a new set of public APIs exposes the dock connector’s ability to interface with big screen TVs and PC monitors. You can either use the composite / component AV cable or the new VGA dongle accessories to connect to an external display.

The new UIScreen APIs

UIScreen is a new UIKit class  that abstracts display interfaces (the one on the device, as well as external ones). You can enumerate the available screens, obtain display modes for each of them (UIScreenMode) and get automatically notified when they are connected or disconnected. An important thing to note is that in order to take part in the rendering pipeline, each screen must have its own root UIWindow instance. For that matter, Apple added a new UIWindow property allowing to switch an entire root window from one screen to another.

How should I use it in my apps

Apple typically recommends using the new UIScreen API to display the main contents of your application (such as videos and pictures) on the external screen. While you would use the device’s multitouch-enabled main screen for displaying auxiliary data and/or controls. In our case, we wanted to use the new APIs so we could demo our apps during meetings or to showcase our work to our clients.

Mirroring the contents of the device’s main screen

In a nutshell

• Automatically detect displays
• Upon detection:
  • Setup a root window for the external display
  • Schedule a timer that will be fire on screen refresh
• On every screen refresh:
  • Copy the device’s main screen to the external screen

Starting in iPhone OS 3.1, the recommended way to periodically refresh screen contents is to use the CADisplayLink class (especially for OpenGL-based games). It is a runloop-based API that is synchronized with Core Animation, the iOS graphics subsystem. The easiest way to copy the contents of the screen is to use the UIGetScreenImage() function. This function used to be a private API, but Apple allowed developers to use it since the fall of 2009. UIGetScreenImage() returns a CGImageRef instance, basically a screenshot of the main screen. Unfortunately, UIGetScreenImage() does not respect the Core Foundation naming conventions, which shows that Apple never really intended to allow public use of this API.

It is important to note that when we schedule our CADisplayLink instance on the runloop, we need to set it so that it fires on NSRunLoopCommonModes input mode. If instead we use the NSDefaultRunLoopMode input mode the timer will not fire when tracking touches (UITrackingRunLoopMode). NSRunLoopCommonModes is a special input mode that combines all input modes, including UITrackingRunLoopMode, but this has a noticeable impact on the performance of screen mirroring. The current generation iPad cannot copy the entire screen to the secondary display buffer without affecting the interface responsiveness.

The UIApplication+ScreenMirroring category

We’ve taken everything we’ve learned while playing with the new UIScreen API and have put together a very simple Objective C category for the UIApplication class. This allows you to add the screen mirroring capability with a single line of code. You would typically call [UIApplication setupScreenMirroring] in your application:didFinishLaunchingWithOptions: method. We have not yet tested this piece of code on the new iPhone 4, but according to the Apple Dev Forum, the new device officially supports the VGA dongle and should work just fine.

The source code for this class is available on Google Code (licensed under New BSD license), along with a sample project showing the various options. For instance, you can get notified when the screen mirroring gets enabled / disabled so can display a visual cue to your users.

A technical article by François Proulx
Software engineer / iOS applications developer