PlanarEmbeddedSubspace

Functions summary

Unit

Creates a 3D space for spatial content that is embedded within and positioned by a 2D container.

Functions

PlanarEmbeddedSubspace

@Composable
@UiComposable
fun PlanarEmbeddedSubspace(content: @Composable @SubspaceComposable SpatialBoxScope.() -> Unit): Unit

Creates a 3D space for spatial content that is embedded within and positioned by a 2D container.

A PlanarEmbeddedSubspace acts as a bridge between a 2D layout context and a 3D spatial scene. It must be placed within a composable that provides a 2D surface in the 3D world, such as SpatialPanel, Orbiter, or a custom component built on similar principles.

The PlanarEmbeddedSubspace itself is laid out like a regular 2D composable, respecting the constraints and positioning of its parent. The 3D content placed inside it is then positioned relative to this 2D-defined area.

Key behaviors:

  • Layout: The width and height are determined by the parent 2D layout. The depth (Z-axis) constraints are inherited from the surrounding spatial environment, allowing content to extend forwards and backwards from the 2D surface.

  • Content: The content lambda is a @SubspaceComposable scope, where you can place 3D elements like SpatialBox.

  • Environment: This composable is a no-op and renders nothing in non-XR environments (e.g., phones and tablets).

import androidx.compose.foundation.layout.Row
import androidx.compose.material3.Text
import androidx.compose.runtime.Composable
import androidx.compose.ui.unit.dp
import androidx.xr.compose.spatial.PlanarEmbeddedSubspace
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.offset

@Composable
@SubspaceComposable
fun PanelWithPlanarEmbeddedSubspace() {
    // A PlanarEmbeddedSubspace is placed inside a SpatialPanel.
    // The 3D content inside the PlanarEmbeddedSubspace is positioned
    // relative to the 2D area of the SpatialPanel.
    // Here we place it in a Row to demonstrate that it participates in 2D layout.
    SpatialPanel {
        Row {
            Text("2D content")

            PlanarEmbeddedSubspace {
                // The content of a PlanarEmbeddedSubspace must be a SubspaceComposable.
                // Here we use another SpatialPanel to host 2D content. However,
                // this could be any 3D content (i.e. glTFs).
                SpatialPanel(SubspaceModifier.offset(z = (-50).dp)) {
                    Text("Embedded 3D content")
                }
            }
        }
    }
}
Parameters
content: @Composable @SubspaceComposable SpatialBoxScope.() -> Unit

The @SubspaceComposable 3D content to render within this subspace.
See also
Subspace

For creating a top-level, application-anchored spatial scene.