Düzenli öğe dosyası referansı

Sceneform Öğe Tanımı (*.sfa) dosyası, Sceneform İkili Öğesi'nin (*.sfb) kullanıcılar tarafından okunabilen bir açıklamasıdır. Dosya, kaynak öğenizdeki modelleri, malzeme tanımlarını ve dokuları işaret eder ve Sceneform'un fiziksel tabanlı malzemeleri için malzeme parametreleri sağlar.

Bu dosya, Sceneform Android Studio eklentisi tarafından ilk içe aktarma işleminde otomatik olarak oluşturulur, ancak öğelerinizin görünümünü değiştirmek için özelliklerde ince ayar yapabilirsiniz. Bu referans, öğenizin görünümünü değiştirmek için yapılandırabileceğiniz özellikleri açıklar. sfa öğesinde bulunmayan isteğe bağlı özelliklerin varsayılan değeri vardır. sfa söz dizimi, JSON uzantısı olan jsonnet şeklindedir.

Söz dizimi

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

Özellikler

materials[].parameters

Bu blokun içeriği, source özelliği tarafından belirtilen malzeme tanımına bağlıdır.

Varsayılan materyaller için (*.sfm) desteklenen parametrelerin listesine bakın:

• OBJ öğeleri: obj_material.sfm
• {8/} öğeleri: fbx_material.sfm
• glTF öğeleri: gltf_material.sfm

Özel materyaller için (*.mat) desteklenen parametrelerin listesi *.mat dosyasında belirtilir:

• Özel malzeme referansına bakın

materials[].source

Malzeme tanımı dosyasını (varsayılan malzeme tanımı (*.sfm) dosyası veya özel malzeme tanımı (*.mat)) belirtir.

model.attributes

Kaynak modelin içe aktarımı sırasında hesaplanan dışa aktarılan tepe noktaları akışını tanımlar. Olası değerler:

Değer	Açıklama
"Color"	Köşe COLOR.
"Orientation"	Köşe TANGENT.
"Position"	Köşe POSITION.
"TexCoord"	TEXCOORD0, ilk UV koordinatı.

model.file

Zorunlu özellik. Kaynak öğe dosyasının dosya sistemi yolunu içerir. Şu anda *.fbx, *.obj, *.gltf ve *.glb biçimleri desteklenir.

model.scale

İsteğe bağlı özellik, varsayılan olarak 1.0 değerine ayarlanır. Dışa aktarılan modelin ve kaynak öğe içeriğinin ölçeğini kontrol eder. 2.0 ölçeği, öğenin değerini iki katına çıkarır.

Sahne biçimi konum değerleri metre cinsinden belirtilir. Standart birimlerdeki farklılıkları barındırmak için ölçek terimi, ilk içe aktarma sırasında en büyük eksen 5 cm'den küçük ve en küçük eksen 1 m'den küçük olacak şekilde otomatik olarak hesaplanır. Bu, ilk içe aktarma deneyimi için geçerlidir; bu sınırlar uygulanmaz.

model.recenter

İsteğe bağlı özellik, varsayılan olarak false değerine ayarlanır. Dışa aktarılan geometrinin konumlandırmasını kontrol eder. Olası değerler:

Değer	Açıklama
false	Geometri, yazıldığı gibi, herhangi bir dönüşüm olmadan dışa aktarılır.
true	Geometrinin merkezi, başlangıç noktasının üzerine yerleştirilecek.
"root"	Geometri, başlangıç noktası üzerinde yatay olarak ortalanacak şekilde dışa aktarılır ve dikey olarak en düşük yönleri orijinalle aynı hizada olacak şekilde kaydırılır. Bu işlem, sabit veya uçakta konumlandırılmış dışa aktarılan bir modelin bu sabitleme noktasının üzerinde kalmasını sağlamak için kullanılabilir.
{x:float, y:float, z:float}	Geometri, kaynağın belirtilen noktaya göre yerleştirileceği şekilde dışa aktarılır. {x:0, y:0, z:0} geometrinin eksene bağlı minimum sınır kutusuna karşılık gelir. {x:1, y:1, z:1} geometrinin eksene bağlı maksimum sınırlayıcı kutusuna karşılık gelir.}

model.smoothing_angle

Derece olarak belirtilen isteğe bağlı özellik, varsayılan olarak 45 değerine sahiptir. Köşe başı normalleri olmayan kaynak öğeler (ör. obj), tepe noktası normal hesaplamasında kullanılan yüz normalleri grubunu sınırlandırmak için smoothing_angle kullanılarak oluşturulan köşe başına normal değerlere sahip olacaktır. Modelde bu açıyı aşan kenarlar 'sert' dış görünümlü, aşmayan kenarlar pürüzsüz görünür.

model.flip_texture_coordinates

İsteğe bağlı özellik, varsayılan olarak false değerine ayarlanır. Doğruysa içe aktarma sırasında dikey koordinat tersine çevrilir ((u, v) -> (u, 1 - v)). Bu, OpenGL/Direct3D arasındaki geçmiş farklılıkların korunmasına yardımcı olur.

model.fix_infacing_normals

İsteğe bağlı özellik, varsayılan olarak false değerine ayarlanır. Doğruysa, içe aktarma işlemi, normalin (yüzdeyi gösteren ' yüzeyin 'dışından düşülene göre) normali bulmaya ve düzeltmeye çalışır.

samplers[].params.usage_type

Çalışma zamanının kodlanmış görüntü verilerini nasıl yorumladığını tanımlar. SRGB resim dokuları için "Color" özelliğini kullanın. Resmin içeriğini doğrusal alandaymış gibi işlemek için "Data" veya "Normal" kullanın. Varsayılan değer "Color" değeridir.

samplers[].params.mag_filter

Örneklenmiş mipmap, geometrinin piksel piksel boyutundan daha büyük olduğunda kullanılan küçültme filtresini tanımlar. Varsayılan değer "Linear" değeridir. Olası değerler:

Değer	Açıklama
"Nearest"	Karşılık gelen GL_NEAREST. Dokulu pikselin merkezine en yakın (Manhattan mesafedeki) doku öğesinin değerini döndürür.
"Linear"	Karşılık gelen GL_LINEAR. Dokulu pikselin merkezine en yakın dört doku öğesinin ağırlıklı ortalamasını döndürür. Bunlar, wrap_s dokusuna ve wrap_t dokusuna ve tam eşlemeye bağlı olarak sınır doku öğeleri içerebilir.

samplers[].params.min_filter

Örneklenmiş mipmap, geometrinin piksel piksel boyutundan daha büyük olduğunda kullanılan küçültme filtresini tanımlar. Varsayılan değer "NearestMipmapLinear" şeklindedir. Olası değerler:

Değer	Açıklama
"Nearest"	Karşılık gelen GL_NEAREST. Doku oluşturulan pikselin merkezine en yakın (Manhattan mesafesinde) doku öğesinin değerini döndürür.
"Linear"	Karşılık gelen GL_LINEAR. Doku haline getirilen pikselin merkezine en yakın dört doku öğesinin ağırlıklı ortalamasını döndürür. Bunlar, wrap_s dokusuna ve wrap_t dokusuna bağlı olarak kenarlık doku öğelerini ve tam eşlemeyi içerebilir.
"NearestMipmapNearest"	Karşılık gelen GL_NEAREST_MIPMAP_NEAREST. Dokulu piksel boyutuyla en yakın mixmap'i seçer ve doku değeri oluşturmak için "Nearest" ölçütünü (pikselin merkezine en yakın doku öğesi) kullanır.
"LinearMipmapNearest"	Karşılık gelen GL_NEAREST_MIPMAP_LINEAR. Doku haline getirilen pikselin boyutuyla en yakın şekilde eşleşen iki mipmap'i seçer ve her bir karma eşlemeden doku değeri oluşturmak için "Nearest" ölçütünü (pikselin merkezine en yakın doku öğesi) kullanır. Son doku değeri, bu iki değerin ağırlıklı ortalamasıdır.
"LinearMipmapLinear"	Karşılık gelen GL_LINEAR_MIPMAP_LINEAR. Doku haline getirilen pikselin boyutuyla en yakın şekilde eşleşen iki mipmap'i seçer ve her bir mip haritasından bir doku değeri oluşturmak için "Linear" ölçütünü (pikselin en yakınına doğru dört doku öğesinin ağırlıklı ortalaması) kullanır. Son doku değeri, bu iki değerin ağırlıklı ortalamasıdır.

samplers[].params.wrap_s

İsteğe bağlı özellik, varsayılan olarak "Repeat" değerine ayarlanır. Yatay sarmalama davranışını kontrol eder.

Değer	Açıklama
"ClampToBorder"	Karşılık gelen GL_CLAMP_TO_BORDER.
"ClampToEdge"	Karşılık gelen GL_CLAMP_TO_BORDER.
"MirroredRepeat"	Karşılık gelen GL_MIRRORED_REPEAT.
"MirrorClampToEdge"	Karşılık gelen GL_MIRROR_CLAMP_TO_EDGE.
"Repeat"	Karşılık gelen GL_REPEAT.

samplers[].params.wrap_t

İsteğe bağlı özellik, varsayılan olarak "Repeat" değerine ayarlanır. Dikey sarmalama davranışını kontrol eder.

Değer	Açıklama
"ClampToBorder"	Karşılık gelen GL_CLAMP_TO_BORDER.
"ClampToEdge"	Karşılık gelen GL_CLAMP_TO_BORDER.
"MirroredRepeat"	Karşılık gelen GL_MIRRORED_REPEAT.
"MirrorClampToEdge"	Karşılık gelen GL_MIRROR_CLAMP_TO_EDGE.
"Repeat"	Karşılık gelen GL_REPEAT.

Varsayılan materyaller için parametreler

Sceneform üç varsayılan malzeme tanımı sağlar: OBJ öğeleri için bir tane, {8/} öğeleri için bir tane ve glTF öğeleri için bir tane.

Bu bölümde, her bir varsayılan malzeme tanımı tarafından desteklenen malzeme parametreleri listelenmektedir.

obj_material.sfm

Parametre	Değer	Açıklama
baseColor	<sampler_name>	Örnekleyiciden alınan değer, çarpım yapılan rengin çarpımıyla baseColor hesaplanır.
	null	baseColor değerini interpolasyon rengi olarak, beyaz olmayan bir renk varsa beyaz olarak hesaplayın.
baseColorTint	<vec4>	[r, b, g, a] olarak belirtilen hesaplanan baseColor değerine bir ton uygular.
metallic	<float_value>	Malzemenin metalikliğini kontrol eder. Metalik olmayan malzeme için 0.0 değerini kullanın. Metalik malzeme için 1.0 kullanın.
roughness	<float_value>	Malzemenin pürüzlüğünü kontrol eder. Parlak malzeme için düşük değerler kullanın (0.0, en iyi aynadır). Dağınık malzeme için yüksek değerler kullanın (1.0 parlak olmayan malzemedir).
opacity	null	Tamamen opak.
	<float_value>	Şeffaflık etkinleştirildi. 1.0 tamamen opak. 0.0 tamamen şeffaf.

fbx_material.sfm

Parametre	Değer	Açıklama
baseColor	<vec4>	baseColorMap sonucundaki tonlama faktörü. [r, g, b, a] olarak belirtilir.
baseColorMap	<sampler_name>	Sonuç, baseColorMap örneğinin değeridir.
	null	Beyaza döner.
normalMap	<sampler_name>	Örnek sonucu, ışıklandırma hesaplamalarında kullanılan tanjant normal alanı olarak yorumlar.
	null	Tanjant alanı normal olarak sabit bir [0, 0, 1] kullanın.
metallic	<float_value>	Materyalin metaliliğini kontrol etmek için metallicMap ölçeklenir. Metalik olmayan malzemeler için 0.0 kullanın Metalik malzeme için 1.0 kullanın.
metallicMap	<sampler_name>	Örnekleyicideki kırmızı kanal değerini metallicMap değerimiz olarak kullanın.
	null	metallic olarak ölçeklenecek sabit bir 1.0 kullanın.
roughness	<float_value>	Malzemenin pürüzlerini kontrol etmek için roughnessMap ölçekler. Parlak malzeme için düşük pürüzlülük kullanın. Difüzyonlu malzemeler için yüksek pürüzlülük kullanın.
roughnessMap	<sampler_name>	Örnekleyicideki kırmızı kanal değerini roughnessMap değerimiz olarak kullanın.
	null	roughness olarak ölçeklenecek sabit bir 1.0 kullanın.
reflectance	<float_value>	Bir malzemenin yansımasını kontrol eder. 0.5 varsayılan değeri, olası tüm malzemeleri kapsar.
opacity	null	Açık opaklık kontrolü yoktur. Kaynak verilerde opak bir harita belirtildiyse malzeme şeffaf harmanlama ile oluşturulur.

gltf_material.sfm

Parametre	Değer	Açıklama
baseColorFactor	<vec4>	[r, g, b, a] sonucu olarak belirtilen baseColor sonucuna ait bir tonlama faktörü.
normal	<sampler_name>	Örnek sonucu, aydınlatma hesaplamalarında kullanılan tanjant alanı normal olarak yorumlar.
	null	Tanjant alanı normal olarak sabit bir [0, 0, 1] kullanın.
metallicFactor	<float_value>	Materyali metal metaliliğini kontrol etmek için metallicRoughness ölçekler. Metalik olmayan malzemeler için 0.0 kullanın. Metalik malzeme için 1.0 kullanın.
roughnessFactor	<float_value>	Malzemenin pürüzlerini kontrol etmek için metallicRoughness ölçekler. Parlak malzeme için düşük pürüzlülük kullanın. Difüzyonlu malzeme için yüksek pürüzlülük kullanın.
metallicRoughness	<sampler_name>	Pürüzlülük için örnekleyicinin yeşil kanalını (roughnessFactor oranında ölçeklendirilir) kullanın. Metalik örnekleyicideki mavi kanalı kullanın (metallicFactor oranında ölçeklendirilir).
	null	metallicFactor ve roughnessFactor kullanın.
occlusion	<sampler_name>	Ortam kapama için örnekleyicideki kırmızı kanalı kullanın.
	null	metallicRoughness dokusu varsa ortam kapamayı artırmak için kırmızı kanalı kullanın.
emissiveFactor	<float_value>	Materyali, emisyonu kontrol etmek için emissive ölçeklendirir. Kendi ışığını üretmeyen malzemeler için 0.0 kullanın.
emissive	<sampler_name>	Yayıcı değerimiz olarak örnekleyicinin rengini kullanın.
	null	Emisyon yok.
reflectance	<float_value>	Bir malzemenin yansımasını kontrol eder. 0.5 örneğinin varsayılan değeri, mümkün olan tüm malzemeleri kapsar.

Kaynak verilerde alfa kesimi belirtildiyse malzeme maskeli harmanlamayla oluşturulur. Kaynak içerikte harmanlama etkinleştirilmişse şeffaflık etkinleştirilir.

Dokuları değiştirme veya ekleme

samplers bloğu, malzemeleriniz için hangi dokuların kullanılabileceğini tanımlar. Kaynak öğeden gelen örnekleyici kayıtları, pipeline_name öğesini bildirir. Bu sayede kayıtları kaynak öğedeki orijinal resim yoluna göre benzersiz şekilde tanımlarlar. file alanı, app/ göreli dosya yolu içerecek şekilde değiştirilebilir. Örneğin, kod:

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

kaynak öğelerde andy.png olarak adlandırılan kaynak dokuyu, dosyanın içeriğiyle değiştirir../sampledata/models/textures/dandy_andy.png

Kaynak öğede tamamen veya kısmen bildirilen dokular, öğeye otomatik olarak aktarılamayabilir. Bu durumda, SFA'ya eklenebilir. Özellik listesinde TexCoord bulunan tüm modellere doku eklemek mümkündür. Kullanıcı, yalnızca otomatik olarak içe aktarılan örnekleyiciler için geçerli olan pipeline_name yerine injections bloku belirtir.

Doku içermeyen, TexCoord özelliğine sahip bir GCDS örneği düşünün. Proje klasörünüze bir resim dosyası ekleyebilir ve bu dosyayı yeni bir örnek blokuna bağlayabilirsiniz. Daha sonra, enjeksiyonlarda resmin aşağıdaki kodda "Normal" olarak belirtildiği belirtilir:

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

Bu noktada doku, malzemelerinize alınabilir. Göstermek için, normalMap parametresi için örnekleyicinin kullanıldığından emin olun. Aksi takdirde, örnekleyici kullanılmamış olur ve toplanır. Örnekleyici blokumuzdaki bumps adı için bu, malzeme blokumuzun aşağıdaki koda sahip olması gerektiği anlamına gelir:

    {
      normalMap: 'bumps',
    },

Enjeksiyon blokunun kullanılabilir kullanımları BaseColor, Metallic,Normal,Emissive, Roughness ve Occlusion'dir.