rewrote timing engine to use TransitionEnd events to manage frame

synchronisation.
This requires passing up 'frame redrawn' flags from the Layer and
Viewport code in order to switch between transitions and timeouts on the
fly, since non-movement will not cause transition callbacks to fire.

animation callbacks now return CSS attributes as an object to apply to
the layer element. This allows frame changes to be checked.

restructured class internals to move timer responsibility to the
TransitionInterval class, drawing functionality to the Layer class

Author: pospi

jcp-layer.js

@@ -19,9 +19,7 @@ jcparallax.Layer = function(viewport, el, options)
 	this.element = el;
 	this.options = options;
 
-	jcparallax.Viewport._handleOptions(this.options);
-
-	this.setFramerate(jcparallax.Viewport._checkFramerate(this.options, this.options.framerateCheckCb));
+	jcparallax.Viewport._calcMovementRanges(this.options);
 
 	// store animation event handler to be called by our Viewport
 	if ($.isFunction(this.options.animHandler)) {
@@ -40,11 +38,8 @@ $.extend(jcparallax.Layer.prototype, {
 	minMaxX : null,
 	minMaxY : null,
 
-	setFramerate : function(ms)
-	{
-		this.framerate = ms;
-		this._addCss(ms);
-	},
+	// previous CSS attributes of the layer
+	prevFrameCss : {},
 
 	/**
 	 * Refreshes the cached coordinates of the layer after some external DOM manipulation
@@ -56,6 +51,23 @@ $.extend(jcparallax.Layer.prototype, {
 		}
 	},
 
+	/**
+	 * Redraw the layer, given new input values
+	 * @return true if the layer needed re-rendering
+	 */
+	redraw : function(xVal, yVal)
+	{
+		var newCss = this.animHandler.call(this, xVal, yVal);
+
+		if (this._cssChanged(newCss)) {
+			this.prevFrameCss = newCss;
+			this.element.css(newCss);
+			return true;
+		}
+
+		return false;
+	},
+
 	_updateMovementRange : function(xRange, yRange)
 	{
 		this.minMaxX = $.isArray(xRange) ? xRange : this._calculateMovementRange(xRange);
@@ -71,15 +83,14 @@ $.extend(jcparallax.Layer.prototype, {
 		return rangeCallback.call(this, this.element, this.viewport);
 	},
 
-	_addCss : function(framerate)
+	_cssChanged : function(newCss)
 	{
-		var that = this;
-		framerate = (framerate / 1000) + 's';
-
-		$.each(jcparallax.cssDomPrefixes, function(i, prefix) {
-			that.element.css(prefix + 'transition-duration', framerate);
-		});
-		that.element.css('transition-duration', framerate);
+		for (var i in newCss) {
+			if (this.prevFrameCss[i] === undefined || this.prevFrameCss[i] != newCss[i]) {
+				return true;
+			}
+		}
+		return false;
 	}
 });
 
@@ -89,40 +100,40 @@ $.extend(jcparallax.Layer.prototype, {
 
 jcparallax.Layer.animHandlers = {
 
-	position : function(el, xVal, yVal)
+	position : function(xVal, yVal)
 	{
-		el.css({
+		return {
 			left : this.minMaxX[0] + (xVal * (this.minMaxX[1] - this.minMaxX[0])),
 			top : this.minMaxY[0] + (yVal * (this.minMaxY[1] - this.minMaxY[0])),
-		});
+		};
 	},
 
-	padding : function(el, xVal, yVal)
+	padding : function(xVal, yVal)
 	{
 
 	},
 
-	margins : function(el, xVal, yVal)
+	margins : function(xVal, yVal)
 	{
 
 	},
 
-	background : function(el, xVal, yVal)
+	background : function(xVal, yVal)
 	{
 
 	},
 
-	stretch : function(el, xVal, yVal)
+	stretch : function(xVal, yVal)
 	{
 
 	},
 
-	textShadow : function(el, xVal, yVal)
+	textShadow : function(xVal, yVal)
 	{
 
 	},
 
-	opacity : function(el, xVal, yVal)
+	opacity : function(xVal, yVal)
 	{
 
 	}

jcp-transitioninterval.js

@@ -10,7 +10,8 @@
  * 	- In half-enabled mode, transitions are still used to smooth between frames but no events are
  *    available to signify the end of transitions. In this case we just use an interval to try to
  *    sync the javascript CSS updates with the end of the CSS transitions - but this *can* get out
- *    of sync slightly which leads to
+ *    of sync slightly which leads to tearing in the animation. Fortunately this mode is unlikely
+ *    to be executed.
  *  - In fallback mode, we simply sample at a higher framerate to compensate for the lack of browser
  *    transition support.
  *
@@ -20,45 +21,122 @@
  * 	- a sampling rate for the animation when running in CSS-enabled browsers
  * 	- a fallback sampling rate when transition smoothing is not available
  *
+ * After construction, call addElements() to append DOM elements under the control of the TransitionInterval's
+ * animation timer. These need to be registered in order to apply the correct CSS attributes necessary for
+ * transition timing on the elements.
+ *
  * @requires jcparallax.js
  */
 (function($) {
 
-jcparallax.TransitionInterval = function(cb, framerate, doNotStart)
+jcparallax.TransitionInterval = function(cb, framerate, fbFramerate, extraCssAnimCheckCb)
 {
-	this.framerate = framerate;
-	this.callback = cb;
-	this.frameCount = -1;
+	this.elements = jQuery([]);
+	this.setFramerates(framerate, fbFramerate, extraCssAnimCheckCb);
 
-	if (!doNotStart) this.start();
+	this.callback = cb;
+	this.frameCount = 0;
 };
 
 $.extend(jcparallax.TransitionInterval.prototype, {
 
-	interval : null,
+	_running : false,
+
+	timeout : null,		// frame timeout reference (fallback mode)
+	update : null,		// underlying registered timer update callback
 
 	start : function()
 	{
 		// ignore if already running
-		if (this.interval) {
+		if (this._running) {
 			return;
 		}
 
-		var that = this,
-			update = function() {
-				++that.frameCount;
-				that.callback.call(that);
+		var that = this;
+
+		if (jcparallax.support.transitionEndEvent) {
+			this.update = function() {
+				// if callback returns to flag no movement, check again at our frame interval
+				if (!that.callback.call(that)) {
+					clearTimeout( that.timeout );
+					that.timeout = setTimeout(function() {
+						that.timeout = null;
+						that.update();
+					}, that.framerate);
+				} else {
+
+					// this check is placed here to failsafe in the event that browser rendering stutters,
+					// resulting in the transition end event never being called and the animation failing
+					// to restart.
+					clearTimeout( that.timeout );
+					that.timeout = setTimeout(function() {
+						that.timeout = null;
+						that.update();
+					}, that.framerate * 2);
+
+					++that.frameCount;
+				}
 			};
 
-		update();	// run to first frame
+			// bind to the first element, we only need it to run once since all framerates are the same
+			this.elements.on(jcparallax.support.transitionEndEvent, that.update);
+		} else {
+			var supported = jcparallax.support.transitions && (!this.useFallbackCheckCb || (this.useFallbackCheckCb && this.useFallbackCheckCb()));
+
+			this.update = function() {
+				that.callback.call(that);
+				that.timeout = setTimeout(that.update, supported ? that.framerate : that.fbFramerate);
 
-		this.interval = setInterval(update, this.framerate);
+				++that.frameCount;
+			};
+			this.timeout = setTimeout(this.update, supported ? this.framerate : this.fbFramerate);
+		}
+		this._running = true;
+
+		this.update();	// run to first frame
 	},
 
 	stop : function()
 	{
-		clearInterval( this.interval );
-		this.interval = null;
+		if (this._running) {
+			if (jcparallax.support.transitionEndEvent) {
+				this.elements.off(jcparallax.support.transitionEndEvent, this.update);
+			} else {
+				clearTimeout( this.timeout );
+				this.timeout = null;
+			}
+			this._running = false;
+		}
+	},
+
+	setFramerates : function(cssFramerate, fallbackFramerate, extraCssAnimCheckCb)
+	{
+		this.framerate = cssFramerate;
+		this.fbFramerate = fallbackFramerate;
+		this.useFallbackCheckCb = extraCssAnimCheckCb;
+		this._applyCss();
+	},
+
+	addElements : function(els)
+	{
+		if ($.isArray(els)) {
+			this.elements.pushStack(els);
+		} else {
+			this.elements = this.elements.add(els);
+		}
+		this._applyCss();
+	},
+
+	_applyCss : function()
+	{
+		var that = this,
+			cssFramerate = (this.framerate / 1000) + 's';
+
+		// set transition-duration for CSS sample tweening
+		$.each(jcparallax.cssDomPrefixes, function(i, prefix) {
+			that.elements.css(prefix + 'transition-duration', cssFramerate);
+		});
+		this.elements.css('transition-duration', cssFramerate);
 	}
 });