androidx.xr.compose.subspace.layout

fun SpatialSmoothFeatheringEffect(horizontal: Dp, vertical: Dp): SpatialFeatheringEffect

Defines a SpatialSmoothFeatheringEffect using Dp.

fun SpatialSmoothFeatheringEffect(horizontal: Float, vertical: Float): SpatialFeatheringEffect

Defines a SpatialSmoothFeatheringEffect using pixels.

fun SpatialSmoothFeatheringEffect(
    percentHorizontal: @IntRange(from = 0, to = 50) Int,
    percentVertical: @IntRange(from = 0, to = 50) Int
): SpatialFeatheringEffect

Defines SpatialSmoothFeatheringEffect based on the percent width and height of the layout.

@SubspaceComposable
@Composable
inline fun SubspaceLayout(
    modifier: SubspaceModifier = SubspaceModifier,
    measurePolicy: SubspaceMeasurePolicy
): Unit

SubspaceLayout is the main component for laying out leaf nodes with zero children.

The measurement, layout and intrinsic measurement behaviours of this layout will be defined by the SubspaceMeasurePolicy instance. See SubspaceMeasurePolicy for more details.

Example:

fun ExactSizeSpacer(size: IntVolumeSize) {
  SubspaceLayout(SubspaceModifier.testTag("exactSizeSpacer")) {
    _, _ -> layout(size.width, size.height, size.depth) {}
  }
}

@SubspaceComposable
@Composable
inline fun SubspaceLayout(
    crossinline content: @Composable @SubspaceComposable () -> Unit,
    modifier: SubspaceModifier = SubspaceModifier,
    measurePolicy: SubspaceMeasurePolicy
): Unit

SubspaceLayout is the main core component for layout. It can be used to measure and position zero or more layout children.

The measurement, layout and intrinsic measurement behaviours of this layout will be defined by the SubspaceMeasurePolicy instance. See SubspaceMeasurePolicy for more details.

Example:

fun MyLayout(
    modifier: SubspaceModifier = SubspaceModifier,
    content: @SubspaceComposable @Composable () -> Unit) {
  SubspaceLayout(content = content, modifier = modifier) {
    measurables, constraints ->
    val placeables = measurables.map { it.measure(constraints) }
    layout(constraints.maxWidth, constraints.maxHeight, constraints.maxDepth) {
      placeables.forEach { it.place(Pose.Identity) }
    }
  }
}

fun SubspaceModifier.alpha(alpha: @FloatRange(from = 0.0, to = 1.0) Float): SubspaceModifier

Sets the opacity of this element (and its children) to a value between 0..1. An alpha value of 0.0f means fully transparent while a value of 1.0f is completely opaque. Elements with semi-transparent alpha values (> 0.0 but < 1.0f) will be rendered using alpha-blending.

fun SubspaceModifier.aspectRatio(
    ratio: @FloatRange(from = 0.0, fromInclusive = false) Float,
    matchHeightConstraintsFirst: Boolean = false
): SubspaceModifier

Attempts to size the content to match a specified aspect ratio by trying to match one of the incoming constraints in the following order: VolumeConstraints.maxWidth, VolumeConstraints.maxHeight, VolumeConstraints.minWidth, VolumeConstraints.minHeight if matchHeightConstraintsFirst is false (which is the default), or VolumeConstraints.maxHeight, VolumeConstraints.maxWidth, VolumeConstraints.minHeight, VolumeConstraints.minWidth if matchHeightConstraintsFirst is true. The size in the other dimension is determined by the aspect ratio. The combinations will be tried in this order until one non-empty is found to satisfy the constraints. If no valid size is obtained this way, it means that there is no non-empty size satisfying both the constraints and the aspect ratio, so the constraints will not be respected and the content will be sized such that the VolumeConstraints.maxWidth or VolumeConstraints.maxHeight is matched (depending on matchHeightConstraintsFirst). Note that this modifier constrains the ratio between the content's width and height only. The depth dimension is not affected or constrained by this aspect ratio modifier.

Example usage:

SpatialPanel(SubspaceModifier.width(100.dp).aspectRatio(16f / 9f)) {
    Text(text = "Inner Composable Content")
}

fun SubspaceModifier.billboard(enabled: Boolean = true): SubspaceModifier

A SubspaceModifier that forces the content to remain upright and will rotate on the y-axis that the content faces the user at all times.

A user of this API should configure the activity's Session object with Config.HeadTrackingMode.LAST_KNOWN which requires android.permission.HEAD_TRACKING Android permission be granted by the calling application. session.configure( config = session.config.copy(headTracking = Config.HeadTrackingMode.LAST_KNOWN) )

fun SubspaceModifier.depth(depth: Dp): SubspaceModifier

Declare the preferred size of the content to be exactly depth dp along the z dimension. Panels have 0 depth and ignore this modifier.

fun SubspaceModifier.depthIn(min: Dp = Dp.Unspecified, max: Dp = Dp.Unspecified): SubspaceModifier

Constrain the depth of the content to be between mindp and maxdp as permitted by the incoming measurement constraints. If the incoming constraints are more restrictive the requested size will obey the incoming constraints and attempt to be as close as possible to the preferred size.

fun SubspaceModifier.fillMaxDepth(
    fraction: @FloatRange(from = 0.0, to = 1.0) Float = 1.0f
): SubspaceModifier

Have the content fill (possibly only partially) the VolumeConstraints.maxDepth of the incoming measurement constraints, by setting the minimum depth and the maximum depth to be equal to the maximum depth multiplied by fraction. Note that, by default, the fraction is 1, so the modifier will make the content fill the whole available depth. If the incoming maximum depth is VolumeConstraints.Infinity this modifier will have no effect.

fun SubspaceModifier.fillMaxHeight(
    fraction: @FloatRange(from = 0.0, to = 1.0) Float = 1.0f
): SubspaceModifier

Have the content fill (possibly only partially) the VolumeConstraints.maxHeight of the incoming measurement constraints, by setting the minimum height and the maximum height to be equal to the maximum height multiplied by fraction. Note that, by default, the fraction is 1, so the modifier will make the content fill the whole available height. If the incoming maximum height is VolumeConstraints.Infinity this modifier will have no effect.

fun SubspaceModifier.fillMaxSize(
    fraction: @FloatRange(from = 0.0, to = 1.0) Float = 1.0f
): SubspaceModifier

Have the content fill (possibly only partially) the VolumeConstraints.maxWidth, VolumeConstraints.maxHeight, and VolumeConstraints.maxDepth of the incoming measurement constraints. See SubspaceModifier.fillMaxWidth, SubspaceModifier.fillMaxHeight, and SubspaceModifier.fillMaxDepth for details. Note that, by default, the fraction is 1, so the modifier will make the content fill the whole available space. If the incoming maximum width or height or depth is VolumeConstraints.Infinity this modifier will have no effect in that dimension.

fun SubspaceModifier.fillMaxWidth(
    fraction: @FloatRange(from = 0.0, to = 1.0) Float = 1.0f
): SubspaceModifier

Have the content fill (possibly only partially) the VolumeConstraints.maxWidth of the incoming measurement constraints, by setting the minimum width and the maximum width to be equal to the maximum width multiplied by fraction. Note that, by default, the fraction is 1, so the modifier will make the content fill the whole available width. If the incoming maximum width is VolumeConstraints.Infinity this modifier will have no effect.

fun SubspaceModifier.gravityAligned(): SubspaceModifier

A SubspaceModifier that forces the content to remain upright, aligned with gravity by isolating the element's yaw by cancelling parent pitch and roll.

This modifier calculates the necessary counter-rotation to ignore the pitch and roll of its parent entity's total world transformation. It only affects the rotation and not the translation. This is useful for UI elements like labels or billboards that should always stay level, regardless of the orientation of the object they are attached to. It effectively isolates the yaw (rotation around the vertical Y-axis).

fun SubspaceModifier.height(height: Dp): SubspaceModifier

Declare the preferred size of the content to be exactly height dp along the y dimension.

fun SubspaceModifier.heightIn(min: Dp = Dp.Unspecified, max: Dp = Dp.Unspecified): SubspaceModifier

Constrain the height of the content to be between mindp and maxdp as permitted by the incoming measurement constraints. If the incoming constraints are more restrictive the requested size will obey the incoming constraints and attempt to be as close as possible to the preferred size.

fun SubspaceModifier.layout(
    measure: SubspaceMeasureScope.(SubspaceMeasurable, VolumeConstraints) -> SubspaceMeasureResult
): SubspaceModifier

Creates a node that allows changing how the wrapped element is measured and laid out.

fun SubspaceModifier.lookAtUser(
    enabled: Boolean = true,
    up: Vector3 = Vector3(0f, 1f, 0f)
): SubspaceModifier

A SubspaceModifier that continuously rotates content so that it faces the user at all times.

A user of this API should configure the activity's Session object with Config.HeadTrackingMode.LAST_KNOWN which requires android.permission.HEAD_TRACKING Android permission be granted by the calling application. session.configure( config = session.config.copy(headTracking = Config.HeadTrackingMode.LAST_KNOWN) )

fun SubspaceModifier.offset(x: Dp = 0.dp, y: Dp = 0.dp, z: Dp = 0.dp): SubspaceModifier

Offset the content by (x dp, y dp, z dp). The offsets can be positive as well as non-positive.

fun SubspaceModifier.onGloballyPositioned(
    onGloballyPositioned: (SubspaceLayoutCoordinates) -> Unit
): SubspaceModifier

Invoke onGloballyPositioned with the SubspaceLayoutCoordinates of the element when the global position or the orientation of the content may have changed. Note that it will be called after a composition when the coordinates are finalized.

This callback executes after composition once the final coordinates are determined. It will be invoked at least once when the SubspaceLayoutCoordinates become available and subsequently whenever the composable's transform (position, rotation, scale) is updated relative to the subspace's origin.

The callback information will be relative to its subspace. For instance, When a nested subspace is moved by the global subspace its Pose will reflect its position in the nested subspace. Its position value will not be updated despite moving locations in the Global Subspace.

fun SubspaceModifier.onPointSourceParamsAvailable(
    onPointSourceParamsAvailable: (PointSourceParams) -> Unit
): SubspaceModifier

Used to provide a PointSourceParams to allow specifying the modified Composable as an audio source. See PointSourceParams for more info on how to attach this object to a media source.

PointSourceParams are used to configure a sound to be spatialized as a point in 3D space. This is to override the default behavior where sound is played from the SpatialMainPanel.

import androidx.compose.foundation.AndroidExternalSurface
import androidx.compose.runtime.Composable
import androidx.compose.runtime.DisposableEffect
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.ui.platform.LocalContext
import androidx.compose.ui.unit.dp
import androidx.xr.compose.platform.LocalSession
import androidx.xr.compose.subspace.MovePolicy
import androidx.xr.compose.subspace.SpatialPanel
import androidx.xr.compose.subspace.SubspaceComposable
import androidx.xr.compose.subspace.layout.SubspaceModifier
import androidx.xr.compose.subspace.layout.onPointSourceParamsAvailable
import androidx.xr.compose.subspace.layout.size
import androidx.xr.scenecore.SpatialMediaPlayer

@Composable
@SubspaceComposable
fun MediaPlayerInSpatialPanel(mediaUri: Uri) {
    val session = LocalSession.current
    val context = LocalContext.current
    val mediaPlayer = remember { MediaPlayer() }
    val paramsSet = remember { mutableStateOf(false) }

    SpatialPanel(
        SubspaceModifier.size(400.dp).onPointSourceParamsAvailable {
            if (!paramsSet.value) {
                paramsSet.value = true
                mediaPlayer.setDataSource(context, mediaUri)
                SpatialMediaPlayer.setPointSourceParams(session!!, mediaPlayer, it)
                mediaPlayer.prepare()
                mediaPlayer.start()
            }
        },
        dragPolicy = MovePolicy(),
    ) {
        DisposableEffect(Unit) { onDispose { mediaPlayer.release() } }

        // Use this for playing video, or omit it for audio only use cases.
        AndroidExternalSurface {
            onSurface { surface, _, _ -> mediaPlayer.setSurface(surface) }
        }
    }
}

fun SubspaceModifier.onSizeChanged(
    onSizeChanged: (size: IntVolumeSize) -> Unit
): SubspaceModifier

Invokes onSizeChanged with the IntVolumeSize of the element when its size changes.

This callback is executed after the layout pass when the SubspaceComposable's size is finalized. It will be invoked at least once when the size becomes available and subsequently whenever the size changes.

For observing changes to position or orientation in addition to size, use SubspaceModifier.onGloballyPositioned instead.

fun SubspaceModifier.padding(all: Dp): SubspaceModifier

Apply all dp of additional space along each edge of the content, left, top, right, bottom, front, and back. Padding is applied before content measurement and takes precedence; content may only be as large as the remaining space.

Negative padding is not permitted — it will cause IllegalArgumentException. See padding

fun SubspaceModifier.padding(
    horizontal: Dp = 0.dp,
    vertical: Dp = 0.dp,
    depth: Dp = 0.dp
): SubspaceModifier

Apply horizontal dp space along the left and right edges of the content, vertical dp space along the top and bottom edges, and depth dp space along front and back edged. Padding is applied before content measurement and takes precedence; content may only be as large as the remaining space.

Negative padding is not permitted — it will cause IllegalArgumentException. See padding

fun SubspaceModifier.padding(
    left: Dp = 0.dp,
    top: Dp = 0.dp,
    right: Dp = 0.dp,
    bottom: Dp = 0.dp,
    front: Dp = 0.dp,
    back: Dp = 0.dp
): SubspaceModifier

Apply additional space along each edge of the content in Dp: left, top, right, bottom, front and back. Padding is applied before content measurement and takes precedence; content may only be as large as the remaining space.

Negative padding is not permitted — it will cause IllegalArgumentException.

fun SubspaceModifier.pointerHoverIcon(icon: SpatialPointerIcon): SubspaceModifier

When present, this modifier defines how the pointer icon will be displayed when the spatial pointer hovers over an element. Any child elements will inherit the pointer icon setting that this modifier defines for their parent element upon hovering.

fun SubspaceModifier.requiredDepth(depth: Dp): SubspaceModifier

Declare the size of the content to be exactly depth dp along the z dimension, disregarding the incoming VolumeConstraints.

This is in contrast to SubspaceModifier.depth, which respects the parent's constraints. requiredDepth will ignore the minDepth and maxDepth from the incoming constraints, which can be useful for sizing an element to a specific value even if it exceeds the parent's bounds.

fun SubspaceModifier.requiredDepthIn(
    min: Dp = Dp.Unspecified,
    max: Dp = Dp.Unspecified
): SubspaceModifier

Constrain the depth of the content to be between min dp and max dp, disregarding the incoming measurement VolumeConstraints.

This is in contrast to SubspaceModifier.depthIn, which respects the parent's constraints. requiredDepthIn will ignore the minDepth and maxDepth from the incoming constraints.

fun SubspaceModifier.requiredHeight(height: Dp): SubspaceModifier

Declare the size of the content to be exactly height dp along the y dimension, disregarding the incoming VolumeConstraints.

This is in contrast to SubspaceModifier.height, which respects the parent's constraints. requiredHeight will ignore the minHeight and maxHeight from the incoming constraints, which can be useful for sizing an element to a specific value even if it exceeds the parent's bounds.

fun SubspaceModifier.requiredHeightIn(
    min: Dp = Dp.Unspecified,
    max: Dp = Dp.Unspecified
): SubspaceModifier

Constrain the height of the content to be between min dp and max dp, disregarding the incoming measurement VolumeConstraints.

This is in contrast to SubspaceModifier.heightIn, which respects the parent's constraints. requiredHeightIn will ignore the minHeight and maxHeight from the incoming constraints.

fun SubspaceModifier.requiredSize(size: Dp): SubspaceModifier

Declare the size of the content to be exactly a size dp cube, disregarding the incoming VolumeConstraints. When applied to a Panel, the size will be a size dp square instead.

This is in contrast to SubspaceModifier.size, which respects the parent's constraints. requiredSize will ignore all min and max constraints from the incoming constraints, which can be useful for sizing an element to a specific value even if it exceeds the parent's bounds.

fun SubspaceModifier.requiredSize(size: DpVolumeSize): SubspaceModifier

Declare the size of the content to be exactly size in each of the three dimensions, disregarding the incoming VolumeConstraints. Panels have 0 depth and ignore the z-component of this modifier.

This is in contrast to SubspaceModifier.size, which respects the parent's constraints. requiredSize will ignore all min and max constraints from the incoming constraints, which can be useful for sizing an element to a specific value even if it exceeds the parent's bounds. The parent will then determine how to handle the overflow.

fun SubspaceModifier.requiredSize(
    width: Dp = Dp.Unspecified,
    height: Dp = Dp.Unspecified,
    depth: Dp = Dp.Unspecified
): SubspaceModifier

Declare the size of the content to be exactly width, height, and depth in each of the three dimensions, disregarding the incoming VolumeConstraints. Panels have 0 depth and ignore the z-component of this modifier.

This is in contrast to SubspaceModifier.size, which respects the parent's constraints. requiredSize will ignore all min and max constraints from the incoming constraints, which can be useful for sizing an element to a specific value even if it exceeds the parent's bounds. The parent will then determine how to handle the overflow.

fun SubspaceModifier.requiredSizeIn(
    minWidth: Dp = Dp.Unspecified,
    maxWidth: Dp = Dp.Unspecified,
    minHeight: Dp = Dp.Unspecified,
    maxHeight: Dp = Dp.Unspecified,
    minDepth: Dp = Dp.Unspecified,
    maxDepth: Dp = Dp.Unspecified
): SubspaceModifier

Constrain the size of the content to be between min and max dp, disregarding the incoming measurement VolumeConstraints.

This is in contrast to SubspaceModifier.sizeIn, which respects the parent's constraints. requiredSizeIn will ignore the min and max constraints from the incoming constraints, which can be useful for sizing an element to a specific range even if it exceeds the parent's bounds.

fun SubspaceModifier.requiredWidth(width: Dp): SubspaceModifier

Declare the size of the content to be exactly width dp along the x dimension, disregarding the incoming VolumeConstraints.

This is in contrast to SubspaceModifier.width, which respects the parent's constraints. requiredWidth will ignore the minWidth and maxWidth from the incoming constraints, which can be useful for sizing an element to a specific value even if it exceeds the parent's bounds.

fun SubspaceModifier.requiredWidthIn(
    min: Dp = Dp.Unspecified,
    max: Dp = Dp.Unspecified
): SubspaceModifier

Constrain the width of the content to be between min dp and max dp, disregarding the incoming measurement VolumeConstraints.

This is in contrast to SubspaceModifier.widthIn, which respects the parent's constraints. requiredWidthIn will ignore the minWidth and maxWidth from the incoming constraints.

fun SubspaceModifier.rotate(quaternion: Quaternion): SubspaceModifier

Rotate a subspace element (i.e. Panel) in space with regards to the center of the element. The rotation is directly specified by the provided Quaternion. The Quaternion values are specified as x,y,z,w. Where w is the rotation of the unit vector, in radians.

fun SubspaceModifier.rotate(axisAngle: Vector3, rotation: Float): SubspaceModifier

Rotate a subspace element (i.e. Panel) in space with regards to the center of the element. The rotation is defined by a Vector3 and a rotation angle in degrees. The axis angle will be normalized during construction. The rotation will be applied to the unit vector representing the axisAngle.

fun SubspaceModifier.rotate(pitch: Float = 0.0f, yaw: Float = 0.0f, roll: Float = 0.0f): SubspaceModifier

Rotate a subspace element (i.e. Panel) in space with regards to the center of the element. Parameter rotation angles are specified in degrees. The rotations are applied with the order pitch, then yaw, then roll. If no values are provided, no rotation is applied.

fun SubspaceModifier.scale(scale: Float): SubspaceModifier

Scale the contents of the composable by the scale factor along horizontal, vertical, and depth axes. Scaling does not change the measured size of the composable content during layout. Measured size of SubspaceComposable elements can be controlled using size Modifiers. Scale factor should be a positive number.

fun SubspaceModifier.semantics(properties: SemanticsPropertyReceiver.() -> Unit): SubspaceModifier

Add semantics key/value pairs to the layout node, for use in testing, accessibility, etc.

Based on androidx.compose.ui.semantics.SemanticsModifier.

fun SubspaceModifier.size(size: Dp): SubspaceModifier

Declare the preferred size of the content to be exactly a size dp cube. When applied to a Panel, the preferred size will be a size dp square instead.

fun SubspaceModifier.size(size: DpVolumeSize): SubspaceModifier

Declare the preferred size of the content to be exactly size in each of the three dimensions. Panels have 0 depth and ignore the z-component of this modifier.

fun SubspaceModifier.size(
    width: Dp = Dp.Unspecified,
    height: Dp = Dp.Unspecified,
    depth: Dp = Dp.Unspecified
): SubspaceModifier

Declare the preferred size of the content to be exactly width dp along the x dimensions, height dp along the y dimensions, and depth dp along the z dimension.

fun SubspaceModifier.sizeIn(
    minWidth: Dp = Dp.Unspecified,
    maxWidth: Dp = Dp.Unspecified,
    minHeight: Dp = Dp.Unspecified,
    maxHeight: Dp = Dp.Unspecified,
    minDepth: Dp = Dp.Unspecified,
    maxDepth: Dp = Dp.Unspecified
): SubspaceModifier

Constrain the size of the content to be between min and max dp as permitted by the incoming measurement constraints. If the incoming constraints are more restrictive the requested size will obey the incoming constraints and attempt to be as close as possible to the preferred size.

fun SubspaceModifier.testTag(tag: String): SubspaceModifier

Applies a tag to allow modified element to be found in tests.

This is a convenience method for a semantics that sets SemanticsPropertyReceiver.testTag.

fun SubspaceModifier.width(width: Dp): SubspaceModifier

Declare the preferred size of the content to be exactly width dp along the x dimension.

fun SubspaceModifier.widthIn(min: Dp = Dp.Unspecified, max: Dp = Dp.Unspecified): SubspaceModifier

Constrain the width of the content to be between mindp and maxdp as permitted by the incoming measurement constraints. If the incoming constraints are more restrictive the requested size will obey the incoming constraints and attempt to be as close as possible to the preferred size.

val ZeroFeatheringEffect: SpatialFeatheringEffect

An effect representing no feathering.