Jetpack SceneCore

Crie e manipule o gráfico de 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
7 de maio de 2025 - - - 1.0.0-alpha04

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-alpha04"
    // 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-alpha04"
}

Kotlin

dependencies {
    implementation("androidx.xr.scenecore:scenecore:1.0.0-alpha04")
    // 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-alpha04")
}

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-alpha04

7 de maio de 2025

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

Novos recursos

  • O processamento de volta agora funciona em entidades de painel sem atividades incorporadas. Para que o processamento de volta funcione, é necessário especificar android:enableOnBackInvokedCallback= "true" no manifesto do Android.
  • Agora, o StereoSurfaceEntity oferece suporte à reprodução de MV-HEVC com dois novos valores de StereoMode: MULTIVIEW_LEFT_PRIMARY e MULTIVIEW_RIGHT_PRIMARY.
  • PanelEntity.setSize e PanelEntity.getSize agora retornam tamanhos no espaço principal.
  • Entity.setPose, Entity.getPose, Entity.setScale, Entity.getScale, Entity.setAlpha e Entity.getAlpha agora usam um novo parâmetro relativeTo, que permite receber/definir valores relativos a diferentes espaços. Os valores aceitos são "Parent", "Activity" e "Real World", e o valor padrão para esse parâmetro é "Parent".
  • Métodos de extensão de callback de visibilidade espacial adicionados a SessionExt.kt para monitorar quando o conteúdo da cena se move dentro ou fora do campo de visão do usuário.
  • setPointSourceParams foi adicionado a SpatialAudioTrack, permitindo que os parâmetros sejam atualizados depois que a faixa for criada.
  • Adicionada uma nova classe, "Scene", com referências às APIs Scenecore. A cena vai estar acessível como uma propriedade de extensão da sessão. As funções dentro de SessionExt foram movidas para "Scene", então as importações precisam ser ajustadas. Por exemplo, SessionExt.getScene(session).addSpatialCapababilitiesChangedListener x SessionExt.addSpatialCapabilitiesChangedListener.
  • O ActivityPose.hitTestAsync foi adicionado, permitindo um hitTest contra conteúdo virtual.
  • Adição do novo tipo de componente SpatialPointerComponent, permitindo que os clientes especifiquem o ícone renderizado para o ponteiro ou desativem o ícone. No momento, esse componente só pode ser anexado a instâncias PanelEntity.
  • Apresentamos a nova fábrica PanelEntity, que usa dimensões de painel em metros ou pixels. Fábrica PanelEntity mais antiga que usa dois parâmetros de tipo de dimensão para o painel removido.

Mudanças na API

  • Removemos a restrição RequiresApi(34) de todos os pacotes do Jetpack XR. Essa restrição era redundante, já que o Jetpack XR está disponível apenas em dispositivos com nível 34 ou mais da API. (Iae0f8)
  • Os projetos lançados com o Kotlin 2.0 exigem o KGP 2.0.0 ou mais recente para serem consumidos (Idb6b5)
  • A turma PermissionHelper foi removida.
  • O uso de PanelEntity.getPixelDensity foi descontinuado.
  • PanelEntity.setPixelDimensions e PanelEntity.getPixelDimension foram removidos e substituídos por setSizeInPixels e getSizeInPixels.
  • Opção Entity.getActivitySpaceAlpha removida. Pode ser substituído por Entity.getAlpha(Space.Activity).
  • Opção Entity.getWorldSpaceScale removida. Pode ser substituído por Entity.getScale(Space.REAL\_WORLD).
  • A classe Session em SceneCore foi excluída em favor da sessão no XR Runtime.
  • StereoSurfaceEntity foi renomeado como SurfaceEntity
  • Entity.setSize e Entity.getSize foram removidos, e os mesmos métodos foram adicionados a PanelEntity.
  • PointSourceAttributes foi renomeado como PointSourceParams
  • SpatializerConstants.SOURCE\_TYPE\_BYPASS foi renomeado como SpatializerConstants.SOURCE\_TYPE\_DEFAULT
  • A entidade PointSourceParams foi modificada de acesso público para interno.
  • Agora, o AnchorEntity.create exige que o PlaneTrackingMode seja configurado em Session.configure().
  • As APIs SpatialUser agora exigem que HeadTrackingMode seja configurado em Session.configure().
  • Quando ResizableComponent não está anexado, ele gera um registro no nível INFO em vez de ERROR.
  • A classe Fov agora é uma classe Kotlin normal.
  • Divida Entity.kt para colocar cada tipo de entidade concreta em um arquivo próprio.
  • Ao criar uma PanelEntity, a maioria das visualizações será reassociada a uma FrameLayout. Isso facilita o uso de LayoutInspector com painéis espaciais.
  • A instância XrExtensions usada no momento está registrada na plataforma, da melhor maneira possível, para ajudar na depuração do app.

Correções de bugs

  • Foi adicionada uma correção para evitar uma falha que poderia ocorrer quando um PanelEntity com MovableComponent e AnchorPlacement era movido.
  • Foi corrigido um problema em que ResizableComponent fornecia tamanhos desatualizados no callback onResizeStart.
  • Correção de uma falha que acontecia quando o dispose() de JxrPlatformAdapterAxr era chamado várias vezes.

Versão 1.0.0-alpha03

26 de fevereiro de 2025

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

Novos recursos

  • Agora há suporte para a minimização do Proguard no código do Jetpack XR.

Correções de bugs

  • Outras correções para oferecer suporte à minificação do Proguard para o Jetpack XR SceneCore (I4f47e)
  • Atualização da regra ProGuard do Jetpack XR Scenecore para evitar AbstractMethodError em clientes minimizados. (I91a01)

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.

Próxima 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 respectivo:
    • 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 precisam 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 precisam adicionar a nova importação para 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 precisam 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() só vão entrar em vigor quando o painel for movido novamente. Para evitar isso, mova 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 de OnSpaceUpdated em ActivitySpace

Mudanças interruptivas e de comportamento

  • 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

  • Apresenta o 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. (No momento, esse parâmetro é ignorado, 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 aplicativos precisam definir CanvasShape para mudar as dimensões.
  • StereoSurfaceEntity agora permite que o StereoMode seja redefinido após a construção.

Outras mudanças

  • Redução do minSDK no tempo de compilação para 24. Todas as APIs do Jetpack XR ainda exigem a API 34 no tempo de execução.
  • A fábrica de sessões do SceneCore (Session.create) não inicia mais uma intent para adquirir a permissão SCENE_UNDERSTANDING. Em vez disso, o aplicativo cliente precisa pedir explicitamente as permissões ao 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

  • 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 certas para calcular mudanças de coordenadas quando o ActivitySpace está envolvido na origem ou no destino.
  • A skybox agora será definida como uma skybox totalmente preta sempre que uma preferência de skybox nula for transmitida usando setSpatialEnvironmentPreference(new SpatialEnvironmentPreference(null, geom)). Para reverter para a skybox e a geometria 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áficos de cena 3D para criar e manipular cenas e ambientes imersivos. Com ela, é possível posicionar e organizar modelos 3D e painéis de conteúdo em relação uns aos outros e aos ambientes virtuais ou do mundo real.

  • SpatialEnvironment: crie experiências totalmente imersivas com uma imagem de skybox e/ou geometria de modelo 3D como pano de fundo para a cena de XR do seu ambiente. Ou ative a transmissão direta para que a cena virtual possa se integrar ao ambiente real do usuário.
  • PanelEntity: adicione conteúdo 2D às suas cenas 3D incorporando layouts e atividades padrão do Android em painéis espacializados que podem flutuar ou ser ancorados em superfícies do mundo real.
  • GltfModelEntity: coloque, anime e interaja com modelos 3D na sua cena. O SceneCore é compatível com o formato de arquivo glTF para facilitar a integração com modelos atuais.
  • SpatialAudio: adicione fontes de áudio ambiente e pontual à sua cena 3D para um som totalmente imersivo e espacializado.
  • StereoSurfaceEntity: o SceneCore é compatível com o roteamento de conteúdo renderizado em uma superfície do Android para os olhos esquerdo e direito. Isso pode ser usado para renderizar conteúdo estereoscópico em um formato lado a lado ou de cima para baixo, como fotos estéreo, vídeos 3D ou outras interfaces renderizadas dinamicamente. Os aplicativos precisam usar o MediaPlayer ou o ExoPlayer para decodificação de vídeo.
  • Sistema de componentes: o SceneCore oferece um sistema de componentes robusto e flexível para adicionar recursos ao seu conteúdo de RV, incluindo affordances para que os usuários movam, redimensionem e interajam com modelos e painéis.
  • Fixação: com a transferência ativada, é possível anexar painéis e modelos a superfícies reais, oferecendo aos usuários uma integração perfeita de conteúdo virtual no ambiente do mundo real.
  • Postura do usuário: acessa a localização do usuário na cena virtual para orientar o conteúdo de acordo com a posição dele.
  • SpatialCapabilities: crie apps totalmente adaptáveis que aproveitam os recursos espacializados quando disponíveis, como o posicionamento 3D do conteúdo da interface. Além disso, o app pode monitorar mudanças nos recursos enquanto está em execução para modificar a experiência com base em como o usuário está usando o dispositivo Android XR.

Problemas conhecidos

  • No momento, é necessário um minSDK de 30 para usar o Jetpack SceneCore. Como alternativa, adicione a seguinte entrada de manifesto <uses-sdk tools:overrideLibrary="androidx.xr.scenecore, androidx.xr.compose"/> para criar e executar com um minSDK de 23.
  • A sessão pode ficar inválida em várias situações que recriam automaticamente a atividade, incluindo redimensionar um painel principal, conectar periféricos e alternar entre o modo claro e o escuro. Se você encontrar problemas de invalidação de sessão, as soluções alternativas incluem tornar seu painel principal não redimensionável, usar uma entidade de painel dinâmico, desativar a recriação de atividades para mudanças de configuração específicas ou desativar as mudanças de tema do modo claro/escuro.
  • Os componentes móveis e redimensionáveis não são compatíveis com GltfEntity.
  • Entity.getSize() não é compatível com GltfEntity.
  • Os apps do Jetpack XR precisam solicitar a permissão android.permission.SCENE_UNDERSTANDING no AndroidManifest.
  • A criação de uma sessão só é compatível com 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 a skybox como nula usando "SpatialEnvironment.setSpatialEnvironmentPreference()" não resulta em uma skybox preta sólida, conforme documentado. Isso pode resultar na skybox padrão do sistema ou em nenhuma mudança na skybox 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 api para que os clientes não precisem declará-la explicitamente.
  • O SceneCore inclui erroneamente com.google.guava:guava-31.1-android e com.google.protobuf:protobuf-javalite como dependências transitivas. Se isso resultar em erros de classe duplicados no seu 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 quando você criar uma sessão. Como solução alternativa, desative o ProGuard. Consulte este guia para mais informações sobre como ativar o ProGuard.