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 subspace composables such as Volume and SpatialPanel for placing 3D models. Some XR components such as Orbiter or SpatialDialog 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, use either the ApplicationSubspace composable or the Subspace composable.

As the name suggests, the ApplicationSubspace composable should contain all of your app's spatialized content. The Subspace composable is ideal for nesting a partition of 3D space deeper in your app's existing UI hierarchy.

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. Use the ApplicationSubspace composable for your top-level subspace, but, if you only use the Subspace composable in your app, the outermost Subspace composable will be your top-level subspace. By default, this top-level subspace is bounded by the recommended space for viewing an app, and it's typically where you place your app's spatial layout and SpatialPanel. If you need to change the bounds of the top-level subspace, pass different VolumeConstraints to your ApplicationSubspace.

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 is 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:

setContent {
    // This is a top-level subspace
    ApplicationSubspace {
        SpatialPanel {
            MyComposable()
        }
    }
}
Subspace.kt

@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(true)
    }
}
Subspace.kt