FCAnimationFactory 0.3 (beta)

FCAnimationFactory is an objective-c library for generating CAKeyFrameAnimation with custom timing functions including cubic, quadratic, or even elastic functions.

The main difference between AHEasing and FCAnimationFactory is that AHEasing create every frames for CAKeyFrameAnimation, which breaks Core Animation model-presentation rendering pipeline. FCAnimationFactory use standard CAMediaTimingFunction to tell CAKeyFrameAnimation the timing and let it deals with frames itself. The challenge is not only timing needs to be interpolated, values (numbers, colors, path) also need to be interpolated as well.

SYNOPSIS

High level animation API:

[CATransaction begin];
[CATransaction setDisableActions:YES];
CAKeyframeAnimation *animation = 
    [FCBasicAnimationFactory animationWithName:@"cubicEaseOut"
                                     fromValue:(__bridge id)[[UIColor redColor] CGColor]
                                       toValue:(__bridge id)[[UIColor greenColor] CGColor]
                                      duration:@2.5f];
animation.keyPath = @"backgroundColor";
animation.repeatCount = HUGE_VALF;      // repeat forever
animation.autoreverses = YES;
[_layer addAnimation:animation forKey:@"animateColor"];
[CATransaction commit];

Create your own timing function directly with FCValueAnimationFactory:

factory = [[FCValueAnimationFactory alloc] init];
factory.timingBlocks = @[
    ^float(float x){return x*x*x*x*x;} // fast shooting with x^5
    ^(float x){return sinf(x*M_PI_2);} // slow down in sine function
];
factory.durations = @[ @1.f, @1.5f];
factory.values = @[
    [NSValue valueWithCGPoint:CGPointMake(0.f, 160.f)],    // start from edge of the screen
    [NSValue valueWithCGPoint:CGPointMake(350.f, 160.f)],  // overshoot to outside of the screen
    [NSValue valueWithCGPoint:CGPointMake(160.f, 160.f)]   // end at middle of the screen
];
CAKeyframeAnimation *animation = [factory animation];
animation.keyPath = @"position";

[_layer addAnimation: animation forKey:@"positionKey"]

Clone the project and see example usage in FCAnimationDemo target.

CLASSES AND METHODS

FCBasicAnimationFactory class

Properties

• timingBlocks An array of objective-c blocks. The type of the blocks is float(^)(float).
• fromValue An id value, can be NSNumbers or NSValues.
• toValue An id value, can be NSNumbers or NSValues.
• totalDurations An NSNumber numberWithfloat which present the total duration presented in seconds.

Methods

• -(CAKeyFrameAnimation*)animation; Create an animation from factory.
• +(CAKeyFrameAnimation*)animationWithName:(NSString*)name fromValue:(NSValue*)value toValue:(NSValue*) duration:(NSNumber*)duration convinient form for creating animations. See Timing block/function names for available names.

FCValueAnimationFactory class

Properties

• timingBlocks An array of objective-c blocks. The type of the blocks is float(^)(float). A timingBlock must start with 0 and end with 1.
• values An array of id values, which can be NSNumbers or NSValues.
• durations An array of NSNumber numberWithFloat of each time segments presented in seconds.

If count of timingBlocks and durations is n, values count must be n+1. The time line looks like this:

    tBlock-0   tBlock-1     ...     tBlock-n
   duration-0 duration-1    ...    duration-n       
  I----------I----------I-- ... --I----------I
value-0   value-1   value-2    value-n   value-n+1

Method

• -(CAKeyFrameAnimation*)animation; Create an animation from factory.

Animatable properties

Single float number

• borderWidth
• cornerRadius
• opacity
• shadowOpacity
• shadowRadius
• zPosition

Use [NSNumber numberWithFloat: myFloat] or objective-c literal @3.5f for fromValue and toValue.

CAKeyframeAnimation *animation = [FCBasicAnimationFactory animationWithName:@"elasticEaseOut"
                                                                  fromValue:@1.f
                                                                    toValue:@0.f
                                                                   duration:@2.5f];
animation.keyPath = @"shadowOpacity";

CGPoint

• anchorPoint
• position

Use [NSValue valueWithCGPoint: point].

CGSize

• shadowOffset

Use [NSValue valueWithCGSize: myOffset].

Frames and bounds

• frame
• bounds
• contentsRect

Use [NSValue valueWithCGRect: bounds].

Colors

• backgroundColor
• borderColor
• shadowColor

Remember to cast CGColorRef into id with toll-free bridging.

UIColor * __autoreleasing redColor = [[UIColor redColor] colorWithAlphaComponent:.5f];
CGColorRef redRef = CFRetain([redColor CGColor]);
facotory.fromValue = (__bridge id)redRef;
CFRelease(redRef);

Animatable properties under cunstruction

• transform and sublayerTransform
• countents I'll use CATransition to made another class to animate contents.
• path property in CAKeyFrameAnimation.

Animatable property won't be supported

• doubleSided
• hidden
• maskToBounds
• mask
• filters
• subLayers

These properties will present the final value at the begining of an animation. You don't need FCAnimationFactory to interpolate these boolean or layer contents. You only need CABasicAnimation or CAKeyFrameAnimation to setup timestamp when it need changes.

Timing block/function names

• linear
• quadraticEaseIn
• quadraticEaseOut
• quadraticEaseInOut
• cubicEaseIn
• cubicEaseOut
• cubicEaseInOut
• quarticEaseIn
• quarticEaseOut
• quarticEaseInOut
• quinticEaseIn
• quinticEaseOut
• quinticEaseInOut
• sineEaseIn
• sineEaseOut
• sineEaseInOut
• circularEaseIn
• circularEaseOut
• circularEaseInOut
• expEaseIn
• expEaseOut
• expEaseInOut
• elasticEaseIn
• elasticEaseOut
• backEaseIn
• backEaseOut

INSTALL

Clone the project and drag these files into your own project:

FCAnimationFactory.h
FCAnimationFactory.m
FCBasicAnimationFactory.h
FCBasicAnimationFactory.m
FCValueAnimationFactory.h
FCValueAnimationFactory.m

The project is still under heavy development. Pull requests are welcome ;)

TODOS

• Write complete API references, use appledoc.

• FCPathAnimationFactory can create cubic path on position or other 2D movement animation.

• Draw timing block diagrams. Write some timingBlocks examples.

• Write example of how doubleSided property works with other animations.

• Make beautiful demos

LICENSE

Created by Felix Chern on 12/10/15.
Copyright (c) 2012 Felix R. Chern. All rights reserved. (BSD LICENSE)

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:

* Redistributions of source code must retain the above copyright
  notice, this list of conditions and the following disclaimer.
* Redistributions in binary form must reproduce the above copyright
  notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.
* Neither the name of the FCAnimationFactory nor the
  names of its contributors may be used to endorse or promote products
  derived from this software without specific prior written permission.
 

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL FELIX R. CHERN BE LIABLE FOR ANY
DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

SEE ALSO

• AHEasing
• IRAnimationQueue
• Robert Panners easing equations