SurfaceEntity

public final class SurfaceEntity extends BaseEntity

java.lang.Object
   ↳ 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.
public interface SurfaceEntity.Shape

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.
public final class SurfaceEntity.Shape.Quad implements SurfaceEntity.Shape

A Quadrilateral-shaped canvas.
public final class SurfaceEntity.Shape.Sphere implements SurfaceEntity.Shape

cal An inwards-facing sphere-shaped mesh, centered at (0,0,0) in the local coordinate space.
public static class SurfaceEntity.StereoMode
public static class SurfaceEntity.SuperSampling

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 methods
static final @NonNull SurfaceEntity
@MainThread
create(
    @NonNull Session session,
    @NonNull Pose pose,
    @NonNull SurfaceEntity.Shape shape,
    int stereoMode,
    int superSampling,
    int surfaceProtection
)

Public factory function for a SurfaceEntity.
final @NonNull FloatSize3d

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

The EdgeFeatheringParams feathering pattern to be used along the edges of the Shape.
final @NonNull PerceivedResolutionResult

Gets the perceived resolution of the entity in the camera view.
final @NonNull SurfaceEntity.Shape

The shape of the canvas that backs the Entity.
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

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

The shape of the canvas that backs the Entity.
final void
@MainThread
setStereoMode(int stereoMode)

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

Inherited methods
From androidx.xr.scenecore.BaseEntity
void

Sets an Entity to be a child of this Entity in the scene graph.
boolean

Adds a Component to this Entity.
void

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

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

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

Retrieves all Components of the given type T and its sub-types attached to this Entity.
@NonNull CharSequence

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

The parent of this Entity, from which this Entity will inherit most of its properties.
@NonNull Pose
getPose(int relativeTo)

Returns the Pose for this Entity, relative to the provided Space.
float
getScale(int relativeTo)

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

Returns the enabled status of this Entity.
void

Remove all components from this Entity.
void

Removes the given Component from this Entity.
void
setAlpha(float alpha, int relativeTo)

Sets the alpha transparency of the Entity relative to given Space.
void

Alternate text for this Entity to be consumed by Accessibility systems.
void
setEnabled(boolean enabled)

Sets the local enabled state of this Entity.
void
setParent(Entity parent)

The parent of this Entity, from which this Entity will inherit most of its properties.
void
setPose(@NonNull Pose pose, int relativeTo)

Sets the Pose for this Entity.
void
setScale(float scale, int relativeTo)

Sets the scale of this Entity relative to the given Space.
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-alpha07
@MainThread
public static final @NonNull SurfaceEntity create(
    @NonNull Session session,
    @NonNull Pose pose,
    @NonNull SurfaceEntity.Shape shape,
    int stereoMode,
    int superSampling,
    int surfaceProtection
)

Public factory function for a SurfaceEntity.

Parameters
@NonNull Session session

Session to create the SurfaceEntity in.
@NonNull Pose pose

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

The Shape which describes the spatialized shape of the canvas.
int stereoMode

Stereo mode for the surface.
int superSampling

The SuperSampling which describes whether super sampling is enabled for the surface.
int surfaceProtection

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

a SurfaceEntity instance

getDimensions

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

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.

getEdgeFeatheringParams

Added in 1.0.0-alpha07
public final @NonNull SurfaceEntity.EdgeFeatheringParams getEdgeFeatheringParams()

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.

getPerceivedResolution

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

getShape

Added in 1.0.0-alpha07
public final @NonNull SurfaceEntity.Shape getShape()

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.

getStereoMode

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

Throws
kotlin.IllegalStateException

when setting this value if the Entity has been disposed.

getSurface

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

Throws
kotlin.IllegalStateException

if the Entity has been disposed.

setEdgeFeatheringParams

Added in 1.0.0-alpha07
@MainThread
public final void setEdgeFeatheringParams(
    @NonNull SurfaceEntity.EdgeFeatheringParams 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.

setShape

Added in 1.0.0-alpha07
@MainThread
public final void setShape(@NonNull SurfaceEntity.Shape 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.

setStereoMode

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

Throws
kotlin.IllegalStateException

when setting this value if the Entity has been disposed.