Skip to content

Full Tilt API Documentation

Jump to bottom
richtr edited this page Nov 20, 2014 · 9 revisions

FULLTILT

The root FULLTILT API object.

Methods

FULLTILT.getDeviceOrientation( [ options ] )

Obtain a new Promise object for Device Orientation Events.

If this Promise object is resolved then the current platform supports Device Orientation Events and a FULLTILT.DeviceOrientation object is provided in the resolved Promise function.

If this Promise object is rejected then the current platform does not support Device Orientation Events and an error string is provided in the rejected Promise function.

Arguments:

  • options - an optional object to override the default FULLTILT.DeviceOrientation object creation settings. Set type to world for compass-based device orientation calculations and game for non-compass-based device orientation calculations. If no type is specified then the library will use whatever type is inherently supported by the current UA (world for Android-based browsers, game for iOS-based browsers).

Returns:

A new Promise object.

Example:

var promise = FULLTILT.getDeviceOrientation({'type': 'world'});

promise
  .then(
    function(deviceOrientation) {
      // Use `deviceOrientation` object to interact with device orientation sensors
    }
  ).catch(
    function(message) {
      // Device Orientation Events are not supported
  
      // Implement manual fallback controls instead...
    }
  );
FULLTILT.getDeviceMotion( [ options ] )

Obtain a new Promise object for Device Motion Events.

If this Promise object is resolved then the current platform supports Device Motion Events and a FULLTILT.DeviceMotion object is provided in the resolved Promise function.

If this Promise object is rejected then the current platform does not support Device Motion Events and an error string is provided in the rejected Promise function.

Arguments:

  • options - an optional object to override the default FULLTILT.DeviceMotion object creation settings. This is a placeholder argument as currently no options are provided for creating new FULLTILT.DeviceMotion objects.

Returns:

A new Promise object.

Example:

var promise = FULLTILT.getDeviceMotion();

promise
  .then(
    function(deviceMotion) {
      // Use `deviceMotion` object to interact with device motion sensors
    }
  ).catch(
    function(message) {
      // Device Motion Events are not supported
  
      // Implement manual fallback controls instead...
    }
  );

FULLTILT.DeviceOrientation

Constructor

new FULLTILT.DeviceOrientation( [ options ] )

Create a new FULLTILT.DeviceOrientation object.

However, it is highly recommended to obtain new FULLTILT.DeviceOrientation objects via FULLTILT.getDeviceOrientation( [options] ) instead.

Arguments:

  • options - a dictionary object that accepts a type attribute. Set type to world for compass-based device orientation calculations and game for non-compass-based device orientation calculations. If no type is specified then the library will use whatever type is inherently supported by the current UA (optional)

Returns:

A new FULLTILT.DeviceOrientation object.

Example:

// Create a new *compass-based* FULLTILT.DeviceOrientation object
var orientationData = new FULLTILT.DeviceOrientation( { 'type': 'world' } );

or:

// Create a new *game-based* FULLTILT.DeviceOrientation object
var orientationData = new FULLTILT.DeviceOrientation( { 'type': 'game' } );

Methods

.start( [ callback ] )

Start the controller and register all required device orientation event listeners.

If this FULLTILT.DeviceOrientation object was created via the FULLTILT.getDeviceOrientation( [ options ] ) function then this method will be called automatically and does not need to be manually re-invoked.

Optionally, you can pass in a JavaScript function that will be called each time a new DeviceOrientation event is fired by the current browser.

Example 1:

orientationData.start();

Example 2:

orientationData.start(function() {
  // DeviceOrientation updated

  var matrix = orientationData.getScreenAdjustedMatrix();

  // Do something with rotation matrix `matrix`...
});
.stop()

Stop the controller and de-register all required device orientation event listeners

Example:

orientationData.stop();
.listen( [ callback ] )

An alias of .start( [callback] ).

.isAvailable( attribute )

Returns true if the requested attribute is available from the platform, otherwise this returns false.

Available attribute values are as follows:

  • .ALPHA
  • .BETA
  • .GAMMA

Example:

orientationData.isAvailable(orientationData.ALPHA); // true or false
.getFixedFrameQuaternion()

Return the last available device orientation as a fixed-frame Quaternion object.

Example:

// Return an object of type FULLTILT.Quaternion (without screen rotation adjustments applied)
var quat = orientationData.getFixedFrameQuaternion();
.getScreenAdjustedQuaternion()

Return the last available device orientation as a screen-adjusted Quaternion object.

Example:

// Return an object of type FULLTILT.Quaternion (with screen rotation adjustments applied)
var quat = orientationData.getScreenAdjustedQuaternion();
.getFixedFrameMatrix()

Return the last available device orientation as a fixed-frame RotationMatrix object.

Example:

// Return an object of type FULLTILT.RotationMatrix (without screen rotation adjustments applied)
var matrix = orientationData.getFixedFrameMatrix();
.getScreenAdjustedMatrix()

Return the last available device orientation as a screen-adjusted RotationMatrix object.

Example:

// Return an object of type FULLTILT.RotationMatrix (with screen rotation adjustments applied)
var matrix = orientationData.getScreenAdjustedMatrix();
.getFixedFrameEuler()

Return the last available device orientation as a fixed-frame Euler object.

Example:

// Return an object of type FULLTILT.Euler (without screen rotation adjustments applied)
var angles = orientationData.getFixedFrameEuler();
.getScreenAdjustedEuler()

Return the last available device orientation as a screen-adjusted Euler object.

Example:

// Return an object of type FULLTILT.Euler (with screen rotation adjustments applied)
var angles = orientationData.getScreenAdjustedEuler();
.isAbsolute()

Returns true if the device orientation is reporting to be compass-orientated otherwise return false to suggest that the device orientation returned is arbitrarily (non-compass) oriented.

At present iOS device orientation should always return false while Android device orientation should always return true.

Example:

// Check if the data is aligned to a real-world compass bearing
var isCompassOriented = orientationData.isAbsolute();
.getLastRawEventData()

Return the last available original (unprocessed, non-screen-adjusted) device orientation event data provided by the web browser.

Example:

// Return the original raw deviceorientation event object
var deviceOrientationEvent = orientationData.getLastRawEventData();

FULLTILT.DeviceMotion

Constructor

new FULLTILT.DeviceMotion( [ options ] )

Create a new FULLTILT.DeviceMotion object.

However, it is highly recommended to obtain new FULLTILT.DeviceMotion objects via FULLTILT.getDeviceMotion( [options] ) instead.

Arguments:

  • options - a dictionary object. This is a placeholder argument as currently no options are provided for creating new FULLTILT.DeviceMotion objects (optional)

Returns:

A new FULLTILT.DeviceMotion object.

Example:

// Create a new FULLTILT.DeviceMotion object
var motionData = new FULLTILT.DeviceMotion();

Methods

.start( [ callback ] )

Start the controller and register all required device motion event listeners.

If this FULLTILT.DeviceMotion object was created via the FULLTILT.getDeviceMotion( [ options ] ) function then this method will be called automatically and does not need to be manually re-invoked.

Optionally, you can pass in a JavaScript function that will be called each time a new DeviceMotion event is fired by the current browser.

Example 1:

motionData.start();

Example 2:

motionData.start(function() {
  // DeviceMotion updated

  var acc = motionData.getScreenAdjustedAcceleration();

  // Do something with `acc`...
});
.stop()

Stop the controller and de-register all required device motion event listeners

Example:

motionData.stop();
.listen( [ callback ] )

An alias of .start( [callback] ).

.isAvailable( attribute )

Returns true if the requested attribute is available from the platform, otherwise this returns false.

Available attribute values are as follows:

  • .ACCELERATION_X
  • .ACCELERATION_Y
  • .ACCELERATION_Z
  • .ACCELERATION_INCLUDING_GRAVITY_X
  • .ACCELERATION_INCLUDING_GRAVITY_Y
  • .ACCELERATION_INCLUDING_GRAVITY_Z
  • .ROTATION_RATE_ALPHA
  • .ROTATION_RATE_BETA
  • .ROTATION_RATE_GAMMA

Example 1:

motionData.isAvailable(motionData.ACCELERATION_INCLUDING_GRAVITY_X); // true or false

Example 2:

motionData.isAvailable(motionData.ROTATION_RATE_GAMMA); // true or false
.getScreenAdjustedAcceleration()

Return the last available screen-adjusted acclerometer values.

Example:

var acc = motionData.getScreenAdjustedAcceleration();
.getScreenAdjustedAccelerationIncludingGravity()

Return the last available screen-adjusted acclerometer values including gravity components.

Example:

var accGrav = motionData.getScreenAdjustedAccelerationIncludingGravity();
.getScreenAdjustedRotationRate()

Return the last available screen-adjusted rotation rate values.

Example:

var rotRate = motionData.getScreenAdjustedRotationRate();
.getLastRawEventData()

Return the last available original (non-screen-adjusted) device motion event data provided by the web browser.

Example:

// Return the original raw devicemotion event object
var deviceMotionEvent = motionData.getLastRawEventData();

FULLTILT.Quaternion

Constructor

new FULLTILT.Quaternion( [x, y, z, w] )

Create a new FULLTILT.Quaternion object.

Arguments:

  • x - the initial x component (optional)
  • y - the initial y component (optional)
  • z - the initial z component (optional)
  • w - the initial w component (optional)

Returns:

A new FULLTILT.Quaternion object.

Example:

// Create a new FULLTILT.Quaternion object
var quat = new FULLTILT.Quaternion( 0, 0, 0, 1 );

is equivalent to:

var quat = new FULLTILT.Quaternion();

Properties

.x
.y
.z
.w

Methods

.set( [x, y, z, w] ) this

Sets the raw values of the current Quaternion object.

Example:

var quat = new FULLTILT.Quaternion();
quat.set(Math.sin(90), 0, 0, Math.cos(90));
.copy( quaternion ) this`

Copies the value of the supplied Quaternion object to the current object.

Example:

var quat1 = new FULLTILT.Quaternion();
var quat2 = new FULLTILT.Quaternion(0, Math.sin(45), 0, Math.cos(45));

quat1.copy(quat2);
.setFromEuler( euler ) this

Sets the component values of this quaternion object from a ZXY-based Euler object.

Example:

var quat = new FULLTILT.Quaternion();
var euler = new FULLTILT.Euler(90, 0, -45);

quat.setFromEuler(euler);
.setFromRotationMatrix( matrix ) this

Sets the component values of this quaternion object from the provided RotationMatrix object.

Example:

var quat = new FULLTILT.Quaternion();
var matrix = new FULLTILT.RotationMatrix(1,0,0,0,1,0,0,0,1);

quat.setFromRotationMatrix(matrix);
.multiply( quaternion ) this`

Multiplies the current object quaternion by the supplied quaternion.

Example:

var quat1 = new FULLTILT.Quaternion(Math.sin(270), 0, 0, Math.cos(270));
var quat2 = new FULLTILT.Quaternion(0, Math.sin(45), 0, Math.cos(45));

quat1.multiply(quat2); // quat1 * quat2
.rotateX( radians ) this`

Rotate the current object quaternion around its x-axis by the supplied angle (in Radians).

Example:

var quat = new FULLTILT.Quaternion(Math.sin(270), 0, 0, Math.cos(270));

quat.rotateX(Math.PI / 2); // rotate this quaternion by 90 degrees along its X-axis
.rotateY( radians ) this`

Rotate the current object quaternion around its y-axis by the supplied angle (in Radians).

Example:

var quat = new FULLTILT.Quaternion(0, Math.sin(45), 0, Math.cos(45));

quat.rotateY(Math.PI / 4); // rotate this quaternion by 45 degrees along its Y-axis
.rotateZ( radians ) this`

Rotate the current object quaternion around its z-axis by the supplied angle (in Radians).

Example:

var quat = new FULLTILT.Quaternion(0, 0, Math.sin(10), Math.cos(10));

quat.rotateY( 20 * (Math.PI / 180) ); // rotate this quaternion by 20 degrees along its Z-axis

FULLTILT.RotationMatrix

Constructor

new FULLTILT.RotationMatrix( [m11, m12, m13, m21, m22, m23, m31, m32, m33] )

Create a new FULLTILT.RotationMatrix object.

Arguments:

The matrix component values to initially set for the object (optional).

Returns:

A new FULLTILT.RotationMatrix object.

Example:

// Create a new FULLTILT.RotationMatrix object
var matrix = new FULLTILT.RotationMatrix( 1, 0, 0, 0, 1, 0, 0, 0, 1 );

is equivalent to:

var matrix = new FULLTILT.RotationMatrix();

Properties

.elements

A ByteArray containing the 9 values of the rotation matrix

Methods

.set( m11, m12, m13, m21, m22, m23, m31, m32, m33 ) this

Sets the raw values of this rotation matrix object.

Example:

var matrix = new FULLTILT.RotationMatrix();

matrix.set(1,0,0,0,1,0,0,0,1);
.copy( matrix ) this`

Copies the component values of the supplied rotation matrix.

Example:

var matrix1 = new FULLTILT.RotationMatrix();
var matrix2 = new FULLTILT.RotationMatrix();
matrix2.setFromEuler(new FULLTILT.Euler(45.4, 0, 10.1));

matrix1.copy(matrix2);
.setFromEuler( euler ) this

Sets the component values of this rotation matrix object from a ZXY-based Euler object.

Example:

var matrix = new FULLTILT.RotationMatrix();
var euler = new FULLTILT.Euler(290.00123, 10.752, 32.2313)

matrix.setFromEuler(euler);
.setFromQuaternion( quaternion ) this

Sets the component values of this rotation matrix object from the provided Quaternion object.

Example:

var matrix = new FULLTILT.RotationMatrix();
var quaternion = new FULLTILT.Quaternion(0,0,0,1);

matrix.setFromQuaternion(quaternion);
.multiply( matrix ) this`

Multiplies the current object rotation matrix by the supplied rotation matrix.

Example:

var matrix1 = new FULLTILT.RotationMatrix();
var matrix2 = new FULLTILT.RotationMatrix();
matrix2.rotateX(90 * (Math.PI / 180));

matrix1.multiply(matrix2); // matrix1 * matrix2
.rotateX( radians ) this`

Rotate the current object rotation matrix around its x-axis by the supplied angle (in Radians).

Example:

var matrix = new FULLTILT.RotationMatrix();

matrix.rotateX(270 * (Math.PI / 180)); // rotate matrix by 270 degrees around its Z-axis
.rotateY( radians ) this`

Rotate the current object rotation matrix around its y-axis by the supplied angle (in Radians).

Example:

var matrix = new FULLTILT.RotationMatrix();

matrix.rotateY(Math.PI / 2); // rotate matrix by 90 degrees around its Y-axis
.rotateZ( radians ) this`

Rotate the current object rotation matrix around its z-axis by the supplied angle (in Radians).

Example:

var matrix = new FULLTILT.RotationMatrix();

matrix.rotateZ(Math.sqrt(0.5)); // rotate matrix by Math.PI/2 around its Z-axis

FULLTILT.Euler

Constructor

new FULLTILT.Euler( [alpha, beta, gamma] )

Create a new FULLTILT.Euler object.

Arguments:

  • alpha - the initial z-axis rotation in Degrees (optional)
  • beta - the initial x-axis rotation in Degrees (optional)
  • gamma - the initial y-axis rotation in Degrees (optional)

Returns:

A new FULLTILT.Euler object.

Example:

// Create a new FULLTILT.Euler object
var euler = new FULLTILT.Euler( 0, 0, 0 );

is equivalent to:

var euler = new FULLTILT.Euler();

Properties

.alpha

The computed rotation around the z-axis (in Degrees).

.beta

The computed rotation around the x-axis (in Degrees).

.gamma

The computed rotation around the y-axis (in Degrees).

Methods

.set( [alpha, beta, gamma] ) this

Sets the component values of this Euler object.

Example:

var euler = new FULLTILT.Euler();

euler.set(270, 45, 45);
.copy( euler ) this`

Copies the component values of the supplied Euler object.

Example:

var euler1 = new FULLTILT.Euler();
var euler2 = new FULLTILT.Euler();
euler2.setFromQuaternion(new FULLTILT.Quaternion(0, Math.sin(45), 0, Math.cos(45)));

euler1.copy(euler2);
.setFromQuaternion( quaternion ) this

Sets the component values of this Euler object from the provided Quaternion object.

Example:

var euler = new FULLTILT.Euler();
var quat = new FULLTILT.Quaternion(0,0,0,1);

euler.setFromQuaternion(quat);
.setFromRotationMatrix( matrix ) this

Sets the component values of this Euler object from the provided RotationMatrix object.

Example:

var euler = new FULLTILT.Euler();
var matrix = new FULLTILT.RotationMatrix();
matrix.rotateX(90 * (Math.PI / 180));

euler.setFromRotationMatrix(matrix);
.rotateX( radians ) this`

Rotate the current object Euler angles around its x-axis by the supplied angle (in Radians).

Example:

var euler = new FULLTILT.Euler();

euler.rotateX(Math.sqrt(0.5)); // rotate by Math.PI/2 around the X axis.
.rotateY( radians ) this`

Rotate the current object Euler angles around its y-axis by the supplied angle (in Radians).

Example:

var euler = new FULLTILT.Euler();

euler.rotateY(Math.PI/4); // rotate by 45 degrees around the Y axis.
.rotateZ( radians ) this`

Rotate the current object Euler angles around its z-axis by the supplied angle (in Radians).

Example:

var euler = new FULLTILT.Euler();

euler.rotateZ(10 * (Math.PI / 180)); // rotate by 10 degrees around the Z axis.
Full Tilt / version 0.7

https://github.com/Full-Tilt/Full-Tilt

Go to Full Tilt repository

Clone this wiki locally