Aggiungere modelli 3D all'app

Dispositivi XR applicabili
Queste indicazioni ti aiutano a creare esperienze per questi tipi di dispositivi XR.
Scopri di più sui tipi di dispositivi XR →
Visori XR
Occhiali XR con cavo
Scopri di più sui tipi di dispositivi XR →

Quando si lavora con modelli 3D, l'SDK Jetpack XR supporta lo standard aperto glTF 2.0. Quando Android XR esegue il rendering delle app create con l'SDK Jetpack XR, i modelli 3D vengono visualizzati con le tecniche di rendering basato sulla fisica(PBR) specificate nello standard glTF 2.0 (insieme alle estensioni supportate). La maggior parte degli strumenti di creazione di contenuti digitali (DCC), come Autodesk Maya, Maxon ZBrush, Blender e Spline, può esportare modelli 3D nel formato glTF (file .gltf o .glb).

Se l'utente o la tua app hanno specificato uno skybox SpatialEnvironment, i modelli 3D verranno illuminati con le informazioni sull'illuminazione fornite dallo skybox dell'ambiente. Anche i materiali riflettenti e i riflessi speculari rifletteranno lo skybox dell'ambiente. Se il passthrough è stato attivato, l'illuminazione, i riflessi e i riflessi speculari si baseranno su una stanza luminosa con una singola luce direzionale.

Per una rapida panoramica dei materiali supportati, consulta le proprietà glTF PBR sul sito di Khronos. Per scoprire come personalizzare i modelli 3D con queste e altre proprietà, consulta Personalizza i modelli 3D nella tua app.

Aggiungi un file glTF alla cartella degli asset

Una volta ottenuto il file glTF, il passaggio successivo consiste nell'aggiungerlo alla directory degli asset in Android Studio. Ti consigliamo di creare una directory models per organizzare meglio i tipi di asset.

Esempio di aggiunta di asset alla directory /models

Aggiungi un oggetto 3D utilizzando SpatialGltfModel

Android XR supporta il formato glTF per i modelli 3D, in genere salvati come file .glb. Per aggiungere questi oggetti al layout, utilizza SpatialGltfModel. Un SpatialGltfModel è un composable di sottospazio che ti consente di aggiungere modelli 3D in formato glTF al tuo layout spaziale. Questa API semplifica il processo di caricamento degli asset e di gestione del loro stato.

Per visualizzare un modello, definisci prima la sua origine e il suo stato utilizzando rememberSpatialGltfModelState. Puoi caricare i modelli dalla cartella assets della tua app, da un URI o da raw data.

val modelState = rememberSpatialGltfModelState(
    source = SpatialGltfModelSource.fromPath(
        Paths.get("models/model_name.glb")
    )
)

Una volta definito lo stato, utilizza il composable SpatialGltfModel per eseguirne il rendering all'interno di un sottospazio:

SpatialGltfModel(state = modelState, modifier = SubspaceModifier)

Punti chiave sul codice

  • Caricamento asincrono: il modello viene caricato in modo asincrono. Durante la composizione iniziale, le sue dimensioni intrinseche potrebbero essere pari a zero; il layout viene ricalcolato una volta che il modello è pronto.
  • Controllo dello stato: utilizza SpatialGltfModelState.status per eseguire query sullo stato di caricamento o per controllare le animazioni.
  • Dimensionamento e scalabilità: per impostazione predefinita, le dimensioni del layout corrispondono al riquadro di delimitazione dell'asset. Puoi eseguire l'override di questa impostazione con un SubspaceModifier.size per scalare il modello in modo uniforme e adattarlo ai limiti specificati.

Posiziona un modello 3D utilizzando un'entità SceneCore di Compose

Per posizionare un modello 3D utilizzando SceneCoreEntity, devi prima caricare il glTF in memoria utilizzando GltfModel.create(). Puoi quindi inserire un modello 3D in un SceneCoreEntity per collegare i componenti SceneCore ai layout di Compose for XR. Consulta Utilizza un oggetto SceneCoreEntity per posizionare un oggetto 3D nel layout.

Posiziona un modello 3D utilizzando Jetpack Scenecore

Per caricare il modello glTF, chiama GltfModel.create().

val gltfModel = GltfModel.create(session, Paths.get("models", "saturn_rings.glb"))

A questo punto, il modello viene caricato in memoria, ma non viene ancora visualizzato. Se hai molti modelli 3D da caricare o se il tuo modello è di grandi dimensioni, è consigliabile caricarli in modo asincrono in anticipo. In questo modo, gli utenti non devono attendere che i modelli vengano caricati in memoria.

Aggiungi il file glTF a ActivitySpace. Chiama GltfModelEntity.create per creare un'entità e posizionarla in ActivitySpace. Come best practice, devi verificare che l'app sia in uno stato che consente le funzionalità spaziali.

if (session.scene.spatialCapabilities.contains(SpatialCapability.SPATIAL_3D_CONTENT)) {
    val gltfEntity = GltfModelEntity.create(session, gltfModel)
}

Ora dovresti vedere il modello 3D caricato quando esegui l'app.

Esempio del modello 3D caricato

Carica un modello 3D utilizzando Scene Viewer

Se cerchi il modo più semplice per caricare un modello 3D con funzionalità di interazione di base, puoi scegliere di utilizzare Scene Viewer come faresti su dispositivi mobili. Una differenza fondamentale tra Scene Viewer su Android XR e su dispositivi mobili è che Scene Viewer supporta solo il parametro URI del file che punta al file glTF e tutti gli altri parametri vengono ignorati.

Scene Viewer è un'app separata che viene richiamata utilizzando un intent e viene eseguita in modalità spazio intero. Di conseguenza, quando lo richiami, la tua app non sarà più visibile e Scene Viewer sarà attivo. Tutti gli ambienti che potresti aver modificato verranno reimpostati in base alle preferenze di sistema dell'utente.

Ecco un esempio di utilizzo di un Intent per visualizzare un file glTF in Scene Viewer su Android XR:

val url =
    "https://raw.githubusercontent.com/KhronosGroup/glTF-Sample-Models/master/2.0/Avocado/glTF/Avocado.gltf"
val sceneViewerIntent = Intent(Intent.ACTION_VIEW)
val intentUri =
    Uri.parse("https://arvr.google.com/scene-viewer/1.2")
        .buildUpon()
        .appendQueryParameter("file", url)
        .build()
sceneViewerIntent.setData(intentUri)
try {
    startActivity(sceneViewerIntent)
} catch (e: ActivityNotFoundException) {
    // There is no activity that could handle the intent.
}

Per ulteriori informazioni sulle opzioni di interattività per Scene Viewer, consulta la nostra documentazione sulla progettazione di modelli 3D.

Estensioni glTF

L'SDK Jetpack XR supporta diverse estensioni glTF che espandono le funzionalità dei modelli 3D. Queste funzionalità sono disponibili sia tramite GltfModelEntity sia tramite Scene Viewer.