SurfaceEntity

public final class SurfaceEntity implements 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
public abstract class SurfaceEntity.CanvasShape

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 static class SurfaceEntity.StereoMode

Public methods
static final @NonNull SurfaceEntity
@MainThread
create(
    @NonNull Session session,
    int stereoMode,
    @NonNull Pose pose,
    @NonNull SurfaceEntity.CanvasShape canvasShape
)

Public factory function for a SurfaceEntity.
void

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

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

The shape of the canvas that backs the Entity.
final @NonNull FloatSize3d

Returns the dimensions of the Entity.
final @NonNull SurfaceEntity.EdgeFeatheringParams

The EdgeFeather feathering pattern to be used along the edges of the CanvasShape.
final @NonNull PerceivedResolutionResult

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

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

Controls how the surface content will be routed for stereo viewing.
final @NonNull Surface

Returns a surface into which the application can render stereo image content.
final void
@MainThread
setAuxiliaryAlphaMaskTexture(Texture auxiliaryAlphaMaskTexture)

The texture to be composited into the alpha channel of the secondary view of the surface.
final void

The shape of the canvas that backs the Entity.
final void

The EdgeFeather feathering pattern to be used along the edges of the CanvasShape.
final void

The texture to be composited into the alpha channel of the surface.
final void
@MainThread
setStereoMode(int stereoMode)

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

Inherited methods
From androidx.xr.scenecore.Entity
@FloatRange(from = 0.0, to = 1.0) float

Returns the alpha transparency set for this Entity.
@NonNull Pose

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

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

Sets the alpha transparency of the Entity and its children.
void

Sets the Pose for this Entity, relative to its parent.
void
setScale(@FloatRange(from = 0.0) float scale)

Sets the scale of this Entity relative to its parent.
From androidx.xr.scenecore.ScenePose
abstract @NonNull Pose

The current Pose relative to the activity space root.
abstract @NonNull HitTestResult
hitTest(@NonNull Vector3 origin, @NonNull Vector3 direction)

Creates a hit test from the specified origin in the specified direction into the Scene.
abstract @NonNull HitTestResult
hitTest(
    @NonNull Vector3 origin,
    @NonNull Vector3 direction,
    int hitTestFilter
)

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

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

Public methods

create

Added in 1.0.0-alpha05
@MainThread
public static final @NonNull SurfaceEntity create(
    @NonNull Session session,
    int stereoMode,
    @NonNull Pose pose,
    @NonNull SurfaceEntity.CanvasShape canvasShape
)

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
@NonNull Session session

Session to create the SurfaceEntity in.
int stereoMode

Stereo mode for the surface.
@NonNull Pose pose

Pose of this entity relative to its parent, default value is Identity.
@NonNull SurfaceEntity.CanvasShape canvasShape

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

a SurfaceEntity instance

dispose

public void dispose()

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.

getAuxiliaryAlphaMaskTexture

Added in 1.0.0-alpha05
public final Texture getAuxiliaryAlphaMaskTexture()

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.

getCanvasShape

Added in 1.0.0-alpha05
public final @NonNull SurfaceEntity.CanvasShape getCanvasShape()

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.

getDimensions

Added in 1.0.0-alpha05
public final @NonNull FloatSize3d getDimensions()

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.

getEdgeFeather

Added in 1.0.0-alpha05
public final @NonNull SurfaceEntity.EdgeFeatheringParams getEdgeFeather()

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.

getPerceivedResolution

Added in 1.0.0-alpha05
public final @NonNull PerceivedResolutionResult getPerceivedResolution()

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
@NonNull 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

getPrimaryAlphaMaskTexture

Added in 1.0.0-alpha05
public final Texture getPrimaryAlphaMaskTexture()

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.

getStereoMode

Added in 1.0.0-alpha05
public final int getStereoMode()

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.

getSurface

Added in 1.0.0-alpha05
@MainThread
public final @NonNull Surface getSurface()

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.

setAuxiliaryAlphaMaskTexture

Added in 1.0.0-alpha05
@MainThread
public final void setAuxiliaryAlphaMaskTexture(Texture auxiliaryAlphaMaskTexture)

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.

setCanvasShape

Added in 1.0.0-alpha05
@MainThread
public final void setCanvasShape(@NonNull SurfaceEntity.CanvasShape 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.

setEdgeFeather

Added in 1.0.0-alpha05
@MainThread
public final void setEdgeFeather(@NonNull SurfaceEntity.EdgeFeatheringParams edgeFeather)

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.

setPrimaryAlphaMaskTexture

Added in 1.0.0-alpha05
@MainThread
public final void setPrimaryAlphaMaskTexture(Texture primaryAlphaMaskTexture)

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.

setStereoMode

Added in 1.0.0-alpha05
@MainThread
public final void setStereoMode(int stereoMode)

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.