/
Android Studio Sign in

SurfaceEntity

public final class SurfaceEntity extends Entity

java.lang.Object
   ↳ androidx.xr.scenecore.BaseScenePose
     ↳ androidx.xr.scenecore.Entity
       ↳ 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 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.

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,
    @NonNull SurfaceEntity.StereoMode stereoMode,
    @NonNull SurfaceEntity.SuperSampling superSampling,
    @NonNull SurfaceEntity.SurfaceProtection surfaceProtection,
    Entity parent
)

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 provided RenderViewpoint.
final @NonNull SurfaceEntity.Shape

The shape of the canvas that backs the Entity.
final @NonNull SurfaceEntity.StereoMode

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

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

Sets the width and height of the Surface which backs this SurfaceEntity in pixels.

Inherited methods
From androidx.xr.scenecore.BaseScenePose
@NonNull Pose

The current Pose relative to the activity space root.
HitTestResult
hitTest(@NonNull Vector3 origin, @NonNull Vector3 direction)

Perform a hit test from the specified origin in the specified direction into the Scene.
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.
@NonNull Vector3
transformDirectionTo(
    @NonNull Vector3 direction,
    @NonNull ScenePose destination
)

Transforms a direction from this ScenePose's local space to the destination ScenePose's local space.
@NonNull Pose
transformPoseTo(@NonNull Pose pose, @NonNull ScenePose destination)

Returns a Pose relative to this ScenePose, transformed into a Pose relative to the destination.
@NonNull Vector3
transformPositionTo(
    @NonNull Vector3 position,
    @NonNull ScenePose destination
)

Transforms a position from this ScenePose's local space to the destination ScenePose's local space.
@NonNull Vector3

Transforms a vector from this ScenePose's local space to the destination ScenePose's local space.
From androidx.xr.scenecore.Entity
final void

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

Adds a Component to this Entity.
final @FloatRange(from = 0.0, to = 1.0) float
getAlpha(@NonNull Space relativeTo)

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

Provides the list of all children of this entity.
final @NonNull List<@NonNull Component>

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

Retrieves all Components of the given type T and its subtypes attached to this Entity.
final @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(@NonNull Space relativeTo)

Returns the Pose for this Entity, relative to the provided Space.
@FloatRange(from = 0.0) float
getScale(@NonNull Space relativeTo)

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

Returns the enabled status of this Entity.
final void

Remove all components from this Entity.
final void

Removes the given Component from this Entity.
final void
setAlpha(@FloatRange(from = 0.0, to = 1.0) float alpha)

Sets the alpha transparency of the Entity relative to the parent Space.
final void

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

Sets the local enabled state of this Entity.
void

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(@FloatRange(from = 0.0) float scale, @NonNull Space relativeTo)

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

Public methods

create

Added in 1.0.0-beta01
@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
@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.
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., ActivitySpace or any other Entity already present in the scene) is assigned later, the entity will become visible (provided it is enabled). This allows for Entity pre-configuration before making it visible.
Returns
@NonNull SurfaceEntity

a SurfaceEntity instance

getDimensions

Added in 1.0.0-beta01
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-beta01
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
IllegalStateException

when setting this value if the Entity has been disposed.

getPerceivedResolution

Added in 1.0.0-beta01
public final @NonNull PerceivedResolutionResult getPerceivedResolution(@NonNull RenderViewpoint renderViewpoint)

Gets the perceived resolution of the entity in the provided RenderViewpoint.

This API is only intended for use in Full Space and will return 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
@NonNull RenderViewpoint renderViewpoint

that provides the pose and field-of-view of the camera.
Returns
@NonNull PerceivedResolutionResult

A PerceivedResolutionResult which encapsulates the outcome: - PerceivedResolutionResult.Success containing the androidx.xr.scenecore.runtime.PixelDimensions if the calculation is successful. - PerceivedResolutionResult.EntityTooClose if the entity is too close to the camera. - PerceivedResolutionResult.InvalidRenderViewpoint if the camera information required for the calculation is invalid or unavailable.
Throws
IllegalStateException

if Session.config is not set to androidx.xr.runtime.DeviceTrackingMode.SPATIAL.
See also
PerceivedResolutionResult

getShape

Added in 1.0.0-beta01
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
IllegalArgumentException

if an invalid canvas shape is provided.
IllegalStateException

when setting this value if the Entity has been disposed.

getStereoMode

Added in 1.0.0-beta01
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
IllegalStateException

when setting this value if the Entity has been disposed.

getSurface

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

if the Entity has been disposed.

setEdgeFeatheringParams

Added in 1.0.0-beta01
@MainThread
public final void setEdgeFeatheringParams(
    @NonNull SurfaceEntity.EdgeFeatheringParams value
)

The EdgeFeatheringParams feathering pattern to be used along the edges of the Shape. This value must only be set from the main thread.

Throws
IllegalStateException

when setting this value if the Entity has been disposed.

setShape

Added in 1.0.0-beta01
@MainThread
public final void setShape(@NonNull SurfaceEntity.Shape value)

The shape of the canvas that backs the Entity. Updating this value will alter the dimensions of the Entity.

Throws
IllegalArgumentException

if an invalid canvas shape is provided.
IllegalStateException

when setting this value if the Entity has been disposed.

setStereoMode

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

when setting this value if the Entity has been disposed.

setSurfacePixelDimensions

Added in 1.0.0-beta01
@MainThread
@ExperimentalSurfaceEntityPixelDimensionsApi
public final void setSurfacePixelDimensions(@NonNull IntSize2d dimensions)

Sets the width and height of the Surface which backs this 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 android.graphics.Canvas APIs to render Bitmaps into the Surface. It is not needed if the application is using MediaPlayer or ExoPlayer to decode media into the Surface, as those systems automatically manage the dimensions of the Surface.

Note that this method does not change the spatial dimensions of the SurfaceEntity, it only updates the resolution of the Surface. Unlike PanelEntity, changing this value will update the pixel density of the displayed Surface. Changing this will not change the scale.

Throws
IllegalArgumentException

if the dimensions are not greater than 0.
IllegalStateException

if the Entity has been disposed, or if SurfaceProtection.PROTECTED was set at creation.
Morty Proxy This is a proxified and sanitized view of the page, visit original site.