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

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)，請參閱支援的參數清單：

如果是自訂資料 (*.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。