Wikitude SDK API Reference

API Docs for: 8.4.0
Show:

context Class

Module: AR

context includes some general functions which allow interaction with system components.

The Singleton instance of the class will automatically be created on World startup and can be accessed via AR.context.

context also allows for some custom functionality, for example onLocationChanged, which will be triggered by the system as soon as the user's location changes. It enables the developer to find out about the user's location and thus setup the AR scene to his needs.

Example:
AR.context.onLocationChanged = function(latitude, longitude, altitude, accuracy){
  //now, add custom functionality to build the AR scene based on the location
  ...
}

Methods

destroyAll

()

Destroys all objects.

See AR.ARchitectObject.destroy() for effects of this call.

openInBrowser

(
  • url
  • forceNativeBrowser
)

Opens the specified url in the native Browser. If forceNativeBrowser is true, the URL will be opened in the native browser (e.g. Safari on iOS), otherwise it will be opened in a new webview.

Parameters:

  • url String

    the url to be opened

  • forceNativeBrowser (defaults to false) Boolean optional

    open URL in native browser (true) or in a webview within the application (false).

setCloudRecognitionServerRegion

(
  • region
  • options
)
deprecated

Deprecated: Use AR.CloudRecognitionService cloudRecognitionServerURL option

Sets the desired server region to be used. Regions can be chosen among the Americas, China and Europe with Europe being the default behaviour. Invalid input parameters results in Europe silently being chosen.

Parameters:

  • region String

    integer value identifying the region {1 : Americas, 2 : China, 3 : Europe} Please refer to the CONST.js file for the definition of the region enumeration.

  • options Object optional

    Additional Parameters to explicitly specify the cloud recognition server by URL. Please note that if a custom cloud recognition server URL is given, the region parameter is ignored.

    Accepted options-properties are

startVideoPlayer

(
  • uri
)

Starts the native video player and plays the video at the specified URI. Will close the video player automatically when the video finished.

Parameters:

  • uri String

    the uri to the video

Properties

clickBehavior

String

clickBehavior controls what should be considered a click. The following options are available:

  • AR.CONST.CLICK_BEHAVIOR.CLICK: the platform considers a click only when the user presses and releases the screen at the same screen region. The click is fired after the user releases the finger from the screen
  • AR.CONST.CLICK_BEHAVIOR.TOUCH_DOWN: click fires as soon as the user touches the screen
  • AR.CONST.CLICK_BEHAVIOR.TOUCH_UP: click fires as soon as the user puts the finger off the screen, regardless of where the user started the touch on the screen.

Default: AR.CONST.CLICK_BEHAVIOR.CLICK

scene.cullingDistance

Number

The maximum distance at which objects are visible in the scene, in meters. If an object's distance to the user is further than the culling distance, the object will not be visible in the scene. Must be a positive whole number.

Default: 50000

scene.globalScale

Float

The amount of scaling that is applied to all drawables in the scene. Use this value to alter the drawable size on different devices so that the world appears in a common look when running on different devices.

Must be in the range of [-1, MAX_FLOAT].

Setting the global scale to 0 will scale all drawables to a size of 0.
Setting the global scale to -1 indicates that the SDK should calculate the value by itself, so that all drawables are equal in pixel size among different devices.

Automatic Scaling
The reference device is a 4 inch iPhone screen (e.g. iPhone 5). All other devices will adjust their global scale so that drawables will appear in the size as if the world would run on the reference device.

Default: 1.0

scene.maxScalingDistance

Number

The distance, in meters, at which objects will keep their size on the screen even when the user moves further away. If the user is further than maxScalingDistance, the object will not appear any smaller than the size it took on at maxScalingDistance. Must be a positive whole number.

Default: 20000

scene.minScalingDistance

Number

The distance, in meters, at which objects will start to appear smaller on the screen when the user moves further away. If the user is closer than minScalingDistance, the object will not appear any bigger than the size it took on at minScalingDistance. Must be a positive whole number.

Default: 10

scene.scalingFactor

Number

The amount of scaling that is applied between minScalingDistance and maxScalingDistance. The scalingFactor controls the size the object takes on at maxScalingDistance, in percentage of the size it took on at minScalingDistance.

Must be in the range of [0,1].

Set the scalingFactor to 1 if no scaling should be applied for the objects.

Default: 0.1

versionNumber

String

Returns the Wikitude SDK version number. The string is formatted in a dot notation with a major, minor and bugfix part. E.g. 4.0.0

Events

on2FingerGestureEnded

executed when the user finishes a 2 finger gesture; a 1 finger gesture could still be active now

on2FingerGestureStarted

executed when the user initiates a 2 finger gesture; a 1 finger gesture could have been active before

onDragBegan

Executed when the user starts dragging on the screen with a single finger, no HTML element was hit by the initiating touch and either

  • no Drawable or InstantTrackble was hit by the initiating touch, or
  • Drawables or InstantTrackables were hit by the initiating touch, but even the last thereof in the touch queue returned false in its onDragBegan trigger.

Event Payload:

  • xNormalized Number

    the distance on the X-axis between the initiating touch position and the updated touch position [-1, 1]; always 0 in onDragBegan as no change to the drag gesture has occurred yet

  • yNormalized Number

    the distance on the Y-axis between the initiating touch position and the updated touch position [-1, 1]; always 0 in onDragBegan as no change to the drag gesture has occurred yet

onDragChanged

Executed when the user drags on the screen with a single finger, no HTML element was hit by the updated touch and either

  • no Drawable or InstantTrackble was hit by the updated touch, or
  • Drawables or InstantTrackables were hit by the updated touch, but even the last thereof in the touch queue returned false in its onDragChanged trigger.

Event Payload:

  • xNormalized Number

    the distance on the X-axis between the initiating touch position and the updated touch position [-1, 1]

  • yNormalized Number

    the distance on the Y-axis between the initiating touch position and the updated touch position [-1, 1]

onDragEnded

Executed when the user stops dragging on the screen with a single finger, no HTML element was hit by the final touch and either

  • no Drawable or InstantTrackble was hit by the final touch, or
  • Drawables or InstantTrackables were hit by the final touch, but even the last thereof in the touch queue returned false in its onDragEnded trigger.

Event Payload:

  • xNormalized Number

    the distance on the X-axis between the initiating touch position and the updated touch position [-1, 1]; always identical to the most recent distance received in onDragChanged

  • yNormalized Number

    the distance on the Y-axis between the initiating touch position and the updated touch position [-1, 1]; always identical to the most recent distance received in onDragChanged

onLocationChanged

The function will be called as soon as

  • the location is fetched the first time, or
  • the location of the user changes.

The trigger is null by default, and will thus result in no action executed when the trigger fires. A developer can add custom functionality by assigning a custom function to onLocationChanged.

Event Payload:

  • latitude Number

    the current latitude of the user, based on WGS84

  • longitude Number

    the current longitude of the user, based on WGS84

  • altitude Number

    the current altitude of the user, based on WGS84

  • accuracy Number

    The accuracy of the reported location, see AR.CONST.LOCATION_ACCURACY for details

onPanBegan

Executed when the user starts dragging on the screen with two fingers, no HTML element was hit by the first touch and either

  • no Drawable or InstantTrackble was hit by the first touch, or
  • Drawables or InstantTrackables were hit by the first touch, but even the last thereof in the touch queue returned false in its onPanBegan trigger.

Event Payload:

  • xNormalized Number

    the distance on the X-axis between the initiating touch positions and the updated touch positions [-1, 1]; always 0 in onPanBegan as no change to the pan gesture has occurred yet; the mid-points between the first and second touches are used to calculate the distances to allow co-operative behaviour with the scale and rotate gesture

  • yNormalized Number

    the distance on the Y-axis between the initiating touch position and the updated touch position [-1, 1]; always 0 in onPanBegan as no change to the pan gesture has occurred yet; the mid-points between the first and second touches are used to calculate the distances to allow co-operative behaviour with the scale and rotate gesture

onPanChanged

Executed when the user drags on the screen with two fingers, no HTML element was hit by the first touch and either

  • no Drawable or InstantTrackble was hit by the first touch, or
  • Drawables or InstantTrackables were hit by the first touch, but even the last thereof in the touch queue returned false in its onPanChanged trigger.

Event Payload:

  • xNormalized Number

    the distance on the X-axis between the initiating touch positions and the updated touch positions [-1, 1]; the mid-points between the first and second touches are used to calculate the distances to allow co-operative behaviour with the scale and rotate gesture

  • yNormalized Number

    the distance on the Y-axis between the initiating touch position and the updated touch position [-1, 1]; the mid-points between the first and second touches are used to calculate the distances to allow co-operative behaviour with the scale and rotate gesture

onPanEnded

Executed when the user stops dragging on the screen with two fingers, no HTML element was hit by the first touch and either

  • no Drawable or InstantTrackble was hit by the first touch, or
  • Drawables or InstantTrackables were hit by the first touch, but even the last thereof in the touch queue returned false in its onPanEnded trigger.

Event Payload:

  • xNormalized Number

    the distance on the X-axis between the initiating touch positions and the updated touch positions [-1, 1]; always identical to the most recent distance received in onPanChanged; the mid-points between the first and second touches are used to calculate the distances to allow co-operative behaviour with the scale and rotate gesture

  • yNormalized Number

    the distance on the Y-axis between the initiating touch position and the updated touch position [-1, 1]; always identical to the most recent distance received in onPanChanged; the mid-points between the first and second touches are used to calculate the distances to allow co-operative behaviour with the scale and rotate gesture

onRotationBegan

Executed when the user starts rotating on the screen with two fingers, no HTML element was hit by the first touch and either

  • no Drawable or InstantTrackble was hit by the first touch, or
  • Drawables or InstantTrackables were hit by the first touch, but even the last thereof in the touch queue returned false in its onRotationBegan trigger.

Event Payload:

  • angle Number

    the CCW angle in degree between the line defined by the initiating touch positions and the line defined by the updated touch positions [0, 360); always 0 in onRotationBegan as no change to the rotation gesture has occurred yet

onRotationChanged

Executed when the user rotates on the screen with two fingers, no HTML element was hit by the first touch and either

  • no Drawable or InstantTrackble was hit by the first touch, or
  • Drawables or InstantTrackables were hit by the first touch, but even the last thereof in the touch queue returned false in its onRotationChanged trigger.

Event Payload:

  • angle Number

    the CCW angle in degree between the line defined by the initiating touch positions and the line defined by the updated touch positions [0, 360)

onRotationEnded

Executed when the user stops rotating on the screen with two fingers, no HTML element was hit by the first touch and either

  • no Drawable or InstantTrackble was hit by the first touch, or
  • Drawables or InstantTrackables were hit by the first touch, but even the last thereof in the touch queue returned false in its onRotationEnded trigger.

Event Payload:

  • angle Number

    the CCW angle in degree between the line defined by the initiating touch positions and the line defined by the updated touch positions [0, 360); always identical to the most recent angle received in onRotationChanged

onScaleBegan

Executed when the user starts scaling on the screen with two fingers, no HTML element was hit by the first touch and either

  • no Drawable or InstantTrackble was hit by the first touch, or
  • Drawables or InstantTrackables were hit by the first touch, but even the last thereof in the touch queue returned false in its onScaleBegan trigger.

Event Payload:

  • scale Number

    the scale value defined the ratio of the distance between the updated touches over the distance between the initiating touches [0, inf]; always 1 in onScaleBegan as no change to the scale gesture has occurred yet

onScaleChanged

Executed when the user starts scaling on the screen with two fingers, no HTML element was hit by the first touch and either

  • no Drawable or InstantTrackble was hit by the first touch, or
  • Drawables or InstantTrackables were hit by the first touch, but even the last thereof in the touch queue returned false in its onScaleChanged trigger.

Event Payload:

  • scale Number

    the scale value defined the ratio of the distance between the updated touches over the distance between the initiating touches [0, inf]

onScaleEnded

Executed when the user starts scaling on the screen with two fingers, no HTML element was hit by the first touch and either

  • no Drawable or InstantTrackble was hit by the first touch, or
  • Drawables or InstantTrackables were hit by the first touch, but even the last thereof in the touch queue returned false in its onScaleEnded trigger.

Event Payload:

  • scale Number

    the scale value defined the ratio of the distance between the updated touches over the distance between the initiating touches [0, inf]; always identical to the most recent scale received in onScaleChanged

onScreenClick

Executed when the user clicks on the screen, no HTML element was hit and either

  • no Drawable was hit on the click, or
  • Drawables were hit on the click, but even the last Drawable in the click queue returned false in its onClick trigger.

See AR.Drawable.onClick() for details on the click-queue.