# SurfaceEntity

Artifact: [androidx.xr.scenecore:scenecore](https://developer.android.com/jetpack/androidx/releases/xr-scenecore) [View Source](https://cs.android.com/search?q=file:androidx/xr/scenecore/SurfaceEntity.kt+class:androidx.xr.scenecore.SurfaceEntity) Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/xr-scenecore#1.0.0)

*** ** * ** ***


```
public final class SurfaceEntity extends Entity
```

<br />

|---|---|---|---|
| [java.lang.Object](https://developer.android.com/reference/java/lang/Object.html) ||||
| ↳ | [androidx.xr.scenecore.BaseScenePose](https://developer.android.com/reference/androidx/xr/scenecore/BaseScenePose) |||
|   | ↳ | [androidx.xr.scenecore.Entity](https://developer.android.com/reference/androidx/xr/scenecore/Entity) ||
|   |   | ↳ | [androidx.xr.scenecore.SurfaceEntity](https://developer.android.com/reference/androidx/xr/scenecore/SurfaceEntity) |

*** ** * ** ***

SurfaceEntity is an `https://developer.android.com/reference/androidx/xr/scenecore/Entity` that hosts a `https://developer.android.com/reference/android/view/Surface.html`, which will be texture mapped onto the `https://developer.android.com/reference/androidx/xr/scenecore/SurfaceEntity.Shape`. If a stereoscopic `https://developer.android.com/reference/androidx/xr/scenecore/SurfaceEntity.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 `https://developer.android.com/reference/androidx/xr/scenecore/SurfaceEntity.Shape` and `https://developer.android.com/reference/androidx/xr/scenecore/SurfaceEntity.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 |
|---|
| `public abstract class https://developer.android.com/reference/androidx/xr/scenecore/SurfaceEntity.EdgeFeatheringParams` Represents edge fading effects for a SurfaceEntity. |
| `public final class https://developer.android.com/reference/androidx/xr/scenecore/SurfaceEntity.EdgeFeatheringParams.NoFeathering extends https://developer.android.com/reference/androidx/xr/scenecore/SurfaceEntity.EdgeFeatheringParams` Applies no edge fading to any canvas. |
| `public final class https://developer.android.com/reference/androidx/xr/scenecore/SurfaceEntity.EdgeFeatheringParams.RectangleFeather extends https://developer.android.com/reference/androidx/xr/scenecore/SurfaceEntity.EdgeFeatheringParams` |
| `public interface https://developer.android.com/reference/androidx/xr/scenecore/SurfaceEntity.Shape` Represents the shape of the Canvas that backs a SurfaceEntity. |
| `public final class https://developer.android.com/reference/androidx/xr/scenecore/SurfaceEntity.Shape.Hemisphere implements https://developer.android.com/reference/androidx/xr/scenecore/SurfaceEntity.Shape` An inwards-facing hemisphere-shaped canvas, where (0,0,0) is the center of the base of the hemisphere. |
| `public final class https://developer.android.com/reference/androidx/xr/scenecore/SurfaceEntity.Shape.Quad implements https://developer.android.com/reference/androidx/xr/scenecore/SurfaceEntity.Shape` A Quadrilateral-shaped canvas. |
| `public final class https://developer.android.com/reference/androidx/xr/scenecore/SurfaceEntity.Shape.Sphere implements https://developer.android.com/reference/androidx/xr/scenecore/SurfaceEntity.Shape` cal An inwards-facing sphere-shaped mesh, centered at (0,0,0) in the local coordinate space. |
| `public final class https://developer.android.com/reference/androidx/xr/scenecore/SurfaceEntity.StereoMode` Specifies how the surface content will be routed for stereo viewing. |
| `public final class https://developer.android.com/reference/androidx/xr/scenecore/SurfaceEntity.SuperSampling` Specifies whether super sampling should be enabled for this surface. |
| `public final class https://developer.android.com/reference/androidx/xr/scenecore/SurfaceEntity.SurfaceProtection` Specifies whether the `https://developer.android.com/reference/android/view/Surface.html` which backs this `https://developer.android.com/reference/androidx/xr/scenecore/Entity` should be backed by `https://developer.android.com/reference/android/hardware/HardwareBuffer.html`s with the USAGE_PROTECTED_CONTENT flag set. |

| ### Public methods |
|---|---|
| `static final @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/xr/scenecore/SurfaceEntity` | `@https://developer.android.com/reference/androidx/annotation/MainThread https://developer.android.com/reference/androidx/xr/scenecore/SurfaceEntity#create(androidx.xr.runtime.Session,androidx.xr.runtime.math.Pose,androidx.xr.scenecore.SurfaceEntity.Shape,androidx.xr.scenecore.SurfaceEntity.StereoMode,androidx.xr.scenecore.SurfaceEntity.SuperSampling,androidx.xr.scenecore.SurfaceEntity.SurfaceProtection,androidx.xr.scenecore.Entity)( @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/xr/runtime/Session session, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/xr/runtime/math/Pose pose, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/xr/scenecore/SurfaceEntity.Shape shape, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/xr/scenecore/SurfaceEntity.StereoMode stereoMode, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/xr/scenecore/SurfaceEntity.SuperSampling superSampling, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/xr/scenecore/SurfaceEntity.SurfaceProtection surfaceProtection, https://developer.android.com/reference/androidx/xr/scenecore/Entity parent )` Public factory function for a SurfaceEntity. |
| `final @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/xr/runtime/math/FloatSize3d` | `https://developer.android.com/reference/androidx/xr/scenecore/SurfaceEntity#getDimensions()()` Returns the size of the canvas in the local spatial coordinate system of the entity. |
| `final @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/xr/scenecore/SurfaceEntity.EdgeFeatheringParams` | `https://developer.android.com/reference/androidx/xr/scenecore/SurfaceEntity#getEdgeFeatheringParams()()` The `https://developer.android.com/reference/androidx/xr/scenecore/SurfaceEntity.EdgeFeatheringParams` feathering pattern to be used along the edges of the Shape. |
| `final @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/xr/scenecore/PerceivedResolutionResult` | `https://developer.android.com/reference/androidx/xr/scenecore/SurfaceEntity#getPerceivedResolution(androidx.xr.arcore.RenderViewpoint)(@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/xr/arcore/RenderViewpoint renderViewpoint)` Gets the perceived resolution of the entity in the provided `https://developer.android.com/reference/androidx/xr/arcore/RenderViewpoint`. |
| `final @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/xr/scenecore/SurfaceEntity.Shape` | `https://developer.android.com/reference/androidx/xr/scenecore/SurfaceEntity#getShape()()` The shape of the canvas that backs the Entity. |
| `final @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/xr/scenecore/SurfaceEntity.StereoMode` | `https://developer.android.com/reference/androidx/xr/scenecore/SurfaceEntity#getStereoMode()()` Controls how the surface content will be routed for stereo viewing. |
| `final @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/android/view/Surface.html` | `@https://developer.android.com/reference/androidx/annotation/MainThread https://developer.android.com/reference/androidx/xr/scenecore/SurfaceEntity#getSurface()()` Returns a surface into which the application can render stereo image content. |
| `final void` | `@https://developer.android.com/reference/androidx/annotation/MainThread https://developer.android.com/reference/androidx/xr/scenecore/SurfaceEntity#setEdgeFeatheringParams(androidx.xr.scenecore.SurfaceEntity.EdgeFeatheringParams)( @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/xr/scenecore/SurfaceEntity.EdgeFeatheringParams value )` The `https://developer.android.com/reference/androidx/xr/scenecore/SurfaceEntity.EdgeFeatheringParams` feathering pattern to be used along the edges of the Shape. |
| `final void` | `@https://developer.android.com/reference/androidx/annotation/MainThread https://developer.android.com/reference/androidx/xr/scenecore/SurfaceEntity#setShape(androidx.xr.scenecore.SurfaceEntity.Shape)(@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/xr/scenecore/SurfaceEntity.Shape value)` The shape of the canvas that backs the Entity. |
| `final void` | `@https://developer.android.com/reference/androidx/annotation/MainThread https://developer.android.com/reference/androidx/xr/scenecore/SurfaceEntity#setStereoMode(androidx.xr.scenecore.SurfaceEntity.StereoMode)(@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/xr/scenecore/SurfaceEntity.StereoMode value)` Controls how the surface content will be routed for stereo viewing. |
| `final void` | `@https://developer.android.com/reference/androidx/annotation/MainThread @https://developer.android.com/reference/androidx/xr/scenecore/ExperimentalSurfaceEntityPixelDimensionsApi https://developer.android.com/reference/androidx/xr/scenecore/SurfaceEntity#setSurfacePixelDimensions(androidx.xr.runtime.math.IntSize2d)(@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/xr/runtime/math/IntSize2d dimensions)` Sets the width and height of the `https://developer.android.com/reference/android/view/Surface.html` which backs this `https://developer.android.com/reference/androidx/xr/scenecore/SurfaceEntity` in pixels. |

### Inherited methods

From [androidx.xr.scenecore.BaseScenePose](https://developer.android.com/reference/androidx/xr/scenecore/BaseScenePose) `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/xr/runtime/math/Pose` `https://developer.android.com/reference/androidx/xr/scenecore/BaseScenePose#getPoseInActivitySpace()()`

The current `https://developer.android.com/reference/androidx/xr/runtime/math/Pose` relative to the activity space root.
`https://developer.android.com/reference/androidx/xr/scenecore/HitTestResult` `https://developer.android.com/reference/androidx/xr/scenecore/BaseScenePose#hitTest(androidx.xr.runtime.math.Vector3,androidx.xr.runtime.math.Vector3)(@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/xr/runtime/math/Vector3 origin, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/xr/runtime/math/Vector3 direction)`

Perform a hit test from the specified origin in the specified direction into the Scene.
`https://developer.android.com/reference/androidx/xr/scenecore/HitTestResult` `https://developer.android.com/reference/androidx/xr/scenecore/BaseScenePose#hitTest(androidx.xr.runtime.math.Vector3,androidx.xr.runtime.math.Vector3,kotlin.Int)(
@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/xr/runtime/math/Vector3 origin,
@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/xr/runtime/math/Vector3 direction,
int hitTestFilter
)`

Creates a hit test from the specified origin in the specified direction into the scene.
`@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/xr/runtime/math/Vector3` `https://developer.android.com/reference/androidx/xr/scenecore/BaseScenePose#transformDirectionTo(androidx.xr.runtime.math.Vector3,androidx.xr.scenecore.ScenePose)(
@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/xr/runtime/math/Vector3 direction,
@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/xr/scenecore/ScenePose destination
)`

Transforms a direction from this ScenePose's local space to the destination ScenePose's local space.
`@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/xr/runtime/math/Pose` `https://developer.android.com/reference/androidx/xr/scenecore/BaseScenePose#transformPoseTo(androidx.xr.runtime.math.Pose,androidx.xr.scenecore.ScenePose)(@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/xr/runtime/math/Pose pose, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/xr/scenecore/ScenePose destination)`

Returns a `https://developer.android.com/reference/androidx/xr/runtime/math/Pose` relative to this ScenePose, transformed into a Pose relative to the destination.
`@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/xr/runtime/math/Vector3` `https://developer.android.com/reference/androidx/xr/scenecore/BaseScenePose#transformPositionTo(androidx.xr.runtime.math.Vector3,androidx.xr.scenecore.ScenePose)(
@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/xr/runtime/math/Vector3 position,
@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/xr/scenecore/ScenePose destination
)`

Transforms a position from this ScenePose's local space to the destination ScenePose's local space.
`@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/xr/runtime/math/Vector3` `https://developer.android.com/reference/androidx/xr/scenecore/BaseScenePose#transformVectorTo(androidx.xr.runtime.math.Vector3,androidx.xr.scenecore.ScenePose)(@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/xr/runtime/math/Vector3 vector, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/xr/scenecore/ScenePose destination)`

Transforms a vector from this ScenePose's local space to the destination ScenePose's local space.
From [androidx.xr.scenecore.Entity](https://developer.android.com/reference/androidx/xr/scenecore/Entity) `final void` `https://developer.android.com/reference/androidx/xr/scenecore/Entity#addChild(androidx.xr.scenecore.Entity)(@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/xr/scenecore/Entity child)`

Sets an Entity to be a child of this Entity in the scene graph.
`final boolean` `https://developer.android.com/reference/androidx/xr/scenecore/Entity#addComponent(androidx.xr.scenecore.Component)(@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/xr/scenecore/Component component)`

Adds a Component to this Entity.
`final @https://developer.android.com/reference/androidx/annotation/FloatRange(from = 0.0, to = 1.0) float` `https://developer.android.com/reference/androidx/xr/scenecore/Entity#getAlpha(androidx.xr.scenecore.Space)(@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/xr/scenecore/Space relativeTo)`

Returns the alpha transparency set for this Entity, relative to given Space.
`final @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/util/List.html<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/xr/scenecore/Entity>` `https://developer.android.com/reference/androidx/xr/scenecore/Entity#getChildren()()`

Provides the list of all children of this entity.
`final @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/util/List.html<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/xr/scenecore/Component>` `https://developer.android.com/reference/androidx/xr/scenecore/Entity#getComponents()()`

Retrieves all components attached to this Entity.
`final @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/util/List.html<@https://developer.android.com/reference/androidx/annotation/NonNull T>` `<T extends https://developer.android.com/reference/androidx/xr/scenecore/Component> https://developer.android.com/reference/androidx/xr/scenecore/Entity#getComponentsOfType(java.lang.Class)(@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/Class.html<@https://developer.android.com/reference/androidx/annotation/NonNull T> type)`

Retrieves all Components of the given type `https://developer.android.com/reference/androidx/xr/scenecore/Entity#getComponentsOfType(java.lang.Class)` and its subtypes attached to this Entity.
`final @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/CharSequence.html` `https://developer.android.com/reference/androidx/xr/scenecore/Entity#getContentDescription()()`

Alternate text for this Entity to be consumed by Accessibility systems.
`https://developer.android.com/reference/androidx/xr/scenecore/Entity` `https://developer.android.com/reference/androidx/xr/scenecore/Entity#getParent()()`

The parent of this Entity, from which this Entity will inherit most of its properties.
`@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/xr/runtime/math/Pose` `https://developer.android.com/reference/androidx/xr/scenecore/Entity#getPose(androidx.xr.scenecore.Space)(@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/xr/scenecore/Space relativeTo)`

Returns the `https://developer.android.com/reference/androidx/xr/runtime/math/Pose` for this Entity, relative to the provided `https://developer.android.com/reference/androidx/xr/scenecore/Space`.
`@https://developer.android.com/reference/androidx/annotation/FloatRange(from = 0.0) float` `https://developer.android.com/reference/androidx/xr/scenecore/Entity#getScale(androidx.xr.scenecore.Space)(@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/xr/scenecore/Space relativeTo)`

Returns the scale of this entity, relative to given space.
`final boolean` `https://developer.android.com/reference/androidx/xr/scenecore/Entity#isEnabled(kotlin.Boolean)(boolean includeParents)`

Returns the enabled status of this Entity.
`final void` `https://developer.android.com/reference/androidx/xr/scenecore/Entity#removeAllComponents()()`

Remove all components from this Entity.
`final void` `https://developer.android.com/reference/androidx/xr/scenecore/Entity#removeComponent(androidx.xr.scenecore.Component)(@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/xr/scenecore/Component component)`

Removes the given Component from this Entity.
`final void` `https://developer.android.com/reference/androidx/xr/scenecore/Entity#setAlpha(kotlin.Float)(@https://developer.android.com/reference/androidx/annotation/FloatRange(from = 0.0, to = 1.0) float alpha)`

Sets the alpha transparency of the Entity relative to the parent Space.
`final void` `https://developer.android.com/reference/androidx/xr/scenecore/Entity#setContentDescription(kotlin.CharSequence)(@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/CharSequence.html value)`

Alternate text for this Entity to be consumed by Accessibility systems.
`final void` `https://developer.android.com/reference/androidx/xr/scenecore/Entity#setEnabled(kotlin.Boolean)(boolean enabled)`

Sets the local enabled state of this Entity.
`void` `https://developer.android.com/reference/androidx/xr/scenecore/Entity#setParent(androidx.xr.scenecore.Entity)(https://developer.android.com/reference/androidx/xr/scenecore/Entity value)`

The parent of this Entity, from which this Entity will inherit most of its properties.
`void` `https://developer.android.com/reference/androidx/xr/scenecore/Entity#setPose(androidx.xr.runtime.math.Pose,androidx.xr.scenecore.Space)(@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/xr/runtime/math/Pose pose, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/xr/scenecore/Space relativeTo)`

Sets the `https://developer.android.com/reference/androidx/xr/runtime/math/Pose` for this Entity.
`void` `https://developer.android.com/reference/androidx/xr/scenecore/Entity#setScale(kotlin.Float,androidx.xr.scenecore.Space)(@https://developer.android.com/reference/androidx/annotation/FloatRange(from = 0.0) float scale, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/xr/scenecore/Space relativeTo)`

Sets the scale of this Entity relative to the given Space.

## Public methods

### create

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/xr-scenecore#1.0.0)

```
@MainThread
public static final @NonNull SurfaceEntity create(
    @NonNull Session session,
    @NonNull Pose pose,
    @NonNull SurfaceEntity.Shape shape,
    @NonNull SurfaceEntity.StereoMode stereoMode,
    @NonNull SurfaceEntity.SuperSampling superSampling,
    @NonNull SurfaceEntity.SurfaceProtection surfaceProtection,
    Entity parent
)
```

Public factory function for a SurfaceEntity.

| Parameters |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/xr/runtime/Session session` | Session to create the SurfaceEntity in. |
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/xr/runtime/math/Pose pose` | Pose of this entity relative to its parent, default value is Identity. |
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/xr/scenecore/SurfaceEntity.Shape shape` | The `https://developer.android.com/reference/androidx/xr/scenecore/SurfaceEntity.Shape` which describes the spatialized shape of the canvas. |
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/xr/scenecore/SurfaceEntity.StereoMode stereoMode` | Stereo mode for the surface. |
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/xr/scenecore/SurfaceEntity.SuperSampling superSampling` | The `https://developer.android.com/reference/androidx/xr/scenecore/SurfaceEntity.SuperSampling` which describes whether super sampling is enabled for the surface. |
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/xr/scenecore/SurfaceEntity.SurfaceProtection surfaceProtection` | The `https://developer.android.com/reference/androidx/xr/scenecore/SurfaceEntity.SurfaceProtection` which describes whether the hosted surface should support Widevine DRM. |
| `https://developer.android.com/reference/androidx/xr/scenecore/Entity parent` | Parent entity. Defaults to `null`. If `null`, the entity is created but not attached to the scene graph, meaning it will be invisible. If a parent entity (e.g., `https://developer.android.com/reference/androidx/xr/scenecore/ActivitySpace` or any other `https://developer.android.com/reference/androidx/xr/scenecore/Entity` already present in the scene) is assigned later, the entity will become visible (provided it is enabled). This allows for `https://developer.android.com/reference/androidx/xr/scenecore/Entity` pre-configuration before making it visible. |

| Returns |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/xr/scenecore/SurfaceEntity` | a SurfaceEntity instance |

### getDimensions

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/xr-scenecore#1.0.0)

```
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 `https://developer.android.com/reference/androidx/xr/scenecore/SurfaceEntity#shape()`.

### getEdgeFeatheringParams

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/xr-scenecore#1.0.0)

```
public final @NonNull SurfaceEntity.EdgeFeatheringParams getEdgeFeatheringParams()
```

The `https://developer.android.com/reference/androidx/xr/scenecore/SurfaceEntity.EdgeFeatheringParams` feathering pattern to be used along the edges of the Shape. This value must only be set from the main thread.

| Throws |
|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-illegal-state-exception/index.html` | when setting this value if the Entity has been disposed. |

### getPerceivedResolution

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/xr-scenecore#1.0.0)

```
public final @NonNull PerceivedResolutionResult getPerceivedResolution(@NonNull RenderViewpoint renderViewpoint)
```

Gets the perceived resolution of the entity in the provided `https://developer.android.com/reference/androidx/xr/arcore/RenderViewpoint`.

This API is only intended for use in Full Space and will return `https://developer.android.com/reference/androidx/xr/scenecore/PerceivedResolutionResult.InvalidRenderViewpoint` in Home Space.

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.

| Parameters |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/xr/arcore/RenderViewpoint renderViewpoint` | that provides the pose and field-of-view of the camera. |

| Returns |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/xr/scenecore/PerceivedResolutionResult` | A `https://developer.android.com/reference/androidx/xr/scenecore/PerceivedResolutionResult` which encapsulates the outcome: - `https://developer.android.com/reference/androidx/xr/scenecore/PerceivedResolutionResult.Success` containing the if the calculation is successful. - `https://developer.android.com/reference/androidx/xr/scenecore/PerceivedResolutionResult.EntityTooClose` if the entity is too close to the camera. - `https://developer.android.com/reference/androidx/xr/scenecore/PerceivedResolutionResult.InvalidRenderViewpoint` if the camera information required for the calculation is invalid or unavailable. |

| Throws |
|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-illegal-state-exception/index.html` | if `https://developer.android.com/reference/androidx/xr/runtime/Session#config()` is not set to `https://developer.android.com/reference/androidx/xr/runtime/DeviceTrackingMode#SPATIAL()`. |

| See also |
|---|---|
| `https://developer.android.com/reference/androidx/xr/scenecore/PerceivedResolutionResult` |   |

### getShape

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/xr-scenecore#1.0.0)

```
public final @NonNull SurfaceEntity.Shape getShape()
```

The shape of the canvas that backs the Entity. Updating this value will alter the `https://developer.android.com/reference/androidx/xr/scenecore/SurfaceEntity#dimensions()` of the Entity.

| Throws |
|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-illegal-argument-exception/index.html` | if an invalid canvas shape is provided. |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-illegal-state-exception/index.html` | when setting this value if the Entity has been disposed. |

### getStereoMode

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/xr-scenecore#1.0.0)

```
public final @NonNull SurfaceEntity.StereoMode 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 |
|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-illegal-state-exception/index.html` | when setting this value if the Entity has been disposed. |

### getSurface

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/xr-scenecore#1.0.0)

```
@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 |
|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-illegal-state-exception/index.html` | if the Entity has been disposed. |

### setEdgeFeatheringParams

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/xr-scenecore#1.0.0)

```
@MainThread
public final void setEdgeFeatheringParams(
    @NonNull SurfaceEntity.EdgeFeatheringParams value
)
```

The `https://developer.android.com/reference/androidx/xr/scenecore/SurfaceEntity.EdgeFeatheringParams` feathering pattern to be used along the edges of the Shape. This value must only be set from the main thread.

| Throws |
|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-illegal-state-exception/index.html` | when setting this value if the Entity has been disposed. |

### setShape

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/xr-scenecore#1.0.0)

```
@MainThread
public final void setShape(@NonNull SurfaceEntity.Shape value)
```

The shape of the canvas that backs the Entity. Updating this value will alter the `https://developer.android.com/reference/androidx/xr/scenecore/SurfaceEntity#dimensions()` of the Entity.

| Throws |
|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-illegal-argument-exception/index.html` | if an invalid canvas shape is provided. |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-illegal-state-exception/index.html` | when setting this value if the Entity has been disposed. |

### setStereoMode

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/xr-scenecore#1.0.0)

```
@MainThread
public final void setStereoMode(@NonNull SurfaceEntity.StereoMode value)
```

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 |
|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-illegal-state-exception/index.html` | when setting this value if the Entity has been disposed. |

### setSurfacePixelDimensions

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/xr-scenecore#1.0.0)

```
@MainThread
@ExperimentalSurfaceEntityPixelDimensionsApi
public final void setSurfacePixelDimensions(@NonNull IntSize2d dimensions)
```

Sets the width and height of the `https://developer.android.com/reference/android/view/Surface.html` which backs this `https://developer.android.com/reference/androidx/xr/scenecore/SurfaceEntity` in pixels.

Before this method is called, the width and height of the underlying Surface are not guaranteed.

This is needed if the application wishes to use `https://developer.android.com/reference/android/graphics/Canvas.html` APIs to render `https://developer.android.com/reference/android/graphics/Bitmap.html` into the Surface. It is not needed if the application is using MediaPlayer or ExoPlayer to decode media into the `https://developer.android.com/reference/android/view/Surface.html`, as those systems automatically manage the dimensions of the `https://developer.android.com/reference/android/view/Surface.html`.

Note that this method does not change the spatial dimensions of the `https://developer.android.com/reference/androidx/xr/scenecore/SurfaceEntity`, it only updates the resolution of the `https://developer.android.com/reference/android/view/Surface.html`. Unlike `https://developer.android.com/reference/androidx/xr/scenecore/PanelEntity`, changing this value will update the pixel density of the displayed Surface. Changing this will not change the scale.

| Throws |
|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-illegal-argument-exception/index.html` | if the dimensions are not greater than 0. |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-illegal-state-exception/index.html` | if the Entity has been disposed, or if `https://developer.android.com/reference/androidx/xr/scenecore/SurfaceEntity.SurfaceProtection#PROTECTED()` was set at creation. |