Adicionar ambientes espaciais ao app

No SDK do Jetpack XR, os ambientes espaciais são ambientes 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 aberto.

Visão geral dos ambientes espaciais

Um SpatialEnvironment é usado para gerenciar as preferências do ambiente espacial de um app. É um composto de uma imagem de skybox independente e uma geometria especificada pelo 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 plano de fundo distante, como um céu, montanhas ou uma paisagem urbana. O usuário não pode interagir com o skybox nem se aproximar dele. O SDK Jetpack XR oferece suporte a skyboxes esféricas no padrão OpenEXR. Além de fornecer um plano de fundo imersivo para o app, uma skybox EXR também fornece iluminação baseada em imagens (IBL, na sigla em inglês) a 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á automaticamente alinhada ao piso 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.

No guia de design para ambientes espaciais, você pode saber mais 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 em 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 exibido é um feed ao vivo das câmeras externas do dispositivo. Com opacidade total, essa superfície de passagem oculta completamente a caixa do céu 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 fica semitransparente, e o alfa se mistura com o skybox e a geometria por trá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 environmentGeometryFuture = GltfModel.create(session, "DayGeometry.glb")
val environmentGeometry = environmentGeometryFuture.await()
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 o cmgen para criar um arquivo ZIP do IBL para seus skyboxes. Consulte nosso guia sobre como otimizar os recursos do ambiente para mais detalhes.

val lightingForSkybox = ExrImage.create(session, "BlueSkyboxLighting.zip")
Environments.kt

Definir a SpatialEnvironmentPreference para seu app

setSpatialEnvironmentPreference é usado para definir o ambiente espacial preferencial de um app. Esse método define apenas uma preferência e não causa uma mudança imediata, a menos que isSpatialEnvironmentPreferenceActive já esteja ativado. Quando o dispositivo entra em um estado em que o plano de fundo do XR pode ser alterado e o recurso SpatialCapabilities.SPATIAL_CAPABILITY_APP_ENVIRONMENT está disponível, o ambiente espacial preferencial para o aplicativo é exibido automaticamente.

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

Se o SpatialEnvironmentPreference fornecido não for nulo, mas todas as propriedades forem nulas, o ambiente espacial 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)
val preferenceResult =
    session.scene.spatialEnvironment.setSpatialEnvironmentPreference(spatialEnvironmentPreference)
if (preferenceResult == SpatialEnvironment.SetSpatialEnvironmentPreferenceChangeApplied()) {
    // The environment was successfully updated and is now visible, and any listeners
    // specified using addOnSpatialEnvironmentChangedListener will be notified.
} else if (preferenceResult == SpatialEnvironment.SetSpatialEnvironmentPreferenceChangePending()) {
    // The environment is in the process of being updated. Once visible, 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 mais controle 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.

Definir 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 preferencial 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 passagem pode ser alterada e o recurso SpatialCapabilities.SPATIAL_CAPABILITY_PASSTHROUGH_CONTROL está disponível, a opacidade de passagem preferida para o aplicativo é aplicada automaticamente.

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

Uso básico

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

val preferenceResult = session.scene.spatialEnvironment.setPassthroughOpacityPreference(1.0f)
if (preferenceResult == SpatialEnvironment.SetPassthroughOpacityPreferenceChangeApplied()) {
    // The passthrough opacity request succeeded and should be visible now, and any listeners
    // specified using addOnPassthroughOpacityChangedListener will be notified
} else if (preferenceResult == SpatialEnvironment.SetPassthroughOpacityPreferenceChangePending()) {
    // 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 passagem, incorpore verificações de SpatialCapabilities e adicione um listener usando addOnPassthroughOpacityChangedListener para determinar quando você quer definir a preferência de opacidade de passagem.

Otimização de recursos

Ao criar recursos para definir o SpatialEnvironment dos usuários, verifique se os recursos alcançam uma resolução de alta qualidade, mantendo um tamanho de arquivo razoável. Para saber mais, consulte nossas orientações sobre como otimizar os recursos do ambiente.

Determinar a opacidade de passagem atual

val currentPassthroughOpacity = session.scene.spatialEnvironment.getCurrentPassthroughOpacity()
Environments.kt

Veja também