Class: Stage3D

Stage3D

new Stage3D(element, autoRenderopt, FPSopt)

All 3D elements to be rendered are to be added to a Stage3D instance. Even though it inherits from DisplayObject3D it should be treated like a 2D object in the DOM as far as its own positioning/rotating goes. Any x, y, z, rotX, rotY, and rotZ properties are not intended to function; just use CSS positioning. If you want a container for 3D elements that you can move and rotate in 3D space then see Group3D.

Also note that a Stage3D needs to be updated each frame. If autoRender is used (as is default) it will just constantly update. This is not as taxing as it would seem since it uses a diry/clean rendering system. For slightly better performance you can update manually as needed using the update method.

This Stage3D will attempt to automatically set up the 3D scene based on its child elements and their CSS classes. To avoid this you can not give it any child elements, or mark all its direct child elements with the CSS class "dom3d-no-3d".

In almost all ways the API to the Stage3D is a mimic of the Group3D. You can treat manipulation of display list children within them almost identically (e.g. addChild, removeChild, getChildById, etc).
Parameters:
Name Type Attributes Default 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.
autoRender Boolean <optional>
true Shortcut to the set autoRender property.
FPS Number <optional>
30 Allows you to determine the update rate of the autoRender in frames per second.
Source:

Extends

Members

autoRender :Boolean

Allows you to turn off/on autoRender. If false then you must tell the scene to update manually via the update method.
Type:
  • Boolean
Default Value:
  • true
Source:

(readonly) children :Array

Allows access to the Array of child objects for this container. Special care should be taken when accessing to not modify the original Array.
Type:
  • Array
Default Value:
  • [empty Array]
Source:

distortion :Number

distortion affects how the location of objects are distorted (lesser for further away, more for closer) as they move on the z-axis. Experiment to get the effect that works for your use.
Type:
  • Number
Default Value:
  • 6
Source:

(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:

FPS :Number

Allows you to determine the rate at which the scene updates during autoRender. If changed while autoRendering then autoRender must be toggled off and back on for the change to take effect.
Type:
  • Number
Default Value:
  • 30
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) 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) isGroup :Boolean

A Stage3D will have an isGroup property of true for identification purposes. Both Stage3D and Group3D will have this property as true, as they are both container/group type concepts. However, Group3D will have an isGroup3D property of true (which a Stage3D will not) and a Stage3D will have an isStage3D property of true (which Group3D will not). This property is made to identify this object as a general concept of grouping/containing 3D elements, as opposed to identifying a certain class.
Type:
  • Boolean
Default Value:
  • true
Source:

(readonly) isStage3D :Boolean

A Stage3D will have an isStage3D 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) stage3D :Stage3D

Stage3D inherits the stage3D property from DisplayObject3D, which identifies the root stage. However, it will simply always point to itself in the case of a Stage3D object.
Type:
Overrides:
Default Value:
  • this
Source:

(readonly) type :String

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

zoom :Number

zoom affects how objects are scaled as they move on the z-axis. Experiment to get the effect that works for your use.
Type:
  • Number
Default Value:
  • 5000
Source:

Methods

addChild() → {DisplayObject3D}

addChild allows objects to be added to this Stage3D. Note: Stage3D instances are meant to be roots of a 3D scene. Do not add a Stage3D to another Stage3D.
Parameters:
Type Description
DisplayObject3D Any object that inherits from DisplayObject3D may be added.
Source:
Returns:
Returns this Stage3D object for chaining.
Type
DisplayObject3D

contains() → {Boolean}

contains allows you to check if a DisplayObject3D is contained (has been added via addChild) by the Stage3D
Parameters:
Type Description
DisplayObject3D The object to test for.
Source:
Returns:
Returns a Boolean value for whether the Stage3D contains the object or not.
Type
Boolean

getChildByElement() → {DisplayObject3D}

getChildByElement allows you to get a child of the Stage3D by its associated HTML Element.
Parameters:
Type Description
HTMLElement The associated HTMLElement of the display object you're looking for.
Source:
Returns:
Returns a the DisplayObject3D found if it is found. Returns null of none found.
Type
DisplayObject3D

getChildById() → {DisplayObject3D}

getChildById allows you to get a child of the Stage3D by its id property (which, remember, will match the actual element's id attribute if it had one).
Parameters:
Type Description
String The String id to look for.
Source:
Returns:
Returns a the DisplayObject3D found if it is found. Returns null of none found.
Type
DisplayObject3D

onAfterUpdate()

This method is meant to be overridden by you in order for you to be able to catch the update of a Stage3D instance that is autoRendering. the this keyword will point to the Stage3D instance it is called for. This is called right after the update actually happens.
Source:

onUpdate()

This method is meant to be overridden by you in order for you to be able to catch the update of a Stage3D instance that is autoRendering. the this keyword will point to the Stage3D instance it is called for. This is called right before the update actually happens, just at the time you need to change anything before the scene renders again.
Source:

removeChild() → {Stage3D}

removeChild allows objects that were added via addChild to be removed.
Parameters:
Type Description
DisplayObject3D Any object that inherits from DisplayObject3D and has been added may be removed.
Source:
Returns:
Returns this Stage3D object for chaining purposes.
Type
Stage3D

update()

This method must be called in order for the Stage3D instance to update every time something changes. Normally you let the stage autoRender, which will update 30 fps by default. However, you can turn autoRender off and update manually.
Source: