PanelEntity

Artifact: androidx.xr.scenecore:scenecore

Kotlin |Java

open class PanelEntity : BaseEntity

kotlin.Any
↳	androidx.xr.scenecore.BaseScenePose
	↳	androidx.xr.scenecore.BaseEntity
		↳	androidx.xr.scenecore.PanelEntity

Known direct subclasses

ActivityPanelEntity, MainPanelEntity

`ActivityPanelEntity`	ActivityPanelEntity creates a spatial panel for embedding an `Activity` in Android XR.
`MainPanelEntity`	Represents the main spatialized panel in a `Scene`.

PanelEntity contains an arbitrary 2D Android View, within a spatialized XR scene.

Summary

Public companion functions
`PanelEntity`	`create( session: Session, view: View, dimensions: FloatSize2d, name: String, pose: Pose )` Factory method for a spatialized PanelEntity.
`PanelEntity`	`create( session: Session, view: View, pixelDimensions: IntSize2d, name: String, pose: Pose )` Factory method for a spatialized PanelEntity.

Public functions
`PerceivedResolutionResult`	`getPerceivedResolution()` Gets the perceived resolution of this Entity in the `CameraView`.
`Pose`	`@ExperimentalPanelCoordinateApi transformNormalizedCoordinatesToPose(coordinates: Vector2)` Gets the 3D pose of a 2D normalized extent coordinate within the Entity's local space.
`Pose`	`@ExperimentalPanelCoordinateApi transformPixelCoordinatesToPose(coordinates: Vector2)` Gets the 3D pose of a 2D pixel coordinate within the Entity's local space.

Public properties
`Float`	`cornerRadius` The corner radius of the PanelEntity, in meters.
`Boolean`	`isMainPanelEntity` True if this panel is the MainPanelEntity, false otherwise.
`FloatSize2d`	`size` The dimensions of this PanelEntity in local space, in units relative to the scale of this Entity's parent.
`IntSize2d`	`sizeInPixels` The dimensions of this PanelEntity, in pixels, which is the resolution of the underlying surface.

Inherited functions

From androidx.xr.scenecore.BaseEntity

`open Unit`	`addChild(child: Entity)` Sets an Entity to be a child of this Entity in the scene graph.
`open Boolean`	`addComponent(component: Component)` Adds a Component to this Entity.
`open Unit`	`dispose()` Disposes of any system resources held by this Entity, and transitively calls dispose() on all its children.
`open Float`	`getAlpha(relativeTo: Space)` Returns the alpha transparency set for this Entity, relative to given Space.
`open List<Component>`	`getComponents()` Retrieves all components attached to this Entity.
`open List<T>`	`<T : Component> getComponentsOfType(type: Class<T>)` Retrieves all Components of the given type `T` and its sub-types attached to this Entity.
`open Pose`	`getPose(relativeTo: Space)` Returns the `Pose` for this Entity, relative to the provided `Space`.
`open Float`	`getScale(relativeTo: Space)` Returns the scale of this entity, relative to given space.
`open Boolean`	`isEnabled(includeParents: Boolean)` Returns the enabled status of this Entity.
`open Unit`	`removeAllComponents()` Remove all components from this Entity.
`open Unit`	`removeComponent(component: Component)` Removes the given Component from this Entity.
`open Unit`	`setAlpha(alpha: Float, relativeTo: Space)` Sets the alpha transparency of the Entity relative to given Space.
`open Unit`	`setEnabled(enabled: Boolean)` Sets the local enabled state of this Entity.
`open Unit`	`setPose(pose: Pose, relativeTo: Space)` Sets the `Pose` for this Entity.
`open Unit`	`setScale(scale: Float, relativeTo: Space)` Sets the scale of this Entity relative to the given Space.

From androidx.xr.scenecore.Entity

`open @FloatRange(from = 0.0, to = 1.0) Float`	`getAlpha()` Returns the alpha transparency set for this Entity.
`open Pose`	`getPose()` Returns the `Pose` for this Entity, relative to its parent.
`open @FloatRange(from = 0.0) Float`	`getScale()` Returns the local scale of this Entity, not inclusive of the parent's scale.
`open Unit`	`setAlpha(alpha: @FloatRange(from = 0.0, to = 1.0) Float)` Sets the alpha transparency of the Entity and its children.
`open Unit`	`setPose(pose: Pose)` Sets the `Pose` for this Entity, relative to its parent.
`open Unit`	`setScale(scale: @FloatRange(from = 0.0) Float)` Sets the scale of this Entity relative to its parent.

From androidx.xr.scenecore.ScenePose

`abstract suspend HitTestResult?`	`hitTest(origin: Vector3, direction: Vector3)` Perform a hit test from the specified origin in the specified direction into the Scene.
`abstract suspend HitTestResult?`	`hitTest(origin: Vector3, direction: Vector3, hitTestFilter: Int)` Creates a hit test from the specified origin in the specified direction into the scene.
`abstract Pose`	`transformPoseTo(pose: Pose, destination: ScenePose)` Returns a `Pose` relative to this ScenePose, transformed into a Pose relative to the destination.

Inherited properties

From androidx.xr.scenecore.BaseEntity

`open List<Entity>`	`children` Provides the list of all children of this entity.
`open CharSequence`	`contentDescription` Alternate text for this Entity to be consumed by Accessibility systems.
`open Entity?`	`parent` The parent of this Entity, from which this Entity will inherit most of its properties.

From androidx.xr.scenecore.ScenePose

abstract Pose

activitySpacePose

The current Pose relative to the activity space root.

Public companion functions

create

Added in 1.0.0-alpha10

fun create(
    session: Session,
    view: View,
    dimensions: FloatSize2d,
    name: String,
    pose: Pose = Pose.Identity
): PanelEntity

Factory method for a spatialized PanelEntity.

Parameters
`session: Session`	XR `Session` in which to create the PanelEntity.
`view: View`	`View` to embed in this panel entity.
`dimensions: FloatSize2d`	Spatialized dimensions for the underlying surface for the given view, in meters.
`name: String`	Name of this PanelEntity.
`pose: Pose = Pose.Identity`	`Pose` of this entity relative to its parent, default value is Identity.

Returns
`PanelEntity`	a PanelEntity instance.

create

Added in 1.0.0-alpha10

fun create(
    session: Session,
    view: View,
    pixelDimensions: IntSize2d,
    name: String,
    pose: Pose = Pose.Identity
): PanelEntity

Factory method for a spatialized PanelEntity.

Parameters
`session: Session`	XR `Session` in which to create the PanelEntity.
`view: View`	`View` to embed in this panel entity.
`pixelDimensions: IntSize2d`	Dimensions for the underlying surface for the given view, in pixels.
`name: String`	Name of the panel.
`pose: Pose = Pose.Identity`	`Pose` of this PanelEntity relative to its parent, default value is Identity.

Returns
`PanelEntity`	a PanelEntity instance.

Public functions

getPerceivedResolution

Added in 1.0.0-alpha10

fun getPerceivedResolution(): PerceivedResolutionResult

Gets the perceived resolution of this Entity in the CameraView.

This API is only intended for use in Full Space Mode and will return PerceivedResolutionResult.InvalidCameraView in Home Space Mode. For applications requiring perceived resolution in Home Space Mode, see MainPanelEntity.getPerceivedResolution.

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. This can be used by clients to dynamically optimize the resolution of assets within the PanelEntity, for example by using lower-resolution assets within panels that are further from the viewer. The Entity's own rotation and the camera's viewing direction are disregarded.

Returns
`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`

transformNormalizedCoordinatesToPose

Added in 1.0.0-alpha10

@ExperimentalPanelCoordinateApi
fun transformNormalizedCoordinatesToPose(coordinates: Vector2): Pose

Gets the 3D pose of a 2D normalized extent coordinate within the Entity's local space.

This method's inputs use a 2D normalized coordinate system where:

The origin (0.0, 0.0) is at the center of the panel.
The +X axis points towards the right edge (mapped to 1.0) of the panel content.
The +Y axis points towards the top edge (mapped to 1.0) of the panel content.

Values outside the -1.0, 1.0 range are permitted and will result in a pose positioned outside the panel's surface.

Note that calling this method on MainPanelEntity during android.app.Activity.onCreate can result in incorrect values.

Parameters
`coordinates: Vector2`	The normalized coordinates, relative to the origin at the center of the panel.

Returns
`Pose`	The 3D pose corresponding to the 2D normalized coordinate. The position will be coplanar to the panel's surface (z=0 in the panel's local space), and the orientation will be the identity rotation such that the Z axis points outwards from the panel.

See also
`transformPoseTo`	to transform the pose to a different coordinate space.

transformPixelCoordinatesToPose

Added in 1.0.0-alpha10

@ExperimentalPanelCoordinateApi
fun transformPixelCoordinatesToPose(coordinates: Vector2): Pose

Gets the 3D pose of a 2D pixel coordinate within the Entity's local space.

This method's inputs use a 2D pixel coordinate system where:

The origin (0, 0) is at the top-left corner of the panel.
The +X axis points towards the right edge of the panel content.
The +Y axis points towards the bottom edge of the panel content.

Input values are floats to allow for sub-pixel accuracy. Values outside the panel's pixel dimensions (e.g., x < 0 or y > panelHeight) are permitted and will result in a pose positioned outside the panel's surface.

Note that calling this method on MainPanelEntity during android.app.Activity.onCreate can result in incorrect values.

Parameters
`coordinates: Vector2`	The pixel coordinate, relative to the top-left origin.

Returns
`Pose`	The 3D pose corresponding to the 2D pixel coordinate. The position will be coplanar to the panel's surface (z=0 in the panel's local space), and the orientation will be the identity rotation such that the Z axis points outwards from the panel.