SurfaceEntity

class SurfaceEntity : BaseEntity

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

SurfaceEntity is an Entity that hosts a Surface, which will be texture mapped onto the Shape. 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 Shape and StereoMode changes with application rendering or video decoding. Applications are advised to carefully hide this entity around state transitions (for example in response to video events) to manage glitchiness.

Summary

Nested types

Represents edge fading effects for a SurfaceEntity.

Applies no edge fading to any canvas.

Represents the shape of the Canvas that backs a SurfaceEntity.

An inwards-facing hemisphere-shaped canvas, where (0,0,0) is the center of the base of the hemisphere.

A Quadrilateral-shaped canvas.

cal An inwards-facing sphere-shaped mesh, centered at (0,0,0) in the local coordinate space.

Specifies whether super sampling should be enabled for this surface.

Specifies whether the Surface which backs this Entity should be backed by android.hardware.HardwareBuffers with the USAGE_PROTECTED_CONTENT flag set.

Public companion functions
SurfaceEntity
@MainThread
create(
    session: Session,
    pose: Pose,
    shape: SurfaceEntity.Shape,
    stereoMode: Int,
    superSampling: Int,
    surfaceProtection: Int
)

Public factory function for a SurfaceEntity.

Public functions
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
FloatSize3d

Returns the size of the canvas in the local spatial coordinate system of the entity.
SurfaceEntity.EdgeFeatheringParams

The EdgeFeatheringParams feathering pattern to be used along the edges of the Shape.
SurfaceEntity.Shape

The shape of the canvas that backs the Entity.
Int

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

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-alpha07
@MainThread
fun create(
    session: Session,
    pose: Pose = Pose.Identity,
    shape: SurfaceEntity.Shape = Shape.Quad(FloatSize2d(1.0f, 1.0f)),
    stereoMode: Int = StereoMode.STEREO_MODE_MONO,
    superSampling: Int = SuperSampling.SUPER_SAMPLING_PENTAGON,
    surfaceProtection: Int = SurfaceProtection.SURFACE_PROTECTION_NONE
): SurfaceEntity

Public factory function for a SurfaceEntity.

Parameters
session: Session

Session to create the SurfaceEntity in.
pose: Pose = Pose.Identity

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

The Shape which describes the spatialized shape of the canvas.
stereoMode: Int = StereoMode.STEREO_MODE_MONO

Stereo mode for the surface.
superSampling: Int = SuperSampling.SUPER_SAMPLING_PENTAGON

The SuperSampling which describes whether super sampling is enabled for the surface.
surfaceProtection: Int = SurfaceProtection.SURFACE_PROTECTION_NONE

The SurfaceProtection which describes whether the hosted surface should support Widevine DRM.
Returns
SurfaceEntity

a SurfaceEntity instance

Public functions

getPerceivedResolution

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

Throws
kotlin.IllegalStateException

if the Entity has been disposed.

Public properties

dimensions

Added in 1.0.0-alpha07
val dimensions: FloatSize3d

Returns the size of the canvas in the local spatial coordinate system of the entity.

This value is entirely determined by the value of shape.

edgeFeatheringParams

Added in 1.0.0-alpha07
var edgeFeatheringParams: SurfaceEntity.EdgeFeatheringParams

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

Throws
kotlin.IllegalStateException

when setting this value if the Entity has been disposed.

shape

Added in 1.0.0-alpha07
var shape: SurfaceEntity.Shape

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.

stereoMode

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

Throws
kotlin.IllegalStateException

when setting this value if the Entity has been disposed.