# 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)

*** ** * ** ***


```
class SurfaceEntity : Entity
```

<br />

|---|---|---|---|
| [kotlin.Any](https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-any/index.html) ||||
| ↳ | [androidx.xr.scenecore.BaseScenePose](https://developer.android.com/reference/kotlin/androidx/xr/scenecore/BaseScenePose) |||
|   | ↳ | [androidx.xr.scenecore.Entity](https://developer.android.com/reference/kotlin/androidx/xr/scenecore/Entity) ||
|   |   | ↳ | [androidx.xr.scenecore.SurfaceEntity](https://developer.android.com/reference/kotlin/androidx/xr/scenecore/SurfaceEntity) |

*** ** * ** ***

SurfaceEntity is an `https://developer.android.com/reference/kotlin/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/kotlin/androidx/xr/scenecore/SurfaceEntity.Shape`. If a stereoscopic `https://developer.android.com/reference/kotlin/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/kotlin/androidx/xr/scenecore/SurfaceEntity.Shape` and `https://developer.android.com/reference/kotlin/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 |
|---|
| `abstract class https://developer.android.com/reference/kotlin/androidx/xr/scenecore/SurfaceEntity.EdgeFeatheringParams` Represents edge fading effects for a SurfaceEntity. |
| `class https://developer.android.com/reference/kotlin/androidx/xr/scenecore/SurfaceEntity.EdgeFeatheringParams.NoFeathering : https://developer.android.com/reference/kotlin/androidx/xr/scenecore/SurfaceEntity.EdgeFeatheringParams` Applies no edge fading to any canvas. |
| `class https://developer.android.com/reference/kotlin/androidx/xr/scenecore/SurfaceEntity.EdgeFeatheringParams.RectangleFeather : https://developer.android.com/reference/kotlin/androidx/xr/scenecore/SurfaceEntity.EdgeFeatheringParams` |
| `interface https://developer.android.com/reference/kotlin/androidx/xr/scenecore/SurfaceEntity.Shape` Represents the shape of the Canvas that backs a SurfaceEntity. |
| `class https://developer.android.com/reference/kotlin/androidx/xr/scenecore/SurfaceEntity.Shape.Hemisphere : https://developer.android.com/reference/kotlin/androidx/xr/scenecore/SurfaceEntity.Shape` An inwards-facing hemisphere-shaped canvas, where (0,0,0) is the center of the base of the hemisphere. |
| `class https://developer.android.com/reference/kotlin/androidx/xr/scenecore/SurfaceEntity.Shape.Quad : https://developer.android.com/reference/kotlin/androidx/xr/scenecore/SurfaceEntity.Shape` A Quadrilateral-shaped canvas. |
| `class https://developer.android.com/reference/kotlin/androidx/xr/scenecore/SurfaceEntity.Shape.Sphere : https://developer.android.com/reference/kotlin/androidx/xr/scenecore/SurfaceEntity.Shape` cal An inwards-facing sphere-shaped mesh, centered at (0,0,0) in the local coordinate space. |
| `class https://developer.android.com/reference/kotlin/androidx/xr/scenecore/SurfaceEntity.StereoMode` Specifies how the surface content will be routed for stereo viewing. |
| `class https://developer.android.com/reference/kotlin/androidx/xr/scenecore/SurfaceEntity.SuperSampling` Specifies whether super sampling should be enabled for this surface. |
| `class https://developer.android.com/reference/kotlin/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/kotlin/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 companion functions |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/xr/scenecore/SurfaceEntity` | `@https://developer.android.com/reference/kotlin/androidx/annotation/MainThread https://developer.android.com/reference/kotlin/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)( session: https://developer.android.com/reference/kotlin/androidx/xr/runtime/Session, pose: https://developer.android.com/reference/kotlin/androidx/xr/runtime/math/Pose, shape: https://developer.android.com/reference/kotlin/androidx/xr/scenecore/SurfaceEntity.Shape, stereoMode: https://developer.android.com/reference/kotlin/androidx/xr/scenecore/SurfaceEntity.StereoMode, superSampling: https://developer.android.com/reference/kotlin/androidx/xr/scenecore/SurfaceEntity.SuperSampling, surfaceProtection: https://developer.android.com/reference/kotlin/androidx/xr/scenecore/SurfaceEntity.SurfaceProtection, parent: https://developer.android.com/reference/kotlin/androidx/xr/scenecore/Entity? )` Public factory function for a SurfaceEntity. |

| ### Public functions |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/xr/scenecore/PerceivedResolutionResult` | `https://developer.android.com/reference/kotlin/androidx/xr/scenecore/SurfaceEntity#getPerceivedResolution(androidx.xr.arcore.RenderViewpoint)(renderViewpoint: https://developer.android.com/reference/kotlin/androidx/xr/arcore/RenderViewpoint)` Gets the perceived resolution of the entity in the provided `https://developer.android.com/reference/kotlin/androidx/xr/arcore/RenderViewpoint`. |
| `https://developer.android.com/reference/android/view/Surface.html` | `@https://developer.android.com/reference/kotlin/androidx/annotation/MainThread https://developer.android.com/reference/kotlin/androidx/xr/scenecore/SurfaceEntity#getSurface()()` Returns a surface into which the application can render stereo image content. |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `@https://developer.android.com/reference/kotlin/androidx/annotation/MainThread @https://developer.android.com/reference/kotlin/androidx/xr/scenecore/ExperimentalSurfaceEntityPixelDimensionsApi https://developer.android.com/reference/kotlin/androidx/xr/scenecore/SurfaceEntity#setSurfacePixelDimensions(androidx.xr.runtime.math.IntSize2d)(dimensions: https://developer.android.com/reference/kotlin/androidx/xr/runtime/math/IntSize2d)` Sets the width and height of the `https://developer.android.com/reference/android/view/Surface.html` which backs this `https://developer.android.com/reference/kotlin/androidx/xr/scenecore/SurfaceEntity` in pixels. |

| ### Public properties |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/xr/runtime/math/FloatSize3d` | `https://developer.android.com/reference/kotlin/androidx/xr/scenecore/SurfaceEntity#dimensions()` Returns the size of the canvas in the local spatial coordinate system of the entity. |
| `https://developer.android.com/reference/kotlin/androidx/xr/scenecore/SurfaceEntity.EdgeFeatheringParams` | `https://developer.android.com/reference/kotlin/androidx/xr/scenecore/SurfaceEntity#edgeFeatheringParams()` The `https://developer.android.com/reference/kotlin/androidx/xr/scenecore/SurfaceEntity.EdgeFeatheringParams` feathering pattern to be used along the edges of the Shape. |
| `https://developer.android.com/reference/kotlin/androidx/xr/scenecore/SurfaceEntity.Shape` | `https://developer.android.com/reference/kotlin/androidx/xr/scenecore/SurfaceEntity#shape()` The shape of the canvas that backs the Entity. |
| `https://developer.android.com/reference/kotlin/androidx/xr/scenecore/SurfaceEntity.StereoMode` | `https://developer.android.com/reference/kotlin/androidx/xr/scenecore/SurfaceEntity#stereoMode()` Controls how the surface content will be routed for stereo viewing. |

### Inherited functions

From [androidx.xr.scenecore.BaseScenePose](https://developer.android.com/reference/kotlin/androidx/xr/scenecore/BaseScenePose) `open suspend https://developer.android.com/reference/kotlin/androidx/xr/scenecore/HitTestResult?` `https://developer.android.com/reference/kotlin/androidx/xr/scenecore/BaseScenePose#hitTest(androidx.xr.runtime.math.Vector3,androidx.xr.runtime.math.Vector3)(origin: https://developer.android.com/reference/kotlin/androidx/xr/runtime/math/Vector3, direction: https://developer.android.com/reference/kotlin/androidx/xr/runtime/math/Vector3)`

Perform a hit test from the specified origin in the specified direction into the Scene.
`open suspend https://developer.android.com/reference/kotlin/androidx/xr/scenecore/HitTestResult?` `https://developer.android.com/reference/kotlin/androidx/xr/scenecore/BaseScenePose#hitTest(androidx.xr.runtime.math.Vector3,androidx.xr.runtime.math.Vector3,kotlin.Int)(origin: https://developer.android.com/reference/kotlin/androidx/xr/runtime/math/Vector3, direction: https://developer.android.com/reference/kotlin/androidx/xr/runtime/math/Vector3, hitTestFilter: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html)`

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

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

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

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

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/kotlin/androidx/xr/scenecore/Entity) `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` `https://developer.android.com/reference/kotlin/androidx/xr/scenecore/Entity#addChild(androidx.xr.scenecore.Entity)(child: https://developer.android.com/reference/kotlin/androidx/xr/scenecore/Entity)`

Sets an Entity to be a child of this Entity in the scene graph.
`https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html` `https://developer.android.com/reference/kotlin/androidx/xr/scenecore/Entity#addComponent(androidx.xr.scenecore.Component)(component: https://developer.android.com/reference/kotlin/androidx/xr/scenecore/Component)`

Adds a Component to this Entity.
`@https://developer.android.com/reference/kotlin/androidx/annotation/FloatRange(from = 0.0, to = 1.0) https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-float/index.html` `https://developer.android.com/reference/kotlin/androidx/xr/scenecore/Entity#getAlpha(androidx.xr.scenecore.Space)(relativeTo: https://developer.android.com/reference/kotlin/androidx/xr/scenecore/Space)`

Returns the alpha transparency set for this Entity, relative to given Space.
`https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-list/index.html<https://developer.android.com/reference/kotlin/androidx/xr/scenecore/Component>` `https://developer.android.com/reference/kotlin/androidx/xr/scenecore/Entity#getComponents()()`

Retrieves all components attached to this Entity.
`https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-list/index.html<T>` `<T : https://developer.android.com/reference/kotlin/androidx/xr/scenecore/Component> https://developer.android.com/reference/kotlin/androidx/xr/scenecore/Entity#getComponentsOfType(java.lang.Class)(type: https://developer.android.com/reference/java/lang/Class.html<T>)`

Retrieves all Components of the given type `https://developer.android.com/reference/kotlin/androidx/xr/scenecore/Entity#getComponentsOfType(java.lang.Class)` and its subtypes attached to this Entity.
`open https://developer.android.com/reference/kotlin/androidx/xr/runtime/math/Pose` `https://developer.android.com/reference/kotlin/androidx/xr/scenecore/Entity#getPose(androidx.xr.scenecore.Space)(relativeTo: https://developer.android.com/reference/kotlin/androidx/xr/scenecore/Space)`

Returns the `https://developer.android.com/reference/kotlin/androidx/xr/runtime/math/Pose` for this Entity, relative to the provided `https://developer.android.com/reference/kotlin/androidx/xr/scenecore/Space`.
`open @https://developer.android.com/reference/kotlin/androidx/annotation/FloatRange(from = 0.0) https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-float/index.html` `https://developer.android.com/reference/kotlin/androidx/xr/scenecore/Entity#getScale(androidx.xr.scenecore.Space)(relativeTo: https://developer.android.com/reference/kotlin/androidx/xr/scenecore/Space)`

Returns the scale of this entity, relative to given space.
`https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html` `https://developer.android.com/reference/kotlin/androidx/xr/scenecore/Entity#isEnabled(kotlin.Boolean)(includeParents: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html)`

Returns the enabled status of this Entity.
`https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` `https://developer.android.com/reference/kotlin/androidx/xr/scenecore/Entity#removeAllComponents()()`

Remove all components from this Entity.
`https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` `https://developer.android.com/reference/kotlin/androidx/xr/scenecore/Entity#removeComponent(androidx.xr.scenecore.Component)(component: https://developer.android.com/reference/kotlin/androidx/xr/scenecore/Component)`

Removes the given Component from this Entity.
`https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` `https://developer.android.com/reference/kotlin/androidx/xr/scenecore/Entity#setAlpha(kotlin.Float)(alpha: @https://developer.android.com/reference/kotlin/androidx/annotation/FloatRange(from = 0.0, to = 1.0) https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-float/index.html)`

Sets the alpha transparency of the Entity relative to the parent Space.
`https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` `https://developer.android.com/reference/kotlin/androidx/xr/scenecore/Entity#setEnabled(kotlin.Boolean)(enabled: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html)`

Sets the local enabled state of this Entity.
`open https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` `https://developer.android.com/reference/kotlin/androidx/xr/scenecore/Entity#setPose(androidx.xr.runtime.math.Pose,androidx.xr.scenecore.Space)(pose: https://developer.android.com/reference/kotlin/androidx/xr/runtime/math/Pose, relativeTo: https://developer.android.com/reference/kotlin/androidx/xr/scenecore/Space)`

Sets the `https://developer.android.com/reference/kotlin/androidx/xr/runtime/math/Pose` for this Entity.
`open https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` `https://developer.android.com/reference/kotlin/androidx/xr/scenecore/Entity#setScale(kotlin.Float,androidx.xr.scenecore.Space)(scale: @https://developer.android.com/reference/kotlin/androidx/annotation/FloatRange(from = 0.0) https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-float/index.html, relativeTo: https://developer.android.com/reference/kotlin/androidx/xr/scenecore/Space)`

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

### Inherited properties

From [androidx.xr.scenecore.BaseScenePose](https://developer.android.com/reference/kotlin/androidx/xr/scenecore/BaseScenePose) `open https://developer.android.com/reference/kotlin/androidx/xr/runtime/math/Pose` `https://developer.android.com/reference/kotlin/androidx/xr/scenecore/BaseScenePose#poseInActivitySpace()`

The current `https://developer.android.com/reference/kotlin/androidx/xr/runtime/math/Pose` relative to the activity space root.
From [androidx.xr.scenecore.Entity](https://developer.android.com/reference/kotlin/androidx/xr/scenecore/Entity) `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-list/index.html<https://developer.android.com/reference/kotlin/androidx/xr/scenecore/Entity>` `https://developer.android.com/reference/kotlin/androidx/xr/scenecore/Entity#children()`

Provides the list of all children of this entity.
`https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-char-sequence/index.html` `https://developer.android.com/reference/kotlin/androidx/xr/scenecore/Entity#contentDescription()`

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

The parent of this Entity, from which this Entity will inherit most of its properties.

## Public companion functions

### create

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

```
@MainThread
fun create(
    session: Session,
    pose: Pose = Pose.Identity,
    shape: SurfaceEntity.Shape = Shape.Quad(FloatSize2d(1.0f, 1.0f)),
    stereoMode: SurfaceEntity.StereoMode = StereoMode.MONO,
    superSampling: SurfaceEntity.SuperSampling = SuperSampling.PENTAGON,
    surfaceProtection: SurfaceEntity.SurfaceProtection = SurfaceProtection.NONE,
    parent: Entity? = null
): SurfaceEntity
```

Public factory function for a SurfaceEntity.

| Parameters |
|---|---|
| `session: https://developer.android.com/reference/kotlin/androidx/xr/runtime/Session` | Session to create the SurfaceEntity in. |
| `pose: https://developer.android.com/reference/kotlin/androidx/xr/runtime/math/Pose = Pose.Identity` | Pose of this entity relative to its parent, default value is Identity. |
| `shape: https://developer.android.com/reference/kotlin/androidx/xr/scenecore/SurfaceEntity.Shape = Shape.Quad(FloatSize2d(1.0f, 1.0f))` | The `https://developer.android.com/reference/kotlin/androidx/xr/scenecore/SurfaceEntity.Shape` which describes the spatialized shape of the canvas. |
| `stereoMode: https://developer.android.com/reference/kotlin/androidx/xr/scenecore/SurfaceEntity.StereoMode = StereoMode.MONO` | Stereo mode for the surface. |
| `superSampling: https://developer.android.com/reference/kotlin/androidx/xr/scenecore/SurfaceEntity.SuperSampling = SuperSampling.PENTAGON` | The `https://developer.android.com/reference/kotlin/androidx/xr/scenecore/SurfaceEntity.SuperSampling` which describes whether super sampling is enabled for the surface. |
| `surfaceProtection: https://developer.android.com/reference/kotlin/androidx/xr/scenecore/SurfaceEntity.SurfaceProtection = SurfaceProtection.NONE` | The `https://developer.android.com/reference/kotlin/androidx/xr/scenecore/SurfaceEntity.SurfaceProtection` which describes whether the hosted surface should support Widevine DRM. |
| `parent: https://developer.android.com/reference/kotlin/androidx/xr/scenecore/Entity? = null` | 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/kotlin/androidx/xr/scenecore/ActivitySpace` or any other `https://developer.android.com/reference/kotlin/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/kotlin/androidx/xr/scenecore/Entity` pre-configuration before making it visible. |

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

## Public functions

### getPerceivedResolution

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

```
fun getPerceivedResolution(renderViewpoint: RenderViewpoint): PerceivedResolutionResult
```

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

This API is only intended for use in Full Space and will return `https://developer.android.com/reference/kotlin/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 |
|---|---|
| `renderViewpoint: https://developer.android.com/reference/kotlin/androidx/xr/arcore/RenderViewpoint` | that provides the pose and field-of-view of the camera. |

| Returns |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/xr/scenecore/PerceivedResolutionResult` | A `https://developer.android.com/reference/kotlin/androidx/xr/scenecore/PerceivedResolutionResult` which encapsulates the outcome: - `https://developer.android.com/reference/kotlin/androidx/xr/scenecore/PerceivedResolutionResult.Success` containing the if the calculation is successful. - `https://developer.android.com/reference/kotlin/androidx/xr/scenecore/PerceivedResolutionResult.EntityTooClose` if the entity is too close to the camera. - `https://developer.android.com/reference/kotlin/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/kotlin/androidx/xr/runtime/Session#config()` is not set to `https://developer.android.com/reference/kotlin/androidx/xr/runtime/DeviceTrackingMode#SPATIAL()`. |

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

### getSurface

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

```
@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 |
|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-illegal-state-exception/index.html` | 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
fun setSurfacePixelDimensions(dimensions: IntSize2d): Unit
```

Sets the width and height of the `https://developer.android.com/reference/android/view/Surface.html` which backs this `https://developer.android.com/reference/kotlin/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/kotlin/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/kotlin/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/kotlin/androidx/xr/scenecore/SurfaceEntity.SurfaceProtection#PROTECTED()` was set at creation. |

## Public properties

### dimensions

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

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

### edgeFeatheringParams

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

```
var edgeFeatheringParams: SurfaceEntity.EdgeFeatheringParams
```

The `https://developer.android.com/reference/kotlin/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. |

### shape

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

```
var shape: SurfaceEntity.Shape
```

The shape of the canvas that backs the Entity. Updating this value will alter the `https://developer.android.com/reference/kotlin/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. |

### stereoMode

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

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