Ajouter un sous-espace à votre application

Un sous-espace est une partition d'un espace 3D au sein de votre application. Vous pouvez y placer des modèles 3D, créer des mises en page 3D et ajouter de la profondeur à des contenus qui seraient en 2D autrement. Un sous-espace n'est affiché que lorsque la spatialisation est activée. Dans l'espace Home ou sur les appareils non XR, tout code de ce sous-espace est ignoré.

Vous pouvez utiliser des composables d'espaces sous-jacents tels que Volume et SpatialPanel pour placer des modèles 3D. Certains composants XR tels que Orbiter ou SpatialDialog sont des composables 2D standards qui peuvent être utilisés n'importe où dans la hiérarchie de l'UI 2D, mais les SubspaceComposable doivent être appelés dans le sous-espace de votre application. Pour ce faire, utilisez le composable ApplicationSubspace ou le composable Subspace.

Comme son nom l'indique, le composable ApplicationSubspace doit contenir l'ensemble du contenu spatialisé de votre application. Le composable Subspace est idéal pour imbriquer une partition d'espace 3D plus profondément dans la hiérarchie d'UI existante de votre application.

Comme pour tout autre composable, vous pouvez appeler Subspace directement dans votre hiérarchie d'UI 2D. Toutefois, il est important de connaître les implications de l'endroit où vous appelez Subspace dans la hiérarchie.

À propos des hiérarchies d'espaces sous-jacents

Le sous-espace de niveau supérieur est le sous-espace le plus externe appelé par votre application. Utilisez le composable ApplicationSubspace pour votre sous-espace de niveau supérieur, mais si vous n'utilisez que le composable Subspace dans votre application, le composable Subspace le plus externe sera votre sous-espace de niveau supérieur. Par défaut, cet espace sous-jacent de niveau supérieur est limité par l'espace recommandé pour afficher une application. C'est généralement là que vous placez la mise en page spatiale et SpatialPanel de votre application. Si vous devez modifier les limites du sous-espace de niveau supérieur, transmettez un VolumeConstraints différent à votre ApplicationSubspace.

Toutefois, si vous imbriquez un autre sous-espace dans une hiérarchie d'UI 2D dans un panneau contenu dans le sous-espace de niveau supérieur, ce sous-espace imbriqué se comporte différemment.

Les sous-espaces imbriqués présentent deux différences majeures par rapport aux Subspace de niveau supérieur:

  • Ils participent à la mise en page 2D dans laquelle ils sont appelés. Cela signifie que la hauteur et la largeur du sous-espace seront limitées par la hauteur et la largeur de sa mise en page parente 2D.
  • Ils se comportent comme des enfants de l'entité dans laquelle ils sont appelés. Cela signifie que si vous appelez un composable Subspace imbriqué dans un SpatialPanel, ce sous-espace est un enfant de l'SpatialPanel dans lequel il est appelé.

Ces comportements des sous-espaces imbriqués permettent les fonctionnalités suivantes:

  • Déplacer l'enfant avec l'entité parente
  • Déplacer l'emplacement de l'enfant à l'aide du décalage SubspaceModifier
  • Présenter un objet 3D qui flotte au-dessus de votre UI 2D et qui correspond à la hauteur et à la largeur de l'espace approprié dans la mise en page 2D

Ajouter un sous-espace à votre application

L'exemple de code suivant montre comment ajouter des sous-espaces de niveau supérieur et imbriqués à votre application:

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