GltfModelEntity

class GltfModelEntity : BaseEntity

kotlin.Any
   ↳ androidx.xr.scenecore.BaseScenePose
     ↳ androidx.xr.scenecore.BaseEntity
       ↳ androidx.xr.scenecore.GltfModelEntity

GltfModelEntity is a concrete implementation of Entity that hosts a glTF model.

Note: The size property of this Entity is always reported as {0, 0, 0}, regardless of the actual size of the model.

Summary

Nested types

Specifies the current animation state of the GltfModelEntity.

Public companion functions
GltfModelEntity
@MainThread
create(session: Session, model: GltfModel, pose: Pose)

Public factory function for a GltfModelEntity.

Public functions
Unit
@MainThread
clearMaterialOverride(nodeName: String, primitiveIndex: Int)

Clears a previously set material override for a specific primitive of a node within the glTF graph.
Unit
@MainThread
setMaterialOverride(
    material: Material,
    nodeName: String,
    primitiveIndex: Int
)

Sets a material override for a primitive of a node within the glTF graph.
Unit

Starts animating the glTF with the first animation found in the model.
Unit
@MainThread
startAnimation(loop: Boolean, animationName: String)

Starts the animation with the given name.
Unit

Stops the currently active animation.

Public properties
Int

The current animation state of the GltfModelEntity.

Inherited functions
From androidx.xr.scenecore.BaseEntity
open Unit
addChild(child: Entity)

Sets an Entity to be a child of this Entity in the scene graph.
open Boolean
addComponent(component: Component)

Adds a Component to this Entity.
open Unit

Disposes of any system resources held by this Entity, and transitively calls dispose() on all its children.
open Float
getAlpha(relativeTo: Int)

Returns the alpha transparency set for this Entity, relative to given Space.
open List<Component>

Retrieves all components attached to this Entity.
open List<T>

Retrieves all Components of the given type T and its sub-types attached to this Entity.
open Pose
getPose(relativeTo: Int)

Returns the Pose for this Entity, relative to the provided Space.
open Float
getScale(relativeTo: Int)

Returns the scale of this entity, relative to given space.
open Boolean
isEnabled(includeParents: Boolean)

Returns the enabled status of this Entity.
open Unit

Remove all components from this Entity.
open Unit

Removes the given Component from this Entity.
open Unit
setAlpha(alpha: Float, relativeTo: Int)

Sets the alpha transparency of the Entity relative to given Space.
open Unit
setEnabled(enabled: Boolean)

Sets the local enabled state of this Entity.
open Unit
setPose(pose: Pose, relativeTo: Int)

Sets the Pose for this Entity.
open Unit
setScale(scale: Float, relativeTo: Int)

Sets the scale of this Entity relative to the given Space.
From androidx.xr.scenecore.Entity
open @FloatRange(from = 0.0, to = 1.0) Float

Returns the alpha transparency set for this Entity.
open Pose

Returns the Pose for this Entity, relative to its parent.
open @FloatRange(from = 0.0) Float

Returns the local scale of this Entity, not inclusive of the parent's scale.
open Unit
setAlpha(alpha: @FloatRange(from = 0.0, to = 1.0) Float)

Sets the alpha transparency of the Entity and its children.
open Unit
setPose(pose: Pose)

Sets the Pose for this Entity, relative to its parent.
open Unit
setScale(scale: @FloatRange(from = 0.0) Float)

Sets the scale of this Entity relative to its parent.
From androidx.xr.scenecore.ScenePose
abstract suspend HitTestResult
hitTest(origin: Vector3, direction: Vector3)

Creates a hit test from the specified origin in the specified direction into the Scene.
abstract suspend HitTestResult
hitTest(origin: Vector3, direction: Vector3, hitTestFilter: Int)

Creates a hit test from the specified origin in the specified direction into the scene.
abstract Pose
transformPoseTo(pose: Pose, destination: ScenePose)

Returns a Pose relative to this ScenePose, transformed into a Pose relative to the destination.

Inherited properties
From androidx.xr.scenecore.BaseEntity
open CharSequence

Alternate text for this Entity to be consumed by Accessibility systems.
open Entity?

The parent of this Entity, from which this Entity will inherit most of its properties.
From androidx.xr.scenecore.ScenePose
abstract Pose

The current Pose relative to the activity space root.

Public companion functions

create

Added in 1.0.0-alpha08
@MainThread
fun create(session: Session, model: GltfModel, pose: Pose = Pose.Identity): GltfModelEntity

Public factory function for a GltfModelEntity.

This method must be called from the main thread. https://developer.android.com/guide/components/processes-and-threads

Parameters
session: Session

Session to create the GltfModel in.
model: GltfModel

The GltfModel this Entity is referencing.
pose: Pose = Pose.Identity

The initial Pose of the Entity.

Public functions

clearMaterialOverride

Added in 1.0.0-alpha08
@MainThread
fun clearMaterialOverride(nodeName: String, primitiveIndex: Int = 0): Unit

Clears a previously set material override for a specific primitive of a node within the glTF graph.

If no override was previously set for that primitive, this call has no effect.

Parameters
nodeName: String

The name of the node containing the primitive whose material override will be cleared.
primitiveIndex: Int = 0

The zero-based index for the primitive of the specified node, as defined in the glTF graph. Default is the first primitive of that node.
Throws
kotlin.IllegalArgumentException

if the provided material is invalid or if no node with the given nodeName is found in the model.
kotlin.IndexOutOfBoundsException

if the primitiveIndex is out of bounds.

setMaterialOverride

Added in 1.0.0-alpha08
@MainThread
fun setMaterialOverride(
    material: Material,
    nodeName: String,
    primitiveIndex: Int = 0
): Unit

Sets a material override for a primitive of a node within the glTF graph.

This function searches for the first node in the glTF scene graph with a matching nodeName. The override is then applied to a primitive of that node at the specified primitiveIndex.

Parameters
material: Material

The new Material to apply to the primitive.
nodeName: String

The name of the node as defined in the glTF graph, containing the primitive to override.
primitiveIndex: Int = 0

The zero-based index for the primitive of the specified node, as defined in the glTF graph. Default is the first primitive of that node.
Throws
kotlin.IllegalArgumentException

if the provided material is invalid or if no node with the given nodeName is found in the model.
kotlin.IndexOutOfBoundsException

if the primitiveIndex is out of bounds.

startAnimation

Added in 1.0.0-alpha08
@MainThread
fun startAnimation(loop: Boolean = true): Unit

Starts animating the glTF with the first animation found in the model.

This method must be called from the main thread. https://developer.android.com/guide/components/processes-and-threads

Parameters
loop: Boolean = true

Whether the animation should loop over or stop after animating once. Defaults to true.
Throws
kotlin.IllegalArgumentException

if the underlying model doesn't contain any animations.

startAnimation

Added in 1.0.0-alpha08
@MainThread
fun startAnimation(loop: Boolean, animationName: String): Unit

Starts the animation with the given name. Only one animation can be playing at a time.

This method must be called from the main thread. https://developer.android.com/guide/components/processes-and-threads

Parameters
loop: Boolean

If true, the animation plays in a loop indefinitely until stopAnimation is called. If false, the animation plays once and then stops.
animationName: String

The name of the animation to start.
Throws
kotlin.IllegalArgumentException

if the underlying model doesn't contain an animation with the given name.

stopAnimation

Added in 1.0.0-alpha08
@MainThread
fun stopAnimation(): Unit

Stops the currently active animation.

This method must be called from the main thread. https://developer.android.com/guide/components/processes-and-threads

Public properties

animationState

Added in 1.0.0-alpha08
val animationState: Int

The current animation state of the GltfModelEntity.

Returns
Int

The current animation state.