A screen surface is an object containing a raw video buffer. It supports a specific resolution, pitch, and pixel format. To create a new screen surface, a buffer is initialized using a dynamic dictionary class named CFMutableDictionary. This is used to provide information about the desired makeup and behavior of the surface. CFMutableDictionary is a class used on both the desktop and mobile platforms of Mac OS X and is part of the Core Foundation framework. Full documentation for this class can be found on the Apple Developer Connection web site.

The following example builds a dictionary object specifying a 320×480 video buffer. It uses RGBA, a four-byte pixel format containing one byte each for red, green, blue, and alpha blending channels. The last method called in the example allocates enough space in the dictionary for all the four-byte pixels in the X×Y rectangle.

CFMutableDictionaryRef dict;
int x = 320, y = 480, pitch = x*4, size = 4*x*y;
char *pixelFormat = "RGBA";

dict = CFDictionaryCreateMutable(kCFAllocatorDefault, 0,
  &kCFTypeDictionaryKeyCallBacks, &kCFTypeDictionaryValueCallBacks);

CFDictionarySetValue(dict, kCoreSurfaceBufferGlobal, kCFBooleanTrue);
CFDictionarySetValue(dict, kCoreSurfaceBufferPitch,
  CFNumberCreate(kCFAllocatorDefault, kCFNumberSInt32Type, &pitch));
CFDictionarySetValue(dict, kCoreSurfaceBufferWidth,
  CFNumberCreate(kCFAllocatorDefault, kCFNumberSInt32Type, &x));
CFDictionarySetValue(dict, kCoreSurfaceBufferHeight,
  CFNumberCreate(kCFAllocatorDefault, kCFNumberSInt32Type, &y));
CFDictionarySetValue(dict, kCoreSurfaceBufferPixelFormat,
  CFNumberCreate(kCFAllocatorDefault, kCFNumberSInt32Type,
  pixelFormat));
CFDictionarySetValue(dict, kCoreSurfaceBufferAllocSize,
  CFNumberCreate(kCFAllocatorDefault, kCFNumberSInt32Type, &size));

Once a dictionary has been built to define the type of buffer needed, the screen surface can be created using its properties.

CoreSurfaceBufferRef screenSurface = CoreSurfaceBufferCreate(dict);

Before a screen surface can be displayed, it needs to be attached to a layer. Create a new layer using the Layer Kit framework’s LKLayer object.

LKLayer *screenLayer;

screenLayer = [ [ LKLayer layer ] retain ];
[ screenLayer setFrame: viewRect ];
[ screenLayer setOpaque: YES ];

Now, attach the contents of the screen surface to the newly created layer. Note that you always have to lock the screen surface while handling it.

CoreSurfaceBufferLock(screenSurface, 3);
[ screenLayer setContents: screenSurface ];
CoreSurfaceBufferUnlock(screenSurface);

The UIView objects you’ve been working with throughout this book contain their own base layer. To display the surface’s contents, add the newly created layer to the existing UIView as a sublayer.

[ [ self _layer ] addSublayer: screenLayer ];

The screen surface is now glued to the layer, and the layer is added to the view. If there are other layers in the UIView object, the new layer will be placed on top of previous layers, meaning you’ll need to adjust its transparency (alpha) in order to see the layers underneath.

Even after you add the surface’s layer to a view, nothing is displayed yet because the video buffer itself is empty. The CoreSurfaceBuffer object contains a pointer to a raw video buffer. To access the base address of this raw video buffer, use the CoreSurfaceBufferGetBaseAddress function:

unsigned long *baseAddress = CoreSurfaceBufferGetBaseAddress(screenSurface);

The buffer is a single-dimensioned array, even though your application and the user think of it as two-dimensional. Pixels run from left to right and from top to bottom. For instance, baseAddress[0] addresses the upper-left pixel in the surface, baseAddress[319] addresses the upper-right pixel for the 320×480 resolution used in this surface, and baseAddress[320] addresses the leftmost pixel in the second row.

Because an RGBA pixel type is used in this example, each pixel is four bytes long. Using an unsigned long pointer (which is also four bytes long) allows entire pixels to be addressed as elements in an array.

You may also choose to use an unsigned char pointer, which would allow you to address the individual pixel values (one byte for each channel). Keep in mind, however, that you’ll need to increment your pointer four bytes at a time to reach the next pixel (assuming a four-byte pixel type). For example, (unsigned char *) baseAddress[0] references the red channel of the first pixel, baseAddress[1] the green channel, baseAddress[2] the blue channel, baseAddress[3] the alpha channel, and finally baseAddress[4] the red channel of the next pixel.

16-bit pixel formats are commonly used in lieu of the 32-bit RGBA pixel to deliver faster performance when color accuracy isn’t critical—and because only expensive desktop displays can even support true 32-bit color, there’s not much reason to use it on a cell phone. Because there’s less memory to move around, a 16-bit frame can be copied in half the time as a 32-bit frame. To use this pixel format, make the following changes to the screen surface’s dictionary properties before the surface is created.

int x = 320, y = 480, pitch = x*2, size = 2*x*y;
char *pixelFormat = "565L";

The 16-bit pixel format uses two bytes per pixel, and is identified by the pixel format 565L. Once the surface has been created, it can then be accessed using an unsigned short pointer, which is two bytes long instead of four.

unsigned short *baseAddress = CoreSurfaceBufferGetBaseAddress(screenSurface);

To convert RGB values to 16-bit values suitable for writing to such a buffer, you can define a macro, allowing your application to move smoothly between 16-bit and 32-bit RGBA.

#define RGB2565L(R, G, B) ((R >> 3) << 11) | (( G >> 2) << 5 ) 
    | (( B >> 3 ) << 0 )

A frame buffer is a secondary memory buffer used to construct a video frame before it is displayed on a screen surface. This can help prevent flickering by applications that render graphics one scan-line at a time (such as emulators) and can also be used to synchronize programs needing to display in frames per second. Using a frame buffer is also useful for aggregating multiple video layers together before displaying a finished frame. For example, if you are writing a game that draws several different video layers—a background, sprites, and a HUD—then each individual video layer can be drawn onto an internal frame buffer before the finished frame is rendered on the screen. The setup and copying of a frame buffer, if you choose to use one, is the job of the application. When the screen surface is created, its size is calculated as the pixel size multiplied by the width and height of the surface. To use a frame buffer, create a buffer of the same size:

workBuffer = malloc(2 * x * y);

Now, move all of your video processing so that it takes place in this work buffer until the program has finished rendering a frame. When the frame is complete, it is ready to be copied to the surface’s video buffer. The period between the completed frame and the rendering of the next frame is called the v-blank period; this period is when the work buffer can safely be written out to the screen surface’s buffer.

memcpy(baseAddress, workBuffer, 2 * x * y);
[ screenView setNeedsDisplay ];

The first graphics program usually written by any geek is the display of random colors across the resolution of the screen. In keeping with this tradition, our example here creates and displays a screen surface, then applies a coat of rand( ) to each pixel every fifth of a second. When the example is run, the entire screen will be filled with colorful geek snow™.

To build this example, the Core Surface and Layer Kit frameworks must be linked in:

$ arm-apple-darwin-gcc -o MyExample MyExample.m -lobjc 
  -framework CoreFoundation -framework Foundation -framework UIKit 
  -framework CoreSurface -framework LayerKit

Example 5-1 and Example 5-2 contain the code for the application.

#import <CoreFoundation/CoreFoundation.h>
#import <UIKit/UIKit.h>
#import <CoreSurface/CoreSurface.h>

@interface MainView : UIView
{
    CoreSurfaceBufferRef screenSurface;
    unsigned short *baseAddress;
    LKLayer *screenLayer;
}

- (id)initWithFrame:(CGRect)frame;
- (void)drawRect:(CGRect)rect;
- (CoreSurfaceBufferRef)screenSurface;
- (void)dealloc;

@end

@interface MyApp : UIApplication
{
    UIWindow *window;
    MainView *mainView;
}

- (void)applicationDidFinishLaunching:(NSNotification *)aNotification;
@end

#import "MyExample.h"

int main(int argc, char **argv)
{
    NSAutoreleasePool *autoreleasePool = [ [ NSAutoreleasePool alloc ] init ];
    int returnCode = UIApplicationMain(argc, argv, [ MyApp class ]);
    [ autoreleasePool release ];
    return returnCode;
}

@implementation MyApp
- (void)applicationDidFinishLaunching:(NSNotification *)aNotification {
    window = [ [ UIWindow alloc ] initWithContentRect:
        [ UIHardware fullScreenApplicationContentRect ]
    ];

    CGRect rect = [ UIHardware fullScreenApplicationContentRect ];
    rect.origin.x = rect.origin.y = 0.0f;

    mainView = [ [ MainView alloc ] initWithFrame: rect ];

    [ window setContentView: mainView ];
    [ window orderFront: self ];
    [ window makeKey: self ];
    [ window _setHidden: NO ];

    NSTimer *timer = [ NSTimer scheduledTimerWithTimeInterval: 0.05
            target: self
            selector: @selector(handleTimer:)
            userInfo: nil
            repeats: YES ];
}

- (void) handleTimer: (NSTimer *) timer
{
    CoreSurfaceBufferRef screenSurface;
    unsigned short *baseAddress;
    int i;
    screenSurface = [ mainView screenSurface ];
    baseAddress = CoreSurfaceBufferGetBaseAddress(screenSurface);

    for(i=0;i < 320 * 480;i++)
        baseAddress[i] = rand(  ) % 0xFFFF;
    [ mainView setNeedsDisplay ];
}
@end

@implementation MainView
- (id)initWithFrame:(CGRect)rect {

    if ((self == [ super initWithFrame: rect ]) != nil) {
        CFMutableDictionaryRef dict;
        int x = 320, y = 480, pitch = x * 2, size = 2 * x * y, i;
        char *pixelFormat = "565L";

        /* Create a screen surface */
        dict = CFDictionaryCreateMutable(kCFAllocatorDefault, 0,
            &kCFTypeDictionaryKeyCallBacks, &kCFTypeDictionaryValueCallBacks);
        CFDictionarySetValue(dict, kCoreSurfaceBufferGlobal, kCFBooleanTrue);
        CFDictionarySetValue(dict, kCoreSurfaceBufferPitch,
            CFNumberCreate(kCFAllocatorDefault, kCFNumberSInt32Type, &pitch));
        CFDictionarySetValue(dict, kCoreSurfaceBufferWidth,
            CFNumberCreate(kCFAllocatorDefault, kCFNumberSInt32Type, &x));
        CFDictionarySetValue(dict, kCoreSurfaceBufferHeight,
            CFNumberCreate(kCFAllocatorDefault, kCFNumberSInt32Type, &y));
        CFDictionarySetValue(dict, kCoreSurfaceBufferPixelFormat,
            CFNumberCreate(kCFAllocatorDefault, kCFNumberSInt32Type,
            pixelFormat));
        CFDictionarySetValue(dict, kCoreSurfaceBufferAllocSize,
            CFNumberCreate(kCFAllocatorDefault, kCFNumberSInt32Type, &size));

        screenSurface = CoreSurfaceBufferCreate(dict);

        screenLayer = [ [ LKLayer layer ] retain ];
        [ screenLayer setFrame: rect ];
        [ screenLayer setContents: screenSurface ];
        [ screenLayer setOpaque: YES ];

        CoreSurfaceBufferLock(screenSurface, 3);

        [ [ self _layer ] addSublayer: screenLayer ];

        CoreSurfaceBufferUnlock(screenSurface);
    }

    return self;
}

- (void)drawRect:(CGRect)rect {

}

- (CoreSurfaceBufferRef)screenSurface {
    return screenSurface;
}

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

@end

The geek snow example works like this:

Layer transitions augment the existing UITransitionView class by providing a way to override its transitions with new ones using Layer Kit’s animation engine. This allows the developer to take advantage of the more advanced 3-D capabilities offered by Layer Kit without making significant changes to their code. When a layer transition, represented by an LKTransition object, is attached to a UITransitionView, the transition invokes Layer Kit to spawn a new thread that takes over all of the graphics processing for the transition. The developer needs only to add the desired transition to enhance an existing application. One such animation is added by the following code:

    LKAnimation *animation = [ LKTransition animation ];
    [ animation setType: @"pageCurl" ];
    [ animation setSubtype: @"fromRight" ];
    [ animation setTimingFunction:
        [ LKTimingFunction functionWithName: @"easeInEaseOut" ] ];
    [ animation setFillMode: @"extended" ];
    [ animation setTransitionFlags: 3 ];
    [ animation setSpeed: 0.25 ];

Once a Layer Kit animation has been configured, it is executed through a UITransitionView object. Before the transition view’s transition method is called, the animation must first attach to the view that will be animated. To animate all of the contents on the screen, the animation can be applied to the main view. This will cause all objects belonging to the view, such as navigation bars and buttons, to be included in the animation. If you’re working with a smaller object, such as a UITextView or UIPushButton object, apply the animation to the transition view itself. This will cause only the smaller object to be affected.

[ [ transitionView _layer ] addAnimation: animation forKey: 0 ];

This line adds the animation to the layer so that when it is transitioned, the Layer Kit animation will be run in place of transition #0. Now, the only thing left is to call the transition:

[ transitionView transition: 0 toView: newView ];

In Chapter 3, you built a page-flipping program to illustrate transitions. We’ll use the same example here, but add Layer Kit animations to flip between pages.

This example can be compiled using the tool chain on the command line:

$ arm-apple-darwin-gcc -o MyExample MyExample.m -lobjc 
    -framework UIKit -framework CoreSurface 
    -framework CoreFoundation -framework LayerKit 
    -framework Foundation

Example 5-3 and Example 5-4 contain the code for the new version of the page-flipping program.

#import <CoreFoundation/CoreFoundation.h>
#import <UIKit/UIKit.h>
#import <UIKit/UINavigationBar.h>
#import <UIKit/UINavigationItem.h>
#import <UIKit/UITransitionView.h>
#import <UIKit/UITextView.h>
#import <LayerKit/LKTransition.h>
#import <LayerKit/LKAnimation.h>

#define MAX_PAGES 10

@interface MainView : UIView
{
    UINavigationBar    *navBar;    /* Our navigation bar */
    UINavigationItem   *navItem;   /* Navigation bar title */
    UITransitionView   *transView; /* Our transition */
    int                pageNum;    /* Current page number */

    /* Some pages to scroll through */
    UITextView         *textPage[MAX_PAGES];
}

- (id)initWithFrame:(CGRect)frame;
- (void)dealloc;
- (UINavigationBar *)createNavBar:(CGRect)rect;
- (void)setNavBar;
- (void)navigationBar:(UINavigationBar *)navbar buttonClicked:(int)button;
- (void)flipTo:(int)page;

@end

@interface MyApp : UIApplication
{
    UIWindow *window;
    MainView *mainView;
}

- (void)applicationDidFinishLaunching:(NSNotification *)aNotification;
@end

#import "MyExample.h"

int main(int argc, char **argv)
{
    NSAutoreleasePool *autoreleasePool = [
        [ NSAutoreleasePool alloc ] init
    ];
    int returnCode = UIApplicationMain(argc, argv, [ MyApp class ]);
    [ autoreleasePool release ];
    return returnCode;
}

@implementation MyApp

- (void)applicationDidFinishLaunching:(NSNotification *)aNotification {
    window = [ [ UIWindow alloc ] initWithContentRect:
        [ UIHardware fullScreenApplicationContentRect ]
    ];

    CGRect rect = [ UIHardware fullScreenApplicationContentRect ];
    rect.origin.x = rect.origin.y = 0.0f;

    mainView = [ [ MainView alloc ] initWithFrame: rect ];

    [ window setContentView: mainView ];
    [ window orderFront: self ];
    [ window makeKey: self ];
    [ window _setHidden: NO ];
}
@end

@implementation MainView
- (id)initWithFrame:(CGRect)rect {
    if ((self == [ super initWithFrame: rect ]) != nil) {
        CGRect viewRect;
        int i;

        /* Create a new view port below the navigation bar */
        viewRect = CGRectMake(rect.origin.x, rect.origin.y + 48.0,
            rect.size.width, rect.size.height - 48.0);

        /* Set our start page */
        pageNum = MAX_PAGES / 2;

        /* Create ten UITextView objects as pages in our book */

        for(i=0;i<MAX_PAGES;i++) {
            textPage[i] = [ [ UITextView alloc ] initWithFrame: rect ];
            [ textPage[i] setText: [ [ NSString alloc ] initWithFormat:
                @"This is some text for page %d", i+1 ] ];
        }

        /* Creat a navigation bar with 'Prev' and 'Next' buttons */
        navBar = [ self createNavBar: rect ];
        [ self setNavBar ];
        [ self addSubview: navBar ];

        /* Create our transition view */
        transView = [ [ UITransitionView alloc ] initWithFrame: viewRect ];
        [ self addSubview: transView ];

        /* Transition to the first page */
        [ self flipTo: pageNum ];
    }

    return self;
}

- (void)dealloc
{
    [ navBar release ];
    [ navItem release ];
    [ self dealloc ];
    [ super dealloc ];
}

- (UINavigationBar *)createNavBar:(CGRect)rect {
    UINavigationBar *newNav = [ [UINavigationBar alloc] initWithFrame:
        CGRectMake(rect.origin.x, rect.origin.y, rect.size.width, 48.0f)
    ];

    [ newNav setDelegate: self ];
    [ newNav enableAnimation ];

    /* Add our title */
    navItem = [ [UINavigationItem alloc] initWithTitle:@"My Example" ];
    [ newNav pushNavigationItem: navItem ];

    [ newNav showLeftButton:@"Prev"  withStyle: 0
                rightButton:@"Next" withStyle: 0 ];

    return newNav;
}
- (void)setNavBar
{

    /* Enable or disable our page buttons */

    if (pageNum == 1)
        [ navBar setButton: 1 enabled: NO ];
    else
        [ navBar setButton: 1 enabled: YES ];

    if (pageNum == MAX_PAGES)
        [ navBar setButton: 0 enabled: NO ];
    else
        [ navBar setButton: 0 enabled: YES ];
}

- (void)navigationBar:(UINavigationBar *)navbar buttonClicked:(int)button
{
    /* Next Page */
    if (button == 0)
    {
        [ self flipTo: pageNum+1 ];
    }

    /* Prev Page */
    else {
        [ self flipTo: pageNum−1 ];
    }

}

- (void)flipTo:(int)page {

    LKAnimation *animation = [ LKTransition animation ];
    [ animation setType: @"oglFlip" ];
    [ animation setSubtype: @"fromLeft" ];
    [ animation setTimingFunction:
        [ LKTimingFunction functionWithName: @"easeOut" ] ];
    [ animation setFillMode: @"extended" ];
    [ animation setTransitionFlags: 3 ];
    [ animation setSpeed: 0.50 ];
    [ [ self  _layer ] addAnimation: animation forKey: 0 ];

    [ transView transition: 0 toView: textPage[page−1] ];
    pageNum = page;
    [ self setNavBar ];
}

@end

This example works in an almost identical fashion to Example 3-9 and Example 3-10 in Chapter 3.

Check out the LKLayer.h, LKAnimation.h, and LKTransition.h prototypes in your tool chain’s include directory. You’ll find it in /usr/local/arm-apple-darwin/include/LayerKit/.

This example makes use of Layer Kit’s LKTransformMakeRotate transformation to spin the desktop wallpaper many different ways on the X, Y, and Z axes. The wallpaper is loaded into a UIAutocorrectImageView class, which is used to scale the image down to half its size (more specifics will be covered in Chapter 7). A timer is then used to adjust the image’s rotation every 0.01 seconds, changing the axis at the end of every 360-degree spin.

To compile this example, use the tool chain on the command line:

$ arm-apple-darwin-gcc -o MyExample MyExample.m -lobjc 
-framework Foundation -framework CoreFoundation -framework UIKit 
-framework LayerKit

Example 5-5 and Example 5-6 show the code.

#import <CoreFoundation/CoreFoundation.h>
#import <UIKit/UIKit.h>
#import <LayerKit/LayerKit.h>
#import <LayerKit/LKTransform.h>

@interface MainView : UIView
{
    UIAutocorrectImageView *imageView;
    LKTransform transform;
    NSTimer *timer;

    float angle, x, y, z;
}

- (id)initWithFrame:(CGRect)frame;
- (void) handleTimer: (NSTimer *) timer;
- (void)dealloc;

@end

@interface MyApp : UIApplication
{
    UIWindow *window;
    MainView *mainView;
}

- (void)applicationDidFinishLaunching:(NSNotification *)aNotification;
@end

#import <UIKit/UIKit.h>
#import <UIKit/UIAutocorrectImageView.h>
#import "MyExample.h"

int main(int argc, char **argv)
{
    NSAutoreleasePool *autoreleasePool = [
        [ NSAutoreleasePool alloc ] init
    ];
    int returnCode = UIApplicationMain(argc, argv, [ MyApp class ]);
    [ autoreleasePool release ];
    return returnCode;

}

@implementation MyApp

- (void)applicationDidFinishLaunching:(NSNotification *)aNotification {
    window = [ [ UIWindow alloc ] initWithContentRect:
        [ UIHardware fullScreenApplicationContentRect ]
    ];

    CGRect rect = [ UIHardware fullScreenApplicationContentRect ];
    rect.origin.x = rect.origin.y = 0.0f;

    mainView = [ [ MainView alloc ] initWithFrame: rect ];

    [ window setContentView: mainView ];
    [ window orderFront: self ];
    [ window makeKey: self ];
    [ window _setHidden: NO ];
}

@end

@implementation MainView
- (id)initWithFrame:(CGRect)rect {

    if ((self == [ super initWithFrame: rect ]) != nil) {
        UIImage *tempImage;

        angle = y = z = 0;
        x = 1;

        tempImage = [ UIImage defaultDesktopImage ];
        imageView =  [ [ UIAutocorrectImageView alloc ]
            initWithFrame: CGRectMake(80, 120, 160, 240)
            image: tempImage ];
        [ [ self _layer ] addSublayer: [ imageView _layer ] ];

        transform = LKTransformMakeRotation(angle, x, y, z);
        [ imageView _layer ].transform = transform;

        [ self setNeedsDisplay ];

        timer = [ NSTimer scheduledTimerWithTimeInterval: 0.01
            target: self
            selector: @selector(handleTimer:)
            userInfo: nil
            repeats: YES ];
    }

    return self;
}

- (void) handleTimer: (NSTimer *) timer
{
    angle += 0.01;
    if (angle > 6.283) {
        angle = 0;
        if (z == 1) {
            x = 0;
        }
        else {
            if (y == 1) {
                z = 1;
            }
            y = 1;
       }
    }

    [ [ imageView _layer] setTransform:
        LKTransformRotate(transform, angle, x, y, z)
    ];
}

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

@end

The transformation demo works like this:

Explore transformations a little more and try these exercises: