Adicionar ambientes espaciais ao app

No SDK Jetpack XR, os ambientes espaciais são imersivos que você pode adicionar ao app para personalizar o plano de fundo da cena virtual. Os ambientes espaciais só ficam visíveis quando um app está no modo de espaço ampliado.

Visão geral dos ambientes espaciais

Um SpatialEnvironment é usado para gerenciar as preferências de ambiente espacial de um app. É um composto de uma imagem independente de skybox e geometria especificada em glTF. Só é possível definir uma imagem de skybox e um arquivo de geometria glTF por vez.

Uma skybox representa a imagem que um usuário vê ao redor em uma cena virtual, criando a ilusão de um ambiente de plano de fundo distante, como um céu, montanhas ou uma paisagem urbana. O usuário não pode interagir ou se aproximar da skybox. O SDK Jetpack XR é compatível com skyboxes esféricos no padrão OpenEXR. Além de fornecer um plano de fundo imersivo para seu app, uma skybox EXR também oferece iluminação baseada em imagens (IBL) 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 plano e plano médio que se misturam à skybox com o efeito de paralaxe.

No guia de design para ambientes espaciais, você pode aprender sobre os diferentes tipos de recursos que podem ser usados para criar ambientes espaciais e como criar ambientes seguros e agradáveis.

Você pode definir o ambiente espacial do app como uma destas três configurações:

  • Uma combinação de uma imagem de skybox e geometria glTF.
  • Uma superfície de passagem, em que o ambiente exibido é uma transmissão ao vivo das câmeras externas do dispositivo. Com opacidade total, essa superfície de transparência oculta completamente a skybox e a geometria.
  • Uma configuração mista, em que a superfície de transmissão não está com opacidade total nem zero. Nesse caso, a superfície de transmissão se torna semitransparente e se mistura com a 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. Um GltfModel pode ser usado como parte de um ambiente de app espacial.

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

Criar um recurso de imagem EXR

Um recurso de imagem EXR pode ser criado como um ExrImage, em que o EXR é carregado de um arquivo local. Um ExrImage pode ser usado com cmgen para criar um arquivo ZIP da IBL para suas skyboxes. Consulte nosso guia sobre como otimizar recursos de ambiente para mais detalhes.

val lightingForSkybox = ExrImage.createFromZip(session, Paths.get("BlueSkyboxLighting.zip"))
Environments.kt

Definir o SpatialEnvironmentPreference para seu app

A propriedade preferredSpatialEnvironment controla o ambiente espacial preferido 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 RV pode ser mudado e o recurso SpatialCapabilities.SPATIAL_CAPABILITY_APP_ENVIRONMENT está disponível, o ambiente espacial preferido para o 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 especificado não for nulo, mas todas as propriedades dele forem nulas, o ambiente espacial vai consistir em um skybox preto e nenhuma geometria.

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

Uso básico

Esse snippet de código cria a geometria do ambiente e os recursos de 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.
}
Environments.kt

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 SpatialCapabilities e implementar um addOnSpatialEnvironmentChangedListener para determinar quando você quer definir a preferência de ambiente espacial.

Defina o PassthroughOpacityPreference para o ambiente espacial do seu app

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

setPassthroughOpacityPreference é usado para definir a opacidade de transmissão 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 SpatialCapabilities.SPATIAL_CAPABILITY_PASSTHROUGH_CONTROL esteja disponível. Quando o dispositivo entra em um estado em que a opacidade de transmissão pode ser alterada e o recurso SpatialCapabilities.SPATIAL_CAPABILITY_PASSTHROUGH_CONTROL está disponível, a opacidade de transmissão preferida para o aplicativo é aplicada automaticamente.

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

Uso básico

Este snippet de código define a preferência de opacidade de transmissão. Essa preferência será memorizada e aplicada quando o app tiver a capacidade de definir a opacidade de transferência.

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.
}
Environments.kt

Uso avançado

Para casos de uso mais avançados em que você precisa de um controle mais preciso sobre a opacidade de transmissão, incorpore verificações de SpatialCapabilities e adicione um listener usando addOnPassthroughOpacityChangedListener para determinar quando definir a preferência de opacidade de transmissão.

Otimização de recursos

Ao criar recursos para definir o SpatialEnvironment dos usuários, garanta que eles tenham uma resolução de alta qualidade e mantenham um tamanho de arquivo razoável. Para saber mais, consulte nossas orientações sobre como otimizar recursos de ambiente.

Determinar a opacidade de transmissão atual

val currentPassthroughOpacity = session.scene.spatialEnvironment.currentPassthroughOpacity
Environments.kt

Veja também