Skip to content

Element3D.md

Latest commit

 

History

History
144 lines (97 loc) · 4.96 KB

Element3D.md

File metadata and controls

144 lines (97 loc) · 4.96 KB
Raw

class Element3D extends SharedAPI :id=Element3D

Element: <lume-element3d>

Element3D is the backing class for <lume-element3d> elements, the most primitive of the LUME 3D elements.

Element3D contains the basics that all elements in a 3D scene need, such as a transform (position, rotation, scale, align-point, mount-point, origin), size, and mechanisms of reactivity.

All elements in a 3D scene are an instance of Element3D, including more advanced elements that render different types of visuals. For example, <lume-sphere> is an element that renders a sphere on the screen and is backed by the Sphere class which extends from Element3D.

All Nodes must be a child of a Scene node (<lume-scene> elements) or another Element3D (or anything that extends from Element3D). If a <lume-element3d> element is a child of anything else, it will not do anything currently.

The Element3D class (backing <lume-element3d> elements) is useful for the following:

  • Transform a parent node in 3D space, and it will transform all its children and grandchildren along with it. For example, if you scale a parent Element3D, then all its children are scaled along too.
  • Transform child Nodes relative to their parent.
  • Render traditional HTML content by placing any regular HTML elements as children of a <lume-element3d> element. See the next example.
  • Extend the Element3D class to make new types of 3D elements relying on the basic features that Element3D provides. Other classes that extend from Element3D may, for example, create layouts, or render WebGL content.

Example

The following example shows traditional HTML content inside a 3D scene, as well as the concept of a hierarchy of nodes called a "scene graph".

Regular HTML content is places in each <lume-element3d> element. CSS is applied to the nodes to give them rounded borders. Standard <img /> elements are used display the sun images.

We create a hierarchy of nodes. We give each node further down in the hiearchy a smaller size. We use align and mount-point attributes to align Nodes to one corner of their parent. align controls where a node is mounted relative to their parent, and mount-point specifies the point in the child that is aligned in the parent. See the alignment guide for how that works.

Each node has the same amount of rotation directly applied to it. Due to the hiearchy, the rotations add up. The parent most node has the least amount of rotation, and the child-most nodes have the most rotation and also are more displaced due to rotation of their parents. See the scene graph guide for details on how the hierarchy works.

Finally, we listen to mouse or finger movement events in order to apply a rotation to the root node based on the current mouse or finger position. See the events guide for how the event system works.

Properties

Inherits properties from SharedAPI.

.isElement3D :id=isElement3D

readonly

Always true for things that are or inherit from Element3D.

.visible :id=visible

attribute

Default: true

Whether or not the node will be visible (if it renders anything). For <lume-element3d> elements, this only applies if the element has CSS styling or traditional HTML content inside of it (children), otherwise <lume-element3d> element's don't have any visual output by default. Other nodes that have default visual output like <lume-box> or <lume-sphere> will not be visible if this is false, and their rendering mechanics will be skipped.

If an Element3D is not visible, its children are also not visible.

Methods

Inherits methods from SharedAPI.

.constructor(): void :id=constructor

Create a Element3D instance.

The following examples calls .set() to set initial properties. Any properties passed into .set() are applied to the instance. For example, writing

var node = new Element3D().set({
  size: {x:100, y:100, z:100},
  rotation: {x:30, y:20, z:25}
})

is the same as writing

var node = new Element3D()
node.size = {x:100, y:100, z:100}
node.rotation = {x:30, y:20, z:25}

.traverseSceneGraph(): undefined :id=traverseSceneGraph

This traverses the composed tree of LUME 3D elements (the scene graph) including this element, in pre-order. It skips non-LUME elements.

This is similar to Scene#traverseSceneGraph but traversal includes the Element3D that this is called on.

Example:

node.traverseSceneGraph(n => {
  console.log(node === n) // true for the first call only
  console.log(n instanceof LUME.Element3D) // true
})