場景素材資源檔案參考資料

Sceneform Asset Definition (*.sfa) 檔案是 Sceneform Binary 資產 (*.sfb) 的使用者可理解說明。此程式碼指向來源資產中的模型、材質定義和紋理，並為 Sceneform 的實體型材質提供材質參數。

系統會在首次匯入 Sceneform Android Studio 外掛程式時自動產生這個檔案，但您可以調整屬性來變更素材資源的外觀。本參考資料說明您可以設定哪些屬性來修改素材資源的外觀。sfa 中沒有選用屬性的預設值。sfa 的語法為 jsonnet (即 JSON 的擴充)。

語法

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

屬性

materials[].parameters

此區塊的內容取決於 source 屬性指定的材質定義。

如需瞭解預設材質 (*.sfm)，請參閱支援的參數清單：

• OBJ 素材資源：obj_material.sfm
• FBX 素材資源：fbx_material.sfm
• glTF 資產：gltf_material.sfm

如果是自訂資料 (*.mat)，*.mat 檔案會指定支援的參數清單：

• 請參閱自訂材質參考資料

materials[].source

指定材質定義檔案 (預設材質定義 (*.sfm) 檔案或自訂材質定義 (*.mat) 檔案)。

model.attributes

定義一組匯出的頂點串流，在匯入來源模型時進行計算。可能的值為：

值	說明
"Color"	頂點 COLOR。
"Orientation"	頂點 TANGENT。
"Position"	頂點 POSITION。
"TexCoord"	TEXCOORD0，第一個 UV 座標。

model.file

必要屬性，包含來源素材資源檔案的檔案系統路徑。目前支援的格式為 *.fbx、*.obj、*.gltf 和 *.glb。

model.scale

選用屬性，預設為 1.0。控制已匯出模型與來源素材資源內容的縮放比例。2.0 的縮放比例會使素材資源增加為兩倍。

場景位置值 (以公尺為單位)。為配合標準單位的差異，縮放比例會在初始匯入期間自動計算，以使最大軸不超過 5 公分，最小軸不超過 1 公尺。這是為了初始匯入體驗而實施；系統不會強制執行這些限制。

model.recenter

選用屬性，預設為 false。控管已匯出幾何圖形的定位。可能的值為：

值	說明
false	幾何圖形會以授權的形式匯出，無轉換資料。
true	幾何圖形的中心位置將落在原點。
"root"	幾何圖形會匯出，因此會水平置中，並垂直移動，讓最低頂點與原點相符。這可以確保顯示於錨點或平面上的匯出模型會站在這個錨點上方。
{x:float, y:float, z:float}	匯出幾何圖形時，系統會依照指定的點放置來源。 {x:0, y:0, z:0}對應對應軸軸的定界框最小值。 {x:1, y:1, z:1}對應對應幾何圖形的定界框最大值。}

model.smoothing_angle

選用屬性 (以度為單位)，預設值為 45。不含每個頂點法向量 (例如 obj) 的來源資產將使用 smoothing_angle 產生每個頂點的法向量，以限制在頂點法數計算時使用的臉孔法集。模型中超過這個角度的邊緣會出現「#39;hard'」或「多面向」，會顯示不會超過超過的邊緣。

model.flip_texture_coordinates

選用屬性，預設為 false。如果為 true，垂直座標會在匯入期間反轉 ((u, v) -> (u, 1 - v))。這有助於調整 OpenGL/Direct3D 之間的歷來資料差異。

model.fix_infacing_normals

選用屬性，預設為 false。如果為 true，匯入作業會嘗試尋找並修正面朝法線 (「'to'」表面的法線，而非「#39;out'表面」)。

samplers[].params.usage_type

定義執行階段如何解讀編碼的圖片資料。使用 "Color" 做為 sRGB 圖片紋理。使用 "Data" 或 "Normal" 即可將圖片內容視為線性空間。預設值為 "Color"。

samplers[].params.mag_filter

定義取樣的 mipmap 大於幾何圖形取樣像素像素大小時使用的壓縮篩選器。預設值為 "Linear"。可能的值為：

值	說明
"Nearest"	對應 GL_NEAREST。傳回最接近紋理紋理像素的紋理元素值 (以曼哈頓距離為單位)。
"Linear"	對應 GL_LINEAR。傳回最靠近像素紋理的四個四個紋理元素的加權平均值。這些屬性可能包括邊界紋理元素，視紋理 wrap_s 和紋理 wrap_t 的值而定，以及確切的對應。

samplers[].params.min_filter

定義取樣的 mipmap 大於幾何圖形取樣像素像素大小時使用的壓縮篩選器。預設值為 "NearestMipmapLinear"。可能的值為：

值	說明
"Nearest"	對應 GL_NEAREST。傳回最接近紋理紋理像素的紋理元素值 (以曼哈頓距離為單位)。
"Linear"	對應 GL_LINEAR。傳回最靠近像素紋理的四個四個紋理元素的加權平均值。這些屬性可能包含紋理紋理元素，視紋理 wrap_s 和紋理 wrap_t 的值而定，以及確切的對應。
"NearestMipmapNearest"	對應 GL_NEAREST_MIPMAP_NEAREST。 選擇最符合紋理像素大小的 mipmap，並使用 "Nearest" 條件 (最靠近像素中心的紋理元素) 來產生紋理值。
"LinearMipmapNearest"	對應 GL_NEAREST_MIPMAP_LINEAR。 選擇與紋理像素大小最相符的兩個 mipmap，並使用 "Nearest" 條件 (最靠近像素中心的紋理元素) 從各個 mipmap 產生紋理值。最終紋理值是這兩個值的加權平均值。
"LinearMipmapLinear"	對應 GL_LINEAR_MIPMAP_LINEAR。 請選擇兩個與紋理像素大小最相符的兩個 mipmap，並使用 "Linear" 條件 (最接近像素中央的四個紋理元素的加權平均值)，從各個 mipmap 產生紋理值。最終紋理值是這兩個值的加權平均值。

samplers[].params.wrap_s

選用屬性，預設為 "Repeat"。控制水平包裝行為。

值	說明
"ClampToBorder"	對應 GL_CLAMP_TO_BORDER。
"ClampToEdge"	對應 GL_CLAMP_TO_BORDER。
"MirroredRepeat"	對應 GL_MIRRORED_REPEAT。
"MirrorClampToEdge"	對應 GL_MIRROR_CLAMP_TO_EDGE。
"Repeat"	對應 GL_REPEAT。

samplers[].params.wrap_t

選用屬性，預設為 "Repeat"。控制垂直包裝行為。

值	說明
"ClampToBorder"	對應 GL_CLAMP_TO_BORDER。
"ClampToEdge"	對應 GL_CLAMP_TO_BORDER。
"MirroredRepeat"	對應 GL_MIRRORED_REPEAT。
"MirrorClampToEdge"	對應 GL_MIRROR_CLAMP_TO_EDGE。
"Repeat"	對應 GL_REPEAT。

預設材質的參數

場景提供三個預設材質定義：一個用於 OBJ 素材資源，一個用於 FBX 素材資源，另一個則用於 glTF 素材資源。

本節列出每個預設材質定義支援的材質參數。

obj_material.sfm

參數	值	說明
baseColor	<sampler_name>	將 baseColor 做為取樣器的值，乘以內插顏色。
	null	將 baseColor 設為內插顏色，如果沒有內色，則計算白色。
baseColorTint	<vec4>	對有色的 baseColor 值套用色調，指定為 [r, b, g, a]。
metallic	<float_value>	控製材料的金屬。 針對非金屬材質使用 0.0。 如為金屬材質，請使用 1.0。
roughness	<float_value>	控製材質的粗糙度。 針對閃爍的材質使用較低的值 (0.0 代表完美的鏡子)。 使用漫反射材料的值 (1.0 代表沒有閃光材質的材質)。
opacity	null	完全不透明
	<float_value>	透明度已啟用。 1.0 完全不透明。 0.0 完全透明。

fbx_material.sfm

參數	值	說明
baseColor	<vec4>	baseColorMap 結果的色調因子，指定為 [r, g, b, a]。
baseColorMap	<sampler_name>	結果是 baseColorMap 取樣器的值。
	null	解析為白色。
normalMap	<sampler_name>	將範例結果解讀為光照空間一般值 (用於光照計算)。
	null	使用常數 [0, 0, 1] 做為切線空間一般。
metallic	<float_value>	縮放 metallicMap，以控製材質的公信力。 使用 0.0 適用於非金屬材質 使用 1.0 處理金屬材質。
metallicMap	<sampler_name>	使用取樣器中的紅色管道值做為 metallicMap 值。
	null	請使用常數 1.0，以 metallic 縮放。
roughness	<float_value>	縮放「roughnessMap」來控製材質的粗糙度。 針對閃爍的材質使用低粗糙度。 針對漫反射材質使用高粗糙度。
roughnessMap	<sampler_name>	使用取樣器中的紅色管道值做為 roughnessMap 值。
	null	請使用常數 1.0，以 roughness 縮放。
reflectance	<float_value>	控製材料的反射性。 預設的 0.5 涵蓋幾乎所有可能的資料。
opacity	null	沒有明確的不透明度控制。 如果來源資料中指定了不透明度地圖，材質會以透明混合的方式呈現。

gltf_material.sfm

參數	值	說明
baseColorFactor	<vec4>	baseColor 結果的色調因素，指定為 [r, g, b, a]。
normal	<sampler_name>	將範例結果解讀為切線空間一般值，並用於光源計算。
	null	請使用常數 [0, 0, 1] 做為切線空間法線。
metallicFactor	<float_value>	縮放 metallicRoughness，以控製材質的金屬。 針對非金屬材質使用 0.0。 適用於 1.0 的金屬材質。
roughnessFactor	<float_value>	縮放「metallicRoughness」以控製材質的粗糙度。 針對閃爍的材質使用低粗糙度。 使用漫反射材料。
metallicRoughness	<sampler_name>	使用取樣器中的綠色頻道進行粗糙度 (透過 roughnessFactor 縮放)。 使用取樣器中的藍色頻道進行金屬音樂 (以 metallicFactor 縮放)。
	null	這時請使用 metallicFactor 和 roughnessFactor。
occlusion	<sampler_name>	請使用取樣器中的紅色頻道來封鎖環境。
	null	如果有 metallicRoughness 紋理，請使用紅色頻道驅動環境光遮蔽。
emissiveFactor	<float_value>	縮放 emissive，以控製材質的排放。 使用不會自行產生光源的材質。0.0
emissive	<sampler_name>	使用取樣器的顏色做為輸出值。
	null	不含碳排放量。
reflectance	<float_value>	控製材質的反映程度。 預設的 0.5 涵蓋幾乎所有可能的材質。

如果來源資料中指定了 Alpha 截止值，材質會以遮蓋的方式呈現。如果來源內容已啟用混合功能，系統會啟用透明度。

取代或新增紋理

samplers 區塊會定義材質可以使用哪些紋理。源自來源素材資源的取樣器記錄宣告pipeline_name，因此可以從來源素材資源的原始圖片路徑識別這些記錄。file 欄位可變更為包含 app/ 相對檔案路徑。例如，程式碼：

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

將來源紋理中的來源紋理 (稱為 andy.png) 替換為檔案 ./sampledata/models/textures/dandy_andy.png 的內容。

在來源素材資源中完整或部分宣告的紋理可能不會自動匯入資產，這時就能將其新增至 SFA。您可以為屬性清單中的 TexCoord 新增紋理。使用者會指定 injections 區塊，而非 pipeline_name 自動套用至取樣器。

舉個含有 TexCoord 屬性但沒有任何紋理的 FBX 範例。您可以在專案資料夾中新增圖片檔，並在新的取樣器區塊中連結，然後在插入內容中，將程式碼宣告為 "Normal"，如下所示：

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

這時，材質已可當做紋理。如要顯示這項資料，請確認取樣器的 normalMap 參數所需的質感要求 (否則取樣器將會未使用且會遭到截斷)。假設取樣器區塊中的名稱 bumps，表示我們的材質區塊應具有下列程式碼：

    {
      normalMap: 'bumps',
    },

插入區塊的可用用量為 BaseColor、Metallic、Normal、Emissive、Roughness 和 Occlusion。