Referensi file aset Sceneform

File Sceneform Asset Definition (*.sfa) adalah deskripsi yang dapat dibaca manusia dari aset Sceneform Binary (*.sfb). File ini mengarah ke model, definisi material, dan tekstur dalam aset sumber Anda serta menyediakan parameter material untuk material berbasis fisik Sceneform.

File ini dibuat secara otomatis saat impor pertama oleh plugin Android Sceneform, tetapi Anda dapat menyesuaikan atribut untuk mengubah tampilan aset Anda. Referensi ini menjelaskan atribut yang dapat Anda konfigurasi untuk mengubah tampilan aset Anda. Atribut opsional yang tidak ada dalam sfa akan memiliki nilai defaultnya. Sintaksis sfa adalah jsonnet, ekstensi JSON.

Sintaksis

{
   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>",
      },
      …
   ]
}

Atribut

materials[].parameters

Konten blok ini bergantung pada definisi material yang ditentukan oleh atribut source.

Untuk bahan default (*.sfm), lihat daftar parameter yang didukung:

Untuk bahan khusus (*.mat), daftar parameter yang didukung ditentukan dalam file *.mat:

materials[].source
Menentukan file definisi material, file definisi material default (*.sfm) atau file definisi materi kustom (*.mat).
model.attributes

Menentukan kumpulan aliran vertex yang diekspor, yang dihitung selama impor model sumber. Nilai yang dimungkinkan adalah:

Nilai Deskripsi
"Color" vertex COLOR.
"Orientation" vertex TANGENT.
"Position" vertex POSITION.
"TexCoord" TEXCOORD0, koordinat UV pertama.
model.file
Atribut yang diperlukan, berisi jalur sistem file ke file aset sumber. Format yang saat ini didukung adalah *.fbx, *.obj, *.gltf, *.glb.
model.scale

Atribut opsional, default-nya adalah 1.0. Mengontrol skala model yang diekspor vs. konten aset sumber. Skala 2.0 akan menjadikan aset dua kali lebih besar.

Nilai posisi Sceneform ditentukan dalam meter. Untuk mengakomodasi perbedaan dalam satuan standar, istilah skala otomatis dihitung selama impor awal untuk membuat sumbu terbesar tidak lebih kecil dari 5 cm, dan sumbu terkecil tidak lebih besar dari 1 m. Hal ini demi pengalaman impor awal; batas ini tidak diterapkan.

model.recenter

Atribut opsional, default-nya adalah false. Mengontrol pemosisian geometri yang diekspor. Nilai yang dimungkinkan adalah:

Nilai Deskripsi
false Geometri akan diekspor sebagai yang ditulis, tanpa transformasi.
true Pusat geometri akan ditempatkan di titik asal.
"root" Geometri akan diekspor sehingga terpusat secara horizontal di atas asal, dan digeser secara vertikal sehingga verteks terendahnya rata dengan asal. Ini dapat digunakan untuk memastikan bahwa model yang diekspor yang diposisikan pada anchor atau bidang akan berdiri di atas titik anchor ini.
{x:float, y:float, z:float} Geometri akan diekspor sedemikian rupa sehingga asalnya ditempatkan sesuai dengan titik yang ditunjukkan.
{x:0, y:0, z:0} sesuai dengan minimum kotak pembatas geometri yang disejajarkan dengan sumbu.
{x:1, y:1, z:1} sesuai dengan ukuran maksimum kotak pembatas rata geometri.}
model.smoothing_angle
Atribut opsional yang ditentukan dalam derajat, ditetapkan secara default ke 45. Aset sumber tanpa normal per-verteks (misalnya obj) akan memiliki normal per-vertex yang dihasilkan menggunakan smoothing_angle untuk membatasi kumpulan normal wajah yang digunakan dalam komputasi vertex normal. Ujung-ujung dalam model yang melebihi sudut ini akan muncul 'keras' atau berfaset, tepi yang tidak melebihi akan muncul terhalus.
model.flip_texture_coordinates
Atribut opsional, ditetapkan secara default ke false. Jika benar, koordinat vertikal dibalik ((u, v) -> (u, 1 - v)) selama pengimporan. Hal ini membantu mengakomodasi perbedaan historis antara OpenGL/Direct3D.
model.fix_infacing_normals
Atribut opsional, ditetapkan secara default ke false. Jika benar, impor akan mencoba menemukan dan memperbaiki permukaan yang normal (normal yang mengarah 'ke' permukaan, bukan 'dari' permukaan.
samplers[].params.usage_type
Menentukan cara runtime menafsirkan data gambar yang dienkode. Gunakan "Color" untuk tekstur gambar SRGB. Gunakan "Data" atau "Normal" untuk memperlakukan konten gambar seolah-olah berada dalam ruang linear. Nilai defaultnya adalah "Color".
samplers[].params.mag_filter

Menentukan filter minifikasi yang digunakan saat mipmap dengan sampel yang lebih besar dari ukuran piksel pengambilan sampel geometri. Nilai default-nya adalah "Linear". Nilai yang dimungkinkan adalah:

Nilai Deskripsi
"Nearest" Sesuai dengan GL_NEAREST. Menampilkan nilai elemen tekstur yang paling dekat (dalam jarak Manhattan) ke bagian tengah piksel yang diberi tekstur.
"Linear" Sesuai dengan GL_LINEAR. Menampilkan rata-rata tertimbang dari empat elemen tekstur yang paling dekat dengan bagian tengah piksel yang diberi tekstur. Ini dapat mencakup elemen tekstur batas, bergantung pada nilai tekstur wrap_s dan tekstur wrap_t, serta pada pemetaan yang tepat.
samplers[].params.min_filter

Menentukan filter minifikasi yang digunakan saat mipmap dengan sampel yang lebih besar dari ukuran piksel pengambilan sampel geometri. Nilai defaultnya adalah "NearestMipmapLinear". Nilai yang dimungkinkan adalah:

Nilai Deskripsi
"Nearest" Sesuai dengan GL_NEAREST. Menampilkan nilai elemen tekstur yang terdekat (dalam jarak Manhattan) ke tengah piksel yang diberi tekstur.
"Linear" Sesuai dengan GL_LINEAR. Menampilkan rata-rata berbobot dari empat elemen tekstur yang paling dekat dengan bagian tengah piksel yang diberi tekstur. Hal ini dapat mencakup elemen tekstur batas, bergantung pada nilai tekstur wrap_s dan tekstur wrap_t, serta pada pemetaan yang tepat.
"NearestMipmapNearest" Sesuai dengan GL_NEAREST_MIPMAP_NEAREST. Memilih mipmap yang paling cocok dengan ukuran piksel yang diberi tekstur dan menggunakan kriteria "Nearest" (elemen tekstur yang paling dekat dengan bagian tengah piksel) untuk menghasilkan nilai tekstur.
"LinearMipmapNearest" Sesuai dengan GL_NEAREST_MIPMAP_LINEAR. Memilih dua mipmap yang paling cocok dengan ukuran piksel yang diberi tekstur dan menggunakan kriteria "Nearest" (elemen tekstur yang paling dekat dengan bagian tengah piksel) untuk menghasilkan nilai tekstur dari setiap mipmap. Nilai tekstur akhir adalah bobot rata-rata dari kedua nilai tersebut.
"LinearMipmapLinear" Sesuai dengan GL_LINEAR_MIPMAP_LINEAR. Memilih dua mipmap yang paling cocok dengan ukuran piksel yang diberi tekstur dan menggunakan kriteria "Linear" (rata-rata tertimbang dari empat elemen tekstur yang terdekat dengan pusat piksel) untuk menghasilkan nilai tekstur dari setiap mipmap. Nilai tekstur akhir adalah rata-rata tertimbang dari kedua nilai tersebut.
samplers[].params.wrap_s

Atribut opsional, default-nya adalah "Repeat". Mengontrol perilaku penggabungan horizontal.

Nilai Deskripsi
"ClampToBorder" Sesuai dengan GL_CLAMP_TO_BORDER.
"ClampToEdge" Sesuai dengan GL_CLAMP_TO_BORDER.
"MirroredRepeat" Sesuai dengan GL_MIRRORED_REPEAT.
"MirrorClampToEdge" Sesuai dengan GL_MIRROR_CLAMP_TO_EDGE.
"Repeat" Sesuai dengan GL_REPEAT.
samplers[].params.wrap_t

Atribut opsional, default-nya adalah "Repeat". Mengontrol perilaku penggabungan vertikal.

Nilai Deskripsi
"ClampToBorder" Sesuai dengan GL_CLAMP_TO_BORDER.
"ClampToEdge" Sesuai dengan GL_CLAMP_TO_BORDER.
"MirroredRepeat" Sesuai dengan GL_MIRRORED_REPEAT.
"MirrorClampToEdge" Sesuai dengan GL_MIRROR_CLAMP_TO_EDGE.
"Repeat" Sesuai dengan GL_REPEAT.

Parameter untuk materi default

Sceneform menyediakan tiga definisi material default: satu untuk aset OBJ, satu untuk aset FBX, dan satu lagi untuk aset glTF.

Bagian ini mencantumkan parameter material yang didukung oleh setiap definisi material default.

obj_material.sfm

Parameter Nilai Deskripsi
baseColor <sampler_name> Hitung baseColor sebagai nilai dari sampel yang dikalikan warna yang diinterpolasi.
null Hitung baseColor sebagai warna interpolasi, atau putih jika tidak ada warna yang diinterpolasi.
baseColorTint <vec4> Menerapkan tint ke nilai baseColor yang dikomputasi, yang ditentukan sebagai [r, b, g, a].
metallic <float_value> Mengontrol metalikitas bahan.
Gunakan 0.0 untuk bahan non-logam.
Gunakan 1.0 untuk bahan logam.
roughness <float_value> Mengontrol kekasaran bahan.
Menggunakan nilai rendah untuk bahan mengkilap (0.0 mewakili cermin yang sempurna).
Gunakan nilai tinggi untuk bahan difusi (1.0 merepresentasikan bahan tanpa kilau).
opacity null Sepenuhnya tidak buram.
<float_value> Transparansi diaktifkan.
1.0 sepenuhnya buram.
0.0 sepenuhnya transparan.

fbx_material.sfm

Parameter Nilai Deskripsi
baseColor <vec4> Faktor tint pada hasil baseColorMap, ditetapkan sebagai [r, g, b, a].
baseColorMap <sampler_name> Hasilnya adalah nilai sampel baseColorMap.
null Pilihan akan berubah menjadi putih.
normalMap <sampler_name> Menafsirkan hasil sampel sebagai ruang tangen normal, yang digunakan dalam komputasi penerangan.
null Gunakan konstanta [0, 0, 1] sebagai ruang tangen normal.
metallic <float_value> Menskalakan metallicMap untuk mengontrol metabolisme bahan.
Gunakan 0.0 untuk bahan non-logam
Gunakan 1.0 untuk bahan metalik.
metallicMap <sampler_name> Gunakan nilai saluran merah dari sampel sebagai nilai metallicMap kita.
null Gunakan 1.0 yang konstan, agar diskalakan oleh metallic.
roughness <float_value> Menskalakan roughnessMap untuk mengontrol kekasaran material.
Gunakan kekasaran rendah untuk material mengkilap.
Gunakan kekasaran tinggi untuk bahan difusi.
roughnessMap <sampler_name> Gunakan nilai saluran merah dari sampel sebagai nilai roughnessMap kita.
null Gunakan 1.0 yang konstan, agar diskalakan oleh roughness.
reflectance <float_value> Mengontrol pantulan bahan.
Default 0.5 mencakup hampir semua kemungkinan bahan.
opacity null Tidak ada kontrol opasitas eksplisit.
Jika peta opasitas ditentukan dalam data sumber, material akan dirender dengan pencampuran transparan.

gltf_material.sfm

Parameter Nilai Deskripsi
baseColorFactor <vec4> Faktor tint pada hasil baseColor, ditetapkan sebagai [r, g, b, a].
normal <sampler_name> Menafsirkan hasil sampel sebagai ruang tangen normal, digunakan dalam komputasi penerangan.
null Gunakan konstanta [0, 0, 1] sebagai ruang tangen yang normal.
metallicFactor <float_value> Skala metallicRoughness untuk mengontrol logam bahan.
Gunakan 0.0 untuk bahan non-logam.
Gunakan 1.0 untuk bahan logam.
roughnessFactor <float_value> Skala metallicRoughness untuk mengontrol kekasaran bahan.
Gunakan kekasaran rendah untuk bahan mengkilap.
Gunakan kekasaran tinggi untuk bahan difusi.
metallicRoughness <sampler_name> Gunakan saluran hijau dari sampel untuk kekasaran (diskalakan oleh roughnessFactor).
Gunakan saluran biru dari sampel untuk metalik (diskalakan dengan metallicFactor).
null Gunakan metallicFactor dan roughnessFactor.
occlusion <sampler_name> Gunakan saluran merah dari sampel untuk oklusi ambien.
null Jika terdapat tekstur metallicRoughness, gunakan saluran merah untuk mendorong oklusi ambien.
emissiveFactor <float_value> Menskalakan emissive untuk mengontrol emisi bahan.
Gunakan 0.0 untuk bahan yang tidak menghasilkan cahayanya sendiri.
emissive <sampler_name> Gunakan warna dari sampel sebagai nilai emisi.
null Tidak ada emisi.
reflectance <float_value> Mengontrol pantulan bahan.
Default 0.5 mencakup hampir semua kemungkinan bahan.


Jika batas alfa ditentukan dalam data sumber, materi akan dirender dengan penggabungan mask. Jika penggabungan diaktifkan pada konten sumber, transparansi akan diaktifkan.

Mengganti atau menambahkan tekstur

Blok samplers menentukan tekstur yang tersedia untuk material Anda. Data sampel yang berasal dari aset sumber mendeklarasikan pipeline_name, sehingga secara unik mengidentifikasinya berdasarkan jalur gambar asli dalam aset sumber. Kolom file dapat diubah agar berisi jalur file relatif app/. Misalnya, kodenya:

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

menggantikan tekstur sumber, yang disebut andy.png dalam aset sumber, dengan isi file ./sampledata/models/textures/dandy_andy.png.

Tekstur yang dideklarasikan sepenuhnya atau sebagian dalam aset sumber tidak akan diimpor secara otomatis ke dalam aset, sehingga dapat ditambahkan ke SFA. Anda dapat menambahkan tekstur ke model apa pun yang memiliki TexCoord dalam daftar atribut. Sebagai ganti pipeline_name, yang hanya berlaku untuk sampler yang diimpor secara otomatis, pengguna menentukan blok injections.

Pertimbangkan contoh FBX yang memiliki atribut TexCoord tetapi tidak memiliki tekstur. Anda dapat menambahkan file gambar dalam folder project dan menautkannya dalam blok sampler baru, lalu di dalam injeksi, mendeklarasikan penggunaannya sebagai "Normal" seperti dalam kode berikut:

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

Pada tahap ini, tekstur tersedia untuk material Anda. Untuk menampilkannya, pastikan permintaan material bahwa sampel untuk parameter normalMap nya (jika tidak, sampel akan tampak tidak digunakan dan akan dihapus). Dengan mempertimbangkan nama bumps dalam blok sampler, itu berarti blok material kita harus memiliki kode berikut:

    {
      normalMap: 'bumps',
    },

Penggunaan yang tersedia untuk blok injeksi adalah BaseColor, Metallic,Normal,Emissive, Roughness, dan Occlusion.