|
| 1 | +## JCParallax ## |
| 2 | + |
| 3 | +> A **J**Query & **C**SS3 **Parallax** engine |
| 4 | +
|
| 5 | +### About ### |
| 6 | + |
| 7 | +This is a flexible parallax animation effect, written on top of an animation engine which uses CSS3 transitions to smooth out JavaScript interpolation of animation in the browser. The library basically creates smoother browser animations by allowing you to decrease the JavaScript sampling rate, offloading animation processing to the GPU and freeing up CPU resources to decrease animation stutter. Inbetween animations generally run at whatever native framerate your monitor supports and appear extremely smooth, obviously however this depends on browser support. |
| 8 | + |
| 9 | +This kind of implementation is particularly suited to regularly sampled animation or keyframed animation. The parallax animation implemented by `jcparallax.Viewport` and `jcparallax.Layer` updates the mouse position constantly in response to input events, and then runs animations on those coordinates at regular intervals to achieve the effect. |
| 10 | + |
| 11 | +#### Animation Engine #### |
| 12 | + |
| 13 | +I have done my best to make JCParallax's animation system as flexible as possible, and it allows for nearly limitless combinations of effects. Combining scrolling parallax with mouse movement parallax, stretching and moving elements together or rotating to follow a point - all are possible. JCParallax basically provides its interface through `Viewports` (elements which receive input to control an animation) and `Layers` (elements being moved to achieve the effect). |
| 14 | + |
| 15 | +- Each viewport has multiple layers under its control |
| 16 | +- Layers can be connected to multiple viewports |
| 17 | +- A layer may have any mumber of attributes animating |
| 18 | +- A layer may have any number of animation inputs (such as events or timers) and output attributes running simultaneously |
| 19 | +- Multiple inputs can be combined to effect the same attribute |
| 20 | +- Animations may be run simultaneously at different timings |
| 21 | +- Layers may also be viewports, and so on... |
| 22 | + |
| 23 | +##### Input handlers ##### |
| 24 | + |
| 25 | +These callbacks read some input event and update a clamped input value for each axis in the range `0 <= x <= 1`. This is achieved in each callback by passing `this.updateLastSamplePos()` the X and Y values from that event. They receive the `Viewport` element and jQuery event as parameters. Builtin input handlers are defined at the base of `jcp-viewport.js`: |
| 26 | + |
| 27 | +- *mousemove*: takes a mousemove event and calculates input based on the mouse position in relation to the viewport element's bounding box |
| 28 | +- *scroll*: takes a scroll event and calculates input based on the scroll positions of the viewport |
| 29 | +- *click*: intercepts the positions of click events on the viewport element and smoothly transitions between them |
| 30 | +- *mousemove_xcentered*: the same as mousemove, except that it returns 1 when the mouse is in the center of the X axis and 0 at each edge |
| 31 | + |
| 32 | +##### Animation handlers ##### |
| 33 | + |
| 34 | +Animation handlers take the output from an input handler for each axis and convert to final CSS values to be set on the layer for that frame. They receive the output X and Y values from the input handlers they are tied to. It is important to return raw values from these methods instead of CSS units - this is required for the internals of the animation engine to average multiple inputs onto the same output value. All values are in pixels (or degrees) when output. Builtin animation handlers are defined at the base of `jcp-animator.js`: |
| 35 | + |
| 36 | +- *position*: moves the layer directly to animate its position |
| 37 | +- *padding*: achieves the same effect as *position* using padding on the target element |
| 38 | +- *margins*: achieves the same effect as *position* using margin offsets |
| 39 | +- *background*: achieves the same effect as *position* using the background position of the target element |
| 40 | +- *stretch*: stretches the layer by animating its width and height |
| 41 | +- *Xrotate*: rotates the layer in response to input on the X axis |
| 42 | +- *Yrotate*: rotates the layer in response to input on the Y axis |
| 43 | +- *textShadow*: moves the text shadow of the layer in response to the parallax effect |
| 44 | +- *opacity*: fades layers in and out. Best used when combined with other effects. |
| 45 | + |
| 46 | +I've chosen to implement a base set of animations for all useful CSS attributes for which transitions are widely supported. You can easily add your own to this set and even implement animation of attributes on which transitions are not supported at all - these additions will coexist with supported features nicely if configured to run at a higher framerate. |
| 47 | + |
| 48 | +##### Range calculators ##### |
| 49 | + |
| 50 | +These are callbacks used to automatically determine the movement range of `Layer` elements, and are only required when not hardcoding animation ranges into your init options. They are called when `refreshCoords()` is called on a `Viewport` or `Layer` element and update the cached coordinates for layers used in animation handling. |
| 51 | + |
| 52 | +They receive the layer element as parameter 0 and `Viewport` element as parameter 1, and should return a two-element array indicating the range of motion this element will take. Builtin range calculators are defined at the base of `jcp-layer.js`: |
| 53 | + |
| 54 | +- *width*: provides a range upward from 0 based on the difference between viewport and layer width |
| 55 | +- *height*: provides a range downward to 0 based on the difference between viewport and layer height |
| 56 | +- *scrollWidth*: provides a range upward to 0 based on layer scroll width & viewport width |
| 57 | +- *scrollHeight*: provides a range upward from 0 based on layer scroll height & viewport height |
| 58 | +- *fontSize*: mainly useful with *textShadow* animation handler, provides a range from 0 to the font size of the layer element intended to be used for horizontal motion |
| 59 | +- *lineHeight*: mainly useful with *textShadow* animation handler, provides a range from the line height of the layer element to 0 intended to be used for vertical motion |
| 60 | +- *opacity*: provides an animation range from 0 to the current opacity of the element |
| 61 | +- *dataRangeX*: reads the `jcp-xrange` data attribute of each layer and splits on the token ',' to provide a hardcoded X range of motion |
| 62 | +- *dataRangeY*: reads the `jcp-yrange` data attribute of each layer and splits on the token ',' to provide a hardcoded Y range of motion |
| 63 | + |
| 64 | +### API ### |
| 65 | + |
| 66 | +:TODO: documentation coming! |
| 67 | + |
| 68 | +### Support ### |
| 69 | + |
| 70 | +Browsers require support for the `transition` CSS property and `transitionend` DOM event for this library to function fully. Chrome is ludicrously smooth, whilst Firefox, Safari & (especially) Opera may experience very occaisonal jitter on slower machines - but nothing outside of what would be expected with standard JavaScript animation techniques. Without these events it simply runs normal timeout-based animation at `fbFramerate` instead of `framerate` - this interval should be sufficiently quick as to make delay indistinguishable as there will be no GPU smoothing inbetween frames. |
| 71 | + |
| 72 | +#### Finer details #### |
| 73 | + |
| 74 | +- CSS transitions are supported in browsers as of Firefox 4, Chrome 1, Opera 10.5, Safari 3.2 and IE 10. |
| 75 | +- Transition end events are supported in all browsers that support transitions, so though there is a facility for the library to work without events it will likely never be used. |
| 76 | +- Rotation, skewing and other transform animations require browser support for 2D transforms and the `transform-origin` CSS attribute. |
| 77 | +- Opera uses fallback mode when animating `background-position` or `text-shadow`, as it does not correctly support transitions of these attributes. |
| 78 | + |
| 79 | +### TODO ### |
| 80 | + |
| 81 | +- implement correct math for combining inputs to the same output |
| 82 | +- pure JavaScripting timing for fallback animation handler |
| 83 | +- detect mouse exiting viewport & update last position |
| 84 | +- allow toggling the behaviour |
| 85 | +- dont add transition duration properties if set to the defaults present in the stylesheet |
| 86 | +- implement a timer to handle the click input handler |
| 87 | + |
| 88 | +### License ### |
| 89 | + |
| 90 | +This software is provided under an MIT open source license, read the 'LICENSE.txt' file for details. |
| 91 | + |
| 92 | +Copyright © 2012 Sam Pospischil (pospi at spadgos dot com) |
0 commit comments