What kind of value is keyTime in an CAKeyFrameAnimation?

Question

For example I have this CAKeyFrameAnimation:

CALayer* theLayer = myView.layer;
    CAKeyframeAnimation* animation;
    animation = [CAKeyframeAnimation animationWithKeyPath:@"transform.rotation.z"];

    animation.duration = 1.6;
    //animation.cumulative = YES;
    animation.repeatCount = 1;
    animation.removedOnCompletion = NO;
    animation.fillMode = kCAFillModeForwards;

    animation.values = [NSArray arrayWithObjects:
                        [NSNumber numberWithFloat:0.0 * M_PI],
                        [NSNumber numberWithFloat:(15.0/180.0) * M_PI],
                        [NSNumber numberWithFloat:(30.0/180.0) * M_PI], // animation stops here...
                        [NSNumber numberWithFloat:(45.0/180.0) * M_PI], // ignored!
                        [NSNumber numberWithFloat:(190.0/180.0) * M_PI], nil]; // ignored!

    animation.keyTimes = [NSArray arrayWithObjects:
                          [NSNumber numberWithFloat:0.0],
                          [NSNumber numberWithFloat:0.2],
                          [NSNumber numberWithFloat:0.4], // ignored!
                          [NSNumber numberWithFloat:0.8], // ignored!
                          [NSNumber numberWithFloat:1.6], nil]; // ignored!

    animation.timingFunctions = [NSArray arrayWithObjects:
                                 [CAMediaTimingFunction functionWithName:kCAMediaTimingFunctionLinear], 
                                 [CAMediaTimingFunction functionWithName:kCAMediaTimingFunctionLinear],
                                 [CAMediaTimingFunction functionWithName:kCAMediaTimingFunctionLinear],
                                 [CAMediaTimingFunction functionWithName:kCAMediaTimingFunctionLinear],
                                 [CAMediaTimingFunction functionWithName:kCAMediaTimingFunctionLinear], nil];

    [theLayer addAnimation:animation forKey:@"transform.rotation.z"];

What I don't get is:

A) are key time values absolute passed time since the animation has started?

B) are key time values just saying how much time to use for this particular key frame?

Answer 1

The value of keyTimes is a percent of the total duration. Valid values range between 0 and 1 (0% to 100%). Your last value of 1.6 is invalid.

As an example, if a keyframe is supposed to happen 0.8 seconds into the animation that keyTime would be 0.5 given your duration of 1.6 seconds.

Answer 2

The docs are phrased a little oddly here, but are accurate:

Each value in the array is a floating point number between 0.0 and 1.0 and corresponds to one element in the values array. Each element in the keyTimes array defines the duration of the corresponding keyframe value as a fraction of the total duration of the animation. Each element value must be greater than, or equal to, the previous value.

Basically, each value indicates at what normalized point in the animation the given keyframe occurs. So if a keyframe is 25% into the animation, the value would be 0.25. The confusing part of the docs is they indicate that it is a duration, when in fact it's a normalized point in time.