BaseApp

lumin. BaseApp

Base class for Lumin Runtime apps.

Methods

(static) CancelMainThreadRunnable(callbackId) → {boolean}

Cancels a previously added runnable if it has not yet run.

Parameters:
Name Type Description
callbackId lumin.utils.CallbackID

the ID returned when the runnable was added.

Returns:

true if the runnable was canceled, false if it has already been scheduled.

Type
boolean

checkPrivilege(privilegeId) → {lumin.PrivilegeResult}

Checks if a privilege is currently granted.

Parameters:
Name Type Description
privilegeId lumin.PrivilegeId

The privilege ID to check

Returns:

Granted or Denied

Type
lumin.PrivilegeResult

deInit() → {number}

Override this method to do one-time de-initialization before quitting.

Returns:
Type
number

deletePrism(prism)

Deletes the prism

Parameters:
Name Type Description
prism lumin.Prism

the Prism to delete

dismissAllNotifications()

Dismss all notifications from this application

dismissNotification(notification) → {boolean}

Dismiss the given notification

Parameters:
Name Type Description
notification lumin.Notification

the notification to dismiss

Returns:

true if the notification was dismissed, false otherwise

Type
boolean

eventListener(a_pEvent) → {boolean}

Override this method to react to incoming events

Note: This is triggered on the same thread as the clientUpdateThread

Parameters:
Name Type Description
a_pEvent lumin.ServerEvent

Server Events

Returns:

true = Event has been consumed

Type
boolean

getComponentName() → {string}

Returns the name of the component this application instance belongs to.

Returns:
Type
string

getCurrentLocaleHelper() → {lumin.utils.LocaleHelper}

Gets the LocaleHelper that's set to the current system locale

Returns:

the current system LocaleHelper

Type
lumin.utils.LocaleHelper

getFloorHeight() → {number}

Returns the height (y-value) of the floor, if known, in world coordinates.

Returns:

Returned floor height.

Type
number

getHeadposeConfidence() → {number}

Get the underlying system's confidence in the headpose values

Returns:

a value between 0.0 and 1.0 indicating the confidence

Type
number

getHeadposeError() → {lumin.headtracking.Error}

Get the current headpose error (if any)

Returns:

the current headpose error

Type
lumin.headtracking.Error

getHeadposeMode() → {lumin.headtracking.Mode}

Get the current headpose mode (6-DOF or 3-DOF)

Returns:

the current headpose mode

Type
lumin.headtracking.Mode

getHeadposeWorldForwardVector() → {vec3}

Get the Headpose forward vector in world space.

Returns:

the world space headpose forward vector.

Type
vec3

getHeadposeWorldPosition() → {vec3}

Get the Headpose position in world space.

Returns:

the world space headpose position.

Type
vec3

getHeadposeWorldUpVector() → {vec3}

Get the Headpose up vector in world space.

Returns:

the world space headpose up vector.

Type
vec3

getLocaleCode() → {string}

Get the system locale code

Returns:
Type
string

getPackageName() → {string}

Returns the package name for this application.

Returns:
Type
string

getPackagePath() → {string}

Returns the application's path

Returns:
Type
string

getPreloadedResources() → {lumin.resources.Preloaded}

Get an object clients can use to find preloaded resources.

Returns:
Type
lumin.resources.Preloaded

getPrism(prismId) → {lumin.Prism}

Returns pointer to the Prism

Parameters:
Name Type Description
prismId BigInt

the Id of the Prism

Returns:

The prism

Type
lumin.Prism

getPrismPosition(a_prism) → {vec3}

Returns the position of a volume in world space

Parameters:
Name Type Description
a_prism lumin.Prism

the prism

Returns:
  • the prism position
Type
vec3

getPrismRotation(a_prism) → {quat}

Returns the rotation of a volume in world space

Parameters:
Name Type Description
a_prism lumin.Prism

the prism

Returns:
  • the prism orientation quaternion
Type
quat

getPrismTransform(a_prism) → {mat4}

Returns the transform of a volume in world space

Parameters:
Name Type Description
a_prism lumin.Prism

the prism

Returns:

The transform of the Prism in world space

Type
mat4

getTempPath() → {string}

Returns the application's path for temporary files

Returns:
Type
string

getVisibleName() → {string}

Returns the user-visible name for this application.

Returns:
Type
string

getWritablePath() → {string}

Returns the application's writable path.

This folder is accessible to the application when the user has logged in once,
even if the device is locked and not in use.
An application that needs to write data when running in the background
(e.g. a music app) should use this path. The same application can continue
using this path when the device is unlocked afterwards.

Returns:
Type
string

getWritablePathWhenUnlocked() → {string}

Returns the application's writable path while unlocked.

This folder is accessible to the application when the user has logged in and the
device is unlocked and being used.

Returns:
Type
string

isImageTrackingReady() → {boolean}

Returns if the image tracking system is ready to be used. Do not call any image tracking functions
until this function returns true.

Returns:

true if we can start tracking images.

Type
boolean

(static) IsMainThreadRunnablePending(callbackId) → {boolean}

Returns true if the runnable with the given ID is still pending.

Parameters:
Name Type Description
callbackId lumin.utils.CallbackID
Returns:

true if the runnable with the given ID is still in the queue.

Type
boolean

isShareableApp() → {boolean}

Returns if the app running is a Shareable app

Returns:
Type
boolean

lockCurrentLocaleHelperToLocale(localeCode)

Lock the LocaleHelper to the given locale. It will no longer change when the system locale is changed

Parameters:
Name Type Description
localeCode string

the lock that the LocaleHelper will be locked to

onAppPause()

The app should backup its data to disk and be prepared to be
killed if the system thinks it is necessary. It should also
stop drawing to the surface since it will not be rendered.

onAppResume()

The app can resume drawing to the surface and recover the
resources it stashed during onPause()

onAppStart(initArg)

Entry point for all application launch requests.

This method will be called right after init() on first application launch.
It will also be called whenever an attempt is made to launch the application
again (from launcher menu, or to open a file or URI).

Parameters:
Name Type Description
initArg lumin.InitArg

The initial application argument.

onAppUnloadResources()

The app should release resources that it is not actively using
to reduce the load on the system

onDeviceActive()

This indicates to the app that the device has transtioned to the active mode

onDeviceReality()

This indicates to the app that the device has transitioned to the reality mode

onDeviceStandby()

This indicates to the app that the device has transitioned to the standby mode

onSharingStart(sessionId, sceneGraphIDs)

Override this method to receive sharing start callback

Parameters:
Name Type Description
sessionId BigInt

Id associated with the sharing session that has just started

sceneGraphIDs Array.<BigInt>

Vector of SceneGraphIDs that are associated with an ongoing session

onSharingStop(sessionId)

Override this method to receive sharing stop callback

Parameters:
Name Type Description
sessionId BigInt

Id associated with the sharing session that has just stopped

orientPrism(a_prism, a_orientation)

Sets the Orientation of the Prism

Parameters:
Name Type Description
a_prism lumin.Prism

the prism

a_orientation quat

the new prism orientation quaternion

orientPrismRelativeToCamera(a_prism, a_orientation)

Sets the Orientation of the Prism relative to the Camera

Parameters:
Name Type Description
a_prism lumin.Prism

the prism

a_orientation quat

the new prism orientation quaternion

positionPrism(a_prism, a_position)

Sets the Prism Position

Parameters:
Name Type Description
a_prism lumin.Prism

the prism

a_position vec3

the new prism position

positionPrismRelativeToCamera(a_prism, a_position)

Sets the Prism Position relative to the camera

Parameters:
Name Type Description
a_prism lumin.Prism

the prism

a_position vec3

the new prism position, relative to the camera

postNotification(notification) → {boolean}

Post the given notification

Parameters:
Name Type Description
notification lumin.Notification

the notification to post

Returns:

true if the notification was posted successfully, false otherwise

Type
boolean

quit()

The application will terminate on the next update loop when this is called.

raycastNodes(a_prism, a_rayStart, a_rayEnd) → {lumin.RayCastResultLight}

Do a raycast in a prism and return the results.

Parameters:
Name Type Description
a_prism lumin.Prism

Prism to do the ray in.

a_rayStart vec3

Ray starting position, in volume coordinates.

a_rayEnd vec3

Ray end position, in volume coordinates.

Returns:

Hit data.

Type
lumin.RayCastResultLight

registerOnLocaleChangedCallback(callbackFunction) → {lumin.utils.CallbackID}

Register a callback for when the system locale is changed

Parameters:
Name Type Description
callbackFunction callable

the function to be called (the new locale code is given as a parameter)

Returns:

the internal ID of the callback, can be used to unregister the callback

Type
lumin.utils.CallbackID

requestPrivilege(privilegeId)

Asynchronously requests a privilege.

The result will be returned on the main thread as a PrivilegeEvent.

Parameters:
Name Type Description
privilegeId lumin.PrivilegeId

The privilege ID to request

requestPrivilegeBlocking(privilegeId) → {lumin.PrivilegeResult}

Makes a blocking request for a privilege (may require user interaction).

Parameters:
Name Type Description
privilegeId lumin.PrivilegeId

The privilege ID to check

Returns:

Granted or Denied

Type
lumin.PrivilegeResult

requestWorldPlaneCast(center, maxDistance, maxPlaneCount, flags, userValue) → {boolean}

Sends a request to the server to search for planes in the environment that match given
criteria. A WorldPlaneCastEventData instance will be sent to the app's eventListener
function when the data is ready.

Parameters:
Name Type Description
center vec3

Position in world-space that is the center of the search space.

maxDistance number

Max distance from the center to search for planes.

maxPlaneCount number

Maximum number of planes to return.

flags lumin.PlanecastFlags

Flags to determine what kind of planes to look for.

userValue BigInt

Value that will be sent back in the WorldPlaneCastEventData instance.

Returns:

true if the request was sent, false on error

Type
boolean

requestWorldRayCast(rayStart, rayDir, userValue, confidenceThresholdopt) → {boolean}

Performs a single ray cast against the world around you. Results are returned as a WorldRayCastEventData
to the app's eventListener function.

Parameters:
Name Type Attributes Default Description
rayStart vec3

The start point of the ray, in world space.

rayDir vec3

Direction to shoot the ray

userValue BigInt

Custom data that you wish to record with this request

confidenceThreshold number <optional>
0.199

Confidence level (between 0 and 1) that must be reached for the
raycast to be considered valid

Returns:

true if the request was sent, false on error

Type
boolean

requestWorldRayCast(rayStart, rayDir, width, height, horizFovDeg, userValue, confidenceThresholdopt) → {boolean}

Performs an area ray cast against the world around you. Results are returned as a WorldRayCastEventData
to the app's eventListener function.

Parameters:
Name Type Attributes Default Description
rayStart vec3

The start point of the ray, in world space.

rayDir vec3

Direction to shoot the ray

width number

Number of horizontal rays

height number

Number of vertical rays

horizFovDeg number

Horizontal field-of-view, in degrees

userValue BigInt

Custom data that you wish to record with this request

confidenceThreshold number <optional>
0.199

Confidence level (between 0 and 1) that must be reached for the
raycast to be considered valid

Returns:

true if the request was sent, false on error

Type
boolean

resizePrism(a_prism, a_size)

Resizes the Prism

Parameters:
Name Type Description
a_prism lumin.Prism

the prism to resize

a_size vec3

the new size of the prism

(static) RunOnMainThread(a_runnable, delay) → {lumin.utils.CallbackID}

Runs the given task on the main thread (with an optional delay).

Parameters:
Name Type Description
a_runnable callable

the callback to run on the main thread.

delay number

the optional time in seconds to wait before running the callback

Returns:

a unique ID that can be used to cancel the runnable.

Type
lumin.utils.CallbackID

(static) RunOnMainThread(a_runnable) → {lumin.utils.CallbackID}

Runs the given task on the main thread (with an optional delay).

Parameters:
Name Type Description
a_runnable callable

the callback to run on the main thread.

Returns:

a unique ID that can be used to cancel the runnable.

Type
lumin.utils.CallbackID

(static) RunOnMainThreadSync(a_runnable)

Similar to RunOnMainThread() but synchronous. Will
block caller until client event loop will process callback
event. Except when invoked form client eventloop thread - in
that case a_runnable will be called immediately.

Parameters:
Name Type Description
a_runnable callable

setEventSleepTime(a_fSleepTime)

Set the Event Sleep Time

This is the amount of time the client should sleep before firing
the updateloop callback, if no other events have occured.

Parameters:
Name Type Description
a_fSleepTime number

Time to sleep in seconds, or 0.0f to sleep
indefinitely, until an event occurs.

stopTrackImage(imageName) → {boolean}

Stops tracking an image. If no images are being tracked, will disable tracking.

Parameters:
Name Type Description
imageName string

Name of the image. Should be the same as the name passed to one of the the
trackImage functions.

Returns:

true if tracking the image was stopped

Type
boolean

trackMovingImage(imageName, dimensions, file, prism) → {boolean}

Starts a request to track a moving image, based on an image file. Moving images are harder to
track than non-moving ones; use this function only if sure the image is moving. This will enable
tracking if it is not already enabled.

Parameters:
Name Type Description
imageName string

Unique name for the image.

dimensions vec2

Approximate size of the image, in meters. This is used to help identify the image.

file string

File name of the image to track. Name is relative to the app's location.

prism lumin.Prism

Where to send the image position info

Returns:

true if tracking was started, false if there was an error.

Type
boolean

trackStaticImage(imageName, dimensions, file, prism) → {boolean}

Starts a request to track an non-moving image, based on an image file. Static images are easier
to track than moving ones, so use this method if possible. This will enable tracking if it is
not already enabled.

Parameters:
Name Type Description
imageName string

Unique name for the image.

dimensions vec2

Approximate size of the image, in meters. This is used to help identify the image.

file string

File name of the image to track. Name is relative to the app's location.

prism lumin.Prism

Where to send the image position info

Returns:

true if tracking was started, false if there was an error.

Type
boolean

triggerControlBodyHaptics(pattern, durationopt, intensityopt, controlIDopt, deviceIDopt)

Request vibration haptics on the body of the control device

Parameters:
Name Type Attributes Default Description
pattern lumin.haptics.VibePattern

the vibration pattern to use

duration number <optional>
100

the duration to play the pattern over (ms)

intensity lumin.haptics.VibeIntensity <optional>
haptics.VibeIntensity.MEDIUM

the intensity of the vibration

controlID number <optional>
INVALID_CONTROL_ID

the ID of the control to use (0 will be the primary control)

deviceID number <optional>
INVALID_DEVICE_ID

the internal ID of the device to use (note, this takes precedence over the control ID)

triggerControlCustomHaptic(haptic, controlIDopt, deviceIDopt)

Trigger a custom control haptic

Parameters:
Name Type Attributes Default Description
haptic lumin.HapticInfo

and individual custom haptic

controlID number <optional>
INVALID_CONTROL_ID

the ID of the control to use (0 will be the primary control)

deviceID number <optional>
INVALID_DEVICE_ID

the internal ID of the device to use (note, this takes precedence over the control ID)

triggerControlCustomHaptics(haptics, controlIDopt, deviceIDopt)

Trigger a list of custom control haptics

Parameters:
Name Type Attributes Default Description
haptics Array.<lumin.HapticInfo>

the combined list of haptics

controlID number <optional>
INVALID_CONTROL_ID

the ID of the control to use (0 will be the primary control)

deviceID number <optional>
INVALID_DEVICE_ID

the internal ID of the device to use (note, this takes precedence over the control ID)

triggerControlHaptic(haptic, controlIDopt, deviceIDopt)

Trigger a control LED haptic

Parameters:
Name Type Attributes Default Description
haptic lumin.haptics.LedPattern

the LedPattern to trigger

controlID number <optional>
INVALID_CONTROL_ID

the ID of the control to use (0 will be the primary control)

deviceID number <optional>
INVALID_DEVICE_ID

the internal ID of the device to use (note, this takes precedence over the control ID)

triggerControlHaptic(haptic, controlIDopt, deviceIDopt)

Trigger a control vibration haptic

Parameters:
Name Type Attributes Default Description
haptic lumin.haptics.VibePattern

the VibePattern to trigger

controlID number <optional>
INVALID_CONTROL_ID

the ID of the control to use (0 will be the primary control)

deviceID number <optional>
INVALID_DEVICE_ID

the internal ID of the device to use (note, this takes precedence over the control ID)

triggerControlLEDHaptics(pattern, durationopt, intensityopt, controlIDopt, deviceIDopt)

Request light haptics on the LEDs of the control device

Parameters:
Name Type Attributes Default Description
pattern lumin.haptics.LedPattern

the LED light pattern to use

duration number <optional>
100

the duration to play the pattern over (ms)

intensity lumin.haptics.VibeIntensity <optional>
haptics.VibeIntensity.MEDIUM

the intensity of the haptic

controlID number <optional>
INVALID_CONTROL_ID

the ID of the control to use (0 will be the primary control)

deviceID number <optional>
INVALID_DEVICE_ID

the internal ID of the device to use (note, this takes precedence over the control ID)

unlockCurrentLocaleHelper()

Unlock the locale of the LocaleHelper. This will set the LocaleHelper back to the current system locale

unregisterOnLocaleChangedCallback(callbackID) → {boolean}

Unregister a callback for when the system locale is changed

Parameters:
Name Type Description
callbackID lumin.utils.CallbackID

the ID of the callback to unregister

Returns:

true if succesfully unregistered, false otherwise

Type
boolean

updateLoop(a_fDelta) → {boolean}

Override this method to do things on the Event Update Thread

Parameters:
Name Type Description
a_fDelta number

Time Delta since last frame

Returns:

true = continue

Type
boolean

waitForTermination()

This call will block the caller thread until the app has finished running.
It must NOT be called from the client update thread or it will assert.