API Docs for:

CameraFlightAnimation

A CameraFlightAnimation jumps or flies the Scene's Camera to look at a given target.

  • TODO: Document behaviour for ortho projection
  • TODO: Update docs for camera refactor, where ortho and perspective components will always be present on camera

Overview

  • Can be made to either fly or jump to its target.
  • While busy flying to a target, it can be stopped, or redirected to fly to a different target.

A CameraFlightAnimation's target can be:

  • specific eye, look and up positions,
  • an axis-aligned World-space bounding box (AABB), or
  • an instance or ID of any Component subtype that provides a World-space AABB.

You can configure its fit and fitFOV properties to make it stop at the point where the target occupies a certain amount of the field-of-view.

Examples

Flying to a Mesh

Flying to a Mesh:

// Create a CameraFlightAnimation that takes one second to fly
// the default Scene's Camera to each specified target
var cameraFlight = new xeogl.CameraFlightAnimation({
   fit: true, // Default
   fitFOV: 45, // Default, degrees
   duration: 1 // Default, seconds
}, function() {
          // Arrived
      });

// Create a Mesh, which gets all the default components
var mesh = new Mesh();

// Fly to the Mesh's World-space AABB
cameraFlight.flyTo(mesh);

Flying to a position

Flying the CameraFlightAnimation from the previous example to specified eye, look and up positions:

cameraFlight.flyTo({
   eye: [-5,-5,-5],
   look: [0,0,0]
   up: [0,1,0],
   duration: 1 // Default, seconds
}, function() {
         // Arrived
     });

Flying to an AABB

Flying the CameraFlightAnimation from the previous two examples explicitly to the Boundary3D axis-aligned bounding box:

cameraFlight.flyTo(mesh.aabb);

Constructor

CameraFlightAnimation

(
  • [owner]
  • [cfg.id]
  • [cfg.meta]
  • [cfg.fit=true]
  • [cfg.fitFOV=45]
  • [cfg.trail]
  • [cfg.duration=1]
)

Parameters:

  • [owner] Component optional

    Owner component. When destroyed, the owner will destroy this component as well. Creates this component within the default Scene when omitted.

  • [cfg.id] String optional

    Optional ID, unique among all components in the parent Scene, generated automatically when omitted.

  • [cfg.meta] String:Object optional

    Optional map of user-defined metadata to attach to this CameraFlightAnimation.

  • [cfg.fit=true] Boolean optional

    When true, will ensure that when this CameraFlightAnimation has flown or jumped to a boundary it will adjust the distance between the Camera's Lookat/eye:property and Lookat/look:property position so as to ensure that the target boundary is filling the view volume.

  • [cfg.fitFOV=45] Number optional

    How much field-of-view, in degrees, that a target boundary should fill the canvas when fitting the Camera to the target boundary. Only applies when the Camera's active projection is aPerspective.

  • [cfg.trail] Boolean optional

    When true, will cause this CameraFlightAnimation to point the Camera in the direction that it is travelling.

  • [cfg.duration=1] Number optional

    Flight duration, in seconds, when calling CameraFlightAnimation#flyTo().

Methods

cancel

()

Cancels an earlier flyTo without calling the arrival callback.

create

(
  • [cfg]
)

Convenience method for creating a Component within this Component's Scene.

The method is given a component configuration, like so:

var material = myComponent.create({
     type: "xeogl.PhongMaterial",
     diffuse: [1,0,0],
     specular: [1,1,0]
}, "myMaterial");

Parameters:

  • [cfg] optional

    Configuration for the component instance.

Returns:

:

destroy

()

Destroys this component.

Fires a destroyed event on this Component.

Automatically disassociates this component from other components, causing them to fall back on any defaults that this component overrode on them.

TODO: describe effect with respect to #create

error

(
  • message
)

Logs an error for this component to the JavaScript console.

The console message will have this format: [ERROR] [<component type> =<component id>: <message>

Also fires the message as an error event on the parent Scene.

Parameters:

  • message String

    The message to log

fire

(
  • event
  • value
  • [forget=false]
)

Fires an event on this component.

Notifies existing subscribers to the event, optionally retains the event to give to any subsequent notifications on the event as they are made.

Parameters:

  • event String

    The event type name

  • value Object

    The event parameters

  • [forget=false] Boolean optional

    When true, does not retain for subsequent subscribers

flyTo

(
  • [params=scene]
  • [callback]
  • [scope]
)

Begins flying the Camera's Camera to the given target.

  • When the target is a boundary, the Camera will fly towards the target and stop when the target fills most of the canvas.
  • When the target is an explicit Camera position, given as eye, look and up vectors, then this CameraFlightAnimation will interpolate the Camera to that target and stop there.

Parameters:

  • [params=scene] | Component optional

    Either a parameters object or a Component subtype that has an AABB.

    • [arc=0] Number optional

      Factor in range [0..1] indicating how much the Lookat/eye:property position will swing away from its Lookat/eye:property position as it flies to the target.

    • [component] Number | String | Component optional

      ID or instance of a component to fly to. Defaults to the entire Scene.

    • [aabb] optional

      World-space axis-aligned bounding box (AABB) target to fly to.

    • [eye] Float32Array optional

      Position to fly the eye position to.

    • [look] Float32Array optional

      Position to fly the look position to.

    • [up] Float32Array optional

      Position to fly the up vector to.

    • [fit=true] Boolean optional

      Whether to fit the target to the view volume. Overrides fit.

    • [fitFOV] Number optional

      How much of field-of-view, in degrees, that a target Object or its AABB should fill the canvas on arrival. Overrides fitFOV.

    • [duration] Number optional

      Flight duration in seconds. Overrides duration.

    • [orthoScale] Number optional

      TODO: document this

  • [callback] Function optional

    Callback fired on arrival

  • [scope] Object optional

    Optional scope for callback

flyTo

(
  • params
)

Jumps the Camera's Camera to the given target.

  • When the target is a boundary, this CameraFlightAnimation will position the Camera at where the target fills most of the canvas.
  • When the target is an explicit Camera position, given as eye, look and up vectors, then this CameraFlightAnimation will jump the Camera to that target.

Parameters:

  • params | Component

    Either a parameters object or a Component subtype that has a World-space AABB.

    • [arc=0] Number optional

      Factor in range [0..1] indicating how much the Camera's eye position will swing away from its look position as it flies to the target.

    • [component] Number | String | Component optional

      ID or instance of a component to fly to.

    • [aabb] optional

      World-space axis-aligned bounding box (AABB) target to fly to.

    • [eye] Float32Array optional

      Position to fly the eye position to.

    • [look] Float32Array optional

      Position to fly the look position to.

    • [up] Float32Array optional

      Position to fly the up vector to.

    • [fitFOV] Number optional

      How much of field-of-view, in degrees, that a target Object or its AABB should fill the canvas on arrival. Overrides fitFOV.

    • [fit] Boolean optional

      Whether to fit the target to the view volume. Overrides fit.

hasSubs

(
  • event
)
Boolean

Returns true if there are any subscribers to the given event on this component.

Parameters:

  • event String

    The event

Returns:

Boolean:

True if there are any subscribers to the given event on this component.

isType

(
  • type
)
Boolean

Tests if this component is of the given type, or is a subclass of the given type.

The type may be given as either a string or a component constructor.

This method works by walking up the inheritance type chain, which this component provides in property Component/superTypes:property, returning true as soon as one of the type strings in the chain matches the given type, of false if none match.

Examples:

var myRotate = new xeogl.Rotate({ ... });

myRotate.isType(xeogl.Component); // Returns true for all xeogl components
myRotate.isType("xeogl.Component"); // Returns true for all xeogl components
myRotate.isType(xeogl.Rotate); // Returns true
myRotate.isType(xeogl.Transform); // Returns true
myRotate.isType("xeogl.Transform"); // Returns true
myRotate.isType(xeogl.Mesh); // Returns false, because xeogl.Rotate does not (even indirectly) extend xeogl.Mesh

Parameters:

  • type String | Function

    Component type to compare with, eg "xeogl.PhongMaterial", or a xeogl component constructor.

Returns:

Boolean:

True if this component is of given type or is subclass of the given type.

log

(
  • message
)

Logs a console debugging message for this component.

The console message will have this format: [LOG] [<component type> <component id>: <message>

Also fires the message as a log event on the parent Scene.

Parameters:

  • message String

    The message to log

off

(
  • subId
)

Cancels an event subscription that was previously made with Component#on() or Component#once().

Parameters:

  • subId String

    Publication subId

on

(
  • event
  • callback
  • [scope=this]
)
String

Subscribes to an event on this component.

The callback is be called with this component as scope.

Parameters:

  • event String

    The event

  • callback Function

    Called fired on the event

  • [scope=this] Object optional

    Scope for the callback

Returns:

String:

Handle to the subscription, which may be used to unsubscribe with {@link #off}.

once

(
  • event
  • callback
  • [scope=this]
)

Subscribes to the next occurrence of the given event, then un-subscribes as soon as the event is subIdd.

This is equivalent to calling Component#on(), and then calling Component#off() inside the callback function.

Parameters:

  • event String

    Data event to listen to

  • callback Function(data)

    Called when fresh data is available at the event

  • [scope=this] Object optional

    Scope for the callback

stop

()

Stops an earlier flyTo, fires arrival callback.

warn

(
  • message
)

Logs a warning for this component to the JavaScript console.

The console message will have this format: [WARN] [<component type> =<component id>: <message>

Also fires the message as a warn event on the parent Scene.

Parameters:

  • message String

    The message to log

Properties

destroyed

Boolean

True as soon as this Component has been destroyed

duration

Number

Flight duration, in seconds, when calling CameraFlightAnimation#flyTo().

Stops any flight currently in progress.

Default: 0.5

fit

Boolean

When true, will ensure that this CameraFlightAnimation is flying to a boundary it will always adjust the distance between the CameraFlightAnimation/camera:property's Lookat/eye:property and Lookat/look:property so as to ensure that the target boundary is always filling the view volume.

When false, the eye will remain at its current distance from the look position.

Default: true

fitFOV

Number

How much of the perspective field-of-view, in degrees, that a target Object or its AABB should fill the canvas when calling CameraFlightAnimation#jumpTo() or CameraFlightAnimation/jumpTo:method.

Default: 45

id

String final

Unique ID for this Component within its parent Scene.

metadata

Object

Arbitrary, user-defined metadata on this component.

model

Model final

The Model which contains this Component, if any.

Will be null if this Component is not in a Model.

scene

Scene final

The parent Scene that contains this Component.

trail

Boolean

When true, will cause this CameraFlightAnimation to point the CameraFlightAnimation/camera:property in the direction that it is travelling.

Default: false

type

String final

JavaScript class name for this Component.

For example: "xeogl.AmbientLight", "xeogl.MetallicMaterial" etc.

Events

destroyed

Fired when this Component is destroyed.