Add a subspace to your app

A subspace is a partition of 3D space within your app where you can place 3D models, build 3D layouts, and add depth to otherwise 2D content. A subspace is rendered only when spatialization is enabled. In Home Space or on non-XR devices, any code within that subspace is ignored.

You can use @SubspaceComposables such as Volume and SpatialPanel for placing 3D models. Some XR components such as Orbiters or SpatialDialogs are standard 2D composables that can be used anywhere in your 2D UI hierarchy, but SubspaceComposables must be invoked in your app's subspace. To do this, you'll use the Subspace composable.

As with any other composable, you can call Subspace directly in your 2D UI hierarchy. However, it's important to be aware of the implications of where in the hierarchy you invoke Subspace.

About subspace hierarchies

The top-level subspace is the outermost subspace invoked by your app. This subspace has effectively infinite bounds, and it's typically where you'll place your app's spatial layout and SpatialPanel.

However, if you nest another subspace inside of a 2D UI hierarchy in a panel that's contained in the top-level subspace, that nested subspace behaves differently.

Nested subspaces have two key differences from top-level Subspace:

• They participate in the 2D layout in which they are invoked. This means that the height and width of the subspace will be constrained by the height and width of its 2D parent layout.
• They behave as children of the entity they're invoked in. This means that, if you call a Subspace composable nested inside of a SpatialPanel, that subspace will be a child of the SpatialPanel it's called in.

These behaviors of nested subspace enable capabilities such as:

• Moving the child with the parent entity
• Offsetting the location of the child using the offset SubspaceModifier
• Presenting a 3D object that hovers above your 2D UI and matches the height and width of the appropriate space in the 2D layout

Add a subspace to your app

The following code example shows how to add top-level and nested subspaces to your app.

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    enableEdgeToEdge()
    setContent {
        // This is a top-level subspace
        Subspace {
            SpatialPanel {
                MyComposable()
            }
        }
    }
}
@Composable
private fun MyComposable() {
    Row {
        PrimaryPane()
        SecondaryPane()
    }
}
@Composable
private fun PrimaryPane() {
      ...
    // This is a nested subspace, because PrimaryPane is in a SpatialPanel
    // and that SpatialPanel is in a top-level Subspace
    Subspace {
        ObjectInAVolume(show3DObject)
    }
      ...
}