Começar a usar o OpenXR para Android XR

Dispositivos XR relevantes

Estas orientações ajudam você a criar experiências para esses tipos de dispositivos XR.

Saiba mais sobre esses dispositivos →

Headsets XR

Óculos XR com fio

Saiba mais sobre esses dispositivos →

Antes de começar a criar com extensões do OpenXR ou com um mecanismo compatível, revise a configuração do manifesto e os requisitos de permissão nas seções a seguir para garantir que o app esteja configurado para o desenvolvimento de XR.

Configurar o arquivo de manifesto do app

Assim como em outros projetos de apps Android, seu app Android XR precisa ter um arquivo AndroidManifest.xml com configurações de manifesto específicas. O arquivo de manifesto descreve informações essenciais sobre o app para as ferramentas de build do Android, para o sistema operacional Android e para o Google Play. Consulte o guia de visão geral do manifesto do app para mais informações.

Observação: embora os apps criados com Unity, Unreal Engine ou Godot para Android XR sejam criados com base no OpenXR, não é necessário adicionar a maioria desses elementos ou atributos de manifesto manualmente se você usar os plug-ins oficiais do Android XR para esses mecanismos. Os plug-ins do mecanismo e as predefinições de exportação configuram o manifesto do app com base nas configurações do projeto e do build.

Para apps diferenciados de XR, o arquivo de manifesto precisa conter os seguintes elementos e atributos:

Propriedade PROPERTY_XR_ACTIVITY_START_MODE

A propriedade android:name="android.window.PROPERTY_XR_ACTIVITY_START_MODE" permite que o sistema saiba que uma atividade precisa ser iniciada em um modo específico quando ela é iniciada.

Essa propriedade tem os seguintes valores:

• XR_ACTIVITY_START_MODE_FULL_SPACE_UNMANAGED (somente OpenXR)

XR_ACTIVITY_START_MODE_FULL_SPACE_UNMANAGED

Os apps criados com o OpenXR são iniciados no Espaço Ampliado e precisam usar o modo de início XR_ACTIVITY_START_MODE_FULL_SPACE_UNMANAGED. O Espaço Ampliado não gerenciado sinaliza ao Android XR que o app usa o OpenXR.

Observação: se você usar um dos pacotes do Android XR para Unity, seu app também será iniciado no Espaço Ampliado. No entanto, não é necessário adicionar isso ao manifesto manualmente. Os pacotes do Unity criam o manifesto do app com base nas configurações do projeto e do build.

<manifest ... >

   <application ... >
       <property
           android:name="android.window.PROPERTY_XR_ACTIVITY_START_MODE"
           android:value="XR_ACTIVITY_START_MODE_FULL_SPACE_UNMANAGED" />
       <activity
           android:name="com.example.myapp.MainActivity" ... >

           <intent-filter>
               <action android:name="android.intent.action.MAIN" />

               <category android:name="android.intent.category.LAUNCHER" />
               <category android:name="org.khronos.openxr.intent.category.IMMERSIVE_HMD" />
           </intent-filter>
       </activity>
   </application>
</manifest>

Propriedade PROPERTY_XR_BOUNDARY_TYPE_RECOMMENDED

A propriedade android:name="android.window.PROPERTY_XR_BOUNDARY_TYPE_RECOMMENDED" indica que o aplicativo precisa ser iniciado com um tipo específico de limite. Seu app precisa especificar XR_BOUNDARY_TYPE_LARGE se ele foi projetado para permitir que os usuários se movam pelo espaço físico. Especificar XR_BOUNDARY_TYPE_NO_RECOMMENDATION não fornece recomendações para o tipo de limite de segurança. Portanto, o sistema usa o tipo que já está em uso.

<manifest ... >

   <application ... >
       <property
           android:name="android.window.PROPERTY_XR_BOUNDARY_TYPE_RECOMMENDED"
           android:value="XR_BOUNDARY_TYPE_LARGE" />
   </application>
</manifest>

Propriedades do contêiner espacial

Se o app usa a extensão XR_EXT_spatial_container (introduzida no nível 4 da API Spatial) para apresentar conteúdo em volumes 3D limitados ou painéis 2D, além de visualizações imersivas completas, declare as seguintes propriedades de manifesto no nível <activity> ou <application> para fornecer dicas de inicialização ao ambiente de execução:

• org.khronos.openxr.PROPERTY_ACTIVITY_HINT_XR_SPATIAL_CONTAINER_USED_BOUNDS_MODES: especifica os modos de limites usados pela atividade, separados por |.

  Os valores válidos são:

  • "2d_panel"
  • "bounded"
  • "immersive"

• org.khronos.openxr.PROPERTY_ACTIVITY_HINT_XR_SPATIAL_CONTAINER_INITIAL_BOUNDS_MODE: especifica o modo de limites iniciais da atividade quando iniciada.

  Os valores válidos são:

  • XR_SPATIAL_CONTAINER_INITIAL_BOUNDS_MODE_BOUNDED
  • XR_SPATIAL_CONTAINER_INITIAL_BOUNDS_MODE_IMMERSIVE
  • XR_SPATIAL_CONTAINER_INITIAL_BOUNDS_MODE_UNDEFINED

Observação: essas propriedades substituem a categoria de filtro de intent <category android:name="org.khronos.openxr.intent.category.IMMERSIVE_HMD" /> ao usar XR_EXT_spatial_container.

<manifest ... >

   <application ... >
       <activity
           android:name="com.example.myapp.MainActivity" ... >
           <property
               android:name="org.khronos.openxr.PROPERTY_ACTIVITY_HINT_XR_SPATIAL_CONTAINER_USED_BOUNDS_MODES"
               android:value="bounded|immersive" />
           <property
               android:name="org.khronos.openxr.PROPERTY_ACTIVITY_HINT_XR_SPATIAL_CONTAINER_INITIAL_BOUNDS_MODE"
               android:value="XR_SPATIAL_CONTAINER_INITIAL_BOUNDS_MODE_BOUNDED" />
       </activity>
   </application>
</manifest>

<uses-native-library> OpenXR

Os aplicativos OpenXR precisam declarar o uso da biblioteca nativa do OpenXR para carregar o ambiente de execução. Sem essa declaração, o ambiente de execução não é carregado.

<manifest ... >

    <application ... >

    <uses-native-library android:name="libopenxr.google.so" android:required="false" />

       <activity
           android:name="com.example.myapp.MainActivity" ... >

           <intent-filter>
               <action android:name="android.intent.action.MAIN" />

               <category android:name="android.intent.category.LAUNCHER" />
           </intent-filter>
        </activity>
    </application>
</manifest>

Recursos do PackageManager para apps de XR

Ao distribuir apps pela Google Play Store, é possível especificar os recursos de hardware ou software necessários no manifesto do app. O elemento uses-feature permite que a Google Play Store filtre adequadamente os apps mostrados aos usuários.

Os recursos a seguir são específicos para apps diferenciados de XR.

android.software.xr.api.openxr

Os apps que segmentam a plataforma Android XR e são criados com o OpenXR ou o Unity precisam incluir esse recurso no manifesto do app com o atributo android:required definido como true.

Os apps que usam o pacote de extensões do Android XR para Unity versão 1.0.0 ou mais recente ou o Unity OpenXR: pacote do Android XR versão 0.5.0-exp.1 ou mais recente não precisam adicionar esse elemento manualmente ao manifesto do app. Esses dois pacotes vão injetar esse elemento no manifesto do app para você.

Os dispositivos podem especificar uma versão para esse recurso, que indica a versão mais recente do OpenXR com suporte no dispositivo. Os 16 bits mais altos representam o número principal, e os 16 bits mais baixos, o número secundário. Por exemplo, para especificar a versão 1.1 do OpenXR, o valor seria definido como "0x00010001".

Os apps podem usar a versão do recurso para indicar uma versão mínima do OpenXR exigida pelo app. Por exemplo, se o app exige suporte à versão 1.1 do OpenXR, declare o seguinte recurso:

<uses-feature android:name="android.software.xr.api.openxr"
    android:version="0x00010001"
    android:required="true" />

android.software.xr.api.spatial

Os apps OpenXR que exigem extensões introduzidas em uma versão da API Spatial específica do Android XR podem declarar o recurso android.software.xr.api.spatial com android:version definido como o nível mínimo exigido da API Spatial (como "1", "2", "3" ou "4"). Consulte Criar com extensões OpenXR compatíveis para verificar a versão da API Spatial necessária para cada extensão.

<!-- Indicates that the app requires Android XR Spatial API Level 4 or higher. -->
<uses-feature android:name="android.software.xr.api.spatial"
    android:version="4"
    android:required="true" />

android.hardware.xr.input.controller

Esse recurso indica que o app precisa de entrada de um controlador de movimento de alta precisão e 6DoF (graus de liberdade) para funcionar corretamente. Se o app oferece suporte a controles e não funciona sem eles, defina o valor como true. Se o app for compatível com controles, mas puder funcionar sem eles, defina-o como false.

Observação: os controles de movimento 6DoF são um par de controles de hardware, um para cada mão. Cada controle é rastreado de forma independente no espaço por seis graus de liberdade, tanto movimentos lineares quanto rotacionais. Esses controles geralmente têm vários botões físicos, incluindo um gatilho e retorno tátil.

<!-- Sets android:required to true, indicating that your app can't function on devices without controllers. -->
<uses-feature android:name="android.hardware.xr.input.controller" android:required="true" />

android.hardware.xr.input.hand_tracking

Essa flag indica que o app precisa de captura de movimentos das mãos de alta fidelidade para funcionar corretamente, incluindo posição, orientação e velocidade das articulações na mão do usuário. Se o app for compatível com a captura de movimentos das mãos e não puder funcionar sem ela, defina o valor como true. Se o app for compatível com a captura de movimentos das mãos, mas puder funcionar sem ela, defina como false.

Observação: essa flag não é necessária para detectar gestos básicos, como pinça, toque, mira e aperto.

<!-- Sets android:required to true, indicating that your app can't function on devices without hand tracking. -->
<uses-feature android:name="android.hardware.xr.input.hand_tracking" android:required="true" />

android.hardware.xr.input.eye_tracking

Essa flag indica que o app requer acompanhamento ocular de alta fidelidade para que a entrada funcione corretamente. Se o app oferece suporte ao acompanhamento ocular para entrada e não pode funcionar sem ele, defina o valor como true. Se o app aceitar o acompanhamento ocular para entrada, mas puder funcionar sem ele, defina como false.

<!-- Sets android:required to true, indicating that your app can't function on devices without eye tracking. -->
<uses-feature android:name="android.hardware.xr.input.eye_tracking" android:required="true" />

android.hardware.xr.input.face_tracking

Essa flag indica que o app requer hardware de captura de expressões faciais para funcionar corretamente. Se o app for compatível com a captura de expressões faciais e não funcionar sem ela, defina o valor como true. Se o app for compatível com a captura de expressões faciais, mas puder funcionar sem ela, defina como false.

<!-- Sets android:required to true, indicating that your app can't function on devices without face tracking. -->
<uses-feature android:name="android.hardware.xr.input.face_tracking" android:required="true" />

android.hardware.location.gps

Essa flag indica que o app usa a localização GPS precisa no dispositivo, como ao usar extensões geoespaciais do OpenXR (XR_ANDROID_geospatial e XR_ANDROID_geospatial_anchor). Defina android:required como true se o app não funcionar sem o hardware de GPS ou false se ele puder operar sem ele.

<uses-feature android:name="android.hardware.location.gps" android:required="false" />

Observação: a captura de movimentos das mãos, o acompanhamento ocular, a captura de expressões faciais, o rastreamento corporal, a compreensão de cena e a localização são recursos que envolvem privacidade e exigem que os apps solicitem permissões de execução. Consulte Noções básicas sobre permissões para XR para mais informações sobre como declarar e solicitar permissões.

Entender as permissões do OpenXR

Muitas extensões do OpenXR acessam dados do sensor e recursos que são sensíveis à privacidade. Para usar essas extensões, o app precisa declarar os elementos <uses-permission> necessários no arquivo AndroidManifest.xml e solicitar permissões perigosas no momento da execução antes de chamar as funções correspondentes do OpenXR.

<manifest ... >
    <!-- Example dangerous permissions required by specific OpenXR extensions -->
    <uses-permission android:name="android.permission.SCENE_UNDERSTANDING_COARSE" />
    <uses-permission android:name="android.permission.HAND_TRACKING" />
    ...
</manifest>

A tabela a seguir resume as permissões perigosas do Android exigidas pelas extensões do OpenXR com suporte no Android XR. Para mais detalhes sobre as permissões de XR em todos os SDKs, consulte Entender as permissões para XR.

Permissão	Recursos	Extensões do OpenXR
android.permission.EYE_TRACKING_COARSE	Pose, status e orientação dos olhos de baixa precisão (como para avatares).	XR_ANDROID_eye_tracking (xrGetCoarseTrackingEyesInfoANDROID)
android.permission.EYE_TRACKING_FINE	Acompanhamento ocular de alta precisão para seleção, entrada, interações e renderização foveada com acompanhamento ocular.	XR_ANDROID_eye_tracking (xrGetFineTrackingEyesInfoANDROID) XR_EXT_eye_gaze_interaction XR_META_foveation_eye_tracked XR_VARJO_foveated_rendering
android.permission.FACE_TRACKING	Rastreamento de formas de mesclagem facial e renderização de expressões faciais.	XR_ANDROID_face_tracking XR_ANDROID_face_tracking_data_source
android.permission.RECORD_AUDIO	Entrada de áudio para fontes de dados de captura de expressões faciais baseadas em áudio.	XR_ANDROID_face_tracking_data_source
android.permission.HAND_TRACKING	Rastreamento de poses, velocidades, estado de mira e representação de malha das articulações das mãos.	XR_ANDROID_hand_mesh XR_EXT_hand_tracking XR_FB_hand_tracking_aim XR_FB_hand_tracking_mesh
android.permission.BODY_TRACKING	Rastreamento de poses de articulações do corpo e proporções do esqueleto.	XR_ANDROID_body_tracking
android.permission.SCENE_UNDERSTANDING_COARSE	Rastreamento de plano, rastreamento de objeto, rastreamento de imagem/marcador/QR code, âncoras, persistência, raycasting em relação a rastreáveis, estimativa de luz e malhas de passagem.	XR_ANDROID_anchor_sharing_export XR_ANDROID_composition_layer_passthrough_mesh XR_ANDROID_device_anchor_persistence XR_ANDROID_light_estimation XR_ANDROID_raycast XR_ANDROID_spatial_anchor_space XR_ANDROID_spatial_component_subsumed_by XR_ANDROID_spatial_discovery_bounds XR_ANDROID_spatial_entity_bound_anchor XR_ANDROID_spatial_object_tracking XR_ANDROID_trackables XR_ANDROID_trackables_image XR_ANDROID_trackables_marker XR_ANDROID_trackables_object XR_ANDROID_trackables_qr_code XR_EXT_spatial_anchor XR_EXT_spatial_image_tracking XR_EXT_spatial_marker_tracking XR_EXT_spatial_mesh_tracking XR_EXT_spatial_object_tracking XR_EXT_spatial_persistence XR_EXT_spatial_persistence_operations XR_EXT_spatial_plane_tracking
android.permission.SCENE_UNDERSTANDING_FINE	Texturas de profundidade, malha de cena, estimativa de luz de cubemap, raycasting de profundidade e anotações espaciais.	XR_ANDROID_depth_texture XR_ANDROID_light_estimation_cubemap XR_ANDROID_scene_meshing XR_ANDROID_spatial_annotation_tracking XR_ANDROID_spatial_discovery_raycast
android.permission.ACCESS_FINE_LOCATION	Localização e orientação precisas em relação à Terra para rastreamento e âncoras geoespaciais.	XR_ANDROID_geospatial XR_ANDROID_geospatial_anchor

Próximas etapas

Agora que você terminou de configurar o manifesto do app e de analisar informações importantes, conheça as maneiras de criar com o OpenXR:

• Criar com extensões OpenXR compatíveis
• Criar com mecanismos compatíveis