{ } { }

Jetpack SceneCore

Crie e manipule a cena do Android XR com conteúdo 3D.
Atualização mais recente Versão estável Versão candidata a lançamento Versão Beta Versão Alfa
12 de fevereiro de 2025 - - - 1.0.0-alpha02

Declarar dependências

Para adicionar uma dependência ao XR SceneCore, adicione o repositório Maven do Google ao seu projeto. Leia Repositório Maven do Google para ver mais informações.

Adicione as dependências dos artefatos necessários ao arquivo build.gradle do seu app ou módulo:

Groovy

dependencies {
    implementation "androidx.xr.scenecore:scenecore:1.0.0-alpha01"
    // Required for Java
    implementation "com.google.guava:listenableFuture:1.0"
    // Required for Kotlin
    implementation "org.jetbrains.kotlinx:kotlinx-coroutines-guava:1.9.0"

    // Use to write unit tests
    testImplementation "androidx.xr.scenecore:scenecore-testing:1.0.0-alpha01"
}

Kotlin

dependencies {
    implementation("androidx.xr.scenecore:scenecore:1.0.0-alpha01")
    // Required for Java
    implementation("com.google.guava:listenableFuture:1.0")
    // Required for Kotlin
    implementation("org.jetbrains.kotlinx:kotlinx-coroutines-guava:1.9.0")

    // Use to write unit tests
    testImplementation("androidx.xr.scenecore:scenecore-testing:1.0.0-alpha01")
}

Para mais informações sobre dependências, consulte Adicionar dependências de build.

Feedback

Seu feedback ajuda a melhorar o Jetpack. Avise se você descobrir novos problemas ou tiver ideias para melhorar esta biblioteca. Consulte os problemas conhecidos nesta biblioteca antes de criar um novo. Adicione seu voto a um problema clicando no botão de estrela.

Criar novo problema

Consulte a documentação do Issue Tracker para saber mais.

Versão 1.0

Versão 1.0.0-alpha02

12 de fevereiro de 2025

Lançamento de androidx.xr.scenecore:scenecore:1.0.0-alpha02 e androidx.xr.scenecore:scenecore-testing:1.0.0-alpha02. A versão 1.0.0-alpha02 contém estas confirmações.

Mudança interruptiva que afeta apps criados antes da versão 1.0.0-alpha02

  • Os métodos de fábrica foram movidos da classe Session para um método complementar em cada tipo:
    • Session.createActivityPanelEntity(Dimensions, String, Activity, Pose) foi excluído e substituído por ActivityPanelEntity.create(Session, Dimensions, String, Pose).
    • Session.createAnchorEntity(Anchor) foi excluído e substituído por AnchorEntity.create(Session, Anchor).
    • Session.createAnchorEntity(Dimensions, Int, Int, Duration) foi excluído e substituído por AnchorEntity.create(Session, Dimensions, Int, Int, Duration).
    • Session.createEntity(String, Pose) foi excluído e substituído por ContentlessEntity.create(Session, String, Pose).
    • Session.createExrImageResource(String) foi excluído e substituído por ExrImage.create(Session, String).
    • Session.createGltfEntity(GltfModel, Pose) foi excluído e substituído por GltfModelEntity.create(Session, GltfModel, Pose).
    • Session.createGltfModelResource(String) foi excluído e substituído por GltfModel.create(Session, String).
    • Session.createInteractableComponent(Executor, InputEventListener) foi excluído e substituído por InteractableComponent.create(Session, Executor, InputEventListener).
    • Session.createMovableComponent(Boolean, Boolean, Set<AnchorPlacement>, Boolean) foi excluído e substituído por MovableComponent.create(Session, Boolean, Boolean, Set<AnchorPlacement>, Boolean).
    • Session.createPanelEntity(View, Dimensions, Dimensions, String, Pose) foi excluído e substituído por PanelEntity.create(Session, View, Dimensions, Dimensions, String, Pose).
    • Session.createResizableComponent(Dimensions, Dimensions) foi excluído e substituído por ResizableComponent.create(Session, Dimensions, Dimensions).
    • Session.createStereoSurfaceEntity(Int, Dimensions, Pose) foi excluído e substituído por StereoSurface.create(Session, Int, Dimensions, Pose).
  • Os seguintes métodos descontinuados foram removidos:
    • Session.canEmbedActivityPanel(Activity) foi excluído. Use getSpatialCapabilities.hasCapabilility(SPATIAL_CAPABILITY_EMBED_ACTIVITY).
    • Session.hasSpatialCapability(Int) foi excluído. Ele foi substituído pelo uso de getSpatialCapabilities().hasCapability() como uma maneira mais compartimentada de verificar a presença de recursos espaciais, já que getSpatialCapabilities() retorna um objeto SpatialCapabilities.
    • Session.requestFullSpaceMode() foi excluído e substituído por SpatialEnvironment.requestFullSpaceMode().
    • Session.requestHomeSpaceMode() foi excluído e substituído por SpatialEnvironment.requestHomeSpaceMode().
  • Session.setFullSpaceMode(Bundle) e Session.setFullSpaceModeWithEnvironmentInherited(Bundle) foram movidos para funções de extensão. Os arquivos do desenvolvedor precisarão adicionar as novas importações para acesso:
    • import androidx.xr.scenecore.setFullSpaceMode
    • import androidx.xr.scenecore.setFullSpaceModeWithEnvironmentInherited
  • Session.setPreferredAspectRatio(Activity, Float) foi movido para uma função de extensão. Os arquivos do desenvolvedor vão precisar adicionar a nova importação para ter acesso:
    • import androidx.xr.scenecore.setPreferredAspectRatio
  • Session.getEntitiesOfType(Class<out T>) e Session.getEntityForRtEntity(RtEntity) foram movidos para funções de extensão. Os arquivos do desenvolvedor precisarão adicionar as novas importações para acesso:
    • import androidx.xr.scenecore.getEntitiesOfType
    • import androidx.xr.scenecore.getEntityForRtEntity
  • Session.unpersistAnchor(Anchor) foi excluído
  • Session.createPersistedAnchorEntity(UUID) foi excluído

Problemas conhecidos

  • PanelEntity.setCornerRadius() e ActivityPanelEntity.setCornerRadius() podem não entrar em vigor até que o painel seja movido novamente. Isso pode ser mitigado movendo o painel para a posição atual.
  • Quando BoundsChanged é chamado no ActivitySpace, alguns ActivityPoses podem não ter sido atualizados corretamente. Ele será atualizado na próxima chamada OnSpaceUpdated no ActivitySpace

Mudanças de comportamento e de interrupção

  • PanelEntity e ActivityPanelEntity terão um raio de canto padrão de 32 dp ou menor se o painel tiver uma largura ou altura menor que 32 dp

Novas APIs e recursos

  • Introdução do StereoSurface.CanvasShape, que permite a criação de telas Spherical e Hemispherical para renderizar mídia imersiva.
  • StereoSurfaceEntity.create() agora aceita um parâmetro CanvasShape. Esse parâmetro é ignorado no momento, mas será usado em uma versão futura.
  • StereoSurfaceEntity.create() não usa mais um parâmetro Dimensions. Os aplicativos precisam controlar o tamanho da tela definindo o CanvasShape.
  • StereoSurfaceEntity tem um membro CanvasShape que pode ser definido dinamicamente.
  • StereoSurfaceEntity.dimensions agora é uma propriedade somente leitura. Os apps precisam definir CanvasShape para mudar as dimensões.
  • StereoSurfaceEntity agora permite que o StereoMode seja redefinido após a construção.

Outras mudanças

  • O minSDK no tempo de compilação foi reduzido para 24. Todas as APIs Jetpack XR continuam exigindo a API 34 no momento da execução.
  • A fábrica de sessões de SceneCore (Session.create) não inicia mais uma intent para adquirir a permissão SCENE_UNDERSTANDING. Em vez disso, o aplicativo cliente precisa solicitar explicitamente as permissões do usuário antes de tentar criar as âncoras. A criação de âncoras vai falhar se a permissão não for concedida pelo usuário.

Correções de bugs

  • O getActivitySpacePose() foi corrigido para considerar a escala ActivitySpace, retornando valores de tradução em metros dimensionados em vez de sempre retornar metros não dimensionados. Agora, transformPoseTo também usa as unidades corretas para calcular mudanças de coordenadas quando o ActivitySpace está envolvido na origem ou no destino
  • O skybox agora será definido como totalmente preto sempre que uma preferência de skybox nula for transmitida usando setSpatialEnvironmentPreference(new SpatialEnvironmentPreference(null, geom)). Para reverter para a geometria e a skybox padrão do sistema, use setSpatialEnvironmentPreference(null).

Versão 1.0.0-alpha01

12 de dezembro de 2024

Lançamento de androidx.xr.scenecore:scenecore-* 1.0.0-alpha01.

Recursos da versão inicial Versão inicial para desenvolvedores do Jetpack SceneCore, uma biblioteca de gráfico de cena 3D para criar e manipular cenas e ambientes imersivos. Com essa biblioteca, você pode posicionar e organizar modelos 3D e painéis de conteúdo em relação a outros e aos seus ambientes virtuais ou reais.

  • SpatialEnvironment: crie experiências totalmente imersivas com uma imagem de skybox e/ou uma geometria de modelo 3D como plano de fundo para a cena de XR do seu ambiente. Ou ative o passthrough para que a cena virtual possa ser integrada ao ambiente real do usuário.
  • PanelEntity: adicione conteúdo 2D às suas cenas 3D incorporando layouts e atividades padrão do Android a painéis espaciais que podem flutuar ou ser ancorados a superfícies do mundo real.
  • GltfModelEntity: posicione, anime e interaja com modelos 3D na sua cena. O SceneCore oferece suporte ao formato de arquivo glTF para facilitar a integração com modelos existentes.
  • SpatialAudio: adicione fontes de áudio ambiente e pontual à sua cena 3D para um som totalmente imersivo e espacializado.
  • StereoSurfaceEntity: o SceneCore oferece suporte ao roteamento de conteúdo renderizado em uma plataforma Android para o olho esquerdo/direito. Ele pode ser usado para renderizar conteúdo estereoscópico em um formato lado a lado ou de cima para baixo, como fotos estereoscópicas, vídeos 3D ou outras interfaces renderizadas dinamicamente. Os aplicativos precisam usar o MediaPlayer ou o ExoPlayer para decodificar vídeos.
  • Sistema de componentes: o SceneCore oferece um sistema de componentes robusto e flexível para adicionar recursos ao seu conteúdo de XR, incluindo recursos para os usuários moverem, redimensionarem e interagirem com modelos e painéis.
  • Âncora: com o recurso de passagem ativado, é possível anexar painéis e modelos a superfícies reais, oferecendo aos usuários a integração perfeita de conteúdo virtual no ambiente real.
  • Pose do usuário: acesse a localização do usuário na cena virtual para orientar seu conteúdo em torno da posição dele.
  • SpatialCapabilities: crie apps totalmente adaptáveis que aproveitem os recursos espaciais quando disponíveis, como posicionamento 3D do conteúdo da interface. Além disso, o app pode monitorar mudanças nos recursos enquanto é executado para modificar a experiência com base na forma como o usuário está usando o dispositivo Android XR.

Problemas conhecidos

  • No momento, um minSDK de 30 é necessário para usar o Jetpack SceneCore. Como solução alternativa, adicione a seguinte entrada de manifesto <uses-sdk tools:overrideLibrary="androidx.xr.scenecore, androidx.xr.compose"/> para poder criar e executar com um minSDK de 23.
  • A sessão pode se tornar inválida em várias situações que recriam automaticamente a atividade, incluindo o redimensionamento de um painel principal, a conexão de periféricos e a mudança entre o modo claro e escuro. Se você encontrar problemas de invalidação de sessão, as soluções alternativas incluem tornar o painel principal não redimensionável, usar uma entidade de painel dinâmico, desativar a recriação de atividades para mudanças específicas de configuração ou desativar mudanças de tema de modo claro/escuro.
  • Componentes móveis e redimensionáveis não são compatíveis com a GltfEntity.
  • Entity.getSize() não tem suporte para GltfEntity.
  • Os apps do Jetpack XR precisavam solicitar a permissão android.permission.SCENE_UNDERSTANDING no AndroidManifest.
  • A criação de uma sessão só é possível em um dispositivo Android XR. No momento, se você criar uma sessão e tentar usá-la em um dispositivo que não seja Android XR, vai receber uma RuntimeException.
  • Definir o skybox como nulo usando "SpatialEnvironment.setSpatialEnvironmentPreference()" não resulta em um skybox preto sólido, como documentado. Isso pode resultar no céu padrão do sistema ou na ausência de mudanças no céu atual.
  • Os clientes do SceneCore precisam adicionar implementation(“com.google.guava:listenablefuture-1.0”) à configuração do Gradle para as dependências do app. Em uma versão futura, o Scenecore vai incluir essa biblioteca como uma dependência de api para que os clientes não precisem declarar isso explicitamente.
  • O SceneCore inclui com.google.guava:guava-31.1-android e com.google.protobuf:protobuf-javalite erroneamente como dependências transitivas. Se isso resultar em erros de classe duplicados no build, essas duas dependências poderão ser excluídas com segurança.
  • Se o app usar o SceneCore e ativar o ProGuard, ele vai falhar ao criar uma sessão. Como solução alternativa, desative o ProGuard. Consulte este guia para mais informações sobre como ativar o ProGuard.