SurfaceEntity

class SurfaceEntity : BaseEntity

kotlin.Any
   ↳ androidx.xr.scenecore.BaseActivityPose
     ↳ androidx.xr.scenecore.BaseEntity
       ↳ androidx.xr.scenecore.SurfaceEntity

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.

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

Public factory function for a SurfaceEntity.

Public functions
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.
Dimensions

Returns the dimensions of the Entity.
Float

Controls the canvas-relative radius of the edge fadeout on the left and right edges of the SurfaceEntity canvas.
Float

Controls the canvas-relative radius of the edge fadeout on the top and bottom edges of the SurfaceEntity canvas.
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.ActivityPose
abstract Pose

Returns the activity space pose for this ActivityPose.
abstract ListenableFuture<HitTestResult>
hitTestAsync(origin: Vector3, direction: Vector3)

Creates a hit test from the specified origin in the specified direction into the scene.
abstract ListenableFuture<HitTestResult>
hitTestAsync(
    origin: Vector3,
    direction: Vector3,
    @ActivityPose.HitTestFilterValue hitTestFilter: Int
)

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

Returns a pose relative to this ActivityPose transformed into a pose relative to the destination.
From androidx.xr.scenecore.BaseEntity
open Unit
addChild(child: Entity)

Sets an Entity to be represented in this coordinate space.
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 Entity?

Returns the parent of 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
isHidden(includeParents: Boolean)

Returns the hidden 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

Sets alternate text for this entity to be consumed by Accessibility systems.
open Unit
setHidden(hidden: Boolean)

Sets the local hidden state of this Entity.
open Unit
setParent(parent: Entity?)

Sets this Entity to be represented in the parent's coordinate space.
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 given space.
From androidx.xr.scenecore.Entity
open Float

Returns the alpha transparency set for this Entity.
open Pose

Returns the pose for this entity, relative to its parent.
open Float

Returns the local scale of this entity, not inclusive of the parent's scale.
open Unit
setAlpha(alpha: 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: Float)

Sets the scale of this entity relative to its parent.

Public companion functions

create

Added in 1.0.0-alpha04
@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

getSurface

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

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

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

Public properties

auxiliaryAlphaMaskTexture

Added in 1.0.0-alpha04
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.

canvasShape

Added in 1.0.0-alpha04
var canvasShape: SurfaceEntity.CanvasShape

The shape of the canvas that backs the Entity.

Updating this value will alter the dimensions of the Entity.

dimensions

Added in 1.0.0-alpha04
val dimensions: Dimensions

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.

featherRadiusX

Added in 1.0.0-alpha04
var featherRadiusX: Float

Controls the canvas-relative radius of the edge fadeout on the left and right edges of the SurfaceEntity canvas. A radius of 0.05 represents 5% of the width of the visible canvas surface. Please note that this is scaled by the aspect ratio of Quad-shaped canvases.

Applications are encouraged to set this to 0.0 on 360 canvases. The behavior is only defined between 0.0f - 0.5f. Default value is 0.0f.

Setter must be called from the main thread.

featherRadiusY

Added in 1.0.0-alpha04
var featherRadiusY: Float

Controls the canvas-relative radius of the edge fadeout on the top and bottom edges of the SurfaceEntity canvas. A radius of 0.05 represents 5% of the height of the visible canvas surface. Please note that this is scaled by the aspect ratio of Quad-shaped canvases.

Applications are encouraged to set this to 0.0 on 360 canvases. The behavior is only defined between 0.0f - 0.5f. Default value is 0.0f.

Setter must be called from the main thread.

primaryAlphaMaskTexture

Added in 1.0.0-alpha04
var primaryAlphaMaskTexture: Texture?

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

stereoMode

Added in 1.0.0-alpha04
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.