Primeiros passos com o Sceneform

Nesta página, explicamos os principais conceitos explorando o código no app de exemplo Hello Sceneform (link em inglês). Observação:

  • Este exemplo usa Sceneform e ARCore.

    Para usar o Sceneform sem o ARCore, siga as etapas abaixo ao ignorar a dependência do ARCore e os requisitos de permissão do CAMERA. Use SceneView no layout do app, conforme descrito em Criar a cena.

  • Este app de exemplo foi escrito como um app RA obrigatório.

    Para saber mais sobre apps RAs opcionais vs. RAs obrigatórios, consulte Como ativar o ARCore.

Para começar a usar o Sceneform no seu projeto, você precisará:

  1. Importar o plug-in do Sceneform
  2. Configurar os arquivos build.gradle do projeto
  3. Atualize seu AndroidManifest.xml
  4. Executar verificações de tempo de execução e criar uma visualização de cena
  5. Criar elementos de renderização
  6. Crie a cena

Importar o plug-in do Sceneform para o seu projeto

Depois de instalado, o plug-in do Sceneform permite importar, ver e criar recursos 3D no SDK do Sceneform para apps de RA no Android Studio. Ele exige o Android Studio versões 3.1 e mais recentes.

Para instalar o plug-in:

  1. No Android Studio, abra as configurações de Plugins:

    • Windows: Arquivo > Configurações > Plug-ins > Procurar repositórios

    • macOS: Android Studio > Preferences > Plugins

  2. Clique em Procurar repositórios e instale as Ferramentas de cena do Google (Beta).

Configurar os arquivos build.gradle do projeto

  1. Verifique se o build.gradle do projeto inclui o repositório Maven do Google.

    allprojects {
    repositories {
        google()
        …

  2. Atualize o build.gradle do app para adicionar as dependências mais recentes de UX do ARCore e do Sceneform e garantir que as configurações do projeto sejam compatíveis com as duas bibliotecas.

    android {
    …
    defaultConfig {
        // Sceneform requires minSdkVersion >= 24.
        minSdkVersion 24
        …
    }
    // Sceneform libraries use language constructs from Java 8.
    // Add these compile options if targeting minSdkVersion < 26.
    compileOptions {
        sourceCompatibility JavaVersion.VERSION_1_8
        targetCompatibility JavaVersion.VERSION_1_8
    }
}

dependencies {
    …
    // Provides ARCore Session and related resources.
    implementation 'com.google.ar:core:1.15.0'

    // Provides ArFragment, and other UX resources.
    implementation 'com.google.ar.sceneform.ux:sceneform-ux:1.15.0'

    // Alternatively, use ArSceneView without the UX dependency.
    implementation 'com.google.ar.sceneform:core:1.15.0'
}

Atualizar seu AndroidManifest.xml

Modifique AndroidManifest.xml para indicar que seu app usa o (AR opcional) ou exige (AR necessário) acesso ao ARCore e ao CAMERA:

<!-- Both "AR Optional" and "AR Required" apps require CAMERA permission. -->
<uses-permission android:name="android.permission.CAMERA" />

<!-- Sceneform requires OpenGL ES 3.0 or later. -->
<uses-feature android:glEsVersion="0x00030000" android:required="true" />

<!-- Indicates that app requires ARCore ("AR Required"). Ensures the app is
     visible only in the Google Play Store on devices that support ARCore.
     For "AR Optional" apps remove this line. -->
<uses-feature android:name="android.hardware.camera.ar" />

<application>
    …
    <!-- Indicates that app requires ARCore ("AR Required"). Causes the Google
         Play Store to download and install Google Play Services for AR along
         with the app. For an "AR Optional" app, specify "optional" instead of
         "required".
    -->
    <meta-data android:name="com.google.ar.core" android:value="required" />
</application>

Executar verificações de tempo de execução e criar uma visualização de cena

A maneira mais fácil de começar a usar o Sceneform e criar uma visualização de cena é usando um ArFragment, que gerencia automaticamente o gerenciamento de sessões do ARCore após fazer as verificações necessárias do ambiente de execução do ARCore:

  1. Verifica se uma versão compatível do Google Play Services para RA está instalada, solicitando que o usuário instale ou atualize conforme necessário.

  2. Verifica se o app tem acesso à câmera e solicita permissão ao usuário caso isso ainda não tenha sido concedido

Caso seu app precise solicitar permissões adicionais ou queira personalizar como e quando a sessão de RA é criada, você pode:

  • Crie uma subclasse de ArFragment para solicitar permissões adicionais.

  • Use ou estenda ArSceneView diretamente. Seu app precisa realizar a verificação de versão do ARCore e chamar setupSession() para criar a sessão do ARCore manualmente, conforme demonstrado no exemplo (link em inglês) do sistema solar.

Quando as verificações forem aprovadas, ArFragment criará:

  1. Um ArSceneView, acessível via getArSceneView(), que:

    • Renderiza as imagens da câmera da sessão em sua superfície

    • Renderiza uma animação de UX integrada no Sceneform que mostra aos usuários como mover o smartphone para ativar a experiência de RA.

    • Destaques detectados Planes usando o padrão PlaneRenderer

  2. Um ARCore Session, acessível via getSession()

Para usar ArFragment no seu app, adicione-o ao layout da atividade, como demonstrado em activity_ux.xml no exemplo Hello Sceneform:

<fragment android:name="com.google.ar.sceneform.ux.ArFragment"
    android:id="@+id/ux_fragment"
    android:layout_width="match_parent"
    android:layout_height="match_parent" />

Criar recursos de renderização

Um Renderable é um modelo 3D que pode ser colocado em qualquer lugar na cena e consiste em malhas, materiais e texturas.

Os renderizadores podem ser criados de:

O app de exemplo cria um elemento renderizado a partir de um arquivo de recurso andy.obj 3D. Quando esse recurso é importado, o plug-in Sceneform atualiza o app's build.gradle para aplicar o plug-in e adicionar uma entrada sceneform.asset() para o modelo importado:

apply plugin: 'com.google.ar.sceneform.plugin'

sceneform.asset('sampledata/models/andy.obj', // 'Source Asset Path' specified during import.
                'default',                    // 'Material Path' specified during import.
                'sampledata/models/andy.sfa', // '.sfa Output Path' specified during import.
                'src/main/res/raw/andy')      // '.sfb Output Path' specified during import.

O recurso res/raw/andy é usado para criar um ModelRenderable:

private ModelRenderable andyRenderable;

@Override
protected void onCreate(Bundle savedInstanceState) {
    …

    ModelRenderable.builder()
        .setSource(this, R.raw.andy)
        .build()
        .thenAccept(renderable -> andyRenderable = renderable)
        .exceptionally(
            throwable -> {
            Log.e(TAG, "Unable to load Renderable.", throwable);
            return null;
        });
}

Crie a cena

A ARSceneView tem uma Scene anexada a ela. A cena é uma estrutura de dados semelhante a uma árvore que contém Nodes que são os objetos virtuais a serem renderizados.

Aqui, o elemento Andy render é anexado diretamente ao nó raiz do cenário:

Node node = new Node();
node.setParent(arFragment.getArSceneView().getScene());
node.setRenderable(andyRenderable);

Cada nó contém todas as informações que o Sceneform precisa renderizar (incluindo posição, orientação e objeto renderizável), bem como interagir com ele (incluindo o formato de colisão e listeners de eventos).

Os nós podem ser adicionados a outros nós, formando uma relação pai-filho. Quando um nó é filho de outro, ele se move, gira e dimensiona com o pai, como o movimento dos braços quando o corpo se move. Um nó pode ter vários filhos, mas apenas um pai, formando uma estrutura semelhante a uma árvore. Essa estrutura é conhecida como o gráfico de cena.

Cada frame, o Sceneform renderiza o gráfico de cena do ponto de vista da câmera (orientado pelo rastreamento de movimento do ARCore). O app pode interagir com a cena detectando eventos de toque e gesto, executando testes de hit em nós e colocando âncoras. Para ver mais informações, consulte Criar e interagir com o cenário.