# Getting started with Sceneform

This page explains key concepts by exploring the code in the [**Hello Sceneform**
sample app](https://developers.google.com/sceneform/develop/samples). Note:

- This sample uses Sceneform and ARCore.

  To use Sceneform without ARCore, follow the steps below while ignoring the
  ARCore dependency and CAMERA permission requirements. Use
  [`SceneView`](https://developers.google.com/sceneform/reference/com/google/ar/sceneform/SceneView) in
  your app's layout as described in
  [Build the Scene](https://developers.google.com/sceneform/develop/build-scene).
- This sample app is written as an *AR Required* app.

  To learn more about *AR Optional* vs. *AR Required* apps, see
  [Enabling ARCore](https://developers.google.com/ar/develop/java/enable-arcore).

> [!NOTE]
> **Note:** Sceneform currently runs on devices that support OpenGL ES 3.0 and later.

To get started with Sceneform in your project, you'll need to:

1. [Import the Sceneform plugin](https://developers.google.com/sceneform/develop/getting-started#import-sceneform-plugin)
2. [Configure your project's `build.gradle` files](https://developers.google.com/sceneform/develop/getting-started#configure-project)
3. [Update your `AndroidManifest.xml`](https://developers.google.com/sceneform/develop/getting-started#manifest)
4. [Perform runtime checks and create a scene view](https://developers.google.com/sceneform/develop/getting-started#scene-view)
5. [Create renderables](https://developers.google.com/sceneform/develop/getting-started#renderables)
6. [Build the Scene](https://developers.google.com/sceneform/develop/getting-started#scene)

## Import the Sceneform plugin into your project

Once installed, the Sceneform plugin lets you import, view, and build 3D assets
in the Sceneform SDK for AR apps in Android Studio. It requires Android Studio
versions 3.1 and above.

To install the plugin:

1. In Android Studio open the **Plugins** settings:

   - Windows: **File \> Settings \> Plugins \> Browse Repositories**

   - macOS: **Android Studio \> Preferences \> Plugins**

2. Click **Browse repositories** , and install the *Google Sceneform Tools (Beta)*.

## Configure your project's `build.gradle` files

1. Make sure your **project's** `build.gradle` includes Google's Maven
   repository:

       allprojects {
           repositories {
               google()
               ...

2. Update your **app's** `build.gradle` to add the latest ARCore and
   Sceneform UX dependencies, and ensure that your project settings are
   compatible with both libraries.

       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'
       }

## Update your `AndroidManifest.xml`

Modify your `AndroidManifest.xml` to indicate that your app uses
(*AR Optional* ) or requires (*AR Required*) ARCore and CAMERA access:

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

## Perform runtime checks and create a scene view

The easiest way to get started using Sceneform and create a scene view is by
using an
[`ArFragment`](https://developers.google.com/sceneform/reference/com/google/ar/sceneform/ux/ArFragment), which
automatically handles ARCore session management after performing necessary
ARCore runtime checks:

1. Checks whether a compatible version of
   [Google Play Services for AR](https://play.google.com/store/apps/details?id=com.google.ar.core)
   is installed, prompting the user to install or update as necessary

2. Checks whether the app has access to the camera, and asks the user for
   permission if it has not yet been granted

If your app needs to request additional permissions, or would like to customize
how and when the AR session is created, you can instead:

- Create a subclass of `ArFragment` to request additional permissions.

- Use or extend
  [`ArSceneView`](https://developers.google.com/sceneform/reference/com/google/ar/sceneform/ArSceneView)
  directly. Your app must perform the ARCore version check and call
  `setupSession()` to create the ARCore session manually, as demonstrated in the
  *Solar System* [sample](https://developers.google.com/sceneform/develop/samples).

Once the checks pass, `ArFragment` creates:

1. An [`ArSceneView`](https://developers.google.com/sceneform/reference/com/google/ar/sceneform/ArSceneView),
   accessible via
   [`getArSceneView()`](https://developers.google.com/sceneform/reference/com/google/ar/sceneform/ux/BaseArFragment#getArSceneView()),
   that:

   - Renders the camera images from the session on to its surface

   - Renders a built-in Sceneform UX animation that shows users how they should
     move their phone to activate the AR experience.

   - Highlights detected [`Planes`](https://developers.google.com/ar/reference/java/com/google/ar/core/Plane)
     using the default
     [`PlaneRenderer`](https://developers.google.com/sceneform/reference/com/google/ar/sceneform/rendering/PlaneRenderer)

2. An ARCore [`Session`](https://developers.google.com/ar/reference/java/arcore/reference/com/google/ar/core/Session),
   accessible via
   [`getSession()`](https://developers.google.com/sceneform/reference/com/google/ar/sceneform/ArSceneView#public-session-getsession-)

To use `ArFragment` in your app, add it to your activity's layout, as
demonstrated in
[`activity_ux.xml`](https://github.com/google-ar/sceneform-android-sdk/blob/v1.15.0/samples/hellosceneform/app/src/main/res/layout/activity_ux.xml)
in the **Hello Sceneform** sample:

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

## Create renderables

A [`Renderable`](https://developers.google.com/sceneform/reference/com/google/ar/sceneform/rendering/Renderable)
is a 3D model that can be placed anywhere in the scene and consists of Meshes,
Materials and Textures.

Renderables can be created from:

- [Standard Android `ViewRenderable`s](https://developers.google.com/sceneform/develop/create-renderables#create_from_android_widgets)
  are rendered as flat 2D cards in the 3D scene, while maintaining the ability
  to interact with them via touch.

- [3D asset files](https://developers.google.com/sceneform/develop/create-renderables#create_from_a_3d_asset)
  (OBJ, FBX, glTF) can be imported, converted, and previewed using the
  Android Studio plugin. For more information, see
  [Import and Preview 3D Assets](https://developers.google.com/sceneform/develop/import-assets).

- [Basic shapes and materials](https://developers.google.com/sceneform/develop/create-renderables#create_simple_shapes_at_runtime)
  can be programmatically combined to create more complicated objects at
  runtime.

The sample app creates a renderable from a 3D `andy.obj` asset file. When this
asset is imported, the
[Sceneform plugin](https://developers.google.com/sceneform/develop/import-assets) updates the
**app's** `build.gradle` to apply the plugin and add a `sceneform.asset()`
entry for the imported model:

    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.

The `res/raw/andy` resource is used to create a `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;
            });
    }

## Build the Scene

The `ARSceneView` has a
[`Scene`](https://developers.google.com/sceneform/reference/com/google/ar/sceneform/Scene) attached to it.
The scene is a tree-like data structure that holds `Node`s that are the virtual
objects to be rendered.

Here the andy renderable is attached directly to root Scene node:

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

Each node contains all the information Sceneform needs to render it
(including its position, orientation, and renderable object) as well as
interact with it (including its collision shape and event listeners).

Nodes can be added to other nodes, forming a parent-child relationship. When a
node is a child of another node, it moves, rotates, and scales with its
parent---like how your arms move when your body moves. A node can have multiple
children, but only one parent, thus forming a tree-like structure. This
structure is known as the *scene graph*.

Each frame, Sceneform renders the scene graph from the Camera's point of view
(guided by ARCore motion tracking). Your app can interact with the scene by
listening for touch and gesture events, performing
[hit tests](https://developers.google.com/sceneform/reference/com/google/ar/sceneform/Scene) against nodes,
and placing anchors. For more info, see
[Build and Interact with the Scene](https://developers.google.com/sceneform/develop/build-scene).