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 tipos de dispositivos XR →
Headsets XR
Óculos XR com fio
Saiba mais sobre tipos de dispositivos XR →

No SDK do Jetpack XR, os ambientes espaciais são espaços imersivos que 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. Ele é composto por uma imagem de skybox independente e uma 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 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 a skybox nem se aproximar dela. O SDK do 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 oferece iluminação baseada em imagem (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 glTF padrão. A geometria do ambiente carregada dessa forma será alinhada automaticamente ao 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 à 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 espaciais seguros e agradáveis.

É possível definir o ambiente espacial do app para 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 passagem oclui completamente a skybox e a geometria.
  • Uma configuração mista, em que a superfície de passagem não está com opacidade total nem zero. Nesse caso, a superfície de passagem 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 por usando a Session classe.

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"))

Criar um recurso de iluminação baseado em imagem

Um recurso de iluminação baseado 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 do IBL para suas skyboxes. Consulte nosso guia sobre como otimizar recursos de ambiente para mais detalhes.

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

Definir a 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 XR pode ser alterado e o SpatialCapabilities.SPATIAL_CAPABILITY_APP_ENVIRONMENT recurso está disponível, o ambiente espacial preferido do aplicativo é exibido automaticamente.

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

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

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

Uso básico

Este snippet de código cria a geometria do ambiente e os recursos da 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 SpatialCapabilities verificações e implementar um addOnSpatialEnvironmentChangedListener para determinar quando você quer definir a preferência de ambiente espacial.

Definir a PassthroughOpacityPreference para o ambiente espacial do 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 é uma transmissão ao vivo das câmeras externas do dispositivo.

setPassthroughOpacityPreference é usado para definir a opacidade de passagem preferida de um app. Esse método só define 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 do 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 está visível) a 1.0f (opacidade total, em que a superfície de passagem 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 retornará o controle de passagem ao sistema.

Uso básico

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

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 de passagem, é possível incorporar verificações de SpatialCapabilities e adicionar 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 eles têm resolução de alta qualidade, mantendo um tamanho de arquivo razoável. Para saber mais, consulte nossas orientações sobre como otimizar recursos de ambiente.

Determinar a opacidade de passagem atual

val currentPassthroughOpacity = session.scene.spatialEnvironment.currentPassthroughOpacity

Consulte também