Riferimento file asset scena

Il file di definizione dell'asset di Sceneform (*.sfa) è una descrizione leggibile dell'asset binario Sceneform (*.sfb). Si riferisce ai modelli, alle definizioni dei materiali e alle texture nel tuo asset di origine e fornisce anche parametri dei materiali per i materiali basati su Sceneform.

Questo file viene generato automaticamente alla prima importazione dal plug-in Sceneform Android Studio, ma puoi modificare gli attributi per modificare l'aspetto dell'asset. Questo riferimento descrive gli attributi che puoi configurare per modificare l'aspetto degli asset. Il valore predefinito degli attributi facoltativi non presenti nel sfa. La sintassi di sfa è jsonnet, un'estensione di JSON.

Sintassi

{
   materials: [
      {
         name: "<name>",
         parameters: [
            {
               <parameterName>: <parameterDefaultValue>,
            },
            …
         ],
         source: "path/to/source_material.sfm",
      },
      …
   ],
   model: {
      attributes: [
         "Position",
         "TexCoord",
         "Orientation",
      ],
      file: "path/to/source_asset.ext",
      name: "<Name>",
      scale: 1.0,
      recenter: false,
      smoothing_angle: 45.0,
      flip_texture_coordinates: false,
      fix_infacing_normals: false,
   },
   samplers: [
      {
         file: "path/to/source_texture.ext",
         name: "<name>",
         params: {
            usage_type: "Color",
            mag_filter: "Linear",
            min_filter: "NearestMipmapLinear",
            wrap_s: "Repeat",
            wrap_t: "Repeat",
         },
         pipeline_name: "<pipeline_name>",
      },
      …
   ]
}

Attributi

materials[].parameters

I contenuti di questo blocco dipendono dalla definizione del materiale specificata dall'attributo source.

Per i materiali predefiniti (*.sfm), consulta l'elenco di parametri supportati:

Per i materiali personalizzati (*.mat), l'elenco dei parametri supportati è specificato nel file *.mat:

materials[].source
Specifica il file di definizione dei materiali: un file di definizione del materiale predefinito (*.sfm) o un file di definizione di materiale personalizzato (*.mat).
model.attributes

Definisce l'insieme di flussi di vertici esportati, calcolato durante l'importazione del modello di origine. I valori possibili sono:

Valore Descrizione
"Color" Il vertice COLOR.
"Orientation" Il vertice TANGENT.
"Position" Il vertice POSITION.
"TexCoord" TEXCOORD0, la prima coordinata UV.
model.file
L'attributo obbligatorio contiene un percorso del file system a un file di asset di origine. I formati attualmente supportati sono *.fbx, *.obj, *.gltf e *.glb.
model.scale

Attributo facoltativo, il valore predefinito è 1.0. Controlla la scalabilità del modello esportato rispetto ai contenuti dell'asset di origine. Una scala pari a 2.0 renderà la risorsa due volte più grande.

I valori di posizione delle scene devono essere specificati in metri. Per soddisfare le differenze nelle unità standard, il termine della scala viene calcolato automaticamente durante l'importazione iniziale per rendere l'asse più grande non inferiore a 5 cm e l'asse più piccolo non più grande di 1 m. Questa regola è utile per l'esperienza di importazione iniziale; questi limiti non vengono applicati.

model.recenter

Attributo facoltativo, il valore predefinito è false. Controlla il posizionamento della geometria esportata. I valori possibili sono:

Valore Descrizione
false La geometria verrà esportata come è stata creata, senza alcuna trasformazione.
true Il centro della geometria sarà posizionato all'origine.
"root" La geometria verrà esportata in modo che sia centrata orizzontalmente sull'origine e spostata in verticale in modo che i vertici più bassi siano a livello dell'origine. Può essere utilizzato per garantire che un modello esportato posizionato su un ancora o su un piano si trovi sopra a questo punto di ancoraggio.
{x:float, y:float, z:float} La geometria verrà esportata in modo tale che l'origine sia posizionata secondo il punto indicato.
{x:0, y:0, z:0} corrisponde al minimo del riquadro di delimitazione allineato all'asse della geometria.
{x:1, y:1, z:1} corrisponde al massimo del riquadro di delimitazione allineato all'asse della geometria.
model.smoothing_angle
Attributo facoltativo specificato in gradi, il valore predefinito è 45. Per le risorse di origine senza valori per vertice (ad esempio obj) verranno generate normali per vertice generate tramite smoothing_angle per limitare l'insieme di valori normali usati nel calcolo di una normale vertice. I bordi del modello che superano questo angolo appariranno "rigidi" o, per i facet, i bordi che non superano l'aspetto appariranno levigati.
model.flip_texture_coordinates
Attributo facoltativo, il valore predefinito è false. Se true, la coordinata verticale viene invertita ((u, v) -> (u, 1 - v)) durante l'importazione. Questo contribuisce alle differenze storiche tra OpenGL/Direct3D.
model.fix_infacing_normals
Attributo facoltativo, il valore predefinito è false. Se true, l'importazione tenterà di trovare e di correggere per le normali in entrata (le normalità che puntano alla superficie, anziché ' la superficie).
samplers[].params.usage_type
Definisce come il runtime interpreta i dati di immagine codificati. Usa "Color" per le texture immagine sGB. Utilizza "Data" o "Normal" per trattare i contenuti dell'immagine come se fossero in uno spazio lineare. Il valore predefinito è "Color".
samplers[].params.mag_filter

Definisce il filtro di minimizzazione utilizzato quando la mipmap campionata è più grande della dimensione dei pixel della geometria che la campiona. Il valore predefinito è "Linear". I valori possibili sono:

Valore Descrizione
"Nearest" Corrisponde a GL_NEAREST. Restituisce il valore dell'elemento di texture più vicino (a distanza di Manhattan) al centro del pixel con texture.
"Linear" Corrisponde a GL_LINEAR. Restituisce la media ponderata dei quattro elementi della texture più vicini al centro del pixel con texture. Possono includere elementi con texture del bordo, a seconda dei valori di texture wrap_s e texture wrap_t, e dell'esatta mappatura.
samplers[].params.min_filter

Definisce il filtro di minimizzazione utilizzato quando la mipmap campionata è più grande della dimensione dei pixel della geometria che la campiona. Il valore predefinito è "NearestMipmapLinear". I valori possibili sono:

Valore Descrizione
"Nearest" Corrisponde a GL_NEAREST. Restituisce il valore dell'elemento texture più vicino (a distanza di Manhattan) al centro del pixel in texture.
"Linear" Corrisponde a GL_LINEAR. Restituisce la media ponderata dei quattro elementi texture più vicini al centro del pixel a cui è applicata la texture. Possono includere elementi con texture del bordo, a seconda dei valori di texture wrap_s e texture wrap_t, e dell'esatta mappatura.
"NearestMipmapNearest" Corrisponde a GL_NEAREST_MIPMAP_NEAREST. Scegli la mappa mip che meglio corrisponde alla dimensione del pixel con texture e utilizza il criterio "Nearest" (l'elemento texture più vicino al centro del pixel) per produrre un valore di texture.
"LinearMipmapNearest" Corrisponde a GL_NEAREST_MIPMAP_LINEAR. Scegli le due mipmaps che più corrispondono alla dimensione del pixel con texture e utilizza il criterio "Nearest" (l'elemento con texture più vicino al centro del pixel) per produrre un valore di texture da ogni mimap. Il valore finale della texture è una media ponderata dei due valori.
"LinearMipmapLinear" Corrisponde a GL_LINEAR_MIPMAP_LINEAR. Scegli le due mappe che corrispondono meglio alle dimensioni del pixel con texture e utilizza il criterio "Linear" (una media ponderata dei quattro elementi texture più vicini al centro del pixel) per produrre un valore di texture da ogni mipmap. Il valore finale della texture è una media ponderata di questi due valori.
samplers[].params.wrap_s

Attributo facoltativo, il valore predefinito è "Repeat". Controlla il comportamento dell'avvolgimento orizzontale.

Valore Descrizione
"ClampToBorder" Corrisponde a GL_CLAMP_TO_BORDER.
"ClampToEdge" Corrisponde a GL_CLAMP_TO_BORDER.
"MirroredRepeat" Corrisponde a GL_MIRRORED_REPEAT.
"MirrorClampToEdge" Corrisponde a GL_MIRROR_CLAMP_TO_EDGE.
"Repeat" Corrisponde a GL_REPEAT.
samplers[].params.wrap_t

Attributo facoltativo, il valore predefinito è "Repeat". Controlla il comportamento di avvolgimento verticale.

Valore Descrizione
"ClampToBorder" Corrisponde a GL_CLAMP_TO_BORDER.
"ClampToEdge" Corrisponde a GL_CLAMP_TO_BORDER.
"MirroredRepeat" Corrisponde a GL_MIRRORED_REPEAT.
"MirrorClampToEdge" Corrisponde a GL_MIRROR_CLAMP_TO_EDGE.
"Repeat" Corrisponde a GL_REPEAT.

Parametri per i materiali predefiniti

Sceneform fornisce tre definizioni di materiale predefinite: una per le risorse OBJ, una per le risorse OBA e una per le risorse glTF.

In questa sezione vengono elencati i parametri dei materiali supportati da ogni definizione di materiale predefinita.

obj_material.sfm

Parametro Valore Descrizione
baseColor <sampler_name> Compute baseColor come valore del campione campionato per il colore interpolato.
null Compute baseColor come colore interpolato o bianco se non è presente alcun colore interpolato.
baseColorTint <vec4> Applica una tinta al valore calcolato baseColor, specificato come [r, b, g, a].
metallic <float_value> Controlla la metallicità del materiale.
Utilizza 0.0 per i materiali non metallici.
Usa 1.0 per i materiali metallici.
roughness <float_value> Controlla la rugosità del materiale.
Utilizza valori bassi per i materiali lucidi (0.0 rappresenta uno specchio perfetto).
Utilizza valori elevati per i materiali diffusi (1.0 rappresenta un materiale senza lucentezza).
opacity null Completamente opaca.
<float_value> Trasparenza attivata.
1.0 è completamente opaca.
0.0 è completamente trasparente.

fbx_material.sfm

Parametro Valore Descrizione
baseColor <vec4> Un fattore di tinta nel risultato di baseColorMap, specificato come [r, g, b, a].
baseColorMap <sampler_name> Il risultato è il valore del campione baseColorMap.
null Risolve il bianco.
normalMap <sampler_name> Interpreta il risultato del campione come uno spazio tangente normale, utilizzato nei calcoli dell'illuminazione.
null Utilizza una costante [0, 0, 1] come normale spazio tangente.
metallic <float_value> Consente di scalare metallicMap per controllare la metallità del materiale.
Utilizza 0.0 per i materiali non metallici
Utilizza 1.0 per i materiali metallici.
metallicMap <sampler_name> Utilizza il valore del canale rosso del campione come valore metallicMap.
null Utilizza una costante 1.0, di modo che venga scalata da metallic.
roughness <float_value> Consente di scalare roughnessMap per controllare la rugosità del materiale.
Utilizza un livello di rugosità basso per i materiali lucidi.
Utilizza la rugosità elevata per i materiali diffusi.
roughnessMap <sampler_name> Utilizza il valore del canale rosso del campione come valore roughnessMap.
null Utilizza una costante 1.0, di modo che venga scalata da roughness.
reflectance <float_value> Controlla la riflessione di un materiale.
Il valore predefinito di 0.5 copre quasi tutti i materiali possibili.
opacity null Nessun controllo esplicito di opacità.
Se nei dati di origine è stata specificata una mappa dell'opacità, il materiale verrà visualizzato con un'unione trasparente.

gltf_material.sfm

Parametro Valore Descrizione
baseColorFactor <vec4> Un fattore di tinta nel risultato di baseColor, specificato come [r, g, b, a].
normal <sampler_name> Interpreta il risultato del campione come uno spazio tangente normale, utilizza i calcoli della luce.
null Utilizza una costante [0, 0, 1] come normale spazio tangente.
metallicFactor <float_value> Consente di scalare metallicRoughness per controllare la metallicità del materiale.
Utilizza 0.0 per i materiali non metallici.
Usa 1.0 per i materiali metallici.
roughnessFactor <float_value> Consente di scalare metallicRoughness per controllare la rugosità del materiale.
Utilizza la rugosità bassa per i materiali lucidi.
Utilizza il livello elevato di rugosità per i materiali diffusi.
metallicRoughness <sampler_name> Utilizza il canale verde del campionatore per la rugosità (scalato da roughnessFactor).
Utilizza il canale blu del campionatore per il metallizzato (scalato da metallicFactor).
null Utilizza metallicFactor e roughnessFactor.
occlusion <sampler_name> Usa il canale rosso del campionatore per occultare l'ambiente.
null Se è presente la texture metallicRoughness, utilizza il canale rosso per occultare i rumori ambientali.
emissiveFactor <float_value> Scalabilità di emissive per controllare le emissioni del materiale.
Utilizza 0.0 per i materiali che non generano una propria luce.
emissive <sampler_name> Usa il colore del campionatore come valore emissivo.
null Nessuna emissione.
reflectance <float_value> Controlla la riflessione di un materiale.
Il valore predefinito di 0.5 copre quasi tutti i materiali possibili.


Se nei dati di origine è stato specificato un limite alfa, il materiale verrà visualizzato con l'unione mascherata. Se l'unione è stata attivata sui contenuti di origine, la trasparenza sarà attivata.

Sostituzione o aggiunta di texture

Il blocco samplers definisce le texture disponibili per i materiali. I record del campionamento provenienti dall'asset di origine dichiarano pipeline_name, identificandoli in modo univoco dal percorso dell'immagine originale nell'asset di origine. Il campo file può essere modificato per contenere un percorso di file relativo app/. Ad esempio, il codice:

  {
     file: "sampledata/models/textures/dandy_andy.png",
     name: "andy",
     pipeline_name: "andy.png",
  },

sostituisce la texture di origine, denominata andy.png negli asset di origine, con i contenuti del file ./sampledata/models/textures/dandy_andy.png.

Le texture completamente o parzialmente dichiarate nell'asset di origine non possono essere importate automaticamente nell'asset, nel qual caso possono essere aggiunte all'SFA. È possibile aggiungere texture a qualsiasi modello che ha TexCoord nell'elenco degli attributi. Invece di un pipeline_name, che si applica solo ai campionatori importati automaticamente, l'utente specifica un blocco injections.

Considera un esempio di OBA con attributi TexCoord, ma senza texture. Puoi aggiungere un file immagine alla cartella del progetto e collegarlo a un nuovo blocco di campionamento, quindi nelle iniezioni dichiara il suo utilizzo come "Normal", come nel seguente codice:

  {
     file: "sampledata/models/cragly_normal.png",
     name: "bumps",
     injections: [
       {usage: "Normal",},
     ],
  },

A questo punto, la texture è disponibile per i materiali. Per visualizzarlo, assicurati che il materiale richieda il campionatore per il relativo parametro normalMap (in caso contrario, il campionatore risulterà inutilizzato e verrà eliminato). Dato il nome bumps nel nostro blocco di anteprime, significa che il nostro blocco di materiale deve avere il seguente codice:

    {
      normalMap: 'bumps',
    },

Utilizzi disponibili per il blocco di inserimento: BaseColor, Metallic,Normal,Emissive, Roughness e Occlusion.