Setting a Background Color

In Interface Builder, you can specify a background color for your button if you are using the ‘Custom’ button setting, but when you run the application, the button will display as a block with no rounded corners. This is because custom buttons don’t really have any default attributes defined. It’s completely up to you to define them. Core Animation layers can help.

Note: Before I get into the source code, I want to remind you that you’ll need to add the QuartzCore framework to your project and #import <QuartzCore/QuartzCore.h> into one of your header files to have Core Animation layer support. I normally add this import statement to my precompiled header (.pch) file.

What Interface Builder doesn’t give you, you can still take advantage of by writing a little bit of code. For example, if you want your custom button to have a red background color with rounded corners and a border, you need to define an outlet in your view controller where the button will be referenced and set the following attributes on the UIButton’s layer.

1
2
3

[[button layer] setCornerRadius:8.0f];
[[button layer] setMasksToBounds:YES];
[[button layer] setBorderWidth:1.0f];

With this code the layer gets a corner radius of 8.0 and the -setMasksToBounds: tells the button’s layer to mask any layer content that comes below it in the layer tree. This is necessary in order for the layer to mask off the rounded corners.

Finally, set the border width to 1.0 to display an outline around the button. The default color for this border is black. You can change it to anything you like using -setBorderColor: on the layer passing it a CGColorRef (e.g. [[UIColor greenColor] CGColor] would give you a green border).

iPhone Development Protip: Rounding corners is possible on any UIView based view. All UIViews have a root layer. You simply call -setCornerRadius: and -setMasksToBounds: on the view’s layer and your corners will be rounded. It is that simple.

You can set the background color in Interface Builder or in code–whichever you prefer. There are two ways to do this in code. One using the layer and one using the UIView call to -setBackgroundColor:.

1
2
3
4

// Core Animation way
[[button layer] setBackgroundColor:[[UIColor redColor] CGColor]];
// UIView way
[button setBackgroundColor:[UIColor redColor]];

The main difference between the two is that the layer works with a CGColorRef while the UIView works with a UIColor. It’s a subtle difference, but one that you should know.

Gradient Buttons Rule

The demo app uses some ultra-bright gaudy looking color gradients just for effect. I suggest you don’t use something so loud and obnoxious. A more subtle difference between colors will look better. Of course this is subjective, so do what you like.

To achieve this gradient look, I use a CAGradientLayer and add it to the root of the button’s layer tree. In fact, for the demo application, I created a UIButton derived class that encapsulates the gradient layer creation and drawing. Here is its implementation:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67

#import "ColorfulButton.h"
 
@implementation ColorfulButton
 
@synthesize _highColor;
@synthesize _lowColor;
@synthesize gradientLayer;
 
- (void)awakeFromNib;
{
    // Initialize the gradient layer
    gradientLayer = [[CAGradientLayer alloc] init];
    // Set its bounds to be the same of its parent
    [gradientLayer setBounds:[self bounds]];
    // Center the layer inside the parent layer
    [gradientLayer setPosition:
                CGPointMake([self bounds].size.width/2,
                       [self bounds].size.height/2)];
 
    // Insert the layer at position zero to make sure the 
    // text of the button is not obscured
    [[self layer] insertSublayer:gradientLayer atIndex:0];
 
    // Set the layer's corner radius
    [[self layer] setCornerRadius:8.0f];
    // Turn on masking
    [[self layer] setMasksToBounds:YES];
    // Display a border around the button 
    // with a 1.0 pixel width
    [[self layer] setBorderWidth:1.0f];
 
}
 
- (void)drawRect:(CGRect)rect;
{
    if (_highColor && _lowColor)
    {
        // Set the colors for the gradient to the 
        // two colors specified for high and low
        [gradientLayer setColors:
                     [NSArray arrayWithObjects:
                            (id)[_highColor CGColor], 
                            (id)[_lowColor CGColor], nil]];
    }
    [super drawRect:rect];
}
 
- (void)setHighColor:(UIColor*)color;
{
    // Set the high color and repaint
    [self set_highColor:color];
    [[self layer] setNeedsDisplay];
}
 
- (void)setLowColor:(UIColor*)color;
{
    // Set the low color and repaint
    [self set_lowColor:color];
    [[self layer] setNeedsDisplay];
}
 
- (void)dealloc {
    // Release our gradient layer
    [gradientLayer release];
    [super dealloc];
}
@end

Now, when I’m creating a button in Interface Builder, I can make it of class ColorfulButton and then set an outlet for it in my view controller.

If I don’t set colors for a gradient, it will just render the button using the background color I specify for it in Interface Builder. If, however, I want to take advantage of the gradient capability, I set the gradient colors in my view controller as shown in the following code snippet:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

- (void)viewDidLoad {
    [super viewDidLoad];
 
    [button1 setHighColor:[UIColor redColor]];
    [button1 setLowColor:[UIColor orangeColor]];
 
    [button2 setHighColor:[UIColor blueColor]];
    [button2 setLowColor:[UIColor lightGrayColor]];
 
    [button3 setHighColor:[UIColor yellowColor]];
    [button3 setLowColor:[UIColor purpleColor]];
 
    [button4 setHighColor:[UIColor cyanColor]];
    [button4 setLowColor:[UIColor magentaColor]];
}

These are the first four buttons you see in the demo app screenshot above. The buttons are declared in the view controller header as show in the following snippet:

1
2
3
4
5
6
7
8
9
10

#import <UIKit/UIKit.h>
#import "ColorfulButton.h"
 
@interface ColorfulButtonsViewController : UIViewController {
    IBOutlet ColorfulButton *button1;
    IBOutlet ColorfulButton *button2;
    IBOutlet ColorfulButton *button3;
    IBOutlet ColorfulButton *button4;
}
@end

The CAGradientLayer supports adding an array of colors and will automatically render them linearly with equal distribution. It will also allow you to specify the distribution pattern, however, to keep it simple here I just use two colors represented by the upper color called highColor and the lower color called lowColor. If you want to add more complex gradients, you could modify my ColorfulButton class to take an array of colors as well. I leave this as an exercise for the reader.

Conclusion

Next time you need to customize a button, consider using Core Animation layers first. You may be surprised at what all you can achieve without having to resort to creating images to use as the button background. I have included the source code for this blog post below. Let me know if you have any thoughts or questions about it in the comments section. Until next time.

Colorful Buttons Demo Project

One of the Core Animation layers available as of Snow Leopard and iPhone OS 3.0, CAShapeLayer provides some interesting attributes that are animatable. The CAShapeLayer enables you to create a layer that renders any arbitrary shape you specify using a path, a CGPathRef. It also enables you to specify a stroke pattern for the stroke that outlines the shape. A stroke is optional, but if you do specify one you may also determine the pattern for it. I do point this part out in the book in Chapter 10, by the way. You use the method, -setLineDashPattern which takes an NSArray of integers. These integers specify painted segments verses unpainted segments. What this means is that if you specify 10, 5 in your array, for example, you will see 10 units of painted segment and 5 units unpainted. Notice I use the term units as opposed to pixels. This is due to the fact that we are to start getting used to the idea of resolution independence. Pixels don’t matter in the same way any more.

The pattern example I used is very simple. You could easily specify something much more complex, say 10, 72, 55, 2, 146, etc. for example. This would mean 10 painted units, followed by 72 unpainted units, followed by 55 painted units, followed by 2 unpainted units, followed by 146 painted units–on and on. You get the picture.

Now for the part I didn’t mention in the book. You can animate this stroke pattern. If you’ve ever used any drawing program you realize that when a rectangular area of the image is in a seleted mode, a dashed pattern stroke outlines that area and the pattern will move like marching ants. To achieve this effect manually actually takes quite a bit of effort, but is quite trivial when done with Core Animation.

What makes it so is another little property of the CAShaperLayer called lineDashPhase. This property specifies the phase of the stroke pattern. The default is zero. Animate this property to see the marching ants effect. If you want the animation to loop perfectly, set the toValue in the animation to the sum of all of the values specified in the lineDashPattern array. The code to animate the lineDashPhase should look something like the following:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

- (IBAction)toggleMarching:(id)sender;
{
    if ([shapeLayer animationForKey:@"linePhase"])
        [shapeLayer removeAnimationForKey:@"linePhase"];
    else {
        CABasicAnimation *dashAnimation;
        dashAnimation = [CABasicAnimation 
                         animationWithKeyPath:@"lineDashPhase"];
 
        [dashAnimation setFromValue:[NSNumber numberWithFloat:0.0f]];
        [dashAnimation setToValue:[NSNumber numberWithFloat:15.0f]];
        [dashAnimation setDuration:0.75f];
        [dashAnimation setRepeatCount:10000];
 
        [shapeLayer addAnimation:dashAnimation forKey:@"linePhase"];
 
    }
}

This is the code we would use to animate a stroke pattern of 10, 5. Notice the sum of those two is 15, which is what the call to setToValue takes in the sample code for the animation. This is important. If the phase doesn’t match the stroke pattern, the animation will jerk back to the starting position. We want the animation to be smooth and seamless.

We set up our CAShaperLayer using the following code:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

- (void)viewDidLoad {
    [super viewDidLoad];
 
    // Create the shape layer
    shapeLayer = [CAShapeLayer layer];
    CGRect shapeRect = CGRectMake(0.0f, 0.0f, 200.0f, 100.0f);
    [shapeLayer setBounds:shapeRect];
    [shapeLayer setPosition:CGPointMake(160.0f, 140.0f)];
    [shapeLayer setFillColor:[[UIColor clearColor] CGColor]];
    [shapeLayer setStrokeColor:[[UIColor blackColor] CGColor]];
    [shapeLayer setLineWidth:1.0f];
    [shapeLayer setLineJoin:kCALineJoinRound];
    [shapeLayer setLineDashPattern:
     [NSArray arrayWithObjects:[NSNumber numberWithInt:10], 
      [NSNumber numberWithInt:5], 
      nil]];
 
 
    // Setup the path
    CGMutablePathRef path = CGPathCreateMutable();
    CGPathAddRect(path, NULL, shapeRect);
    [shapeLayer setPath:path];
    CGPathRelease(path);
 
    // Set the layer's contents
    [shapeLayer setContents:(id)[[UIImage imageNamed:@"balloon.jpg"] CGImage]];
 
    [[[self view] layer] addSublayer:shapeLayer];
 
}

Set the fill color to clear color so we can see through the shape. Set the line width to 1.0. Set the line join to be rounded. Then create the lineDashPattern. Next we create a path that matches the rectangle of our layer as to outline it correctly.

Finally we set the contents of the shape layer to a CGImageRef of the image we load from the bundle called balloon.jpg.

Once we connect the button in Interface Builder to the action called -toggleMarching, we can start and stop the marching ants animation.

Conclusion

The marching ants effect has limited use, but this example code demonstrates once again how Core Animation really simplifies a lot of visual tasks that would have at one time taken a lot more code to achieve. If there is anything I’ve learned while researching and writing the book it’s that Core Animation should be the go-to technology for a vast majority of visualizations on OS X and the iPhone. I find many questions related to the visual aspects of programming for both platforms on Stack Overflow have a very elegant answer in Core Animation. Other solutions exist, but they are often much more cumbersome. Until next time.

Marching Ants Demo Project

The basic process flow goes like this. Clicking the ‘Capture’ button on the user interface calls an IBAction called -saveAnimation. It prompts the user to select an output file for the movie. When the user has selected the file, the animations are created and added to the layer. Next we create a timer that is going to call a function that will grab the current frame and place it into the QTMovie object using -addImage at a specified interval. We set our AppDelegate to also be the delegate for the animation group so that when the animation completes we get notified and can then write our QTMovie object data to disk.

Use An Interesting Animation

First you are going to need an animation that is worth recording. Of course any old animation will do, but we’ll keep it interesting by adding multiple animations to a single layer. I have created four different keyframe animations that we will add to an animation group. The keypaths are “backgroundColor”, “borderWidth”, “position”, and “bounds”. Check the sample code to see how these animations are constructed.

We set the duration for all of the animations to five seconds. We also need to make sure that we set the duration for the group itself, otherwise it will override the five second duration we set for the animations themselves and run in the default 0.25 seconds. The code below shows how the animations are added to the layer.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

- (void)loadAnimations;
{
  CAAnimationGroup *group = [CAAnimationGroup animation];
 
  [group setAnimations:[NSArray arrayWithObjects:[self backgroundColorAnimation],
                          [self borderWidthAnimation],
                          [self positionAnimation],
                          [self boundsAnimation], nil]];
 
  [group setValue:@"mainGroup" forKey:@"name"];
  [group setDuration:5.0];
  [group setAutoreverses:YES];
  [group setDelegate:self];
 
  [layer addAnimation:group forKey:@"group"];  
}

Notice that we have used KVC here to set a name for the animation group. We will use this as a tag later to make sure the animation that triggers our -animationDidStop:finished animation delegate is the correct one. More on that later.

Get Our Movie Ready

Prior to loading the animations, we prompt the user to select a file to write the movie file to. After loading the animations, we start our timer.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

- (IBAction)saveAnimation:(id)sender;
{
  NSSavePanel *savePanel;
 
  savePanel = [NSSavePanel savePanel];
  [savePanel setExtensionHidden:YES];
  [savePanel setCanSelectHiddenExtension:NO];
  [savePanel setTreatsFilePackagesAsDirectories:NO];
 
  if( [savePanel runModal] == NSOKButton )
  {
    movie = [[QTMovie alloc] initToWritableFile:[savePanel filename] error:nil];    
  }
 
  [self loadAnimations];
 
  timer = [NSTimer scheduledTimerWithTimeInterval:1.0/(NSTimeInterval)10.0
                                           target:self
                                         selector:@selector(updateTime:)
                                         userInfo:NULL
                                          repeats:YES];    
 
}

Our -updateTime selector will get called every 1/10th of a second and will grab the current frame to save it to the QTMoive object. Here is the -updateTime code.

1
2
3
4
5
6
7
8
9
10
11

- (void)updateTime:(NSTimer*)theTimer;
{
  NSBitmapImageRep *image = [self getCurrentFrame];
 
  QTTime time = QTMakeTime(1, 10);
  NSDictionary *attrs = [NSDictionary dictionaryWithObject:@"png " forKey:QTAddImageCodecType];
  NSImage *img = [[NSImage alloc] initWithData:[image TIFFRepresentation]];
  [movie addImage:img forDuration:time withAttributes:attrs];
 
  [image release];
}

Obtaining the Current Frame

The code to obtain the current frame is somewhat lengthy, but the concepts are pretty simple. We need to create a graphics context that we can draw into and then draw into it using the presentationLayer of the contenView’s root layer. If you’re not familiar, the presentationLayer provides the current state of the animated fields while “in-flight”.

Core Animation doesn’t provide any callbacks for when a frame is ready to be displayed which is why we are using a timer. This means that we may be capturing more frames than we need to, so getting the right frame rate takes a bit of trial and error, which I have to confess I wasn’t able to get nailed down completely. I’m still working on it and will update here when I get that part figured out. Meanwhile, here is the code for -getCurrentFrame

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39

- (NSBitmapImageRep*)getCurrentFrame;
{
  CGContextRef    context = NULL;
  CGColorSpaceRef colorSpace;
  int bitmapByteCount;
  int bitmapBytesPerRow;
 
  int pixelsHigh = (int)[[[window contentView] layer] bounds].size.height;
  int pixelsWide = (int)[[[window contentView] layer] bounds].size.width;
 
  bitmapBytesPerRow   = (pixelsWide * 4);
  bitmapByteCount     = (bitmapBytesPerRow * pixelsHigh);
 
  colorSpace = CGColorSpaceCreateWithName(kCGColorSpaceGenericRGB);
 
  context = CGBitmapContextCreate (NULL,
                                   pixelsWide,
                                   pixelsHigh,
                                   8,
                                   bitmapBytesPerRow,
                                   colorSpace,
                                   kCGImageAlphaPremultipliedLast);
  if (context== NULL)
  {
    NSLog(@"Failed to create context.");
    return nil;
  }
 
  CGColorSpaceRelease( colorSpace );
 
  [[[[window contentView] layer] presentationLayer] renderInContext:context];
 
  CGImageRef img = CGBitmapContextCreateImage(context);
  NSBitmapImageRep *bitmap = [[NSBitmapImageRep alloc] initWithCGImage:img];
  CFRelease(img);
 
  return bitmap;
 
}

Notice that we are calling -renderInContext on the presentationLayer of the window’s contentView’s root layer. If we were only to render our animated layer, we wouldn’t be able to see the animation as it will only render the containing rectangle of the animating layer.

Finishing Up

Finally we need to write the movie data out to disk. The QTMovie object provides a single call to do so, but we need a way to know when the animation has finished so we can make this call. When we created our animation group, we set its delegate to our AppDelegate which will cause the delegate method -animationDidStop:finished to get called. Remember that setting the delegate for each of the individual animations gets ignored when you are using an animation group. We implement the -animationDidStop:finished delegate as shown below.

1
2
3
4
5
6
7
8
9
10
11
12

- (void)animationDidStop:(CAAnimation *)theAnimation finished:(BOOL)flag;
{
  NSLog(@"Animation stopped: %@", theAnimation);
 
  id name = [theAnimation valueForKey:@"name"];
  if( name )
    if( [name isEqualToString:@"mainGroup"] )
    {
      [movie updateMovieFile];
      [timer invalidate];
    }
}

The first thing we do is check the animation tag we set when creating the animation group. This really isn’t necessary in this code example since there is only one animation that is going to use it, but this code shows you how to differentiate if you were to use multiple animations or groups and wanted to know when each of them finished animating.

The call to -updateMovieFile writes the data to disk and we now have a QuickTime movie that will play our animation. Open the resulting file in QuickTime or just invoke QuickLook to see the result.

Conclusion

Maybe you can think of a use for this kind of thing. I haven’t yet–other than for writing a blog post of course. Shoot me your thoughts and comments in the comments section. Until next time.

CA Animation Capture Demo Project

Differentiating Keypath From Key

Each core animation layer contains a dictionary that enables you to add and remove animations based on a key that you define. I created a layer-backed view that receives mouse clicks and animates the position of the layer toward that mouse click.

1
2
3
4
5
6
7
8
9
10
11

- (void)mouseDown:(NSEvent*)event;
{
    CABasicAnimation *animation = [CABasicAnimation animationWithKeyPath:@"position"];
    [animation setDelegate:self];
    [animation setFromValue:[NSValue valueWithPoint:previousValue]];
    previousValue = NSMakePoint([event locationInWindow].x, [event locationInWindow].y);
    [animation setToValue:[NSValue valueWithPoint:previousValue]];
    [animation setDuration:2.0];
 
    [objectLayer addAnimation:animation forKey:@"follow"];
}

Notice that when I create the animation, I am creating it with a keypath–in this case position. The keypath is different from the key by which we store the animation in the animations dictionary contained by the layer. In the sample code I add the animation to the dictionary using a key called “follow”. This could be any string that is meaningful to keep track of the animation in question. Consider it a tag.

I only make this distinction because I’ve seen some confusion about the difference between the two. To summarize, the keypath specifies which layer property you want to animate while the key is the key by which you will store, recall, and delete an animation from the animation dictionary contained by the layer.

Adding The Animation, Again

In the code above, you’ll also notice that we are adding the animation to the layer for the same key each time we receive a -mouseDown. If we are setting a new object in the dictionary each time, then how are we able to keep track of whether or not the animation finished?

By setting a delegate for the animation, we can be notified when animation has been removed from the animations dictionary. We implement the -animationDidStop:finished delegate.

1
2
3
4

- (void)animationDidStop:(CAAnimation *)theAnimation finished:(BOOL)flag
{
    NSLog(@"Animation interrupted: %@", (!flag)?@"Yes" : @"No");
}

There are several things going on here. When we call [objectLayer addAnimation:animation forKey:@"follow"]; in our -mouseDown code, the animation that was there previously, if there was one, is replaced by the new one. If the user clicked on the screen before the animation completed, the animation is removed and the delegate -animationDidStop gets called. If instead of clicking the mouse again before the current animation is finished, you just let it finish, the animation is also removed from the dictionary because this is the default behavior for an animation. If you don’t specify [animation setRemovedOnCompletion:NO] explicitly, the animation will be removed.

Changing Direction While In Flight

When the view receives a click the basic animation is re-created and added to the layer for the key “follow” again. The fromValue field needs set again, but if you click another spot on the view before the animation finishes, what value do you set it to? If you set it to the previous value, it will simply animate from the previous location which won’t look right. You want it to change direction rather than starting from the previous start location.

If instead of using a basic animation in our example code we had simply opted to use the animator proxy, calling -setPosition on the layer would do this for us. The problem is that we want to be able to demonstrate the -animationDidStop delegate which we can’t do with the animator proxy. So how do we provide this functionality of changing direction in flight?

Look no further than the presentationLayer which is accessible through our layer object. We can obtain the last location of our “position” parameter by first getting the presentationLayer and getting the position from it instead. We’ve modified our -mouseDown event to reflect this change.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

- (void)mouseDown:(NSEvent*)event;
{
  CABasicAnimation *animation = 
          [CABasicAnimation animationWithKeyPath:@"position"];
  [animation setDelegate:self];
 
  // Get the presentationLayer
  CALayer *p = (CALayer*)[objectLayer presentationLayer];
  CGPoint position = [p position];
  NSValue *prevVal = [NSValue valueWithPoint:
                      NSPointFromCGPoint(position)];
 
  [animation setFromValue:prevVal];
 
  [animation setToValue:[NSValue valueWithPoint:[event locationInWindow]]];
  [animation setDuration:2.0];
  [animation setRemovedOnCompletion:NO];
 
  [objectLayer addAnimation:animation forKey:@"follow"];
}

Now, when we click in our view, the animation changes directions from its current location in the animation. The presentationLayer provides you with current values of whatever field you are currently animating. If a value is not being animated, you will get the same value as what is in the main layer.

Conclusion

It’s very handy to have a way to know when an animation is completed. You simply set your app delegate to be your animation’s delegate and when the animation completes, -animationDidStop:finished gets called conveying through the finished flag whether the animation was interrupted or not. To get our in flight values when the animation hasn’t completed, we simply look at the presentationLayer. These features of Core Animation are very powerful. Given the choice I would like to see the presentationLayer values become KVO compliant as this would let you monitor changes in real time, but being able to read the current value at any given time is a great capability in its own right. It’s very cool technology. Until next time.

Follow Me Demo Project

The Slider Value

We connect a slider to an IBAction in xcode that will get called continuously as we have checked the checkbox called ‘Continuous’ in Interface Builder. We can read the slider value and apply it to our animation that we use to rotate the layer. In interface builder, we have specified a minimum value of -180, a maximum value of 180 and a current value (our starting value) of 0 on the slide control. When the slider is moved, the rotation updates as does the value of our text layer.

While it is coincidental that the demo application sort of looks like a pumpkin, it seems appropriate considering the time of year.

Layer Rotate

Rotation Animation

Rotating a layer is very simple. You just need to create an animation with “transform.rotation.z” as your keypath and then you can set from and to values that the animation will rotate between. We simply keep track of the last value we rotated (previousValue in the code) to and use this as our from value in the next change to the slider.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

- (CAAnimation*)rotateAnimation;
{
  CABasicAnimation * animation;
  animation = [CABasicAnimation 
               animationWithKeyPath:@"transform.rotation.z"];
 
  [animation setFromValue:DegreesToNumber(previousValue)];
  [animation setToValue:DegreesToNumber([slider floatValue])];
 
  [animation setRemovedOnCompletion:NO];
  [animation setFillMode:kCAFillModeForwards];
 
  previousValue = [slider floatValue];
 
  return animation;
}

When our -sliderChange function gets called when the user moves the slider, we add the animation to the layer again using the key “rotate”. This is done first in our -awakeFromNib call and then in the -sliderChange call.

1
2
3
4
5
6

- (IBAction)sliderChange:(id)sender;
{
  [degreesTextLayer setString:[NSString stringWithFormat:@"%f", [slider floatValue]]];
  [needleLayer addAnimation:[self rotateAnimation] forKey:@"rotate"];
  [needleLayer setNeedsDisplay];
}

You will notice that we call -setNeedsDisplay on the layer. This is necessary as we have implemented the delegate method -drawLayer:inContext. We use this method to draw the vertical and horizontal black lines that intersect in the center of the circle layer.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

- (void)drawLayer:(CALayer *)layer inContext:(CGContextRef)context;
{
  if( layer == needleLayer )
  {
      CGMutablePathRef path = CGPathCreateMutable();
 
      CGPathMoveToPoint(path,NULL, [view bounds].size.width/2.0, 0.0);
      CGPathAddLineToPoint(path, NULL, [view bounds].size.width/2.0, [view bounds].size.height);
 
      CGPathMoveToPoint(path,NULL, 0.0, [view bounds].size.height/2.0);
      CGPathAddLineToPoint(path, NULL, [view bounds].size.width, [view bounds].size.height/2.0);
 
      CGColorRef black =
              CGColorCreateGenericRGB(0.0, 0.0, 0.0, 1.0);
      CGContextSetStrokeColorWithColor(context, black);
      CFRelease(black);
 
      CGContextBeginPath(context);
      CGContextAddPath(context, path);
 
      CGContextSetLineWidth(context, 3.0);
 
      CGContextStrokePath(context);
 
      CFRelease(path);
 
  }  
}

Retaining The Rotation Position

There are two parameters of an animation that must be set otherwise the layer transform will just revert back to the original rotation. These two lines of code in our animation creation code ensure that what you see remains sticky when the value is changed.

[animation setRemovedOnCompletion:NO];
[animation setFillMode:kCAFillModeForwards];

Now, when the slider moves, the vertical and horizontal lines will stay in the correct rotation position. If you comment those two lines of code out in the demo project, you will see that while the rotation layer animates, it jumps right back to its original rotation as soon as the animation completes.

Conclusion

You will likely find many uses for this type of control. You could of course control the rotation based upon some other value or control other than a slider, but this code demonstrates how simple it is to rotate a layer based upon user input. Until next time.

Layer Rotate Demo Project

1
2
3
4
5
6
7

[[window contentView] setWantsLayer:YES];
[qcView setWantsLayer:YES];
 
CATextLayer *text = [CATextLayer layer];
[text setString:@"hello World"];
[text setFrame:NSRectToCGRect([qcView frame])];
[[qcView layer] addSublayer:text];

This code would allow the text layer to show up, however, the Quartz Composition was gone and all I got was a gray window with the “hello World” text on it.

Two Heads Better Than One

This is what I love about NSCoder Night. You get some Cocoa geeks together and the collective wisdom starts this synergy where we can bounce things off each other and a solution emerges.

Chad, in the mean time, had been searching the web for some examples and at about the time I started to wonder if there was a Core Animation specific layer for Quartz Compositions, he said, “QCCompositionLayer”. Marcus and I were both at that point thinking, “ah, I should have thought of that since there are Core Animation layers to do everything else media related.”

I then went to town slinging some code and here is what I came up with:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

- (void)awakeFromNib;
{
  [[window contentView] setWantsLayer:YES];
 
  QCCompositionLayer *layer = [[QCCompositionLayer alloc] 
            initWithFile:@"/Developer/Examples/Quartz Composer/Plugins/OpticalFlow/Teapotii.qtz"];
 
  [layer setFrame:NSRectToCGRect([[window contentView] frame])];
 
  CATextLayer *text = [CATextLayer layer];
  [text setString:@"hello World"];
  [text setFrame:NSRectToCGRect([[window contentView] frame])];
  [ayer addSublayer:text];
 
  [[[window contentView] layer] addSublayer:layer];    
}

I got rid of the QCView altogether and just added the Quartz Composer layer to the sublayers of the window’s content view. The Quartz Composition in a QCCompositionLayer begins to play automatically, so really this code is all there is to it. And notice that the text overlay works as well. You could really add anything you wanted in a Core Animation layer at this point.

Your Own Composition

If you’re anything like me this will whet your appetite for playing with some very cool technology. I decided to create my own Quartz Composition and include that in the demo project. The demo composition takes the vide input of your iSight camera and applies the image to each side of a cube. It then rotates the cube. Creating the composition was pretty easy with a cursory reading of Apple’s Quartz Composer User Guide. It’s quite helpful.

You can take a look at the Quartz Composition in Quartz Composer. The demo application has two .qtz files in it. You can just double click either of those from the Finder to see what I did. The one I’m using in the demo app is the one called “VideoCub.qtz”. You can switch it in the code to see the other one as well, which is a quad of four iSight inputs.

VideoCube QC Editor

Quartz Composer Layer

You can see I added a CATextLayer to the QCCompositionLayer which displays the words, “hello World”. I also applied a Gaussian blur filter to the whole thing so you can see how easy it is to add filters as well. Here is all of the code needed to make this work.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

- (void)awakeFromNib;
{
    [[window contentView] setWantsLayer:YES];
 
    NSString *path = [[NSBundle mainBundle] 
                      pathForResource:@"VideoCube" 
                      ofType:@"qtz"];
 
    QCCompositionLayer *layer = 
        [[QCCompositionLayer alloc] initWithFile:path];
 
    [layer setFrame:NSRectToCGRect([[window contentView] frame])];
 
    CATextLayer *text = [CATextLayer layer];
    [text setString:@"hello World"];
    [text setFrame:NSRectToCGRect([[window contentView] frame])];
    [layer addSublayer:text];
 
    CIFilter *blurFilter = 
    [CIFilter filterWithName:@"CIGaussianBlur"];
 
    [blurFilter setDefaults];
    [blurFilter setValue:[NSNumber numberWithFloat:2.0] 
                  forKey:@"inputRadius"];
    [blurFilter setName:@"blur"];
 
    [layer setFilters:[NSArray arrayWithObject:blurFilter]];
 
 
    [[[window contentView] layer] addSublayer:layer];
}

What’s even more exciting to me is that if you know a bit of OpenGL, you can do all kinds of other manipulations of the image since QCCompositionLayer inherits from CAOpenGLLayer. Take a close look at -drawInCGLContext in the CAOpenGLLayer API docs. There is a ton of great potential there.

Conclusion

The conclusion is that Quartz Compositions are very cool and they are now even cooler since you can work with them in Core Animation. Take a look a the Quartz Composer guide and start building your own compositions that you can easily incorporate into your Core Animation based applications. Until next time.

Quartz Composition Layer Demo Project

Getting two technologies to work together can be a challenge especially when the bridges between the two are not necessarily clearly laid out in documentation. As I pointed out Apple provides some excellent sample code to help you along, but there is no hand-holding approach to any of it. I actually appreciate that having come from the Windows world as it seems that there all you get sometimes is hand-holding where Microsoft doesn’t trust you, the developer to figure things out and really own what you’re doing. But I digress (wouldn’t be a CIMGF post if I didn’t dig on MS a bit).

Like peanut butter and chocolate, what you get when you put together QuickTime and OpenGL is something greater than either of them left on their own (ok, this is subjective. Not everyone likes peanut butter and chocolate together, but again, I digress).

If you read the Core Video Programming Guide from Apple, you see they provide the reasons for using Core Video:

CoreVideo is necessary only if you want to manipulate individual video frames. For example, the following types of video processing would require CoreVideo:

• Color correction or other filtering, such as provided by Core Image filters
• Physical transforms of the video images (such as warping, or mapping on to a surface)
• Adding video to an OpenGL scene
• Adding additional information to frames, such as a visible timecode
• Compositing multiple video streams

If all you need to do is display a movie, you should simply use either a QTMovieView or, if you want to stick with the Core Animation route, use a QTMovieLayer. They both function similarly, however, the view provides a lot of features that you won’t have to implement in the UI yourself such as a scrubber or play/pause buttons. Plus the view is very fast and efficient. I’m in the process of exploring performance differences between the two, but I will save my comments about that for another post.

For our example code we are most interested in the third point above–adding video to an OpenGL scene. It seems that new QuickTime developers often want to know how to manipulate movie images before displaying them. Often this leads them to pursue adding sub-views to the movie view which can become a big mess. Because we are using OpenGL, doing other drawing on the scene is very fast. I won’t kid you. OpenGL is a pain. I don’t know anybody who loves it, but everybody respects it because of its raw speed.

Point number five above–compositing multiple video streams–is also interesting. While I won’t be covering it in this post, I will say that it makes a world of difference performance wise if you composite the movies into a OpenGL scene. If you’ve ever tried to run multiple videos simultaneously in two different views or layers, it can get pretty herky jerky. You can see why it is necessary to use OpenGL instead.

The OpenGL QuickTime Two Step

Ok, it actually will take more than two steps, however, when you are working with Core Animation layers things get a whole lot easier than they are for rendering a movie in an NSOpenGLView. Here is what you get for free, as the kids say.

• You don’t have to set up the OpenGL context. It is already available for you to send your OpenGL calls to.
• The viewport for display is already configured
• You don’t need to set up a display link callback

What took over 400 lines of code when rendering a QuickTime movie with no filters to an NSOpengGLView now only takes around 150 lines. Any time you can reduce code to something simpler, it makes life easier. It also makes it much easier to grok, in my opinion.

There really are two primary steps you take when using a CAOpenGLLayer. First you check to see if you should draw. Then, depending upon the answer, drawInCGLContext gets called or doesn’t. Really thats it. Determining whether or not you should draw depends upon what you are trying to do. In our case, we only want to draw if all of the following are true:

• The movie is actually playing back
• The visual context for the movie has been initialized
• The visual context has a new image ready to be rendered

If all of these are true, then our call to canDrawInCGLContext returns YES. Here is the code I use to check these contraints in canDrawInCGLContext:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41

- (BOOL)canDrawInCGLContext:(CGLContextObj)glContext 
                pixelFormat:(CGLPixelFormatObj)pixelFormat 
               forLayerTime:(CFTimeInterval)timeInterval 
                displayTime:(const CVTimeStamp *)timeStamp
{ 
    // There is no point in trying to draw anything if our
    // movie is not playing.
    if( [movie rate] <= 0.0 )
        return NO;
 
    if( !qtVisualContext )
    {
        // If our visual context for our QTMovie has not been set up
        // we initialize it now
        [self setupVisualContext:glContext withPixelFormat:pixelFormat];
    }
 
    // Check to see if a new frame (image) is ready to be draw at
    // the time specified.
    if(QTVisualContextIsNewImageAvailable(qtVisualContext,timeStamp))
    {
        // Release the previous frame
        CVOpenGLTextureRelease(currentFrame);
 
        // Copy the current frame into our image buffer
        QTVisualContextCopyImageForTime(qtVisualContext,
                                        NULL,
                                        timeStamp,
                                        &currentFrame);
 
        // Returns the texture coordinates for the part of the image that should be displayed
        CVOpenGLTextureGetCleanTexCoords(
                            currentFrame, 
                            lowerLeft, 
                            lowerRight, 
                            upperRight, upperLeft);
        return YES;
    }
 
    return NO;
}

The call to setup the visual context is where we are associating the QuickTime movie itself with a QTVisualContextRef object which is what OpenGL needs to draw the current frame. We will then use this object to load image data into a CVImageBufferRef which can be used for rendering with OpenGL. Here is the code to set up the visual context.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

- (void)setupVisualContext:(CGLContextObj)glContext 
           withPixelFormat:(CGLPixelFormatObj)pixelFormat;
{
    OSStatus			    error;
 
    NSDictionary	    *attributes = nil;
    attributes = [NSDictionary dictionaryWithObjectsAndKeys:
                  [NSDictionary dictionaryWithObjectsAndKeys:
                   [NSNumber numberWithFloat:[self frame].size.width],
                   kQTVisualContextTargetDimensions_WidthKey,
                   [NSNumber numberWithFloat:[self frame].size.height],
                   kQTVisualContextTargetDimensions_HeightKey, nil], 
                  kQTVisualContextTargetDimensionsKey, 
                  [NSDictionary dictionaryWithObjectsAndKeys:
                   [NSNumber numberWithFloat:[self frame].size.width], 
                   kCVPixelBufferWidthKey, 
                   [NSNumber numberWithFloat:[self frame].size.height], 
                   kCVPixelBufferHeightKey, nil], 
                  kQTVisualContextPixelBufferAttributesKey,
                  nil];
 
    // Create our quicktimee visual context
    error = QTOpenGLTextureContextCreate(NULL,
                                         glContext,
                                         pixelFormat,
                                         (CFDictionaryRef)attributes,
                                         &qtVisualContext);
 
    // Associate it with our movie.
    SetMovieVisualContext([movie quickTimeMovie],qtVisualContext);
}

Next we check to see if there is an image ready using:

1

if(QTVisualContextIsNewImageAvailable(qtVisualContext,timeStamp))

And then we copy the image to our CVImageBufferRef with:

1
2
3
4
5

// Copy the current frame into our image buffer
QTVisualContextCopyImageForTime(qtVisualContext,
                                NULL,
                                timeStamp,
                                &currentFrame);

Now it’s all a matter of rendering the frame for the current time stamp.

But Wait! What TimeStamp?

If you asked this question, then you are a very astute reader. In order to obtain the next image, we simply passed the CVTimeStamp parameter, timeStamp to our call to QTVisualContextCopyImageForTime. But how do we even have a timestamp? Isn’t that something we need to get from a display link? If you’re asking what is a display link at this point, take a look at the Core Video Programming Guide which states:

To simplify synchronization of video with a display’s refresh rate, Core Video provides a special timer called a display link. The display link runs as a separate high priority thread, which is not affected by interactions within your application process. In the past, synchronizing your video frames with the display’s refresh rate was often a problem, especially if you also had audio. You could only make simple guesses for when to output a frame (by using a timer, for example), which didn’t take into account possible latency from user interactions, CPU loading, window compositing and so on. The Core Video display link can make intelligent estimates for when a frame needs to be output, based on display type and latencies.

I will provide a more complete answer to the question in the future as I am still studying it myself, however, I will mention that a display link callback is unnecessary in this context as the CAOpenGLLayer is providing this for us. The timestamp field is all we need in order to get the current frame assuming that the movie is playing back.

Drawing The Frame

There is a special group of people who really get OpenGL. I salute all of you to whom this applies. You are amazing. I, however, only write as much of it as necessary and you’ll see that most of the code I have here is simply a copy and paste from sample code I got from Apple. I am starting to understand it more and more, however, it makes my brain hurt. Here is my drawing code for when a frame is ready to be rendered.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64

- (void)drawInCGLContext:(CGLContextObj)glContext 
             pixelFormat:(CGLPixelFormatObj)pixelFormat 
            forLayerTime:(CFTimeInterval)interval 
             displayTime:(const CVTimeStamp *)timeStamp
{
    NSRect    bounds = NSRectFromCGRect([self bounds]);
 
    GLfloat 	minX, minY, maxX, maxY;        
 
    minX = NSMinX(bounds);
    minY = NSMinY(bounds);
    maxX = NSMaxX(bounds);
    maxY = NSMaxY(bounds);
 
    glMatrixMode(GL_MODELVIEW);
    glLoadIdentity();
    glMatrixMode(GL_PROJECTION);
    glLoadIdentity();
    glOrtho( minX, maxX, minY, maxY, -1.0, 1.0);
 
    glClearColor(0.0, 0.0, 0.0, 0.0);	     
    glClear(GL_COLOR_BUFFER_BIT);
 
    CGRect imageRect = [self frame];
    // Enable target for the current frame
    glEnable(CVOpenGLTextureGetTarget(currentFrame));
    // Bind to the current frame
    // This tells OpenGL which texture we are wanting 
    // to draw so that when we make our glTexCord and 
    // glVertex calls, our current frame gets drawn
    // to the context.
    glBindTexture(CVOpenGLTextureGetTarget(currentFrame), 
                  CVOpenGLTextureGetName(currentFrame));
    glMatrixMode(GL_TEXTURE);
    glLoadIdentity();
    glColor4f(1.0, 1.0, 1.0, 1.0);
    glBegin(GL_QUADS);
 
    // Draw the quads
    glTexCoord2f(upperLeft[0], upperLeft[1]);
    glVertex2f  (imageRect.origin.x, 
                 imageRect.origin.y + imageRect.size.height);
    glTexCoord2f(upperRight[0], upperRight[1]);
    glVertex2f  (imageRect.origin.x + imageRect.size.width, 
                 imageRect.origin.y + imageRect.size.height);
    glTexCoord2f(lowerRight[0], lowerRight[1]);
    glVertex2f  (imageRect.origin.x + imageRect.size.width, 
                 imageRect.origin.y);
    glTexCoord2f(lowerLeft[0], lowerLeft[1]);
    glVertex2f  (imageRect.origin.x, imageRect.origin.y);
 
    glEnd();
 
    // This CAOpenGLLayer is responsible to flush
    // the OpenGL context so we call super
    [super drawInCGLContext:glContext 
                pixelFormat:pixelFormat 
               forLayerTime:interval 
                displayTime:timeStamp];
 
    // Task the context
    QTVisualContextTask(qtVisualContext);
 
}

If you’re not familiar with OpenGL it would help you to know that it’s all about the current state. What does this mean? Well, simply put, it means that the call you are making right now, applies to whatever state the context is in. These two calls are what are the most important for our purposes.

1
2
3

glEnable(CVOpenGLTextureGetTarget(currentFrame));
glBindTexture(CVOpenGLTextureGetTarget(currentFrame), 
                  CVOpenGLTextureGetName(currentFrame));

With these two calls we have told OpenGL which texture to use. Now, every subsequent call applies to this texture until the state is changed to something else. So now, when we set a color or draw a quad, it applies to the texture that has been set here.

Conclusion

I love both of these technologies, QuickTime and OpenGL. They are so powerful. It’s harnessing the power that’s the trick. I’ve got some other ideas for some related posts that I plan to cover in the weeks to come, but this was a real breakthrough for me. With the help of John Clayton, Jean-Daniel Dupas, and David Duncan on the cocoa-dev list, I was able to get the sample code put together for this post. Feel free to ask questions in the comments. I will do my best to answer, but I’m still pretty new to these technologies. Write some code yourself and have fun. This is really exciting stuff. Until next time.

About The Demo Code

John Clayton has some issues getting the code to work on his Mac Pro. I successfully ran it on my MacBook Pro, and the family iMac without any issues. Anyhow, we’re not sure what the problem is, so if you do run into trouble, let me know. Maybe we can figure it out. Meanwhile we’re investigating it as we have time.

Update: John Clayton figured it out. Apparently the visual context needs to be reset because the pixel format is not correct on the first run. We just reset the visual context now in the call to -copyCGLContextForPixelFormat and everything seems happy. The demo code has been updated to reflect the change.

Quicktime CAOpenGLLayer Demo

I’m not sure this is the best name for it as some people may think we mean the ripple effect you see when you drop a new Dashboard widget on the screen, but what we mean is the way in which the Dashboard widgets that are already employed in Dashboard fly in and out of view when you enable and disable Dashboard. Enable Dashboard now and watch your widgets fly in from offscreen. Then disable it and watch the widgets fly out again. This is what we mean by the Dashboard effect and this is what we set out to duplicate.

Download the demo project from here: Dashboard Effect Sample Project. When you build and run it, press Command-N to add additional layers to the screen and then press Command-E to see the effect. Press Shift-Command-E to see the effect in slow motion.

Scaling Sublayers Is Automatic In Core Animation

When you create a Core Animation layer tree, your layer transformation cascades the tree automatically, so we really only have to create sublayers and add them to a top level layer upon which we perform the scaling transformation. Before we do that, though, go ahead and enable Dashboard in Mac OS X so you can see the effect that we’re going for. Hold the shift key while you enable/disable Dashboard and you’ll see it animate slowly. In my demo project I’ve simply created a BOOL variable to keep track of whether we are scaling up or down and set that on each invocation of the scaling function. Here is what the function looks like:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

- (void)doItIn:(float)duration
{
    // Set the animation duration.
    [[NSAnimationContext currentContext] setDuration:duration];
 
    if( scaleUp )
    {
        // Scale everything (x, y, and z) by a factor of factor (static variable) and reduce the opacity
        CATransform3D transform = CATransform3DMakeScale(factor, factor, factor);
        [mainLayer setTransform:transform];
        mainLayer.opacity = 0.0f;
        scaleUp = NO;
    }
    else
    {
        // Scale the rect back down to the orignal and bring up the opacity
        CATransform3D transform = CATransform3DMakeScale(1.0f, 1.0f, 1.0f);
        [mainLayer setTransform:transform];
        mainLayer.opacity = 1.0f;
        scaleUp = YES;
    } 
}

In this function we pass in the duration we want to use. This is predicated on whether or not the user was holding the shift key as we want to try to duplicate the effect of Dashboard as close as possible. Take a look at the two IBAction(s) we’ve declared in AppDelegate.h in the sample project to see it getting called.

Adding Random Layers

I’ve added another menu action as well as keyboard shortcut (Command-N) that will allow you to add new layers at random points with random sizes and colors onto the screen. Just press Command-N several times and then press Command-E again to see the effect. Notice that I’ve also dimmed the background behind the front layers (which are our representation of Dashboard widgets). That dimmed backing layer is actually the only layer we animate as you see in the previous code example. Here is how the layers (widgets) get created:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41

- (IBAction)addNewLayer:(id)sender;
{
 
    CALayer *layer = [CALayer layer];
 
    // Set some random colors, and the border width
    float r = SSRandomFloatBetween(1.00, 0.00);
    float g = SSRandomFloatBetween(1.00, 0.00);
    float b = SSRandomFloatBetween(1.00, 0.00);
 
    layer.backgroundColor = CGColorCreateGenericRGB(r,g,b,1.0f);
    layer.borderColor=CGColorCreateGenericRGB(b,r,g,1.0f);
    layer.borderWidth=4.0;
 
    // Create a random rectangle with a size between 300 and 200 pixels.
    NSRect rect = NSZeroRect;
    rect.size = NSMakeSize( SSRandomFloatBetween( 300.0, 200.0 ), SSRandomFloatBetween( 300.0, 200.0 ));
 
    // Calculate random origin point
    rect.origin = SSRandomPointForSizeWithinRect( rect.size, [window frame] );
 
    // Set the layer frame to our random rectangle.
    layer.frame = NSRectToCGRect(rect);
    layer.cornerRadius = rect.size.height/5;
 
    // Create a text layer to add so we can see text scale too.
    CATextLayer *textLayer = [CATextLayer layer];
    textLayer.string = @"Hello World!";
    CGFontRef font = CGFontCreateWithFontName((CFStringRef)@"Helvetica");
    textLayer.font = font;
    textLayer.frame = CGRectMake(10.0, 100.0, 195.0, 35.0);
    CGFontRelease(font);
 
    // Use the same color for the text that we used for the border.
    textLayer.foregroundColor = layer.borderColor;
    // Add the text layer
    [layer addSublayer:textLayer];
 
    // Insert the layer into the root layer
    [mainLayer addSublayer:layer];
}

Note: I grabbed these convenience functions, SSRandomFloatBetween and SSRandomPointForSizeWithinRectfrom the <ScreenSaver/ScreenSaver.h> library. They provide a simple way to get random points and rectangles for placing new layers on the screen. You’ll need to #import <ScreenSaver/ScreenSaver.h> to use them in your projects.

Trans-Parent

The parent window in our application, is a borderless window with a transparent background color. You’ll see the window class we’ve created called BorderlessWindow in the project. This simply removes the borders and makes the backing window transparent so all we see are Core Animation layers. I used a similar technique in my last post. Again, I haven’t taken the time to see if there is a way to click through the window. As it stands, you can see through the window, but when you try to click what’s behind it, no dice.

Conclusion

Well, that’s about it for this one. It’s pretty simple thanks to Core Animation. Marcus and I started down a path where we were trying to figure out all of the math ourselves in order to scale and move each of the CALayer frames individually. As it turns out, all of the hard work is done for us where all we had to do was specify the scaleX, scaleY, and scaleZ to the CATransform3DMakeScale function and voila, instant layer scaling with cascading. I’m continually impressed by all Apple has provided to developers to use in Core Animation. It’s a great library.

Getting Ready For The Image

The focus of this tutorial is Core Animation and specifically how to use a QTMovieLayer as well as animating an image across the screen using a CALayer. I, therefore, will not spend any time addressing NSOperation and I think we’ve covered this adequately on this site. I would suggest, however, that you familiarize yourself with Marcus’ post on NSOperation as he discusses calling back into the main thread once the NSOperation has completed. I employ Marcus’ technique in this project so that I can be notified when the image I’m wanting to animate is ready.

You can download the demo project for this post from here: Movie Image Flick Demo Project

Download the project and run it. It will prompt you to select a QuickTime movie to play. Once the movie starts playing, tap your spacebar and watch the images pop off of the movie and animate to random places on the screen. Tap the spacebar quickly to see the effect work in rapid succession.

As in my NSOperation post, I want the video playback to be completely flicker free. I achieve this by obtaining a reference to a copy of the QTMovie object from which I obtain the image at the given time. If you take a look at my main: function in my NSOperation derived class, you’ll see how I am notifying the main thread that it may now do something with the image I’ve obtained.

ImageGrabber.m:main

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

- (void)main;
{
    if( movie )
    {
        NSImage* image;
        image = [movie frameImageAtTime:time 
                      withAttributes:imageAttrs error:nil];
        [image retain];
 
        [[AppDelegate shared] performSelectorOnMainThread:@selector(imageReady:)
                                               withObject:image
                                            waitUntilDone:YES];
        [image release];
    }
 
}

In the second last line of the function, notice I am calling back into my main thread and letting the app delegate know that the image is ready. I am also handing the image to the imageReady: function. This is very convenient for what we need to do next. But first, let’s discuss drawing the layers with no backing view or window.

Drawing Layers In Thin Air

This project employs a trick that makes it appear as if the layers are being drawn without a backing view. This is, of course, not really possible, so instead we do a little trick. I achieved this effect by creating a borderless window with a transparent background. As usual, I want to give credit where credit is due. Lucas Newman answered a question I posted on Scott Stevenson’s blog to find out how Lucas did this in his demo project a the Silicon Valley CocoaHeads meeting on Core Animation. You simply create your own NSWindow derived class and override the initWithContentRect: method. Here is the resulting initialization code I came up with from his suggestion.

BorderlessWindow.m:initWithContentRect

1
2
3
4
5
6
7
8
9
10
11
12
13
14

- (id) initWithContentRect: (NSRect) contentRect
                 styleMask: (unsigned int) aStyle
                   backing: (NSBackingStoreType) bufferingType
                     defer: (BOOL) flag
{
    if (![super initWithContentRect: contentRect 
                 styleMask: NSBorderlessWindowMask 
                   backing: bufferingType 
                   defer: flag]) return nil;
    [self setBackgroundColor: [NSColor clearColor]];
    [self setOpaque:NO];
 
    return self;
}

The only issue with using a transparent backing window/view is that you cannot click through it even though it looks like you ought to be able to. There is probably a way to pass the click on to the next front most window, but I haven’t yet researched this. I’ll let you know when I find the answer, or if you know the answer, post it in the comments.

Rapid Fire Image Animation

I created a method to initialize my NSOperation derived objects and hand them off to the NSOperationQueue. I hooked it up to the spacebar and can then tap the spacebar as quickly as possible and watch the images just pop off the playing movie. Here is my flickIt: function.

AppDelegate.m:flickIt

1
2
3
4
5
6
7
8
9
10
11
12

- (IBAction)flickIt:(id)sender;
{
    ImageGrabber *grabber = [[ImageGrabber alloc] init];
 
    [grabber setTime:[movie currentTime]];
    // Hand off the background movie to the NSOperation derived
    // object
    [grabber setMovie:movieBak];
 
    // Add the oepration to the queue. It will be run immediately.
    [queue addOperation:grabber];
}

This function creates the NSOpeartion derived objects and passes a reference to the current time in the playing movie as well as a reference to the background movie that I use to pull the image data from. Remember that this object is copied from the original QTMovie object and is used to keep from needing to pull the image data from the QTMovie object that is actually playing in the QTMovieLayer. Pulling the image from the QTMovie object that is being used for playback would cause the playback to stutter.

As stated earlier, when my image is ready, the NSOperation derived object, ImageGrabber, calls back into the main thread calling the function called imageReady:. Here is its implementation.

AppDelegate.m:imageReady

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

- (void)imageReady:(NSImage*)image;
{    
    [[NSAnimationContext currentContext] setDuration:1.5f];
 
    // Save off the rectangle of the ready layer before
    // it gets animated. We will use this to reset the
    // ready layer.
    CGRect prevRect = [readyLayer frame];
 
    // Convert the NSImage to a CGImageRef
    CGImageRef imageRef = [self nsImageToCGImageRef:image];
    CFRetain(imageRef);
    readyLayer.contents = (id)imageRef;
    readyLayer.backgroundColor = CGColorCreateGenericRGB(0.0f,0.0f,0.0f,1.0f);
    readyLayer.borderColor = CGColorCreateGenericRGB(0.45f,0.45f,0.45f,1.0f);
    readyLayer.borderWidth = 4.0f;
 
    // Grab a random rectangle on the screen where our image
    // layer will animate to.
    CGRect randRect = [self getRandomRect:prevRect];
    [readyLayer setFrame:randRect];
    [readyLayer setOpacity:1.0f];
 
    // Reset the ready layer so that it is ready for the next image
    readyLayer = [[[CALayer alloc] init] retain];
    readyLayer.frame = prevRect;
    readyLayer.opacity = 0.01f;
 
    [[[window contentView] layer] addSublayer:readyLayer];
}

Notice that we are converting the NSImage that gets passed to this function into a CGImageRef which is what our Core Animation layer requires to set it contents. Here is the code to convert an NSImage to a CGImageRef.

AppDelegate.m:nsImageToCGImageRef

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

- (CGImageRef)nsImageToCGImageRef:(NSImage*)image;
{
    NSData * imageData = [image TIFFRepresentation];
    CGImageRef imageRef;
    if(imageData)
    {
        CGImageSourceRef imageSource = 
                     CGImageSourceCreateWithData(
                           (CFDataRef)imageData,  NULL);
 
        imageRef = CGImageSourceCreateImageAtIndex(
                          imageSource, 0, NULL);
    }
    return imageRef;
}

Preloading A Layer to Animate

Instead of creating the layer, setting its contents, and then animating it all at once, I instead set an empty layer with a near zero opacity to overlay the QTMovieLayer when the movie first loads. Then, when the user taps the spacebar, I populate that invisible layer’s contents with the image data and then animate it. This keeps me from having to create a more complicated animation to get the desired effect.

Once the image layer has it’s new frame set, I re-initialize the ready layer. You see the ready layer get reset with this code from the imageReady: function.

1
2
3
4
5
6

// Reset the ready layer so that it is ready for the next image
readyLayer = [[[CALayer alloc] init] retain];
readyLayer.frame = prevRect;
readyLayer.opacity = 0.01f;
 
[[[window contentView] layer] addSublayer:readyLayer];

Note: I set the opacity to near zero as when it is set to zero it won’t animate the opacity change properly. I’m looking into why this is and will update this post with what I find when I find it.

 

Random Points

When I animate the layers, I simply grab a random point and the screen and then scale the image down to 35% of the original. When I call setFrame: the magic ensues and my screen gets really cluttered with lots of images. As I said before, not very useful, but excellent. Here is the random rectangle calculation function, getRandomRect:.

AppDelegate.m:getRandomRect

1
2
3
4
5
6
7
8
9
10

- (CGRect)getRandomRect:(CGRect)startRect;
{    
    CGPoint point = CGPointMake(random() % 
                          (NSUInteger)NSWidth([window frame]), 
                          random() % 
                           (NSUInteger)NSHeight([window frame]));
 
    return CGRectMake(point.x, point.y, 
                 startRect.size.width * 0.35f, startRect.size.height * 0.35f);
}

Conclusion

The nuances of Core Animation are quite interesting and provide a fun challenge when trying to solve problems. In other words, the devil is in the details. There is probably a better way to achieve the animation code, but I felt that the solution I came up with here works pretty well. There are details about Core Animation that I am still learning, but this type of effect demonstrates exactly the kinds of interesting things that are possible.

The basic concept behind this project is to present a window to the user that will walk them through a list of options. To accomplish this task, I created a number of NSViews that will be presented to the user in order so that they can make the decisions needed. To make this a little easier, I have extended NSView to create MSZLinkedView. The added functionality in this subclass is that the view has a reference to the previous and next views in the wizard. These references are set in interface builder directly so that I do not have to worry about them in code.

You can download the sample project from here: Core Animation Wizard Tutorial Project.

MSZLinkedView.h

1
2
3
4
5
6
7
8
9
10
11

@interface MSZLinkedView : NSView {
    IBOutlet MSZLinkedView *previousView;
    IBOutlet MSZLinkedView *nextView;
 
    IBOutlet NSButton *nextButton;
    IBOutlet NSButton *previousButton;
}
 
@property(retain)MSZLinkedView *previousView, *nextView;
 
@end

MSZLinkedView.m

1
2
3
4
5
6
7
8
9
10
11
12

@implementation MSZLinkedView
 
@synthesize  previousView, nextView;
 
- (void)awakeFromNib
{
    [self setWantsLayer:YES];
    [previousButton setEnabled:(previousView != nil)];
    [nextButton setEnabled:(nextView != nil)];
}
 
@end

There is not much to this class. The primary purpose is to keep a reference to its place in the linked list. But since I have the subclass I have added the core animation setWantsLayer: call into the awakeFromNib and it also checks to see if it has a previous and/or next view to disable the appropriate buttons. This NSView subclass will be used to build the different “pages” of the wizard.

Building the XIB/NIB

The next step in building the wizard is to lay out the views in Interface Builder. In the sample project, I have created three views: first, second and third. Each of these views has a next button, previous button and a custom box with a different color. If you build and run the project you can flip through these three and the appropriate button will be disabled.

Each view links to the next view, the previous view, and its own next and previous button. All of these links will occur before the awakeFromNib is called on each view so that the buttons will be disabled as appropriate. In an actual application I would have put in text fields, radio buttons, pictures, etc on each “slide” but in this case I only put in a simple box with a custom design. This will allow the user to see the slides clearly.

The application delegate in this example holds a reference to the main window and only the first selected view. Because the views are in a linked list, the AppDelegate does not care about the other views at all. That is responsibility of the list. There is one little catch though. When the nib is being loaded, the current view will be referenced before the awakeFromNib is called. To get the view added as a subview I need to add it in the awakeFromNib. This will set the stage for the wizard.

AppDelegate.h

1
2
3
4
5
6
7
8
9
10
11
12
13
14

@interface AppDelegate : NSObject {
    IBOutlet NSWindow *window;
    IBOutlet MSZLinkedView *currentView;
 
    CATransition *transition;
}
 
@property(retain)NSWindow *window;
@property(retain)MSZLinkedView *currentView;
 
- (IBAction)nextView:(id)sender;
- (IBAction)previousView:(id)sender;
 
@end

Method breakdown of the AppDelegate

1
2
3
4
5
6
7
8
9
10
11
12
13
14

- (void)awakeFromNib
{
    NSView *contentView = [[self window] contentView];
    [contentView setWantsLayer:YES];
    [contentView addSubview:[self currentView]];
 
    transition = [CATransition animation];
    [transition setType:kCATransitionPush];
    [transition setSubtype:kCATransitionFromLeft];
 
    NSDictionary *ani = [NSDictionary dictionaryWithObject:transition 
                                                    forKey:@"subviews"];
    [contentView setAnimations:ani];
}

awakeFromNib

The awakeFromNib first turns on Core Animation for the content view of the window. It then adds the currently referenced “currentView” as a subview of the contentView. Since we have already set up the “currentView” to have a frameOrigin of 0,0 I do not need to worry about setting the subview’s location.

<

p>Next I build a CATransition animation. Note that I have kept a reference to this animation as an ivar in the AppDelegate. The reason for that will become apparent later. Once the animation is built, I add it as the transition animation for the key “subviews” in the content view. This transition animation will trigger whenever a subview is added, removed or replaced.

<

p>

1
2
3
4
5
6
7
8
9
10

- (void)setCurrentView:(MSZLinkedView*)newView
{
    if (!currentView) {
        currentView = newView;
        return;
    }
    NSView *contentView = [[self window] contentView];
    [[contentView animator] replaceSubview:currentView with:newView];
    currentView = newView;
}

setCurrentView:(MSZLinkedView*)view

The reason that I overrode this setter method is a matter of convenience. Since I only ever wanted one view showing at any time, I can comfortably swap out the views whenever the setter for “currentView” is called. I could do this in other places to the same effect but since I want to keep track of the current view it is ideal to handle both at the same time. Therefore, whenever I want to switch the subviews I can pass the new view into the setCurrentView method and be done with it.

1
2
3
4
5
6
7
8
9
10
11
12
13

- (IBAction)nextView:(id)sender;
{
    if (![[self currentView] nextView]) return;
    [transition setSubtype:kCATransitionFromRight];
    [self setCurrentView:[[self currentView] nextView]];
}
 
- (IBAction)previousView:(id)sender;
{
    if (![[self currentView] previousView]) return;
    [transition setSubtype:kCATransitionFromLeft];
    [self setCurrentView:[[self currentView] previousView]];
}

nextView:(id)sender previousView:(id)sender

Both of these methods perform the same function. In each method I grab a reference to the current view and check that its previous/next is not nil. This is only protective since each view should have already disabled the buttons that don’t have a link.

Once that check is complete, I simply call setCurrentView: passing it the appropriate view — either the next or previous based on the method called. The setCurrentView: discussed above takes care of the rest. Just before I change the view, however, I change the subtype for the transition. This is the reason I keep a reference to the transition around. I do this so that visually the transitions make sense. The previous view comes in from the left and the next view comes in from the right. While this step is not necessary, it does give a nicer spacial feel to the animation.

Conclusion

So where is the magic? What makes the Core Animation transition happen? All of that is in the AppDelegate’s awakeFromNib. Simply setting the CATransition on the content view of the window takes care of all the animation. The rest of the code is just to handle all of the switching of the subview. You can play with the transitions very easily by change the type and subtype being set in the awakeFromNib of the AppDelegate.

Shaking To Say No

If you have your system set up to auto-login, you’ve probably never seen this effect before. Simply put, when you enter your password in the login window when doing a manual login, if you fat-finger it, it will shake you off–which is to say it will shake side to side several times in succession. It’s really quite a clever and intuitive response to what is normally responded to with a dialog.

After a fair bit of research and tweaking some code we found in a CocoaBuilder post written by Bill Dudney, author of the upcoming Core Animation for OS X: Creating Dynamic Compelling User Interfaces, we came up with a very elegant and tight solution. We have provided an example project you can download, but here is the frame animation code.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

- (CAKeyframeAnimation *)shakeAnimation:(NSRect)frame
{
    CAKeyframeAnimation *shakeAnimation = [CAKeyframeAnimation animation];
 
    CGMutablePathRef shakePath = CGPathCreateMutable();
    CGPathMoveToPoint(shakePath, NULL, NSMinX(frame), NSMinY(frame));
    int index;
    for (index = 0; index < numberOfShakes; ++index)
    {
        CGPathAddLineToPoint(shakePath, NULL, NSMinX(frame) - frame.size.width * vigourOfShake, NSMinY(frame));
        CGPathAddLineToPoint(shakePath, NULL, NSMinX(frame) + frame.size.width * vigourOfShake, NSMinY(frame));
    }
    CGPathCloseSubpath(shakePath);
    shakeAnimation.path = shakePath;
    shakeAnimation.duration = durationOfShake;
    return shakeAnimation;
}

That’s really all there is to it. We’ve set some static variables in the demo project that are used to determine how many times to shake the window, how vigorously to shake it and how long the shake effect should take to complete. Play with these variables yourself to see a variation of this same shaking effect you find in the OS X login window.