SurfaceEntity

Artifact: androidx.xr.scenecore:scenecore

Kotlin |Java

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
`public abstract class SurfaceEntity.EdgeFeatheringParams` Represents edge fading effects for a SurfaceEntity.
`public final class SurfaceEntity.EdgeFeatheringParams.NoFeathering extends SurfaceEntity.EdgeFeatheringParams` Applies no edge fading to any canvas.
`public final class SurfaceEntity.EdgeFeatheringParams.RectangleFeather extends SurfaceEntity.EdgeFeatheringParams`
`public interface SurfaceEntity.Shape` Represents the shape of the Canvas that backs a SurfaceEntity.
`public final class SurfaceEntity.Shape.Hemisphere implements SurfaceEntity.Shape` 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 final class SurfaceEntity.StereoMode` Specifies how the surface content will be routed for stereo viewing.
`public final class SurfaceEntity.SuperSampling` Specifies whether super sampling should be enabled for this surface.
`public final class SurfaceEntity.SurfaceProtection` Specifies whether the `Surface` which backs this `Entity` should be backed by `android.hardware.HardwareBuffer`s 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, @NonNull SurfaceEntity.StereoMode stereoMode, @NonNull SurfaceEntity.SuperSampling superSampling, @NonNull SurfaceEntity.SurfaceProtection surfaceProtection )` Public factory function for a SurfaceEntity.
`final @NonNull FloatSize3d`	`getDimensions()` Returns the size of the canvas in the local spatial coordinate system of the entity.
`final @NonNull SurfaceEntity.EdgeFeatheringParams`	`getEdgeFeatheringParams()` The `EdgeFeatheringParams` feathering pattern to be used along the edges of the Shape.
`final @NonNull PerceivedResolutionResult`	`getPerceivedResolution()` Gets the perceived resolution of the entity in the camera view.
`final @NonNull SurfaceEntity.Shape`	`getShape()` The shape of the canvas that backs the Entity.
`final @NonNull SurfaceEntity.StereoMode`	`getStereoMode()` Controls how the surface content will be routed for stereo viewing.
`final @NonNull Surface`	`@MainThread getSurface()` Returns a surface into which the application can render stereo image content.
`final void`	`@MainThread setEdgeFeatheringParams( @NonNull SurfaceEntity.EdgeFeatheringParams edgeFeatheringParams )` The `EdgeFeatheringParams` feathering pattern to be used along the edges of the Shape.
`final void`	`@MainThread setShape(@NonNull SurfaceEntity.Shape shape)` The shape of the canvas that backs the Entity.
`final void`	`@MainThread setStereoMode(@NonNull SurfaceEntity.StereoMode stereoMode)` Controls how the surface content will be routed for stereo viewing.

Inherited methods

From androidx.xr.scenecore.BaseEntity

`void`	`addChild(@NonNull Entity child)` Sets an Entity to be a child of this Entity in the scene graph.
`boolean`	`addComponent(@NonNull Component component)` Adds a Component to this Entity.
`void`	`dispose()` Disposes of any system resources held by this Entity, and transitively calls dispose() on all its children.
`float`	`getAlpha(@NonNull Space relativeTo)` Returns the alpha transparency set for this Entity, relative to given Space.
`@NonNull List<@NonNull Entity>`	`getChildren()` Provides the list of all children of this entity.
`@NonNull List<@NonNull Component>`	`getComponents()` Retrieves all components attached to this Entity.
`@NonNull List<@NonNull T>`	`<T extends Component> getComponentsOfType(@NonNull Class<@NonNull T> type)` Retrieves all Components of the given type `T` and its sub-types attached to this Entity.
`@NonNull CharSequence`	`getContentDescription()` Alternate text for this Entity to be consumed by Accessibility systems.
`Entity`	`getParent()` The parent of this Entity, from which this Entity will inherit most of its properties.
`@NonNull Pose`	`getPose(@NonNull Space relativeTo)` Returns the `Pose` for this Entity, relative to the provided `Space`.
`float`	`getScale(@NonNull Space relativeTo)` Returns the scale of this entity, relative to given space.
`boolean`	`isEnabled(boolean includeParents)` Returns the enabled status of this Entity.
`void`	`removeAllComponents()` Remove all components from this Entity.
`void`	`removeComponent(@NonNull Component component)` Removes the given Component from this Entity.
`void`	`setAlpha(float alpha, @NonNull Space relativeTo)` Sets the alpha transparency of the Entity relative to given Space.
`void`	`setContentDescription(@NonNull CharSequence contentDescription)` 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, @NonNull Space relativeTo)` Sets the `Pose` for this Entity.
`void`	`setScale(float scale, @NonNull Space 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`	`getAlpha()` Returns the alpha transparency set for this Entity.
`@NonNull Pose`	`getPose()` Returns the `Pose` for this Entity, relative to its parent.
`@FloatRange(from = 0.0) float`	`getScale()` 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`	`setPose(@NonNull Pose pose)` 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`	`getActivitySpacePose()` The current `Pose` relative to the activity space root.
`abstract HitTestResult`	`hitTest(@NonNull Vector3 origin, @NonNull Vector3 direction)` Perform a hit test from the specified origin in the specified direction into the Scene.
`abstract 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-alpha10

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

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.
`@NonNull SurfaceEntity.StereoMode stereoMode`	Stereo mode for the surface.
`@NonNull SurfaceEntity.SuperSampling superSampling`	The `SuperSampling` which describes whether super sampling is enabled for the surface.
`@NonNull SurfaceEntity.SurfaceProtection 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-alpha10

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-alpha10

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-alpha10

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` is not set to `Config.DeviceTrackingMode.LAST_KNOWN`.

See also
`PerceivedResolutionResult`

getShape

Added in 1.0.0-alpha10

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-alpha10

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
`kotlin.IllegalStateException`	when setting this value if the Entity has been disposed.

getSurface

Added in 1.0.0-alpha10

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

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

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

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

Throws
`kotlin.IllegalStateException`	when setting this value if the Entity has been disposed.

SurfaceEntity

Summary

Nested types

Public methods

Inherited methods

Public methods

create

getDimensions

getEdgeFeatheringParams

getPerceivedResolution

getShape

getStereoMode

getSurface

setEdgeFeatheringParams

setShape

setStereoMode