Class Sprite3D

Defined in: Sprite3D.js.

Class Summary
Constructor Attributes	Constructor Name and Description
	Sprite3D(element) Creates an instance of Sprite3D

Field Summary
Field Attributes	Field Name and Description
	children An array holding references of the Sprite3D's children object
	domElement A reference to the DOM element associated with this Sprite3D object
	height The height of the HTML element associated with the Sprite3D object
	numChildren The number of child objects
	regX The X-axis registration point of the Sprite3D object used for 3D positionning
	regY The Y-axis registration point of the Sprite3D object used for 3D positionning
	regZ The Y-axis registration point of the Sprite3D object used for 3D positionning
	rotateFirst A boolean value to decide in which order transformations are applied.
	rotationX The X-axis rotation of the Sprite3D
	rotationY The Y-axis rotation of the Sprite3D
	rotationZ The Z-axis rotation of the Sprite3D
	scaleX The X-axis scale of the Sprite3D
	scaleY The Y-axis scale of the Sprite3D
	scaleZ The Z-axis scale of the Sprite3D
	style A reference to the CSS style object of the DOM element
	tileHeight The height (in pixels) of the tiles in the spritesheet
	tileWidth The width (in pixels) of the tiles in the spritesheet
	transformString The transform string.
	width The width of the HTML element associated with the Sprite3D object
	x The X-axis position of the Sprite3D
	y The Y-axis position of the Sprite3D
	z The Z-axis position of the Sprite3D

Method Summary
Method Attributes	Method Name and Description
	addChild(e) Adds a Sprite3D object to this Sprite3D children.
	addClassName(className) Adds a CSS class to the DOM element This method does not require a call to the update methods.
	addEventListener(event, callback) Adds an event listener to the DOM element for the provided event id.
<static>	Sprite3D.createCenteredContainer() Creates a centered empty HTML div element to be used as root container for the other Sprite3D objects.
<static>	Sprite3D.createTopLeftCenteredContainer() Creates a top-left aligned empty HTML div element to be used as root container for the other Sprite3D objects.
	findFromDOMElement(element) Finds and return the Sprite3D object associated with the provided DOM element
	getClassName() Returns the name of the CSS class of the DOM element.
	getCSS(name) Returns the value assigned to the provided CSS property.
	getId() Returns the ID of the DOM element associated with the Sprite3D.
	getOpacity() Returns the opacity of the element.
<static>	Sprite3D.isSupported() Test for CSS 3D transforms support in the current browser.
	move(px, py, pz) Applies a relative translation in 3D space.
	moveX(px) Applies a relative translation in 3D space on the X-axis.
	moveY(py) Applies a relative translation in 3D space on the Y-axis.
	moveZ(pz) Applies a relative translation in 3D space on the Z-axis.
	removeChild(child) Removes a Sprite3D object from this Sprite3D children.
	removeChildAt(n) Removes the nth Sprite3D object from this Sprite3D children.
	removeClassName(className) [BETA] Removes a CSS class from the DOM element This method does not require a call to the update methods.
	removeEventListener(event, callback) Removes an event listener to the DOM element for the provided event id.
	rotate(rx, ry, rz) Applies a relative rotation in 3D space.
	rotateX(rx) Applies a relative rotation in 3D space around the X-axis.
	rotateY(ry) Applies a relative rotation in 3D space around the Y-axis.
	rotateZ(rz) Applies a relative rotation in 3D space around the Z-axis.
	setClassName(className) Sets the CSS class name of the DOM element associated with the Sprite3D object.
	setCSS(name, value) Allows to set any value in any CSS property of the style object of the DOM element.
	setId(id) Sets the ID of the DOM element in the document.
	setInnerHTML(value) Allows direct write access to the innerHTML property of the DOM element.
	setOpacity(alpha) Sets the opacity of the element.
	setPosition(px, py, pz) Sets the 3D position of the Sprite.
	setProperty(label, value) Allows to set a arbitary property value while using the chaining syntax.
	setRegistrationPoint(rx, ry, rz) Sets the registrations point for the Sprite3D object.
	setRotateFirst(rf) Sets the order in which transformations are applied.
	setRotation(rx, ry, rz) Sets the 3D rotation of the Sprite.
	setRotationX(rx) Sets the amount of rotation around the X-axis of the Sprite3D.
	setRotationY(ry) Sets the amount of rotation around the Y-axis of the Sprite3D.
	setRotationZ(rz) Sets the amount of rotation around the Z-axis of the Sprite3D.
	setScale(sx, sy, sz) Sets the scaling of the Sprite3D object on the 3 axis.
	setScaleX(sx) Sets the scaling of the Sprite3D object on the X-axis.
	setScaleY(sy) Sets the scaling of the Sprite3D object on the Y-axis.
	setScaleZ(sz) Sets the scaling of the Sprite3D object on the Z-axis.
	setSize(width, height) Sets the size of the HTML element linked to the Sprite3D object, using the width and height css properties.
	setTilePosition(tilePosX, tilePosY) Modifies the sprites's background image position to display the selected tile.
	setTileSize(width, height) Sets the size of the tiles in the spritesheet used as background image.
	setTransformOrigin(px, py) Sets the origin of the 3D transforms.
	setTransformString(ts) Sets the value of the transformString property, allowing to control transformations order.
	setX(px) Sets the X-axis position of the Sprite3D.
	setY(py) Sets the Y-axis position of the Sprite3D.
	setZ(pz) Sets the Z-axis position of the Sprite3D.
	update() Applies position and rotation values.
	update2D() Applies 2D position, rotation and scaling values.
	updateAll() Applies position and rotation values, as well as opacity and size.
	updateChildren() Calls the update() method on every child of the Sprite3D object.
	updateChildrenAll() Calls the updateAll() method on every child of the Sprite3D object.
	updateWithChildren(recursive) Updates itself, then calls the update() method on every child of the Sprite3D object.

Class Detail

Sprite3D(element)

Creates an instance of Sprite3D
Author: boblemarin.

Parameters:
{Object} element: The DOM element to wrap the Sprite3D object around. When no element is provided, a empty div is created and added to the document.

Field Detail

children

An array holding references of the Sprite3D's children object

domElement

A reference to the DOM element associated with this Sprite3D object

height

The height of the HTML element associated with the Sprite3D object

numChildren

The number of child objects

regX

The X-axis registration point of the Sprite3D object used for 3D positionning

regY

The Y-axis registration point of the Sprite3D object used for 3D positionning

regZ

The Y-axis registration point of the Sprite3D object used for 3D positionning

rotateFirst

A boolean value to decide in which order transformations are applied. If true, rotations are applied before translations. If false, translations are applied before rotations. For a more accurate control over transformations order, you should use the transformString property. This property is now BROKEN.

rotationX

The X-axis rotation of the Sprite3D

rotationY

The Y-axis rotation of the Sprite3D

rotationZ

The Z-axis rotation of the Sprite3D

scaleX

The X-axis scale of the Sprite3D

scaleY

The Y-axis scale of the Sprite3D

scaleZ

The Z-axis scale of the Sprite3D

style

A reference to the CSS style object of the DOM element

tileHeight

The height (in pixels) of the tiles in the spritesheet

tileWidth

The width (in pixels) of the tiles in the spritesheet

transformString

The transform string. You can use this property to fine control the order in which transformations are applied. The following values will be replaced by their respective transformations : _p for position/translations _s for scaling _rx for rotationX _ry for rotationY _rz for rotationZ Example: sprite.transformString = "_rx _ry _rz _p _s";

width

The width of the HTML element associated with the Sprite3D object

The X-axis position of the Sprite3D

The Y-axis position of the Sprite3D

The Z-axis position of the Sprite3D

Method Detail

{Sprite3D} addChild(e)

Adds a Sprite3D object to this Sprite3D children.

Parameters:
{Sprite3D} e: The Sprite3D object to add

Returns:: {Sprite3D} The reference to the added Sprite3D object

{Sprite3D} addClassName(className)

Adds a CSS class to the DOM element This method does not require a call to the update methods.

Parameters:
{String} className: The name of the class to be added

Returns:: {Sprite3D} The reference to this Sprite3D object

{Sprite3D} addEventListener(event, callback)

Adds an event listener to the DOM element for the provided event id.

Parameters:
{String} event: The name of the event to watch
{Function} callback: The callback function

Returns:: {Sprite3D} The reference to this Sprite3D object

<static> {Sprite3D} Sprite3D.createCenteredContainer()

Creates a centered empty HTML div element to be used as root container for the other Sprite3D objects.

Returns:: {Sprite3D} The created Sprite3D object

<static> {Sprite3D} Sprite3D.createTopLeftCenteredContainer()

Creates a top-left aligned empty HTML div element to be used as root container for the other Sprite3D objects.

Returns:: {Sprite3D} The created Sprite3D object

{Sprite3D} findFromDOMElement(element)

Finds and return the Sprite3D object associated with the provided DOM element

Parameters:
{Object} element: The DOM element

Returns:: {Sprite3D} The reference to the associated Sprite3D object. Returns null if no relevant Sprite3D object was found

{String} getClassName()

Returns the name of the CSS class of the DOM element.

Returns:: {String} The CSS class name

{String} getCSS(name)

Returns the value assigned to the provided CSS property.

Parameters:
{String} name: The name of the property to get the value from

Returns:: {String} The value of the CSS property

{String} getId()

Returns the ID of the DOM element associated with the Sprite3D.

Returns:: {String} The CSS class name

{Number} getOpacity()

Returns the opacity of the element.

Returns:: {Number} The opacity of the element

<static> {boolean} Sprite3D.isSupported()

Test for CSS 3D transforms support in the current browser. If 3D transforms are not supported, the update() method is replaced by the update2D() method, providing an automatic fallback that might save some bits :)

Returns:: {boolean} True if the 3D transforms are supported by the browser

{Sprite3D} move(px, py, pz)

Applies a relative translation in 3D space.

Parameters:
{Number} px: The value of the translation on the X-axis
{Number} py: The value of the translation on the Y-axis
{Number} pz: The value of the translation on the Z-axis

Returns:: {Sprite3D} The reference to this Sprite3D object

{Sprite3D} moveX(px)

Applies a relative translation in 3D space on the X-axis.

Parameters:
{Number} px: The value of the translation

Returns:: {Sprite3D} The reference to this Sprite3D object

{Sprite3D} moveY(py)

Applies a relative translation in 3D space on the Y-axis.

Parameters:
{Number} py: The value of the translation

Returns:: {Sprite3D} The reference to this Sprite3D object

{Sprite3D} moveZ(pz)

Applies a relative translation in 3D space on the Z-axis.

Parameters:
{Number} pz: The value of the translation

Returns:: {Sprite3D} The reference to this Sprite3D object

{Sprite3D} removeChild(child)

Removes a Sprite3D object from this Sprite3D children.

Parameters:
{Sprite3D} child: The Sprite3D object to remove

Returns:: {Sprite3D} The reference to the removed Sprite3D object. null if the child was not found in this Sprite3D children list

{Sprite3D} removeChildAt(n)

Removes the nth Sprite3D object from this Sprite3D children.

Parameters:
{number} n: The index of the Sprite3D object to remove

Returns:: {Sprite3D} The reference to the removed Sprite3D object.

{Sprite3D} removeClassName(className)

[BETA] Removes a CSS class from the DOM element This method does not require a call to the update methods.

Parameters:
{String} className: The name of the class to be removed

Returns:: {Sprite3D} The reference to this Sprite3D object

{Sprite3D} removeEventListener(event, callback)

Removes an event listener to the DOM element for the provided event id.

Parameters:
{String} event: The name of the event to watch
{Function} callback: The callback function

Returns:: {Sprite3D} The reference to this Sprite3D object

{Sprite3D} rotate(rx, ry, rz)

Applies a relative rotation in 3D space.

Parameters:
{Number} rx: The value of the rotation around the X-axis
{Number} ry: The value of the rotation around the Y-axis
{Number} rz: The value of the rotation around the Z-axis

Returns:: {Sprite3D} The reference to this Sprite3D object

{Sprite3D} rotateX(rx)

Applies a relative rotation in 3D space around the X-axis.

Parameters:
{Number} rx: The value of the rotation

Returns:: {Sprite3D} The reference to this Sprite3D object

{Sprite3D} rotateY(ry)

Applies a relative rotation in 3D space around the Y-axis.

Parameters:
{Number} ry: The value of the rotation

Returns:: {Sprite3D} The reference to this Sprite3D object

{Sprite3D} rotateZ(rz)

Applies a relative rotation in 3D space around the Z-axis.

Parameters:
{Number} rz: The value of the rotation

Returns:: {Sprite3D} The reference to this Sprite3D object

{Sprite3D} setClassName(className)

Sets the CSS class name of the DOM element associated with the Sprite3D object. When applying multiple class names, provide a single string with space-separated class names like you would do in pure CSS manipulation. This method does not require a call to the update methods.

Parameters:
{String} className: The name of the class to be set

Returns:: {Sprite3D} The reference to this Sprite3D object

{Sprite3D} setCSS(name, value)

Allows to set any value in any CSS property of the style object of the DOM element. This method is just a helper allowing neverending chaining in the Sprite3D creation syntax. For one time modifications, you can simply use the style property of the Sprite3D. This method does not require a call to the update methods.

Parameters:
{String} name: The name of the CSS property in which the value will be stored
{String} value: The value to assign to the property

Returns:: {Sprite3D} The reference to this Sprite3D object

{Sprite3D} setId(id)

Sets the ID of the DOM element in the document. This method is just a helper allowing neverending chaining in the Sprite3D creation syntax. You can also simply access the domElement property of the Sprite3D and set its id property. This method does not require a call to the update methods.

Parameters:
{String} id: The ID

Returns:: {Sprite3D} The reference to this Sprite3D object

{Sprite3D} setInnerHTML(value)

Allows direct write access to the innerHTML property of the DOM element.

Parameters:
{String} value: The string to write into the innerHTML property

Returns:: {Sprite3D} The reference to this Sprite3D object

{Sprite3D} setOpacity(alpha)

Sets the opacity of the element. This method applies the changes to the style object, so it does not require a call to the update methods

Parameters:
{Number} alpha: The desired opacity, ranging from 0 to 1

Returns:: {Sprite3D} The reference to this Sprite3D object

{Sprite3D} setPosition(px, py, pz)

Sets the 3D position of the Sprite.

Parameters:
{Number} px: The position on the X-axis
{Number} py: The position on the Y-axis
{Number} pz: The position on the Z-axis

Returns:: {Sprite3D} The reference to this Sprite3D object

{Sprite3D} setProperty(label, value)

Allows to set a arbitary property value while using the chaining syntax.

Parameters:
{String} label: The name of the property
{Object} value: The value for that property

Returns:: {Sprite3D} The reference to this Sprite3D object

{Sprite3D} setRegistrationPoint(rx, ry, rz)

Sets the registrations point for the Sprite3D object. By default, CSS positionning is relative to the top left corner of the element. The registration point values are simply substracted from the position when applied

Parameters:
{Number} rx: The registration point value for the X-axis
{Number} ry: The registration point value for the Y-axis
{Number} rz: The registration point value for the Z-axis

Returns:: {Sprite3D} The reference to this Sprite3D object

{Sprite3D} setRotateFirst(rf)

Sets the order in which transformations are applied. If true, rotations are applied before translations. If false, translations are applied before rotations. Note that, when applying rotations, the axis of the object rotate, and subsequent translations follow the modified orientation of the axis. For a more accurate control, you should use the transformString property.

Parameters:
{boolean} rf: true to rotate first, false to translate first

Returns:: {Sprite3D} The reference to this Sprite3D object

{Sprite3D} setRotation(rx, ry, rz)

Sets the 3D rotation of the Sprite.

Parameters:
{Number} rx: The rotation around the X-axis
{Number} ry: The rotation around the Y-axis
{Number} rz: The rotation around the Z-axis

Returns:: {Sprite3D} The reference to this Sprite3D object

{Sprite3D} setRotationX(rx)

Sets the amount of rotation around the X-axis of the Sprite3D.

Parameters:
{Number} rx: The value of the rotation

Returns:: {Sprite3D} The reference to this Sprite3D object

{Sprite3D} setRotationY(ry)

Sets the amount of rotation around the Y-axis of the Sprite3D.

Parameters:
{Number} ry: The value of the rotation

Returns:: {Sprite3D} The reference to this Sprite3D object

{Sprite3D} setRotationZ(rz)

Sets the amount of rotation around the Z-axis of the Sprite3D.

Parameters:
{Number} rz: The value of the rotation

Returns:: {Sprite3D} The reference to this Sprite3D object

{Sprite3D} setScale(sx, sy, sz)

Sets the scaling of the Sprite3D object on the 3 axis.

Parameters:
{Number} sx: The value of the scaling on the X-axis
{Number} sy: The value of the scaling on the Y-axis
{Number} sz: The value of the scaling on the Z-axis

Returns:: {Sprite3D} The reference to this Sprite3D object

{Sprite3D} setScaleX(sx)

Sets the scaling of the Sprite3D object on the X-axis.

Parameters:
{Number} sx: The value of the scaling on the X-axis

Returns:: {Sprite3D} The reference to this Sprite3D object

{Sprite3D} setScaleY(sy)

Sets the scaling of the Sprite3D object on the Y-axis.

Parameters:
{Number} sy: The value of the scaling on the Y-axis

Returns:: {Sprite3D} The reference to this Sprite3D object

{Sprite3D} setScaleZ(sz)

Sets the scaling of the Sprite3D object on the Z-axis.

Parameters:
{Number} sz: The value of the scaling on the Z-axis

Returns:: {Sprite3D} The reference to this Sprite3D object

{Sprite3D} setSize(width, height)

Sets the size of the HTML element linked to the Sprite3D object, using the width and height css properties. Note that animating using these properties does not provide an optimal performance. You should rather try to use CSS scale using the scale() method This method applies the changes to the style object, so it does not require a call to the update methods

Parameters:
{Number} width: The desired width
{Number} height: The desired height

Returns:: {Sprite3D} The reference to this Sprite3D object

{Sprite3D} setTilePosition(tilePosX, tilePosY)

Modifies the sprites's background image position to display the selected tile. For this method to work, you are supposed to set a background image and limit the size of the element using CSS styles, and use a sprite sheet where all tiles have the same size. No checking is performed on the provided values.

Parameters:
{Number} tilePosX: The horizontal index of the tile to be displayed
{Number} tilePosY: The vertical index of the tile to be displayed

Returns:: {Sprite3D} The reference to this Sprite3D object

{Sprite3D} setTileSize(width, height)

Sets the size of the tiles in the spritesheet used as background image.

Parameters:
{Number} width: The desired width
{Number} height: The desired height

Returns:: {Sprite3D} The reference to this Sprite3D object

{Sprite3D} setTransformOrigin(px, py)

Sets the origin of the 3D transforms. By default, CSS transforms are relative to the center of the element.

Parameters:
{Number} px: The transform origin value for the X-axis
{Number} py: The transform origin value for the Y-axis

Returns:: {Sprite3D} The reference to this Sprite3D object

{Sprite3D} setTransformString(ts)

Sets the value of the transformString property, allowing to control transformations order. A valid value may be "_rx _ry _rz _p _s". See the transformString property for more informations.

Parameters:
{String} ts: The string that will be used to swap

Returns:: {Sprite3D} The reference to this Sprite3D object

{Sprite3D} setX(px)

Sets the X-axis position of the Sprite3D.

Parameters:
{Number} px: The position

Returns:: {Sprite3D} The reference to this Sprite3D object

{Sprite3D} setY(py)

Sets the Y-axis position of the Sprite3D.

Parameters:
{Number} py: The position

Returns:: {Sprite3D} The reference to this Sprite3D object

{Sprite3D} setZ(pz)

Sets the Z-axis position of the Sprite3D.

Parameters:
{Number} pz: The position

Returns:: {Sprite3D} The reference to this Sprite3D object

{Sprite3D} update()

Applies position and rotation values.

Returns:: {Sprite3D} The reference to this Sprite3D object

{Sprite3D} update2D()

Applies 2D position, rotation and scaling values. This method allows to use Sprite3D with browsers that only support 2D transforms. When applying the transforms, it uses the x and y position, z rotation and x and y scaling. The other values are ignored.

Returns:: {Sprite3D} The reference to this Sprite3D object

{Sprite3D} updateAll()

Applies position and rotation values, as well as opacity and size.

Returns:: {Sprite3D} The reference to this Sprite3D object

{Sprite3D} updateChildren()

Calls the update() method on every child of the Sprite3D object.

Returns:: {Sprite3D} The reference to this Sprite3D object

{Sprite3D} updateChildrenAll()

Calls the updateAll() method on every child of the Sprite3D object.

Returns:: {Sprite3D} The reference to this Sprite3D object

{Sprite3D} updateWithChildren(recursive)

Updates itself, then calls the update() method on every child of the Sprite3D object.

Parameters:
{boolean} recursive: If set to true, make the update call recursive, update every child's children

Returns:: {Sprite3D} The reference to this Sprite3D object

Classes

Class Sprite3D