Adicionar ambientes espaciais 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 →

No SDK do Jetpack XR, os ambientes espaciais são imersivos e podem ser adicionados ao app para personalizar o plano de fundo da cena virtual. Os ambientes espaciais só ficam visíveis quando um app está no Espaço Ampliado.

Visão geral dos ambientes espaciais

Um SpatialEnvironment gerencia as preferências de ambiente espacial de um app. É uma composição de uma imagem de skybox independente e uma geometria especificada por glTF. Só é possível definir uma imagem de skybox e um arquivo de geometria glTF por vez.

Um skybox representa a imagem que o usuário vê ao redor dele na cena virtual, criando a ilusão de um ambiente de fundo distante, como um céu, montanhas ou uma paisagem urbana. O usuário não pode interagir nem se aproximar do skybox. O SDK do Jetpack XR oferece suporte a skyboxes esféricos no padrão OpenEXR. Além de fornecer um plano de fundo imersivo para o app, um skybox EXR também oferece iluminação baseada em imagem (IBL, na sigla em inglês) para modelos 3D carregados pelo app. Para mais informações, consulte o guia para trabalhar com modelos 3D.

Os ambientes espaciais também podem incluir conteúdo de geometria 3D no padrão glTF. A geometria do ambiente carregada dessa forma será alinhada automaticamente com o chão do mundo real. A geometria do ambiente é uma ótima maneira de adicionar realismo ao ambiente usando elementos de primeiro e segundo plano que se misturam ao skybox com o efeito de paralaxe.

Nas orientações de design para ambientes espaciais, você vai aprender sobre os diferentes tipos de recursos que podem ser usados para criar ambientes espaciais e como criar ambientes espaciais seguros e agradáveis.

É possível definir o ambiente espacial do app como uma destas três configurações:

  • Uma combinação de uma imagem de skybox e uma geometria glTF.
  • Uma superfície de passagem, em que o ambiente mostrado é um feed ao vivo das câmeras externas do dispositivo. Com opacidade total, essa superfície de passagem oculta completamente o skybox e a geometria.
  • Uma configuração mista, em que a superfície de passagem não está com opacidade total nem com opacidade zero. Nesse caso, a superfície de passagem se torna semitransparente e se mistura com o skybox e a geometria atrás dela.

Recursos espaciais para ambientes espaciais

Importar e carregar recursos de ambiente espacial

Os recursos glTF e EXR para ambientes espaciais são carregados de forma assíncrona usando a classe Session.

Criar um recurso glTF

Um recurso glTF pode ser criado como um GltfModel, em que o glTF é carregado de um arquivo local. Uma GltfModel pode ser usada como parte de um ambiente de app espacial.

val environmentGeometry = GltfModel.create(session, Paths.get("DayGeometry.glb"))

Criar um recurso de iluminação baseada em imagem

Um recurso de iluminação baseada em imagem pode ser criado como um ImageBasedLightingAsset, em que a iluminação é carregada de um arquivo local. Um ImageBasedLightingAsset pode ser usado com cmgen para criar um arquivo ZIP da IBL para seus skyboxes. Consulte nosso guia sobre como otimizar recursos de ambiente para mais detalhes.

val lightingForSkybox = ImageBasedLightingAsset.createFromZip(session, Paths.get("BlueSkyboxLighting.zip"))

Definir o SpatialEnvironmentPreference para seu app

A propriedade preferredSpatialEnvironment controla o ambiente espacial preferencial de um app. Quando essa propriedade é usada para definir uma preferência, ela não causa uma mudança imediata, a menos que isPreferredSpatialEnvironmentActive já seja true. Quando o dispositivo entra em um estado em que o plano de fundo de XR pode ser mudado e o recurso SpatialCapability.APP_ENVIRONMENT está disponível, o ambiente espacial preferido do aplicativo é mostrado automaticamente.

Definir a preferência como null desativa o ambiente espacial preferido para o app, o que significa que o ambiente padrão do sistema será mostrado.

Se o SpatialEnvironmentPreference fornecido não for nulo, mas todas as propriedades forem nulas, o ambiente espacial vai consistir em uma skybox preta e nenhuma geometria.

Para receber notificações de mudanças no estado de SpatialEnvironment, use addOnSpatialEnvironmentChangedListener.

Uso básico

Esse snippet de código cria os recursos de geometria do ambiente e skybox e, em seguida, define a preferência de ambiente espacial. Essa preferência será lembrada e aplicada quando o app tiver a capacidade de definir o próprio ambiente.

val spatialEnvironmentPreference =
    SpatialEnvironment.SpatialEnvironmentPreference(lightingForSkybox, environmentGeometry)
session.scene.spatialEnvironment.preferredSpatialEnvironment = spatialEnvironmentPreference
if (session.scene.spatialEnvironment.isPreferredSpatialEnvironmentActive) {
    // The environment was successfully updated and is now visible, and any listeners
    // specified using addOnSpatialEnvironmentChangedListener will be notified.
} else {
    // The passthrough opacity preference was successfully set, but not
    // immediately visible. The passthrough opacity change will be applied
    // when the activity has the SPATIAL_CAPABILITY_APP_ENVIRONMENT capability.
    // Then, any listeners specified using addOnSpatialEnvironmentChangedListener
    // will be notified.
}

Uso avançado

Para casos de uso mais avançados em que você precisa de um controle mais preciso sobre o ambiente, é possível incorporar verificações de SpatialCapability e implementar um addOnSpatialEnvironmentChangedListener para determinar quando você quer definir a preferência de ambiente espacial.

Defina a PassthroughOpacityPreference para o ambiente espacial do seu app

Um dos componentes do plano de fundo virtual imersivo de um app é uma superfície de passagem. Nesse caso, o plano de fundo exibido é um feed ao vivo das câmeras externas do dispositivo.

setPassthroughOpacityPreference é usado para definir a opacidade de passagem preferida de um app. Esse método define apenas uma preferência e não causa uma mudança imediata, a menos que o recurso SpatialCapability.PASSTHROUGH_CONTROL esteja disponível. Quando o dispositivo entra em um estado em que a opacidade de passagem pode ser alterada e o recurso SpatialCapability.PASSTHROUGH_CONTROL está disponível, a opacidade de passagem preferencial para o aplicativo é aplicada automaticamente.

Os valores da preferência de opacidade do passthrough variam de 0.0f (opacidade zero, em que a superfície do passthrough não é visível) a 1.0f (opacidade total, em que a superfície do passthrough oculta o ambiente espacial). O parâmetro setPassthroughOpacityPreference é um float anulável. Definir o valor como nulo indica que o app não tem preferência de opacidade de passagem e vai retornar o controle de passagem para o sistema.

Uso básico

Este snippet de código define a preferência de opacidade do passthrough. Essa preferência será lembrada e aplicada quando o app tiver a capacidade de definir a opacidade do passthrough.

session.scene.spatialEnvironment.preferredPassthroughOpacity = 1.0f
if (session.scene.spatialEnvironment.currentPassthroughOpacity == 1.0f) {
    // The passthrough opacity request succeeded and should be visible now, and any listeners
    // specified using addOnPassthroughOpacityChangedListener will be notified.
} else {
    // The passthrough opacity preference was successfully set, but not
    // immediately visible. The passthrough opacity change will be applied
    // when the activity has the
    // SpatialCapabilities.SPATIAL_CAPABILITY_PASSTHROUGH_CONTROL capability.
    // Then, any listeners specified using addOnPassthroughOpacityChangedListener
    // will be notified.
}

Uso avançado

Para casos de uso mais avançados em que você precisa de um controle mais preciso sobre a opacidade do passthrough, é possível incorporar verificações de SpatialCapability e adicionar um listener usando addOnPassthroughOpacityChangedListener para determinar quando você quer definir a preferência de opacidade do passthrough.

Otimização de recursos

Ao criar recursos para definir o SpatialEnvironment dos usuários, verifique se eles têm resolução de alta qualidade e mantêm um tamanho de arquivo razoável. Para saber mais, consulte nossas orientações sobre como otimizar recursos de ambiente.

Determinar a opacidade atual do passthrough

val currentPassthroughOpacity = session.scene.spatialEnvironment.currentPassthroughOpacity

Consulte também