Prism

lumin. Prism

Represents the bounded volume within which the Scenegraph renders. Prisms are created via
the App::requestNewPrism function.

Methods

createAll(objectModelName) → {lumin.Node}

Create all objects from a loaded object model and
return them as children of newly created root Node.

Parameters:
Name Type Description
objectModelName string

The name of the object model.

Returns:

Root node containing all objects from model or nullptr if creation failed

Type
lumin.Node

createAnimationBlendSetupResourceId(a_fileName, a_absolutePathopt, a_descriptoropt, a_basePathopt) → {BigInt}

Creates animation blend setup resource

Parameters:
Name Type Attributes Default Description
a_fileName string

File name of the resource to load. By default assumed to be a relative path
from the executable file.

a_absolutePath boolean <optional>
false

Flag that a_fileName is an absolute path name, instead of a relative path.

a_descriptor number <optional>
-1

optional file descriptor that points to a resource.
If passed to the resource the resource takes ownership of the File Descriptor.

a_basePath string <optional>
null

If you are loading a resource from an absolute path, and that path !=
The current process path, set this field to the equivalent base path in the other
client directory. This allows path relative dependencies to solve a fully
qualified (absolute) path outside of the current process. This value defaults to
the currently executing process root.

NOTE: In case a Standard resource is already created. And a new resource is created with the same filename but instanced,
it will not overwrite the standard resource. In that case, you will have to delete that resource, and post that, create
a new instanced resource.
This is not required if you want to use an instanced resource as a standard resource.

Returns:

ID for the Resource

Type
BigInt

createAnimationResourceId(a_fileName, a_absolutePathopt, a_descriptoropt, a_basePathopt) → {BigInt}

Creates animation resource

Parameters:
Name Type Attributes Default Description
a_fileName string

File name of the resource to load. By default assumed to be a relative path
from the executable file.

a_absolutePath boolean <optional>
false

Flag that a_fileName is an absolute path name, instead of a relative path.

a_descriptor number <optional>
-1

optional file descriptor that points to a resource.
If passed to the resource the resource takes ownership of the File Descriptor.

a_basePath string <optional>
null

If you are loading a resource from an absolute path, and that path !=
The current process path, set this field to the equivalent base path in the other
client directory. This allows path relative dependencies to solve a fully
qualified (absolute) path outside of the current process. This value defaults to
the currently executing process root.

NOTE: In case a Standard resource is already created. And a new resource is created with the same filename but instanced,
it will not overwrite the standard resource. In that case, you will have to delete that resource, and post that, create
a new instanced resource.
This is not required if you want to use an instanced resource as a standard resource.

Returns:

ID for the Resource

Type
BigInt

createAnimationSetResourceId(a_fileName, a_absolutePathopt, a_descriptoropt, a_basePathopt) → {BigInt}

Creates animation set resource

Parameters:
Name Type Attributes Default Description
a_fileName string

File name of the resource to load. By default assumed to be a relative path
from the executable file.

a_absolutePath boolean <optional>
false

Flag that a_fileName is an absolute path name, instead of a relative path.

a_descriptor number <optional>
-1

optional file descriptor that points to a resource.
If passed to the resource the resource takes ownership of the File Descriptor.

a_basePath string <optional>
null

If you are loading a resource from an absolute path, and that path !=
The current process path, set this field to the equivalent base path in the other
client directory. This allows path relative dependencies to solve a fully
qualified (absolute) path outside of the current process. This value defaults to
the currently executing process root.

NOTE: In case a Standard resource is already created. And a new resource is created with the same filename but instanced,
it will not overwrite the standard resource. In that case, you will have to delete that resource, and post that, create
a new instanced resource.
This is not required if you want to use an instanced resource as a standard resource.

Returns:

ID for the Resource

Type
BigInt

createAudioNode() → {lumin.AudioNode}

Create a new AudioNode.
After calling this createAudioNode(), must call one of the AudioNode::createSoundXxxxX() methods
to create a specific type of audio node.

Returns:

New AudioNode on success; nullptr on failure.

Type
lumin.AudioNode

createDefaultText2dNode(desc, styleopt) → {lumin.Text2dNode}

Create a 2D text node using the Magic Leap UI font (regular weight).

Parameters:
Name Type Attributes Default Description
desc lumin.Text2dDesc

Information about the Text2dNode to create.

style lumin.resources.FontStyle <optional>
resources.FontStyle.kNormal

Either normal or italic style are supported.

Returns:

The new Text2dNode.

Type
lumin.Text2dNode

createFont2dResourceId(fontDesc, fontFile, a_absolutePathopt) → {BigInt}

Create a Font2dResource with the given description.

Parameters:
Name Type Attributes Default Description
fontDesc lumin.glyph.Font2dDesc

Initialization parameters for the resource. For
reasonable default values, use the DEFAULT static member.

fontFile string

The font file from which to load the glyphs. By default assumed to be a relative
path from the executable file.

a_absolutePath boolean <optional>
false

Flag that fontFile is an absolute path name, instead of a relative path.

Returns:

The new Font2dResource.

Type
BigInt

createImage3d(format, width, height, depth) → {lumin.AssetPacker.Image3d}

Create a Image-3D data.

Parameters:
Name Type Description
format lumin.utils.Format

The format of the pixel data.

width number

The width of the texture.

height number

The height of the texture.

depth number

The depth of the texture.

Returns:

Return a valid Image-3D that should be used to create Texture-3D Resource.

Type
lumin.AssetPacker.Image3d

createInstancedModelResourceId(a_fileName, a_maxInstances, a_absolutePathopt, a_descriptoropt, a_basePathopt) → {BigInt}

Creates instanced model resource

Parameters:
Name Type Attributes Default Description
a_fileName string

File name of the resource to load. By default assumed to be a relative path
from the executable file.

a_maxInstances number

MaximumInstances the resource can have

a_absolutePath boolean <optional>
false

Flag that a_fileName is an absolute path name, instead of a relative path.

a_descriptor number <optional>
-1

optional file descriptor that points to a resource.
If passed to the resource the resource takes ownership of the File Descriptor.

a_basePath string <optional>
null

If you are loading a resource from an absolute path, and that path !=
The current process path, set this field to the equivalent base path in the other
client directory. This allows path relative dependencies to solve a fully
qualified (absolute) path outside of the current process. This value defaults to
the currently executing process root.

NOTE: In case a Standard resource is already created. And a new resource is created with the same filename but instanced,
it will not overwrite the standard resource. In that case, you will have to delete that resource, and post that, create
a new instanced resource.
This is not required if you want to use an instanced resource as a standard resource.

Returns:

ID for the Resource

Type
BigInt

createLightNode() → {lumin.LightNode}

Creates directional light node

Returns:

The new LightNode

Type
lumin.LightNode

createLineNode() → {lumin.LineNode}

Create a new LineNode.

Returns:

New LineNode on success; nullptr on failure.

Type
lumin.LineNode

createLoadedFileAudioResourceId(a_fileName, a_absolutePathopt, a_descriptoropt, a_basePathopt) → {BigInt}

Creates audio resource by loading the entire audio file in the memory.
Use this method for audio files which are not too big to hog memory.
For big files you may use the createStreamedFileAudioResource method.

Parameters:
Name Type Attributes Default Description
a_fileName string

File name of the resource to load. By default assumed to be a relative path
from the executable file.

a_absolutePath boolean <optional>
false

Flag that a_fileName is an absolute path name, instead of a relative path.

a_descriptor number <optional>
-1

optional file descriptor that points to a resource.
If passed to the resource the resource takes ownership of the File Descriptor.

a_basePath string <optional>
null

If you are loading a resource from an absolute path, and that path !=
The current process path, set this field to the equivalent base path in the other
client directory. This allows path relative dependencies to solve a fully
qualified (absolute) path outside of the current process. This value defaults to
the currently executing process root.

Returns:

Resource ID

Type
BigInt

createMaterialResourceId(a_fileName, a_localScopeOnlyopt, a_absolutePathopt) → {BigInt}

Creates a MaterialResource

Parameters:
Name Type Attributes Default Description
a_fileName string

File name of the resource to load. By default assumed to be a relative path
from the executable file.

a_localScopeOnly boolean <optional>
false

The scope of this material. When set to true the kmat's contained in the material
will not be added to the prism's list of materials for general resolve.

a_absolutePath boolean <optional>
false

Flag that a_fileName is an absolute path name, instead of a relative path.

Returns:

resource instance

Type
BigInt

createModelAttachmentNode(modelNode, boneName) → {lumin.ModelAttachmentNode}

Create a new ModelAttachmentNode.

Parameters:
Name Type Description
modelNode lumin.ModelNode

the ModelNode to which the bone is attached

boneName string

the name of the bone

Returns:

New ModelAttachmentNode on success; nullptr on failure.

Type
lumin.ModelAttachmentNode

createModelNode(resourceId) → {lumin.ModelNode}

Create a new ModelNode.

Parameters:
Name Type Description
resourceId BigInt

optional resource Id to use for the node.

Returns:

New ModelNode on success; nullptr on failure.

Type
lumin.ModelNode

createModelResourceId(a_fileName, a_importScale, a_absolutePathopt, a_descriptoropt, a_basePathopt) → {BigInt}

Creates a ModelResource

Parameters:
Name Type Attributes Default Description
a_fileName string

File name of the resource to load. By default assumed to be a relative path
from the executable file.

a_importScale number

The scale that will be applied to this resource

a_absolutePath boolean <optional>
false

Flag that a_fileName is an absolute path name, instead of a relative path.

a_descriptor number <optional>
-1

optional file descriptor that points to a resource.
If passed to the resource the resource takes ownership of the File Descriptor.

a_basePath string <optional>
null

If you are loading a resource from an absolute path, and that path !=
The current process path, set this field to the equivalent base path in the other
client directory. This allows path relative dependencies to solve a fully
qualified (absolute) path outside of the current process. This value defaults to
the currently executing process root.

Returns:

ID for the Resource

Type
BigInt

createNode(objectModelName, objectNameopt) → {lumin.Node}

Create a node from a loaded object model.

Parameters:
Name Type Attributes Default Description
objectModelName string

The name of the object model.

objectName string <optional>
""

The name of an object in the object model. If empty, the first object in the object model is used.

Returns:

Newly created node or nullptr if creation failed.

Type
lumin.Node

createNode() → {lumin.Node}

Creates a node of the base type, suitable for organizing a group of child nodes.

Returns:
Type
lumin.Node

createObjMtlResourceId(a_fileName, a_absolutePathopt) → {BigInt}

Creates mtl resource

Parameters:
Name Type Attributes Default Description
a_fileName string

File name of the resource to load. By default assumed to be a relative path
from the executable file.

a_absolutePath boolean <optional>
false

Flag that a_fileName is an absolute path name, instead of a relative path.

Returns:

ID for the Resource

Type
BigInt

createParticleNode(packageResource) → {lumin.ParticleNode}

Create a new ParticleNode.

Parameters:
Name Type Description
packageResource BigInt

resource Id of the particle effect package to use.

Returns:

New ParticleNode on success; nullptr on failure.

Type
lumin.ParticleNode

createParticlePackageResourceId(a_fileName, a_absolutePathopt) → {BigInt}

Creates particle package resource

Parameters:
Name Type Attributes Default Description
a_fileName string

File name of the resource to load. By default assumed to be a relative path
from the executable file.

a_absolutePath boolean <optional>
false

Flag that a_fileName is an absolute path name, instead of a relative path.

Returns:

ID for the Resource

Type
BigInt

createPlanarEGLResourceId(a_widthopt, a_heightopt) → {BigInt}

Creates a PlanarResource of given size which provides access to EGL Context and EGL Surface.

Parameters:
Name Type Attributes Default Description
a_width number <optional>
512

The Width 1 to 2048

a_height number <optional>
512

The Height 1 to 2048

Returns:

The new PlanarResource

Type
BigInt

createQuad3dNode(resourceId) → {lumin.Quad3dNode}

Create a new Quad3dNode with a Texture3dResource id.

It works only with Texture3dResource. The call would return nullptr,
for any other resource types.

Parameters:
Name Type Description
resourceId BigInt

resource Id to use for the node.

Returns:

New Quad3dNode on success; nullptr on failure.

Type
lumin.Quad3dNode

createQuadNode(resourceId) → {lumin.QuadNode}

Create a new QuadNode.

Parameters:
Name Type Description
resourceId BigInt

optional resource Id to use for the node.

Returns:

New QuadNode on success; nullptr on failure.

Type
lumin.QuadNode

createSpriteNode(resourceId) → {lumin.SpriteNode}

Create a new SpriteNode from a texture pack resource.

Parameters:
Name Type Description
resourceId BigInt

id of the resource that contains the frames for the sprite.

Returns:

New SpriteNode on success; nullptr on failure.

Type
lumin.SpriteNode

createStreamedFileAudioResourceId(a_fileName, a_absolutePathopt, a_descriptoropt, a_basePathopt) → {BigInt}

Create audio resource with streamed file.
Use this resource for big audio files where the audio file is loaded only chunk at a time in then memory.
Normally audio resource will be fully loaded in memory, in which case use createLoadedFileAudioResource() method.

Uses same params as createLoadedFileAudioResource method.

Parameters:
Name Type Attributes Default Description
a_fileName string
a_absolutePath boolean <optional>
false
a_descriptor number <optional>
-1
a_basePath string <optional>
null
Returns:

Resource ID

Type
BigInt

createText2dNode(fontResourceId, desc) → {lumin.Text2dNode}

Create a 2D text node with the given font and properties
encapsulated in the description object.

Parameters:
Name Type Description
fontResourceId BigInt

Id of a FontResource to use.

desc lumin.Text2dDesc

Information about the Text2dNode to create.

Returns:

The new Text2dNode.

Type
lumin.Text2dNode

createTexture3dResourceId(image, descopt) → {BigInt}

Create a Texture-3D resource with the decoded image data.

Parameters:
Name Type Attributes Default Description
image lumin.AssetPacker.Image3d

Decoded Image data to be used for rendering.

desc lumin.Desc3d <optional>
Desc3d.DEFAULT

Optional Initialization parameters for the resource to control rendering.

Returns:

The new Texture-3D resource id.

Type
BigInt

createTexturePackResourceId(directory, params, absolutePathopt) → {BigInt}

Create and initialize a TexturePackResource.

Parameters:
Name Type Attributes Default Description
directory string

file-system directory where the data to initialize the resource is located.

params lumin.multipack.Params

control how the textures are rendered; see PackedTextureParams::DEFAULT.

absolutePath boolean <optional>
false

flag that the location is an absolute path instead of a relative path.

Returns:

The new TexturePackResource.

Type
BigInt

createTexturePackResourceId(desc, absolutePathopt) → {BigInt}

Create and initialize a TexturePackResource.

Parameters:
Name Type Attributes Default Description
desc lumin.multipack.Descriptor

user-created descriptor object, which includes the location of the data.

absolutePath boolean <optional>
false

flag that the location is an absolute path instead of a relative path.

Returns:

The new TexturePackResource.

Type
BigInt

createTexturePackResourceId(a_vMetaDataNames, a_params, absolutePathopt) → {BigInt}

Create and initialize a TexturePackResource.

Parameters:
Name Type Attributes Default Description
a_vMetaDataNames Array.<string>

a list of json files that define the TexturePack.

a_params lumin.multipack.Params

control how the textures are rendered;

absolutePath boolean <optional>
false

flag that the location is an absolute path instead of a relative path.

Returns:

The new TexturePackResource.

Type
BigInt

createTextureResourceId(tex2dDesc, imageFile, a_absolutePathopt, a_fileDescriptoropt) → {BigInt}

Create a TextureResource with the given description from the PNG image file.

Parameters:
Name Type Attributes Default Description
tex2dDesc lumin.Desc2d

Initialization parameters for the resource. For reasonable default values,
use the DEFAULT static member.

imageFile string

PNG or JPEG-encoded image file. By default assumed to be a relative path
from the executable file.

a_absolutePath boolean <optional>
false

Flag that pngFile is an absolute path name, instead of a relative path.

a_fileDescriptor number <optional>
-1

optional file descriptor that points to a png resource.
If passed to the resource the resource takes ownership of the File Descriptor.

Returns:

The new TextureResource.

Type
BigInt

createTransformNode(localTransform) → {lumin.TransformNode}

Create a new TransformNode.

Parameters:
Name Type Description
localTransform mat4

The local transform of the new node;
use glm::mat4() for the identity matrix.

Returns:

New TransformNode on success; nullptr on failure.

Type
lumin.TransformNode

createTree(objectModelName, objectNameopt) → {lumin.Node}

Create a node tree from a loaded object model.

Parameters:
Name Type Attributes Default Description
objectModelName string

The name of the object model.

objectName string <optional>
""

The name of an object in the object model. A node tree will be created using this node and its descendants. If empty, the first object in the object model is used.

Returns:

Root node of a newly created node tree or nullptr if creation failed.

Type
lumin.Node

createVideoNode(a_widthopt, a_heightopt) → {lumin.VideoNode}

Creates a VideoNode with the given resolution and display mode.

Parameters:
Name Type Attributes Default Description
a_width number <optional>
512

The surface resolution width 1 to 2048

a_height number <optional>
512

The surface resolution height 1 to 2048

Returns:

The new VideoNode

Type
lumin.VideoNode

createVolumeCubeNode(resourceId) → {lumin.VolumeCubeNode}

Creates a VolumeCubeNode with a Texture3dResource id.

It works only with Texture3dResource. The call would return nullptr,
for any other resource types.

Parameters:
Name Type Description
resourceId BigInt

resource Id to use for the node.

Returns:

The new VolumeCubeNode on success; nullptr on failure.

Type
lumin.VolumeCubeNode

deleteNode(a_pNode)

Tells the Prism to delete this Node and all its children

Parameters:
Name Type Description
a_pNode lumin.Node

The Node that will be deleted

destroyResource(a_iID)

Destroys a Resource with a given ResourceIDType.
Paired with createResource(). For each create() there should be a destroy().

Parameters:
Name Type Description
a_iID BigInt

ID of the resource

enableVisualState(value)

Enable//Disable the Prism Visual state changes

Parameters:
Name Type Description
value boolean

Enable/Disable the state changing

findNode(a_name, a_parent) → {lumin.Node}

Find a Node by name.

Parameters:
Name Type Description
a_name string

The Node name to look for

a_parent lumin.Node

The node which to look for a decendant node of.

Returns:
Type
lumin.Node

getHandGestureHoverDistance() → {number}

Returns:

the distance threshold the hand gesture cursor must be at for a node
register as hovered

Type
number

getHandGestureTouchDistance() → {number}

Returns:

the distance threshold the hand gesture cursor must be at for a node
register as touched

Type
number

getNode(a_id) → {lumin.Node}

Get a Node by its Id

Parameters:
Name Type Description
a_id BigInt

The Node id to look for

Returns:

the Node

Type
lumin.Node

getPosition() → {vec3}

Get the position of this prism in world space

Returns:

Prism position

Type
vec3

getPrismId() → {BigInt}

Get the Prism ID

Returns:

Prism ID

Type
BigInt

getPrismType() → {lumin.PrismType}

Returns the Prism type.

Returns:

The Prism type.

Type
lumin.PrismType

getResource(name) → {BigInt}

Acquire loaded resource mapped to the given name in the declarative system.

Parameters:
Name Type Description
name string

The name of the resource.

Returns:

ID of named resource or INVALID_RESOURCE_ID if no resource is loaded with that name.

Type
BigInt

getResource(a_iID) → {lumin.Resource}

Get the resource with the given ID. Should only be called on the render
thread for resources related to rendering.

Parameters:
Name Type Description
a_iID BigInt

the unique ID of the resource to find.

Returns:

pointer to the resource or else nullptr if not found.

Type
lumin.Resource

getRootNode() → {lumin.RootNode}

Get the root node of the scene graph. The node version will be the last seen version.

Returns:

the root node

Type
lumin.RootNode

getRotation() → {quat}

Get the rotation of this prism in world space

Returns:

Prism rotation

Type
quat

getScale() → {vec3}

Get the scale of this prism

Returns:

Prism scale

Type
vec3

getSize() → {vec3}

Get the Bounding size

Returns:

Size (width,height,depth)

Type
vec3

getSound(name) → {lumin.Sound}

Acquire loaded sound mapped to the given name in the declarative system.

Parameters:
Name Type Description
name string

The name of the sound.

Returns:

Pointer to named sound or nullptr if no sound is loaded with that name.

Type
lumin.Sound

getTransform() → {mat4}

Get the Real World Transform of this prism

Returns:

Prism transform matrix

Type
mat4

getUserAutoHapticGesture() → {number}

Gives the current set of Auto Haptic Gestures for this prism
required by User

Returns:
  • Active DeviceGestureFlags
Type
number

getUserHandGesture() → {number}

Gives the current set of Hand Gesture for this prism
required by User

Returns:
  • Active HandGesture Flags
Type
number

isPrismSelected() → {boolean}

Get whether this Prism is selected.

Returns:

the selected state of the prism.

Type
boolean

loadObjectModel(filePath) → {string}

Load an object model into memory.

Parameters:
Name Type Description
filePath string

Path to object model file.

Returns:

If successful this string will be populated with the object model's name.

Type
string

loadResourceModel(filePath) → {boolean}

Load a resource model into memory, and create its defined resources.

Parameters:
Name Type Description
filePath string

Path to resource model file.

Returns:

True if the resource model was successfully loaded.

Type
boolean

loadSoundModel(filePath) → {boolean}

Load a sound model into memory, and create its defined sounds.

Parameters:
Name Type Description
filePath string

Path to sound model file.

Returns:

True if the sound model was successfully loaded.

Type
boolean

objectModelLoaded(name) → {boolean}

Determine whether or not an object model is loaded.

Parameters:
Name Type Description
name string

The name of the object model.

Returns:

True if a object model with the given name is loaded.

Type
boolean

onDestroyEventSub(callback) → {lumin.utils.CallbackID}

Returns an Event that will be triggered right before this prism is destroyed.

This event will be dispatched after PrismController::onDetachPrism is called
(if there is a PrismController attached to the prism).

Parameters:
Name Type Description
callback callable
Returns:
Type
lumin.utils.CallbackID

onDestroyEventUnsub(callbackID) → {boolean}

Parameters:
Name Type Description
callbackID lumin.utils.CallbackID
Returns:
Type
boolean

parseObjectModel(modelString) → {string}

Load an object model from a string into memory.

Parameters:
Name Type Description
modelString string

Object model data as a string.

Returns:

If successful this string will be populated with the object model's name.

Type
string

retainEyeTrackingUpdates() → {lumin.PrismDataHandle}

Retain this shared pointer to force the prism to receive eye tracking updates.

NOTE: Must be called on client main thread.

Returns:
Type
lumin.PrismDataHandle

retainFloorUpdates() → {lumin.PrismDataHandle}

Retain this shared pointer to force the volume to receive floor updates.

NOTE: Must be called on client main thread.

Returns:
Type
lumin.PrismDataHandle

retainFPSMode() → {lumin.KEmpty}

Retain this shared pointer to force the prism to enter fps mode

Returns:
Type
lumin.KEmpty

retainHeadposeUpdates() → {lumin.PrismDataHandle}

Retain this shared pointer to force the prism to receive headpose updates.

NOTE: Must be called on client main thread.

Returns:
Type
lumin.PrismDataHandle

setExcludeFromAutoFocus(exclude)

If true, this prism will be excluded from the server's auto focus calculation

Parameters:
Name Type Description
exclude boolean

se