Class: Sprite3D

Sprite3D

new Sprite3D(element, data)

Sprite3D basically is a 2D container moving around in the 3D world that always faces direct front. Instead of rotating, it moves through images in a spritesheet that represent a 360 degree rotation of an object (such as a 360 degree render) around either the X or Y axis. In this way we have a 3D rendering that can be rotated.

Due to some complexity in the way 3D euler angles work (i.e. 2 different combos of rotX, rotY, rotZ can technically lead to the same exact orientation) using the true concatenated 3D angles doesn't work so hot. A good way to approximate for these purposes, however, is to just add the local rotY of the child and every parent (or rotX if that's what you're using) just for figuring what frame the Sprite3D should be on for its rotation. It's not technically perfectly accurate for complex usage, but for most usage it works fine.

In automatic scene creation based on the DOM this class is automatically created for any element with a CSS class dom3d-sprite3d and must have the attributes data-src="image-path.png" data-width="10" data-height="10" data-frames="10" for the path to the spritesheet, the width of the frames, height of frames, and total frame count, and can optionally have the attributes data-regX="10" data-regY="10" to set a registration point (the Sprite3D class allows this to be set because you don't control the internal elements of this object, so you can't do it yourself by offsetting them).
Parameters:
Name Type Description
element An argument identifying the HTML Element the display object is to associate with. Can be the actual element itself, an HTML string representing an element to create, or a query selector string which will identify the intended HTML element already in the DOM.
data An initialization object consisting of the .src, .width, .height, .frames properties to use (just like the above description of the data-attributes) and optionally the .regX and .regY properties to use.
Source:

Extends

Members

(readonly) element :HTMLElement

Every DisplayObject3D represents an HTML Element. You can access that element by accessing the object's element property. Conversely any element that has an associated DisplayObject3D will have a property .dom3dObject which references its DisplayObject3D.
Type:
  • HTMLElement
Inherited From:
Default Value:
  • null
Source:

id :String

Each DisplayObject3D has a unique id property. When the element it represents has an id attribute at the time of instantiation it will match its element's id. Otherwise a unique one will be generated. You can also assign your own.
Type:
  • String
Inherited From:
Default Value:
  • ""
Source:

(readonly) innerSprite :HTMLElement

Pointss to the HTMLElement inside the associated .element which is actually having the spritesheet applied to it.
Type:
  • HTMLElement
Default Value:
  • null
Source:

inverse :Boolean

A value of true inverts the axis of rotation in case your 3D sprite turns out to have been animated backwards to what the Sprite3D class expects.
Type:
  • Boolean
Default Value:
  • false
Source:

(readonly) isDisplayObject3D :Boolean

Any dom3d object meant to be part of the display list/stage will have this property as true.
Type:
  • Boolean
Inherited From:
Default Value:
  • true
Source:

(readonly) isSprite3D :Boolean

A Sprite3D will have an isSprite3D property of true for identification purposes. isDisplayObject3D (which is inherited) will also exist as a uniform way to identify dom3d display objects in general.
Type:
  • Boolean
Default Value:
  • true
Source:

(readonly) parent :DisplayObject3D

Each DisplayObject3D has a parent property that allows it to tell which object is currently this object's parent in the display list. Null if it is not in the display list.
Type:
Inherited From:
Default Value:
  • null
Source:

(readonly) ready :Boolean

A Boolean telling whether the sprite sheet is currently loaded and ready.
Type:
  • Boolean
Default Value:
  • false
Source:

rotationOffset :Number

Offsets the Sprite3D zero rotation with your animation. Example: offsetting by 180 would make the middle of your animation be considered the 0 degree showing frame. Note: never set to more than + or - your rotationRange. Can be positive or negative.
Type:
  • Number
Default Value:
  • 0
Source:

rotationRange :Number

For load speed purposes if you're not using the full 360 degree rotation of your object you can tell Sprite3D how many degrees its supposed to cover when dividing up your animation sprite. Never set to more than 360. Positive numbers only.
Type:
  • Number
Default Value:
  • 360
Source:

rotX :Number

The rotX property sets the x-axis rotation value for the DisplayObject3D instance in degrees.

This property can be set automatically upon instantiation by having a data-rotX attribute on the element set to a number.
Type:
  • Number
Inherited From:
Default Value:
  • 0
Source:

rotY :Number

The rotY property sets the y-axis rotation value for the DisplayObject3D instance in degrees.

This property can be set automatically upon instantiation by having a data-rotY attribute on the element set to a number.
Type:
  • Number
Inherited From:
Default Value:
  • 0
Source:

rotZ :Number

The rotZ property sets the z-axis rotation value for the DisplayObject3D instance in degrees.

This property can be set automatically upon instantiation by having a data-rotZ attribute on the element set to a number.
Type:
  • Number
Inherited From:
Default Value:
  • 0
Source:

(readonly) stage3D :Stage3D

Each DisplayObject3D has a stage3D property that allows it to tell which stage it is currently in the display list of. Is null when not in a display list.
Type:
Inherited From:
Default Value:
  • null
Source:

(readonly) type :String

A Sprite3D will have a type property of "Sprite3D" for identification purposes.
Type:
  • String
Default Value:
  • "Sprite3D"
Source:

useRotX :Boolean

Set this to true if your animation is around the x-axis instead of y-axis.
Type:
  • Boolean
Default Value:
  • false
Source:

x :Number

The x property sets the x coordinate value for the DisplayObject3D instance.

This property can be set automatically upon instantiation by either having a CSS style left property set in pixels, or a data-x attribute on the element set to a number.
Type:
  • Number
Inherited From:
Default Value:
  • 0
Source:

y :Number

The y property sets the y coordinate value for the DisplayObject3D instance.

This property can be set automatically upon instantiation by either having a CSS style top property set in pixels, or a data-y attribute on the element set to a number.
Type:
  • Number
Inherited From:
Default Value:
  • 0
Source:

z :Number

The z property sets the z coordinate value for the DisplayObject3D instance.

This property can be set automatically upon instantiation by having a data-z attribute on the element set to a number.
Type:
  • Number
Inherited From:
Default Value:
  • 0
Source:

Methods

onLoaded()

This method is meant to be overridden by you in order for you to be able to catch the loading of the sprite sheet image. the this keyword will point to the Sprite3D instance it is called for.
Source:

setX(value) → {DisplayObject3D}

setX (and likewise the setY, setZ, setRotX, setRotY, and setRotZ which are not documented because they operate the same as setX but for their respective properties) is a method that allows you to set the x coordinate value in a chainable way like is familiar in libraries such as jQuery. So myObj.setX(20).setY(20); is legitimate to set the x and y to 20. It also allows relative changes via a string using operators, such as "+=20", "*=2" or just "++" and "--" increments. This is much slower than just setting the properties, but useful nonetheless in some situations.
Parameters:
Name Type Description
value Number | String The new number value to set it to, or the string indicating the relative change to happen.
Inherited From:
Source:
Returns:
Returns this DisplayObject3D for chaining purposes.
Type
DisplayObject3D