Créer avec des conteneurs spatiaux

Appareils XR concernés
Ces conseils vous aideront à créer des expériences pour ces types d'appareils XR.
En savoir plus sur les types d'appareils XR →
Casques XR
Lunettes XR filaires
En savoir plus sur les types d'appareils XR →

Les conteneurs spatiaux apportent le fenêtrage volumétrique à OpenXR. Défini par les extensions XR_EXT_spatial_container et XR_EXT_spatial_container_self_rendering dans OpenXR 1.1, un conteneur spatial est une région volumétrique 3D gérée par le système dans l'espace de l'utilisateur, où votre application affiche du contenu 3D à l'aide de couches de composition OpenXR standards.

Traditionnellement, une session OpenXR revendique un accès exclusif à l'ensemble du champ de vision de l'utilisateur. Les conteneurs spatiaux permettent à votre application d'afficher du contenu OpenXR 3D dans une boîte 3D délimitée dans l'environnement de l'utilisateur, ou de passer à tout moment à une expérience immersive plein écran non délimitée.

À propos des conteneurs spatiaux

Un conteneur spatial est une région 3D limitée ou illimitée gérée par le système Android XR et affichée par votre application OpenXR :

  • Mode délimité : votre application suggère des dimensions 3D (largeur, hauteur et profondeur en mètres), et le système alloue un cadre de délimitation 3D dans l'environnement de l'utilisateur. Votre application affiche du contenu 3D stéréo dans le volume, et le système limite le contenu affiché aux limites de la boîte 3D.
  • Mode immersif : le conteneur spatial s'étend à l'infini, ce qui permet à votre application d'occuper tout le champ de vision de l'utilisateur, comme une session OpenXR plein écran traditionnelle.
Trois conteneurs spatiaux s'exécutant simultanément en mode Full Space : un conteneur de terrain 3D orange verrouillé au sol, un modèle de canard 3D bleu avec une UI 2D associée et un conteneur d'UI 2D vert.
Figure 1. Plusieurs conteneurs spatiaux en mode Full Space : un volume de terrain 3D verrouillé au sol (à gauche), un volume de canard 3D associé à une UI 2D (au centre) et un conteneur d'UI 2D (à droite).

Comment les utilisateurs interagissent avec les conteneurs spatiaux

Le système Android XR gère les commandes de fenêtre du conteneur spatial et son emplacement dans l'espace physique, ce qui fournit un modèle d'interaction cohérent entre les applications :

  • Déplacement et repositionnement : les utilisateurs peuvent saisir la poignée système d'un conteneur spatial à l'aide de gestes de la main (comme un pincement) ou de contrôleurs de mouvement pour le repositionner dans l'espace 3D.
  • Réduire et fermer : les commandes de la fenêtre système permettent aux utilisateurs de réduire ou de fermer des conteneurs spatiaux individuels. Lorsqu'un utilisateur ferme un conteneur, le système en informe votre application afin qu'elle puisse nettoyer les ressources.
  • Verrouillage au sol avec compréhension de la scène : lorsque votre application déclare et demande l'autorisation android.permission.SCENE_UNDERSTANDING_COARSE, le système active automatiquement l'ancrage à la surface afin que les utilisateurs puissent placer et verrouiller un conteneur spatial au sol physique sans configuration supplémentaire de l'application, comme l'illustre le conteneur de terrain orange de la figure 1.
  • Interaction 3D directe : lorsqu'un conteneur est sélectionné et interactif, les utilisateurs peuvent interagir directement avec le contenu 3D à l'intérieur du volume à l'aide du suivi des mains, du regard ou de manettes 6DoF.
Un utilisateur interagit avec un canard en 3D dans un conteneur spatial bleu délimité à l'aide du suivi des mains.
Figure 2. Utilisateur interagissant avec du contenu 3D dans un conteneur spatial délimité à l'aide du suivi des mains.
  • Transition entre les modes délimité et immersif : l'utilisateur ou votre application peut faire passer un conteneur d'une boîte 3D délimitée à une vue immersive plein écran non délimitée sans redémarrer la session OpenXR.
Scène de canard en 3D après la transition d'un conteneur spatial limité à une vue immersive plein écran illimitée.
Figure 3 : Conteneur spatial après la transition du mode limité au mode immersif, remplissant le champ de vision de l'utilisateur.
  • Mode Suivi en déplacement : comme le système contrôle la position de l'espace de coordonnées de chaque conteneur spatial (xrCreateSpatialContainerSpaceEXT), les utilisateurs peuvent activer le mode Suivi à partir des commandes de la fenêtre système. Ainsi, un conteneur 3D délimité les suit automatiquement et reste dans leur champ de vision lorsqu'ils se déplacent, sans qu'aucune configuration supplémentaire ne soit requise dans votre application.

Utiliser des conteneurs spatiaux sur Android XR

Lorsque vous créez une application avec des conteneurs spatiaux, concevez votre scène en fonction des limites du conteneur, des changements d'état et du mode de fusion de l'arrière-plan.

Adapter votre contenu 3D aux limites du conteneur

En mode délimité, l'origine (0, 0, 0) de l'espace du conteneur spatial (xrCreateSpatialContainerSpaceEXT) se trouve au centre du cadre de délimitation 3D. Étant donné que le système gère la position de l'espace du conteneur dans l'environnement de l'utilisateur, votre application affiche son contenu 3D par rapport à (0, 0, 0), tandis que le système gère le repositionnement de l'utilisateur et le mode Suivi. Le système recadre toute géométrie affichée en dehors de la largeur, de la hauteur ou de la profondeur de la boîte afin que le contenu reste dans le volume qui lui est attribué.

Votre application doit écouter les événements de modification des limites de l'environnement d'exécution et redimensionner ou repositionner votre scène 3D afin que le contenu clé tienne dans les dimensions actuelles du conteneur. Lorsque le conteneur passe en mode immersif, les limites deviennent infinies et vous pouvez restaurer votre scène à l'échelle réelle 1:1.

Répondre aux changements d'état du conteneur

Au lieu de gérer la visibilité et la sélection uniquement au niveau de l'application, chaque conteneur spatial signale son propre état afin que votre application puisse réagir en conséquence :

  • Visibilité : indique si le conteneur est actuellement affiché ou masqué. Mettez en pause les animations, l'audio ou les mises à jour de simulation lorsque le conteneur est masqué. Votre application peut également demander à afficher ou à masquer un conteneur.
  • Interactivité : indique si le conteneur est sélectionné et reçoit des entrées utilisateur provenant du suivi des mains, des manettes ou du regard. Activez ou désactivez les mises en surbrillance interactives et la gestion des entrées lorsque la sélection change.
  • Mode de délimitation : indique si le conteneur est actuellement en mode XR_SPATIAL_CONTAINER_BOUNDS_MODE_BOUNDED_EXT (limité à une boîte 3D) ou XR_SPATIAL_CONTAINER_BOUNDS_MODE_IMMERSIVE_EXT (plein écran non limité). Mettez à jour l'échelle de votre scène et activez/désactivez les éléments visuels de l'environnement (comme les skybox ou le passthrough) lorsque le mode change. Votre application peut également demander des transitions entre les modes délimité et immersif à tout moment.

Utiliser la transparence alpha-blended en mode limité

En mode délimité, un arrière-plan transparent permet à l'environnement physique de l'utilisateur et aux autres fenêtres de rester visibles autour de vos modèles 3D. Configurez votre caméra ou votre fenêtre d'affichage avec un arrière-plan transparent et utilisez le mode de fusion d'environnement alpha-blend. Lorsque vous passez en mode immersif, vous pouvez soit laisser le passthrough activé, soit passer à un environnement skybox opaque.

Vérifier la disponibilité des fonctionnalités et configurer votre fichier manifeste

Les conteneurs spatiaux nécessitent un appareil Android XR compatible avec l'API spatiale de niveau 4 ou supérieur. Plutôt que de vérifier directement le niveau d'API Android, interrogez l'environnement d'exécution OpenXR pour déterminer si les conteneurs spatiaux sont compatibles en appelant xrEnumerateInstanceExtensionProperties pour vérifier que XR_EXT_spatial_container et XR_EXT_spatial_container_self_rendering sont disponibles, et en appelant xrGetSystemProperties avec XrSystemSpatialContainerPropertiesEXT pour inspecter supportsBounded et supportsImmersive.

Avant de créer une application qui utilise des conteneurs spatiaux, configurez le mode de démarrage de votre activité et les autorisations spécifiques aux fonctionnalités dans AndroidManifest.xml.

Activer le mode Full Space dans AndroidManifest.xml

Les conteneurs spatiaux nécessitent le mode Full Space géré, même pour les applications OpenXR autonomes. Les applications OpenXR plein écran traditionnelles déclarent XR_ACTIVITY_START_MODE_FULL_SPACE_UNMANAGED pour prendre le contrôle exclusif de l'affichage sans gestion des fenêtres système. En revanche, une application utilisant des conteneurs spatiaux s'appuie sur le compositeur système Android XR pour gérer les volumes délimités en 3D, les commandes de fenêtre et l'emplacement spatial en mode Full Space. Elle doit définir android.window.PROPERTY_XR_ACTIVITY_START_MODE sur XR_ACTIVITY_START_MODE_FULL_SPACE_MANAGED :

<manifest xmlns:android="http://schemas.android.com/apk/res/android">
    <application ...>
        <!-- Spatial Containers require Full Space Managed mode -->
        <property
            android:name="android.window.PROPERTY_XR_ACTIVITY_START_MODE"
            android:value="XR_ACTIVITY_START_MODE_FULL_SPACE_MANAGED" />

        <activity android:name=".MainActivity" ...>
            <!-- Optional hint declaring which bounds modes the activity uses -->
            <property
                android:name="org.khronos.openxr.PROPERTY_ACTIVITY_HINT_XR_SPATIAL_CONTAINER_USED_BOUNDS_MODES"
                android:value="XR_SPATIAL_CONTAINER_BOUNDS_MODE_BOUNDED_EXT|XR_SPATIAL_CONTAINER_BOUNDS_MODE_IMMERSIVE_EXT" />
        </activity>
    </application>
</manifest>

Déclarer et demander des autorisations spécifiques à une fonctionnalité

La création et l'affichage d'un conteneur spatial de base ne nécessitent pas d'autorisations d'exécution dangereuses. Toutefois, certaines fonctionnalités nécessitent de déclarer et de demander les autorisations Android XR correspondantes :

  • Pour verrouiller et ancrer un conteneur spatial au sol physique à l'aide de la compréhension de la scène, déclarez et demandez l'autorisation dangereuse android.permission.SCENE_UNDERSTANDING_COARSE au moment de l'exécution.
  • Pour suivre la position de la tête de l'utilisateur dans OpenXR, déclarez et demandez android.permission.HEAD_TRACKING.
<uses-permission android:name="android.permission.HEAD_TRACKING" />
<uses-permission android:name="android.permission.SCENE_UNDERSTANDING_COARSE" />

Pour en savoir plus sur la déclaration et la demande d'autorisations XR dangereuses au moment de l'exécution, consultez Comprendre les autorisations pour la réalité XR.

Activer les conteneurs spatiaux dans votre projet

Vous pouvez créer des conteneurs spatiaux à l'aide d'Unity, de Godot ou directement avec OpenXR en C++. Sélectionnez un onglet pour afficher les conditions préalables, la configuration de l'éditeur et un exemple de code pour l'environnement de votre choix :

Unity

Conditions préalables

Configurer votre projet

  1. Accédez à Edit > Project Settings > XR Plug-in Management > OpenXR (Modifier > Paramètres du projet > Gestion des plug-ins XR > OpenXR).
  2. Cliquez sur Paramètres à côté de Android XR (Extensions): Session Management (Android XR (Extensions) : gestion des sessions), puis décochez Immersive XR (XR immersif).
  3. Dans la liste OpenXR Feature Groups (Groupes de fonctionnalités OpenXR), activez Spatial Container (Conteneur spatial).

Utilisez XRSpatialContainerFeature en C# pour interroger les limites, répondre aux événements de conteneur et basculer entre les modes limité et immersif :

void OnEnable()
{
    XRSpatialContainerFeature.OnSpatialContainerBoundsChanged += OnBoundsChanged;
}

private void OnBoundsChanged(Vector3 bounds, bool infiniteBounds)
{
    float minScale = Mathf.Min(bounds.x, bounds.y, bounds.z);
    transform.localScale = infiniteBounds ? Vector3.one : Vector3.one * minScale;
}

public void SetImmersiveMode(bool immersive)
{
    XRSpatialContainerFeature.TryRequestBoundsMode(immersive);
}

Pour connaître la procédure complète de configuration du projet, de configuration du fichier manifeste et de gestion des autorisations, consultez Utiliser des conteneurs spatiaux dans Unity.

Godot

Conditions préalables

Configurer votre projet

  1. Accédez à Project > Project Settings (Projet > Paramètres du projet), activez Advanced Settings (Paramètres avancés), puis accédez à General > XR > OpenXR > Extensions (Général > XR > OpenXR > Extensions).
  2. Dans la sous-section Conteneur spatial, sélectionnez Activé, puis configurez Mode de limites et Limites.
  3. Accédez à Project > Export... > Android, puis sélectionnez Use Experimental Features (Utiliser les fonctionnalités expérimentales) sous Android XR Features (Fonctionnalités Android XR).

Utilisez le singleton OpenXRSpatialContainerExtension dans GDScript pour répondre aux changements de limites et de mode du conteneur :

func _ready() -> void:
    if OpenXRSpatialContainerExtension.is_enabled():
        OpenXRSpatialContainerExtension.spatial_container_bounds_changed.connect(
            _on_bounds_changed
        )

func _on_bounds_changed(_rid: RID, bounds: Vector3) -> void:
    scale = Vector3.ONE * min(bounds.x, bounds.y, bounds.z)

func set_immersive_mode() -> void:
    OpenXRSpatialContainerExtension.request_main_spatial_container_bounds_mode(
        OpenXRSpatialContainerState.IMMERSIVE
    )

Pour obtenir des exemples complets de paramètres de projet, d'autorisations d'exportation et de GDScript, consultez Utiliser des conteneurs spatiaux dans Godot.

OpenXR

Conditions préalables

Activez XR_EXT_spatial_container et XR_EXT_spatial_container_self_rendering lorsque vous créez votre XrInstance, puis créez et affichez votre conteneur spatial :

// 1. Enable the Spatial Container extensions during xrCreateInstance
const char* enabledExtensions[] = {
    XR_EXT_SPATIAL_CONTAINER_EXTENSION_NAME,
    XR_EXT_SPATIAL_CONTAINER_SELF_RENDERING_EXTENSION_NAME,
};

// 2. Configure and create a self-rendering spatial container
XrSpatialContainerConfigurationSelfRenderingEXT selfRenderingConfig{
    .type = XR_TYPE_SPATIAL_CONTAINER_CONFIGURATION_SELF_RENDERING_EXT,
    .next = nullptr,
    .viewConfigurationType = XR_VIEW_CONFIGURATION_TYPE_PRIMARY_STEREO,
    .suggestedBounds = {1.5f, 1.5f, 1.5f}, // Width, height, depth in meters
};

XrSpatialContainerCreateInfoEXT createInfo{
    .type = XR_TYPE_SPATIAL_CONTAINER_CREATE_INFO_EXT,
    .next = &selfRenderingConfig,
    .spatialContainerConfig =
        reinterpret_cast<const XrSpatialContainerConfigurationBaseHeaderEXT*>(
            &selfRenderingConfig),
};

XrSpatialContainerEXT spatialContainer = XR_NULL_HANDLE;
xrCreateSpatialContainerEXT(session, &createInfo, &spatialContainer);

// 3. Request bounded mode and make the container visible
xrRequestSpatialContainerBoundsModeEXT(
    spatialContainer, XR_SPATIAL_CONTAINER_BOUNDS_MODE_BOUNDED_EXT);
xrRequestSpatialContainerVisibilityEXT(spatialContainer, XR_TRUE);

Voir aussi

OpenXR™ et le logo OpenXR sont des marques appartenant à The Khronos Group Inc. et sont déposées en Chine, dans l'Union européenne, au Japon et au Royaume-Uni.