Sprite3D.js - Documentation

back

Getting started

How does it work ? Sprite3D.js simply adds some methods and properties to your HTML elements making their 3D transformations a bit more elegant and easier. Normally, you should write (at least) this : var d = document.createElement("div"); d.id = "my3dElement"; d.style.[insertBrowserPrefixHere]TransformStyle = "preserve-3d"; d.style.[insertBrowserPrefixHere]Transform = "translate3d(200px, 0px, -300px) rotateX(12deg) rotateY(5deg) scale3d(2,2,2)"; but, with Sprite3D, you get this : var d = Sprite3D .create("my3dElement") .position(200,0,300) .rotation(12,5,0) .scale(2);

1. Prepare

Link to the source in html code

<script src="js/Sprite3D.js" type="text/javascript" charset="utf-8"></script>

You can check if 3D transforms are supported by the current browser :

if ( Sprite3D.isSupported() ) {
  // display 3D content
} else {
  // display warning or alternative content
}

2. Set up a root container

When working with Sprite3D, you have to set up a root container for your 3D elements. There are two methods for doing that.

a. Create a new DIV element centered in the page. Use this when you want to create full page 3D content.

var stage = Sprite3D.stage();

b. Transform a existing element into a 3D container. It's existing CSS properties will remain unchanged, exept its position that will be set to relative if static.

var stage = Sprite3D.stage( document.getElementById("rootContainer") );

Static methods

Usage Description
Sprite3D.isSupported() Returns a boolean value indicating if the library has found support for CSS 3D transforms in current browser.
Sprite3D.stage() Creates and returns a DIV element absolutely positionned in the center of the page with the needed CSS properties set to act as a root container for all your 3D content.
Use this method if you want to create full page 3D content with centered origin.
Sprite3D.stage( DOMElement ) Receives an DOM element and transforms it into a valid container for 3D transformed content. The only CSS properties that will be altered are perspective, transform and transform-style. If the element's position is static, it will be changed to relative.
Use this method to get a rectangular viewport if your 3D content is not covering the whole page. The origin will be the top-left corner of the element.
Sprite3D.create( DOMElement ) Receives an DOM element and transforms it into a valid container for 3D transformed content. The only CSS properties that will be altered are perspective, transform and transform-style. If the element's position is static, it will be changed to relative.
Use this method to get a rectangular viewport if your 3D content is not covering the whole page. The origin will be the top-left corner of the element.
Sprite3D.box( width, height, depth ) Creates the required elements to display a cube with the given dimensions. The faces of the cube will have class names reflecting their respective position (front,back,left,right,top,bottom)
Sprite3D.isSupported() Returns a boolean value indicating if the library has found support for CSS 3D transforms in current browser.
Sprite3D.stage() Creates and returns a DIV element absolutely positionned in the center of the page with the needed CSS properties set to act as a root container for all your 3D content.
Use this method if you want to create full page 3D content with centered origin.
Sprite3D.stage( DOMElement ) Receives an DOM element and transforms it into a valid container for 3D transformed content. The only CSS properties that will be altered are perspective, transform and transform-style. If the element's position is static, it will be changed to relative.
Use this method to get a rectangular viewport if your 3D content is not covering the whole page. The origin will be the top-left corner of the element.
Sprite3D.cube( width, height, depth ) Creates the required elements to display a cube with the given dimensions. The faces of the cube will have class names reflecting their respective position (front,back,left,right,top,bottom)

Position

Usage Description
x() returns the coordinates of the sprite on the X axis
x(v) sets the coordinates of the sprite on the X axis
y() returns the coordinates of the sprite on the Y axis
y(v) sets the coordinates of the sprite on the Y axis
z() sets the coordinates of the sprite on the Z axis
z(v) sets the coordinates of the sprite on the Z axis
position(x,y,z) sets the coordinates of the sprite on all three axis
move(x,y,z) adds the supplied values to the current coordinates of the sprite on all 3 axis
move(x,y) adds the supplied values to the current coordinates of the sprite on the X and Y axis
origin(x,y,z) Defines the registration point of the 3D object. If you have a div that is 50x50px and want it to be positionned by it center, use sprite.origin( 25, 25, 0 ). You can also drop the third argument and use sprite.origin( 25, 25 )

Rotation

Usage Description
rotationX() returns the current rotation of the sprite around the X axis
x(v) sets the coordinates of the sprite on the X axis
y() returns the current rotation of the sprite around the Y axis
y(v) sets the coordinates of the sprite on the Y axis
z() returns the current rotation of the sprite around the Z axis
z(v) sets the coordinates of the sprite on the Z axis
position(x,y,z) sets the coordinates of the sprite on all three axis
move(x,y,z) adds the supplied values to the current coordinates of the sprite on all 3 axis
move(x,y) adds the supplied values to the current coordinates of the sprite on the X and Y axis
origin(x,y,z) Defines the registration point of the 3D object. If you have a div that is 50x50px and want it to be positionned by it center, use sprite.origin( 25, 25, 0 ). You can also drop the third argument and use sprite.origin( 25, 25 )

Scale

Usage Description
scaleX() returns the X scale factor of the object
scale() returns the X scale factor of the object
scale( s ) uniformly scale the sprite on all three axis
returns the sprite object
scale( sx, sy ) sets the scale values for the X and Y axis. Z axis remains unchanged.
returns the sprite object
scale( sx, sy, sz ) sets the scale values for the X, Y and Z axis
returns the sprite object

Updating

Helper functions