{ } { }

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
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 vai funcionar em entidades de painel sem atividades incorporadas. Para que o backhandling funcione, é necessário especificar android:enableOnBackInvokedCallback= "true" no manifesto do Android.
  • Agora, 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 pai.
  • 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 em relação a diferentes espaços. Os valores aceitos são "Parent", "Activity" e "Real World", e o valor padrão para esse parâmetro é "Parent".
  • Os métodos de extensão de callback de visibilidade espacial foram 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.
  • Adição de uma nova classe, "Scene", com referências a APIs Scenecore. A cena vai ser acessível como uma propriedade de extensão da sessão. As funções dentro de SessionExt foram movidas para a cena, então as importações precisam ser ajustadas. Por exemplo, SessionExt.getScene(session).addSpatialCapababilitiesChangedListener x SessionExt.addSpatialCapabilitiesChangedListener.
  • ActivityPose.hitTestAsync foi adicionado, permitindo um hitTest contra conteúdo virtual.
  • Foi adicionado um novo tipo de componente SpatialPointerComponent, permitindo que os clientes especifiquem o ícone renderizado para o ponteiro ou o desativem. No momento, esse componente só pode ser anexado a instâncias PanelEntity.
  • Apresentação da nova fábrica PanelEntity, que usa as dimensões do painel em metros ou pixels. A fábrica PanelEntity mais antiga que usa dois parâmetros de tipo de dimensão para o painel foi removida.

Mudanças na API

  • A restrição RequiresApi(34) foi removida de todos os pacotes do Jetpack XR. Essa restrição era redundante, porque o Jetpack XR só está disponível em dispositivos com nível 34 da API ou mais recente. (Iae0f8)
  • Os projetos lançados com o Kotlin 2.0 exigem o KGP 2.0.0 ou mais recente para serem consumidos (Idb6b5).
  • A classe 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 ambiente de execução do XR.
  • 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 acesso interno.
  • AnchorEntity.create agora exige que 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 um registro no nível ERROR.
  • A classe Fov agora é uma classe Kotlin regular.
  • Divida Entity.kt para colocar cada tipo de entidade concreto no próprio arquivo.
  • Ao criar um novo PanelEntity, a maioria das visualizações será reclassificada como FrameLayout. Isso facilita o uso de LayoutInspector com painéis espaciais.
  • A instância XrExtensions usada atualmente agora é registrada na plataforma, de maneira otimizada, para ajudar no processo de depuração do app.

Correções de bugs

  • Uma correção foi adicionada para evitar uma falha que podia ocorrer quando um PanelEntity com MovableComponent e AnchorPlacement era movido
  • Correção de um problema em que ResizableComponent fornecia tamanhos desatualizados no callback onResizeStart.
  • Correção de uma falha que acontecia quando 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

  • A minificação do Proguard agora tem suporte ao código Jetpack XR

Correções de bugs

  • Correções adicionais para oferecer suporte à minificação do Proguard para o Jetpack XR SceneCore (I4f47e).
  • Atualizamos a regra ProGuard do Jetpack XR Scenecore para evitar AbstractMethodError em clientes minificados. (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.

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 precisarão 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 do 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 em 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 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 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 não mudar o 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 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.