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`](https://developer.android.com/reference/kotlin/androidx/xr/compose/subspace/package-summary#Volume(androidx.xr.compose.subspace.layout.SubspaceModifier,kotlin.Function1)) and [`SpatialPanel`](https://developer.android.com/reference/kotlin/androidx/xr/compose/subspace/package-summary#SpatialPanel(androidx.xr.compose.subspace.layout.SubspaceModifier,androidx.xr.compose.subspace.layout.SpatialShape,kotlin.Function0))
for placing 3D models. Some XR components such as [`Orbiter`](https://developer.android.com/reference/kotlin/androidx/xr/compose/spatial/package-summary#Orbiter(androidx.xr.compose.spatial.ContentEdge.Horizontal,androidx.compose.ui.unit.Dp,androidx.xr.compose.spatial.OrbiterOffsetType,androidx.compose.ui.Alignment.Horizontal,androidx.xr.compose.subspace.layout.SpatialShape,androidx.compose.ui.unit.Dp,kotlin.Boolean,kotlin.Function0)) or
[`SpatialDialog`](https://developer.android.com/reference/kotlin/androidx/xr/compose/spatial/package-summary#SpatialDialog(kotlin.Function0,androidx.xr.compose.spatial.SpatialDialogProperties,kotlin.Function0)) are standard 2D composables that can be used anywhere in
your 2D UI hierarchy, but [`SubspaceComposable`](https://developer.android.com/reference/kotlin/androidx/xr/compose/subspace/SubspaceComposable)s must be invoked in your
app's subspace. To do this, use either the `ApplicationSubspace` composable or
the [`Subspace`](https://developer.android.com/reference/kotlin/androidx/xr/compose/spatial/package-summary#Subspace(kotlin.Function1)) composable.

As the name suggests, the [`ApplicationSubspace`](https://developer.android.com/reference/kotlin/androidx/xr/compose/spatial/package-summary#ApplicationSubspace(androidx.xr.compose.unit.VolumeConstraints,androidx.xr.compose.spatial.ConstraintsBehavior,kotlin.Function1)) composable should contain
all of your app's spatialized content. The [`Subspace`](https://developer.android.com/reference/kotlin/androidx/xr/compose/spatial/package-summary#Subspace(kotlin.Function1)) 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`](https://developer.android.com/reference/kotlin/androidx/xr/compose/spatial/package-summary#Subspace(kotlin.Function1)) directly in your 2D
UI hierarchy. However, it's important to be aware of the implications of where
in the hierarchy you invoke [`Subspace`](https://developer.android.com/reference/kotlin/androidx/xr/compose/spatial/package-summary#Subspace(kotlin.Function1)).

## About subspace hierarchies

The top-level subspace is the outermost subspace invoked by your app. Use the
[`ApplicationSubspace`](https://developer.android.com/reference/kotlin/androidx/xr/compose/spatial/package-summary#ApplicationSubspace(androidx.xr.compose.unit.VolumeConstraints,androidx.xr.compose.spatial.ConstraintsBehavior,kotlin.Function1)) 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`](https://developer.android.com/reference/kotlin/androidx/xr/compose/subspace/package-summary#SpatialPanel(androidx.xr.compose.subspace.layout.SubspaceModifier,androidx.xr.compose.subspace.layout.SpatialShape,kotlin.Function0)). If you need to
change the bounds of the top-level subspace, pass different
[`VolumeConstraints`](https://developer.android.com/reference/kotlin/androidx/xr/compose/unit/VolumeConstraints) to your [`ApplicationSubspace`](https://developer.android.com/reference/kotlin/androidx/xr/compose/spatial/package-summary#ApplicationSubspace(androidx.xr.compose.unit.VolumeConstraints,androidx.xr.compose.spatial.ConstraintsBehavior,kotlin.Function1)).

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`](https://developer.android.com/reference/kotlin/androidx/xr/compose/spatial/package-summary#Subspace(kotlin.Function1)):

- 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`](https://developer.android.com/reference/kotlin/androidx/xr/compose/spatial/package-summary#Subspace(kotlin.Function1)) composable nested inside of a [`SpatialPanel`](https://developer.android.com/reference/kotlin/androidx/xr/compose/subspace/package-summary#SpatialPanel(androidx.xr.compose.subspace.layout.SubspaceModifier,androidx.xr.compose.subspace.layout.SpatialShape,kotlin.Function0)), that subspace is a child of the [`SpatialPanel`](https://developer.android.com/reference/kotlin/androidx/xr/compose/subspace/package-summary#SpatialPanel(androidx.xr.compose.subspace.layout.SubspaceModifier,androidx.xr.compose.subspace.layout.SpatialShape,kotlin.Function0)) 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`](https://developer.android.com/reference/kotlin/androidx/xr/compose/subspace/layout/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:


```kotlin
setContent {
    // This is a top-level subspace
    ApplicationSubspace {
        SpatialPanel {
            MyComposable()
        }
    }
}https://github.com/android/snippets/blob/2f246fb3f712172fefe2e1761f3483568348bf90/xr/src/main/java/com/example/xr/compose/Subspace.kt#L34-L41
```

<br />


```kotlin
@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)
    }
}https://github.com/android/snippets/blob/2f246fb3f712172fefe2e1761f3483568348bf90/xr/src/main/java/com/example/xr/compose/Subspace.kt#L47-L62
```

<br />