Class: Viewer

Viewer(domElement, opts)

A Viewer is a container for multiple scenes to be displayed inside a stage contained in the DOM.

Scenes may be created by calling Viewer#createScene. Except during a scene switch, a single one of them, called the current scene, is visible. Calling Viewer#switchScene sets the current scene and switches to it.

Constructor

new Viewer(domElement, opts)

Parameters:
Name Type Description
domElement Element

The DOM element to contain the stage.

opts Object

Viewer creation options.

Properties
Name Type Description
controls Object

Options to be passed to registerDefaultControls.

stage Object

Options to be passed to the Stage constructor.

cursors Object

Cursor options.

Properties
Name Type Description
drag Object

Drag cursor options to be passed to the ControlCursor constructor.

Methods

breakIdleMovement()

Stops the idle movement. It will be started again after the timeout set by Viewer#setIdleMovement.

controls() → {Controls}

Returns the underlying controls.

Returns:
Type
Controls

createEmptyScene(opts) → {Scene}

Creates a new scene with no layers and adds it to the viewer.

Layers may be added to the scene by calling Scene#createLayer. However, if the scene has a single layer, it is simpler to call Viewer#createScene instead of this method.

The current scene does not change. To switch to the scene, call Viewer#switchScene.

Parameters:
Name Type Description
opts Object

Scene creation options.

Properties
Name Type Description
view View

The scene's underlying View.

Returns:
Type
Scene

createScene(opts) → {Scene}

Creates a new scene with a single layer and adds it to the viewer.

The current scene does not change. To switch to the scene, call Viewer#switchScene.

Parameters:
Name Type Description
opts Object

Scene creation options.

Properties
Name Type Attributes Default Description
view View

The scene's underlying View.

source Source

The layer's underlying Source.

geometry Geometry

The layer's underlying Geometry.

pinFirstLevel boolean <optional>
false

Whether to pin the first level to provide a fallback of last resort, at the cost of memory consumption.

textureStoreOpts Object <optional>
{}

Options to pass to the TextureStore constructor.

layerOpts Object <optional>
{}

Options to pass to the Layer constructor.

Returns:
Type
Scene

destroy()

Destructor.

destroyAllScenes()

Destroys all scenes and removes them from the viewer.

destroyScene(scene)

Destroys a scene and removes it from the viewer.

Parameters:
Name Type Description
scene Scene

domElement() → {Element}

Returns the underlying DOM element.

Returns:
Type
Element

hasScene(scene) → {boolean}

Returns whether the viewer contains a scene.

Parameters:
Name Type Description
scene Scene
Returns:
Type
boolean

listScenes() → {Array.<Scene>}

Returns a list of all scenes.

Returns:
Type
Array.<Scene>

lookTo(opts, done)

Tweens the view for the current scene.

This method is equivalent to calling Scene#lookTo on the current scene.

Parameters:
Name Type Description
opts Object

Options to pass into Scene#lookTo.

done function

Function to call when the tween is complete.

movement() → {function}

Returns the current movement.

This method is equivalent to calling Scene#movement on the current scene. If there is no current scene, this is a no-op.

Returns:
Type
function

renderLoop() → {RenderLoop}

Returns the underlying render loop.

Returns:
Type
RenderLoop

scene() → {Scene}

Returns the current scene, or null if there isn't one.

To change the current scene, call Viewer#switchScene.

Returns:
Type
Scene

setIdleMovement(timeout, movement)

Schedules an idle movement to be automatically started when the view remains unchanged for the given timeout period.

Changing the view while the idle movement is active stops the movement and schedules it to start again after the same timeout period. To disable it permanently, call with a null movement or an infinite timeout.

Parameters:
Name Type Description
timeout number

Timeout period in milliseconds.

movement function

Automatic movement function, or null to disable.

stage() → {Stage}

Returns the underlying stage.

Returns:
Type
Stage

startMovement(fn, done)

Starts a movement, possibly replacing the current movement.

This method is equivalent to calling Scene#startMovement on the current scene. If there is no current scene, this is a no-op.

Parameters:
Name Type Description
fn function

The movement function.

done function

Function to be called when the movement finishes or is interrupted.

stopMovement()

Stops the current movement.

This method is equivalent to calling Scene#stopMovement on the current scene. If there is no current scene, this is a no-op.

switchScene(newScene, opts, done)

Switches to another scene with a fade transition. This scene becomes the current one.

If a transition is already taking place, it is interrupted before the new one starts.

Parameters:
Name Type Description
newScene Scene

The scene to switch to.

opts Object

Transition options.

Properties
Name Type Attributes Default Description
transitionDuration number <optional>
1000

Transition duration, in milliseconds.

transitionUpdate number <optional>
defaultTransitionUpdate

Transition update function, with signature f(t, newScene, oldScene). This function is called on each frame with t increasing from 0 to 1. An initial call with t=0 and a final call with t=1 are guaranteed. The default function sets the opacity of the new scene to t.

done function

Function to call when the transition finishes or is interrupted. If the new scene is equal to the old one, no transition takes place, but this function is still called.

updateSize()

Updates the stage size to fill the containing element.

This method is automatically called when the browser window is resized. Most clients won't need to explicitly call it to keep the size up to date.

view() → {View}

Returns the view for the current scene, or null if there isn't one.

Returns:
Type
View

Events

sceneChange

Signals that the current scene has changed.

viewChange

Signals that the view of the current scene has changed. See View#event:change.