Adicionar modelos 3D ao app

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 →

Ao trabalhar com modelos 3D, o SDK do Jetpack XR é compatível com o padrão aberto glTF 2.0. Quando o Android XR renderiza apps criados com o SDK do Jetpack para XR, os modelos 3D são renderizados com técnicas de renderização com base física(PBR, na sigla em inglês) especificadas no padrão glTF 2.0 (com as extensões compatíveis). A maioria das ferramentas de criação de conteúdo digital (DCC, na sigla em inglês), como Autodesk Maya, Maxon ZBrush, Blender e Spline, pode exportar modelos 3D para o formato glTF (arquivos .gltf ou .glb).

Se um skybox SpatialEnvironment tiver sido especificado pelo usuário ou pelo seu app, os modelos 3D serão iluminados com as informações de iluminação fornecidas pelo skybox do ambiente. Materiais reflexivos e destaques especulares também vão refletir o skybox do ambiente. Se o passthrough estiver ativado, a iluminação, os reflexos e os destaques especulares serão baseados em uma sala iluminada com uma única luz direcional.

Para uma visão geral rápida dos materiais compatíveis, consulte as propriedades de PBR do glTF no site do Khronos. Para saber como personalizar seus modelos 3D com essas e outras propriedades, consulte Personalizar modelos 3D no seu app.

Adicionar um arquivo glTF à pasta de recursos

Depois de ter o arquivo glTF, a próxima etapa é adicioná-lo ao diretório de assets no Android Studio. Recomendamos criar um diretório models para organizar melhor os tipos de recursos.

Exemplo de adição de recursos ao diretório /models

Adicionar um objeto 3D usando SpatialGltfModel

O Android XR é compatível com o formato glTF para modelos 3D, normalmente salvos como arquivos .glb. Para adicionar esses objetos ao layout, use SpatialGltfModel. Um SpatialGltfModel é um subespaço combinável que permite adicionar modelos 3D no formato glTF ao seu layout espacial. Essa API simplifica o processo de carregamento de recursos e gerenciamento do estado deles.

Para exibir um modelo, primeiro defina a origem e o estado dele usando rememberSpatialGltfModelState. É possível carregar modelos da pasta assets do app, de um URI ou do raw data.

val modelState = rememberSpatialGltfModelState(
    source = SpatialGltfModelSource.fromPath(
        Paths.get("models/model_name.glb")
    )
)

Depois que o estado for definido, use o elemento combinável SpatialGltfModel para renderizá-lo em um subespaço:

SpatialGltfModel(state = modelState, modifier = SubspaceModifier)

Pontos principais sobre o código

  • Carregamento assíncrono: o modelo é carregado de forma assíncrona. Durante a composição inicial, o tamanho intrínseco pode ser zero. O layout é medido novamente quando o modelo está pronto.
  • Controlar o estado: use SpatialGltfModelState.status para consultar o status de carregamento ou controlar animações.
  • Dimensionamento e escalonamento: por padrão, o tamanho do layout corresponde à caixa delimitadora do recurso. É possível substituir isso por um SubspaceModifier.size para dimensionar o modelo de maneira uniforme e ajustá-lo aos limites especificados.

Colocar um modelo 3D usando uma SceneCoreEntity do Compose

Para posicionar um modelo 3D usando SceneCoreEntity, primeiro é necessário carregar o glTF na memória usando GltfModel.create(). Em seguida, coloque um modelo 3D em um SceneCoreEntity para conectar os componentes do SceneCore com os layouts do Compose para XR. Consulte Usar uma SceneCoreEntity para colocar um objeto 3D no seu layout.

Colocar um modelo 3D usando o Jetpack Scenecore

Para carregar o modelo glTF, chame GltfModel.create().

val gltfModel = GltfModel.create(session, Paths.get("models", "saturn_rings.glb"))

Nesse ponto, o modelo é carregado na memória, mas ainda não é renderizado. Se você tiver muitos modelos 3D para carregar ou se o modelo for grande, é uma boa ideia carregá-los de forma assíncrona com antecedência. Dessa forma, os usuários não precisam esperar que os modelos sejam carregados na memória.

Adicione o glTF ao ActivitySpace. Chame GltfModelEntity.create para criar uma entidade e colocá-la no ActivitySpace. Como prática recomendada, verifique se o app está em um estado que permite recursos espaciais.

if (session.scene.spatialCapabilities.contains(SpatialCapability.SPATIAL_3D_CONTENT)) {
    val gltfEntity = GltfModelEntity.create(session, gltfModel)
}

Agora, o modelo 3D carregado vai aparecer quando você executar o app.

Exemplo do modelo 3D carregado

Carregar um modelo 3D usando o Scene Viewer

Se você está procurando a maneira mais simples de carregar um modelo 3D com recursos básicos de interação, pode usar o Scene Viewer como faria em um dispositivo móvel. Uma diferença importante entre o Scene Viewer no Android XR e em dispositivos móveis é que o Scene Viewer só aceita o parâmetro de URI de arquivo que aponta para o arquivo glTF, e todos os outros parâmetros são ignorados.

O Scene Viewer é um app separado que é invocado usando uma intent e executado no Modo de Espaço Ampliado. Como resultado, quando você o invocar, seu app não ficará mais visível, e o Scene Viewer estará em foco. Todos os ambientes que você tiver alterado serão redefinidos para as preferências do sistema do usuário.

Confira um exemplo de como usar um Intent para abrir um arquivo glTF no Scene Viewer no Android XR:

val url =
    "https://raw.githubusercontent.com/KhronosGroup/glTF-Sample-Models/master/2.0/Avocado/glTF/Avocado.gltf"
val sceneViewerIntent = Intent(Intent.ACTION_VIEW)
val intentUri =
    Uri.parse("https://arvr.google.com/scene-viewer/1.2")
        .buildUpon()
        .appendQueryParameter("file", url)
        .build()
sceneViewerIntent.setData(intentUri)
try {
    startActivity(sceneViewerIntent)
} catch (e: ActivityNotFoundException) {
    // There is no activity that could handle the intent.
}

Para mais informações sobre as opções de interatividade do Scene Viewer, consulte nossa documentação de design de modelos 3D.

Extensões glTF

O SDK do Jetpack XR é compatível com várias extensões glTF que expandem os recursos de modelos 3D. Esses recursos estão disponíveis no GltfModelEntity e no Scene Viewer.