SurfaceEntity

public final class SurfaceEntity extends BaseEntity

java.lang.Object
   ↳ 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
public abstract class SurfaceEntity.CanvasShape

Represents the shape of the Canvas that backs a SurfaceEntity.
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.
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 Dimensions

Returns the dimensions of the Entity.
final float

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

Controls the canvas-relative radius of the edge fadeout on the top and bottom edges of the SurfaceEntity canvas.
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
@MainThread
setFeatherRadiusX(float featherRadiusX)

Controls the canvas-relative radius of the edge fadeout on the left and right edges of the SurfaceEntity canvas.
final void
@MainThread
setFeatherRadiusY(float featherRadiusY)

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

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

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

Creates a hit test from the specified origin in the specified direction into the scene.
abstract @NonNull Pose

Returns a pose relative to this ActivityPose transformed into a pose relative to the destination.
From androidx.xr.scenecore.BaseEntity
void

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

Returns the parent of this Entity.
@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
isHidden(boolean includeParents)

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

Sets alternate text for this entity to be consumed by Accessibility systems.
void
setHidden(boolean hidden)

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

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

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

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

Returns the local scale of this entity, not inclusive of the parent's scale.
void
setAlpha(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(float scale)

Sets the scale of this entity relative to its parent.

Public methods

create

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

getAuxiliaryAlphaMaskTexture

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

getCanvasShape

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

getDimensions

Added in 1.0.0-alpha04
public final @NonNull Dimensions 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.

getFeatherRadiusX

Added in 1.0.0-alpha04
public final float getFeatherRadiusX()

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.

getFeatherRadiusY

Added in 1.0.0-alpha04
public final float getFeatherRadiusY()

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.

getPrimaryAlphaMaskTexture

Added in 1.0.0-alpha04
public final Texture getPrimaryAlphaMaskTexture()

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

getStereoMode

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

getSurface

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

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

setAuxiliaryAlphaMaskTexture

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

setCanvasShape

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

setFeatherRadiusX

Added in 1.0.0-alpha04
@MainThread
public final void setFeatherRadiusX(float featherRadiusX)

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.

setFeatherRadiusY

Added in 1.0.0-alpha04
@MainThread
public final void setFeatherRadiusY(float featherRadiusY)

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.

setPrimaryAlphaMaskTexture

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

setStereoMode

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