Skip to content

Latest commit

 

History

History
186 lines (98 loc) · 5.4 KB

SharedAPI.md

File metadata and controls

186 lines (98 loc) · 5.4 KB

class SharedAPI extends Settable, Transformable :id=SharedAPI

This is an abstract base class that provides common properties and methods for the non-abstract Element3D and Scene custom element classes.

This class is not intended for extension by end users. You'll want to extend from Scene or Element3D (or their subclasses) instead of this class.

For purposes of documentation it is still useful to know what properties and methods subclasses inherit from here.

Properties

Inherits properties from Settable, Transformable.

.isScene :id=isScene

True if a subclass of this class is a Scene.

.isElement3D :id=isElement3D

True if a subclass of this class is an Element3D.

.opacity :id=opacity

attribute

Default: 1

Set the object's opacity.

The value should be a number from 0 to 1. 0 is fully transparent, and 1 is fully opaque.

.debug :id=debug

attribute

Default: false

When true, show debug visuals for the object. Not all objects implement debug visuals yet.

.glLoaded :id=glLoaded

DEPRECATED Now always true. For logic depending on this in an effect (f.e. returning early when false), instead init things when an element is connected, and uninit when an element is disconnected.

readonly

.cssLoaded :id=cssLoaded

DEPRECATED Now always true. For logic depending on this in an effect (f.e. returning early when false), instead init things when an element is connected, and uninit when an element is disconnected.

readonly

.scene :id=scene

signal, readonly

The <lume-scene> that the element is a child or grandchild of, null if the element is not a descendant of a Scene, null if the child is a descendant of a Scene that is not connected into the DOM, or null if the element is a descendant of a connected Scene but the element is not participating in the composed tree (i.e. the element is not distributed to a <slot> element of a ShadowRoot of the element's parent).

.three :id=three

readonly

The WebGL rendering content of this element. Useful if you know Three.js APIs. See Object3D.

.threeCSS :id=threeCSS

readonly

The CSS rendering content of this element. Useful if you know Three.js APIs. See THREE.Object3D.

.version :id=version

signal

Default: 0

Incremented any time the element has been updated for rendering in an animation frame. Any time this changes, it means the underlying Three.js world matrices for this element and its sub tree have been calculated.

Methods

Inherits methods from Settable, Transformable.

.recreateThree(): void :id=recreateThree

Replaces the current three object with a new one, reconnecting it to the same parent and children. This can be useful in scenarios where a property of a three object needs to be updated but the property can only be updated via the constructor, requiring us to make a new object.

.recreateThreeCSS(): void :id=recreateThreeCSS

Replaces the current threeCSS object with a new one, reconnecting it to the same parent and children. This can be useful in scenarios where a property of a threeCSS object needs to be updated but the property can only be updated via the constructor, requiring us to make a new object.

.needsUpdate(): void :id=needsUpdate

Schedules a rendering update for the element. Usually you don't need to call this when using the outer APIs, as setting attributes or properties will queue an update.

But if you're doing something special to an Element3D or a Scene, f.e. modifying the .three or .threeCSS properties whose updates are not tracked (are not reactive), you should call this so that LUME will know to re-render the visuals for the element.

Example:

const mesh = document.querySelector('lume-mesh')

// Custom modification of underlying Three.js objects:
mesh.three.material.transparent = true
mesh.three.material.opacity = 0.4
mesh.three.add(new THREE.Mesh(...))

// Tell LUME the elements needs to be re-rendered.
mesh.needsUpdate()

.makeThreeObject3d(): void :id=makeThreeObject3d

protected

Creates a LUME element's Three.js object for WebGL rendering. <lume-mesh> elements override this to create and return THREE.Mesh instances, for example.

.makeThreeCSSObject(): void :id=makeThreeCSSObject

protected

Creates a LUME element's Three.js object for CSS rendering. At the moment this is not overriden by any subclasses, and always creates CSS3DObjectNested instances for CSS rendering, which is a modified version of THREE.CSS3DObject.