Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

Added README & license details

  • Loading branch information...
commit 8ceec3288da00f957009dc0ef93817497874f658 1 parent 90721d9
Joe Lambert authored

Showing 3 changed files with 155 additions and 1 deletion. Show diff stats Hide diff stats

  1. +21 0 MIT-LICENSE
  2. +133 0 README.md
  3. +1 1  demo.html
21 MIT-LICENSE
... ... @@ -0,0 +1,21 @@
  1 +Copyright (c) 2011 Joe Lambert
  2 +http://www.joelambert.co.uk
  3 +
  4 +Permission is hereby granted, free of charge, to any person obtaining
  5 +a copy of this software and associated documentation files (the
  6 +"Software"), to deal in the Software without restriction, including
  7 +without limitation the rights to use, copy, modify, merge, publish,
  8 +distribute, sublicense, and/or sell copies of the Software, and to
  9 +permit persons to whom the Software is furnished to do so, subject to
  10 +the following conditions:
  11 +
  12 +The above copyright notice and this permission notice shall be
  13 +included in all copies or substantial portions of the Software.
  14 +
  15 +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
  16 +EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
  17 +MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
  18 +NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
  19 +LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
  20 +OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
  21 +WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
133 README.md
Source Rendered
... ... @@ -0,0 +1,133 @@
  1 +# Morf.js
  2 +
  3 +Morf.js is a Javascript work-around for hardware accelerated CSS3 transitions with custom easing functions. Ever wanted to produce CSS transitions with more compelling effects than just `linear`, `ease`, `ease-out`, `ease-in` or `cubic-bezier`? Well now you can!
  4 +
  5 +# Requirements
  6 +Morf requires the following:
  7 +
  8 +- A WebKit browser capable of CSS Animations (Morf uses `@keyframes` animations under the hood)
  9 +- Shifty.js (>= 0.1.3) - Morf can be downloaded with or without Shifty pre-bundled
  10 +
  11 +## Why is this WebKit only?
  12 +
  13 +Although other browser vendors have started to add CSS Animations (e.g. Firefox 5) they do not yet have an alternative implementation for the `WebKitCSSMatrix` object which is used to calculate the interpolated matrix values.
  14 +
  15 +# How do I use it?
  16 +
  17 +Using it is simple but does require that you trigger the transition from Javascript. To transition an element to a new state you would do the following:
  18 +
  19 + // Get a reference to the element
  20 + var elem = document.getElementById('elem');
  21 +
  22 + var trans = Morf.transition(elem, {
  23 + // New CSS state
  24 + '-webkit-transform': 'translate3d(300px, 0, 0) rotate(90deg)',
  25 + 'background-color': '#FF0000'
  26 + }, {
  27 + duration: '1500ms',
  28 + timingFunction: 'bounce'
  29 + });
  30 +
  31 +Thats it! Your element will then transition right 300px, rotate 90deg & change colour to red using the `bounce` easing function.
  32 +
  33 +##Using morf.js as a CSS3 Animation Generator
  34 +
  35 +You may also just want to use Morf as a CSS animation generator, in which case you can get the generated keyframes in CSS format using the `.css` property. So, continuing the above example:
  36 +
  37 + console.log(trans.css);
  38 +
  39 +You can then paste the `@keyframes` code straight into your stylesheet and use it as normal, without the need for Javascript.
  40 +
  41 +##Available easing functions
  42 +
  43 +All of [Robert Penner](http://www.robertpenner.com/easing/)'s easing functions are available (via [Shifty.js](https://github.com/jeremyckahn/shifty))
  44 +
  45 +- `easeInQuad`
  46 +- `easeOutQuad`
  47 +- `easeInOutQuad`
  48 +- `easeInCubic`
  49 +- `easeOutCubic`
  50 +- `easeInOutCubic`
  51 +- `easeInQuart`
  52 +- `easeOutQuart`
  53 +- `easeInOutQuart`
  54 +- `easeInQuint`
  55 +- `easeOutQuint`
  56 +- `easeInOutQuint`
  57 +- `easeInSine`
  58 +- `easeOutSine`
  59 +- `easeInOutSine`
  60 +- `easeInExpo`
  61 +- `easeOutExpo`
  62 +- `easeInOutExpo`
  63 +- `easeInCirc`
  64 +- `easeOutCirc`
  65 +- `easeInOutCirc`
  66 +- `easeOutBounce`
  67 +- `easeInBack`
  68 +- `easeOutBack`
  69 +- `easeInOutBack`
  70 +- `elastic`
  71 +- `swingFromTo`
  72 +- `swingFrom`
  73 +- `swingTo`
  74 +- `bounce`
  75 +- `bouncePast`
  76 +- `easeFromTo`
  77 +- `easeFrom`
  78 +- `easeTo`
  79 +
  80 +There are also a couple of handpicked formulas from [Thomas Fuch](http://mir.aculo.us)'s [Scripty2](http://scripty2.com/):
  81 +
  82 +- `spring`
  83 +- `sinusoidal`
  84 +
  85 +##How can I add my own?
  86 +
  87 +Adding your own is easy, an easing function has the following prototype:
  88 +
  89 + // pos is the percentage of the way through the transition (0.0-1.0)
  90 + function(pos) {
  91 + var newPos = someMaths(pos)
  92 + return newPos;
  93 + };
  94 +
  95 +Once you've written your function, you just need to load it into Shifty's available formulas. Here's how I add the Scripty2 functions:
  96 +
  97 + (function(){
  98 + var scripty2 = {
  99 + spring: function(pos) {
  100 + return 1 - (Math.cos(pos * 4.5 * Math.PI) * Math.exp(-pos * 6));
  101 + },
  102 +
  103 + sinusoidal: function(pos) {
  104 + return (-Math.cos(pos*Math.PI)/2) + 0.5;
  105 + }
  106 + };
  107 +
  108 + // Load the Scripty2 functions
  109 + for(var t in scripty2)
  110 + Tweenable.prototype.formula[t] = scripty2[t];
  111 + })();
  112 +
  113 +# How does it work?
  114 +
  115 +So you know how to use it but you want to know how it works? Well, what Morf actually does is create a CSS3 animation on the fly for the requested transition. In other words at the time that `Morf.transition` is called, all the necessary keyframes are generated to give the impression that a transition has taken place.
  116 +
  117 +Even though this is actually a CSS Animation, Morf does its best to masquerade as a transition, event throwing a `webkitTransitionEnd` event when its finished.
  118 +
  119 +## Tweening CSS
  120 +To work out all the interpolated CSS states, Morf uses the fantastic [Shifty.js](https://github.com/jeremyckahn/shifty) along with some custom code to handle matrix transformations. Shifty is responsible for working out all regular CSS tween values. e.g. `width`, `height`, `background-color`.
  121 +
  122 +## Tweening Matrix Transformations
  123 +In order to tween the 3D matrix, I had to add some custom functions to the `WebKitCSSMatrix` object. The process of accurately tweening between two matrix states requires that the matrixes themselves be first decomposed into their composite parts (translate, rotate, scale etc). Once these composite parts are known, its a matter of tweening between each part of each state and then rebuilding the composite matrix.
  124 +
  125 +The bulk of this calculation is done using the custom `WebKitCSSMatrix.decompose()` function. This function is a Javascript implementation of [pseudo code provided by the W3C](http://www.w3.org/TR/css3-2d-transforms/#matrix-decomposition). Its likely that this is pretty close to how WebKit produces tween values internally but in Javascript rather than native code, so not quite as quick.
  126 +
  127 +In order to get the `decompose()` function working I also had to supplement the `WebKitCSSMatrix` object with some other helpful matrix functions and add a basic `Vector4` implementation. This may be of use to others so feel free to repurpose the code for your own projects.
  128 +
  129 +***Note:** The `decompose()` function is fairly expensive so its only called once for the start and end state of each transition.*
  130 +
  131 +# License
  132 +
  133 +Morf is Copyright © 2011 [Joe Lambert](http://www.joelambert.co.uk) and is licensed under the terms of the [MIT License](http://www.opensource.org/licenses/mit-license.php).
2  demo.html
@@ -2,7 +2,7 @@
2 2 <html>
3 3 <head>
4 4 <meta charset=utf-8 />
5   - <title>CSS3 Tween</title>
  5 + <title>Morf.js - CSS3 Transitions with custom easing functions</title>
6 6 <link rel="stylesheet" href="css/demo.css" type="text/css" media="screen" title="no title" charset="utf-8">
7 7 <script src="https://ajax.googleapis.com/ajax/libs/jquery/1.4.4/jquery.min.js" type="text/javascript" charset="utf-8"></script>
8 8 <script src="js/modernizr.js" type="text/javascript" charset="utf-8"></script>

0 comments on commit 8ceec32

Please sign in to comment.
Something went wrong with that request. Please try again.