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 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 baseada em física(PBR) especificadas no padrão glTF 2.0 (junto com extensões compatíveis). A maioria das ferramentas de criação de conteúdo digital (DCC), como Autodesk Maya, Maxon ZBrush, Blender e Spline, pode exportar modelos 3D para o formato glTF (arquivos .gltf ou .glb).

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

Para uma visão geral rápida dos materiais compatíveis, consulte as Propriedades PBR do glTF no site da 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 seus 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, geralmente salvos como arquivos .glb. Para adicionar esses objetos ao layout, use o elemento combinável SpatialGltfModel. Essa API simplifica o processo de carregamento de recursos e gerenciamento do estado deles.

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

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

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

SpatialGltfModel(state = modelState, modifier = SubspaceModifier)

Posicionar um modelo 3D usando um Compose SceneCoreEntity

Para colocar um modelo 3D usando SceneCoreEntity, primeiro carregue o glTF na memória usando GltfModel.create(). Em seguida, coloque um modelo 3D em um SceneCoreEntity para conectar componentes do SceneCore com layouts do Compose para XR. Consulte Usar um SceneCoreEntity para colocar um objeto 3D no 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"))

Neste ponto, o modelo é carregado na memória, mas ainda não está sendo renderizado. Se você tiver muitos modelos 3D para carregar ou se o modelo for grande, é recomendável carregá-los de forma assíncrona com antecedência. Assim, os usuários não precisam esperar que seus 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, você vai ver o modelo 3D carregado ao executar o app.

Exemplo do modelo 3D carregado

Carregar um modelo 3D usando o Scene Viewer

Se você estiver procurando a maneira mais simples de carregar um modelo 3D com recursos básicos de interação, use o Scene Viewer como faria em um dispositivo móvel. Uma diferença fundamental entre o Scene Viewer no Android XR e em dispositivos móveis é que ele só aceita o parâmetro URI de arquivo que aponta para o arquivo glTF. 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 vai mais ficar visível e o Scene Viewer vai estar em foco. Todos os ambientes que você mudou serão redefinidos para as preferências do sistema do usuário.

Confira um exemplo de uso de um Intent para ver 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 Jetpack XR é compatível com várias extensões glTF que ampliam os recursos de modelos 3D. Esses recursos estão disponíveis no GltfModelEntity e no Scene Viewer.