SurfaceEntity

class SurfaceEntity : ScenePose, Entity

SurfaceEntity is a concrete implementation of Entity that hosts a StereoSurface Canvas. The entity creates and owns an Android Surface into which the application can render stereo image content. This Surface is then texture mapped to the canvas, and if a stereoscopic StereoMode is specified, then the User will see left and right eye content mapped to the appropriate display.

Note that it is not currently possible to synchronize CanvasShape and StereoMode changes with application rendering or video decoding. Applications are advised to carefully hide this entity around transitions to manage glitchiness.

Summary

Nested types

Represents the shape of the Canvas that backs a SurfaceEntity.

Represents edge fading effects for a SurfaceEntity.

Applies no edge fading to any canvas.

Public companion functions
SurfaceEntity
@MainThread
create(
    session: Session,
    stereoMode: Int,
    pose: Pose,
    canvasShape: SurfaceEntity.CanvasShape
)

Public factory function for a SurfaceEntity.

Public functions
open Unit

Disposes of any system resources held by this Entity, and transitively calls dispose() on all its children.
PerceivedResolutionResult

Gets the perceived resolution of the entity in the camera view.
Surface

Returns a surface into which the application can render stereo image content.

Public properties
Texture?

The texture to be composited into the alpha channel of the secondary view of the surface.
SurfaceEntity.CanvasShape

The shape of the canvas that backs the Entity.
FloatSize3d

Returns the dimensions of the Entity.
SurfaceEntity.EdgeFeatheringParams

The EdgeFeather feathering pattern to be used along the edges of the CanvasShape.
Texture?

The texture to be composited into the alpha channel of the surface.
Int

Controls how the surface content will be routed for stereo viewing.

Inherited functions
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.ScenePose
abstract Pose

The current Pose relative to the activity space root.

Public companion functions

create

Added in 1.0.0-alpha05
@MainThread
fun create(
    session: Session,
    stereoMode: Int = SurfaceEntity.StereoMode.SIDE_BY_SIDE,
    pose: Pose = Pose.Identity,
    canvasShape: SurfaceEntity.CanvasShape = CanvasShape.Quad(1.0f, 1.0f)
): SurfaceEntity

Public factory function for a SurfaceEntity.

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 SurfaceEntity in.
stereoMode: Int = SurfaceEntity.StereoMode.SIDE_BY_SIDE

Stereo mode for the surface.
pose: Pose = Pose.Identity

Pose of this entity relative to its parent, default value is Identity.
canvasShape: SurfaceEntity.CanvasShape = CanvasShape.Quad(1.0f, 1.0f)

The CanvasShape which describes the spatialized shape of the canvas.
Returns
SurfaceEntity

a SurfaceEntity instance

Public functions

dispose

open fun dispose(): Unit

Disposes of any system resources held by this Entity, and transitively calls dispose() on all its children. Once disposed, this Entity is invalid and cannot be used again.

getPerceivedResolution

Added in 1.0.0-alpha05
fun getPerceivedResolution(): PerceivedResolutionResult

Gets the perceived resolution of the entity in the camera view.

This API is only intended for use in Full Space Mode and will return PerceivedResolutionResult.InvalidCameraView in Home Space Mode.

The entity's own rotation and the camera's viewing direction are disregarded; this value represents the dimensions of the entity on the camera view if its largest surface was facing the camera without changing the distance of the entity to the camera.

Returns
PerceivedResolutionResult

A PerceivedResolutionResult which encapsulates the outcome: - PerceivedResolutionResult.Success containing the PixelDimensions if the calculation is successful. - PerceivedResolutionResult.EntityTooClose if the entity is too close to the camera. - PerceivedResolutionResult.InvalidCameraView if the camera information required for the calculation is invalid or unavailable.
Throws
kotlin.IllegalStateException

if Session.config.headTracking is set to Config.HeadTrackingMode.DISABLED.
See also
PerceivedResolutionResult

getSurface

Added in 1.0.0-alpha05
@MainThread
fun getSurface(): Surface

Returns a surface into which the application can render stereo image content. Note that android.graphics.Canvas Apis are not currently supported on this Canvas.

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

Throws
kotlin.IllegalStateException

if the Entity has been disposed.

Public properties

auxiliaryAlphaMaskTexture

Added in 1.0.0-alpha05
var auxiliaryAlphaMaskTexture: Texture?

The texture to be composited into the alpha channel of the secondary view of the surface. This is only used for interleaved stereo content. If null, the alpha mask will be disabled.

Throws
kotlin.IllegalStateException

when setting this value if the Entity has been disposed.

canvasShape

Added in 1.0.0-alpha05
var canvasShape: SurfaceEntity.CanvasShape

The shape of the canvas that backs the Entity. Updating this value will alter the dimensions of the Entity.

Throws
kotlin.IllegalArgumentException

if an invalid canvas shape is provided.
kotlin.IllegalStateException

when setting this value if the Entity has been disposed.

dimensions

Added in 1.0.0-alpha05
val dimensions: FloatSize3d

Returns the dimensions of the Entity.

This is the size of the canvas in the local spatial coordinate system of the entity. This field cannot be directly set - to update the dimensions of the canvas, update the value of canvasShape.

edgeFeather

Added in 1.0.0-alpha05
var edgeFeather: SurfaceEntity.EdgeFeatheringParams

The EdgeFeather feathering pattern to be used along the edges of the CanvasShape. This value must only be set from the main thread.

Throws
kotlin.IllegalStateException

when setting this value if the Entity has been disposed.

primaryAlphaMaskTexture

Added in 1.0.0-alpha05
var primaryAlphaMaskTexture: Texture?

The texture to be composited into the alpha channel of the surface. If null, the alpha mask will be disabled.

Throws
kotlin.IllegalStateException

when setting this value if the Entity has been disposed.

stereoMode

Added in 1.0.0-alpha05
var stereoMode: Int

Controls how the surface content will be routed for stereo viewing. Applications must render into the surface in accordance with what is specified here in order for the compositor to correctly produce a stereoscopic view to the user.

Values must be one of the values from StereoMode.

Throws
kotlin.IllegalStateException

when setting this value if the Entity has been disposed.