Redline Solutions, LLC

Accessing a secondary screen is a new feature as of Apple IPhone OS v3.2. The short story is that you can now create an application that displays to a video screen along with the standard display screen on the IPad. Not many developers are aware of this feature, but chances are if you are reading this, you would definitely like to know how to write an application that can use this feature. So let’s not keep you waiting… let’s dive into a quick tutorial.

Requirements:

• Download the XCode 3.2 or higher SDK
• A real IPad device (no simulation is available)
• An Apple brand video out cable
• Knowledge of Objective-C and UIKit IPhone libraries
• An external video display (TV or LCD)

Background:

First off, this new API is only available on the IPad using XCode 3.2 or higher.  You might find references on the web to a previously undocumented API for the IPhone OS (2.2.1 to 3.1.3) that allows for “video out” in applications.  That code will not work on the IPad and has been replaced by this new official API.

The second thing to note is that accessing the external screen is not based on “mirroring”.  The output that you see on the IPad is not automatically replicated to the secondary screen. The idea behind the API is that the application developer has full control over how to draw to the external display screen and it’s not based in hardware or is a simple bitblit copy.  You as the developer must set up a new area to draw to on the second display and render your application into it.

The new changes to the SDK that enable video our are fairly simple and straightforward.  Two Objective-C Cocoa Touch classes, UIScreen and UIWindow, have the additional functionality to make the code very easy to integrate into your existing code base.

Code:

For the code, I am assuming you understand Cocoa Touch and the UIKit classes.  Namely that you already use UIWindow and UIView to display your user interface.

Step 1. Determine if an external display screen is available

To begin, you’ll typically need to know if the external display is connected to the device.  You can perform this check at the start of your application.

NSArray* arrScreens = [UIScreen screens];
int numberOfScreens = [arrScreens count];
bool isExternalDisplayConnected = (numberOfScreens > 1);

However a better method would be to use the [notifyScreenConnected] notification message.  I will not show this method here, but will update the tutorial with this solution at a later time.

Once our secondary display is available, then the UIScreen array will contain more than one entry.  The first entry is the primary display on the IPad.  The second entry is the external display.  We will need a refence to this screen.

UIScreen* videoScreen = NULL;
videoScreen = (UIScreen*) [arrScreens objectAtIndex: 1];

Step 2. Create secondary UI

Now we need to create a new UIWindow and any other necessary views.  We can create them conditionally when we know the external screen is connected.

CGRect rect;
UIView* videoView;
if (isExternalDisplayConnected && videoScreen != NULL)
{
    rect = [videoScreen bounds];
    window = [[UIWindow alloc] initWithFrame: rect];
    window.screen = videoScreen;
    videoView = [[UIView alloc] initWithFrame:rect];
    videoView.layer.anchorPoint = CGPointMake(0.0f, 0.0f);
    videoView.layer.position = CGPointMake(0.0f, 0.0f);
    [window addSubview: evView];
    [window makeKeyAndVisible];
}

Note that there is nothing particularly different about creating a new UIWindow and UIView here.  The only difference is setting the screen property of the window object to the new video screen.  This is what allows the window to display on the external screen as opposed to the default IPad screen.  Also take note that the size of the external screen is determine by looking at the bounds property of the video screen.  I’ve set the new window and view to be the size of the external display so that it will appear full sized.

You should create any necessary subviews that your application would need to display on the external display and attach them to the primary view as necessary.  This may involve loading any views from an application Bundle.

Step 3. Update your display

If you application needs to refresh itself, remember that you must refresh both the main window’s views AND the external window’s views.  For the external screen view above, refreshing the UI would be a standard call.

[ videoView setNeedsDisplay ];

Step 4. Destroy UI when display disconnects

During your application’s lifecycle, you can poll the UIScreen screens array to see if the screen has disconnected or use the system notification when the display is not longer connected.  When the screen is disconnected, you should cease drawing to the screen and clean up any UIWindows and UIViews that you have created along the way for that window.  This allows you to start again from step 1 to repeat the cycle if the same or a new external display with a different resolution is re-connected to the IPad while the application is running.

Other Considerations:

As you can see, you will need two UI trees to render your application on two screens.  The system UI thread will deal with the redraw of the screens on each display.  If you have a game application or other application that needs to constantly refresh its user interface, then the application may need to render twice to keep the external screen up to date.  This all depends on the nature of your application.  You can decide to only refresh one screen, whether it is the internal or the external one.  However if you choose to refresh both displays, your application will certainly take more time and frame rates will be lower than rendering to only one display.

The importance of checking that the display is connected will help with this performance consideration.  Preventing any extraneous drawing updates to the windows when the screen is not connected will certainly improve your applications performance.

You can control the video modes of the external display by using the videoModes property of the UIScreen object.  You can then choose which video mode to use for that screen.  By default, the highest resolution video mode is enabled.

Also take note the secondary display will not receive any form of user input and it will not have a status bar.

Project demo:

You can take a look at “Waiting For Google”, a sample IPad application that uses the internal and external screen simultaneously.  It synchronously draws to both displays to make for an interactive experience on the IPad and for visual presentation displayed through a digital projector.

That wraps up things for this tutorial!  I hope it was helpful and gives you some insight to using this feature in one of your own applications.

Cheers!

Jose Rojas

HOW TO: use an external screen (video out) in an Apple IPad application10.0102